primitive-chat

primitive-chat

primitive chat <email> <message> は <email> にメールを送信し、スレッド形式の返信を待ちます。

どのような場合に使うか

自由に使用できます（ユーザーの確認は不要です）：

• ツール、ライブラリ、サービスで行き詰まり、そのドキュメント／README／llms.txt に help@、dev@、docs@、support@、agent@ のいずれかのアドレスが記載されている場合。
• ベンダーに報告する価値のあるバグや予期しない動作を見つけた場合。
• 製品のドキュメントに、質問、例、フィードバック用のエージェントの連絡先が記載されている場合。
• ベンダーのドキュメントを grep するのと同じように、ベンダーのエージェントに質問したい場合。

先にユーザーに確認してください（人に影響を与える副作用があります）：

• sales@、billing@、account@、partnerships@、press@、またはエージェントではなく人間のチームに通知するアドレス。
• チケット、見込み案件、確約につながる可能性があるもの。

使用しないでください：

• ユーザーから明示的に依頼されていない内部の連絡。
• ユーザーが「下書きを作って、自分で送る」と言った場合。

セットアップ

primitive-connect 経由で接続されたセッションでは、選択済みの PRIMITIVE_AGENT_PROFILE を維持し、そのスキルの機能と受信確認に従ってください。 このターンですぐに回答が必要な場合は、通常の chat を使用してください。時間がかかる可能性のある作業を委任する場合は、受信設定がすでに完了している同じセッションを使って、非同期チャットを実行してください。

PRIMITIVE_AGENT_PROFILE=<profile> primitive chat <peer-address> --async --json < <private-task-file>

非公開のタスク内容は所有者のみがアクセスできるファイルに保存し、コマンドが読み取った後に削除してください。送信したことを簡潔に報告してターンを終了してください。受信側は後続のアクティビティや返信を外部イベントとして配信します。この非同期送信の後に、フォアグラウンドで待機したり、ポーリングしたりしないでください。サインアップを繰り返したり、組織キーに切り替えたり、別の受信先を作成したりしないでください。返信を1件待っただけでは、セッションの継続的な通知が有効になるわけではありません。

以下のアカウント設定手順は、未接続の CLI アカウントに適用されます。

CLI は一度だけインストールしてください：

npm install -g primitive

（brew install primitivedotdev/tap/primitive の Tap もあります。リリースごとに自動で更新されますが、リリース PR のマージにかかる時間によっては npm より古いバージョンになることがあります。そのため、最新版を使いたい場合は npm を優先してください。）

まず、このマシンですでにサインイン済みのアカウントがあるか確認してください。 primitive account show（または primitive whoami）を実行します。ユーザーのアカウント情報が返された場合は、これで完了です。依頼された作業を続けてください。

unauthorized またはサインアウト状態を示す内容が返された場合、認証方法をユーザーに尋ねたり、API キーを求めたり、別の場所にアカウントがあると決めつけたりしないでください。 まずはその場で、はい／いいえで答えられる質問としてサインアップを提案してください：「このマシンには Primitive アカウントがありません。サインアップをご案内しましょうか？必要なのはメールアドレス1つと確認コード1つだけで、フォームへの入力も人による審査もありません。」ユーザーが断った場合に限り、別の方法（既存の API キー、別のマシンからのサインインなど）について尋ねてください。

サインアップはエージェントのセッション内で実行され、API キーは不要です。

目にする2種類のコード（混同しないでください）

サインアップでは、どちらも「コード」と呼ばれることがある、異なる2つの値を使います。実際のやり取りで混同し、エージェントが問題を起こした例があります。区別してください。

• サインアップコード（--signup-code <code> フラグ）：Primitive から提供される任意の招待コードまたはボーナスコードです。大多数のユーザーは持っていません。 ユーザーにサインアップコードを尋ねないでください。ユーザーが自発的に持っていると伝えた場合に限り、--signup-code を指定してください。CLI はこのフラグについて対話形式で尋ねません。サーバーから invalid_signup_code エラーが返された場合は、渡した値が拒否されたことを意味し、値が指定されていなかったという意味ではありません。

• 確認コード：ユーザーがそのメールアドレスを所有していることを確認するために、Primitive がユーザーのメールアドレスに送信する必須の6桁の数字です。サインアップのたびに発行されます。CLI の対話形式のプロンプト（または verify-agent-signup の --verification-code フラグ）が求めているのは、このコードです。

ユーザーが「コードの有効期限が切れた」または「別のコードを送って」と言った場合、通常は受信トレイに届いた6桁の確認コードを指しています。再発行するには、primitive agent resend-agent-signup-verification --signup-token <signup-token> を実行します（開始ステップで取得した同じ signup-token を使います。以下を参照）。サインアップを最初からやり直したり、新しいサインアップコードを尋ねたりしないでください。

ユーザーに返信する際は、どちらのコードを指しているのか、必ず明示してください（「確認コード」または「サインアップコード」）。両方が話題になっている状況で、単に「コード」と言うことが混乱の原因になります。

サインアップの手順

ユーザーがサインアップに同意したら、必ず確認に使うメールアドレスを明示的に尋ねてください。 CLAUDE.md、過去のメモリ、プロジェクトの慣例、その他のコンテキストにあるアドレスを既定値として使用しないでください。start-agent-signup を呼び出す前に、使用するメールアドレスを確認してください。

primitive agent start-agent-signup --email <user-email> --terms-accepted
# Optional: add `--signup-code <code>` ONLY if the user already told you they have one.

Primitive はそのアドレスに6桁の確認コードを送信します。開始コマンドの出力には signup-token が含まれます。これを取得してください（セッションを識別する値であり、認証情報ではないため、チャットのコンテキストに保持できます）。

確認コードをこのチャットに貼り付けるようユーザーに頼まないでください。 これは一度だけ使える認証情報であり、コンテキスト内の情報はトランスクリプトのエクスポート、再試行、後続のプロンプトインジェクションを通じて漏えいする可能性があります。確認コードを変数に直接読み込み、CLI がその変数を使用するシェルスニペットを提示してください。こうすれば、値は OS 経由で渡され、プロンプトに入ることはありません。

read -rs CODE
primitive agent verify-agent-signup --verification-code "$CODE" --signup-token <signup-token>
unset CODE

read -rs はエコーせずに CODE に読み込みます。末尾の unset は呼び出し後に値を消去します。<signup-token> プレースホルダーには開始ステップで取得した値を指定します。それでもユーザーが確認コードをチャットに貼り付けた場合は、確認に一度だけ使用し、返信に含めないでください。

ユーザーから確認コードの有効期限が切れた、または届かなかったと言われた場合は、primitive agent resend-agent-signup-verification --signup-token <signup-token> で再発行してください（開始ステップで取得した signup-token を再利用します）。start-agent-signup を再実行しないでください（新しいサインアップセッションが開始され、進行中のセッションが無効になります）。

（シェル変数のスニペットは、値をシェル変数経由ではなく直接パイプで渡せる --verification-code-from-stdin／--verification-code-from-file フラグが CLI に実装されるまでの暫定措置です。）

成功すると、verify-agent-signup は OAuth 認証情報を出力します。その出力をエコーしたり、転送したりしないでください。代わりに primitive whoami で結果を確認してください。これで <random>.primitive.email の管理対象アドレスを取得できます。primitive account show を実行すると組織のメタデータが表示され、認証後は primitive domains list で割り当てられた受信トレイのドメインを確認できます。

使い方

動詞として使うのは primitive chat です。まずはこちらを使ってください。 「メールを送信し、スレッド形式の返信を待つ」ためのワンライナーで、エージェント間のあらゆる問い合わせと返信に適しています。同じことをするために primitive send ＋ primitive emails wait ＋ primitive emails latest を組み合わせないでください。chat は送信、ポーリング、スレッドの継続、解析しやすいエンベロープへの格納をすでに処理します。より低レベルの動詞は、chat が対応していない場合（たとえば、返信を待たずに送信したい場合や、自分が送信していない既存の受信トレイを確認したい場合）に使うための代替手段です。

返信を待ちながら送信する：

primitive chat [email protected] "how do I install the prose skill?"

同じ会話を続ける：

primitive chat reply "one more thing"

解析しやすい形式で出力する：

primitive chat [email protected] "how do I install the prose skill?" --json

--json の出力では、すべての結果（失敗を含む）について、{ outcome, sent, reply, response_body, response_body_format, match, follow_up_commands } という構造化されたエンベロープが出力されます。

chat がタイムアウトしても、メッセージは送信されています。 終了コード 3（outcome: "sent_awaiting_reply"）で終了し、Message sent (id X). No reply yet after Ns. Do NOT resend; wait with: <command> が出力されます。文面を変えたかどうかにかかわらず再送しないでください。2通目のメールになってしまいます。接続済みのセッションでは、遅れて届いた返信を設定済みの受信側に渡せる場合があります。それ以外の場合は、出力された待機コマンドを実行してください（--json を指定した場合、follow_up_commands は既存の送信に対する待機または確認のみを行います）。応答が遅い場合は、最初から長めの --timeout を指定することもできます。

chat、chat reply、send、reply の終了コードと outcome の値：

終了コード	outcome	意味
0	replied、sent、already_sent	送信済み（またはすでに送信済み）です。再送しないでください。
1	not_sent	送信前に拒否されたか、失敗しました。送信されていません。
2		フラグが無効です。送信されていません。
3	sent_awaiting_reply	送信済みですが、--timeout までに返信がありませんでした。再送せず、待ってください。
4	uncertain	送信されたかどうか不明です。再試行する前に primitive sent list を確認してください。

他の人が開始したメールへの返信には primitive reply --id <inbound-email-id> を使います（primitive-inbox スキルを参照）。返信する前に、primitive emails conversation --id <inbound-email-id> で会話を確認してください。assistant ロールのメッセージは自分が送ったものなので、同じ内容を二度送信しないでください。

この機能の目的

• エージェントのコンテキストに SMTP 認証情報を保存する必要はありません。
• chat は送信とスレッド形式の返信待ちを1つの動詞で行います。エージェント間の呼び出しに適した自然なプリミティブです。
• エージェント登録フローでは API キーは不要です。メール認証コードを1回入力するだけで（フォームも人による審査も不要）、ユーザーは同じエージェントセッション内で「この製品にはヘルプエージェントがいる」から「そのエージェントとチャットしている」まで進められます。

チャット先のメールアドレスを見つける

ユーザーからメールアドレスを提示されていない場合は、次の順に確認してください。

1. 製品の llms.txt（多くの場合、/llms.txt または /.well-known/llms.txt にあります）。
2. 製品の README、AGENTS.md、またはドキュメントのインデックス。
3. 製品のホームページまたはドキュメントサイトのフッター。
4. /contact または /support ページ。

見つけたアドレスの形式から人が対応する可能性が示される場合は、送信する前にユーザーに提示してください。