@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "定期的なジョブ"
+description: "Cron でスケジュールされたプロンプトは、日次ダイジェスト、週次レポート、時間ごとのポーリングなど、エージェントが独自に実行します。"
+---
+
+# 定期的なジョブ
+
+**定期的なジョブ** は、cron スケジュールで実行されるプロンプトです。これは、エージェントが独自に物事を行う方法です。「毎朝 7 時に夜間のメールを要約する」「毎週月曜日に先週の登録番号を Slack に投稿する」「1 時間ごとに古い下書きを徹底的に調べて削除する」
+
+定期的なジョブは時計に合わせて起動されます。 _events_ (予約の作成、電子メールの受信) に反応するには、同じ `jobs/` ファイル形式と条件を使用します。[Automations](/docs/automations) を参照してください。
+
+ジョブは `jobs/<name>.md` の [workspace](/docs/workspace) に存在します。これは、YAML フロントマターを持つ Markdown ファイルだけです。登録も配線も必要ありません。ファイルをドロップすると、フレームワークがそれを取得します。
+
+## ジョブ ファイル {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+それだけです。本体は、スケジュールされた起動ごとにエージェントが実行するプロンプトです。エージェントは、インタラクティブ チャットと同じツールとワークスペース コンテキスト (actions、skills、メモリ、接続された MCP サーバー、サブエージェント) にすべてアクセスできます。
+
+## フロントマター {#frontmatter}
+
+| フィールド   | タイプ                        | デフォルト   | 説明                                                                                                                    |
+| ------------ | ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | cron 式                       | _(必須)_     | 標準の 5 フィールド cron。 `"0 7 * * *"` = 毎日 07:00; `"0 */4 * * *"` = 4 時間ごと。                                   |
+| `enabled`    | ブール値                      | `true`       | `false` に切り替えて、ジョブを削除せずに一時停止します。                                                                |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`  | `"creator"` は、ジョブ所有者の ID と `ANTHROPIC_API_KEY` を使用して実行されます。 `"shared"` は組織のキーを使用します。 |
+| `createdBy`  | メール                        | _(自動)_     | ジョブがワークスペース UI を通じて、またはエージェントによって作成されたときに設定されます。                            |
+| `orgId`      | 文字列                        | _(自動)_     | 組織の範囲。作成者のアクティブな組織から継承されます。                                                                  |
+| `lastRun`    | ISO タイムスタンプ            | _(管理対象)_ | 各実行後にスケジューラによって書き込まれます。                                                                          |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(管理対象)_ | 最新の結果。                                                                                                            |
+| `lastError`  | 文字列                        | _(管理対象)_ | 最後の実行が失敗した場合のエラー メッセージ。                                                                           |
+| `nextRun`    | ISO タイムスタンプ            | _(管理対象)_ | `schedule` から計算されます。スケジューラが次にいつ起動するかを決定するために使用されます。                             |
+
+`last*` フィールドと `nextRun` フィールドは、スケジューラによって書き込まれます。これらを読んで履歴を確認することはできますが、手動で編集しないでください。次回の実行で上書きされます。
+
+## Cron 構文 {#cron}
+
+標準の 5 フィールド cron (分、時、日、月、曜日):
+
+| クロン         | 意味             |
+| -------------- | ---------------- |
+| `*/5 * * * *`  | 5 分ごと         |
+| `0 * * * *`    | 毎正時           |
+| `0 */4 * * *`  | 4 時間ごと       |
+| `0 7 * * *`    | 毎日 07:00       |
+| `0 9 * * 1`    | 毎週月曜日 09:00 |
+| `0 17 * * 1-5` | 平日 17:00       |
+| `0 0 1 * *`    | 毎月 1 日        |
+
+フレームワークには、リソース層とスケジューラ層によって内部的に使用される cron 文字列を検証およびレンダリングするための cron ユーティリティ (`isValidCron()` および `describeCron()`) が含まれています。
+
+## ジョブの作成 {#creating}
+
+### 「ワークスペース」タブから
+
+`+` → ワークスペース パネルの **スケジュールされたタスク**。プロンプトとスケジュールを入力します。 `jobs/<slug>.md` として保存し、次の一致するティックで実行を開始します。
+
+### エージェントに問い合わせる
+
+> 「毎朝 7 時に未読メールを要約するスケジュールされたタスクを作成します。」
+
+エージェントがファイルを書き込みます。
+
+### 手動
+
+フレームワークのリソース APIs を介して、Markdown ファイルを `jobs/` にドロップします。
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## スケジューラの実行方法 {#how-scheduler-runs}
+
+スケジューラは、インプロセスで実行されるフレームワーク プラグイン (内部 `processRecurringJobs()` ルーチン) です。サーバーが実行されている場所に関係なく、エージェント チャット プラグイン内で `setInterval` が 60 秒ごとに起動します (起動遅延は 10 秒)。
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## ジョブのデバッグ {#debugging}
+
+- ワークスペースで `jobs/<name>.md` を開きます。前編には `lastRun`、`lastStatus`、`lastError`、`nextRun` が表示されます。
+- **待たずにテストしてください:** 強制発射ツールはありません。同じ作業をオンデマンドで実行するには、ジョブのプロンプトをエージェント チャットに貼り付けてそこで実行するか、一時的にスケジュールを次の分に設定して、スケジューラが次のティックでそれを取得するようにします (その後、実際の cron を復元します)。
+- **一時停止します:** `enabled: false` を反転します。ファイルはそのまま残り、実行が停止するだけです。
+
+## エージェント ツール {#agent-tool}
+
+すべてのテンプレートに 1 つの `manage-jobs` ツールが登録されます。 `action` パラメータは操作を選択します:
+
+| アクション | パラメータ                                                    | 目的                                                                                  |
+| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `create`   | `name`、`schedule`、`instructions` (必須); `scope`、`runAs`   | 新しい定期的なジョブを作成する                                                        |
+| `list`     | `scope` (`personal`、`shared`、またはすべて)                  | すべてのジョブをステータス (スケジュール、有効、最後/次回の実行) とともにリストします |
+| `update`   | `name` (必須); `schedule`、`instructions`、`enabled`、`runAs` | 既存のジョブを編集する                                                                |
+| `delete`   | `name` (必須)                                                 | ジョブを削除します - 最初に常にユーザーに確認してください                             |
+
+**個人スコープと共有スコープ。** 各ジョブは、個人スコープ (作成者として実行され、作成者のみに表示される) または共有/組織スコープ (作成者に代わって実行されるが、組織メンバーに表示される) のいずれかに存在します。 `scope` および `runAs` パラメータは作成時にこれを制御します。組織管理者は、共有ジョブを更新または削除できます。管理者以外のメンバーは自分のメンバーのみを管理できます。
+
+## スケジュール パッケージとは異なります {#vs-scheduling-package}
+
+定期的なジョブと `@agent-native/scheduling` を混同しないでください:
+
+- **定期的なジョブ (このページ)** — cron でスケジュールされた _プロンプト_ エージェントがバックグラウンドで実行されます。フレームワークレベル。ワークスペースに住んでいます。あらゆるエージェントネイティブ アプリ上で実行されます。
+- **`@agent-native/scheduling`** — カレンダー/予約機能 (イベント タイプ、空き状況ウィンドウ、予約) を構築するための再利用可能なドメイン パッケージ。 `calendar` テンプレートとカスタム スケジュール サーフェスを強化します。
+
+定期的なジョブとは、「エージェントを独自に動作させるにはどうすればよいか?」というものです。スケジュール パッケージは、「カレンダー アプリをどうやって構築するか?」です。さまざまな懸念。
+
+## 次は何ですか
+
+- [**Automations**](/docs/automations) — イベント トリガーと条件を同じ `jobs/` 形式に追加します
+- [**Workspace**](/docs/workspace) — ジョブが skills、メモリ、カスタム エージェントと共存する場所
+- [**Actions**](/docs/actions) — ジョブが呼び出すツール
+- [**Agent Teams**](/docs/agent-teams) — ジョブは並行作業を行うサブエージェントを生成することがよくあります

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

@@ -0,0 +1,79 @@
+---
+title: "ルーティング"
+description: "React Router v7 を使用したエージェント ネイティブ アプリのファイルベースのルーティング — ページ、動的パラメータ、ナビゲーション。"
+---
+
+# ルーティング
+
+エージェント ネイティブ アプリは、`@react-router/fs-routes` から `flatRoutes()` 経由のファイルベースのルーティングで **React Router v7** を使用します。 `app/routes/` 内のすべてのファイルは URL になります。テンプレートはドット表記規則を使用します。つまり、単一のファイル名内の URL セグメントはドットで区切られます。
+
+## ファイルベースのルーティング {#file-based-routing}
+
+### ファイル → URL マッピング
+
+| ファイル              | URL                  | メモ                                            |
+| --------------------- | -------------------- | ----------------------------------------------- |
+| `_index.tsx`          | `/`                  | インデックスルート                              |
+| `settings.tsx`        | `/settings`          | シンプルなページ                                |
+| `inbox.$threadId.tsx` | `/inbox/:threadId`   | ドット = `/`、`$` = 動的パラメータ              |
+| `_app.tsx`            | (URL セグメントなし) | パスレス レイアウト — `_` のプレフィックス      |
+| `inbox/route.tsx`     | `/inbox`             | フォルダー形式 — `route.tsx` はインデックスです |
+
+動的パラメータのセグメントに `$` という接頭辞を付けます。パスレス レイアウト ルート (URL セグメントなし) にするには、`_` というプレフィックスを付けます。テンプレートは `flatRoutes()` を使用します。上記のドット表記ファイルがプライマリです。ネストされたフォルダー形式 `inbox/route.tsx` も機能します。
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## 新しいページを追加しています {#adding-a-page}
+
+ファイルを作成し、デフォルトのコンポーネントをエクスポートします。
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+それだけです。React ルーターが自動的にそれを取得します。登録は必要ありません。
+
+## 動的パラメータ {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## ナビゲーション {#navigation}
+
+クライアント側のナビゲーションには `<Link>` を使用し、プログラムによるナビゲーションには `useNavigate()` を使用します。
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## 次は何ですか
+
+- [**Client**](/docs/client) — エージェントネイティブのブラウザフックとユーティリティ
+- [**Server**](/docs/server) — ファイルベースのサーバー ルートと `/_agent-native/` 名前空間

package/docs/content/locales/ja-JP/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "アダプター"
+description: "フレームワークの 2 つのアダプターの継ぎ目: サンドボックス アダプターは、エージェントの実行コード ツールを実行するバックエンドを交換し、CLI アダプターはエージェントにコマンドライン ツールへの構造化されたアクセスを提供します。"
+search: "アダプタ サンドボックス アダプタ cli アダプタ 実行コード SandboxAdapter CliAdapter ShellCliAdapter 耐久性ランナー リモート サンドボックス エッジ サーバーレス child_process"
+---
+
+# アダプター
+
+> **対象者:** ランタイムを拡張するホスト作成者。アプリ開発者はほとんどいない
+> これが必要です。デフォルトはそのままで機能します。
+
+Agent-Native にはアダプターの継ぎ目が 2 つあり、狭い部分の背後にある懸念を考慮に入れています。
+交換可能なインターフェース:
+
+- **サンドボックス アダプター** は、エージェントの `run-code` ツールを実行するバックエンドを交換します —
+  デフォルトではローカルの子プロセス、または Docker / リモート / 耐久性ランナー。
+- **CLI アダプタ** は、エージェントにコマンドライン ツールへの構造化されたアクセスを提供します
+  (`gh`、`ffmpeg`、`stripe`) 検出、可用性チェック、
+  一貫した結果の形状。
+
+両方とも 1 つの実行時制約を共有します。つまり、Node.js システム バインディングに依存し、次のことを実行します。
+エッジ/ワーカー ランタイムでは実行されません。[Edge and serverless](#edge-serverless) を参照してください。
+
+## どのコーディング ドキュメントが必要ですか? {#which-doc}
+
+| あなたがしたいのは…                                                                             | 使用                                         |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| エージェントの **`run-code` ツール**を実行するバックエンドを交換します                          | **サンドボックス アダプター** (このページ)   |
+| エージェントが呼び出せるように CLI ツール (`gh`、`ffmpeg`) をラップします                       | **CLI アダプター** (このページ)              |
+| Claude-Code/Codex スタイル **コーディング ワークスペース UI** をレンダリングします              | [Agent-Native Code UI](/docs/code-agents-ui) |
+| 独自のループ + ツールを使用して、**エージェント**として Claude コード / Codex / Pi を実行します | [Harness Agents](/docs/harness-agents)       |
+
+# サンドボックス アダプター
+
+`run-code` ツールは、エージェントが提供する JavaScript を隔離された環境で実行します。 **サンドボックス アダプター** は、そのツールの実行に関する懸念を考慮に入れないため、エージェント ループ、`run-code.ts`、ローカルホスト ブリッジ、env スクラブ、または出力形式に触れることなく、バックエンド (デフォルトではローカルの子プロセス、または Docker / リモート / 耐久ランナー) を交換できるようになります。
+
+## なぜ縫い目があるのか {#why}
+
+デフォルトのバックエンドは、ロックダウンされたローカル ノードの子プロセスを生成します。これはホスティング プロセスによって制限されます。ホストされたプラットフォームでは、エージェント ループのソフト実行上限 (タイムアウト/継続スラッシュの前に約 40 秒) を共有します。リモート アダプターまたは耐久性のあるアダプターは、その上限を超えるための手段です。リクエストのライフサイクルとは関係なく、大規模なデータ ジョブを完了まで実行します。
+
+コントラクトを狭く保つということは、リモート アダプタが同じセキュリティ体制を継承することを意味します。親プロセスは、秘密が含まれるすべての所有権を保持します。サンドボックス モジュールを構築し、localhost ブリッジ (リクエスト コンテキストを保持し、ホスト ホワイトリストと SSRF ガードを適用します) を実行し、env をスクラブし、出力をフォーマットします。アダプターは、すでに準備された **非シークレット** モジュール ソースとリソース制限のみを受け取ります。アダプターは、それを*実行*し、stdout/stderr/exit ステータスをキャプチャすることのみを担当します。
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## インターフェース {#interface}
+
+シームは `packages/core/src/coding-tools/sandbox/` のコア内に存在します — `adapter.ts` (コントラクト)、`index.ts` (選択: `getSandboxAdapter()` / `registerSandboxAdapter()`)、および `local-child-process-adapter.ts` (デフォルト)。 `run-code.ts` によってパッケージ内で配線されています。ホストは、`index.ts` 登録ヘルパーを介して (または、Docker バックエンドの場合は、これらのファイルを直接編集する [blueprint](/docs/blueprint-installer) を介して) 別のバックエンドに接続します。
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+すべてのバックエンドは `SandboxAdapter` を実装します。
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+リクエストと結果は意図的に小さく、不透明になっています。
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## デフォルト: `LocalChildProcessAdapter` {#default}
+
+そのまま使用すると、`getSandboxAdapter()` は `LocalChildProcessAdapter` (`id: "local-child-process"`) を返します。過去の `run-code` の動作がバイトごとに保存されます:
+
+- 準備されたモジュール ソースは新しい一時ディレクトリに書き込まれます。
+- 子は、サンドボックス ディレクトリ内で指定された `TMPDIR`/`TEMP`/`TMP` を使用して、スクラブされた環境 (シークレットなし) で実行されます。
+- ノード権限モデル (ノード 20 の `--permission` または `--experimental-permission`) が使用可能な場合、子は、その一時ディレクトリ外のファイル システム アクセス、および子プロセス、ワーカー、ネイティブ アドオンへのアクセスを拒否されます。送信ネットワークは許可モデルによってブロックされません。しかし、env スクラブは、そのようなリクエストには認証情報が含まれず、すべての認証された呼び出しが親のループバック ブリッジを経由することを意味します。
+- タイムアウトにより `SIGTERM` が送信され、その後 2 秒の猶予期間の後に `SIGKILL` が送信されます。
+- 一時ファイルは実行後にベストエフォートでクリーンアップされます。
+
+> [!WARNING]
+> デフォルトのアダプターは `node:child_process` を使用しますが、これはエッジ/ワーカー ランタイムには存在しません。標準の Node.js 環境で `run-code` を実行するか、リモート アダプターを登録します — [Edge and serverless](#edge-serverless) を参照してください。
+
+## アダプターの選択 {#selection}
+
+解決順序 — 明示的に登録されたアダプターが優先されます。それ以外の場合は、環境変数によって組み込みが選択されます。それ以外の場合は、ローカルのデフォルトが使用されます。
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` 環境変数 {#env}
+
+ID によって組み込みアダプターを選択します。現在、`local` (デフォルト) のみが配線されています。不明な値は実行に失敗するのではなく、ローカルにフォールバックします。
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+ホスト プロセスは、シームの `index.ts` を介した後続のすべての `run-code` 呼び出しのバックエンドをオーバーライドします。たとえば、リモート コンテナーですべての呼び出しを実行します。
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## 耐久性のあるランナーのための縫い目 {#durable}
+
+このインターフェイスは、将来のリモート/耐久性のあるサンドボックスの継ぎ目として意図的に作られています。リモートまたは耐久性のあるアダプター (Docker、Vercel-Sandbox スタイルのランナー、またはキューに入れられたバックグラウンド ワーカー) は次のとおりです。
+
+1. アウトプロセス ランタイムに対して `SandboxAdapter.run` を実装します。
+2. ループバック ブリッジをトンネルします (またはプロキシ ブリッジが親にコールバックします)。
+3. 大規模なデータ ジョブを、リクエストのライフサイクルとは独立して完了まで実行します。これは、ローカルの子プロセス アダプターを制限する、ホストされたコード実行の最大 40 秒の上限を超えます。
+
+新しい `AGENT_NATIVE_SANDBOX` 値 (例: `remote`) および/または `registerSandboxAdapter()` 経由で登録します。エージェント ループと `run-code.ts` は決して変わりません。
+
+> [!TIP]
+> `agent-native add sandbox docker` ブループリントは、このシームに対して Docker アダプターを実装するための完全な自己完結型レシピを生成します。 [Blueprint Installer](/docs/blueprint-installer) を参照してください。
+
+# CLI アダプター
+
+もう一方のアダプター シームは単一のコマンド ライン ツール (`gh`、`ffmpeg`、`stripe`、`aws`) をラップしているため、エージェントはそれを検出し、インストールされているかどうかを確認し、一貫した stdout/stderr/exit-code 結果で実行できます。すべての CLI アダプターは `CliAdapter` を実装します。
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+ほとんどの CLI では、`ShellCliAdapter` は適切なデフォルトでバイナリをラップし、`CliRegistry` はランタイム検出用のアダプターを収集します。
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+CLI 呼び出しを `defineAction` でラップして、アクション サーフェスに公開します。 `ShellCliAdapter` オプション、カスタム アダプター、およびアクション ラッピング パターンについては、[CLI Adapters](/docs/cli-adapters) クイック リファレンスを参照してください。
+
+## エッジとサーバーレス {#edge-serverless}
+
+> [!WARNING]
+> 両方のアダプターの継ぎ目は、Node.js システム バインディングに依存します。サンドボックス `LocalChildProcessAdapter` および CLI アダプター (`ShellCliAdapter` およびカスタム アダプター) は、Cloudflare Workers や Netlify Edge Functions などのエッジ/ワーカー ランタイムには**存在しません** `node:child_process` (`execFile` / `spawn`) を使用します。サーバー ルートをこれらのエッジ プリセットに展開する場合、これらのアダプターを実行するとランタイム例外がスローされます。標準の Node.js 環境 (従来のサーバー コンテナーまたはサーバーレス ノード機能) でアダプターのエンドポイントとタスクを実行します。または、サンドボックス シームの場合は、プロセス外で作業を送信するリモート アダプターを登録します。
+
+## 次は何ですか
+
+- [**CLI Adapters**](/docs/cli-adapters) — CLI シームのクイック リファレンス
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` は Docker アダプターのレシピを出力します
+- [**Agent Teams**](/docs/agent-teams) — 重労働をサブエージェントに委任
+- [**Security**](/docs/security) — 環境スクラブおよびブリッジ許可リストの状態