@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "テンプレートの作成"
+description: "独自のエージェント ネイティブ アプリ テンプレートを作成して公開する方法。"
+---
+
+# テンプレートの作成
+
+テンプレートは、実際のワークフローを解決する完全なフォーク可能なエージェント ネイティブ アプリです。ファーストパーティ テンプレートは、使用するのと同じフレームワーク サーフェスを使用して構築されます。UI の React ルート、データの Drizzle SQL、操作の actions、エージェントの動作のワークスペース リソース、およびエージェントと UI の連携を維持するためのポーリング同期です。
+
+良いテンプレート:
+
+- 有用なシード データまたは空の状態のフローを使用して、1 つのワークフローをエンドツーエンドで解決します。
+- 永続的な状態は、JSON ファイルではなく、SQL に保存されます。
+- アプリの操作を `defineAction()` actions として定義します。
+- アプリケーションの状態を通じてナビゲーションと選択を公開します。
+- 明確な `AGENTS.md` と、明確ではないワークフロー向けに焦点を絞った skills を同梱します。
+- 必要なプロバイダーとシークレットのオンボーディング手順を登録します。
+- スタンドアロン アプリとしても、マルチアプリ ワークスペースの一部としても機能します。
+
+## チャットから開始 {#start-from-chat}
+
+フレームワークの配線がすでに整っている最小限のアプリが必要な場合は、チャット テンプレートを使用します。
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+複数のアプリを含むワークスペースの場合は、ピッカーを実行し、必要なドメイン テンプレートを使用してチャットを含めます。
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+チャットでは、認証、耐久性のあるチャット スレッド、SQL を利用したリソース、ツール、アプリケーションの状態、actions、ポーリング同期が提供されます。ドメイン モデルと製品 UI を追加します。
+
+再利用可能な UI テンプレートをまだ構築していない場合は、[Getting Started](/docs/getting-started#1-create-your-app) のヘッドレス オンランプを使用します。アクションを 1 つ定義し、`pnpm agent` で実行し、後でワークフローで耐久性のあるサーフェスが必要になったときに UI を追加します。
+
+## プロジェクトの構造 {#project-structure}
+
+すべてのテンプレートは、同じ広範なレイアウトに従います:
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+アプリケーション状態に `data/` ディレクトリを追加しないでください。永続的なアプリ データは SQL に属し、UI は actions または型指定されたサーバー ハンドラーを通じてそれを読み取ります。
+
+各テンプレートの 4 つの領域は、1 つの共有アクション サーフェスと 1 つの SQL データベースを介して連携します。エージェントと UI は、同じ操作に関して同等のパートナーです。
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## SQL のモデル データ {#data-models}
+
+フレームワーク Drizzle ヘルパーを使用してドメイン テーブルを定義し、SQLite、Postgres、D1、Turso、Supabase、Neon、およびその他のサポートされているバックエンド間でスキーマの移植性を維持します。
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+スキーマの変更は追加的である必要があります。 `server/plugins/db.ts` の `runMigrations()` を通じてテーブルと列を追加します。破壊的な SQL、`drizzle-kit push`、テーブル名の変更、または列の削除は決して使用しないでください。
+
+アプリの読み取りと書き込みには、Drizzle のクエリ ビルダーと `drizzle-orm` のポータブル オペレーターを使用します。 Drizzle でクエリを表現できる場合は、生の SQL を使用して製品コードを記述しないでください。また、テンプレートで `drizzle-orm/sqlite-core` または `drizzle-orm/pg-core` からインポートしないでください。
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+ユーザーまたは組織のデータを保持するスキーマを追加する前に、[Database](/docs/database) ドキュメントと [Security](/docs/security) ドキュメントを使用してください。
+
+## オペレーションを Actions として定義 {#actions}
+
+Actions は、アプリの動作に関する唯一の信頼できる情報源です。エージェントはそれらをツールとして呼び出し、フロントエンドはフックを通じてそれらを呼び出し、他のアプリは MCP/A2A を通じてそれらにアクセスできます。
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "型付き契約", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+読み取り専用の actions には、`http: { method: "GET" }` または `readOnly: true` を使用します。 `parallelSafe: true` は、同じターンのツール呼び出しと同時に安全に実行できる actions を変更する場合にのみ使用します。サンドボックス ツールから実行すべきではない、爆発半径の大きい actions には `toolCallable: false` を使用してください。
+
+## UI を構築する {#ui}
+
+ルートは `app/routes/` に存在し、React Router v7 ファイル ルーティングを使用します。 actions または API ハンドラーを通じてデータをクエリし、デフォルトでミューテーションを楽観的にします。
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+ライブ同期をアプリ シェルの近くに 1 回接続して、エージェント、別のタブ、またはアクションがデータを変更したときに React クエリ キャッシュが更新されるようにします。
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**エージェント ネイティブの約束: エージェントの書き込みは手動更新なしで UI に表示されます。** `useActionQuery` が簡単なパスです。変更アクションが `source: "action"` を発行すると、すべてのフックが再フェッチされます。カスタム キー (統合ステータスを読み取る低レベルのクライアント ヘルパーなど) を使用して生の `useQuery` に到達する場合は、ターゲットを絞った更新のためにソースごとのカウンターを queryKey に組み込みます。
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+共通ソース: `"action"` (すべての成功したエージェント アクション - 信頼性の高いフォールバック)、`"app-state"`、`"settings"`、およびストアが `recordChange` 経由で発行するカスタム リソース ソース。完全なパターンについては、`real-time-sync` スキルを参照してください。
+
+## アプリケーションの状態を追加 {#application-state}
+
+アプリケーションの状態は、エージェントがユーザーに何が表示されているかを知る方法です。少なくとも次の内容を追加します。
+
+- ルート、選択されたレコード、アクティブなタブ、またはエディターの選択が変更されたときにセマンティック `navigation` 状態を書き込む UI フック。
+- その状態を読み取り、現在の画面スナップショットを返す `view-screen` アクション。
+- UI が消費するワンショット `navigate` コマンドを書き込む `navigate` アクション。
+
+アプリケーション状態の書き込み、タブスコープのコマンド読み取り、読み取り後の削除、および重複コマンド保護の一貫性を維持するには、UI フックに `useAgentRouteState` を使用します。
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+URL クエリ パラメータで共有可能なフィルターを保持します。フレームワークはそれらを `<current-url>` としてエージェントに公開し、組み込みエージェントは `set-search-params` を使用してそれらを変更できます。 `navigation` は、完全なクエリ文字列の 2 番目のコピーではなく、セマンティック ID とエイリアスを保持する必要があります。
+
+アプリのナビゲーションには、同じオリジンを含む 1 つの `navigate` コマンドを優先します
+`path` (URL が既知の場合)。同じ動きに対して `__set_url__` も書き込まないでください。
+そのキーは、フレームワーク URL ツールおよび URL のみのフィルター変更用に予約されています。
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+完全なパターンについては、[Context Awareness](/docs/context-awareness) を参照してください。
+
+## API ルートは控えめに使用する {#api-routes}
+
+アプリの操作には actions を優先します。きれいに actions にできないサーフェスに対してのみ、カスタム Nitro ルートを作成します:
+
+- ファイルのアップロードまたはバイナリ ストリーミング。
+- 公開匿名ページと webhooks。
+- OAuth コールバックとプロバイダー固有のプロトコル ハンドラー。
+- サーバーでレンダリングされたパブリック コンテンツ。
+
+所有可能なデータを扱うカスタム ルートは、アクセス ヘルパーを使用する前に、`getSession(event)` を呼び出し、データベース作業を `runWithRequestContext({ userEmail, orgId }, fn)` でラップする必要があります。
+
+## エージェントの指示を書く {#write-agents-md}
+
+`AGENTS.md` は、アプリのエージェントのマップです。
+目的行、コア ルール、アプリケーション状態キー、アクション テーブル、および skills
+インデックス:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+新しいアクション、ルート、状態キー、または繰り返しを追加するたびに、`AGENTS.md` を更新します
+ワークフロー。 [Writing Agent Instructions](/docs/writing-agent-instructions) は
+完全ガイド — `AGENTS.md` をスキミング可能に保つ方法、4 つのそれぞれに属するもの
+ガイダンスの内容、およびエージェントが理解できるようにスキルとツールの説明を表現する方法
+確実にトリガーします。
+
+## Skills を追加 {#skills}
+
+プロバイダー固有の API、インポート/エクスポート形式、複雑な編集フロー、ドメイン用語など、`AGENTS.md` を肥大化させる詳細なパターンには、skills を使用します。
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+テンプレート skills を `.agents/skills/<name>/SKILL.md` に保存します。ユーザーが実行時にガイダンスを編集できるようにする必要がある場合は、ワークスペース リソースからもガイダンスを表示します。
+
+## セットアップ手順を登録する {#onboarding}
+
+テンプレートに API キー、OAuth 接続、またはプロバイダー アカウントが必要な場合は、要件を README に埋め込むのではなく、オンボーディング ステップを登録します。
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+[Onboarding & API Keys](/docs/onboarding) を参照。
+
+## ワークスペース対応にする {#workspace-ready}
+
+テンプレートは [Multi-App Workspaces](/docs/multi-app-workspace) に自然に適合し、通常は [Dispatch](/docs/dispatch) によって調整されます。
+
+チェックリスト:
+
+- フレームワーク エージェント チャット プラグインまたは `mountA2A()` を介して A2A をマウントし、兄弟アプリがエージェントを呼び出せるようにします。
+- エージェント カードの説明は、Dispatch が作業を正確にルーティングできるよう十分具体的なものにしてください。
+- 必要なシークレット/オンボーディングを登録すると、セットアップがサイドバーに表示され、Dispatch が共有認証情報を管理できるようになります。
+- 横断的な指示はすべてのアプリにコピーするのではなく、ワークスペース `AGENTS.md` またはワークスペース リソースに保持してください。
+- すべての所有可能なリソースに対して共有/アクセス ヘルパーを使用して、組織スコープのワークスペースを分離したままにします。
+
+## テンプレートを公開する {#publishing}
+
+共有する前に:
+
+1. `pnpm install`、`pnpm typecheck`、およびテンプレートのテストを実行します。
+2. オプションのプロバイダー キーが構成されていない状態でも動作することを確認します。
+3. 認証、共有、および 2 ユーザーのデータ分離を確認します。
+4. 必要な環境変数とオンボーディング手順を文書化します。
+5. 追跡されるランタイム データ ファイルではなく、追加的な移行を通じてサンプルまたはシード行を含めます。
+
+コミュニティ テンプレートは、GitHub リポジトリから作成できます。
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## フレームワークモノリポジトリへの貢献 {#contributing}
+
+### 未公開のフレームワークの変更をテストする {#test-unpublished-framework-changes}
+
+フレームワークモノリポジトリ内で作業していて、生成されたリポジトリが必要な場合
+未公開のパッケージまたはテンプレートの変更を使用するワークスペース。
+ローカルパッケージフラグ:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+生成されたワークスペースは、ローカルの `@agent-native/core` と
+`@agent-native/dispatch` パッケージのため、コア API、ディスパッチ ワークスペースに変更
+動作やファーストパーティのテンプレートは、公開前にテストできます。パッケージ
+`prepack` スクリプトは、リンク前に `dist` をビルドし、生成されたファイルを保持します
+現在のビルド出力を指すワークスペース。

package/corpus/core/docs/content/locales/ja-JP/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "クロスアプリ SSO"
+description: "Dispatch を ID 権限とする ID フェデレーションを介して、ホストされているすべてのエージェント ネイティブ アプリに 1 回サインインします。アプリごとにオプトインし、単一の環境変数で元に戻すことができます。"
+---
+
+# クロスアプリ SSO
+
+`*.agent-native.com` でホストされている各アプリは、**独自の個別のユーザー ストア**を使用して独自の展開を実行します。 `mail.agent-native.com` と `calendar.agent-native.com` は、データベース、セッション テーブル、または Cookie ドメインを共有しません。したがって、「一度サインインすればすべてのアプリを使用」を共有 Cookie にすることはできません。ワークスペースの ID 権限として [Dispatch](/docs/dispatch) が機能する **ID フェデレーション** である必要があります。
+
+これは、[A2A](/docs/a2a-protocol) と [External Agents](/docs/external-agents) がすでに使用しているものと同じ信頼プリミティブです。リクエスト境界で検証された `A2A_SECRET` 署名付き JWT が、エージェント間の呼び出しではなく人間のサインイン パスに適用されます。
+
+> **統合デプロイとドメインごとのデプロイ。** すべてのアプリを 1 つのオリジン (`your-agents.com/mail`、`your-agents.com/calendar`) でホストする場合、すでに単一の Cookie ドメイン経由で共有ログインが得られます。フェデレーションは必要ありません。クロスアプリ SSO は、アプリが別のドメインで実行される場合にのみ必要です。 [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment) を参照してください。
+
+## 内容と理由 {#what-why}
+
+アプリごとのユーザー ストアは、すべてのアプリが信頼するブラウザー Cookie が存在できる単一の場所が存在しないことを意味します。フェデレーション モデルでは、代わりに 1 つのアプリ (**Dispatch**) を ID 機関として指定します。他のアプリは「この人は誰ですか?」を委任できます。 Dispatch に送信し、ユーザーの検証済みメールの短期間の署名付きアサーションを取得し、**それをメールで自分のローカル アカウントにリンク**します。
+
+リンク ルールは意図的に狭く、追加的なものになっています。
+
+- **既存の同じ電子メール ユーザー → リンク済み。** ローカル アカウントは検証済みの電子メールと照合され、そのまま再利用されます。これは **変更、名前変更、または削除されることはありません**。フェデレーション レイヤーはそれを読み取り、セッションを作成するだけです。
+- **新しいメール → 作成されました。** 検証されたメールに対して新しいローカル アカウントが作成され、通常のローカル セッションが作成されます。
+
+これにより、ユーザーがログアウトされてもロールアウトが安全になります。 **ログアウトが必要です。** アプリがこれをオンにすると、既存のセッションが終了し、ユーザーは Dispatch を通じて再認証されます。ただし、ID 行は「追加」されるだけであり、破棄されたり、名前が変更されたり、再ポイントされたりすることはないため、常に **すべてのデータがそのままの状態で、**同じメールアドレスが一致したアカウントに再度ログインします\*\*。
+
+## 仕組み {#how-it-works}
+
+このフローは、標準的な承認→署名付きトークン→コールバック リダイレクトで、信頼境界を越えるのは電子メールだけです。
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **アプリ → ディスパッチ (承認)。** アプリはユーザーを ID 認証局に送信します。
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="ID 承認エンドポイント"
+   {
+     "メソッド": "GET",
+     "パス": "/_agent-native/identity/authorize",
+     "summary": "ディスパッチ (ID 機関) が人間を認証し、署名された ID トークンでリダイレクトします",
+     "auth": "セッションをディスパッチします (ない場合は対話型ログイン)",
+     "params": [
+       { "name": "app"、"in": "query"、"type": "string"、"required": true、"description": "要求元のアプリの識別子。" },
+       { "name": "redirect_uri"、"in": "query"、"type": "string"、"required": true、"description": "アプリ コールバック URL。厳格な許可リスト (デフォルトでは `*.agent-native.com` または localhost) に対して検証されます。" },
+       { "name": "state"、"in": "query"、"type": "string"、"required": true、"description": "リダイレクトで CSRF 状態がエコーバックされました。" }
+     ],
+     「応答」: [
+       { "status": "302", "description": "短期間の `A2A_SECRET` 署名付き ID JWT (`scope: \"identity\"`、`exp` ≤ 2 分) と元の `state` を運ぶ `redirect_uri` にリダイレクトします。" },
+       { "status": "400", "description": "`redirect_uri` が許可リストの検証に失敗しました (クロスオリジン、スキーム相対 `//host`、またはリストにないサフィックス)。" }
+     ]
+   }
+   ```
+
+2. **Dispatch は人間を認証します。** ユーザーがすでに Dispatch セッションを持っている場合、これは透過的です。そうでない場合、Dispatch は独自の通常のログイン (電子メール/パスワード、Google など - [Authentication](/docs/authentication) を参照) を表示します。ここでの Dispatch は、単なる通常のエージェントネイティブ アプリです。特別な認証モードは実行されていません。
+
+3. **ディスパッチ → アプリ (署名付き ID トークン)。** ディスパッチは、厳格な許可リストに対して `redirect_uri` を検証し、有効期間の短い **`A2A_SECRET` 署名付き ID JWT** を保持するアプリの `redirect_uri` に 302 リダイレクトします。トークンの要求は意図的に最小限に抑えられています:
+
+   | 請求         | 意味                                                         |
+   | ------------ | ------------------------------------------------------------ |
+   | `sub`        | ID 認証局での安定したユーザー ID                             |
+   | `email`      | ユーザーの **検証済み** メール — 唯一の参加キー              |
+   | `name`       | 表示名 (非権限、UI のみ)                                     |
+   | `org_domain` | ワークスペース/組織ドメイン (存在する場合)                   |
+   | `scope`      | 常に `"identity"` — このトークンはサインインのみを承認します |
+   | `exp`        | **≤ 2 分** 発行から                                          |
+
+4. **アプリは電子メールで検証し、JIT リンクします。** アプリは独自の `A2A_SECRET` でトークンの署名を検証し、`scope: "identity"` と `exp` をチェックして、**検証された電子メールによって厳密にジャストインタイム リンク**を実行します。
+   - その電子メールを持つローカル ユーザーが存在する場合 → それを変更せずに再利用します。
+   - そうでない場合は、そのメールのローカル ユーザーを作成します。
+
+5. **アプリは通常のローカル セッションを作成します。** ここから、ユーザーはそのアプリ自身のストアで通常のローカル セッションを持ちます。既存のすべてのアクセス チェック、組織スコープ、およびアクション ガードは以前とまったく同じように機能します。連邦は玄関口でのみ起こった。
+
+### オプトイン {#opt-in}
+
+アプリは、この環境変数がデプロイメントで設定されている場合に**のみ**参加します:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → アプリには、上記のフローを実行する **「Agent-Native でサインイン」** オプションが表示されます。直接ローカル ログイン (電子メール/パスワード、Google) は引き続き機能します。
+- **未設定 (デフォルト)** → **動作変更なし。** アプリは以前とまったく同じように認証します。フェデレーション コード パスは休止状態です。スキーマの変更や移行するものはないため、変数のオンとオフをいつでも完全に元に戻すことができます。
+
+## セキュリティ {#security}
+
+モデル全体は、いくつかの意図的に小さな保証に基づいています。
+
+- **有効期限の短い署名付きトークン。** ID アサーションは、有効期限が **≤ 2 分** の `A2A_SECRET` 署名付き JWT と `scope: "identity"` です。これはシングル サインインを承認し、長時間再生したり、API/A2A アクセスに再利用したりすることはできません。
+- **厳格な `redirect_uri` ホワイトリスト。** デフォルトでは、ディスパッチは `*.agent-native.com` またはローカルホストにのみリダイレクトされます。任意の、スキーム相対 (`//host`) およびクロスオリジン リダイレクト ターゲットは拒否されるため、権限をオープン リダイレクトまたはトークン抽出オラクルに変えることはできません。
+- **検証済みトークンからの電子メールのみの参加。** 信頼境界を越えるのは*のみ*、署名付きトークン内の検証済み電子メールです。アプリは、ネットワークからのユーザー ID、ロール、組織メンバーシップ、または特権状態を受け入れません。一致したアカウントからすべてをローカルに取得します。
+- **追加のみの ID 書き込み。** リンクでは、既存の同じ電子メール アカウントをそのまま再利用するか、新しいアカウントを挿入します。このパスでは、ID 行の更新、名前変更、再ポイント、削除は行われません。
+- **デフォルトではオフ。** `AGENT_NATIVE_IDENTITY_HUB_URL` を設定しないと、機能全体が不活性になります。
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+ジャストインタイム リンクは、検証済みの電子メールに完全に基づいて決定される単一の決定です。
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## セルフホスティング {#self-hosting}
+
+あらゆる Dispatch デプロイメントが ID ハブとして機能できます。`dispatch.agent-native.com` に限定されません。 Dispatch インスタンスを指すように各クライアント アプリで `AGENT_NATIVE_IDENTITY_HUB_URL` を設定します。
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**リダイレクト許可リスト。** ハブ (ディスパッチ) は、トークンを発行する前に承認エンドポイントで `redirect_uri` を検証します。ホワイトリストは `templates/dispatch/server/lib/identity-sso.ts` で構成されています:
+
+- **デフォルト:** `*.agent-native.com` および localhost のみ (`DEFAULT_ALLOWED_HOST_SUFFIXES` 定数)。
+- **拡張:** 追加のホスト サフィックスのカンマ区切りリストを使用して、Dispatch デプロイメントの `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` 環境変数を設定します。
+
+  ```bash
+  # デフォルトに加えて yourcompany.com サブドメインを許可します
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  各エントリはドットプレフィックス付きのサフィックス (`.yourcompany.com`) に正規化されるため、サフィックス チェックで十分であり、フットガンの可能性も最も低くなります。同期を保つためのアプリごとのリストは必要ありません。すべてに一致するエントリ (空または `.` のみ) はフィルタリングされて除外されます。
+
+- **Localhost** は、`IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` に関係なく、クライアント側アプリのローカル開発に常に許可されます。
+
+`IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` がない場合、セルフホスト型ディスパッチは `*.agent-native.com` 上のアプリにのみトークンを発行できます。 Dispatch デプロイメントで環境変数を設定して、他のドメインのロックを解除します。
+
+## Canary ロールアウト ランブック {#canary-rollout}
+
+カットオーバーとロールバックは、**アプリのデプロイメントごとに 1 つの環境変数**です。一度に 1 つのアプリをロールアウトし、検証してから拡張します。すべてのアプリに一度に変数を設定しないでください。
+
+**1。コードをデプロイします - 動作は変わりません。**
+`AGENT_NATIVE_IDENTITY_HUB_URL` **すべての設定を解除**して、すべてのアプリにリリースを配布します。いくつかのアプリで通常のログインが引き続き機能することを確認します。
+
+**2. ONE アプリでカナリアを一度に有効にします。**
+1 つの展開のみで設定:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+他のすべてのアプリの環境は未設定のままにしておきます。再デプロイ/再起動して、変数を取得します。
+
+**3.カナリアを検証します (チェックリスト)。**
+
+- アプリから**ログアウト**します。
+- ログイン画面に **「Agent-Native でサインイン」** と表示されます。クリックしてください。
+- **Dispatch** に移動し、ログインを完了します (すでにサインインしている場合はそのまま進みます)。
+- **アプリにリダイレクトされ、ログイン**します。これは新しいアカウントではなく、**以前と同じ既存のアカウント** (同じメールアドレス) です。
+- **アプリのデータはそのままです** - 既存のレコード、設定、組織のスコープは以前とまったく同じです。
+- **既存の直接ログインは引き続き機能します** — 電子メール/パスワードと Google サインインは、SSO と並行して機能し続けます。
+
+いずれかのチェックが失敗した場合は、ステップ 4 (ロールバック) に直接進みます。これは即座に行われ、データは安全です。
+
+**4.アプリごとに展開します。**
+1 つのアプリが検証されたら、次のアプリに対して手順 2 ～ 3 を繰り返し、一度に 1 つの展開で `AGENT_NATIVE_IDENTITY_HUB_URL` を設定します。決してバッチ有効化しないでください。
+
+**5.ロールバック = そのアプリのデプロイで環境変数の設定を解除します。**
+アプリを元に戻すには、**そのアプリの環境から `AGENT_NATIVE_IDENTITY_HUB_URL` を削除し、再デプロイ/再起動します。** アプリはすぐに以前の認証動作に戻ります。 **元に戻すデータ変更はありません**。ID 行は追加されただけであり、変数の設定を解除するとフェデレーション パスが再び休止状態になるだけです。各アプリのカットオーバーとロールバックは独立しており、元に戻すことができます。
+
+> ロールアウトは、各アプリが有効になるとユーザーをログアウトします (ユーザーは Dispatch 経由で再認証します)。ただし、ID 行は破棄されたり名前が変更されたりすることはなく、追加されるだけであるため、**データがそのままの状態で同じ電子メールが一致したアカウント**に常にログインし直します。
+
+## 関連 {#related}
+
+- [Authentication](/docs/authentication) — ローカル認証モード、セッション、組織、`A2A_SECRET` 環境変数
+- [A2A Protocol](/docs/a2a-protocol) — これが再利用する署名付き JWT、境界検証信頼モデル。
+- [External Agents](/docs/external-agents) — エージェント接続とディープリンクに適用される同じ `A2A_SECRET` 署名付き ID パターン。
+- [Dispatch](/docs/dispatch) — ワークスペース ID 権限およびルーティング ハブ。
+- [Security & Data Scoping](/docs/security) — 加算専用のデータ書き込みとアカウントごとのスコープ。
+- [Multi-App Workspaces](/docs/multi-app-workspace) — クロスドメイン SSO を完全に回避する統合シングルオリジン デプロイ。