@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "In-Loop-Prozessoren"
+description: "Schleifeninterne Beobachter-/Leitplanken-Hooks, die die gestreamte Ausgabe und die Werkzeugaufrufe des Modells während der Ausführung überwachen und abbrechen können – die Nahtstelle für Echtzeit-Leitplanken und Proof-of-Done-Gates."
+---
+
+# In-Loop-Prozessoren
+
+Ein `Processor` ist ein schleifeninterner **Beobachter/Leitplanke** für den Agentenlauf. Es überwacht die gestreamte Ausgabe des Modells und die von ihm aufgerufenen Tool-Anfragen _während der Ausführung fortschreitet_, behält seinen eigenen Scratch-Status bei und kann die Ausführung **abbrechen**, bevor ein „Fertig“-Status beansprucht wird. Dies ist die strukturelle Voraussetzung für Echtzeit-Leitlinien (Blockieren unzulässiger Ausgaben mitten im Stream) und ein Proof-of-Done/Coverage-Gate (überprüfen, was das Modell tun wird, und anhalten).
+
+```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]
+> Ein Prozessor ist eine **Konfiguration**, kein Werkzeug, keine Aktion und kein Authoring DSL. Prozessoren beobachten nur, verändern ihren eigenen Stream-Scope-Status und `abort()`. Sie definieren niemals das App-Verhalten, ersetzen actions oder erscheinen im Modell. App-Vorgänge gehören zu [actions](/docs/actions).
+
+## Die Haken {#hooks}
+
+Ein Prozessor implementiert eine beliebige Teilmenge von drei optionalen Lebenszyklus-Hooks (die Form ist von den Ausgabeprozessoren von Mastra übernommen):
+
+| Haken                 | Brände…                                                                | Verwenden Sie es, um…                                                      |
+| --------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `processOutputStream` | pro gestreamtem Block (Text-/Denkdeltas), während das Modell generiert | reagieren Sie auf die Ausgabe, bevor die volle Runde erreicht ist          |
+| `processOutputStep`   | einmal pro Modellantwort, rund um die Toolausführung                   | Überprüfen Sie die Toolaufrufe, die das Modell ausführen soll. Tor sie ein |
+| `processOutputResult` | einmal am Ende des Laufs, mit dem endgültigen Assistententext          | Zeichnen Sie ein Urteil/einen Nachweis über die vollständige Antwort auf   |
+
+Jeder Prozessor erhält sein eigenes veränderbares, laufbereichsbezogenes `state`-Objekt, das bei jedem seiner Hook-Aufrufe innerhalb eines einzelnen Laufs bestehen bleibt und vom Status anderer Prozessoren **isoliert** ist.
+
+```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";
+  },
+};
+```
+
+## Abbruch mit `TripWire` {#tripwire}
+
+Ein Hook stoppt die Ausführung durch den Aufruf von `abort(reason, meta?)`, der ein **`TripWire`** auslöst. Die Schleife fängt es ab, gibt ein einzelnes **`tripwire`-Ereignis** aus, stoppt sauber und zeigt den Grund als letzte Assistentenmeldung an.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+Das `tripwire`-Ereignis trägt:
+
+| Feld        | Typ      | Notizen                                                                    |
+| ----------- | -------- | -------------------------------------------------------------------------- |
+| `reason`    | `string` | Der für Menschen lesbare Grund, der an `abort` übergeben wird.             |
+| `processor` | `string` | Name des Prozessors, der abgebrochen hat, als er einen `name` deklarierte. |
+
+`TripWire` trägt auch optional strukturiertes `meta` und den ursprünglichen `processor`-Namen für programmatische Verbraucher, die ihn `instanceof`-prüfen. Da ein Stopp ordnungsgemäß erfolgt, feuert `processOutputResult` weiterhin auf den (angehaltenen) endgültigen Text, sodass ein Proof-of-Done-Prozessor sein Urteil auch dann aufzeichnen kann, wenn der Lauf abgebrochen wurde.
+
+## Verkabelung von Prozessoren {#wiring}
+
+Prozessoren werden im Code über das `processors`-Array auf `runAgentLoop` konfiguriert:
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**Kein Overhead, wenn nicht verwendet.** Die Schleife baut die Prozessorkette nur auf, wenn mindestens ein Prozessor bereitgestellt wird; Wenn `processors` weggelassen oder leer ist, wird keiner der Nahtcodes ausgeführt und die Schleife bleibt Byte für Byte unverändert. Hooks werden in der Reihenfolge der Registrierung ausgeführt und können synchron oder asynchron sein.
+
+> [!NOTE]
+> Der Loop-Level-Seam ist heute lieferbar und kann direkt von Subagenten, A2A, MCP und Tests aufgerufen werden. Das Einfädeln von `processors` durch den HTTP-Chat-Handler (damit ein Pro-Request-Resolver sie konfigurieren kann, ohne `runAgentLoop` direkt aufzurufen) ist eine praktische Installation, die noch nicht verkabelt ist – konfigurieren Sie Prozessoren vorerst an der `runAgentLoop`-Aufrufseite.
+
+## Verwandt
+
+- [**Durable Resume**](/docs/durable-resume) – wie die Schleife Unterbrechungen übersteht, ohne abgeschlossene Nebenwirkungen erneut auszuführen.
+- [**Custom Agents & Teams**](/docs/agent-teams) – Subagenten führen dieselbe Schleife aus und können ihre eigenen Prozessoren tragen.
+- [**Observability**](/docs/observability) – Prozessorurteile neben Ausführungsspuren aufzeichnen.

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

@@ -0,0 +1,199 @@
+---
+title: "Fortschritt"
+description: "Live-Fortschrittssignal für Agentenaufgaben mit langer Laufzeit – starten, aktualisieren, abschließen"
+---
+
+# Fortschritt
+
+Lange Agentenaufgaben sollten sich nicht hinter einem Spinner verstecken. `progress_runs` gibt dem Agenten die Möglichkeit, anzukündigen: „Ich arbeite daran, ich bin zu 45 % fertig, hier ist der aktuelle Schritt“ – was der UI als schwebende Ausführungsleiste mit einem Prozentbalken rendert.
+
+```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");
+```
+
+Separates Problem von [notifications](/docs/notifications): Benachrichtigungen werden einmal ausgelöst (_"X ist passiert"_), der Fortschritt ist ein kontinuierlicher Status (_"X ist zu 45 % erledigt"_). Die beiden setzen sich zusammen – `completeRun` gefolgt von `notify(..., severity: "info")` teilt dem Benutzer mit, wann die Arbeit beendet ist, auch wenn er nicht auf das Fach geachtet hat.
+
+## Der Lebenszyklus {#lifecycle}
+
+| Status      | Übergang                                 |
+| ----------- | ---------------------------------------- |
+| `running`   | Anfänglich – festgelegt durch `startRun` |
+| `succeeded` | Happy-Path-Terminal                      |
+| `failed`    | Fehlerterminal                           |
+| `cancelled` | Benutzer unterbrochen                    |
+
+```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}"
+}
+```
+
+Terminalstatus gesetzt `completed_at`. Das Fach UI zeigt nur `running`-Zeilen; Abgeschlossene Zeilen bleiben für `action=list`-Abfragen in der Datenbank.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+Erstellen Sie einen Lauf. Gibt das vollständige `AgentRun` mit einer generierten ID zurück.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+Gibt `run.progress.started` auf dem Ereignisbus aus.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+Patcht ein beliebiges Feld eines laufenden Laufs. Alle ausgelassenen Felder bleiben unverändert.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+Gibt `run.progress.updated` auf dem Ereignisbus aus. Gibt den aktualisierten `AgentRun` oder `null` zurück, wenn der Lauf nicht existiert oder nicht dem Aufrufer gehört.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+Übergang in einen Terminalstatus. `succeeded` legt implizit `percent=100` fest.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+Gibt außerdem `run.progress.updated` mit dem Terminalstatus aus.
+
+### Eintrag {#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}
+
+Wird durch das Core-Routes-Plugin bei `/_agent-native/runs/*` gemountet. **Schreibgeschützt über HTTP** – Schreibvorgänge durchlaufen die Agent-Tools, da der Agent der kanonische Autor ist. Alle Routen unterliegen dem Eigentümerbereich.
+
+| Methode  | Pfad                              |
+| -------- | --------------------------------- |
+| `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-Komponente {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+Inline-Header-Widget – montieren Sie es neben der Benachrichtigungsglocke. Zeigt ein Drehsymbol und ein Zählabzeichen an, wenn Läufe aktiv sind. Durch Klicken wird ein Dropdown-Menü mit einem Live-Prozentbalken pro Lauf geöffnet. Blendet den Auslöser vollständig aus, wenn keine aktiven Ausführungen erfolgen. Fragt `/_agent-native/runs?active=true` alle `pollMs` ab (Standard 3 s). Verwendet shadcn-semantische Token, passt sich an helle und dunkle Themen an.
+
+## Agent-Tool {#agent-tool}
+
+In jeder Vorlage ist ein einzelnes `manage-progress`-Tool registriert. Der Parameter `action` wählt die Operation aus:
+
+| Aktion     | Zweck                                                                       |
+| ---------- | --------------------------------------------------------------------------- |
+| `start`    | Anruf am Anfang einer langen Aufgabe. Gibt eine runId zurück.               |
+| `update`   | Rufen Sie während der Aufgabe regelmäßig mit `percent` und/oder `step` auf. |
+| `complete` | Terminal – eines von `succeeded`, `failed`, `cancelled`.                    |
+| `list`     | Inspizieren Sie die letzten Ausführungen (Filter nach `active=true`).       |
+
+### Wann soll ein Lauf gestartet werden? {#when-to-start}
+
+- Für alles > ~5 Sekunden verwenden. Ein Spinner ohne Kontext fühlt sich eingefroren an.
+- Aktualisierung an natürlichen Prüfpunkten, nicht bei jeder Iteration. Alle 5–10 % sind ausreichend.
+- **Rufen Sie `manage-progress` immer** mit `action=complete` auf, auch in Fehlerpfaden. Eine verwaiste `running`-Zeile ist schlimmer als keine Zeile.
+- Koppeln Sie nach Abschluss mit `notify`, damit der Benutzer das Ergebnis sieht, wenn er das Fach nicht aktiv beobachtet.
+
+## Ereignisbus {#event-bus}
+
+Zwei Ereignisse werden auf dem [event bus](/docs/automations#event-bus) ausgegeben:
+
+| Ereignis               | Nutzlast                           |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) kann diese abonnieren – zum Beispiel _"Wenn ein Lauf länger als 5 Minuten dauert, benachrichtigen Sie mich"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## Wie es funktioniert {#internals}
+
+- **Owner Scoping** – jede Zeile hat eine `owner`-Spalte; Jede Abfrage filtert danach. Benutzer sehen nur ihre eigenen Läufe.
+- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
+- **Tabellenname** – das Framework verfügt außerdem über eine `agent_runs`-Tabelle für die interne Nachverfolgung des Agent-Chat-Turn-Lebenszyklus. Das Fortschrittsprimitiv verwendet `progress_runs`, um die beiden Anliegen getrennt zu halten.
+- **Prozent-Klammerung** – Werte werden auf `[0, 100]` geklemmt und beim Schreiben auf eine Ganzzahl gerundet.
+
+## Was kommt als nächstes?
+
+- [**Notifications**](/docs/notifications) – koppeln Sie es mit `manage-progress` (`action=complete`), um dem Benutzer mitzuteilen, wann die Arbeit beendet ist
+- [**Automations**](/docs/automations) – langsamer Watchdog läuft über `run.progress.updated`
+- [**Client**](/docs/client) – `useDbSync` für Echtzeit-Cache-Ungültigmachung

package/docs/content/locales/de-DE/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "Pure-Agent-Apps"
+description: "Apps, bei denen der Agent das gesamte Produkt darstellt: Die App-Agent-Schleife ist die Eingangstür, und UI wird nur hinzugefügt, wenn Menschen sie benötigen."
+---
+
+# Pure-Agent-Apps
+
+Eine reine Agent-App ist das minimale Ende von Agent-Native: Die App-Agent-Schleife ist die
+Produkt, kein Dashboard. Sie senden eine Anfrage vom Terminal, Slack, E-Mail, a
+geplanter Job, ein anderer Agent oder Chat – „meine ungelesenen E-Mails zusammenfassen“, „veröffentlichen
+tägliche Metriken an Slack“ – und der Agent handelt und gibt das Ergebnis zurück, wo immer es ist
+gehört. Es ist immer noch eine echte App: actions, Sitzungen, App-Status, Verlauf,
+Einstellungen, Anmeldeinformationen und Freigabedatensätze sind alle live in 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}"
+}
+```
+
+Greifen Sie nach dieser Form, wenn die Arbeit im Hintergrund läuft, die Ausgabe verlässt das
+app, die Domäne ist einmalig oder Sie erstellen einen Prototyp. Der Agent benötigt noch einen UI –
+kein Dashboard, sondern ein Ort, an dem Menschen es überwachen, konfigurieren und steuern können –
+weshalb auch reine Agent-Apps normalerweise die integrierte Chat-Shell bereitstellen.
+
+Dies ist die **kopflose** Produktform. Der vollständige Entscheidungsleitfaden, was im Lieferumfang enthalten ist
+Die Box, das Gerüst, der Repo-Zugriff und die Lauffreigabe sind jetzt an einem Ort verfügbar:
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## Was kommt als nächstes
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) – der vollständige Headless-Entscheidungsleitfaden und APIs
+- [**Getting Started**](/docs/getting-started) – Erstellen Sie zuerst eine Chat-App oder einen Headless-Agenten
+- [**Dispatch**](/docs/template-dispatch) – die Arbeitsbereichsvorlage, die ein großartiger Ausgangspunkt für reine Agenten ist
+- [**Messaging the agent**](/docs/messaging) – wie Benutzer mit dem Agenten über das Web, Slack, Telegram oder E-Mail kommunizieren
+- [**Recurring Jobs**](/docs/recurring-jobs) – geplante Eingabeaufforderungen, die der Agent selbstständig ausführt
+- [**Actions**](/docs/actions) – die Tools, die Ihr reiner Agent aufrufen wird