@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/blueprint-installer.md

@@ -0,0 +1,83 @@
+---
+title: "ブループリント インストーラー"
+description: "agent-native add は、厳選された Markdown 統合レシピを stdout に出力します。これをコーディング エージェントにパイプし、ライブ リポジトリに対して変更を適用します。"
+---
+
+# ブループリント インストーラー
+
+> **対象者:** プロバイダー、チャネルを追加するホスト作成者およびインテグレーター
+> サンドボックス バックエンド、またはレシピをコーディング エージェントにパイプすることによるリポジトリへのアクション。
+
+`agent-native add` は、ファイルを書き込む愚かなスキャフォールダーではありません\*\*。厳選された Markdown _統合ブループリント_ を標準出力に出力します。そのブループリントを独自のコーディング エージェント (Claude コード、Codex など) にパイプし、フル コンテキストでライブ リポジトリに対して変更を適用します。
+
+これは、エージェントが変更を適用し、ファイルシステムを優先するハウス スタイルに適合します。フレームワークがレシピ (参照する正規ファイル、遵守するルール、検証ステップ) を提供し、コーディング エージェントが編集を行います。
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 使用法 {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # research-and-integrate from a URL
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- 裸の **名前** は、`blueprints/<kind>/<name>.md` から厳選されたブループリントを解決します。
+- 名前の代わりに **URL** を使用すると、その種類の一般的な _research-and-integrate_ ブループリントが生成され、URL が研究の開始点として埋め込まれます (URL は研究のシードであり、既知のレシピではありません)。
+- ブループリントは **stdout** に保存されます。診断は標準エラー出力に送られるため、`… | claude` はブループリントのみを受け取ります。
+
+## シードされたブループリント {#seeded}
+
+`agent-native add --list` には同梱品が表示されます:
+
+| 種類       | 名前      | 設定内容                                                                                            |
+| ---------- | --------- | --------------------------------------------------------------------------------------------------- |
+| `provider` | `stripe`  | プロバイダーを `provider-api` 基板 (カタログ/ドキュメント/リクエスト トリオ) に配線します。         |
+| `channel`  | `discord` | `PlatformAdapter` 受信 Webhook チャネルを実装し、登録します。                                       |
+| `sandbox`  | `docker`  | `SandboxAdapter` シームを実装して、Docker コンテナで `run-code` を実行します。                      |
+| `action`   | `crud`    | Zod スキーマを使用して単一のマルチサーフェス `defineAction` を追加します (N 上に 1 つの `update`)。 |
+
+各ブループリントは自己完結型です。ブループリントを読み取るコーディング エージェントは、アクセスするファイルを取得し、遵守するフレームワーク ルール (actions は唯一の真実のソース、シークレットは決してハードコードしない、所有可能なデータの範囲を設定する、`packages/*` ソースの変更セットを追加する)、および具体的な **Verify** セクションを取得します。
+
+## URL → 研究設計図 {#url}
+
+その種類に厳選されたレシピがない (または新たな統合が必要な) URL を渡すと、`add` は URL をシードとして汎用の「調査と統合」ブループリントを出力します。
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+生成されたブループリントは、コーディング エージェントに、実際のエンドポイント、認証モデル、ペイロード形状、署名/検証要件の URL (およびそのリンク先のページ) を取得するように指示します (トレーニング データから推測するのではなく)。その後、実装して検証します。また、種類固有のガイダンスも含まれます (例: `provider` URL は `provider-api` 基板に向けて誘導され、`channel` URL は `PlatformAdapter` に向けて誘導されます)。
+
+## 独自のブループリントを追加する {#authoring}
+
+Markdown ファイルを `packages/core/blueprints/<kind>/<name>.md` にドロップします。種類はサブディレクトリです。名前は`.md`を除いたファイル名です。これは自動的に取得されます。`--list`、名前解決、カタログはすべて実行時にディレクトリを読み取ります。登録するためにコードを変更する必要はありません。
+
+ブループリント `.md` ファイルは、`package.json` `files` の `blueprints` エントリを介して公開パッケージに同梱されるため、エンド ユーザーにとっては `node_modules/@agent-native/core/blueprints/**` で解決されます。
+
+各ブループリントを、他のコンテキストを持たないコーディング エージェントの命令セットとして作成します。優れた青写真には次のような特徴があります。
+
+1. **1 行の目標** と「あなたはエージェント ネイティブ アプリのコーディング エージェントであり、これらを実際のソース変更として適用します」というフレームワーク。
+2. **最初にお読みください** — 契約書である正確なファイル。
+3. **操作するファイル** — 具体的なパスと各変更の内容。
+4. **遵守するフレームワーク ルール** — actions ファースト、ハードコーディングされたシークレットなし、所有可能なデータのスコープ、公開可能なパッケージ ソースの変更セットの追加。
+5. **検証** — タイプチェック、焦点を絞った `*.spec.ts`、およびエンドツーエンド チェック。
+
+> [!TIP]
+> 既存の種類の下で新しくキュレートされたブループリントにはコードは必要ありません。ただし、新しい種類のディレクトリを作成すると、その種類は `--list` にも自動的に表示されます。
+
+## 次は何ですか
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) — `add sandbox docker` ブループリントのターゲットとなる継ぎ目
+- [**Actions**](/docs/actions) — すべてのブループリントが構築される唯一の信頼できる情報源
+- [**External Agents**](/docs/external-agents) — ブループリントをパイプするコーディング エージェントの接続

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

@@ -0,0 +1,129 @@
+---
+title: "CLI アダプター"
+description: "標準アダプター インターフェイス (アダプター ガイドで説明されている 2 つのアダプター シームの 1 つ) を介して、エージェントに CLI ツール (gh、ffmpeg、ストライプ) への構造化されたアクセスを提供します。"
+---
+
+# CLI アダプター
+
+> **これが当てはまる場所:** CLI アダプターは、
+> フレームワーク。正規ガイドは [Adapters](/docs/sandbox-adapters) です。
+> は、このシームと `run-code` サンドボックス シームの両方をカバーします (共有を含む)
+> エッジ/サーバーレス制約。このページはCLI側のクイックリファレンスです。
+
+CLI アダプターは単一のコマンドライン ツール (`gh`、`ffmpeg`、`stripe`、`aws`) をラップするため、エージェントはアダプターを検出し、インストールされているかどうかを確認し、一貫した stdout/stderr/exit-code 結果で実行できます。この継ぎ目がない場合、すべてのスクリプトは、CLI を呼び出してその出力を解析する方法を再発明します。
+
+```an-diagram title="CLI adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## インターフェース {#the-interface}
+
+すべての 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;
+}
+```
+
+## ShellCliAdapter {#shell-adapter}
+
+ほとんどの CLI では、カスタム クラスは必要ありません。`ShellCliAdapter` は、適切なデフォルトでバイナリをラップします。
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+オプション: `command` (必須)、`description` (必須)、`name` (デフォルトは `command`)、`env` (`process.env` とマージ)、`cwd` (デフォルトは `process.cwd()`)、および `timeoutMs` (デフォルト) `30000`)。
+
+カスタム認証、出力解析、または前後処理の場合は、`ShellCliAdapter` を使用する代わりに、`CliAdapter` を直接実装します。
+
+## レジストリ {#registry}
+
+`CliRegistry` は、エージェントが実行時に利用可能なものを検出できるようにアダプターを収集します。
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## actions から使用 {#from-actions}
+
+CLI 呼び出しを `defineAction` でラップして、アクション サーフェス上で公開します。コードがサーバー アクション サーフェス内で実行される場合は、`defineAction` が必要です。それ以外の場合は、`scripts/` ファイルでアダプターを直接使用します。アクション内で `process.exit` を決して呼び出さないでください。代わりにエラーをスローします。
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## エッジとサーバーレス {#edge-serverless}
+
+CLI アダプターは、エッジ/ワーカー ランタイム (Cloudflare ワーカー、Netlify Edge Functions) には存在しない `node:child_process` を使用します。標準の Node.js 環境で CLI アダプターのエンドポイントとタスクを実行します。この制約はサンドボックス シームと共有されます。詳細については、[Adapters](/docs/sandbox-adapters#edge-serverless) を参照してください。
+
+## 次は何だ
+
+- [**Adapters**](/docs/sandbox-adapters) — 両方のアダプターの継ぎ目への標準ガイド。
+- [**Actions**](/docs/actions) — 通常、CLI アダプターがラップされるアクション サーフェス。

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

@@ -0,0 +1,398 @@
+---
+title: "クライアント"
+description: "エージェント ネイティブ アプリ用の React フックとユーティリティ: sendToAgentChat、オプションのエージェント チャット コンテキスト状態、useDbSync、useAgentChatGenerating、および cn。"
+---
+
+# クライアント
+
+`@agent-native/core` は、エージェント ネイティブ アプリのブラウザ側に React フックとユーティリティを提供します。
+
+これらのクライアント/React API は、`@agent-native/core` と `@agent-native/core/client` の両方からエクスポートされます。ベア `@agent-native/core` ルートはデフォルトでノード ビルドに解決されるため、明確にして正しいバンドルを実現するために、`@agent-native/core/client` (ブラウザ エントリ) からインポートします。
+
+ファイルベースのルーティング (ページ、動的パラメータ、ナビゲーションの追加) については、[Routing](/docs/routing) を参照してください。
+
+## データのフェッチと変更 {#fetching-mutating}
+
+ブラウザからアプリ データを読み書きする主な方法は、アクション フックを使用することです。 `fetch` 呼び出しを `/_agent-native/*` ルートに手書きしないでください。代わりに名前付きヘルパーを使用してください ([Actions](/docs/actions) を参照)。
+
+```an-diagram title="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+postMessage 経由でエージェント チャットにメッセージを送信します。これは、UI インタラクションから AI タスクを委任する一般的な方法です。非表示のモデル コンテキストには `context` を渡し、すぐに送信するには `submit: true` を、ユーザーが最初にレビューするドラフトを事前入力するには `submit: false` を渡します。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+`embedApp()` で作成された MCP アプリ埋め込み内、自動送信メッセージ
+(`submit` 省略または `true`) は MCP アプリ ホスト ブリッジに転送されます。
+包含ホストに、非表示のコンテキストを追加し、表示されるユーザー ターンを送信するように要求します。
+`context` は、ユーザー向けチャットとして投稿されずに、モデルに表示されたままになります。
+MCP アプリはローカルの事前入力/レビュー動作を維持しないため、`submit: false` はローカルの事前入力/レビュー動作を維持します
+標準のドラフトプレフィル API を定義します。内部的には、これは送信されたチャット パスです
+`agentNative.submitChat` として現れることもあります。アプリコードは
+そのイベントを直接投稿するのではなく、`sendToAgentChat()`。
+
+### サイレントバックグラウンド送信 {#background-send}
+
+UI アクションが実際のエージェントの作業を開始する必要がある場合は、`background: true` を使用します
+サイドバーを開くか、フォーカスします。これでも通常のチャット スレッド/実行が作成されます。
+エージェントの tools/actions/context を使用し、作業を監視可能な状態に保ちます
+ラントレイ。これは生のワンショット モデル呼び出しではありません。
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` は `newTab` とペアになるように設計されているため、非表示の作業は行われません
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+後でフォローアップ ステータスを関連付けたり、実行にディープリンクしたりする必要があります。
+
+### エージェントチャットメッセージ {#agentchatmessage}
+
+| オプション            | タイプ      | 説明                                                                            |
+| --------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `message`             | `string`    | チャットに送信される表示されるプロンプト                                        |
+| `context`             | `string?`   | 非表示のコンテキストが追加されました (チャット UI には表示されません)           |
+| `submit`              | `boolean?`  | true = 自動送信、false = 事前入力のみ                                           |
+| `newTab`              | `boolean?`  | このプロンプトに対して別のチャット スレッドを作成します                         |
+| `background`          | `boolean?`  | `newTab` では、タブをフォーカスせずに実行し、実行結果を `RunsTray` に表示します |
+| `openSidebar`         | `boolean?`  | サイドバーを開かずに送信/事前入力するには false を設定します                    |
+| `projectSlug`         | `string?`   | 構造化コンテキストのオプションのプロジェクト スラグ                             |
+| `preset`              | `string?`   | ダウンストリーム コンシューマのオプションのプリセット名                         |
+| `referenceImagePaths` | `string[]?` | オプションの参照画像パス                                                        |
+
+## エージェント チャット コンテキストの状態 (詳細) {#agent-chat-context-state}
+
+コンテキスト状態の API は、双方向同期を必要とする UI のオプションのプラミングです。
+ステージングされたコンテキスト チップ: 現在のステージングされたアイテムをコンポーザーの外部でレンダリングします。
+項目がすでに添付されているかどうかを反映するか、明示的に提供する
+コントロールを削除/クリアします。
+
+単純に「これをエージェントに送信する」目的でこれらのヘルパーにアクセスしないでください。
+「レビューのためにこのドラフトを事前入力する」フロー。 `sendToAgentChat()` を `context` と一緒に使用する
+それらについては `submit`。
+
+| API                               | 次の場合に使用します                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | React コンポーネントにはライブ ステージングされたコンテキスト リストが必要です                        |
+| `setAgentChatContextItem(item)`   | 命令型コードは 1 つのキー付きコンテキスト項目をステージングまたは置換する必要があります               |
+| `listAgentChatContext()`          | 非 React コードには、ステージングされたコンテキストの 1 回限りのスナップショットが必要です            |
+| `removeAgentChatContextItem(key)` | UI は、安定した `key` によって 1 つの段階的コンテキスト項目を削除する必要があります                   |
+| `clearAgentChatContext()`         | UI は、ビューやモードのリセット後など、ステージングされたコンテキストをすべてクリアする必要があります |
+| `refreshAgentChatContext()`       | 命令型コードは、永続化された最新のコンテキスト スナップショットを再読み取りする必要があります         |
+
+`useAgentChatContext()` は `{ items, set, remove, clear, refresh }` を返します。
+
+## openAgentSettings(セクション?) {#openagentsettings}
+
+アプリ設定ページまたはセットアップ カードを開く必要がある場合は、`openAgentSettings()` を使用してください
+エージェント サイドバーの [設定] タブ。 `"llm"`、`"secrets"` などのセクション ID を渡します。
+`"automations"`、`"voice"`、または `"limits"` を使用して特定のセクションを開きます。
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+`agent-panel:open-settings` を直接ディスパッチするよりも、このヘルパーを優先します。
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client";
+
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` は、
+現在ステージングされているアイテムを 1 回。 `clearAgentChatContext()` は意図的に幅広くなっています。使用
+選択項目が 1 つだけ変更された場合は `removeAgentChatContextItem(key)`。
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| オプション    | タイプ     | 説明                                                                            |
+| ------------- | ---------- | ------------------------------------------------------------------------------- |
+| `key`         | `string`   | 既存のナゲットを置き換えるために使用される安定した識別子                        |
+| `title`       | `string`   | コンポーザーチップに表示される短いラベル                                        |
+| `context`     | `string`   | 次に送信されるプロンプトに含まれる非表示のコンテキスト                          |
+| `openSidebar` | `boolean?` | デフォルトは true です。 false をステージングコンテキストにサイレントに渡します |
+
+## ユーザーに質問する(オプション) {#ask-user-question}
+
+アプリコードからユーザーに多肢選択の質問をし、それをインラインでレンダリングします
+エージェントパネルに進み、**回答を待ちます**。これは、
+エージェントの組み込み `ask-question` ツール: `GuidedQuestionPayload` を
+`"guided-questions"` アプリケーション状態キー (マウントされた場所
+`GuidedQuestionFlow` がそれをレンダリングし、エージェント パネルが表示されるので、質問は次のとおりです。
+表示されます。回答がエージェントに返されるエージェント ツールとは異なります。
+`askUserQuestion()` **発信者への応答で解決**するため、UI は
+その上で分岐します。
+
+UI がその前に 1 つの小さな決定 (2 ～ 4 つの選択肢) を必要とする場合に使用します
+カスタム モーダルを構築するのではなく、エージェントの作業を開始します。
+フリーフォーム詳細用のコンポーザと、複数フィールド入力用のフォーム/ポップオーバー。
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+各オプションは `{ label, value?, description?, preview?, recommended? }` です。 `value`
+デフォルトは `label` で、`preview` は
+option. The promise resolves with the selected `value` (or `value[]` when
+`allowMultiple`)、ユーザーが「その他」を選択した場合のフリーテキスト文字列、または `null`
+スキップした場合、ユーザーが応答するまで保留状態になります。エージェントパネルが必要
+マウントされます (すべてのテンプレートにあります)。
+
+エージェントは `ask-question` ツールを通じて同じ UI に到達します。
+エージェントは、_it_ がコンテキストから解決できない本物のフォークにヒットしたときに尋ねます。使用
+`askUserQuestion()` _UI_ が選択肢に基づいてアクションを制御する必要がある場合。
+
+## MCP アプリホストブリッジ {#mcp-app-host-bridge}
+
+MCP アプリとして埋め込まれたルートは URL ファーストである必要があります: 現在のアーティファクトをロードします
+パス/クエリ パラメータ、実際の React ルートまたはフォーカスされた共有コンポーネントをレンダリングします。
+ホストブリッジはホスト所有の動作にのみ使用します。 `@agent-native/core/client`
+ヘルパーに埋め込まれたルート呼び出しをエクスポートします:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client";
+```
+
+`getMcpAppHostContext()` は、プッシュされた最新のホスト コンテキスト スナップショットを読み取ります。
+`useMcpAppHostContext()` は、React コンポーネントを変更にサブスクライブします。リクエスト
+ヘルパー (`openMcpAppHostLink`、`requestMcpAppDisplayMode`、
+`updateMcpAppModelContext`) 埋め込まれた MCP アプリ フレームの外で `false` を返す、または
+`Promise<boolean>` フレーム内。 `sendToAgentChat()` は
+埋め込みルートからの自動送信プロンプト。
+
+ブリッジ自体 — `ui/*` JSON-RPC メッセージ、`agentNative.mcpHost.*`
+ラッパー リレー、移植対制御フレーム レンダリング、ホスト コンテキスト、および
+表示モードのリクエスト — が所有しています
+[External Agents](/docs/external-agents#mcp-app-bridge).
+
+## 動的な提案 {#dynamic-suggestions}
+
+`<AgentSidebar>`、`<AgentPanel>`、および `<AssistantChat>` は、デフォルトで静的 `suggestions` をコンテキスト認識の提案とマージします。フレームワークは、空のチャットが表示されている間にアプリケーションの状態から `navigation`、`selection`、`pending-selection-context`、および現在の URL を読み取り、現在の画面に一致するプロンプト チップを提供します。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+静的チップのみを保持するように `dynamicSuggestions={false}` を設定します。アプリが同じアプリケーション状態コンテキストからの決定論的なドメイン固有のチップを必要とする場合は、`getSuggestions` を渡します。
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+読み込み状態の追跡を使用して sendToAgentChat をラップする React フック:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating` は、`send()` を呼び出すと true になり、エージェントが生成を完了すると自動的に false にリセットされます。
+
+## useDbSync(オプション?) {#usedbsync}
+
+React フック (以前の `useFileWatcher`) は、SSE を介してデータベースの変更をリッスンし、ポーリングにフォールバックし、UI をエージェントの書き込みと一致させるフレームワーク クエリ キャッシュを無効にします。
+
+```ts
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### オプション {#usedbsync-options}
+
+| オプション         | タイプ             | 説明                                                                                   |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
+| `queryClient`      | `QueryClient?`     | React - キャッシュ無効化のためのクライアントのクエリ                                   |
+| `queryKeys`        | `string[]?`        | 非推奨で無視されます。古い通話サイト用に保持                                           |
+| `pollUrl`          | `string?`          | エンドポイント URL をポーリングします。デフォルト: `"/_agent-native/poll"`             |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
+| `interval`         | `number?`          | ポーリング間隔 (ミリ秒)。デフォルト: `2000`                                            |
+| `fallbackInterval` | `number?`          | SSE が使用できない場合のフォールバック ポーリング間隔。デフォルト: `15000`             |
+| `pauseWhenHidden`  | `boolean?`         | ブラウザのタブが非表示の場合はポーリングを一時停止します。デフォルト: `true`           |
+| `ignoreSource`     | `string?`          | タブが自身の書き込みから再取得しないように無視するタブごとのリクエスト ソース          |
+| `onEvent`          | `(data) => void`   | SSE/polling が変更イベントを受信したときのオプションのコールバック                     |
+
+通常の CRUD の場合は、`useActionQuery` および `useActionMutation` を優先します。 actions を変更すると `source: "action"` が発行され、それらのフックは自動的に再フェッチされます。
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+フレームワークは変更バージョンを使用して、React クエリ キャッシュをバックグラウンド エージェント、cron ジョブ、または他のユーザーによって行われた変更と同期します。
+
+サーバー側のデータベースの変更が発生すると、サーバーは特定の `source` キーを使用して変更イベントを記録します。クライアントの `useDbSync` リスナーはこれらのイベントを受信し、そのソースのローカル変更バージョン カウンターをバンプします。バージョン カウンターを React クエリ キーに組み込むことにより、バックエンドがクライアントに新しいアクティビティを通知するたびに、クエリが自動的に再フェッチされます。
+
+- **`useChangeVersion(source: string): number`** — 指定された `source` が変更されるたびに増加するカウンターを返します。
+- **`useChangeVersions(sources: readonly string[]): number`** — 複数のソースのバージョン カウンターの合計を返します。
+
+### 例: 生のクエリをデータベースと同期する
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client";
+
+function DashboardView({ id }) {
+  // Get version for dashboards domain source
+  const v = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+### レイテンシ モデルと無効化動作
+
+- **UI によって開始されたミューテーション:** `useActionMutation` を使用して UI からアクションを実行すると、ミューテーションは成功するとすぐに `source: "action"` のローカル イベントを起動します。これにより、そのアクションに応じてすべてのクエリ キーの**即時の楽観的な再取得**がトリガーされ、視覚的な遅延が回避されます。
+- **バックグラウンドまたはエージェントの変更:** AI エージェント、Webhook、またはバックグラウンド ワーカーがデータを変更すると、更新がクライアントにブロードキャストされます。クライアントの `useDbSync` は、これを SSE (サーバー送信イベント) 経由で即座にキャプチャするか、**2 秒のポーリング ティック** にフォールバックします。その後、クエリ キーのバージョンが変化し、バックグラウンドでの再取得がトリガーされます。
+
+```an-diagram title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Agent · webhook · other tab</span><strong>Remote write</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
+## cn(...入力) {#cn}
+
+クラス名をマージするためのユーティリティ (clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core/client";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```