@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "インループ プロセッサ"
+description: "ループ内部のオブザーバー/ガードレール フックは、モデルのストリーミング出力を監視し、実行中にツール呼び出しを中止することができます。これは、リアルタイム ガードレールと Proof-of-Done ゲートの継ぎ目です。"
+---
+
+# インループ プロセッサ
+
+`Processor` は、エージェント実行のためのループ内部 **オブザーバー/ガードレール** です。モデルのストリーミング出力を監視し、ツールは実行の進行に応じてリクエストを呼び出し、独自のスクラッチ状態を維持し、「完了」が要求される前に実行を**中止**できます。これは、リアルタイム ガードレール (許可されていない出力を途中でブロックする) と、Proof-of-Done/カバレッジ ゲート (モデルが実行しようとしていることを検査して停止する) の構造的な前提条件です。
+
+```an-diagram title="Where the three hooks fire in the run" summary="processOutputStream watches every chunk, processOutputStep gates tool calls per response, processOutputResult records a verdict at the end. Any hook can abort with a TripWire."
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — gate tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — verdict</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> プロセッサは **構成** であり、ツール、アクション、オーサリング DSL ではありません。プロセッサーは、自身のストリームスコープの状態、および `abort()` のみを観察し、変更します。これらは、アプリの動作を定義したり、actions を置き換えたり、モデルに表示されることはありません。アプリの操作は [actions](/docs/actions) に属します。
+
+## フック {#hooks}
+
+プロセッサは、3 つのオプションのライフサイクル フックのサブセットを実装します (形状は Mastra の出力プロセッサから借用されています)。
+
+| フック                | 火災…                                                                    | これを使用して…                                                    |
+| --------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `processOutputStream` | モデルの生成中にストリーミングされたチャンクごと (テキスト / 思考デルタ) | フルターンが着地する前に出力に反応する                             |
+| `processOutputStep`   | ツールの実行時に、モデルの応答ごとに 1 回                                | モデルが実行しようとしているツール呼び出しを検査します。門を閉める |
+| `processOutputResult` | 実行終了時に 1 回、最終アシスタント テキスト付き                         | 完成した回答に対する評決/完了証明を記録する                        |
+
+各プロセッサは、単一の実行内のすべてのフック呼び出しにわたって永続化し、他のプロセッサの状態から**分離**される、独自の変更可能な実行スコープの `state` オブジェクトを取得します。
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## `TripWire` で中止します {#tripwire}
+
+フックは `abort(reason, meta?)` を呼び出して実行を停止し、**`TripWire`** をスローします。ループはそれをキャッチし、単一の **`tripwire` イベント**を発行し、きれいに停止し、最終アシスタント メッセージとして理由を表示します。
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+`tripwire` イベントの内容:
+
+| フィールド  | タイプ   | メモ                                                |
+| ----------- | -------- | --------------------------------------------------- |
+| `reason`    | `string` | 人間が判読できる理由が `abort` に渡されました。     |
+| `processor` | `string` | `name` を宣言したときに中止されたプロセッサの名前。 |
+
+`TripWire` は、オプションの構造化 `meta` と、`instanceof` チェックするプログラム コンシューマーの元の `processor` 名も保持します。停止は正常に行われるため、`processOutputResult` は (停止された) 最終テキストに対して引き続き起動されるため、実行が中止された場合でも、proof-of-done プロセッサはその判定を記録できます。
+
+## 配線プロセッサ {#wiring}
+
+プロセッサは、`runAgentLoop` 上の `processors` アレイを介してコードで構成されます。
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**未使用時はオーバーヘッドゼロ。** ループは、少なくとも 1 つのプロセッサが提供されている場合にのみプロセッサ チェーンを構築します。 `processors` が省略されるか空の場合、シーム コードは実行されず、ループはバイトごとに変更されません。フックは登録順に実行され、同期または非同期の場合があります。
+
+> [!NOTE]
+> ループレベルのシームは今日の成果物であり、サブエージェント、A2A、MCP、およびテストによって直接呼び出すことができます。 HTTP チャット ハンドラーを介して `processors` をスレッドする (したがって、リクエストごとのリゾルバーが `runAgentLoop` を直接呼び出さずにそれらを構成できる) のは、まだ配線されていない便利な配管です。現時点では、`runAgentLoop` 呼び出しサイトでプロセッサーを構成します。
+
+## 関連
+
+- [**Durable Resume**](/docs/durable-resume) — 完了した副作用を再実行せずにループが中断に耐える方法。
+- [**Custom Agents & Teams**](/docs/agent-teams) — サブエージェントは同じループを実行し、独自のプロセッサを搭載できます。
+- [**Observability**](/docs/observability) — 実行トレースとともにプロセッサーの判定を記録します。

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

@@ -0,0 +1,199 @@
+---
+title: "進捗状況"
+description: "長時間実行されるエージェント タスクのライブ進行状況シグナル - 開始、更新、完了"
+---
+
+# 進捗状況
+
+長いエージェント タスクはスピナーの後ろに隠れてはいけません。 `progress_runs` は、エージェントに _「これに取り組んでいます。45% 完了しました。現在のステップは次のとおりです」_ とアナウンスする方法を提供します。これは、UI がパーセント バー付きのフローティング ラン トレイとしてレンダリングします。
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+[notifications](/docs/notifications) とは別の懸念事項: 通知は 1 回発生し (_「X が発生しました」_)、進行状況は継続的な状態です (_「X は 45% 完了しました」_)。この 2 つは構成されます。`completeRun` とそれに続く `notify(..., severity: "info")` は、ユーザーがトレイを見ていなくても、作業がいつ終了したかをユーザーに知らせます。
+
+## ライフサイクル {#lifecycle}
+
+| ステータス  | 移行                             |
+| ----------- | -------------------------------- |
+| `running`   | 初期値 — `startRun` によって設定 |
+| `succeeded` | ハッピーパスターミナル           |
+| `failed`    | エラー端子                       |
+| `cancelled` | ユーザーが中断しました           |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+端末ステータスは `completed_at` に設定されます。 UI トレイには `running` 行のみが表示されます。完了した行は、`action=list` クエリのためにデータベースに残ります。
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+実行を作成します。生成された ID を含む完全な `AgentRun` を返します。
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+イベント バス上で `run.progress.started` を発行します。
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+実行中の run のフィールドにパッチを適用します。省略されたフィールドは変更されません。
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+イベント バス上で `run.progress.updated` を発行します。更新された `AgentRun` を返します。実行が存在しない場合、または呼び出し元が所有していない場合は `null` を返します。
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+ターミナルステータスに遷移します。 `succeeded` は暗黙的に `percent=100` を設定します。
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+端末ステータスとともに `run.progress.updated` も出力します。
+
+### リスト {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+core-routes プラグインによって `/_agent-native/runs/*` にマウントされます。 **HTTP では読み取り専用** — エージェントが正規のライターであるため、書き込みはエージェント ツールを経由します。すべてのルートは所有者スコープです。
+
+| メソッド | パス                              |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## UIコンポーネント {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+インライン ヘッダー ウィジェット — 通知ベルの隣に取り付けます。実行がアクティブな場合は、スピナー アイコン + カウント バッジが表示されます。クリックすると、実行ごとに 1 つのライブ パーセント バーが表示されるドロップダウンが開きます。アクティブな実行がない場合はトリガーを完全に非表示にします。 `pollMs` ごとに `/_agent-native/runs?active=true` をポーリングします (デフォルトは 3 秒)。 shadcn セマンティック トークンを使用し、明るいテーマと暗いテーマに適応します。
+
+## エージェント ツール {#agent-tool}
+
+すべてのテンプレートに 1 つの `manage-progress` ツールが登録されます。 `action` パラメータは操作を選択します:
+
+| アクション | 目的                                                               |
+| ---------- | ------------------------------------------------------------------ |
+| `start`    | 長いタスクの先頭で呼び出します。 runId を返します。                |
+| `update`   | タスク中に `percent` および/または `step` を定期的に呼び出します。 |
+| `complete` | ターミナル — `succeeded`、`failed`、`cancelled` のいずれか。       |
+| `list`     | 最近の実行を検査します (`active=true` でフィルタリングします)。    |
+
+### いつランニングを開始するか {#when-to-start}
+
+- ~5 秒以上の何かに使用します。文脈のないスピナーは固まったように感じます。
+- 反復ごとではなく、自然なチェックポイントで更新します。 5 ～ 10% ごとに十分です。
+- **常に** `manage-progress` を `action=complete` とともに呼び出します (エラー パスも含む)。孤立した `running` 行は、行がないよりも悪いです。
+- 完了時に `notify` とペアリングすると、ユーザーがトレイをアクティブに監視していないときに結果が表示されます。
+
+## イベントバス {#event-bus}
+
+[event bus](/docs/automations#event-bus) で 2 つのイベントが発行されます:
+
+| イベント               | ペイロード                         |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) はこれらをサブスクライブできます。たとえば、_「実行に 5 分以上かかる場合は通知してください」_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## 仕組み {#internals}
+
+- **所有者のスコープ** — すべての行に `owner` 列があります。すべてのクエリはそれをフィルターに掛けます。ユーザーには自分の実行のみが表示されます。
+- **ポーリング統合** — すべてのミューテーションが `recordChange()` を呼び出すため、[`useDbSync`](/docs/client) を使用するテンプレートは追加の配線なしで自動無効化されます。
+- **テーブル名** — フレームワークには、内部エージェント チャット ターン ライフサイクル追跡用の `agent_runs` テーブルもあります。進行状況プリミティブは、`progress_runs` を使用して 2 つの懸念事項を分離します。
+- **パーセント クランプ** — 値は `[0, 100]` にクランプされ、書き込み時に整数に丸められます。
+
+## 次は何ですか
+
+- [**Notifications**](/docs/notifications) — `manage-progress` (`action=complete`) と組み合わせて、作業の終了をユーザーに通知します
+- [**Automations**](/docs/automations) — `run.progress.updated` 経由でウォッチドッグが低速で実行されます
+- [**Client**](/docs/client) — リアルタイム キャッシュ無効化の場合は `useDbSync`

package/corpus/core/docs/content/locales/ja-JP/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "純粋なエージェント アプリ"
+description: "エージェントが製品全体であるアプリ: アプリとエージェントのループが玄関口であり、UI は人間が必要とする場合にのみ追加されます。"
+---
+
+# 純粋なエージェント アプリ
+
+純粋なエージェント アプリは、エージェント ネイティブの最小限の終端です。アプリとエージェントのループは、
+製品であり、ダッシュボードではありません。端末 Slack、電子メール、
+スケジュールされたジョブ、別のエージェント、またはチャット — 「未読メールの要約」、「投稿」
+毎日のメトリクスを Slack に送信します。エージェントはどこにいても動作し、結果を返します。
+に属します。これはまだ実際のアプリです: actions、セッション、アプリの状態、履歴
+設定、認証情報、共有レコードはすべて SQL に保存されます。
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+作業がバックグラウンドで実行されているときにこの形状に到達すると、出力が残ります
+アプリ、ドメインはワンショットであるか、プロトタイピング中です。エージェントには依然として UI が必要です —
+ダッシュボードではなく、人間が管理、設定、操作するための場所です —
+これが、純粋なエージェント アプリでも通常、組み込みのチャット シェルをマウントする理由です。
+
+これは **ヘッドレス** 製品形状です。完全な意思決定ガイド、同梱物
+ボックス、スキャフォールド、リポジトリへのアクセス、および実行共有が 1 か所に存在するようになりました:
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## 次は何ですか
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — 完全なヘッドレス意思決定ガイドと API
+- [**Getting Started**](/docs/getting-started) — まずチャット アプリまたはヘッドレス エージェントを作成します
+- [**Dispatch**](/docs/template-dispatch) — 純粋なエージェントの優れた出発点となるワークスペース テンプレート
+- [**Messaging the agent**](/docs/messaging) — ユーザーがウェブ、Slack、電報、電子メールでエージェントと会話する方法
+- [**Recurring Jobs**](/docs/recurring-jobs) — エージェントが独自に実行するスケジュールされたプロンプト
+- [**Actions**](/docs/actions) — 純粋なエージェントが呼び出すツール