@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/dispatch.md

@@ -0,0 +1,146 @@
+---
+title: "派遣"
+description: "ワークスペース コントロール プレーン: シークレット ボールト、統合ハブ、クロスアプリ デリゲート、Slack、電子メール、テレグラム、WhatsApp の中央受信トレイ。"
+---
+
+# 派遣
+
+Dispatch は、ワークスペース内の他のすべてのアプリの前に位置し、シークレット、統合、メッセージング、およびアプリ間の委任を処理する中心的なアプリです。これは **ワークスペース コントロール プレーン** です。チームが通信する単一のエージェント、認証情報が存在する単一の場所、および特定のリクエストをどの専門アプリが処理するかを決定する単一のルーターです。
+
+> **テンプレートのディスパッチとパッケージの `@agent-native/dispatch` の比較。** このページでは、ディスパッチ アプリ/テンプレートの概念、その機能とそれが必要な理由について説明します。 `@agent-native/dispatch` npm パッケージは、Dispatch テンプレートのサーバー ロジック (コンテナー、統合、宛先、スケジュールされたジョブ、アプリ間の委任) を、それを拡張するワークスペースのドロップイン パッケージとしてバンドルする、個別に公開されたランタイムです。スキャフォールドされたアプリ自体 (ルート、画面、エージェント ガイド) については、[Dispatch template](/docs/template-dispatch) を参照してください。
+
+Dispatch を使用しない場合、マルチアプリ ワークスペース内のすべてのアプリは、同じ配管、つまり独自の Slack ボット、独自のシークレット ストア、独自のスケジュールされたジョブ、独自のワークスペースの命令のコピーを再実装することになります。 1 つの API キーを回転すると、10 回の再展開になります。新しいポリシーを追加するには、10 回のコピー＆ペーストが必要になります。 Dispatch はそのすべてを 1 つのアプリに一元化するため、他のアプリは自分のドメインに集中し続けることができます。
+
+```an-diagram title="Dispatch as the workspace control plane" summary="One inbox, one vault, one MCP gateway, and shared resources sit in front of the domain apps, which Dispatch reaches as A2A peers."
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · email · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">Central inbox</span><span class=\"diagram-pill\">Secret vault</span><span class=\"diagram-pill\">Cross-app delegation</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">Workspace resources</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## 発送をご希望の場合 {#when}
+
+次のいずれかに該当する場合、派遣に連絡します:
+
+- メール、カレンダー、分析、コンテンツなどの [multi-app workspace](/docs/multi-app-workspace) を実行していますが、アプリごとに 1 つの Slack ボットは必要ありません。
+- ユーザーが 1 つのボットに DM を送信し、適切な専門アプリが舞台裏で作業を引き受けられるように、**「エージェント」用に 1 つの受信箱** が必要です。
+- 複数のアプリに必要な **ワークスペース全体のシークレット** (ストライプ キー、OpenAI キー、サードパーティ API トークン) があり、すべての `.env` に値をコピーするのではなく、1 つのボールトが必要です。
+- 機密変更 (宛先の保存、ポリシーの編集) の前に **実行時承認フロー** を設けて、管理者以外のユーザーがリクエストでき、管理者がコードをデプロイせずにサインオフできるようにする必要があります。
+- ワークスペース内のアプリが継承する **共有 skills、手順、エージェント プロファイル、および MCP サーバー**が必要です。これは、一度変更すればすべてに適用されます。
+
+単一のテンプレートをスタンドアロンで実行している場合、Dispatch は必要ありません。各テンプレートは独自のメッセージング統合を直接接続できます。スタンドアロン セットアップについては、[Messaging](/docs/messaging) を参照してください。
+
+## Dispatch の機能 {#what-it-does}
+
+7 つの機能はすべて、他のアプリが使用する同じワークスペース データベース上にあります。
+
+| 能力                        | それがあなたにもたらすもの                                                                            | セットアップしてください                                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| **中央受信箱**              | Slack、電子メール、電報、WhatsApp はすべて、共有メモリとツールを備えた 1 つのエージェントに到達します | **設定 → メッセージング** ([Messaging](/docs/messaging))     |
+| **秘密の保管庫**            | 各認証情報を 1 回保存します。すべてのアプリにわたって 1 か所でローテーション                          | **Vault** + アクセス モード (すべてのアプリまたは手動)       |
+| **アプリ間の委任**          | リクエストを A2A 経由で適切な専門アプリにルーティングし、スレッド内で応答します                       | 自動 ([A2A](/docs/a2a-protocol))                             |
+| **統合 MCP ゲートウェイ**   | 外部エージェント用の 1 つの MCP コネクタが、付与されたすべてのワークスペース アプリに接続します       | [External Agents](/docs/external-agents)                     |
+| **ワークスペース リソース** | skills/instructions/profile を 1 回作成します。アプリは実行時にそれらを継承します                     | **リソース** ([Workspace](/docs/workspace#global-resources)) |
+| **夢**                      | 過去の実行/フィードバックをレビューし、永続的な改善を提案して承認してください                         | **夢** タブ                                                  |
+| **承認フロー**              | インライン管理レビューの背後にあるゲートセンシティブなランタイム変更                                  | **ディスパッチ承認ポリシー**                                 |
+
+それぞれについては以下で詳しく説明します。
+
+### 中央受信トレイ
+
+Slack、電子メール、テレグラム、WhatsApp はすべて Dispatch のエージェント ループに流れます。 **[設定] → [メッセージング]** で各プラットフォームに 1 回接続すると、すべてのチャネルが同じメモリとツールを備えた同じエージェントに到達します。 Slack DM と `agent@yourcompany.com` への電子メールは、切断された 2 つのボットではなく、1 つの会話履歴上の 2 つの表面として扱われます。認証情報と Webhook URL については、「[Messaging](/docs/messaging)」を参照してください。
+
+### 秘密の保管庫
+
+資格情報を Dispatch のボールトに一度保存します。デフォルトでは、ボールトへのアクセスは **すべてのアプリ** です。保存されたすべてのキーはすべてのワークスペース アプリで利用でき、`sync-vault-to-app` は完全なボールトをターゲット アプリにプッシュします。より厳密な分離が必要なワークスペースは、コンテナーを **手動** モードに切り替えることができます。このモードでは、同期前にアプリごとの明示的な許可が必要です。管理者以外はアプリのシークレットを**リクエスト**できます。管理者は **承認**。これによりシークレットが作成され、手動ワークフローでは許可が作成されます。すべての読み取り、許可、同期、ローテーションが監査ログにキャプチャされます。これにより、「OpenAI キーの回転」が 10 個の PR ではなく 10 個のアプリにわたってワンクリック操作になるのです。
+
+### アプリ間の委任
+
+Dispatch は、ワークスペース内の他のアプリを A2A ピアとして自動的に検出します。手動登録やアプリごとの構成は必要ありません。ユーザーが Slack で「先週のサインアップの概要」を要求すると、Dispatch はそれを分析リクエストとして認識し、[A2A](/docs/a2a-protocol) 経由で分析アプリを呼び出します。 「アリスへの返信の下書き」を求めると、メール アプリにルーティングされます。 Dispatch は、最終的な回答を元のスレッドに投稿します。動作ルールはディスパッチ エージェントの指示の中にあります。つまり、ドメイン作業はドメイン アプリに属します。ディスパッチはスペシャリストではなくオーケストレーターです。
+
+### 統合 MCP ゲートウェイ
+
+ディスパッチは、外部エージェントの単一の MCP コネクタにすることができます。Claude、ChatGPT、Codex、または Cursor に `https://dispatch.agent-native.com/_agent-native/mcp` を 1 回追加すると、アプリごとに 1 つのコネクタではなく、付与されたすべてのワークスペース アプリに 1 つの承認が到達します。完全な接続フロー、アプリ許可、OAuth、およびインライン MCP アプリ プレビューについては、[External Agents](/docs/external-agents) を参照してください。
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "Unified MCP gateway endpoint",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### ワークスペース リソース
+
+Skills、ガードレール命令、エージェント プロファイル、および参照リソースは、Dispatch で一度作成すると、残りのワークスペースに継承できます。 **すべてのアプリ** スコープのリソースはグローバルです。Dispatch はそれらをワークスペース スコープで一度保存し、すべてのアプリ エージェントが実行時にそれらを読み取ります。これらは各アプリにコピーされず、手動によるワークスペースとリソースの同期手順はありません。アプリ共有リソースと個人リソースは、ワークスペースのデフォルトをローカルで上書きしたり、制限したりできます。
+
+正規パス テーブル、スターター パック、およびオーバーライド モデルについては、[Workspace — Global resources](/docs/workspace#global-resources) を参照してください。
+
+MCP サーバー リソースは JSON を使用し、意図的に HTTP 専用です。トークンを
+Vault をディスパッチし、それらのキーをターゲット アプリに付与または同期し、それらを参照します
+`${keys.NAME}` のヘッダーから取得するため、生の資格情報は決して存在しません
+リソース本体。
+
+**リソース** ページでは推奨スターター パックが強調表示されているため、管理者はどのファイルが存在するかをすぐに確認し、既存のスターター ファイルを上書きせずに不足しているスターター ファイルを復元し、その内容を編集できます。リソースを展開すると、選択したアプリ/ユーザーの効果的なランタイム スタックをプレビューできます。各アプリ カードには、アプリが何を受け取るかを正確に示す **コンテキスト** ビューもあります。
+
+### 夢
+
+Dispatch Dreams は、以前のエージェントの実行、フィードバック、評価、繰り返しの失敗をレビューして、永続的な改善を提案します。夢のレポートは、サイレントな書き換えではなく、レビューの表面です。それは、個人のメモリの更新、古いメモリのクリーンアップ、共有の `LEARNINGS.md` 編集、ワークスペースの指示/スキル/知識/エージェントのリソース、または定期的なジョブを提案することができ、各提案は、それを正当化する実行にリンクされます。共有指示とチーム全体のリソースは、特に受信 Slack、電子メール、電報、WhatsApp、または Web コンテンツから証拠が得られた場合、適用する前にレビューする必要があります。
+
+書き込みを提案する前に、Dreams は証拠を個人の記憶インデックス、既存の `memory/*.md` メモ、共有 `LEARNINGS.md` と比較します。レッスンがすでにキャプチャされている場合、レポートにはそのレッスンがスキップされたことが記録されます。関連する個人的な記憶が古くなっていると思われる場合、提案は複製を作成するのではなく、その既存のメモを対象とします。
+
+Dispatch の **Dreams** タブから開始します。最初に手動パスを実行し、提案レビュー シートを開いて現在のターゲットと提案されたコンテンツおよびソース証拠を比較してから、保持したい変更のみを適用します。レポートが一貫して役立つようになると、Dispatch は、共有または指示レベルの変更を自動適用することなく提案を作成し続ける、定期的な夢のジョブを作成できます。
+
+### 承認フロー
+
+Dispatch は、管理者のレビューの背後で機密性の高い実行時の変更をゲートできます。現在、これには **保存された宛先** (エージェントが積極的に送信できる Slack チャネルと電子メール アドレス)、共有/チーム **夢の提案**、オールアプリの **ワークスペース リソース**の作成/更新/削除、および **ディスパッチ承認ポリシー**自体が含まれます。ポリシーが有効になると、変更はキューに入れられ、エージェントはインライン承認プレビューをチャットに直接表示します。管理者は会話を離れることなく承認または拒否します。
+
+## Slack メッセージがディスパッチを通過する仕組み {#flow}
+
+一例をエンドツーエンドで見てみましょう。ユーザーがボットに次の DM を送信します: _「先週のサインアップの概要」_
+
+1. **Slack → Webhook.** Dispatch アプリで Slack `POST` から `/_agent-native/integrations/slack/webhook` へ。ハンドラーは署名を検証し、**`integration_pending_tasks` に行を挿入**してから、セルフターゲットの `POST` を自身のプロセッサーに起動し、Slack が再試行しないようにすぐに `200` を返します。
+2. **最新のプロセッサ実行。** プロセッサ エンドポイントは、独自のフル タイムアウトで新しい関数実行で実行されます。タスクをアトミックに要求し、エージェント ループを開始します。
+3. **ディスパッチ エージェントが決定します。** エージェントはメッセージを読み、「サインアップ」を分析インテントとして認識し、分析アプリの [A2A endpoint](/docs/a2a-protocol) に対して `call-agent` を呼び出します。実際の SQL の作業はそこで実行されます。
+4. **スレッドに返信が投稿されました。** 分析エージェントが結果を返します。 Dispatch はそれをフォーマットし、リンクされた ID があればそれを使用して、ユーザーが書き込んだのと同じ Slack スレッドにポストバックします (そのため、エージェントはワークスペース所有者の権限ではなく、要求者の権限で動作します)。
+5. **何かが故障した場合の回復。** プロセッサが飛行中にクラッシュした場合 (A2A タイムアウト、ダウンストリーム エージェント エラー、機能フリーズ)、再試行ジョブが 60 秒ごとにスタックしたタスクをスイープし、プロセッサを再起動します。タスクが `failed` とマークされるまで、最大 3 回の試行が必要です。
+
+```an-diagram title="A Slack message through Dispatch" summary="Slack enqueues into SQL, a fresh execution drains it, the Dispatch agent delegates the domain work over A2A, and the reply lands back in the originating thread. A 60s retry job recovers anything that dies mid-flight."
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack DM<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">verify + INSERT pending task</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">claim task · start agent loop</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch agent decides</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>Analytics app<br><small class=\"diagram-muted\">A2A peer · runs the SQL work</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+同じフローが電子メール、テレグラム、WhatsApp にも適用されます。変更されるのはアダプターのみです。
+
+## 信頼性のストーリー {#reliability}
+
+パイプライン全体は、プラットフォーム固有のバックグラウンド実行 API に依存することなく、すべてのサーバーレス ホスト (Netlify、Vercel、Cloudflare Workers) 上で存続できるように構築されています。
+
+- **Webhook → SQL キュー → 新規実行プロセッサ。** Webhook ハンドラー内でエージェント ループが実行されることはありません。ハンドラーの唯一のジョブは、検証し、キューに入れて、200 を返すことです。別の新しい実行によってキューが空になるため、エージェントの実行が遅いために受信 Webhook が拘束されたり、プラットフォームが再試行されたりすることはありません。
+- **A2A 継続ポーリング。** Dispatch が別のアプリに委任すると、制限付きタイムアウトでダウンストリーム タスクをポーリングします。ダウンストリーム エージェントに時間がかかりすぎるかクラッシュした場合、Dispatch は継続を記録し、再試行ジョブがそれを取得します。ユーザーの Slack 応答は引き続き到着します。
+- **自動署名クロスアプリ A2A。** ホストされたマルチアプリ ワークスペースは、デプロイ時にアプリごとの A2A 資格情報を自動生成するため、JWT シークレットを貼り付けなくても、同じワークスペース内のアプリが相互に呼び出すことができます。 Dispatch のエージェント検出レイヤーはワークスペース データベースからこれらの認証情報を読み取るため、新しく追加されたアプリは自動的に呼び出し可能なピアとして表示されます。
+
+## セットアップ {#setup}
+
+3 つの短いステップ:
+
+1. **Dispatch を含むワークスペースをスキャフォールディングします。** `npx @agent-native/core@latest create my-company-platform` を実行し、必要なドメイン テンプレートと一緒に `dispatch` を選択します。 Dispatch は `apps/dispatch` にあり、残りのアプリはその隣にあります。 [Multi-App Workspace](/docs/multi-app-workspace) を参照してください。
+2. **メッセージングに接続します。** Dispatch で **設定 → メッセージング** を開き、Slack、電子メール、テレグラム、または WhatsApp の接続をクリックします。フォーム フィールドは、[Messaging](/docs/messaging) ドキュメントの環境変数と一致します。各プラットフォームに必要なものについては、そこを参照してください。
+3. **他のアプリを追加します。** 各ドメイン アプリのワークスペース ルートから `npx @agent-native/core@latest add-app` を実行します。これらは、Dispatch の `list-workspace-apps` では A2A ピアとして自動的に表示されます。手動登録やエージェント カードの編集は必要ありません。エージェント カードが到達可能になり次第、ディスパッチは彼らへの委任を開始します。
+
+次に、資格情報をボールトに追加し、(オプションで) **リソース** の下にグローバル ワークスペース リソースを作成します。アクセス モードに応じて、Vault キーを同期または付与することができます。すべてのアプリのワークスペース リソースは自動的に継承されます。アプリごとにシークレットを分離する必要がある場合は、個々のアプリに許可を与える前に、ボールトのアクセス設定を手動に切り替えてください。
+
+## こちらもご覧ください {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) — 完全なアクション カタログとエージェント ガイドを備えた実際のスキャフォールド アプリ
+- [Messaging](/docs/messaging) — Slack、電子メール、電報、WhatsApp の接続
+- [A2A Protocol](/docs/a2a-protocol) — アプリ間の委任が内部的にどのように機能するか
+- [Multi-App Workspace](/docs/multi-app-workspace) — Dispatch が構築される展開形状
+- [Workspace Governance](/docs/workspace-management) — Dispatch のランタイム ガバナンスと組み合わせる git/GitHub ガバナンス

package/docs/content/locales/ja-JP/drop-in-agent.md

@@ -0,0 +1,260 @@
+---
+title: "ドロップインエージェント"
+description: "<AgentPanel>、<AgentSidebar>、sendToAgentChat() を使用して、エージェント チャット + ワークスペースを React アプリにマウントします。"
+---
+
+# ドロップインエージェント
+
+> **開発者ページ。** このページは、React アプリにエージェントを埋め込む開発者向けです。エージェントを使用したエンドユーザー エクスペリエンスについては、[Using Your Agent](/docs/using-your-agent) を参照してください。
+
+エージェントネイティブを最初から構築する必要はありません。エージェント チャット、ワークスペース タブ、CLI ターミナル、音声入力、およびすべての関連インフラストラクチャは、任意のアプリにドロップできる少数の React コンポーネントとして出荷されます。
+
+> **前提条件:** サーバーは `agent-chat-plugin` を実行している必要があります (すべてのテンプレートで自動マウントされます)。最初から始める場合は、[Server](/docs/server) を参照してください。
+>
+> チュートリアルの代わりに公開された API マップが必要ですか? [Component API](/docs/components) を参照してください。
+
+## コンポーネントの概要 {#components}
+
+| コンポーネント        | それは何ですか                                                                                       | 次の場合に使用します                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `<AgentSidebar>`      | ルート アプリのレイアウトをラップし、完全なエージェントを含む切り替え可能なサイド パネルを追加します | すべての画面でアプリの横にエージェントを使用できるようにしたい           |
+| `<AgentToggleButton>` | `<AgentSidebar>` を開く/閉じる (ヘッダーに入れます)                                                  | `<AgentSidebar>` とペアリング                                            |
+| `<AgentPanel>`        | 生のパネル自体 — チャット + CLI + ワークスペース タブ                                                | レイアウトを完全に制御したい、または専用のエージェント ページが必要      |
+| `<AgentChatSurface>`  | 配線済みのパネル/ページ チャット サーフェス                                                          | サイドバー ラッパーなしでチャットしたい                                  |
+| `<AssistantChat>`     | コンポーザー/履歴フックを備えた下位レベルのチャット レンダラー                                       | 標準会話 UI の周囲にカスタム クロムが必要です                            |
+| `sendToAgentChat()`   | プログラムによってメッセージをチャットに送信します                                                   | インラインで実行する代わりにエージェントに作業を渡すボタン               |
+| `useActionMutation()` | アクションのタイプセーフなフロントエンド ラッパー                                                    | UI は、エージェント ツールが実行するのと同じ操作を実行する必要があります |
+
+これらはすべて `@agent-native/core/client` からエクスポートされます。
+
+```an-diagram title="The mount model" summary="<AgentSidebar> wraps your existing layout. Your routes render in the main area; the agent panel mounts beside them. <AgentPanel> is the same panel without the wrapper."
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">Your app<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">Agent panel<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 80% のケース: `<AgentSidebar>` {#sidebar}
+
+最も一般的な設定は、どの画面でも右側から開くサイドバーです。
+既存のルート レイアウトを `<AgentSidebar>` でラップします。
+子はメイン アプリ領域に留まります。エージェント チャットはサイド パネルです。
+
+```an-annotated-code title="Wrapping the root layout with <AgentSidebar>"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"How can I help?\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "Wrapper", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "Starter prompts", "note": "`suggestions` render as clickable chips on the empty chat." },
+    { "lines": "13", "label": "Context-aware chips", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "Toggle button", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "Your app", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+それだけです。ユーザーは、チャット履歴、ワークスペース タブ、CLI ターミナル、音声入力、全画面モードを備えた、すべてのページに切り替え可能なエージェントを表示できるようになりました。状態は `localStorage` 経由でリロードしても維持されます。
+
+### 小道具
+
+- **`children`** — アプリの通常のレイアウトとルート。メインエリアにレンダリングされます。エージェント パネルは、デスクトップでは横に、モバイル/フルスクリーンではその上にマウントされます。
+- **`emptyStateText`** — チャットにメッセージがない場合に表示される挨拶。デフォルト: `"How can I help you?"`。
+- **`suggestions`** — スターター プロンプトが空の場合、クリック可能なチップとしてレンダリングされます。
+- **`dynamicSuggestions`** — `suggestions` と統合されたコンテキスト認識プロンプト チップ。デフォルトで有効になっています。静的な提案のみを表示するには `false` を渡し、カスタマイズするには `{ max, includeStatic, getSuggestions }` を渡します。
+- **`defaultSidebarWidth`** — 初期ピクセル幅 (マウントのみ。ユーザーによるサイズ変更と保存された値の上書き)。デフォルト: `380`。
+- **`position`** — `"left"` または `"right"`。デフォルト: `"right"`。
+- **`defaultOpen`** — サイドバーを開いた状態で開始するかどうか (デスクトップのみ)。デフォルト: `false`。
+
+## 残りの 20%: `<AgentPanel>` {#panel}
+
+専用の `/chat` ルート、管理するサイド列の埋め込みパネル、またはポップアップなど、レイアウトを完全に制御する必要がある場合は、`<AgentPanel>` を直接レンダリングします。
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` は、サイドバー ラッパー、折りたたみボタン、または状態の永続性のない生のタブ (チャット / CLI / ワークスペース) を提供します。好きな場所に置いてください。レイアウトを扱うのはあなたです。
+
+### 選択された小道具
+
+- **`defaultMode`** — `"chat"` または `"cli"`。デフォルト: `"chat"`。
+- **`className`** — 外側コンテナの CSS クラス。
+- **`onCollapse`** — 指定すると、ヘッダーに折りたたみボタンが表示されます。
+- **`isFullscreen`** / **`onToggleFullscreen`** — Claude スタイルの中央揃えの列が必要な場合は、外部の全画面状態を接続します。
+- **`storageKey`** — `localStorage` キーの名前空間。同じページ内で複数のパネル (異なるアプリ インスタンスまたはワークスペース) をレンダリングする場合に便利です。
+
+完全なプロパティ: `AgentPanelProps` の `@agent-native/core/client`。
+
+## プログラムメッセージ: `sendToAgentChat()` {#send}
+
+エージェントに作業を引き渡すボタン (インライン `llm()` 呼び出しを実行する代わりに - [ladder](/docs/what-is-agent-native#the-ladder) からのアンチパターン):
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### オプション
+
+- **`message`** — チャットに表示されるプロンプト。
+- **`context`** — プロンプトに追加される隠しコンテキスト (選択されたテキスト、カーソル位置、現在のエンティティ ID — エージェントが知っておく必要があるが、ユーザーが二度見すべきでないもの)。
+- **`submit`** — `true` は自動実行、`false` は事前入力されますが待機します。プロジェクトのデフォルトを使用する場合は省略します。
+- **`newTab`** — このプロンプトに対して別のチャット スレッドを作成します。
+- **`background`** — `newTab` では、新しいスレッドをフォーカスせずに実行します。非表示の実行は `RunsTray` で追跡されます。
+- **`openSidebar`** — バックグラウンド/サイレント送信の場合は `false` に設定します。デフォルトではサイドバーが開き、ユーザーに応答が表示されます。
+- **`type`** — `"content"` (デフォルト) は、組み込みアプリ エージェントで作業を保持します。 `"code"` はコード編集フレームにルーティングされます (エージェントが作成したコードの変更については、[Frames](/docs/frames) を参照してください)。
+
+`sendToAgentChat` は、チャットの実行を追跡するために使用できる安定した `tabId` を返します。
+
+サイレント作業の場合は、`newTab`、`background`、`openSidebar: false` をペアリングします。
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+これは、ツール、actions、スレッド状態、および実行を使用して実行される完全なエージェントです
+追跡。ユーザーの現在のサイドバー状態からフォーカスを盗むわけではありません。
+
+同じルートが MCP アプリとして埋め込まれている場合、送信されます
+`sendToAgentChat()` 通話は、サポートされている場合はホスト チャットに転送されます。
+MCP アプリ ブリッジ動作の [Client](/docs/client#sendtoagentchat)。
+
+読み込み状態が必要な場合は、`useSendToAgentChat()` フックを使用します。これは、`send` と `isGenerating` の両方を返します。
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## 標準のサイドバーが適合しない場合 {#custom-chat-ui}
+
+`<AgentSidebar>` と `<AgentPanel>` はほとんどのアプリをカバーします。
+エージェントの周りのレイアウト、またはエージェントとの会話を促進したい
+他の場所でビルドした場合は、レイヤーをドロップダウンしますが、フレームワークがそのレイヤーを所有し続ける
+ランタイム、actions、および SQL をサポートする状態:
+
+- **標準ランタイム周辺のクロムを所有します。** `<AgentChatSurface>` を使用してください
+  専用のチャット ルート、またはカスタム ヘッダーが必要な場合は `<AssistantChat>`
+  タブ、および標準会話の周りの空の状態。完全なレイヤー マップ —
+  インポート パスを含むすべてのコンポーネント、フック、コンポーザー、アダプターは、
+  [Component API](/docs/components#agent-chat-ui).
+- **独自のエージェント ランタイムを使用してください。** 他の場所で構築したエージェントを使用する場合は、
+  Agent-Native が作曲家、トランスクリプト、ツールを維持しながら会話を強化
+  カード、承認、ネイティブ ウィジェットは、`AgentChatRuntime` を
+  `<AssistantChat runtime={...} />`。コネクタ
+  (`createHttpAgentChatRuntime()` および OpenAI / Claude / Vercel AI / AG-UI
+  ヘルパー) とイベント コントラクトは
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+どのレイヤーを選択しても、actions および SQL をサポートするアプリの状態をコントラクトとして維持します。
+製品 UI から `/_agent-native/agent-chat` に直接投稿することは避けてください。もし
+実際のカスタム サーフェスに名前付きヘルパーがありません。最初にそのヘルパーを追加してください。
+クライアント コードは 2 番目のアドホック トランスポートを学習しません。
+
+## UI からのタイプセーフ actions: `useActionMutation()` {#use-action-mutation}
+
+UI がエージェント ツールが実行するのと同じ操作を実行する必要がある場合 ([ladder](/docs/what-is-agent-native#rung-three) の行 3)、`useActionMutation` を使用します。
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+タイプセーフな引数は、`defineAction()` の zod スキーマから取得されます。フルアクションシステムについては[Actions](/docs/actions)を参照してください。
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## 選択 + カーソル認識 {#selection}
+
+エージェントは、アプリケーション状態で `navigation` キーと `selection` キーを使用して、ユーザーが選択した内容 (テキスト、セル、スライド、連絡先) を確認できます。また、空のチャットでは、現在の画面に関連性がある場合に、これらのキーを使用して、「この選択内容を要約する」や「このスライドを改善する」などの動的な提案を提供します。 Cmd-I (または同様のもの) を使用して、選択した範囲をコンテキストとしてチャットに送信したい場合は、[Context Awareness](/docs/context-awareness) を参照してください。
+
+## すべてをまとめる {#putting-it-together}
+
+典型的なドロップイン設定:
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+ユーザーはヘッダーにチャット ボタンが表示され、それを開いてエージェントと会話できます。ボタンは、ワンショットの LLM コールを実行するのではなく、同じエージェントに対して手動で動作します。
+
+## 次は何ですか
+
+- [**Actions**](/docs/actions) — `defineAction()` および `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — 選択、ナビゲーション、画面表示
+- [**Workspace**](/docs/workspace) — [ワークスペース] タブに含まれるもの (skills、メモリ、MCP サーバー、スケジュールされたジョブ)
+- [**Voice Input**](/docs/voice-input) — チャット コンポーザーのマイク

package/docs/content/locales/ja-JP/durable-resume.md

@@ -0,0 +1,65 @@
+---
+title: "耐久性のある履歴書"
+description: "ホスト型エージェントの実行が中断されて再開される場合、完了した副作用のあるツール呼び出しは再実行されません。耐久性台帳から派生したツール呼び出しジャーナルにより、重複した送信、請求、チケットがブロックされます。"
+---
+
+# 耐久性のある履歴書
+
+> **対象者:** フレームワークがどのように実行されるかを理解したい人
+> リカバリにより、重複した副作用が回避されます。これは組み込みの動作です。
+> 接続するものは何もありません。
+
+ホストされたエージェントの実行が中断されます。サーバーレス関数がストリームの途中でハード タイムアウトに達し、ゲートウェイが 45 秒で接続を切断し、ソケットがハングアップし、プラットフォームがコールドスタートします。フレームワークは、会話プレフィックスを保存し、LLM 呼び出しを再実行する (「中断したところから続行する」) ことで、これらの状況からすでに回復しています。しかし、回復だけでも鋭い利点があります。中断された試行が **すでにメールを送信しているか、チケットを作成している**場合、単純な履歴書で再度実行できる可能性があります。
+
+耐久性のある履歴書がそのギャップを埋めます。再開時に、フレームワークは、どの副作用ツール呼び出しがすでに完了しているかを認識し、それらの再実行を拒否します (2 つのレイヤーで)。
+
+```an-diagram title="Two layers block duplicate side effects on resume" summary="The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">Layer 2 · hard-block re-dispatched write</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## ツールコールジャーナル {#journal}
+
+ジャーナルは **耐久性のある実行イベント台帳の純粋な読み取り**です。ホット パスには新しい記録フックはありません。現在のターンですでに記録されているツール呼び出しを分類します。
+
+- **Completed** — `tool_start` と一致する `tool_done`。呼び出しが実行され、副作用が発生し、その結果が記録されました。 **再実行しないでください。**
+- **中断** — `tool_done` に一致するものが**ない** `tool_start`。電話が始まり、その副作用が現れたかもしれないし、そうでないかもしれない、そして中断が結果を蝕んだ。結果は不明。
+
+マッチングは、耐久性のあるターンが他の場所でどのように再構築されるかを反映しています。`tool_done` は、同じツール名 (ツールごとに FIFO) のまだ開いている最も古い `tool_start` とペアになります。 `clear` イベント (破棄されたパーシャル出力) はターンごとの集計をリセットするため、破棄されたパーシャルがファントム オープン コールを残さないようにします。
+
+## レイヤー 1: プロンプトレベルのジャーナルノート {#prompt-note}
+
+実行が再開されると (ソフト タイムアウト、ゲートウェイ タイムアウト、または再開可能なトランスポート エラー)、フレームワークは、「中断したところから続行する」ナッジの直後に、**構造化されたジャーナル メモ**を再開プロンプトに追加します。このメモはモデルにプレーン テキストで次のように伝えます。
+
+- このツールは **すでに完了** (結果は短い) を呼び出すため、それらを再利用し、**再実行しません**。
+- どのツール呼び出しが **不明な結果で中断された**ため、成功か失敗かを判断する前に状態を確認します。
+
+ジャーナルが空の場合 (ツール アクティビティのないターン、またはクリーンな継続)、余分なものは何も追加されず、再開動作はバイトごとに以前と同じになります。このメモはベストエフォート型です。失敗した台帳の読み取りによって、通常は成功するリカバリがブロックされることはありません。
+
+## レイヤー 2: ツールレイヤーのハードブロック {#hard-block}
+
+プロンプトメモはアドバイスです。行儀の良いモデルは注意を払いますが、モデルは保証ではありません。したがって、ループはツール層でもそれを強制します。
+
+再開されたチャンクでループが実行される前に、ジャーナルのスナップショットが 1 回作成されます (この論理ターンの **前の** チャンクのみをキャプチャします)。モデルが、ツール名 ** と input** が完了したジャーナル エントリと一致する **write** ツールを再ディスパッチすると、ループが短絡します。アクションを実行する代わりに、ジャーナルに記録された結果を返します。ただし、呼び出しは以前に中断された試行ですでに完了しており、重複した副作用を避けるために再実行されなかったことが注意されます。
+
+主要なプロパティ:
+
+- **書き込みツールのみ。** 読み取り専用 (`readOnly` / GET) actions はブロックされません。再読み取りは安全で冪等です。
+- **Content-addressed.** 一致はツール名 + 入力署名であるため、ターン内の別の位置にある再開された呼び出しは依然として一致します。 *異なる*呼び出し (異なる引数) は新しいものとして扱われ、通常どおり実行されます。
+- **Consume-once.** 完了した各エントリは一致すると要求されるため、同じターン内の 2 つの完全に異なる同一のフレッシュ コールが両方とも 1 つのジャーナリングされた完了でショートすることはありません。
+- **新鮮なコールはそのままです。** 最初のターンのコールでは空のジャーナルが表示されます。通常の実行では何も変わりません。
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## 関連
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) — 耐久性のある実行台帳がクライアントにストリーミングされ、再接続時に再生される方法。
+- [**Actions**](/docs/actions) — `readOnly` は、読み取りを再実行しても安全であるとマークします。それ以外のものはすべて副作用として扱われます。
+- [**In-Loop Processors**](/docs/processors) — 別のループ内部硬化シーム。