@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "ハーネス エージェント"
+description: "独自のループ、サンドボックス、ネイティブ ツール、および再開可能な SQL バックアップ セッションを使用して、Claude コード、Codex、Pi、およびその他の完全なコーディング ハーネスを Agent-Native 内の組み込みエージェントとして実行します。"
+search: "ハーネス エージェント AgentHarness ai-sdk HarnessAgent Claude コード Codex Pi Cursor Mastra 埋め込みコーディング エージェントsolveAgentHarness startAgentHarnessRun 再開可能なセッション サンドボックス ホスト ツール"
+---
+
+# ハーネスエージェント
+
+> **対象者:** 完全なコーディング ランタイム (Claude コード) を配線するホスト作成者
+> Codex, Pi) をエージェントとして Agent-Native に入力します。アプリを構築しますか?
+> [Creating Templates](/docs/creating-templates).
+
+ハーネス エージェントは、完全なエージェント ランタイム (Claude コード、Codex、Pi など) です。
+独自のループ、ワークスペース、ネイティブ ファイル ツール、セッション状態、圧縮を所有する
+承認モデルとサンドボックスの動作。 Agent-Native は
+**`AgentHarness`** `@agent-native/core/agent/harness` のサブストレート、ストリーミング
+イベントを通常のトランスクリプトに取り込み、スレッドとしてネイティブ セッションを保持します
+一時停止と再開が可能です。
+
+これは、組み込みのチャット エージェントや独自のチャットの導入とは異なります
+ランタイム。組み込みエージェントと `AgentEngine` は 1 つのモデルの往復用です
+`runAgentLoop` の下。ハーネスは `AgentEngine` プロバイダーではありません。
+独自のループをエンドツーエンドで実行するため、Agent-Native はそれを単一ではなくセッションとして駆動します
+モデル呼び出し。
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## どのコーディング ドキュメントが必要ですか? {#which-doc}
+
+| あなたがしたいのは…                                                                             | 使用                                         |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| 独自のループ + ツールを使用して、**エージェント**として Claude コード / Codex / Pi を実行します | **ハーネス エージェント** (このページ)       |
+| Claude-Code/Codex スタイル **コーディング ワークスペース UI** をレンダリングします              | [Agent-Native Code UI](/docs/code-agents-ui) |
+| エージェントの **`run-code` ツール**を実行するバックエンドを交換します                          | [Adapters](/docs/sandbox-adapters)           |
+| エージェントが呼び出せるように CLI ツール (`gh`、`ffmpeg`) をラップします                       | [Adapters](/docs/sandbox-adapters)           |
+
+隣接するサーフェス: Agent-Native のチャットの背後に別の場所に構築したエージェントを配置します
+UI と [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes);させて
+外部 MCP ホストが [External Agents](/docs/external-agents) 経由でアプリを呼び出します。
+スポーンバックグラウンド/サブエージェントは[Custom Agents & Teams](/docs/agent-teams)で実行されます。
+
+## 内蔵ハーネス {#built-in}
+
+`registerBuiltinAgentHarnesses()` は、AI SDK によってサポートされる 3 つのアダプターを登録します
+`HarnessAgent`:
+
+| 名前                         | ランタイム    | サンドボックス | 承認   |
+| ---------------------------- | ------------- | -------------- | ------ |
+| `ai-sdk-harness:claude-code` | Claude コード | はい           | はい   |
+| `ai-sdk-harness:codex`       | Codex         | はい           | いいえ |
+| `ai-sdk-harness:pi`          | 円周率        | いいえ         | はい   |
+
+それらのランタイム パッケージは **オプションのピア依存関係**であり、遅延ロードされるため、
+ハーネスを使用しないアプリには料金がかかりません。各アダプターには、
+`installPackage` ヒント (例: `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` はクリア インストールをスローします
+パッケージが見つからない場合のエラー、および `isAgentHarnessPackageInstalled(entry)`
+最初に確認できます。
+
+`registerBuiltinAgentHarnesses()` は [ACP](#acp) ハーネスも登録します
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## ACP エージェント {#acp}
+
+Agent-Native は [ACP](https://agentclientprotocol.com) (エージェント クライアント) として機能できます
+プロトコル) **クライアント** およびローカル コーディング エージェントを駆動します — Gemini CLI、Claude コード、
+または ACP 準拠のエージェント — この同じ基板を介して。エージェントは
+stdio 経由で改行区切りの JSON ～ RPC を話すローカル サブプロセス。 ACP の編集者
+↔ エージェント モデルはまさにこの形状です。
+
+このアダプターのスコープは **ローカル コーディング**です。子プロセスは
+親環境なので、エージェントはすでに持っているローカル CLI ログインを再利用します
+(たとえば、ユーザーのホーム ディレクトリの `gemini` または `claude` 認証)。それは
+ホスト型またはサンドボックス型のトランスポートであり、チャット/A2A トランスポートではありません - それらの場合
+[Agent Surfaces](/docs/agent-surfaces) を参照。
+
+| 名前              | デフォルトのコマンド                           | 再開可能\* |
+| ----------------- | ---------------------------------------------- | ---------- |
+| `acp`             | _(構成経由で `command`/`args` を供給)_         | はい       |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | はい       |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | はい       |
+
+\*エージェントが `loadSession` 機能をアドバタイズする場合、再開は機能します。
+それ以外の場合は、新しいセッションに低下します。
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+プロトコル トランスポート (`@zed-industries/agent-client-protocol`) はオプションです
+AI SDK と同様に、`installPackage` ヒントを通じて遅延ロードされる依存関係
+ハーネス。エージェント バイナリ自体 (`@google/gemini-cli`、
+`@zed-industries/claude-code-acp`, …) は別の外部 CLI です。プリセット
+`npx` を通じて起動すると、エージェント ACP のためコマンド/引数はオーバーライド可能なままになります
+エントリーフラグはまだ進化しています。
+
+ツール呼び出しを使用して、`permissionMode` を ACP `session/request_permission` にマップします
+エージェントのレポートの種類: 読み取りは常に実行され、編集は `allow-edits` で実行されます。
+`allow-all` を除き、危険なプロンプトはすべて表示されます。承認は通常どおり表面化します
+`approval-request` イベント。アダプターは `fs/read_text_file` と
+セッション ワークスペースに対する `fs/write_text_file` (エスケープするパスを拒否する
+it) と書き込みにより `file-change` イベントが発行されます。ターミナルメソッドはアドバタイズされません。
+したがって、エージェントは独自のシェルを使用します。
+
+## Codex 認証: コード UI とハーネス サンドボックス {#codex-auth}
+
+Codex サーフェスは 2 つあり、それぞれ異なる方法で認証されます。
+
+- **Agent-Native コード / デスクトップ** はユーザーのマシン上で `codex exec` を実行します。もし
+  ユーザーは `codex login` を実行しました。このローカル実行では ChatGPT が再利用されます
+  サブスクリプションまたは API キーは、インストールされた Codex CLI レポートを認証します
+  `codex login status`.
+- **`ai-sdk-harness:codex`** は `@ai-sdk/harness-codex` をロードし、Codex を駆動します
+  `@openai/codex-sdk` を介してハーネス サンドボックス内にあります。黙って行わない
+  サンドボックスがリモートである可能性があるため、ユーザーのデスクトップ `~/.codex` ログインを継承します
+  または孤立しています。信頼できる/プライベート サンドボックスの場合は、`codexCliAuth: true` でオプトインします。
+  Agent-Native は、ローカル Codex CLI 認証ファイルをサンドボックスにコピーしてから、
+  ハーネスが起動します。ホストまたは共有サンドボックスの場合、API キー / ゲートウェイを構成します
+  代わりに認証を行ってください。
+
+誰かが Codex OAuth パスを持つパッケージを尋ねたら: ローカル コーディング用
+セッション、`@agent-native/core` / デスクトップとインストール済みのものを使用します
+`@openai/codex` CLI および `codex login`。サンドボックス化された `ai-sdk-harness:codex` の場合、
+ログインをサンドボックスにコピーするときに、明示的な `codexCliAuth` オプトインを使用します
+許容されます。
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` は、`CODEX_HOME/auth.json` または `~/.codex/auth.json` を読み取ります。へ
+別のローカル ログインをポイントし、パス
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` または
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## 登録して解決 {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` は `AgentHarnessAdapter` を返します。
+オプションの `config` は、AI SDK アダプター用にアダプター工場に転送されます
+`AiSdkHarnessAdapterOptions` (`label`、`description`) にマッピングされます
+`permissionMode`、`harnessOptions`、`agentOptions`、および Codex のみ
+`codexCliAuth`)。 `listAgentHarnesses()` を使用して、登録されているものを列挙します。
+ピッカー。
+
+## ターンを実行する {#run-a-turn}
+
+`startAgentHarnessRun` はハーネス セッションを共有 run-manager にブリッジします
+ライフサイクル。ネイティブ セッションを作成 (または再利用) し、永続化し、
+ターン、各ハーネス イベントをトランスクリプト イベントに変換し、
+ターン完了時に状態を再開可能。
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` は実行マネージャーから `ActiveRun` を返します。そのため、ターン
+同様に、既存の実行ルート、トランスクリプト、キャンセルを通じて表示されます
+他のエージェントが実行されます。 `createSession` の代わりに、すでに作成された `session` を渡します
+メモリ内に保持しているセッションを継続します。
+
+## セッションと履歴書 {#sessions}
+
+ハーネスは、存続期間の長いネイティブ セッション状態を所有します。 Agent-Native は SQL に永続化します
+そのため、スレッドはターン、プロセス、デプロイを経ても存続できます。 `resumeState`
+は **不透明** — Agent-Native は保管して返却しますが、検査や
+それを解釈します。
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+このストアでは、`saveAgentHarnessSession`、`updateAgentHarnessSession` も公開しています。
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped`、および `ensureAgentHarnessSessionTables`。
+`startAgentHarnessRun` は保存/更新/停止パスを呼び出します。彼らに手を伸ばそう
+カスタム ホスト内でのみ直接。
+
+## ホストツールと権限 {#host-tools}
+
+ハーネスは独自のネイティブ ツール (読み取り、編集、書き込み、シェルなど) を備えているため、
+ファイル編集をホスト ツールとして再公開する**ことはありません**。 **狭い道だけを通過してください。
+Agent-Native actions から `createSession.tools` までの意図的なセット**
+ハーネスが特定のアプリ操作に到達し、`defineAction` を維持できるようにしたい
+認証、リクエスト コンテキスト、タイムアウト、切り捨て、読み取り専用メタデータがそのままの場合
+そうですよね。
+
+`permissionMode` は、承認なしにハーネスが実行できる動作を制限します:
+
+| モード        | 意味                                                                |
+| ------------- | ------------------------------------------------------------------- |
+| `allow-reads` | デフォルト。読み取りが実行されます。編集と危険な actions プロンプト |
+| `allow-edits` | 読み取りと編集が実行されます。その他の危険な actions プロンプト     |
+| `allow-all`   | 承認ゲートなし                                                      |
+
+ハーネスが承認のために一時停止すると、`approval-request` イベントが発行され、
+セッションは `idle` とマークされ、保留中の承認が記録されているため、UI は実行できます
+それを表面化し、ユーザーの決定に従って再開します。参照
+承認画面の場合は [Human Approval](/docs/human-approval)。
+
+## イベント {#events}
+
+ハーネス セッションは `AgentHarnessEvent` 値をストリーミングします。この値は Agent-Native
+次の標準 `AgentChatEvent` ストリームに変換します
+`agentHarnessEventToAgentChatEvents`。イベント ユニオンは `text-delta` をカバーします。
+`thinking-delta`、`activity`、`tool-start`、`tool-done` (
+ネイティブ ウィジェットの `mcpApp` ペイロード)、`approval-request`、`file-change`、
+`compaction`、`usage`、`error`、および `done`。ツールの結果は
+同じ翻訳、アクション宣言されたネイティブ ウィジェットは引き続きレンダリングされます — を参照
+[Native Chat UI](/docs/native-chat-ui).
+
+## バックグラウンド実行と UI {#background-runs}
+
+ハーネスはプロジェクトを共有 `BackgroundAgentRun` 形状に実行します
+`createAgentHarnessBackgroundAgentController()` は、
+既存の実行ルートは `goalId=agent-harness` です。つまり、長期にわたる Claude
+コードまたは Codex セッションが同じバックグラウンド実行およびトランスクリプト サーフェスに表示される
+`listAgentHarnessBackgroundRuns` を使用したエージェント チームおよびその他のアダプターとして
+`listAgentHarnessBackgroundTranscriptEvents`、`getAgentHarnessBackgroundRun`、
+`stopAgentHarnessBackgroundRun` はカスタム ホストで利用可能です。
+
+## カスタム アダプター {#custom-adapters}
+
+組み込みのいずれでもないランタイムをラップするには、
+`AgentHarnessAdapter` を入力して登録します。アダプターはその機能を宣言し、
+セッションを作成します。セッションは `streamTurn` とオプションの `continueTurn` を公開します。
+`approve`、`detach`、`stop`、および `destroy`。
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+`createSession` での動的インポートを使用してランタイム パッケージをオプションのままにし、
+`installPackage` ヒント。ブリッジバックコーディングハーネスの場合は、本物の
+で任意のコーディング エージェントを実行するのではなく、サンドボックス/ワークスペース プロバイダー
+ホスト プロセス — [Sandbox Adapters](/docs/sandbox-adapters) を参照。 AI SDK アダプター
+(`createAiSdkHarnessAdapter`、`@ai-sdk/harness` の `HarnessAgent` が支援) は
+パブリック抽象化ではなく、このコントラクトの 1 つの実装。
+
+## しないでください {#donts}
+
+- Claude コード、Codex、カーソル、マストラ、または Pi を `AgentEngine` として追加しないでください。彼ら
+  自分たちのループを所有します。 `AgentEngine.stream()` の下で 1 つを実行すると、ループが 2 回実行されます
+  セッションのライフサイクル セマンティクスが失われます。
+- 毎ターン、完全な Agent-Native チャット履歴をハーネスに再生しないでください。再開
+  代わりに `resumeState` を使用したハーネス セッション。
+- `resumeState` を `application_state` に保存しないでください。それはハーネスに属します
+  セッション SQL テーブル。
+- デフォルトでは、すべてのアプリ アクションをすべてのハーネス セッションに公開しないでください。渡してください
+  意図的に作られた小さなツールセット
+
+## 関連ドキュメント {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — `AgentChatRuntime` とのチャット UI の背後に独自のエージェントを配置します。
+- [Agent Surfaces](/docs/agent-surfaces) — ヘッドレス、チャット、サイドカー、またはフルアプリを選択します。
+- [Agent-Native Code UI](/docs/code-agents-ui) — 再利用可能なコーディング ワークスペース サーフェス。
+- [Custom Agents & Teams](/docs/agent-teams) — バックグラウンド実行とサブエージェントの委任。
+- [Sandbox Adapters](/docs/sandbox-adapters) — コーディング ハーネス用のプラグ可能な実行バックエンド。
+- [Human Approval](/docs/human-approval) — 承認サーフェス ハーネス実行が使用します。

package/docs/content/locales/ja-JP/human-approval.md

@@ -0,0 +1,86 @@
+---
+title: "人間参加型の承認"
+description: "重要なアクションが実行される前にエージェントを一時停止します。defineAction の needApproval ゲートは、approval_required イベントを発行し、人間が承認して初めてツールが実行されます。"
+---
+
+# 人間参加型の承認
+
+ほとんどの actions はそのまま実行できるはずです。メールの送信、カードへのチャージ、アカウントの削除などのいくつかの操作は、外向きで元に戻すのが難しいため、エージェントに自律的に実行してほしくありません。これらの場合、`defineAction` にはオプトイン **承認ゲート** があります。エージェントがアクションを呼び出そうとすると、ループが一時停止し、承認/拒否アフォーダンスを人間に表示し、人間がその特定の呼び出しを承認した後でのみアクションを実行します。
+
+> [!WARNING]
+> 承認は稀に保ちます。すべてのゲート アクションはエージェント ループのハード ストップであり、実行が中断され、人間による往復が必要になります。 `needsApproval` は、本当に重大な結果をもたらす、元に戻すのが難しい、外向きの操作にのみ使用してください。読み取りまたは定期的な書き込みをゲートしていることに気付いた場合、それは間違っています。デフォルトは **オフ** であり、ほとんどすべてのアクションではオフのままにする必要があります。
+
+## `needsApproval` ゲート {#needs-approval}
+
+`defineAction` に `needsApproval` を設定します。ブール値または述語を受け入れます。
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — 常に承認が必要です。
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** — 述語が true を返した場合にのみ承認が必要です。条件付きでゲートします。例:外部受信者のみ、またはしきい値を超える金額のみ:
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  述語を純粋かつ高速に保ちます。 **失敗クローズ**: 述語がスローされた場合、フレームワークは結果の高いアクションを黙って実行するのではなく、それを「承認が必要」として扱います。
+
+`needsApproval` が省略された場合、動作はバイトごとに変更されません。共通パスに追加のコストはかかりません。
+
+これは、従来の `parameters` スタイルの actions とスキーマ ベースの actions、およびアプリ内エージェント、サブエージェント、A2A、および MCP 呼び出し元でも同様に機能します (すべてのエージェント サーフェスは同じループを介してルーティングされます)。
+
+## ループの一時停止方法 {#loop}
+
+エージェントがゲート アクションを呼び出し、この特定の呼び出しがまだ承認されていない場合、ループは `run()` を実行しません\*\*。代わりに:
+
+1. ゲートを解決します。述語の場合、`needsApproval(input, ctx)` を呼び出します。スローは「承認が必要」（フェイルクローズ）として扱われます。
+2. `tool_start` イベントを発行し (UI が呼び出しを表示するように)、その直後に **`approval_required`** イベントが続き、ターンを停止します。アクションの副作用は決して起こりません。
+
+`approval_required` イベントには、クライアントがアフォーダンスをレンダリングするために必要なものがすべて含まれています。
+
+| フィールド    | タイプ       | メモ                                                                                |
+| ------------- | ------------ | ----------------------------------------------------------------------------------- |
+| `tool`        | `string`     | エージェントが呼び出そうとしたアクション名。                                        |
+| `input`       | オブジェクト | エージェントが渡した引数。                                                          |
+| `approvalKey` | `string`     | **安定したキー** クライアントは、*この呼び出し*を承認するためにエコーバックします。 |
+| `toolCallId`  | `string`     | モデル側のツール呼び出し ID (使用可能な場合)。                                      |
+
+`approvalKey` はツール名とその入力から決定論的に導出されるため、同じ論理呼び出しでは常に同じキーが生成されます。モデルがそれを確認したり設定したりすることはありません。これは純粋にフレームワークと人間の承認アフォーダンスの間のハンドシェイクです。
+
+一時停止されたツールは、ターンが一時停止され、再試行しないようにモデルに通知する結果を返すため、モデルは回転しません。
+
+## 人間がどのように承認するか {#approve}
+
+`approval_required` では、チャット UI が、一時停止されたツール呼び出しに対して **承認/拒否** アフォーダンスをレンダリングします。これは `AssistantChat` で自動的に接続されます。テンプレートごとに構築する必要はありません。
+
+- **Approve** は、`approvedToolCalls: [approvalKey]` にコールのキーを含むターン (通常の継続メッセージ) を再発行します。再発行されたターンでは、ゲートは承認されたセット内のキーを確認し、その特定の呼び出しを通常どおり実行できるようにします。
+- **Deny** はアフォーダンスをローカルで拒否します。何も再発行されないため、アクションは実行されません。
+
+`approvedToolCalls` は、チャット リクエスト (`AgentChatRequest.approvedToolCalls`) のフィールドです。その中に存在しないキーは一時停止されたままになります。1 つの通話を承認しても、他の通話が白紙に承認されることはありません。キーはコンテンツでアドレス指定されているため、承認により、*それらの引数を使用した呼び出し*が許可されます。後でモデルが別の送信を提案した場合、それは新しいキーと新たな承認になります。
+
+## エンドツーエンド {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+フレームワークにおけるこのゲートの標準的な (そして意図的にまれな) 使用法は、メール テンプレートの `send-email` アクションです。これにより、`needsApproval: true` が設定されるため、エージェントは自由にドラフトしてキューに入れることができますが、特定の送信を人間が承認しないと実際にメッセージを送信することはできません。
+
+## 関連
+
+- [**Actions**](/docs/actions#needs-approval) — 戻り値を検証するための `outputSchema` を含む、完全な `defineAction` サーフェス。
+- [**Security**](/docs/security) — 承認ゲートに到達するタイミングとモデルからアクションを非表示にするタイミング。
+- [**Mail template**](/docs/template-mail) — `send-email` は参考例です。

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

@@ -1,15 +1,18 @@
 ---
 title: "国際化"
-description: "共有 locale カタログ、言語ピッカー、ブラウザー言語フォールバック、locale 対応 docs コンテンツで Agent Native アプリをローカライズします。"
+description: "共有ロケール カタログ、言語ピッカー、ブラウザ言語フォールバック、ロケール対応ドキュメント コンテンツを使用して、Agent Native アプリをローカライズします。"
 ---
 
 # 国際化
 
-Agent Native アプリは共有ランタイム `@agent-native/core/client/i18n` を通じて、フレームワークとテンプレートの UI をローカライズできます。フレームワークはユーザーの言語選択を SQL settings に保存し、それを actions として公開し、アプリがまだ翻訳していない文字列は English にフォールバックします。
+Agent Native アプリは、共有を通じてフレームワークとテンプレート UI をローカライズできます
+`@agent-native/core/client/i18n` ランタイム。フレームワークはユーザーの
+SQL 設定で言語を選択し、actions として公開し、
+アプリが文字列をまだ翻訳していない場合の英語。
 
-## ランタイム {#runtime}
+## ランタイム
 
-`AppProviders` から provider を使います。
+`AppProviders` を通じてプロバイダーを使用します:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` は React の hydration 前に初期 `lang`、`dir`、`window.__AGENT_NATIVE_LOCALE__` を設定します。公開 SSR ルートでは `@agent-native/core/server` の `resolveLocaleFromRequest()` を呼び、解決された locale/catalog をこの script に渡すことで hydration mismatch を避けられます。
+`getLocaleInitScript()` は、初期の `lang`、`dir`、および
+React が水和する前の `window.__AGENT_NATIVE_LOCALE__`。パブリック SSR ルートは
+`@agent-native/core/server` から `resolveLocaleFromRequest()` を呼び出し、
+ハイドレーションの不一致を避けるために、ロケール/カタログをそのスクリプトに解決しました。
 
-## カタログ {#catalogs}
+## カタログ
 
-ローカライズされた各テンプレートは `app/i18n/` にカタログを置きます。
+ローカライズされた各テンプレートは、`app/i18n/` の下にカタログを保持します。
 
 ```ts
 // app/i18n/index.ts
@@ -52,11 +58,15 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-`en-US` は必ずバンドルします。English 以外のカタログは動的 import にして、ユーザーが現在の locale だけをダウンロードするようにします。対応する locale codes は `en-US`、`zh-CN`、`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN`、`ar-SA` です。
+常に `en-US` をバンドルします。英語以外のカタログを動的にインポートできるため、ユーザーのみ
+アクティブなロケールをダウンロードします。サポートされているロケール コードは、`en-US`、`zh-CN`、
+`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN`、および `ar-SA`。
 
-## UI {#ui}
+## UI
 
-インターフェイス文字列には `useT()` を使い、アプリの `/settings` ページに `<LanguagePicker />` を置きます。サイドバーを持つアプリは、アプリのサイドバーに **Settings** を表示してください。ヘッダーの言語アイコンはショートカットです。
+インターフェース文字列に `useT()` を使用し、アプリに `<LanguagePicker />` を配置します
+`/settings` ページ。サイドバー アプリは、アプリのサイドバーに **設定** を公開する必要があります。
+ヘッダーの言語アイコンは単なるショートカットです。
 
 ```tsx
 import {
@@ -82,26 +92,42 @@ function SettingsPage() {
 }
 ```
 
-「Agent settings」コントロールは、モデル、API キー、自動化、音声などの framework-level controls のために、右側の agent sidebar の Settings tab を開くべきです。その設定がアプリの中心的な体験なら、アプリ自身の settings page に重要な framework 設定を重複表示してもかまいません。ただし source of truth は sidebar settings tab です。
+「エージェント設定」コントロールは、右側のエージェント サイドバーの設定タブを開く必要があります
+モデル、API キー、オートメーション、音声、その他のフレームワーク レベルのコントロール用。
+アプリは、独自の設定ページで価値の高いフレームワーク設定を複製する場合があります
+設定がアプリの中心であるが、サイドバーの設定タブがそのままの場合
+真実の情報源。
 
-日付、数値、相対時間、リストには `useFormatters()` を使います。locale に依存する日付や数値の整形を翻訳文字列の中に入れないでください。
+日付、数値、相対時間、リストには `useFormatters()` を使用します。入れないでください
+翻訳文字列内のロケール依存の日付/数値の書式設定。
 
-## Docs サイトのコンテンツ {#docs-site-content}
+## ドキュメント サイトのコンテンツ {#docs-site-content}
 
-公開 docs ページは同じ core provider を使いますが、`persistPreference={false}` にして匿名 docs トラフィックが SQL settings actions ではなく localStorage とブラウザー言語を使うようにします。English のソースは `packages/core/docs/content/*.md` に残ります。ローカライズされたページ override は `packages/core/docs/content/locales/<locale>/<slug>.md` に置きます。
+パブリック ドキュメント ページは同じコア プロバイダーを使用しますが、
+`persistPreference={false}` なので、匿名ドキュメント トラフィックは localStorage を使用し、
+SQL 設定 actions の代わりにブラウザ言語。英語のソースは
+`packages/core/docs/content/*.md`。ローカライズされたページのオーバーライドは、
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-アプリのカタログと同じ BCP-47 locale codes を使ってください。English ソースと同じ slug を維持し、翻訳された見出しでは `{#anchor}` で安定したアンカーを保ち、routes、action names、protocol fields、env vars、provider names は翻訳しません。ある locale に翻訳 Markdown がないページは English にフォールバックしつつ、ナビゲーションと chrome はローカライズされます。
+アプリ カタログと同じ BCP-47 ロケール コードを使用します。
+英語ソース。翻訳された見出しに `{#anchor}` を使用して安定したアンカーを保持します。
+ルート、アクション名、プロトコル フィールド、環境変数、プロバイダー名はそのままにします
+未翻訳。ロケールのページに翻訳された Markdown がない場合は、ドキュメント サイト
+ナビゲーションとクロムをローカライズしながら、そのページは英語に戻ります。
 
-## Actions と永続化 {#actions-and-persistence}
+## Actions と永続性
 
-すべてのアプリは以下を継承します。
+すべてのアプリは以下を継承します:
 
-- `get-localization-preference` — 現在のユーザーの `{ locale }` を読む
-- `set-localization-preference` — `"system"` または対応 locale を設定する
+- `get-localization-preference` — 現在のユーザーの `{ locale }` を読み取ります
+- `set-localization-preference` — `"system"` またはサポートされているロケールを設定します
 
-永続値はユーザー単位の SQL settings の `localization` に保存されます。`localStorage` は pre-hydration と匿名フォールバックにだけ使います。アクティブな locale は application state に環境コンテキストとして反映されるため、agents は現在の UI 言語を確認できます。
+耐久性の値は、`localization` の下のユーザースコープの SQL 設定に存在します。
+`localStorage` は、事前ハイドレーションと匿名フォールバックにのみ使用されます。アクティブ
+ロケールはアンビエント コンテキストとしてアプリケーションの状態にミラーリングされるため、エージェントは確認できます
+現在のインターフェース言語。
 
-## Guard {#guard}
+## ガード
 
 実行:
 
@@ -109,6 +135,11 @@ function SettingsPage() {
 pnpm guard:i18n-catalogs
 ```
 
-guard は対応 locale ファイル名、key parity、placeholder parity、stale keys、`Intl.PluralRules` による CLDR plural categories を検証します。構造を検証するもので、翻訳品質は検証しません。目立つ文字列は人によるレビューが必要です。
+ガードは、サポートされているロケール ファイル名、キー パリティ、プレースホルダー パリティを検証します。
+古いキー、および CLDR から `Intl.PluralRules` までの複数のカテゴリ。チェックします
+翻訳の品質ではなく構造。視認性の高い文字列には依然として人間が必要です
+レビュー。
 
-action names、routes、enum values、app-state keys、database values、protocol fields、env var names、provider names などの安定した識別子は翻訳しないでください。
+アクション名、ルート、列挙値などの安定した識別子は変換しないでください。
+アプリ状態キー、データベース値、プロトコル フィールド、環境変数名、またはプロバイダー
+名前。