@delofarag/ai-utils 1.5.0 → 1.7.0

package/README.md

@@ -2,9 +2,10 @@
 
 Ein praktisches Utility-Package für LLM-Apps mit LangChain:
 
-- `Chain`, `MemoryChain`, `Agent`
+- `Chain`, `Agent`, `DeepAgent` (Filesystem, HITL, Sandboxes, Subagents)
+- Memory via Checkpoint-Saver (`MemorySaver`, `SmartCheckpointSaver`, `SupabaseCheckpointSaver`)
 - RAG-Helper (FAISS, Supabase, In-Memory)
-- Tooling (`ToolRegistry`, `createRAGTool`, `tavilySearchTool`)
+- Tooling (`ToolRegistry`, `CombinedToolRegistry`, `ZodiosToolRegistry`, `createRAGTool`, `tavilySearchTool`)
 - Magic-Funcs (Parser, Evaluator, Optimizer, Answerer)
 - Modalities (STT, TTS, Vision, Image Generation)
 
@@ -19,7 +20,7 @@ Im Package gilt als Standard-LLM-Default für die allgemeine Nutzung:
 
 Wenn du nichts explizit setzt, orientiere dich an diesem Default in deinen Aufrufen.
 
-Für modality-spezifische Flows (`stt`, `tts`, `vision`, `image-gen`) wird zusätzlich mit `type` gearbeitet, damit passende Modelle gewählt werden koennen.
+Für modality-spezifische Flows (`stt`, `tts`, `vision`, `image-gen`) wird zusätzlich mit `type` gearbeitet, damit passende Modelle gewählt werden können.
 
 ---
 
@@ -29,6 +30,12 @@ Für modality-spezifische Flows (`stt`, `tts`, `vision`, `image-gen`) wird zusä
 npm i @delofarag/ai-utils
 ```
 
+Peer dependency für Supabase-Features:
+
+```bash
+npm i @delofarag/supabase-utils
+```
+
 ---
 
 ## Environment Variables
@@ -44,12 +51,12 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY=...
 SUPABASE_SERVICE_ROLE_KEY=...
 ```
 
-### Welche Variable wofuer?
+### Welche Variable wofür?
 
 - `OPENROUTER_API_KEY`: OpenRouter-Modelle und Modalities
 - `CHATGROQ_API_KEY`: wenn du `provider: "chatgroq"` nutzt
 - `TAVILY_API_KEY`: `websearch()` / `tavilySearchTool`
-- Supabase-Variablen: fuer `createSupabaseVectoreStore()` und `getSupabaseVectorStore()`
+- Supabase-Variablen: für `createSupabaseVectoreStore()`, `getSupabaseVectorStore()` und `SupabaseCheckpointSaver`
 
 ---
 
@@ -78,19 +85,27 @@ getLLM({ provider: "openrouter", type: "vision" })
 getLLM({ provider: "openrouter", type: "image-gen" })
 ```
 
+EU-Datenrouting (OpenRouter):
+
+```ts
+getLLM({ provider: "openrouter", dataSafe: true })
+```
+
 ---
 
 ## Core Classes
 
+> **DeepAgent-Dokumentation:** Abschnitt [3) DeepAgent](#3-deepagent) — Feature-Übersicht, Backend, HITL, Stream-Chunks, CLI-Testing.
+
 ## 1) `Chain`
 
-Stateless LLM-Chain fuer strukturierte Ergebnisse.
+Stateless LLM-Chain für strukturierte Ergebnisse. Kein Memory — `thread_id` wird ignoriert.
 
-### Besseres Praxisbeispiel (custom output schema)
+### Custom Output Schema
 
 ```ts
 import { Chain, getLLM } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+import { z } from "zod/v4"
 
 const productBriefSchema = z.object({
     title: z.string().describe("Kurzer Produktname"),
@@ -106,7 +121,7 @@ const chain = new Chain({
 })
 
 const result = await chain.invoke({
-    product: "AI-Notizapp fuer Teams",
+    product: "AI-Notizapp für Teams",
     market: "DACH SaaS"
 })
 ```
@@ -115,7 +130,7 @@ const result = await chain.invoke({
 
 ```ts
 import { Chain, createFaissStore } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+import { z } from "zod/v4"
 
 const vectorStore = await createFaissStore(["Dokument A", "Dokument B"])
 
@@ -130,121 +145,560 @@ await chain.addContext(["Dokument C"])
 const answer = await chain.invoke({ question: "Was steht in Dokument C?" })
 ```
 
+### Streaming
+
+```ts
+for await (const chunk of chain.stream({ question: "Erkläre das kurz." })) {
+    process.stdout.write(chunk)
+}
+```
+
 ---
 
-## 2) `MemoryChain`
+## 2) `Agent`
 
-`Chain` + Conversation Memory ueber `thread_id`.
+Tool-using Agent auf Basis von `createReactAgent`. Unterstützt optional Checkpointer (Thread-State) und strukturierten Output.
 
 ### Basis
 
 ```ts
-import { MemoryChain, getLLM } from "@delofarag/ai-utils"
+import { Agent, ToolRegistry, getLLM } from "@delofarag/ai-utils"
+import { z } from "zod/v4"
+
+const tools = new ToolRegistry([
+    {
+        name: "sum",
+        description: "Addiert zwei Zahlen",
+        schema: z.object({ a: z.number(), b: z.number() }),
+        func: ({ a, b }) => a + b
+    }
+]).allTools
 
-const memoryChain = new MemoryChain({
+const agent = new Agent({
     llm: getLLM({ provider: "openrouter", model: "openai/gpt-5.4-mini" }),
-    prompt: "Du bist ein hilfreicher Assistent."
+    prompt: "Du darfst Tools nutzen wenn nötig.",
+    tools
 })
 
-await memoryChain.invoke({ thread_id: "u1", input: "Ich heisse Max." })
-const r2 = await memoryChain.invoke({ thread_id: "u1", input: "Wie heisse ich?" })
+const result = await agent.invoke({ input: "Was ist 8 + 13?" })
 ```
 
-### RAG mit `MemoryChain`
+### Checkpointer mit `Agent`
+
+Conversation State läuft über Checkpoint-Saver + `thread_id`:
 
 ```ts
-import { MemoryChain, createFaissStore } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+import { Agent, MemorySaver, SmartCheckpointSaver, getLLM } from "@delofarag/ai-utils"
+
+const checkpointer = new SmartCheckpointSaver(new MemorySaver(), {
+    llm: getLLM({ provider: "openrouter" }),
+    messagesBeforeSummary: 12,
+    maxSummaries: 7
+})
 
-const vectorStore = await createFaissStore(["Policy A", "Policy B"])
+const agent = new Agent({
+    tools: [...],
+    prompt: "Du bist ein hilfreicher Assistent.",
+    checkpointer
+})
 
-const memoryChain = new MemoryChain({
-    prompt: "Nutze Kontext und Gespraechshistorie.",
+await agent.invoke({ thread_id: "u1", input: "Ich heisse Max." })
+const r2 = await agent.invoke({ thread_id: "u1", input: "Wie heisse ich?" })
+```
+
+### Strukturierter Output
+
+```ts
+const agent = new Agent({
+    tools,
+    output: z.object({
+        answer: z.string(),
+        confidence: z.number()
+    })
+})
+
+const result = await agent.invoke({ input: "Analysiere das..." })
+// result: { answer: string, confidence: number }
+```
+
+### RAG als Tool
+
+```ts
+import { Agent, createRAGTool, createFaissStore } from "@delofarag/ai-utils"
+
+const vectorStore = await createFaissStore(["Release Notes 2026-04", "Known Issues"])
+const ragTool = createRAGTool({
     vectorStore,
-    output: z.object({ output: z.string() })
+    name: "search_docs",
+    description: "Sucht relevante Produktdokumente"
 })
 
-const response = await memoryChain.invoke({
-    thread_id: "support-77",
-    question: "Welche Regel steht in Policy B?"
+const agent = new Agent({
+    prompt: "Nutze search_docs für faktenbasierte Antworten.",
+    tools: [ragTool]
 })
 ```
 
+### Streaming
+
+```ts
+for await (const chunk of agent.stream({ input: "Erkläre mir das.", thread_id: "u1" })) {
+    process.stdout.write(chunk)
+}
+```
+
 ---
 
-## 3) `Agent`
+## 3) `DeepAgent`
+
+LangChain Deep Agent (`createDeepAgent()`) als typisierte Wrapper-Klasse. Für autonome Tasks mit Filesystem, Planning, Subagents und optional Sandboxes.
+
+### DeepAgent auf einen Blick
+
+| Feature | Kurz erklärt |
+|---|---|
+| **Filesystem-Tools** | `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` (built-in) |
+| **Custom Tools** | Eigene Tools via `ToolRegistry` / `DynamicStructuredTool` |
+| **`execute`** | Shell-Befehle — nur mit Shell/Sandbox-Backend (`createLocalShellBackend`, Deno, Daytona) |
+| **`backend`** | Wo Dateien physisch liegen + wie der Agent Pfade sieht |
+| **`permissions`** | Statische FS-Regeln (allow/deny) — **kein** User-Dialog |
+| **`interruptOn`** | Human-in-the-Loop — pausiert **vor** Tool-Ausführung, User entscheidet |
+| **`checkpointer` + `thread_id`** | Conversation-State über Runs hinweg (Pflicht für HITL) |
+| **`invoke` / `stream`** | Gleiche API für Message **und** HITL-Resume via `decision` |
+| **`showToolCalls`** | Streamt `[tool:start]` / `[tool:end]` Events (nur `stream()`) |
+| **`agentsMd`** | AGENTS.md-Dateien als Startup-Kontext |
+| **`subagents`** | Delegation an spezialisierte Sub-Agents |
+| **`skills`** | Skill-Dateien vom Backend laden |
+| **`output`** | Optional strukturierter Zod-Output |
+
+### Wann `DeepAgent` statt `Agent`?
+
+| | `Agent` | `DeepAgent` |
+|---|---|---|
+| Tool-using ReAct | ja | ja |
+| Built-in Filesystem | nein | ja |
+| Backend / Sandbox | nein | ja |
+| Subagents / Skills | nein | ja |
+| HITL (`interruptOn`) | nein | ja |
+| Typischer Use-Case | Chatbots, API-Tools | Coding Agents, autonome Tasks |
 
-Tool-using Agent auf Basis von `createReactAgent`.
+---
 
-### Basis
+### Alle Props
+
+`DeepAgent` wrappt intern LangChains `createDeepAgent()`. Die Tabelle unten listet die Props, die du über `@delofarag/ai-utils` setzt — für den **vollen Einblick aller nativen Parameter** (z. B. `cache`, `debug`, Middleware-Details, Backend-Protokolle) in die **LangChain Deep Agents Docs** schauen:
+
+- [Deep Agents Overview](https://docs.langchain.com/oss/javascript/deepagents/overview)
+- [`createDeepAgent()` Reference (JS)](https://reference.langchain.com/javascript/deepagents/agent/createDeepAgent)
+
+Einige Namen weichen in ai-utils ab: `prompt` → `systemPrompt`, `agentsMd` → `memory`, `interruptOn` → `interrupt_on`.
 
 ```ts
-import { Agent, ToolRegistry, getLLM } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+new DeepAgent({
+    prompt,           // string | string[] — System-Prompt(s)
+    llm,              // BaseChatModel (Default: OpenRouter gpt-5.4-mini)
+    tools,            // readonly DynamicStructuredTool[] (z.B. ToolRegistry.allTools)
+    output,           // Zod-Schema für strukturierten Output
+    checkpointer,     // BaseCheckpointSaver | boolean (Default: MemorySaver)
+    backend,          // DeepAgentBackend — siehe Backend-Abschnitt
+    permissions,      // FilesystemPermission[] — statische FS-Regeln
+    interruptOn,      // pro Tool: decisions + question (HITL)
+    agentsMd,         // string[] — Pfade zu AGENTS.md
+    subagents,        // SubAgent[]
+    skills,           // string[] — Skill-Pfade relativ zum Backend
+    middleware,       // AgentMiddleware[]
+    store,            // BaseStore — LangGraph Store
+    name,             // Agent-Name
+    contextSchema,    // Runtime-Context-Schema
+})
+```
+
+**Wichtig:** `backend` erwartet eine **Instanz** (oder Factory) — kein `Promise`. Async Backends vorher mit `await` erstellen:
+
+```ts
+// ❌ backend: createLocalShellBackend({ ... })
+// ✅ backend: await createLocalShellBackend({ ... })
+```
+
+Typ: `DeepAgentBackend` (= native deepagents `AnyBackendProtocol | Factory`).
+
+---
+
+### Basis: Coding Agent mit isoliertem Workspace
+
+```ts
+import path from "node:path"
+import {
+    DeepAgent,
+    createLocalShellBackend,
+    workspacePermissions,
+    ToolRegistry,
+    MemorySaver,
+    getLLM,
+} from "@delofarag/ai-utils"
+import { z } from "zod/v4"
 
 const tools = new ToolRegistry([
     {
-        name: "sum",
-        description: "Addiert zwei Zahlen",
-        schema: z.object({ a: z.number(), b: z.number() }),
-        func: ({ a, b }) => a + b
-    }
+        name: "get_weather",
+        description: "Wetter für eine Stadt",
+        schema: z.object({ city: z.string() }),
+        func: async ({ city }) => `${city}: sonnig`,
+    },
 ]).allTools
 
-const agent = new Agent({
+const agent = new DeepAgent({
     llm: getLLM({ provider: "openrouter", model: "openai/gpt-5.4-mini" }),
-    prompt: "Du darfst Tools nutzen wenn noetig.",
-    tools
+    prompt: "Du bist ein Coding Agent. Arbeite nur im Workspace.",
+    tools,
+    checkpointer: new MemorySaver(),
+    backend: await createLocalShellBackend({
+        rootDir: path.join(process.cwd(), "coding_space"),
+        route: "/workspace/",
+    }),
+    permissions: workspacePermissions("/workspace/"),
 })
 
-const result = await agent.invoke({ input: "Was ist 8 + 13?" })
+const answer = await agent.invoke({
+    input: "Erstelle eine kleine HTML-Seite",
+    thread_id: "session-1",
+})
 ```
 
-### RAG mit `Agent` (als Tool)
+---
+
+### Backend: `rootDir` vs `route`
+
+Zwei getrennte Konzepte — oft verwechselt:
+
+| Prop | Bedeutung | Beispiel |
+|---|---|---|
+| **`rootDir`** | Echter Ordner auf der Festplatte | `"./coding_space"` oder absoluter Pfad |
+| **`route`** | Virtueller Pfad, den der **Agent sieht** | `"/workspace/"` |
+
+Mapping:
+
+```
+Agent schreibt:  /workspace/index.html
+                         ↓
+Physisch auf Disk: coding_space/index.html
+```
+
+Der Agent kennt `coding_space` nicht — nur `/workspace/`. Du entscheidest mit `rootDir`, wo Dateien wirklich landen.
+
+**Relative Pfade für `rootDir` funktionieren** — deepagents resolved sie via `path.resolve(rootDir)`.
+
+---
+
+### Backend-Helper
+
+| Helper | Async? | `execute`? | Wofür |
+|---|---|---|---|
+| `createStateBackend()` | nein | nein | Ephemeral — Dateien nur im Agent-State |
+| `createFilesystemBackend({ rootDir })` | nein | nein | Direktes FS ohne StateBackend |
+| `createWorkspaceBackend({ rootDir, route? })` | nein | nein | StateBackend + FS unter `route` (empfohlen für reines Coden) |
+| `createLocalShellBackend({ rootDir, route? })` | **ja** | **ja** | Wie Workspace + Shell auf Host (**nur Dev**) |
+| `createDenoSandbox()` | **ja** | ja | Isolierte Deno-Sandbox |
+| `createDaytonaSandbox()` | **ja** | ja | Isolierte Daytona-Sandbox |
 
 ```ts
-import { Agent, ToolRegistry, createRAGTool, createFaissStore } from "@delofarag/ai-utils"
+// Reines Filesystem (kein Shell)
+backend: createWorkspaceBackend({
+    rootDir: path.join(process.cwd(), "coding_space"),
+    route: "/workspace/",
+})
 
-const vectorStore = await createFaissStore(["Release Notes 2026-04", "Known Issues"])
-const ragTool = createRAGTool({
-    vectorStore,
-    name: "search_docs",
-    description: "Sucht relevante Produktdokumente"
+// Mit Shell (Dev only — execute läuft auf dem Host!)
+backend: await createLocalShellBackend({
+    rootDir: path.join(process.cwd(), "coding_space"),
+    route: "/workspace/",
 })
+```
 
-const registry = new ToolRegistry([
-    {
-        name: "search_docs",
-        description: "Sucht relevante Produktdokumente",
-        schema: ragTool.schema as any,
-        func: ragTool.func as any
+---
+
+### `permissions` vs `interruptOn`
+
+Zwei verschiedene Sicherheitsmechanismen:
+
+| | `permissions` | `interruptOn` |
+|---|---|---|
+| **Was** | Statische Regeln | User-Dialog vor Tool-Ausführung |
+| **Wann** | Sofort beim Tool-Call | Pause + warte auf Entscheidung |
+| **Tools** | Nur FS: `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` | Alle konfigurierten Tools inkl. Custom + `execute` |
+| **`execute`** | Wird **nicht** enforced | Kann konfiguriert werden |
+
+Helper für `permissions`:
+
+```ts
+import { workspacePermissions, allowRead, denyWrite } from "@delofarag/ai-utils"
+
+permissions: workspacePermissions("/workspace/")
+// = lesen + schreiben nur unter /workspace/**, sonst deny
+```
+
+---
+
+### Built-in Filesystem-Tools
+
+DeepAgent bringt diese Tools automatisch mit (via deepagents Middleware):
+
+- `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`
+- `execute` — nur wenn Backend Shell/Sandbox unterstützt
+
+Custom Tools aus `ToolRegistry` kommen dazu. Für `interruptOn`-Autocomplete werden alle verfügbaren Tool-Namen typisiert.
+
+---
+
+### `invoke()` — Message und HITL-Resume in einer API
+
+**Normale Message:**
+
+```ts
+const result = await agent.invoke({
+    input: "Analysiere die Codebase",
+    thread_id: "u1",
+})
+// result: string (oder Zod-Output wenn output gesetzt)
+```
+
+**Nach Interrupt — Resume:**
+
+```ts
+let result = await agent.invoke({ input: "Schreib eine Datei", thread_id: "u1" })
+
+if (typeof result === "object" && result.kind === "interrupt") {
+    result = await agent.invoke({
+        thread_id: "u1",
+        decision: "approve",
+    })
+}
+```
+
+**Entscheidungs-Typen (`DeepAgentUserDecision`):**
+
+```ts
+"approve"
+"reject"
+{ type: "reject", message: "Zu gefährlich" }
+{ type: "edit", args: { file_path: "/workspace/safe.txt", content: "..." } }
+```
+
+**Mehrere parallele Tool-Calls (Batch-Interrupt):**
+
+```ts
+await agent.invoke({
+    thread_id: "u1",
+    decisions: ["approve", "approve"],
+})
+```
+
+Regeln:
+- `thread_id` **Pflicht** wenn `checkpointer` gesetzt
+- `decision`/`decisions` und `input` **nicht gleichzeitig**
+- `checkpointer` **Pflicht** für HITL-Resume
+
+---
+
+### Human-in-the-Loop (`interruptOn`)
+
+Pausiert den Agent **vor** Tool-Ausführung. Tools die **nicht** im Objekt stehen, laufen ohne Pause.
+
+```ts
+const agent = new DeepAgent({
+    checkpointer: new MemorySaver(),
+    tools: myTools,
+    interruptOn: {
+        write_file: {
+            decisions: ["approve", "reject"],
+            question: "Datei schreiben?",
+        },
+        edit_file: {
+            decisions: ["approve", "edit", "reject"],
+            question: (call) =>
+                `Editieren?\nPfad: ${call.args.file_path ?? "?"}`,
+        },
+        get_weather: {
+            decisions: ["approve", "reject"],
+            question: (call) => `Wetter für ${call.args.city} abrufen?`,
+        },
+        execute: {
+            decisions: ["approve", "reject"],
+            question: "Shell-Befehl ausführen?",
+        },
+    },
+})
+```
+
+**Config pro Tool:**
+
+| Feld | Typ | Beschreibung |
+|---|---|---|
+| `decisions` | `("approve" \| "edit" \| "reject")[]` | Erlaubte User-Antworten |
+| `question` | `string \| (toolCall) => string` | Frage an den User (statisch oder dynamisch) |
+
+**Typisierte Keys (Autocomplete):** alle FS-Tools + deine Custom-Tools + `execute` (wenn Shell-Backend). Mit `interruptOn` gesetzt liefert `invoke()`/`stream()` zusätzlich `DeepAgentInterrupt`-Chunks.
+
+HITL-Helper (optional, low-level):
+
+```ts
+import {
+    approveDecision,
+    rejectDecision,
+    editDecision,
+    approveAll,
+    createResumeCommand,
+    isInterruptResult,
+    mapResultToInterrupt,
+} from "@delofarag/ai-utils"
+```
+
+---
+
+### `stream()` — Text, Interrupts und Tool-Events
+
+Gleiche Input-API wie `invoke()` — plus optionale Tool-Events:
+
+```ts
+for await (const chunk of agent.stream({
+    input: "Baue eine Website",
+    thread_id: "u1",
+    showToolCalls: true,
+})) {
+    if (typeof chunk === "string") {
+        process.stdout.write(chunk)
+    } else if (chunk.kind === "interrupt") {
+        console.log("Interrupt:", chunk.question)
+        console.log("Decisions:", chunk.decisions)
+    } else if (chunk.kind === "tool") {
+        console.log(`[tool:${chunk.phase}]`, chunk.toolName)
     }
-])
+}
+```
 
-const agent = new Agent({
-    prompt: "Nutze search_docs fuer faktenbasierte Antworten.",
-    tools: [...registry.allTools, ragTool]
+**Stream-Chunk-Typen:**
+
+| Chunk | Wann | Shape |
+|---|---|---|
+| `string` | LLM-Text-Tokens | `"Hallo..."` |
+| `DeepAgentInterrupt` | HITL-Pause | `{ kind: "interrupt", question, decisions, toolName?, args? }` |
+| `DeepAgentInterruptBatch` | Mehrere Tools gleichzeitig | `{ kind: "interrupt", items: [...] }` |
+| `DeepAgentToolEvent` | Mit `showToolCalls: true` | `{ kind: "tool", phase: "start"\|"end", toolName, args? }` |
+
+**Resume im Stream:**
+
+```ts
+for await (const chunk of agent.stream({
+    thread_id: "u1",
+    decision: "approve",
+    showToolCalls: true,
+})) { ... }
+```
+
+Frontend ohne LangChain-Bundle:
+
+```ts
+import { isInterrupt, isToolEvent } from "@delofarag/ai-utils/client"
+```
+
+---
+
+### `agentsMd` vs `checkpointer`
+
+| Prop | LangChain-Parameter | Bedeutung |
+|---|---|---|
+| `checkpointer` | `checkpointer` | Thread-State über `thread_id` (Chat-Verlauf) |
+| `agentsMd` | `memory` | AGENTS.md-Pfade als Startup-Kontext (kein Chat-Memory) |
+
+```ts
+const agent = new DeepAgent({
+    agentsMd: ["./AGENTS.md", "./.deepagents/AGENTS.md"],
+    checkpointer: new MemorySaver(),
+})
+```
+
+---
+
+### Skills
+
+Skill-Dateien vom Backend laden (deepagents native Feature):
+
+```ts
+const agent = new DeepAgent({
+    backend: await createLocalShellBackend({ rootDir: "./coding_space" }),
+    skills: ["./skills/refactor/SKILL.md", "./skills/test/SKILL.md"],
+})
+```
+
+Pfade relativ zum Backend — der Agent kann Skills zur Laufzeit einlesen.
+
+---
+
+### Sandbox (Production)
+
+```ts
+import { DeepAgent, createDenoSandbox } from "@delofarag/ai-utils"
+
+const sandbox = await createDenoSandbox()
+const agent = new DeepAgent({
+    backend: sandbox,
+    permissions: workspacePermissions("/workspace/"),
 })
+
+// sandbox.close() wenn fertig
+```
+
+---
+
+### Runtime-Methoden
+
+```ts
+agent.addTool(extraTool)       // Tool nachträglich hinzufügen
+agent.currentTools           // string[] — alle registrierten Tool-Namen
+```
+
+---
+
+### API-Route Pattern (NDJSON Stream)
+
+```ts
+import { StreamResponse } from "@delofarag/ai-utils"
+import { isInterrupt } from "@delofarag/ai-utils/client"
+
+// Gleiche stream()-Methode für Message und HITL-Resume
+return StreamResponse(
+    agent.stream({
+        thread_id,
+        ...(decision ? { decision } : { input: message }),
+        showToolCalls: true,
+    })
+)
 ```
 
+Response: `Content-Type: application/x-ndjson` — ein JSON-Objekt pro Zeile.
+
 ---
 
-## Tool Registry (eigene Section)
+## Tool Registry
+
+### `ToolRegistry`
+
+Konvertiert einfache Tool-Definitionen zu `DynamicStructuredTool`:
 
-`ToolRegistry` konvertiert einfache Tool-Definitionen zu `DynamicStructuredTool` und bietet:
+- `getTool(name)` — wirft `Error` wenn Tool nicht existiert (kein `undefined`)
+- `getTools(...names)` — mehrere Tools, wirft bei unbekanntem Namen
+- `allTools` — alle Tools als Array
 
-- `getTool(name)`
-- `getTools(...names)`
-- `allTools`
+Tool-Namen werden als Literal-Typen erhalten — wichtig für `interruptOn`-Autocomplete bei `new DeepAgent()`.
 
 ```ts
 import { ToolRegistry } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+import { z } from "zod/v4"
 
 const registry = new ToolRegistry([
     {
         name: "get_weather",
-        description: "Liefert Wetter fuer eine Stadt",
+        description: "Liefert Wetter für eine Stadt",
         schema: z.object({ city: z.string() }),
         func: async ({ city }) => `${city}: sonnig`
     },
@@ -260,7 +714,28 @@ const weatherTool = registry.getTool("get_weather")
 const tools = registry.allTools
 ```
 
-### Tavily Tooling
+### `CombinedToolRegistry` + `ZodiosToolRegistry`
+
+Kombiniert manuelle Tools mit einem Zodios-API-Client (max. 1 Client):
+
+```ts
+import { CombinedToolRegistry } from "@delofarag/ai-utils"
+import { Zodios } from "zodios"
+
+const registry = new CombinedToolRegistry([
+    {
+        name: "get_weather",
+        description: "Wetter abfragen",
+        schema: z.object({ city: z.string() }),
+        func: async ({ city }) => `${city}: sonnig`
+    },
+    myZodiosClient
+] as const)
+
+const agent = new Agent({ tools: registry.allTools })
+```
+
+### Tavily
 
 ```ts
 import { tavilySearchTool, TavilySearch } from "@delofarag/ai-utils"
@@ -277,14 +752,16 @@ const response = await tavily.invoke({ query: "latest AI regulation EU" })
 
 ---
 
-## Memory Section (ausfuehrlich)
+## Memory (Checkpoint-Saver)
 
-### `MemorySaver` (in-memory, schnell fuer local/dev)
+Thread-State wird über LangGraph Checkpoint-Saver an `Agent` / `DeepAgent` gehängt — nicht über eine eigene Chain-Klasse.
+
+### `MemorySaver` (in-memory, schnell für local/dev)
 
 ```ts
 import { MemorySaver, SmartCheckpointSaver, getLLM } from "@delofarag/ai-utils"
 
-const memory = new SmartCheckpointSaver(new MemorySaver(), {
+const checkpointer = new SmartCheckpointSaver(new MemorySaver(), {
     llm: getLLM({ provider: "openrouter", model: "openai/gpt-5.4-mini" }),
     messagesBeforeSummary: 12,
     maxSummaries: 7
@@ -293,13 +770,11 @@ const memory = new SmartCheckpointSaver(new MemorySaver(), {
 
 ### `SmartCheckpointSaver`
 
-Was es macht:
-
-- fasst alte Chatverlaeufe zusammen
+- fasst alte Chatverläufe zusammen
 - reduziert Token-Kosten
-- erhaelt wichtige Fakten ueber mehrere Sessions
+- erhält wichtige Fakten über mehrere Sessions
 
-Wichtige Optionen:
+Optionen:
 
 - `messagesBeforeSummary` (default `12`)
 - `maxSummaries` (default `7`)
@@ -308,7 +783,7 @@ Wichtige Optionen:
 
 ### `SupabaseCheckpointSaver`
 
-Persistiert Checkpoints in Supabase.
+Persistiert Checkpoints in Supabase:
 
 ```ts
 import { SupabaseCheckpointSaver, type SupabaseCheckpointRow } from "@delofarag/ai-utils"
@@ -319,22 +794,26 @@ const checkpointsTable = new SupabaseTable<SupabaseCheckpointRow>({
 })
 
 const saver = new SupabaseCheckpointSaver(checkpointsTable)
+
+const agent = new Agent({
+    tools: [...],
+    checkpointer: saver
+})
 ```
 
-Typischer Einsatz:
+### Checkpoint-Helpers
 
 ```ts
-import { MemoryChain } from "@delofarag/ai-utils"
-
-const memoryChain = new MemoryChain({
-    prompt: "Du bist ein Support Assistant.",
-    memory: saver
-})
+import {
+    formatCheckpointMessagesForLLM,
+    getMessagesArrayFromCheckpoint,
+    chatSummarizer
+} from "@delofarag/ai-utils"
 ```
 
 ---
 
-## RAG Utilities (Detail)
+## RAG Utilities
 
 ### Vector Stores
 
@@ -369,20 +848,24 @@ const ragTool = createRAGTool({
 ## Magic-Funcs
 
 ### Answerers
+
 - `ask({ question, llm? })`
 - `websearch(query)` (braucht `TAVILY_API_KEY`)
 
 ### Evaluators
+
 - `classify({ data, classes, context?, llm? })`
 - `decide({ material, kriteria_to_decide, llm? })`
 
 ### Parsers
+
 - `extract({ data, schema, goal?, llm? })`
 - `structure({ data, into, retries?, llm? })`
 - `rewrite({ data, instruction, llm? })`
 - `summarize({ data, fokuss?, maxWords?, llm? })`
 
 ### Optimizers
+
 - `promptify({ request, agentRole?, llm? })`
 - `ragify({ data, llm? })`
 
@@ -390,7 +873,7 @@ Beispiel:
 
 ```ts
 import { classify, extract, summarize } from "@delofarag/ai-utils"
-import { z } from "zod/v3"
+import { z } from "zod/v4"
 
 const sentiment = await classify({
     data: "Das Produkt ist wirklich gut.",
@@ -419,7 +902,7 @@ const short = await summarize({
 ### STT
 
 - `stt(...)`
-- `createSTTPhoneSocketSession(...)` fuer live phone socket chunks (Twilio/Telnyx-style)
+- `createSTTPhoneSocketSession(...)` für live phone socket chunks (Twilio/Telnyx-style)
 
 ```ts
 import { stt } from "@delofarag/ai-utils"
@@ -433,7 +916,7 @@ const result = await stt({
 ### TTS
 
 - `tts(...)`
-- `streamTTSOverPhoneSocket(...)` fuer chunked outbound audio
+- `streamTTSOverPhoneSocket(...)` für chunked outbound audio
 
 ```ts
 import { tts, streamTTSOverPhoneSocket } from "@delofarag/ai-utils"
@@ -479,29 +962,97 @@ const generated = await generateImages({
 ## Session / Stream Helpers
 
 ```ts
-import { session, StreamResponse } from "@delofarag/ai-utils"
+import { session, StreamResponse, logChunk } from "@delofarag/ai-utils"
+```
+
+### `session()` — CLI-Testloop
+
+Interaktive Konsole für `Agent.stream()` oder `DeepAgent.stream()`.
+
+| Prop | Default | Beschreibung |
+|---|---|---|
+| `streamable` | — | Objekt mit `.stream({ input, thread_id, ... })` |
+| `breakword` | `"exit"` | Beendet die Session |
+| `id` | Timestamp | Wird als `thread_id` genutzt |
+| `numberOfMessages` | `Infinity` | Max. User+Assistant-Runden |
+| `isDeepAgent` | `false` | HITL-Modus für DeepAgent (siehe unten) |
+
+**Normaler Agent:**
+
+```ts
+await session({
+    streamable: agent,
+    breakword: "exit",
+    id: "dev-session-1",
+})
 ```
 
-- `session({ streamable, ... })`: CLI-like interactive loop
-- `StreamResponse(asyncIterable)`: streambares NDJSON-HTTP-Response-Objekt
+**DeepAgent mit HITL + Tool-Logs:**
+
+```ts
+await session({
+    streamable: deepAgent,
+    isDeepAgent: true,
+    id: "dev-session-1",
+})
+```
+
+Mit `isDeepAgent: true` passiert automatisch:
+
+- `showToolCalls: true` — `[tool:start]` / `[tool:end]` in der Konsole
+- Nach einem Interrupt wartet die Session auf deine Entscheidung statt neuer Message
+- Erkannte Antworten: `approve`, `ja`, `ok`, `reject`, `reject: Grund hier`
+- `logChunk()` formatiert Text, Interrupts und Tool-Events lesbar
+
+Flow:
+
+```
+You: Schreib eine Datei
+Assistant: [tool:start] write_file {...}
+           [interrupt] Datei schreiben?
+           decisions: approve, reject
+You: approve
+Assistant: [tool:end] write_file
+           Fertig!
+```
+
+### `StreamResponse()` — NDJSON für HTTP
+
+Wrappt einen `AsyncIterable` als HTTP-Response (`application/x-ndjson`). Jeder Chunk = eine JSON-Zeile. Ideal für `DeepAgent.stream()` in API-Routes.
+
+### `logChunk()`
+
+Hilfsfunktion für Stream-Output in der Konsole — nutzt intern `isInterrupt()` und `isToolEvent()`.
 
 ---
 
-## Export Overview (high-level)
+## Export Overview
 
-Top-level Exports decken u. a. ab:
+Top-level Exports (`@delofarag/ai-utils`):
 
-- Helpers (`helpers`, `memory`, `rag`, `llms`, `chatbot`)
-- Core (`Agent`, `Chain`, `MemoryChain`)
-- Tools (`ToolRegistry`, `Tavily`, `RAGTool`, Zodios registries)
+- Helpers (`helpers`, `memory`, `rag`, `llms`, `chatbot`, `logChunk`)
+- Core (`Agent`, `Chain`, `DeepAgent`)
+- DeepAgent (`createWorkspaceBackend`, `createLocalShellBackend`, `createDenoSandbox`, `workspacePermissions`, `interruptOn`-Helper, alle `DeepAgent*`-Types)
+- Memory (`MemorySaver`, `SmartCheckpointSaver`, `SupabaseCheckpointSaver`, `chatSummarizer`)
+- Tools (`ToolRegistry`, `CombinedToolRegistry`, `ZodiosToolRegistry`, `Tavily`, `RAGTool`)
 - Magic-Funcs (answerers/evaluators/parsers/optimizers)
 - Modalities (`stt`, `tts`, `vision`, `generateImages`)
 
+Client-Subpath (`@delofarag/ai-utils/client`) — ohne LangChain-Bundle, für Frontend:
+
+- Types: `DeepAgentInterrupt`, `DeepAgentToolEvent`, `DeepAgentStreamChunk`, ...
+- Guards: `isInterrupt()`, `isToolEvent()`
+
 ---
 
 ## Empfehlungen
 
-- Fuer strukturierte Outputs immer `zod/v3` verwenden.
-- Fuer Produktion API-Keys als ENV setzen, nicht hardcoden.
-- Bei langen Chats `SmartCheckpointSaver` verwenden.
+- Für strukturierte Outputs immer `zod/v4` verwenden.
+- Für Produktion API-Keys als ENV setzen, nicht hardcoden.
+- Bei langen Chats `SmartCheckpointSaver` am `Agent` verwenden.
 - RAG als Tool im `Agent` ist in der Praxis oft robuster als RAG-only Prompting.
+- `Chain` für stateless Tasks, `Agent` für Tools und Conversation Memory, `DeepAgent` für autonome Coding-/Research-Agents.
+- DeepAgent: `rootDir` + `route` klar trennen — Agent sieht nur den virtuellen Pfad.
+- DeepAgent HITL: immer `checkpointer` + `thread_id`; `interruptOn` pro Tool konfigurieren.
+- DeepAgent Shell: `createLocalShellBackend` nur lokal/Dev — `execute` läuft auf dem Host.
+- DeepAgent testen: `session({ streamable: agent, isDeepAgent: true })`.