@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,332 @@
+---
+title: "認証"
+description: "電子メール/パスワード、ソーシャル プロバイダー、組織、および MCP ベアラー資格情報との認証統合の向上。"
+---
+
+# 認証
+
+エージェント ネイティブ アプリは、アカウント優先の設計で認証に [Better Auth](https://better-auth.com) を使用します。ユーザーは初回訪問時にアカウントを作成し、初日から実際の ID を取得します。
+
+## 概要 {#overview}
+
+認証は、認証サーバー プラグインの `autoMountAuth(app)` を介して自動的に構成されます。 3 つのモードがあります:
+
+- **デフォルト:** 電子メール/パスワード + ソーシャルプロバイダーによる認証の向上。初回訪問時にオンボーディング ページが表示されます。
+- **リモート MCP OAuth:** Claude コードや ChatGPT コネクタなどの MCP ホスト用の標準 OAuth 2.1。
+- **カスタム:** `getSession` コールバック経由で独自の認証を取得します。
+
+```an-diagram title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads."
+{
+  "html": "<div class=\"auth-modes\"><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default</span><strong>Better Auth</strong><small class=\"diagram-muted\">email/password &middot; Google &middot; GitHub</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Remote MCP OAuth</span><strong>OAuth 2.1 + PKCE</strong><small class=\"diagram-muted\">Claude Code, ChatGPT connectors</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Custom</span><strong>getSession callback</strong><small class=\"diagram-muted\">Clerk &middot; Auth0 &middot; Firebase</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">AuthSession</span><small class=\"diagram-muted\">email &middot; orgId &middot; orgRole</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Request context &amp; data scoping</div></div>",
+  "css": ".auth-modes{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.auth-modes .diagram-col{display:flex;flex-direction:column;gap:10px}.auth-modes .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.auth-modes .diagram-arrow{font-size:22px;line-height:1}.auth-modes .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+ブラウザ フローはどこでも同じ Better Auth フローです。**開発認証バイパスはありません**。`getSession()` が `local@localhost` センチネルにフォールバックすることはありません。環境間で変わるのはサインアップの摩擦であり、ログインの壁ではありません:
+
+| 環境                | 初回読み込み時の動作                                                                   | メール認証                                                      |
+| ------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **ローカル開発**    | 使い捨て開発アカウントが自動的に作成され、サインインされます (ログインの壁なし)        | デフォルトでスキップされます (電子メールプロバイダーがない場合) |
+| **QA / プレビュー** | 通常のサインアップですが、テスターがメールを待つ必要がないように検証をスキップできます | `AUTH_SKIP_EMAIL_VERIFICATION=1` でスキップ                     |
+| **生産**            | 通常の Better Auth サインアップ/ログイン                                               | 必須（電子メールプロバイダーが設定されている場合）              |
+
+いくつかのフラグでこれを調整します。詳細は [Environment Variables](#environment-variables) テーブルにあります:
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` — 自動開発アカウントではなく、ローカル開発の通常のサインアップ ページを使用します。
+- `AUTH_DISABLED=true` — ログイン/サインアップを完全にスキップし、すべてのリクエストを 1 人の共有ユーザーとして実行します (ローカル開発/プレビュー/デモのみ。実際のユーザーによる運用は決して行わないでください)。
+- `AUTH_MODE=local` — CLI/エージェント ID (開発ユーザー `pnpm action` が実行される) にのみ影響します。これはブラウザのログイン バイパスではありません\*\*。
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`AUTH_DISABLED=true` runs **every request as one shared user**. Use it only for local dev, previews, or demos — never in production with real users, where it would expose all data to anyone."
+}
+```
+
+## より良い認証 (デフォルト) {#better-auth}
+
+デフォルトでは、Better Auth が認証を強化します。以下を提供します:
+
+- 電子メール/パスワードの登録とログイン
+- ソーシャル プロバイダー (Google、GitHub、その他 35 社以上)
+- 役割と招待状を持つ組織
+- API および A2A アクセス用の JWT トークン
+- プログラマティック クライアントのベアラー トークンのサポート
+
+Better Auth ルートは `/_agent-native/auth/ba/*` にマウントされます。このフレームワークは、下位互換性のあるエンドポイントも提供します。
+
+- `GET /_agent-native/auth/session` — 現在のセッションを取得
+- `POST /_agent-native/auth/login` — 電子メール/パスワードによるログイン
+- `POST /_agent-native/auth/register` — アカウントを作成
+- `POST /_agent-native/auth/logout` — サインアウト
+
+## クッキー レルム {#cookie-realms}
+
+セッション Cookie のレルムはデプロイメント形状に従います。そのため、
+データベース/オリジンは、分離されたままではないサインインとアプリを共有します:
+
+| 展開形状                                              | Cookie レルム                                                                                                                                |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| スタンドアロン アプリ                                 | スラッグ (`APP_NAME`、またはローカル開発のパッケージ名) によってアプリごとに分離されます。本番環境では安定した `an` プレフィックス           |
+| ワークスペース モード (`AGENT_NATIVE_WORKSPACE=1`)    | 1 つの共有レルム — ワークスペース アプリがオリジンとデータベースを共有する                                                                   |
+| カスタムの同じデータベースのサブドメイン              | `COOKIE_DOMAIN` で共有 Cookie をオプトインします                                                                                             |
+| ファーストパーティがホストする (`*.agent-native.com`) | アプリごとに分離された名前空間 (それぞれに独自の認証データベースがあります)。 `COOKIE_DOMAIN=.agent-native.com` はデフォルトでは無視されます |
+
+ファーストパーティがホストするアプリにはそれぞれ独自の認証データベースがあるため、クロスアプリ サインイン
+共有 Cookie ではなく [Cross-App SSO](/docs/cross-app-sso) を経由します。
+これらのデプロイでは、`APP_NAME` または派生可能なアプリ URL (`APP_URL`、`URL`) を提供する必要があります。
+`DEPLOY_PRIME_URL`、または `DEPLOY_URL`);そうしないと、落ちるのではなく起動が失敗します
+共有 `an_session` 名に戻ります。 1 つの認証データベースを意図的に共有する
+サブドメイン全体で、`AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` を横に設定します
+`COOKIE_DOMAIN`.
+
+## QA アカウント {#qa-accounts}
+
+ローカル開発とテストでは、デフォルトでサインアップ電子メールの検証がスキップされるため、
+受信トレイを待たずに実際の電子メール/パスワード アカウントを作成できます。強制する
+フローのテスト中にローカルで検証し、`AUTH_SKIP_EMAIL_VERIFICATION=0` を設定します。
+
+テスターが実際のアカウントを必要とするが、待つ必要がないホスト型 QA 環境の場合
+電子メール配信時に次のように設定します。
+
+```bash
+AUTH_SKIP_EMAIL_VERIFICATION=1
+```
+
+このフラグが設定されている場合、電子メール/パスワードによるサインアップに電子メールは必要ありません
+検証が行われ、サインアップ検証メールは送信されません。 QA のみに使用してください
+またはプレビュー環境で、`+qa` アドレスを持つテスト アカウントに名前を付けます
+(`name+qa@example.com`) なので、簡単に識別できます。
+
+## ソーシャル プロバイダー {#social-providers}
+
+ソーシャル ログインを有効にするために環境変数を設定します。 Better Auth はそれらを自動検出します:
+
+```bash
+# Google OAuth
+GOOGLE_SIGN_IN_CLIENT_ID=your-low-scope-sign-in-client-id
+GOOGLE_SIGN_IN_CLIENT_SECRET=your-low-scope-sign-in-client-secret
+
+# Backwards-compatible fallback, and provider OAuth credentials for templates
+# that connect to Google APIs such as Gmail or Calendar.
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+`createGoogleAuthPlugin()` を使用するテンプレートには、「Google でサインイン」ページが表示されます。 Google OAuth コールバックは、ネイティブ アプリのモバイル ディープ リンクを自動的に処理します。
+
+通常の場合は `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` を優先します
+アプリのログイン。そのクライアントは ID スコープのみを要求する必要があります。キープ
+必要な製品統合用の `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`
+Google API スコープ、またはデプロイが分割されていない場合の従来のフォールバックとして
+まだ。メールおよびカレンダー スタイルのアプリは、独自のプロバイダー OAuth クライアントを使用する必要があるため、
+広範な同意画面は汎用アプリのサインインには影響しません。
+
+### OAuth 状態署名 {#oauth-state-secret}
+
+本番環境では `OAUTH_STATE_SECRET` をランダムな 32 文字以上の文字値に設定し、OAuth 状態エンベロープ (Google、Atlassian、Zoom) がサードパーティの秘密から独立した専用キーで HMAC 署名されるようにします。完全な要件と脅威モデルについては、[Security — OAuth State Signing](/docs/security#oauth-state) を参照してください。
+
+## 組織 {#organizations}
+
+このフレームワークは、組み込みの組織システムを提供します。これは、`organizations` テーブルと `org_members` テーブルによってサポートされるフレームワーク独自の `org/` モジュールであり、意図的に登録されていない Better Auth の組織プラグインではありません。すべてのアプリは以下をサポートしています:
+
+- 組織の作成
+- ロール (`owner`、`admin`、`member`) を持つメンバーを招待
+- アクティブな組織の切り替え
+- `org_id` 列による組織ごとのデータスコープ
+
+アクティブな組織はセッション上で `session.orgId` として追跡され、組織を切り替えるとユーザーとエージェントに表示されるデータが変更されます。データ スコープ自体はスタックの下位で行われます。完全な `session.orgId → AGENT_ORG_ID → SQL` パイプラインとアクセス ガードについては、[Security & Data Scoping](/docs/security#data-scoping) を参照してください。 [Multi-Tenancy](/docs/multi-tenancy) ドキュメントでは、組織管理面について説明します。
+
+## 静的 MCP ベアラー トークン {#access-tokens}
+
+`ACCESS_TOKEN` と `ACCESS_TOKENS` はブラウザ認証ではないため、アプリを非公開にしません。これらは、OAuth フローを使用できない MCP/connect クライアントの静的ベアラー資格情報としてのみ残ります。
+
+```bash
+# Single token
+ACCESS_TOKEN=my-secret-token
+
+# Multiple tokens
+ACCESS_TOKENS=token1,token2,token3
+```
+
+これらの変数を構成しても、訪問者に対してトークン ログイン ページが表示されることはありません。 Web サインインは、Better Auth またはカスタム `getSession` プロバイダーに留まります。
+
+## リモート MCP OAuth {#remote-mcp-oauth}
+
+すべてのアプリの MCP エンドポイントは、標準の保護された MCP リソースとして機能できます。 OAuth 対応クライアントは、リモート MCP URL のみで構成できます:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+認証されていない MCP リクエストは、`/.well-known/oauth-protected-resource` を指す `WWW-Authenticate` チャレンジを返します。次に、クライアントはアプリの OAuth メタデータを検出し、パブリック クライアントを動的に登録し、アプリの認証ページを開き、アクセス トークンとリフレッシュ トークンのために認証コードを PKCE と交換します。
+
+```an-diagram title="Remote MCP OAuth handshake" summary="An OAuth-capable client bootstraps from just the MCP URL — challenge, discovery, dynamic registration, then a PKCE code exchange."
+{
+  "html": "<div class=\"mcp-flow\"><div class=\"diagram-node\">1 &middot; MCP request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node warn\">2 &middot; 401 challenge<br><small class=\"diagram-muted\">WWW-Authenticate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">3 &middot; Discover metadata<br><small class=\"diagram-muted\">.well-known</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">4 &middot; Register client<br><small class=\"diagram-muted\">dynamic, public</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">5 &middot; Authorize + PKCE<br><small class=\"diagram-muted\">code exchange</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">6 &middot; Access + refresh<br><small class=\"diagram-muted\">audience-bound</small></div></div>",
+  "css": ".mcp-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.mcp-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.mcp-flow .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+アクセス トークンは、設定されている場合は `A2A_SECRET` で署名され、それ以外の場合は `BETTER_AUTH_SECRET` で署名されます。これらは、署名されたユーザー/組織 ID と `mcp:read`、`mcp:write`、および/または `mcp:apps` スコープを保持し、正確な MCP リソース URL にオーディエンス バインドされています。リフレッシュ トークンはハッシュとしてのみ保存され、リフレッシュのたびにローテーションされます。ツール呼び出しと MCP アプリ リソースの読み取りは、サインインしているユーザーと同じ要求コンテキスト内で実行されます。埋め込まれた MCP アプリ iframe は、生の OAuth トークンを受信しません。
+
+`npx @agent-native/core@latest connect <url> --client claude-code` は、この標準フローの URL 専用の MCP エントリを書き込みます。リモート MCP OAuth を実行できないクライアントの場合は、接続ページまたは `npx @agent-native/core@latest connect --token <token>` フォールバックを使用して、明示的なベアラー トークン エントリを書き込みます。
+
+## 独自の認証を使用する {#byoa}
+
+カスタム `getSession` コールバックを渡して、任意の認証プロバイダー (Clerk、Auth0、Firebase など) を使用します。
+
+```ts
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## パブリック ワークスペース アプリ {#public-workspace-apps}
+
+ワークスペース アプリはデフォルトで内部にあります。匿名の訪問者がパブリックをロードできるようにするには
+サイトは管理ページを認証のままにし、ルート アクセスを宣言します
+`apps/<id>/package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+逆の形状の場合は、デフォルトの内部対象ユーザーを維持し、公開のみを行います
+特定の公開ページ:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+`publicPaths` と `protectedPaths` はプレフィックス マッチングを使用するため、`"/admin"` も使用します
+は `"/admin/users"` をカバーします。これらの設定では、ページ ナビゲーションのみが開きます。フレームワーク
+ルート (`/_agent-native/*`) とカスタム API ルート (`/api/*`) には引き続き認証が必要です
+アプリがこれらのプレフィックスを明示的に追加しない限り
+`createAuthPlugin({ publicPaths: [...] })`.
+
+## セッション API {#session-api}
+
+`getSession(event)` によって返されるセッション オブジェクトの形状は次のとおりです:
+
+```ts
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+クライアントで、`useSession()` フックを使用します。
+
+```ts
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## Return URL でサインイン {#sign-in-return-url}
+
+**公開ページ** (共有リンク、埋め込み、マーケティング ページ) を含むテンプレートには、多くの場合、匿名の閲覧者にサインインを求め、元のページに戻すページ内 CTA が必要です。フレームワークは、このための単一のエントリ ポイントを提供します。
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+匿名のビューアがこの URL にアクセスすると、フレームワークのログイン ページが表示されます。サインインが成功すると (トークン、電子メール/パスワード、Google OAuth などの任意のフロー)、ビューアは `return` に 302 されます。
+
+`return` パラメータは **同一オリジン パス**として検証されます。ネットワーク パス参照 (`//evil.com/...`)、絶対 URL、`data:` / `javascript:` スキーム、および埋め込み制御文字はすべて `/` にフォールバックします。検証されたパスは、入力からエコーバックされるのではなく、URL パーサーから再構築されます。
+
+**React コンポーネントから:**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### ブックマークされたプライベート パス
+
+匿名ユーザーが `/dashboard` のようなプライベート パスに直接移動すると、フレームワークはすでに URL でログイン ページを提供します。サインインに成功すると、ページがリロードされ、ユーザーは `/dashboard` に移動します。特別な処理は必要ありません。これは、トークン、メール/パスワード、**、および** Google OAuth に対して機能します。
+
+### 舞台裏: Google OAuth
+
+両方のフロー (明示的な `/_agent-native/sign-in` エントリポイントとブックマークされたパスのケース) は、OAuth 状態を通じてリターン URL をスレッド化します。状態はHMAC署名されているため、輸送中に偽造することはできません。コールバックでは、戻り値 URL はリダイレクトの前に同一オリジンとして再検証されます。そのため、漏洩した署名キーをオープン リダイレクト オラクルに変えることはできません。
+
+テンプレートが `/_agent-native/google/auth-url` を直接ラップする場合 (例: 範囲を広げるためにメール テンプレートやカレンダー テンプレートがラップする場合)、`?return=<path>` クエリを受け入れ、`encodeOAuthState` のオプション オブジェクト形式を介して転送します。
+
+```ts
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState({
+  redirectUri,
+  desktop,
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
+```
+
+デフォルトの `/_agent-native/google/auth-url` ルートはこれを自動的に行います。テンプレートでカスタム OAuth 処理が必要な場合にのみオーバーライドされます。
+
+## 環境変数 {#environment-variables}
+
+| 変数                                    | 目的                                                                                                                                                                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BETTER_AUTH_SECRET`                    | Better Auth 用の署名キー (設定されていない場合は自動生成されます)                                                                                                                                                  |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | QA/プレビュー環境で `1` に設定すると、電子メール/パスワードのサインアップが検証なしで続行できるようになります。ローカルの開発/テストはデフォルトでスキップされます                                                 |
+| `AUTH_DISABLED`                         | ログイン/サインアップをスキップするには、`true` または `1` に設定します。すべてのリクエストは 1 人の共有ユーザーとして実行されます (ローカルの開発/プレビューのみ。実際のユーザーによる本番環境では使用できません) |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | 新しい開発データベースでローカルホストの自動サインインを無効にするには、`1` に設定します                                                                                                                           |
+| `AUTH_MODE`                             | `local` は、CLI/エージェント ID のみを解決します (開発ユーザー `pnpm action` が実行される)。ブラウザのログインをバイパスしない                                                                                     |
+| `COOKIE_DOMAIN`                         | 同じデータベースのサブドメイン間で共有セッション Cookie をオプトインします ([Cookie Realms](#cookie-realms) を参照)                                                                                                |
+| `AGENT_NATIVE_WORKSPACE`                | `1` はワークスペース モードで実行されます。ワークスペース アプリ間で 1 つの共有セッション レルム                                                                                                                   |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | ファーストパーティのサブドメイン間で 1 つの認証データベースを共有するには、`COOKIE_DOMAIN` で設定します                                                                                                            |
+| `OAUTH_STATE_SECRET`                    | OAuth 状態エンベロープ用の専用 HMAC キー ([Security — OAuth State Signing](/docs/security#oauth-state) を参照)                                                                                                     |
+| `GOOGLE_SIGN_IN_CLIENT_ID`              | アプリログインに優先される低スコープの Google OAuth クライアント ID                                                                                                                                                |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET`          | アプリログイン用に優先される低スコープの Google OAuth シークレット                                                                                                                                                 |
+| `GOOGLE_CLIENT_ID`                      | 従来の Google ログイン フォールバック、および Google API 統合用のプロバイダー OAuth クライアント ID                                                                                                                |
+| `GOOGLE_CLIENT_SECRET`                  | 従来の Google ログイン フォールバック、および Google API 統合用のプロバイダ OAuth シークレット                                                                                                                     |
+| `GITHUB_CLIENT_ID`                      | GitHub OAuth を有効にする                                                                                                                                                                                          |
+| `GITHUB_CLIENT_SECRET`                  | GitHub OAuth シークレット                                                                                                                                                                                          |
+| `ACCESS_TOKEN`                          | MCP/connect クライアントの静的ベアラー フォールバック。ブラウザ認証ではありません                                                                                                                                  |
+| `ACCESS_TOKENS`                         | MCP/connect クライアントのカンマ区切りの静的ベアラー フォールバック。ブラウザ認証ではありません                                                                                                                    |
+| `A2A_SECRET`                            | JWT 署名付き A2A クロスアプリ ID 検証用の共有シークレット、および存在する場合は MCP OAuth アクセス トークン署名                                                                                                    |

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

@@ -0,0 +1,268 @@
+---
+title: "自動化"
+description: "自然言語条件を使用したイベントトリガーおよびスケジュールされた自動化"
+---
+
+# 自動化
+
+**自動化** は、自然言語で記述されたルールです: _X が発生したら Y を実行します_。エージェントが指示を実行するため、オートメーションはエージェントが対話型チャットで使用できるすべてのアクション、ツール、MCP サーバーにアクセスできます。
+
+オートメーションは、`web-request` ツールを介して **イベント トリガー**、**自然言語条件**、**アウトバウンド HTTP** を使用して [recurring jobs](/docs/recurring-jobs) を拡張します。これらは、定期的なジョブとして同じ `jobs/<name>.md` ファイル形式、ストレージ、および「3 つの方法を作成」ワークフローを使用します。共有形式については、[Recurring Jobs](/docs/recurring-jobs#job-file) を参照してください。このページでは、イベント ドリブン オートメーションの新機能のみを説明します。
+
+```an-diagram title="When X happens, do Y" summary="An event fires on the bus, an optional natural-language condition gates it, and the agent runs the automation body with full tool access."
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">Agent runs the body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## 2 つのトリガー タイプ {#trigger-types}
+
+| タイプ     | 次の場合に起動                                                 | キーフィールド      |
+| ---------- | -------------------------------------------------------------- | ------------------- |
+| `schedule` | cron 式が一致する (定期的なジョブと同じ)                       | `schedule` (クロン) |
+| `event`    | 一致するイベントがフレームワーク イベント バス上に出力されます | `event` (名前)      |
+
+イベント トリガーには、ディスパッチ前にイベント ペイロードに対して Haiku によって評価される自然言語文字列である `condition` を含めることができます。条件が一致しない場合、自動化は通知なくスキップされます。
+
+## オートメーションの作成 {#creating}
+
+### エージェントに問い合わせる
+
+> 「誰かが @builder.io メールで会議を予約したら、Slack でメッセージを送ってください。」
+
+エージェントは利用可能なイベントを検出し、計画を確認し、自動化を作成します。
+
+### 設定 UI から
+
+オートメーションが設定パネルに表示されます。ユーザーはそこでそれらを表示、有効化/無効化、削除できます。
+
+3 番目のパス (`resourcePut` 経由で `jobs/<name>.md` ファイルを手動で書き込む) は、[recurring jobs](/docs/recurring-jobs#creating) の場合とまったく同じように機能します。イベント駆動型オートメーションの場合は、以下のイベント トリガー フロントマターを同じファイルに追加します。イベントトリガージョブは、`schedule: ""` を設定し、`triggerType: event`、`event` 名、およびオプションの `condition` を提供します。
+
+```an-annotated-code title="An event-triggered automation"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "No cron", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "The trigger", "note": "`triggerType: event` plus the `event` name subscribes this automation to the bus." },
+    { "lines": "6", "label": "Gate", "note": "An optional natural-language `condition`, evaluated by Haiku against the payload before dispatch." },
+    { "lines": "12", "label": "Server-side secret", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## 自動化の最前線 {#frontmatter}
+
+オートメーションは、[recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter) のすべてのフィールドを共有します。これらの追加フィールドは、イベント トリガー、条件、実行モードを制御します。
+
+| フィールド    | タイプ                           | デフォルト     | 説明                                                                                                                                                                                                                |
+| ------------- | -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"`   | オートメーションの起動方法                                                                                                                                                                                          |
+| `event`       | 文字列                           | _(オプション)_ | サブスクライブするイベント名 (イベント トリガーのみ)                                                                                                                                                                |
+| `condition`   | 文字列                           | _(オプション)_ | 発送前に評価される自然言語条件                                                                                                                                                                                      |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`    | 完全なエージェント ループ。 (`"deterministic"` は予約されていますが、まだ実装されていません。これを設定するオートメーションはスキップされます。現在のすべてのオートメーションには `"agentic"` を使用してください。) |
+| `domain`      | 文字列                           | _(オプション)_ | グループ化タグ (メール、カレンダー、クリップなど)                                                                                                                                                                   |
+
+イベント トリガーの場合、`schedule` は `""` (空) です。スケジュール トリガーの場合は cron 式が含まれます。ディスパッチャは、スケジューラと同じ管理対象 `lastRun` / `lastStatus` / `lastError` フィールドに加えて、条件が false と評価された場合の `"skipped"` ステータスも書き込みます。
+
+## イベントバス {#event-bus}
+
+統合はモジュールのロード時にイベントを登録します。バスはペイロードを [Standard Schema](https://standardschema.dev) 定義と照合して検証し、サブスクライバにディスパッチします。
+
+### 組み込みイベント {#built-in-events}
+
+| イベント               | ソース                                                  |
+| ---------------------- | ------------------------------------------------------- |
+| `test.event.fired`     | マニュアル / `manage-automations` アクション=火災テスト |
+| `agent.turn.completed` | エージェントチャット                                    |
+| `calendar.*`           | カレンダーの統合                                        |
+| `clip.*`               | クリップの統合                                          |
+| `mail.*`               | メールの統合                                            |
+
+エージェントから `action=list-events` を使用して `manage-automations` を呼び出し、現在のテンプレートの説明とペイロード スキーマを含むすべての登録済みイベントを表示します。
+
+### カスタム イベントの発行 {#emitting-events}
+
+サーバー プラグインにイベント タイプを登録し、それを actions または Webhook ハンドラーから発行します。
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+オートメーションが起動する出力メタデータ スコープ内の `owner` は、同じユーザーが所有するオートメーション (または共有オートメーション) のみが評価されます。
+
+## 条件 {#conditions}
+
+条件は、イベント ペイロードに対して Claude Haiku によって評価される自然言語文字列です。これは、はい/いいえの分類であり、生成タスクではありません。
+
+- **条件が空または欠落している** = 無条件 (常に起動)。
+- 結果は、5 分間の TTL キャッシュと 500 エントリの LRU キャッシュを使用してメモ化されます (条件 + ペイロードの SHA-256)。
+- ペイロードは Haiku に送信する前に 4000 文字に切り詰められます。
+- API 障害の場合、条件は `false` と評価されます (安全なデフォルト - 自動化はスキップされます)。
+
+条件の例:
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## Web リクエスト ツール {#web-request}
+
+オートメーションは、アウトバウンド HTTP に `web-request` ツールを使用します。 URL、ヘッダー、本文の `${keys.NAME}` プレースホルダーをサポートします。
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+プレースホルダーは、エージェントがツール呼び出しを発行した後、**サーバー側**で解決されます。生のシークレット値がエージェントのコンテキストに入ることはありません。
+
+### パラメータ {#web-request-params}
+
+| パラメータ   | タイプ | デフォルト | 説明                                                                     |
+| ------------ | ------ | ---------- | ------------------------------------------------------------------------ |
+| `url`        | 文字列 | —          | 完全な URL。 `${keys.NAME}` 参照が含まれる可能性があります。             |
+| `method`     | 文字列 | `GET`      | HTTP メソッド (GET、POST、PUT、PATCH、DELETE、HEAD)。                    |
+| `headers`    | 文字列 | `{}`       | ヘッダーの JSON オブジェクト。 `${keys.NAME}` が含まれる場合があります。 |
+| `body`       | 文字列 | —          | リクエストの本文。 `${keys.NAME}` が含まれる場合があります。             |
+| `timeout_ms` | 数値   | 15000      | ミリ秒単位のタイムアウト (最大 30000)。                                  |
+
+## キー {#keys}
+
+キーは、自動化に使用するためにユーザーまたはエージェントによって作成されるアドホック シークレットです (例: `SLACK_WEBHOOK`、`HUBSPOT_API_KEY`)。テンプレート定義のメタデータやオンボーディング手順がないという点で、登録済みシークレット (`registerRequiredSecret`) とは異なります。
+
+- 設定 UI または `/_agent-native/secrets/adhoc` API によって作成されます。
+- 各キーには、キーを送信できるオリジンを制限する **URL ホワイトリスト** を含めることができます (オリジン レベルの照合)。
+- 生の値が AI に公開されることはありません。エージェントのコンテキストには `${keys.NAME}` プレースホルダーのみが表示されます。
+- 解決はユーザー スコープからワークスペース スコープにフォールバックするため、ユーザーは共有キーをオーバーライドできます。
+
+## エージェント ツール {#agent-tools}
+
+すべての自動化操作は、`action` パラメータを使用した単一の `manage-automations` ツールを通じてアクセスされます。
+
+| アクション    | 目的                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `list-events` | 説明とペイロード スキーマを含むすべての登録済みイベントを検出します                              |
+| `list`        | すべてのオートメーションをステータスとともにリストします。ドメインまたは有効によるフィルタリング |
+| `define`      | 新しいオートメーションを作成します (名前、トリガー タイプ、イベント、条件、本文)                 |
+| `update`      | 既存のオートメーションを更新します (有効、条件、本文)                                            |
+| `delete`      | オートメーションを削除します (常に最初にユーザーに確認します)                                    |
+| `fire-test`   | `test.event.fired` イベントを発行して自動化を検証する                                            |
+
+追加ツール: `web-request` — `${keys.NAME}` 置換を使用したアウトバウンド HTTP。
+
+## API エンドポイント {#api}
+
+| エンドポイント                         | メソッド | 説明                                              |
+| -------------------------------------- | -------- | ------------------------------------------------- |
+| `/_agent-native/automations`           | GET      | すべてのオートメーションをリストします (解析済み) |
+| `/_agent-native/automations/fire-test` | POST     | `test.event.fired` イベントを発行する             |
+| `/_agent-native/secrets/adhoc`         | GET      | アドホック キーのリスト (値なし)                  |
+| `/_agent-native/secrets/adhoc`         | POST     | アドホック キーを作成または更新する               |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE   | アドホック キーを削除する                         |
+
+```an-api title="Fire a test event"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "Emit a test.event.fired event to validate event-triggered automations",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## 派遣の仕組み {#dispatch}
+
+```an-diagram title="The dispatch path" summary="From a fired event to a completed agent run, gated by ownership scope and the natural-language condition."
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> with body as prompt, payload as context, 5-min timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## 例 {#example}
+
+**ユーザー:** 「誰かが @builder.io メールで予約したら、Slack でメッセージを送ってください。」
+
+**エージェント フロー:**
+
+1. `action=list-events` を使用して `manage-automations` を呼び出します — `calendar.booking.created` を見つけます。
+2. ユーザーに計画を確認します。
+3. `action=define` を使用して `manage-automations` を呼び出します:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. オートメーションは `jobs/slack-on-builder-booking.md` として保存され、すぐにリスニングを開始します。
+
+## その他の例 {#more-examples}
+
+### プランがコメントされたときに Webhook 経由で通知する
+
+プラン エージェントに尋ねます: _「誰かがプランに人間のコメントを追加すると、POST となります
+Web フックへの通知。"_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+`NOTIFY_WEBHOOK` を任意の HTTP エンドポイント (汎用の Slack 受信 Webhook) に設定します
+通知サービス、またはカスタム レシーバー。 `web-request` ツールは
+`${keys.NOTIFY_WEBHOOK}` サーバー側。生の URL はエージェントの
+コンテキスト。 [Visual Plans — Events and notifications](/docs/template-plan#events)
+完全な `plan.commented` ペイロード リファレンスと 4 つのプラン イベントすべてについて。
+
+## 次は何ですか
+
+- [**Recurring Jobs**](/docs/recurring-jobs) — スケジュールでトリガーされるオートメーションは同じスケジューラーを再利用します
+- [**Actions**](/docs/actions) — オートメーションはエージェント ループ経由で登録されたアクションを呼び出すことができます
+- [**Security**](/docs/security) — 入力検証とシークレット処理
+- [**Visual Plans — Events**](/docs/template-plan#events) — 計画イベントのリファレンスと自動化レシピ