@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/de-DE/context-awareness.md

@@ -0,0 +1,373 @@
+---
+title: "Kontextbewusstsein"
+description: "Wie der Agent weiß, was der Benutzer sieht: Navigationsstatus, Auswahlkontext, Bildschirmansicht, sendToAgentChat-Übergaben, Navigationsbefehle und Jitter-Verhinderung."
+---
+
+# Kontextbewusstsein
+
+> **Entwicklerseite.** Diese Seite ist für Entwickler gedacht, die die Kontextebene der App vernetzen. Informationen zur Endbenutzererfahrung – wie der Agent diesen Kontext im Gespräch verwendet – finden Sie unter [Using Your Agent](/docs/using-your-agent).
+
+Wie der Agent weiß, was der Benutzer sieht – und wie der Agent steuern kann, was der Benutzer sieht.
+
+## Übersicht {#overview}
+
+Ohne Kontextbewusstsein ist der Agent blind. Es wird gefragt: „Welche E-Mail?“ wenn der Benutzer eines anstarrt. Es kann nicht auf die aktuelle Auswahl reagieren, keine relevanten Vorschläge bereitstellen und nicht ändern, was der Benutzer sieht. Mit Kontextbewusstsein kann der Benutzer auf eine Zeile klicken, einen Absatz hervorheben, ein Folienelement auswählen oder Befehl+I drücken und dann „Zusammenfassen“ sagen, und der Agent weiß bereits, was „dies“ bedeutet.
+
+Um zu verstehen, was in welche Oberfläche eingefügt werden muss (AGENTS.md vs. skills vs. application_state), siehe [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces).
+
+Sechs Muster lösen dieses Problem:
+
+1. **Navigationsstatus** – der UI schreibt bei jeder Routenänderung einen `navigation`-Schlüssel in den Anwendungsstatus
+2. **Aktuelles URL** – das Framework schreibt `__url__`, sodass Abfrageparameter vom Agent sichtbar und bearbeitbar sind
+3. **Auswahlstatus** – der UI schreibt einen `selection`-Schlüssel, wenn der Benutzer etwas Sinnvolles fokussiert, auswählt oder mehrfach auswählt
+4. **`view-screen`** – eine Aktion, die den Anwendungsstatus liest, Kontextdaten abruft und einen Schnappschuss dessen zurückgibt, was der Benutzer sieht
+5. **Prompte Übergabe** – UI steuert den Anruf `sendToAgentChat()`, wenn ein Klick zum Agentenwechsel werden soll
+6. **`navigate`** – ein einmaliger Befehl vom Agenten, der dem UI mitteilt, wohin er gehen soll
+
+```an-diagram title="How the agent sees what you see" summary="The UI writes lightweight state keys; view-screen hydrates them into real records; the agent can write navigate back to move the UI."
+{
+  "html": "<div class=\"diagram-ctx\"><div class=\"diagram-card col\"><span class=\"diagram-pill\">UI writes</span><div class=\"diagram-node\">navigation<br><small class=\"diagram-muted\">view, open ids</small></div><div class=\"diagram-node\">__url__<br><small class=\"diagram-muted\">shareable filters</small></div><div class=\"diagram-node\">selection<br><small class=\"diagram-muted\">rows, blocks, shapes</small></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\">view-screen</span><small class=\"diagram-muted\">reads state &middot; fetches records</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Agent acts<br><small class=\"diagram-muted\">on the real object</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box diagram-accent\">navigate<br><small class=\"diagram-muted\">agent moves the UI</small></div></div>",
+  "css": ".diagram-ctx{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-ctx .col{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-ctx .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-ctx .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Kontextebenen {#context-layers}
+
+Verwenden Sie unterschiedliche Kontextkanäle für unterschiedliche Aufgaben:
+
+| Ebene                                           | Eigentümer        | Verwenden Sie es für                                                                                                   |
+| ----------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `navigation` App-Statusschlüssel                | UI                | Semantischer Routenstatus: aktuelle Ansicht, geöffneter Datensatz, aktive Registerkarte, stabile IDs                   |
+| `__url__` App-Statusschlüssel                   | Framework UI      | Aktueller Pfadname, Suchzeichenfolge, Hash und analysierte URL-Abfrageparameter                                        |
+| `__set_url__` App-Statusschlüssel               | Agent/Framework   | Einzelne URL-Bearbeitungen von `set-search-params` und `set-url-path`                                                  |
+| `selection` App-Statusschlüssel                 | UI                | Dauerhafte semantische Auswahl: Zeilen, Blöcke, Formen, Assets, Nachrichten                                            |
+| `pending-selection-context` App-Statusschlüssel | UI / `AgentPanel` | Einmaliger ausgewählter Text, der an die nächste Chat-Runde angehängt wird, normalerweise über Cmd+I                   |
+| `view-screen`-Aktion                            | Agent             | Übertragung der App-Statusschlüssel in echte Datensätze und Bildschirmzusammenfassungen                                |
+| `sendToAgentChat()`                             | UI                | Einen Klick, einen Befehl, eine Kommentar-Pin oder ein ausgewähltes Element in eine Chat-Eingabeaufforderung umwandeln |
+| `navigate` App-Statusschlüssel                  | Agent             | Aufforderung an den UI, zu einer anderen Route zu wechseln oder ein anderes Objekt zu fokussieren                      |
+
+Die Kurzfassung: URL-Abfrageparameter sind die Quelle der Wahrheit für gemeinsam nutzbare Filter, `navigation` speichert semantische IDs und Ansichtsnamen, `view-screen` wandelt diese Zustandsebenen in nützliche Daten um und `sendToAgentChat()` wandelt die UI-Absicht in eine Chat-Nachricht um, wenn der Benutzer auf einen Befehl klickt.
+
+## Navigationsstatus {#navigation-state}
+
+Der UI schreibt bei jeder Routenänderung einen `navigation`-Schlüssel in den Anwendungsstatus. Dies teilt dem Agenten mit, in welcher Ansicht sich der Benutzer befindet, welches Element geöffnet ist und welcher semantische UI-Status wichtig ist.
+
+```json
+{
+  "view": "inbox",
+  "threadId": "thread-123",
+  "focusedEmailId": "msg-456",
+  "label": "important"
+}
+```
+
+Was in den Navigationsstatus aufgenommen werden soll:
+
+- `view` – die aktuelle Seite/der aktuelle Abschnitt, z. B. „Posteingang“, „Formular-Builder“ oder „Dashboard“
+- Artikel-IDs – der ausgewählte/offene Artikel, z. B. `threadId` oder `formId`
+- Semantische Aliase – aktive Registerkarte, Labelname oder andere stabile App-Konzepte, die dem Agenten bei der Argumentation helfen
+- Lichtfokusstatus – fokussierte Zeile, aktive Registerkarte, aktuelles Panel
+
+`navigation` klein und semantisch halten. Es sollte den aktuellen Bildschirm identifizieren und nicht ganze Datensätze duplizieren oder jeden Abfrageparameter widerspiegeln. Rufen Sie Datensätze in `view-screen` ab, damit der Agent immer aktuelle Daten erhält.
+
+Der Agent liest dies, bevor er handelt:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// { view: "inbox", threadId: "thread-123", label: "important" }
+```
+
+## Aktuelle URL und Filter {#current-url}
+
+`AgentPanel` synchronisiert automatisch den aktuellen React-Router URL mit dem `__url__`-Anwendungsstatusschlüssel. Der integrierte Agent bindet es in jeder Runde als `<current-url>`-Block ein:
+
+```text
+<current-url>
+pathname: /adhoc/revenue
+search: ?f_region=west&q=renewal
+searchParams:
+  f_region: west
+  q: renewal
+</current-url>
+```
+
+Dies ist die kanonische Ebene für den gemeinsam nutzbaren Filterstatus. Wenn der Benutzer einen URL kopieren und zur gleichen gefilterten Liste zurückkehren kann, gehört der Filter in die Abfragezeichenfolge. Der Agent kann diese Filter mit dem integrierten `set-search-params`-Tool ändern:
+
+```text
+set-search-params({ "params": { "f_region": "east", "q": null } })
+```
+
+Verwenden Sie `navigation` nur für semantische Aliase, die `view-screen` dabei helfen, die richtigen Daten abzurufen oder zusammenzufassen. Ein Dashboard behält möglicherweise `navigation.dashboardId` bei, während `__url__.searchParams` `f_region`, `f_dateStart` und `q` besitzt.
+
+Wenn `view-screen` einen umfangreicheren Snapshot zurückgibt, können wichtige URL-Filter in ein benutzerfreundliches `activeFilters`-Objekt kopiert werden:
+
+```ts
+const url = (await readAppState("__url__")) as {
+  searchParams?: Record<string, string>;
+} | null;
+
+if (url?.searchParams) {
+  screen.activeFilters = Object.fromEntries(
+    Object.entries(url.searchParams).filter(
+      ([key, value]) => key.startsWith("f_") && value,
+    ),
+  );
+}
+```
+
+## Auswahlstatus {#selection-state}
+
+Auswahl ist semantischer UI-Zustand. Auf diese Weise werden „das Diagramm, auf das ich geklickt habe“, „diese drei Zeilen“, „dieser Folientitel“ oder „der aktuelle E-Mail-Entwurfsbereich“ zum modellsichtbaren Kontext.
+
+Verwenden Sie den `selection`-App-Statusschlüssel für eine dauerhafte Auswahl, die einen Moment der Navigation, leere Chat-Vorschläge oder einen späteren `view-screen`-Aufruf überstehen sollte:
+
+```json
+{
+  "kind": "slide.elements",
+  "deckId": "deck-123",
+  "slideId": "slide-4",
+  "items": [
+    {
+      "id": "hero-title",
+      "selector": "[data-block-id='hero-title']",
+      "label": "Hero title",
+      "text": "Q3 launch plan"
+    }
+  ],
+  "capturedAt": 1780332977027
+}
+```
+
+Schreiben Sie es aus UI, wenn der Benutzer bedeutungsvolle Objekte auswählt, fokussiert oder mehrfach auswählt:
+
+```tsx
+import { setClientAppState } from "@agent-native/core/client";
+
+async function syncSelection(selection: unknown | null) {
+  await setClientAppState("selection", selection, { keepalive: true });
+}
+```
+
+Ein guter Auswahlstatus umfasst:
+
+- Stabile IDs, die der Agent in actions verwenden kann, wie z. B. `threadId`, `slideId` oder `assetId`
+- Eine kurze menschliche Bezeichnung, damit Eingabeaufforderungen und Vorschläge lesbar sind
+- Genügend Text oder Metadaten, um das Objekt eindeutig zu machen
+- Optionale UI-Locators wie Selektoren oder Koordinaten, wenn der Agent auf ein visuelles Element zurückgreifen muss
+- `capturedAt`, wenn eine veraltete Auswahl schädlich wäre
+
+Vermeiden Sie das Speichern von Geheimnissen, vollständigen Dokumenten, großen binären Nutzlasten oder ganzen API-Antworten in `selection`. Speichern Sie IDs und kurze Auszüge und lassen Sie dann `view-screen` die aktuelle Quelle der Wahrheit abrufen.
+
+### Einmal ausgewählter Text {#pending-selection-context}
+
+`AgentPanel` übernimmt bereits den allgemeinen Textauswahlfluss. Wenn der Benutzer bei ausgewähltem Text auf der Seite Befehl+I (oder Strg+I) drückt, geschieht Folgendes:
+
+1. Liest `window.getSelection()`
+2. Schreibt `{ text, capturedAt }` in `pending-selection-context`
+3. Konzentriert den Agenten-Chat
+
+Der Produktionsagent fügt diesen Schlüssel als unmittelbaren Auswahlkontext in die nächste Runde ein und ignoriert ihn, sobald er veraltet ist. Dies ist der Pfad, der dafür sorgt, dass „Text auswählen, Cmd+I drücken, fragen, dies ausdrucksstärker machen“ funktioniert, ohne dass der Benutzer die Auswahl in die Eingabeaufforderung kopiert.
+
+Benutzerdefinierte Editoren können denselben Schlüssel schreiben, wenn ihre Auswahl nicht durch die native Browserauswahl repräsentiert wird:
+
+```tsx
+import { setClientAppState } from "@agent-native/core/client";
+
+await setClientAppState(
+  "pending-selection-context",
+  {
+    text: selectedMarkdown,
+    capturedAt: Date.now(),
+  },
+  { keepalive: true },
+);
+```
+
+Verwenden Sie `pending-selection-context` für einmalige Abläufe „Auf genau diesen hervorgehobenen Text reagieren“. Verwenden Sie `selection` für eine dauerhafte Objektauswahl, die `view-screen` und dynamische Vorschläge weiterhin sehen sollten.
+
+## Die Bildschirmaktion {#view-screen-action}
+
+Jede Vorlage sollte eine `view-screen`-Aktion haben. Es liest den Navigations- und Auswahlstatus, ruft die relevanten Daten ab und gibt eine Momentaufnahme dessen zurück, was der Benutzer sieht. Das sind die Augen des Agenten.
+
+```an-annotated-code title="view-screen — the agent's eyes"
+{
+  "filename": "actions/view-screen.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { readAppState } from \"@agent-native/core/application-state\";\nimport { eq, inArray } from \"drizzle-orm\";\nimport { z } from \"zod\";\nimport { getDb, schema } from \"../server/db/index.js\";\n\nexport default defineAction({\n  description:\n    \"See what the user is currently looking at on screen.\",\n  schema: z.object({}),\n  http: false,\n  run: async () => {\n    const navigation = (await readAppState(\"navigation\")) as any;\n    const selection = (await readAppState(\"selection\")) as any;\n    const screen: Record<string, unknown> = {};\n    if (navigation) screen.navigation = navigation;\n    if (selection) screen.selection = selection;\n\n    const db = getDb();\n\n    // Fetch data based on what the user is viewing\n    if (navigation?.view === \"inbox\") {\n      screen.emailList = await db\n        .select()\n        .from(schema.emails)\n        .where(eq(schema.emails.label, navigation.label));\n    }\n    if (navigation?.threadId) {\n      screen.thread = await db\n        .select()\n        .from(schema.threads)\n        .where(eq(schema.threads.id, navigation.threadId));\n    }\n    if (selection?.kind === \"email.messages\") {\n      screen.selectedMessages = await db\n        .select()\n        .from(schema.emails)\n        .where(inArray(schema.emails.id, selection.messageIds));\n    }\n\n    if (Object.keys(screen).length === 0) {\n      return \"No application state found. Is the app running?\";\n    }\n    return screen;\n  },\n});",
+  "annotations": [
+    { "lines": "10-11", "label": "Tool surface", "note": "The agent reads this description to know it can call `view-screen` to see the current UI." },
+    { "lines": "13", "label": "http: false", "note": "Internal action — not exposed over HTTP. The agent and `pnpm action` call it, not the browser." },
+    { "lines": "15-16", "label": "Read state", "note": "Pulls the lightweight `navigation` and `selection` keys the UI wrote." },
+    { "lines": "23-37", "label": "Hydrate", "note": "Turns those IDs into **fresh** records straight from SQL, so the agent verifies the live object before acting." }
+  ]
+}
+```
+
+Der Agent sollte `pnpm action view-screen` aufrufen, bevor er auf den aktuellen UI reagiert. Dies ist eine strenge Konvention für alle Vorlagen. Wenn Sie neue Funktionen hinzufügen, aktualisieren Sie `view-screen`, um Daten für die neue Ansicht und alle neuen Auswahlformen zurückzugeben.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Keep `navigation` and `selection` small.** Store IDs plus short labels, not whole records. `view-screen` fetches the source of truth on demand, so stale or bulky state never reaches the agent."
+}
+```
+
+## Prompte Übergabe mit `sendToAgentChat()` {#send-to-agent-chat}
+
+Manchmal sollte der Kontext nicht nur im App-Status verbleiben. Ein Benutzer klickt auf eine Schaltfläche, hinterlässt eine Kommentarnadel, wählt ein Element aus und wählt „Agenten fragen“ oder drückt einen KI-Befehl in einer Symbolleiste. Dieser Klick ist eine Anweisung. Übergeben Sie es im Browser UI mit `sendToAgentChat()`.
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+function askAgentAboutSelection(selection: {
+  documentId: string;
+  blockId: string;
+  label: string;
+  text: string;
+}) {
+  sendToAgentChat({
+    message: `Improve the selected block: ${selection.label}`,
+    context: [
+      `Document id: ${selection.documentId}`,
+      `Block id: ${selection.blockId}`,
+      "Current selected text:",
+      selection.text,
+    ].join("\n"),
+    submit: false,
+    openSidebar: true,
+  });
+}
+```
+
+Verwenden Sie die Felder bewusst:
+
+| Feld                | Bedeutung                                                                                                         |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `message`           | Sichtbarer Aufforderungstext wird im Chat angezeigt                                                               |
+| `context`           | Versteckter, für das Modell sichtbarer Kontext, der nicht als für den Benutzer sichtbarer Chattext angezeigt wird |
+| `submit: true`      | Sofort senden; gut für explizite Befehlsschaltflächen wie „Layout korrigieren“                                    |
+| `submit: false`     | Vorausfüllen zur Benutzerüberprüfung; Gut für „Fragen Sie den Agenten danach“ oder mehrdeutige Auswahlen          |
+| `openSidebar: true` | Machen Sie die Antwort des Agenten sichtbar, auch wenn das Bedienfeld ausgeblendet war                            |
+| `newTab: true`      | Starten Sie einen separaten Chat-Thread für eine größere Erstellungsaufgabe                                       |
+| `type: "code"`      | Weiterleitung zum Codebearbeitungs-Frame, wenn es bei der Anfrage darum geht, die App-Quelle zu ändern            |
+
+`sendToAgentChat()` ist der unterstützte Browser-Wrapper für den Pfad des übermittelten Chats, der intern manchmal als `agentNative.submitChat` angezeigt wird. Die App UI sollte den Wrapper aufrufen, anstatt `agentNative.submitChat` direkt zu veröffentlichen, da der Wrapper lokale Seitenleisten, Builder/Frame-Routing, MCP-App-Host-Routing, Tab-IDs und Code-Anfrage-Routing verarbeitet.
+
+Verwenden Sie `agentChat.submit()` oder `agentChat.prefill()` für Knoten-/Skriptkontexte, in denen es keine Browser-Seitenleiste gibt. Der Server actions sollte im Allgemeinen nicht den reinen Browser `sendToAgentChat()` aufrufen. Wenn eine Aktion das offene UI benötigt, um den Agenten etwas zu fragen, schreiben Sie eine kleine Anfrage in `application_state` und lassen Sie sie von einer UI-Brücke vom Browser senden.
+
+### Auf Elemente in der Eingabeaufforderung geklickt {#clicked-items-in-prompt}
+
+Für die Erfahrung „Klicken Sie auf Elemente im UI und sie werden Teil der Eingabeaufforderung“ kombinieren Sie den Auswahlstatus mit der Eingabeaufforderungsübergabe:
+
+1. Schreiben Sie beim Klicken oder bei der Mehrfachauswahl den semantischen `selection`-Status, damit `view-screen`, dynamische Vorschläge und zukünftige Runden ihn sehen können.
+2. Wenn der Klick auch ein Befehl ist, rufen Sie `sendToAgentChat()` mit einem prägnanten sichtbaren `message` und einem reichhaltigeren versteckten `context` auf.
+3. Führen Sie in `view-screen` die ausgewählten IDs in aktuelle Datensätze ein, damit der Agent das Objekt überprüfen kann, bevor er es mutiert.
+4. Clear `selection` when the object is no longer selected, deleted, or no longer relevant.
+
+Das gibt dem Benutzer das magische „Das habe ich gemeint“-Verhalten, ohne jede Eingabeaufforderung mit sperrigem, sichtbarem Kontext zu füllen.
+
+## Die Navigationsaktion {#navigate-action}
+
+`navigate` ist das Spiegelbild von `navigation`. Dabei ist `navigation` der UI, der dem Agenten mitteilt, wo sich der Benutzer befindet, und `navigate` der Agent, der dem UI mitteilt, wohin er gehen soll. Der Agent schreibt einen einmaligen `navigate`-Befehl in den Anwendungsstatus. Der UI liest ihn, führt die Navigation durch und löscht dann den Eintrag.
+
+```ts
+// Agent side -- write a navigate command
+import { writeAppState } from "@agent-native/core/application-state";
+
+await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
+```
+
+Auf der UI-Seite sollten Sie diesen Schlüssel niemals manuell abfragen oder löschen. Beide Richtungen – das Schreiben von `navigation` bei jeder Routenänderung und das Verwenden des `navigate`-Befehls des Agenten – werden von einem einzigen Hook, [`useNavigationState`](#use-navigation-state), verarbeitet, der im nächsten Abschnitt behandelt wird.
+
+Der `navigation`-Schlüssel gehört zum UI; Der Agent darf niemals direkt darauf schreiben. Der Agent schreibt `navigate`, der UI führt die Verschiebung durch, und diese Verschiebung aktualisiert `navigation`.
+
+Wenn das Ziel einen echten URL hat, fügen Sie einen `path` mit demselben Ursprung hinzu
+`navigate`-Befehl und veranlassen Sie, dass UI diesen Pfad bevorzugt, bevor auf ihn zurückgegriffen wird
+semantische Felder. Sorgen Sie dafür, dass die App-Navigation einkanalig ist: Schreiben Sie nicht beides
+`navigate` und `__set_url__` für denselben Zug. `__set_url__` ist für die
+Framework URL-Tools (`set-url-path`, `set-search-params`) und reiner URL-Filter
+Änderungen. Für Befehle, die während des Chat-Streamings eintreffen können, schreiben Sie die Route fest
+mit `navigate(path, { replace: true, flushSync: true })`, anstatt es zu umschließen
+in einem Ansichtsübergang, damit die Adressleiste und die sichtbare Seite zusammen bleiben.
+
+## Der useNavigationState-Hook {#use-navigation-state}
+
+`useNavigationState` ist **der Hook Ihrer App, kein Framework-Import.** Jede Vorlage liefert eine unter `app/hooks/use-navigation-state.ts` und ruft sie einmal aus der App-Shell (`root.tsx`) auf. Es ist der einzige Ort, der die Navigation in beide Richtungen verbindet:
+
+- **Ausgehend (UI → Agent):** schreibt den Schlüssel `navigation`, wenn sich die Route ändert, sodass der Agent immer die aktuelle Ansicht kennt.
+- **Eingehend (Agent → UI):** fragt den `navigate`-Befehl ab, führt die Navigation aus und löscht den Befehl.
+
+Es bleibt kurz, weil es ein dünner Wrapper um das eigentliche Framework-Grundelement `useAgentRouteState` (exportiert aus `@agent-native/core/client`) ist. Sie stellen zwei app-spezifische Funktionen bereit und das Framework erledigt den Rest:
+
+```tsx
+// app/hooks/use-navigation-state.ts -- this file lives in YOUR app
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+interface NavigationState {
+  view: "inbox" | "thread";
+  threadId?: string;
+  path?: string;
+}
+
+export function useNavigationState() {
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+
+    // UI → agent: derive semantic state from the current URL.
+    getNavigationState: ({ pathname }) => {
+      const match = pathname.match(/^\/thread\/([^/]+)/);
+      return match ? { view: "thread", threadId: match[1] } : { view: "inbox" };
+    },
+
+    // agent → UI: turn a `navigate` command into a route to push.
+    getCommandPath: (command) =>
+      command.path ??
+      (command.view === "thread" && command.threadId
+        ? `/thread/${command.threadId}`
+        : "/"),
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+| Du schreibst                                                         | Das Framework behandelt                                                                               |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `getNavigationState` – ordnet URL dem semantischen Zustand zu        | `navigation` schreibt, tabulatorgesteuert und mit einem globalen Fallback-Schlüssel                   |
+| `getCommandPath` – Ordnen Sie einen `navigate`-Befehl einer Route zu | Befehlsabfrage, Löschen nach dem Lesen, Schutz vor doppelten Befehlen, Tagging der Anforderungsquelle |
+
+`useAgentRouteState` geht vom React-Router aus. Wenn die Navigation nicht im URL erfolgt – ein Assistentenschritt, eine Canvas-Auswahl, eine Nicht-Router-Shell –, wechseln Sie stattdessen zur untergeordneten `useSemanticNavigationState`: Sie übergeben ihr einen vorgefertigten `state`-Wert plus `navigationKeys`/`commandKeys` und einen `onCommand`-Rückruf, und sie bleibt völlig unabhängig vom React-Router.
+
+## Jitter-Verhinderung {#jitter-prevention}
+
+Wenn der Agent in den Anwendungsstatus schreibt, kann das Synchronisierungssystem dazu führen, dass UI die gerade geschriebenen Daten erneut abruft. Dadurch entsteht Jitter. Die Lösung ist Quell-Tagging:
+
+Verwenden Sie `setClientAppState`, `writeClientAppState`, `readClientAppState` und `deleteClientAppState` von `@agent-native/core/client` für den browserseitigen Zugriff auf den Anwendungsstatus. Übergeben Sie `{ requestSource: TAB_ID }` an UI-Schreibvorgänge, wenn Sie mit `useDbSync({ ignoreSource: TAB_ID })` koppeln. Übergeben Sie `{ keepalive: true }` für kurzlebige Schreibvorgänge, z. B. die Auswahlbereinigung während des Entladens.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID, // ignore events from this tab's own writes
+});
+```
+
+So funktioniert es:
+
+- Agent-Schreibvorgänge sind mit `requestSource: "agent"` gekennzeichnet (die Aktionshelfer führen dies automatisch durch)
+- UI-Schreibvorgänge enthalten die eindeutige ID der Registerkarte über den `X-Request-Source`-Header
+- Der Server speichert die Quelle für jedes Ereignis
+- Bei der Verarbeitung von Synchronisierungsereignissen filtert der UI Ereignisse heraus, die seinem eigenen `ignoreSource`-Wert entsprechen – sodass er die Daten, die er gerade geschrieben hat, nicht erneut abruft.
+- Ereignisse von Agenten, anderen Registerkarten und actions kommen weiterhin normal durch
+
+```an-diagram title="Source tagging stops self-refetch jitter" summary="A tab ignores sync events stamped with its own TAB_ID, but still reacts to agent and other-tab writes."
+{
+  "html": "<div class=\"diagram-jitter\"><div class=\"diagram-node\">This tab writes<br><small class=\"diagram-muted\">X-Request-Source: TAB_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Server stores source<br>on the event</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill warn\">source == TAB_ID &rarr; ignored</div><small class=\"diagram-muted\">no refetch, no flicker</small><div class=\"diagram-pill ok\">agent / other tab &rarr; applied</div><small class=\"diagram-muted\">UI updates live</small></div></div>",
+  "css": ".diagram-jitter{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jitter .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-jitter .diagram-arrow{font-size:22px;line-height:1}"
+}
+```