@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "Harness-Agenten"
+description: "Führen Sie Claude Code, Codex, Pi und andere vollständige Codierungssysteme als eingebettete Agenten in Agent-Native aus, mit eigener Schleife, Sandbox, nativen Tools und wiederaufnehmbaren, von SQL unterstützten Sitzungen."
+search: "Harness Agents AgentHarness ai-sdk HarnessAgent Claude Code Codex Pi Cursor Mastra eingebetteter Codierungsagent discoverAgentHarness startAgentHarnessRun fortsetzbare Sitzungs-Sandbox-Host-Tools"
+---
+
+# Harness-Agenten
+
+> **Für wen ist das gedacht:** Host-Autoren, die eine vollständige Coding-Laufzeit verkabeln (Claude-Code,
+> Codex, Pi) als Agent in Agent-Native ein. Eine App erstellen? Beginnen Sie mit
+> [Creating Templates](/docs/creating-templates).
+
+Ein Harness-Agent ist eine vollständige Agentenlaufzeit – Claude-Code, Codex, Pi und ähnliches –
+das über eine eigene Schleife, einen eigenen Arbeitsbereich, native Dateitools, einen eigenen Sitzungsstatus und eine eigene Komprimierung verfügt
+Genehmigungsmodell und Sandbox-Verhalten. Agent-Native führt diese über den
+**`AgentHarness`** Substrat in `@agent-native/core/agent/harness`, streamt ihre
+Ereignisse in das normale Transkript und behält ihre native Sitzung als Thread bei
+kann pausieren und fortsetzen.
+
+Dies unterscheidet sich vom integrierten Chat-Agenten und vom Mitbringen Ihres eigenen Chats
+Laufzeit. Der integrierte Agent und `AgentEngine` sind für einen Modell-Roundtrip
+unter `runAgentLoop`. Ein Kabelbaum ist kein `AgentEngine`-Anbieter – er betreibt seinen
+Eigene End-to-End-Schleife, daher fährt Agent-Native sie als Sitzung und nicht als einzelne
+Modellaufruf.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Welches Codierungsdokument möchte ich? {#which-doc}
+
+| Sie möchten…                                                                       | Verwenden                                    |
+| ---------------------------------------------------------------------------------- | -------------------------------------------- |
+| Führen Sie Claude Code / Codex / Pi **als Agent** mit eigener Schleife + Tools aus | **Harness-Agenten** (diese Seite)            |
+| Rendern Sie einen **Codierungsarbeitsbereich UI** im Claude-Code/Codex-Stil        | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Tausch das Backend, das das **`run-code`-Tool** des Agenten ausführt               | [Adapters](/docs/sandbox-adapters)           |
+| Verpacken Sie ein CLI-Tool (`gh`, `ffmpeg`), damit der Agent anrufen kann          | [Adapters](/docs/sandbox-adapters)           |
+
+Angrenzende Oberflächen: Platzieren Sie einen Agenten, den Sie an anderer Stelle erstellt haben, hinter dem Chat von Agent-Native
+UI mit [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); lass ein
+externer MCP-Hostaufruf in Ihre App über [External Agents](/docs/external-agents);
+Spawn-Hintergrund/Subagent läuft mit [Custom Agents & Teams](/docs/agent-teams).
+
+## Eingebaute Gurte {#built-in}
+
+`registerBuiltinAgentHarnesses()` registriert drei Adapter, die von der AI SDK unterstützt werden
+`HarnessAgent`:
+
+| Name                         | Laufzeit    | Sandbox | Genehmigungen |
+| ---------------------------- | ----------- | ------- | ------------- |
+| `ai-sdk-harness:claude-code` | Claude-Code | Ja      | Ja            |
+| `ai-sdk-harness:codex`       | Codex       | Ja      | nein          |
+| `ai-sdk-harness:pi`          | Pi          | nein    | Ja            |
+
+Ihre Laufzeitpakete sind **optionale Peer-Abhängigkeiten** und werden träge geladen, also ein
+Apps, die niemals ein Geschirr verwenden, zahlen nicht dafür. Jeder Adapter trägt eine
+`installPackage`-Hinweis (zum Beispiel „@ai-sdk/harness@canary“
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness`löst eine klare Installation aus
+Fehler, wenn die Pakete fehlen, und`isAgentHarnessPackageInstalled(entry)`
+ermöglicht es Ihnen, zuerst zu prüfen.
+
+`registerBuiltinAgentHarnesses()` registriert auch die [ACP](#acp)-Kabelbäume
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## ACP-Agenten {#acp}
+
+Agent-Native kann als [ACP](https://agentclientprotocol.com) (Agent Client) fungieren
+Protokoll) **Client** und steuern Sie einen lokalen Codierungsagenten – Gemini CLI, Claude Code,
+oder ein beliebiger ACP-kompatibler Agent – über dasselbe Substrat. Der Agent wird als
+lokaler Unterprozess, der durch Zeilenumbrüche getrennte JSON-RPC über stdio spricht; Editor von ACP
+↔ Agentenmodell hat genau diese Form.
+
+Dieser Adapter ist auf **lokale Codierung** ausgelegt. Der untergeordnete Prozess erbt die
+übergeordnete Umgebung, sodass der Agent alle lokalen CLI-Anmeldungen wiederverwendet, über die er bereits verfügt
+(zum Beispiel `gemini`- oder `claude`-Authentifizierung im Home-Verzeichnis des Benutzers). Es ist kein
+gehosteter oder Sandbox-Transport, und es handelt sich nicht um einen Chat/A2A-Transport – für diese
+siehe [Agent Surfaces](/docs/agent-surfaces).
+
+| Name              | Standardbefehl                                        | Fortsetzbar\* |
+| ----------------- | ----------------------------------------------------- | ------------- |
+| `acp`             | _(`command`/`args` über Konfiguration bereitstellen)_ | Ja            |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp`        | Ja            |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`              | Ja            |
+
+\*Resume funktioniert, wenn der Agent die `loadSession`-Fähigkeit ankündigt und
+wird andernfalls zu einer neuen Sitzung degradiert.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+Der Protokolltransport (`@zed-industries/agent-client-protocol`) ist optional
+Abhängigkeit wird träge über den `installPackage`-Hinweis geladen, genau wie die KI SDK
+Geschirr. Die Agent-Binärdatei selbst (`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`, …) ist ein separater externer CLI; die Voreinstellungen
+Starten Sie es über `npx` und der Befehl/die Argumente bleiben überschreibbar, da Agent ACP
+Eintrittsflaggen entwickeln sich noch weiter.
+
+`permissionMode` wird mithilfe des Tool-Aufrufs auf ACP `session/request_permission` abgebildet
+Art der Agent-Berichte: Lesevorgänge werden immer ausgeführt, Bearbeitungen werden unter `allow-edits` ausgeführt und
+alles riskante Eingabeaufforderungen, es sei denn `allow-all`. Genehmigungen werden wie gewohnt angezeigt
+`approval-request`-Ereignisse. Der Adapter bedient `fs/read_text_file` und
+`fs/write_text_file` für den Sitzungsarbeitsbereich (verweigert entkommene Pfade
+it) und Schreibvorgänge geben `file-change`-Ereignisse aus; Terminalmethoden werden nicht angekündigt,
+daher verwendet der Agent seine eigene Shell.
+
+## Codex-Authentifizierung: Code UI vs. Nutzung von Sandboxen {#codex-auth}
+
+Es gibt zwei Codex-Oberflächen, die sich unterschiedlich authentifizieren:
+
+- **Agent-Native Code / Desktop** führt `codex exec` auf dem Computer des Benutzers aus. Wenn
+  Der Benutzer hat `codex login` ausgeführt. Bei dieser lokalen Ausführung wird alles ChatGPT wiederverwendet
+  Abonnement oder API-Schlüsselauthentifizierung der installierten Codex CLI-Berichte über
+  `codex login status`.
+- **`ai-sdk-harness:codex`** lädt `@ai-sdk/harness-codex`, das Codex antreibt
+  in der Kabelbaum-Sandbox durch `@openai/codex-sdk`. Es geschieht nicht lautlos
+  übernimmt die Desktop-`~/.codex`-Anmeldung des Benutzers, da die Sandbox möglicherweise remote ist
+  oder isoliert. Für vertrauenswürdige/private Sandboxen aktivieren Sie die Option `codexCliAuth: true`;
+  Agent-Native kopiert die lokale Codex CLI-Authentifizierungsdatei vor dem
+  Kabelbaum startet. Konfigurieren Sie für gehostete oder gemeinsam genutzte Sandboxes API-key/gateway
+  auth stattdessen.
+
+Wenn also jemand fragt, welches Paket den Codex OAuth-Pfad trägt: für lokale Codierung
+Sitzungen, verwenden Sie `@agent-native/core` / Desktop plus die installierten
+`@openai/codex` CLI und `codex login`. Für `ai-sdk-harness:codex` mit Sandbox,
+Verwenden Sie das explizite `codexCliAuth`-Opt-in, wenn Sie diesen Login in die Sandbox kopieren
+ist akzeptabel.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` liest `CODEX_HOME/auth.json` oder `~/.codex/auth.json`. Zu
+zeigen Sie auf ein anderes lokales Login, übergeben Sie
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` oder
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## Registrieren und lösen {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` gibt einen `AgentHarnessAdapter` zurück. Die
+optionales `config` wird an die Adapterfabrik weitergeleitet – für die AI SDK-Adapter
+das ist `AiSdkHarnessAdapterOptions` (`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions` und nur Codex
+`codexCliAuth`). Verwenden Sie `listAgentHarnesses()`, um aufzulisten, wofür registriert ist
+ein Pflücker.
+
+## Führe eine Runde aus {#run-a-turn}
+
+`startAgentHarnessRun` überbrückt eine Harness-Sitzung in den gemeinsam genutzten Run-Manager
+Lebenszyklus. Es erstellt (oder verwendet) die native Sitzung, behält sie bei und streamt die
+turn, übersetzt jedes Harness-Ereignis in Transkriptereignisse und trennt das
+Wiederaufnahmestatus, wenn die Runde abgeschlossen ist.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` gibt den `ActiveRun` vom Run-Manager zurück, also der Zug
+wird in den vorhandenen Laufrouten, Transkripten und Stornierungen angezeigt, genau wie
+jede andere Agentenausführung. Übergeben Sie ein bereits erstelltes `session` anstelle von `createSession`
+um eine Sitzung fortzusetzen, die Sie im Speicher halten.
+
+## Sitzungen und Lebenslauf {#sessions}
+
+Ein Harness besitzt einen langlebigen nativen Sitzungsstatus. Agent-Native behält es in SQL
+damit ein Thread über Runden, Prozesse und Bereitstellungen hinweg überleben kann. Der `resumeState`
+ist **undurchsichtig** – Agent-Native speichert es und gibt es zurück, inspiziert es jedoch nie oder
+interpretiert es.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+Der Store macht auch `saveAgentHarnessSession`, `updateAgentHarnessSession`,
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` und `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` ruft die Speicher-/Aktualisierungs-/Stopppfade für Sie auf; Greifen Sie nach ihnen
+direkt nur in einem benutzerdefinierten Host.
+
+## Host-Tools und Berechtigungen {#host-tools}
+
+Ein Harness bringt seine eigenen nativen Tools mit (Lesen, Bearbeiten, Schreiben, Shell usw.), also
+Sie stellen die Dateibearbeitung **nicht** erneut als Host-Tools zur Verfügung. Passieren Sie nur eine **schmale,
+absichtliche Festlegung** von Agent-Native actions bis `createSession.tools`, wenn Sie
+Sie möchten, dass der Kabelbaum bestimmte App-Vorgänge erreicht – und `defineAction` beibehalten
+Authentifizierung, Anforderungskontext, Zeitüberschreitungen, Kürzung und schreibgeschützte Metadaten intakt, wenn
+Das tun Sie.
+
+`permissionMode` grenzt ein, was der Gurt ohne Genehmigung tun darf:
+
+| Modus         | Bedeutung                                                                       |
+| ------------- | ------------------------------------------------------------------------------- |
+| `allow-reads` | Standard. Liest ausgeführt; Änderungen und riskante actions-Eingabeaufforderung |
+| `allow-edits` | Lese- und Bearbeitungslauf; andere riskante actions-Eingabeaufforderung         |
+| `allow-all`   | Kein Genehmigungs-Gating                                                        |
+
+Wenn ein Kabelbaum zur Genehmigung pausiert, gibt er ein `approval-request`-Ereignis aus und
+Die Sitzung wird als `idle` markiert, wobei die ausstehende Genehmigung aufgezeichnet wird, sodass UI dies tun kann
+Auftauchen und nach der Entscheidung des Benutzers fortfahren. Siehe
+[Human Approval](/docs/human-approval) für die Genehmigungsoberfläche.
+
+## Ereignisse {#events}
+
+Eine Harness-Sitzung streamt `AgentHarnessEvent`-Werte, die Agent-Native
+übersetzt in den Standard-`AgentChatEvent`-Stream mit
+`agentHarnessEventToAgentChatEvents`. Die Ereignisunion umfasst `text-delta`,
+`thinking-delta`, `activity`, `tool-start`, `tool-done` (die einen tragen können
+`mcpApp`-Nutzlast für native Widgets), `approval-request`, `file-change`,
+`compaction`, `usage`, `error` und `done`. Denn Werkzeugergebnisse fließen durch das
+gleiche Übersetzung, aktionsdeklarierte native Widgets werden weiterhin gerendert – siehe
+[Native Chat UI](/docs/native-chat-ui).
+
+## Hintergrundläufe und UI {#background-runs}
+
+Harness führt das Projekt in die gemeinsame `BackgroundAgentRun`-Form aus
+`createAgentHarnessBackgroundAgentController()` und sind über die
+vorhandene Laufrouten als `goalId=agent-harness`. Das bedeutet einen lang laufenden Claude
+Code oder Codex-Sitzung werden in denselben Hintergrundausführungs- und Transkriptoberflächen angezeigt
+als Agent Teams und andere Adapter, mit `listAgentHarnessBackgroundRuns`,
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun` und
+`stopAgentHarnessBackgroundRun` verfügbar für benutzerdefinierte Hosts.
+
+## Benutzerdefinierte Adapter {#custom-adapters}
+
+Um eine Laufzeit einzuschließen, die nicht zu den integrierten Funktionen gehört, implementieren Sie
+`AgentHarnessAdapter` und registrieren Sie es. Der Adapter deklariert seine Fähigkeiten und
+erstellt Sitzungen; Eine Sitzung macht `streamTurn` und optional `continueTurn` verfügbar,
+`approve`, `detach`, `stop` und `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+Halten Sie das Laufzeitpaket optional mit einem dynamischen Import in `createSession` und einem
+`installPackage` Hinweis. Für brückengestützte Codierungskabelbäume ist ein echtes
+Sandbox/Workspace-Anbieter, anstatt einen beliebigen Codierungsagenten im
+Host-Prozess – siehe [Sandbox Adapters](/docs/sandbox-adapters). Der AI SDK-Adapter
+(`createAiSdkHarnessAdapter`, unterstützt durch `HarnessAgent` von `@ai-sdk/harness`) ist
+Eine Implementierung dieses Vertrags, nicht die öffentliche Abstraktion.
+
+## Nicht {#donts}
+
+- Fügen Sie Claude-Code, Codex, Cursor, Mastra oder Pi nicht als `AgentEngine` hinzu. Sie
+  eigene Schleife; Wenn Sie einen unter `AgentEngine.stream()` ausführen, wird die Schleife doppelt ausgeführt
+  und die Semantik des Sitzungslebenszyklus geht verloren.
+- Spielen Sie nicht jede Runde den gesamten Agent-Native-Chatverlauf in einem Geschirr ab. Fortsetzen
+  Stattdessen die Harness-Sitzung mit ihrem `resumeState`.
+- Don't store `resumeState` in `application_state`. It belongs in the harness
+  Sitzungs-SQL-Tabelle.
+- Machen Sie nicht standardmäßig jede App-Aktion für jede Harness-Sitzung verfügbar. Geben Sie es ab
+  kleines, gezieltes Werkzeugset.
+
+## Verwandte Dokumente {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) – Stellen Sie Ihren eigenen Agenten hinter den Chat UI mit `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces) – wählen Sie Headless, Chat, Sidecar oder Voll-App.
+- [Agent-Native Code UI](/docs/code-agents-ui) – die wiederverwendbare Codierungsarbeitsbereichsoberfläche.
+- [Custom Agents & Teams](/docs/agent-teams) – Hintergrundausführungen und Subagentendelegierung.
+- [Sandbox Adapters](/docs/sandbox-adapters) – steckbare Ausführungs-Backends für Codierungskabelbäume.
+- [Human Approval](/docs/human-approval) – der zugelassene Oberflächenkabelbaum läuft.

package/docs/content/locales/de-DE/human-approval.md

@@ -0,0 +1,86 @@
+---
+title: "Human-in-the-Loop-Genehmigungen"
+description: "Halten Sie den Agenten an, bevor eine Aktion mit hoher Konsequenz ausgeführt wird – das NeedsApproval-Gate von defineAction gibt ein Approval_required-Ereignis aus, der Mensch genehmigt und erst dann wird das Tool ausgeführt."
+---
+
+# Human-in-the-Loop-Genehmigungen
+
+Die meisten actions sollten einfach laufen. Einige davon – das Senden einer E-Mail, das Aufladen einer Karte, das Löschen eines Kontos – sind nach außen gerichtet und schwer rückgängig zu machen, und Sie möchten nicht, dass der Agent sie selbstständig erledigt. Für diese verfügt `defineAction` über ein optionales **Genehmigungstor**: Wenn der Agent versucht, die Aktion aufzurufen, pausiert die Schleife, zeigt dem Menschen ein Genehmigen/Verweigern-Angebot an und führt die Aktion _erst_ aus, nachdem der Mensch diesen spezifischen Aufruf genehmigt hat.
+
+> [!WARNING]
+> Halten Sie Genehmigungen selten. Jede geschlossene Aktion stellt einen harten Stopp in der Agentenschleife dar – sie unterbricht den Ablauf und erfordert einen menschlichen Rundlauf. Verwenden Sie `needsApproval` nur für wirklich schwerwiegende, schwer rückgängig zu machende, nach außen gerichtete Vorgänge. Wenn Sie feststellen, dass Sie Gating-Lesevorgänge oder routinemäßige Schreibvorgänge ausführen, liegen Sie falsch. Die Standardeinstellung ist **aus** und sollte bei fast jeder Aktion ausgeschaltet bleiben.
+
+## Das `needsApproval`-Tor {#needs-approval}
+
+Legen Sie `needsApproval` auf einen `defineAction`. Es akzeptiert einen booleschen Wert oder ein Prädikat:
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** – immer Genehmigung erforderlich.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** – Genehmigung nur erforderlich, wenn das Prädikat „true“ zurückgibt. Tor bedingt, z.B. nur für externe Empfänger oder nur über einem Dollar-Schwellenwert:
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  Halten Sie das Prädikat rein und schnell. **Es schlägt im geschlossenen Zustand fehl**: Wenn das Prädikat auslöst, behandelt das Framework dies als „Genehmigung erforderlich“, anstatt stillschweigend eine Aktion mit hoher Konsequenz auszuführen.
+
+Wenn `needsApproval` weggelassen wird, bleibt das Verhalten Byte für Byte unverändert – es fallen keine zusätzlichen Kosten für den gemeinsamen Pfad an.
+
+Dies funktioniert genauso für actions im Legacy-`parameters`-Stil und schemabasiertes actions sowie für den In-App-Agenten, Subagenten, A2A- und MCP-Aufrufer (jede Agentenoberfläche leitet durch dieselbe Schleife).
+
+## Wie die Schleife pausiert {#loop}
+
+Wenn der Agent eine Gated-Aktion aufruft und dieser spezielle Aufruf **noch** nicht genehmigt wurde, führt die Schleife `run()` **nicht** aus. Stattdessen:
+
+1. Löst das Tor. Für ein Prädikat wird `needsApproval(input, ctx)` aufgerufen; Ein Wurf wird als „muss genehmigt werden“ behandelt (fehlgeschlagen geschlossen).
+2. Gibt ein `tool_start`-Ereignis aus (damit der UI den Anruf anzeigt), gefolgt von einem **`approval_required`**-Ereignis, und stoppt dann die Runde. Der Nebeneffekt der Aktion tritt nie ein.
+
+Das `approval_required`-Event beinhaltet alles, was der Kunde braucht, um ein Angebot zu machen:
+
+| Feld          | Typ      | Notizen                                                                                     |
+| ------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `tool`        | `string` | Der Aktionsname, den der Agent aufzurufen versuchte.                                        |
+| `input`       | Objekt   | Die Argumente, die der Agent übergeben hat.                                                 |
+| `approvalKey` | `string` | **Stabiler Schlüssel**, der der Client zurückgibt, um _diesen genauen Anruf_ zu genehmigen. |
+| `toolCallId`  | `string` | Die modellseitige Tool-Aufruf-ID, sofern verfügbar.                                         |
+
+`approvalKey` wird deterministisch aus dem Werkzeugnamen und seiner Eingabe abgeleitet, sodass derselbe logische Aufruf immer denselben Schlüssel erzeugt. Das Modell sieht oder legt es nie fest – es handelt sich lediglich um einen Handschlag zwischen dem Framework und dem Approve-Angebot des Menschen.
+
+Das angehaltene Werkzeug gibt ein Ergebnis zurück, das dem Modell mitteilt, dass die Drehung angehalten wurde und es nicht erneut versucht werden soll, sodass sich das Modell nicht dreht.
+
+## Wie der Mensch zustimmt {#approve}
+
+Auf `approval_required` rendert der Chat UI ein **Genehmigen/Verweigern**-Angebot für den angehaltenen Tool-Aufruf. Dies wird in `AssistantChat` automatisch verkabelt – Sie erstellen es nicht pro Vorlage.
+
+- **Approve** gibt den Turn erneut aus (eine gewöhnliche Fortsetzungsnachricht) und trägt den Schlüssel des Anrufs in `approvedToolCalls: [approvalKey]`. Bei der erneuten Ausgabe erkennt das Tor den Schlüssel im genehmigten Satz und lässt diesen bestimmten Anruf normal laufen.
+- **Deny** lehnt das Angebot lokal ab; Es wird nichts erneut ausgegeben, daher wird die Aktion nie ausgeführt.
+
+`approvedToolCalls` ist ein Feld in der Chat-Anfrage (`AgentChatRequest.approvedToolCalls`). Schlüssel, die darin nicht vorhanden sind, bleiben pausiert – die Genehmigung eines Anrufs bedeutet niemals, dass andere Anrufe ohne weiteres genehmigt werden. Da der Schlüssel inhaltsadressiert ist, autorisiert eine Genehmigung diesen Aufruf mit diesen Argumenten. Wenn das Modell später einen anderen Versand vorschlägt, handelt es sich um einen neuen Schlüssel und eine neue Genehmigung.
+
+## End-to-End {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Die kanonische (und absichtlich seltene) Verwendung dieses Gates im Framework ist die Aktion `send-email` der Mail-Vorlage, die `needsApproval: true` so festlegt, dass der Agent frei verfassen und in die Warteschlange stellen kann, aber niemals tatsächlich eine Nachricht senden kann, ohne dass ein Mensch den spezifischen Versand genehmigt.
+
+## Verwandt
+
+- [**Actions**](/docs/actions#needs-approval) – die vollständige `defineAction`-Oberfläche, einschließlich `outputSchema` zur Validierung von Rückgabewerten.
+- [**Security**](/docs/security) – wann man nach einem Genehmigungstor greifen sollte oder wann man eine Aktion vor dem Modell verbergen sollte.
+- [**Mail template**](/docs/template-mail) – `send-email` ist das Referenzbeispiel.

package/docs/content/locales/de-DE/internationalization.md

@@ -1,15 +1,18 @@
 ---
 title: "Internationalisierung"
-description: "Lokalisiere Agent Native Apps mit gemeinsamen Locale-Katalogen, Sprachauswahl, Browser-Fallback und locale-bewussten Docs."
+description: "Lokalisieren Sie Agent Native-Apps mit freigegebenen Gebietsschemakatalogen, einer Sprachauswahl, einem Browser-Sprach-Fallback und länderspezifischen Dokumentinhalten."
 ---
 
 # Internationalisierung
 
-Agent Native Apps können Framework- und Template-UI über die gemeinsame Runtime `@agent-native/core/client/i18n` lokalisieren. Das Framework speichert die Sprachwahl des Benutzers in SQL-Settings, stellt sie als actions bereit und fällt auf English zurück, wenn eine App einen String noch nicht übersetzt hat.
+Agent Native-Apps können Framework und Vorlage UI über die gemeinsame lokalisieren
+`@agent-native/core/client/i18n`-Laufzeit. Das Framework speichert die Daten des Benutzers
+Sprachauswahl in den SQL-Einstellungen, macht sie als actions verfügbar und greift auf
+Englisch, wenn eine App eine Zeichenfolge noch nicht übersetzt hat.
 
-## Runtime {#runtime}
+## Laufzeit
 
-Verwende den Provider über `AppProviders`:
+Verwenden Sie den Anbieter über `AppProviders`:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` setzt das anfängliche `lang`, `dir` und `window.__AGENT_NATIVE_LOCALE__`, bevor React hydriert. Öffentliche SSR-Routen können `resolveLocaleFromRequest()` aus `@agent-native/core/server` aufrufen und den aufgelösten locale/catalog an das Script übergeben, um Hydration-Abweichungen zu vermeiden.
+`getLocaleInitScript()` legt die anfänglichen Werte `lang`, `dir` und
+`window.__AGENT_NATIVE_LOCALE__` bevor React hydratisiert. Öffentliche SSR-Routen können
+Rufen Sie `resolveLocaleFromRequest()` von `@agent-native/core/server` auf und übergeben Sie
+Gebietsschema/Katalog in diesem Skript aufgelöst, um Nichtübereinstimmungen bei der Hydratation zu vermeiden.
 
-## Kataloge {#catalogs}
+## Kataloge
 
-Jedes lokalisierte Template hält Kataloge unter `app/i18n/`:
+Jede lokalisierte Vorlage behält Kataloge unter `app/i18n/`:
 
 ```ts
 // app/i18n/index.ts
@@ -52,44 +58,76 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-Bundle immer `en-US`. Importiere Nicht-English-Kataloge dynamisch, damit Benutzer nur den aktiven locale herunterladen. Unterstützte locale codes sind `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` und `ar-SA`.
+Always bundle `en-US`. Dynamic-import non-English catalogs so users only
+Laden Sie das aktive Gebietsschema herunter. Die unterstützten Gebietsschemacodes sind `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` und `ar-SA`.
 
-## UI {#ui}
+## UI
 
-Verwende `useT()` für UI-Texte und `<LanguagePicker />` in den Settings:
+Verwenden Sie `useT()` für Schnittstellenzeichenfolgen und fügen Sie `<LanguagePicker />` in die App ein
+`/settings`-Seite. Sidebar-Apps sollten **Einstellungen** in der App-Sidebar anzeigen;
+Das Sprachsymbol in der Kopfzeile ist nur eine Verknüpfung.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-Verwende `useFormatters()` für Datumswerte, Zahlen, relative Zeiten und Listen. Lege locale-abhängige Datums- oder Zahlenformatierung nicht in Übersetzungsstrings ab.
+Das Steuerelement „Agenteneinstellungen“ sollte die Registerkarte „Einstellungen“ der rechten Agentenseitenleiste öffnen
+für Modell, API-Taste, Automatisierung, Sprache und andere Steuerelemente auf Framework-Ebene.
+Apps duplizieren möglicherweise hochwertige Framework-Einstellungen auf ihrer eigenen Einstellungsseite
+wenn die Einstellung für die App von zentraler Bedeutung ist, die Registerkarte mit den Seitenleisteneinstellungen jedoch erhalten bleibt
+Quelle der Wahrheit.
+
+Verwenden Sie `useFormatters()` für Datumsangaben, Zahlen, relative Zeit und Listen. Nicht einfügen
+Gebietsabhängige Datums-/Zahlenformatierung in Übersetzungszeichenfolgen.
 
 ## Docs-Site-Inhalt {#docs-site-content}
 
-Öffentliche Docs-Seiten verwenden denselben core provider, aber mit `persistPreference={false}`, damit anonymer Docs-Traffic localStorage und die Browsersprache nutzt statt SQL-Settings-actions. Die English-Quelle bleibt in `packages/core/docs/content/*.md`. Lokalisierte Seiten-Overrides liegen unter `packages/core/docs/content/locales/<locale>/<slug>.md`.
+Öffentliche Dokumentseiten verwenden denselben Kernanbieter, jedoch mit
+`persistPreference={false}`, sodass anonymer Dokumentenverkehr localStorage und
+Browsersprache statt SQL Einstellungen actions. Die englische Quelle bleibt in
+`packages/core/docs/content/*.md`. Lokalisierte Seitenüberschreibungen werden direkt daneben unter
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-Verwende dieselben BCP-47 locale codes wie App-Kataloge. Behalte denselben slug wie die English-Quelle, bewahre stabile Anker mit `{#anchor}` auf übersetzten Überschriften und übersetze keine routes, action names, protocol fields, env vars oder provider names. Wenn ein locale keine übersetzte Markdown-Datei für eine Seite hat, fällt die Docs-Site für diese Seite auf English zurück, lokalisiert aber weiterhin Navigation und Chrome.
+Verwenden Sie dieselben BCP-47-Gebietsschemacodes wie App-Kataloge. Behalten Sie den gleichen Slug wie der
+Englische Quelle, stabile Anker mit `{#anchor}` bei übersetzten Überschriften beibehalten
+und hinterlassen Sie Routen, Aktionsnamen, Protokollfelder, Umgebungsvariablen und Anbieternamen
+unübersetzt. Wenn ein Gebietsschema kein übersetztes Markdown für eine Seite hat, die Dokumentationsseite
+greift für diese Seite auf Englisch zurück, während Navigation und Chrome weiterhin lokalisiert werden.
 
-## Actions und Persistenz {#actions-and-persistence}
+## Actions und Beharrlichkeit
 
 Jede App erbt:
 
-- `get-localization-preference` — liest `{ locale }` des aktuellen Benutzers
-- `set-localization-preference` — setzt `"system"` oder einen unterstützten locale
+- `get-localization-preference` – liest den `{ locale }` des aktuellen Benutzers
+- `set-localization-preference` – Legen Sie `"system"` oder ein unterstütztes Gebietsschema fest
 
-Der dauerhafte Wert liegt in benutzerbezogenen SQL-Settings unter `localization`. `localStorage` wird nur für Pre-Hydration und anonymen Fallback genutzt. Der aktive locale wird als Umgebungskontext in application state gespiegelt, damit agents die aktuelle UI-Sprache sehen.
+Der dauerhafte Wert lebt in benutzerbezogenen SQL-Einstellungen unter `localization`.
+`localStorage` wird nur zur Vorhydratation und zum anonymen Fallback verwendet. Das aktive
+Das Gebietsschema wird als Umgebungskontext in den Anwendungsstatus gespiegelt, sodass Agenten es sehen können
+die aktuelle Schnittstellensprache.
 
-## Guard {#guard}
+## Wache
 
 Ausführen:
 
@@ -97,6 +135,11 @@ Ausführen:
 pnpm guard:i18n-catalogs
 ```
 
-Der Guard prüft unterstützte locale-Dateinamen, key parity, placeholder parity, stale keys und CLDR-Pluralkategorien über `Intl.PluralRules`. Er prüft Struktur, nicht Übersetzungsqualität; gut sichtbare Strings brauchen weiterhin menschliche Prüfung.
+Der Wächter überprüft unterstützte Gebietsschema-Dateinamen, Schlüsselparität und Platzhalterparität.
+veraltete Schlüssel und CLDR Pluralkategorien bis `Intl.PluralRules`. Es prüft
+Struktur, nicht Übersetzungsqualität; Gut sichtbare Saiten brauchen immer noch Menschen
+Rezension.
 
-Übersetze keine stabilen Bezeichner wie action names, routes, enum values, app-state keys, database values, protocol fields, env var names oder provider names.
+Übersetzen Sie keine stabilen Bezeichner wie Aktionsnamen, Routen, Enum-Werte usw.
+App-Statusschlüssel, Datenbankwerte, Protokollfelder, Umgebungsvariablennamen oder Anbieter
+Namen.