@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "Wiederkehrende Jobs"
+description: "Cron-geplante Eingabeaufforderungen, die der Agent selbstständig ausführt – tägliche Übersichten, wöchentliche Berichte, stündliche Abfragen."
+---
+
+# Wiederkehrende Jobs
+
+Ein **wiederkehrender Job** ist eine Eingabeaufforderung, die nach einem Cron-Zeitplan ausgeführt wird. So erledigt der Agent die Dinge selbst: „Jeden Morgen um 7 Uhr fasse ich meine Nacht-E-Mails zusammen“, „postet jeden Montag die Anmeldenummern der letzten Woche an Slack“, „sucht jede Stunde nach veralteten Entwürfen und löscht sie.“
+
+Wiederkehrende Aufträge werden nach dem Takt der Uhr ausgelöst. Um auf _Ereignisse_ (eine erstellte Buchung, eine empfangene E-Mail) zu reagieren – dasselbe `jobs/`-Dateiformat plus Bedingungen – siehe [Automations](/docs/automations).
+
+Jobs leben im [workspace](/docs/workspace) bei `jobs/<name>.md` – nur eine Markdown-Datei mit YAML-Frontmatter. Keine Registrierung, keine Verkabelung. Legen Sie die Datei ab und das Framework übernimmt sie.
+
+## Eine Jobdatei {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+Das ist es. Der Hauptteil ist eine Eingabeaufforderung, die der Agent bei jeder geplanten Auslösung ausführt. Der Agent hat Zugriff auf dieselben Tools und denselben Arbeitsbereichskontext wie in einem interaktiven Chat – actions, skills, Speicher, verbundene MCP-Server, Subagenten.
+
+## Frontmatter {#frontmatter}
+
+| Feld         | Typ                           | Standard         | Beschreibung                                                                                                                                   |
+| ------------ | ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | Cron-Ausdruck                 | _(erforderlich)_ | Standard-Cron mit 5 Feldern. `"0 7 * * *"` = jeden Tag um 07:00; `"0 */4 * * *"` = alle 4 Stunden.                                             |
+| `enabled`    | boolean                       | `true`           | Wechseln Sie zu `false`, um den Job anzuhalten, ohne ihn zu löschen.                                                                           |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`      | `"creator"` wird mit der Identität des Jobeigentümers und `ANTHROPIC_API_KEY` ausgeführt. `"shared"` verwendet den Schlüssel der Organisation. |
+| `createdBy`  | E-Mail                        | _(auto)_         | Wird ausgefüllt, wenn der Job über den Arbeitsbereich UI oder durch den Agenten erstellt wird.                                                 |
+| `orgId`      | Zeichenfolge                  | _(auto)_         | Organisationsbereich; Von der aktiven Organisation des Erstellers geerbt.                                                                      |
+| `lastRun`    | ISO-Zeitstempel               | _(verwaltet)_    | Wird vom Planer nach jedem Lauf geschrieben.                                                                                                   |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(verwaltet)_    | Neuestes Ergebnis.                                                                                                                             |
+| `lastError`  | Zeichenfolge                  | _(verwaltet)_    | Fehlermeldung, wenn der letzte Lauf fehlgeschlagen ist.                                                                                        |
+| `nextRun`    | ISO-Zeitstempel               | _(verwaltet)_    | Berechnet aus `schedule`; Wird vom Planer verwendet, um zu entscheiden, wann das nächste Mal ausgelöst wird.                                   |
+
+Die Felder `last*` und `nextRun` werden vom Scheduler geschrieben. Sie können sie lesen, um den Verlauf anzuzeigen, aber bearbeiten Sie sie nicht manuell – beim nächsten Durchlauf werden sie überschrieben.
+
+## Cron-Syntax {#cron}
+
+Standard-Cron mit 5 Feldern (Minute, Stunde, Tag des Monats, Monat, Wochentag):
+
+| Cron           | Bedeutung                 |
+| -------------- | ------------------------- |
+| `*/5 * * * *`  | Alle 5 Minuten            |
+| `0 * * * *`    | Jede volle Stunde         |
+| `0 */4 * * *`  | Alle 4 Stunden            |
+| `0 7 * * *`    | Jeden Tag um 07:00 Uhr    |
+| `0 9 * * 1`    | Jeden Montag um 09:00 Uhr |
+| `0 17 * * 1-5` | Wochentags um 17:00       |
+| `0 0 1 * *`    | Erster Tag jedes Monats   |
+
+Das Framework umfasst Cron-Dienstprogramme (`isValidCron()` und `describeCron()`) zum Validieren und Rendern von Cron-Strings, die intern von der Ressourcen- und Scheduler-Ebene verwendet werden.
+
+## Job erstellen {#creating}
+
+### Auf der Registerkarte „Arbeitsbereich“
+
+`+` → **Geplante Aufgabe** im Arbeitsbereichsbereich. Füllen Sie die Eingabeaufforderung und den Zeitplan aus. Speichert als `jobs/<slug>.md` und beginnt mit der Ausführung beim nächsten passenden Tick.
+
+### Indem Sie den Agenten fragen
+
+> „Erstellen Sie jeden Morgen um 7 Uhr eine geplante Aufgabe, die meine ungelesenen E-Mails zusammenfasst.“
+
+Der Agent schreibt die Datei für Sie.
+
+### Von Hand
+
+Legen Sie eine Markdown-Datei über die Ressource APIs des Frameworks in `jobs/` ab:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## Wie der Planer ausgeführt wird {#how-scheduler-runs}
+
+Der Scheduler ist ein Framework-Plugin (die interne `processRecurringJobs()`-Routine), das prozessintern ausgeführt wird: Ein `setInterval` wird alle 60 Sekunden (mit einer Startverzögerung von 10 Sekunden) innerhalb des Agenten-Chat-Plugins ausgelöst, wo auch immer der Server läuft.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## Debuggen eines Jobs {#debugging}
+
+- Öffnen Sie `jobs/<name>.md` im Arbeitsbereich – die Vorderseite zeigt `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- **Testen Sie es ohne zu warten:** Es gibt kein Force-Fire-Tool. Um die gleiche Arbeit bei Bedarf auszuführen, fügen Sie entweder die Eingabeaufforderung des Jobs in den Agenten-Chat ein und lassen Sie ihn dort ausführen, oder stellen Sie den Zeitplan vorübergehend auf die nächste Minute ein, damit der Planer ihn beim nächsten Tick übernimmt (und stellen Sie dann den echten Cron wieder her).
+- **Pause:** umdrehen `enabled: false`. Die Datei bleibt bestehen und wird einfach nicht mehr ausgeführt.
+
+## Agent-Tool {#agent-tool}
+
+In jeder Vorlage ist ein einzelnes `manage-jobs`-Tool registriert. Der Parameter `action` wählt die Operation aus:
+
+| Aktion   | Parameter                                                             | Zweck                                                                          |
+| -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `create` | `name`, `schedule`, `instructions` (erforderlich); `scope`, `runAs`   | Erstellen Sie einen neuen wiederkehrenden Auftrag                              |
+| `list`   | `scope` (`personal`, `shared` oder alle)                              | Alle Jobs mit Status auflisten (geplant, aktiviert, letzte/nächste Ausführung) |
+| `update` | `name` (erforderlich); `schedule`, `instructions`, `enabled`, `runAs` | Bestehenden Job bearbeiten                                                     |
+| `delete` | `name` (erforderlich)                                                 | Einen Auftrag löschen – immer zuerst mit dem Benutzer bestätigen               |
+
+**Persönlicher vs. gemeinsamer Bereich.** Jeder Job befindet sich entweder im persönlichen Bereich (läuft als und ist nur für den Ersteller sichtbar) oder im freigegebenen/organisatorischen Bereich (wird im Namen des Erstellers ausgeführt, ist aber für Organisationsmitglieder sichtbar). Die Parameter `scope` und `runAs` steuern dies zum Zeitpunkt der Erstellung. Organisationsadministratoren können alle freigegebenen Jobs aktualisieren oder löschen. Nicht-Administrator-Mitglieder können nur ihre eigenen verwalten.
+
+## Unterscheidet sich vom Planungspaket {#vs-scheduling-package}
+
+Verwechseln Sie wiederkehrende Aufträge nicht mit `@agent-native/scheduling`:
+
+- **Wiederkehrende Jobs (diese Seite)** – Cron-geplante Eingabeaufforderungen, die der Agent im Hintergrund ausführt. Framework-Ebene. Lebt im Arbeitsbereich. Läuft auf jeder agentennativen App.
+- **`@agent-native/scheduling`** – ein wiederverwendbares Domänenpaket zum Erstellen von Kalender-/Buchungsfunktionen (Veranstaltungstypen, Verfügbarkeitsfenster, Buchungen). Unterstützt die `calendar`-Vorlage und benutzerdefinierte Planungsoberflächen.
+
+Wiederkehrende Aufträge lauten: „Wie bringe ich den Agent dazu, eigenständig zu handeln?“ Das Planungspaket lautet: „Wie erstelle ich eine Kalender-App?“ Verschiedene Anliegen.
+
+## Was kommt als nächstes?
+
+- [**Automations**](/docs/automations) – Ereignisauslöser und Bedingungen zum gleichen `jobs/`-Format hinzufügen
+- [**Workspace**](/docs/workspace) – wo Jobs neben skills, Speicher und benutzerdefinierten Agents leben
+- [**Actions**](/docs/actions) – die Werkzeuge, die ein Job erfordert
+- [**Agent Teams**](/docs/agent-teams) – Jobs erzeugen oft Subagenten, um parallele Arbeit zu erledigen

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

@@ -0,0 +1,79 @@
+---
+title: "Routing"
+description: "Dateibasiertes Routing für agentennative Apps mit React Router v7 – Seiten, dynamische Parameter und Navigation."
+---
+
+# Routing
+
+Agent-native Apps verwenden **React Router v7** mit dateibasiertem Routing über `flatRoutes()` von `@react-router/fs-routes`. Jede Datei in `app/routes/` wird zu einem URL. Vorlagen verwenden die Punktnotationskonvention – Punkte trennen URL-Segmente innerhalb eines einzelnen Dateinamens.
+
+## Dateibasiertes Routing {#file-based-routing}
+
+### Datei → URL-Zuordnung
+
+| Datei                 | URL                | Notizen                                  |
+| --------------------- | ------------------ | ---------------------------------------- |
+| `_index.tsx`          | `/`                | Indexroute                               |
+| `settings.tsx`        | `/settings`        | Einfache Seite                           |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | Punkt = `/`, `$` = dynamischer Parameter |
+| `_app.tsx`            | (kein URL-Segment) | Pfadloses Layout – Präfix mit `_`        |
+| `inbox/route.tsx`     | `/inbox`           | Ordnerform – `route.tsx` ist der Index   |
+
+Stellen Sie einem Segment `$` für einen dynamischen Parameter voran. Setzen Sie als Präfix `_`, um eine pfadlose Layoutroute zu erstellen (kein URL-Segment). Vorlagen verwenden `flatRoutes()` – die obige Punktnotationsdatei ist primär; Die verschachtelte Ordnerform `inbox/route.tsx` funktioniert auch.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## Eine neue Seite hinzufügen {#adding-a-page}
+
+Erstellen Sie die Datei und exportieren Sie eine Standardkomponente:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+Das ist alles – der React-Router nimmt es automatisch auf, keine Registrierung erforderlich.
+
+## Dynamische Parameter {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## Navigation {#navigation}
+
+Verwenden Sie `<Link>` für die clientseitige Navigation und `useNavigate()` für die programmgesteuerte Navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## Was kommt als nächstes?
+
+- [**Client**](/docs/client) – die agentennativen Browser-Hooks und Dienstprogramme
+- [**Server**](/docs/server) – dateibasierte Serverrouten und der `/_agent-native/`-Namespace

package/docs/content/locales/de-DE/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "Adapter"
+description: "Die beiden Adapter-Seams des Frameworks: Sandbox-Adapter tauschen das Backend aus, das das Run-Code-Tool des Agenten ausführt, und CLI-Adapter ermöglichen dem Agenten strukturierten Zugriff auf Befehlszeilentools."
+search: "Adapter, Sandbox-Adapter, CLI-Adapter, Run-Code, SandboxAdapter, CliAdapter, ShellCliAdapter, dauerhafter Läufer, Remote-Sandbox-Edge, serverloser untergeordneter_Prozess"
+---
+
+# Adapter
+
+> **Für wen ist das gedacht:** Host-Autoren, die die Laufzeit verlängern. App-Entwickler selten
+> brauche das – die Standardeinstellungen funktionieren sofort.
+
+Agent-Native verfügt über zwei Verbindungsnähte, die ein Problem hinter einer schmalen Naht verdrängen,
+austauschbare Schnittstelle:
+
+- **Sandbox-Adapter** tauschen das Backend aus, das das `run-code`-Tool des Agenten ausführt –
+  standardmäßig ein lokaler untergeordneter Prozess oder ein Docker-/Remote-/Durable-Runner.
+- **CLI-Adapter** ermöglichen dem Agenten strukturierten Zugriff auf Befehlszeilentools
+  (`gh`, `ffmpeg`, `stripe`) mit Erkennung, Verfügbarkeitsprüfungen und einem
+  konsistente Ergebnisform.
+
+Beide haben eine Laufzeitbeschränkung gemeinsam: Sie verlassen sich auf Node.js-Systembindungen und tun dies auch
+nicht auf Edge-/Worker-Laufzeiten ausführen – siehe [Edge and serverless](#edge-serverless).
+
+## Welches Codierungsdokument möchte ich? {#which-doc}
+
+| Sie möchten…                                                                       | Verwenden                                    |
+| ---------------------------------------------------------------------------------- | -------------------------------------------- |
+| Tauschen Sie das Backend aus, das das **`run-code`-Tool** des Agenten ausführt     | **Sandbox-Adapter** (diese Seite)            |
+| Verpacken Sie ein CLI-Tool (`gh`, `ffmpeg`), damit der Agent anrufen kann          | **CLI-Adapter** (diese Seite)                |
+| Rendern Sie einen **Codierungsarbeitsbereich UI** im Claude-Code/Codex-Stil        | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Führen Sie Claude Code / Codex / Pi **als Agent** mit eigener Schleife + Tools aus | [Harness Agents](/docs/harness-agents)       |
+
+# Sandbox-Adapter
+
+Das Tool `run-code` führt das vom Agenten bereitgestellte JavaScript in einer isolierten Umgebung aus. **Sandbox-Adapter** berücksichtigen das _Ausführungsproblem_ dieses Tools, sodass das Backend ausgetauscht werden kann – standardmäßig ein lokaler untergeordneter Prozess oder ein Docker-/Remote-/Durable-Runner – ohne die Agentenschleife, `run-code.ts`, die Localhost-Brücke, den Env-Scrub oder die Ausgabeformatierung zu berühren.
+
+## Warum eine Naht {#why}
+
+Das Standard-Backend erzeugt einen gesperrten lokalen untergeordneten Knotenprozess. Dies ist durch den Hosting-Prozess begrenzt: Auf der gehosteten Plattform teilt es sich die weiche Ausführungsobergrenze der Agentenschleife (~40 Sekunden vor Timeout/Fortsetzungs-Thrash). Ein Remote- oder dauerhafter Adapter ist der Hebel, um diese Obergrenze zu überschreiten – er führt große Datenaufträge unabhängig vom Anforderungslebenszyklus bis zum Abschluss aus.
+
+Wenn der Vertrag eng gefasst bleibt, erbt ein Remote-Adapter denselben Sicherheitsstatus. Der übergeordnete Prozess behält das Eigentum an allem, was Geheimnisse enthält: Er erstellt das Sandbox-Modul, führt die Localhost-Bridge aus (die den Anforderungskontext enthält und Host-Zulassungslisten + SSRF-Guards anwendet), bereinigt die Umgebung und formatiert die Ausgabe. Ein Adapter erhält nur eine bereits vorbereitete, **nicht geheime** Modulquelle plus Ressourcenlimits – er ist allein dafür verantwortlich, sie auszuführen und den stdout/stderr/exit-Status zu erfassen.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Die Schnittstelle {#interface}
+
+Die Naht befindet sich im Kern bei `packages/core/src/coding-tools/sandbox/` – `adapter.ts` (der Vertrag), `index.ts` (Auswahl: `getSandboxAdapter()` / `registerSandboxAdapter()`) und `local-child-process-adapter.ts` (die Standardeinstellung). Die Verkabelung erfolgt im Gehäuse durch `run-code.ts`; Ein Host verbindet ein anderes Backend über den Registrierungshelfer `index.ts` (oder, für ein Docker-Backend, über [blueprint](/docs/blueprint-installer), der diese Dateien direkt bearbeitet).
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+Jedes Backend implementiert `SandboxAdapter`:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+Die Anfrage und das Ergebnis sind bewusst klein und undurchsichtig:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## Der Standardwert: `LocalChildProcessAdapter` {#default}
+
+Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "local-child-process"`). It preserves the historical `run-code` behavior byte-for-byte:
+
+- Die vorbereitete Modulquelle wird in ein neues temporäres Verzeichnis geschrieben.
+- Das Kind läuft mit der bereinigten Umgebung (keine Geheimnisse), wobei `TMPDIR`/`TEMP`/`TMP` auf das Sandbox-Verzeichnis zeigt.
+- Wenn das Node-Berechtigungsmodell verfügbar ist (`--permission` oder `--experimental-permission` auf Node 20), wird dem Kind der Zugriff auf das Dateisystem außerhalb seines temporären Verzeichnisses sowie auf untergeordnete Prozesse, Worker und native Add-ons verweigert. Ausgehendes Netzwerk wird _nicht_ durch das Berechtigungsmodell blockiert – aber der Env Scrub bedeutet, dass solche Anfragen keine Anmeldeinformationen enthalten und alle authentifizierten Anrufe über die Loopback-Brücke des übergeordneten Netzwerks laufen.
+- Eine Zeitüberschreitung sendet `SIGTERM`, dann `SIGKILL` nach einer Kulanzfrist von 2 Sekunden.
+- Temporäre Dateien werden nach der Ausführung bestmöglich bereinigt.
+
+> [!WARNING]
+> Der Standardadapter verwendet `node:child_process`, das auf Edge-/Worker-Laufzeiten nicht vorhanden ist. Führen Sie `run-code` in einer Standard-Node.js-Umgebung aus oder registrieren Sie einen Remote-Adapter – siehe [Edge and serverless](#edge-serverless).
+
+## Adapter auswählen {#selection}
+
+Auflösungsreihenfolge – ein explizit registrierter Adapter gewinnt; andernfalls wählt die Umgebungsvariable eine integrierte Variable aus; andernfalls wird der lokale Standard verwendet:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` Umgebungsvariable {#env}
+
+Wählt einen integrierten Adapter anhand der ID aus. Derzeit ist nur `local` (Standard) verkabelt; Bei unbekannten Werten wird auf lokal zurückgegriffen, anstatt dass die Ausführung fehlschlägt.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+Ein Hostprozess überschreibt das Backend für alle nachfolgenden `run-code`-Aufrufe über den `index.ts` der Seam – zum Beispiel, um jeden Aufruf in einem Remote-Container auszuführen:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## Die Naht für einen langlebigen Läufer {#durable}
+
+Diese Schnittstelle ist bewusst die Nahtstelle für eine zukünftige Remote-/dauerhafte Sandbox. Ein Remote- oder dauerhafter Adapter (Docker, ein Läufer im Vercel-Sandbox-Stil oder ein Hintergrundarbeiter in der Warteschlange) würde:
+
+1. Implementieren Sie `SandboxAdapter.run` gegen eine Out-of-Process-Laufzeit.
+2. Tunnel die Loopback-Brücke (oder Proxy-Bridge-Aufrufe zurück zum übergeordneten Element).
+3. Große Datenaufträge können unabhängig vom Anforderungslebenszyklus bis zum Abschluss ausgeführt werden – wobei die gehostete Code-Exec-Obergrenze von ca. 40 Sekunden überschritten wird, die den lokalen untergeordneten Prozessadapter begrenzt.
+
+Registrieren Sie es unter einem neuen `AGENT_NATIVE_SANDBOX`-Wert (z. B. `remote`) und/oder über `registerSandboxAdapter()`. Die Agentenschleife und `run-code.ts` ändern sich nie.
+
+> [!TIP]
+> Der `agent-native add sandbox docker`-Blueprint liefert ein vollständiges, eigenständiges Rezept für die Implementierung eines Docker-Adapters gegen diese Naht. Siehe [Blueprint Installer](/docs/blueprint-installer).
+
+# CLI-Adapter
+
+Die andere Adapternaht umschließt ein einzelnes Befehlszeilentool (`gh`, `ffmpeg`, `stripe`, `aws`), sodass der Agent es erkennen, prüfen kann, ob es installiert ist, und es mit einem konsistenten stdout/stderr/exit-code-Ergebnis ausführen kann. Jeder CLI-Adapter implementiert `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+Bei den meisten CLIs umschließt `ShellCliAdapter` jede Binärdatei mit sinnvollen Standardwerten, und `CliRegistry` sammelt Adapter für die Laufzeiterkennung:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+Umschließen Sie einen CLI-Aufruf in `defineAction`, um ihn auf der Aktionsoberfläche verfügbar zu machen. Weitere Informationen zu `ShellCliAdapter`-Optionen, benutzerdefinierten Adaptern und dem Action-Wrapping-Muster finden Sie in der [CLI Adapters](/docs/cli-adapters)-Kurzreferenz.
+
+## Edge und serverlos {#edge-serverless}
+
+> [!WARNING]
+> Beide Adapternähte basieren auf Node.js-Systembindungen. Die Sandbox-Adapter `LocalChildProcessAdapter` und CLI (`ShellCliAdapter` und benutzerdefinierte Adapter) verwenden `node:child_process` (`execFile` / `spawn`), das auf Edge-/Worker-Laufzeiten wie Cloudflare Workers oder Netlify Edge Functions **nicht vorhanden** ist. Wenn Sie Serverrouten zu diesen Edge-Voreinstellungen bereitstellen, löst die Ausführung dieser Adapter eine Laufzeitausnahme aus. Führen Sie Adapterendpunkte und -aufgaben in einer Standard-Node.js-Umgebung aus (herkömmliche Servercontainer oder serverlose Knotenfunktionen) – oder registrieren Sie für die Sandbox-Verbindung einen Remote-Adapter, der Arbeit außerhalb des Prozesses versendet.
+
+## Was kommt als nächstes?
+
+- [**CLI Adapters**](/docs/cli-adapters) – die Kurzreferenz für die CLI-Naht
+- [**Blueprint Installer**](/docs/blueprint-installer) – `agent-native add sandbox docker` druckt ein Docker-Adapter-Rezept
+- [**Agent Teams**](/docs/agent-teams) – Delegierung schwerer Arbeit an Unteragenten
+- [**Security**](/docs/security) – der Env Scrub- und Bridge-Zulassungslistenstatus