human-to-code 0.1.12 → 0.1.13

package/dist/pipeline/deep-agent.js

@@ -1,147 +1,87 @@
-/**
- * Deep-agent orchestration for the direct `npx human-to-code .` flow.
- *
- * This path runs a LangChain/LangGraph "deep agent" (via the `deepagents`
- * harness) with the four batteries-included pillars:
- *
- *   1. Planning     — the built-in `write_todos` tool decomposes the run.
- *   2. File System  — a real-disk `FilesystemBackend` rooted at the project
- *                     gives the agent `ls`/`read_file`/`write_file`/`edit_file`/
- *                     `glob`/`grep` over the working tree.
- *   3. Sub Agents   — a `planner`, `implementer`, and `reviewer` subagent are
- *                     reachable through the built-in `task` tool.
- *   4. Prompts      — a task-specific system prompt for the main agent and one
- *                     per subagent role.
- *
- * Unlike the deterministic guided pipeline, the model drives scope, file
- * reads/writes, and delegation here. The blast radius is bounded to the project
- * root by the backend and by deny-write filesystem permissions on sensitive
- * paths, but this is an autonomous agent, not a hash-verified patch pipeline.
- */
-import { createDeepAgent } from "deepagents";
-import { FilesystemBackend } from "deepagents/node";
-import { languageProfile } from "./simple.js";
-/**
- * Writes are denied on version-control internals, dependencies, the tool's own
- * state, and credential-bearing files. Paths are backend-absolute globs (rooted
- * at the project). Reads stay permissive so the agent can ground itself.
- */
-const DENY_WRITE_PATHS = [
-    "/.git/**",
-    "/.hg/**",
-    "/.svn/**",
-    "/node_modules/**",
-    "/.human-to-code/**",
-    "/human-to-code.config.json",
-    "/secrets.human",
-    "/**/.env",
-    "/**/.env.*",
-    "/**/*.env",
-    "/**/*.env.*",
-    "/**/*.pem",
-    "/**/*.key",
-    "/**/id_rsa",
-    "/**/id_ed25519",
-];
-function mainSystemPrompt(languageLabel) {
+/** Tool-rich, bounded agent orchestration for the direct conversion flow. */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createAgent } from "langchain";
+import { tool } from "@langchain/core/tools";
+import { AGENT_TOOL_SCHEMAS, AgentToolRuntime, } from "./agent-tools.js";
+import { extractInlineMarkers, languageProfile } from "./simple.js";
+export class DeepAgentIncompleteError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "DeepAgentIncompleteError";
+        this.code = code;
+    }
+}
+export const AGENT_TOOL_NAMES = Object.freeze(Object.keys(AGENT_TOOL_SCHEMAS));
+export function agentSystemPrompt(languageLabel) {
     return [
-        `You are human-to-code, an autonomous ${languageLabel} coding agent.`,
-        "Your job is to fulfil natural-language change requests that a developer left in their codebase, in two forms:",
-        "  1. Whole `.human` files (never `*.strict.human`): generate a sibling source file with the same base name and the language's extension, containing only real code.",
-        "  2. Inline `@human` markers inside existing source files: replace the marker comment in place with the code it asks for, preserving all surrounding code.",
+        `You are human-to-code, an interactive ${languageLabel} software-engineering agent.`,
+        "Complete the confirmed worklist by inspecting and editing the project with tools. Be concise and stop as soon as every item is implemented.",
         "",
-        "Working method — be efficient; every step is a slow model call, so avoid unnecessary ones:",
-        "- First call write_todos once to record a short ordered plan covering every worklist item.",
-        "- Read each target file once with read_file to ground yourself before editing. Every path is absolute and rooted at the project: it must start with `/` (e.g. `/src/a.ts`).",
-        "- For simple items, write the code yourself directly with write_file (for `.human` file outputs) or edit_file (for inline markers). Only delegate to the `implementer` subagent for genuinely complex items, and only use the `reviewer` subagent when correctness is non-obvious. Do not delegate or review trivial one-liners.",
-        "- Never remove or rewrite code that a marker did not ask you to change. Reuse declarations that already exist in the file instead of redeclaring them.",
-        "- Keep todos updated: mark each in_progress when you start it and completed when its code is written.",
-        "- When every item is done, stop and give a one-line summary. Do not re-read or re-verify files you have already written.",
+        "MANDATORY WORKFLOW:",
+        "1. Call TodoWrite exactly once at the start with one todo per worklist item. Only one todo may be in_progress.",
+        "2. Call Read before Edit, MultiEdit, or overwriting an existing file with Write.",
+        "3. Use Edit for one exact replacement, MultiEdit for several replacements in one file, and Write only for a new whole-file output.",
+        "4. Use Glob/Grep/LS for discovery. Use Bash only for a necessary build, typecheck, or test command. Never use Bash to read, search, or edit files.",
+        "5. Use Task only when an item truly needs multi-step research or independent implementation. Valid subagent_type values are general-purpose, implementer, and reviewer.",
+        "6. After writing an item, immediately call TodoWrite with that item completed and the next item in_progress.",
+        "7. When all items are completed, return one short sentence with no tool call. This is the stop condition. Never continue checking completed work.",
         "",
-        "Output only real, compilable code into files. Do not add comments describing what you changed. Do not touch dependency, VCS, secret, or configuration files.",
+        "PATH AND FILE RULES:",
+        "- Every tool path is project-rooted and starts with '/'. Example: src/app.ts is /src/app.ts.",
+        "- A whole .human file creates the sibling output named in the worklist. Never overwrite an existing output without reading it.",
+        "- An inline @human marker is replaced in place. Preserve indentation and all unrelated code.",
+        "- Reuse existing declarations. Write only real compilable code; no markdown fences or change-description comments.",
+        "- Never touch dependencies, lockfiles, VCS data, tool state, credentials, or configuration unless the worklist explicitly names a normal source configuration file.",
+        "",
+        "TOOL-CALL FORMAT FOR SMALL MODELS:",
+        "Tool arguments are JSON objects. Do not print XML or narrate a tool call.",
+        "Plan example: TodoWrite({\"todos\":[{\"id\":\"1\",\"content\":\"Implement /src/math.ts marker\",\"status\":\"in_progress\"}]})",
+        "Read example: Read({\"file_path\":\"/src/math.ts\"})",
+        "Inline edit example: Edit({\"file_path\":\"/src/math.ts\",\"old_string\":\"// @human add two numbers\",\"new_string\":\"export function add(a: number, b: number) { return a + b; }\"})",
+        "New file example: Read({\"file_path\":\"/feature.human\"}) then Write({\"file_path\":\"/feature.ts\",\"content\":\"export const feature = true;\\n\"})",
+        "Validation example: Bash({\"command\":\"npm test\",\"description\":\"Runs project tests\"})",
+        "Finish example: TodoWrite({\"todos\":[{\"id\":\"1\",\"content\":\"Implement /src/math.ts marker\",\"status\":\"completed\"}]}) then answer: Implemented the requested conversion.",
     ].join("\n");
 }
-function plannerSubagent(languageLabel) {
-    return {
-        name: "planner",
-        description: "Break a human-to-code conversion request into an ordered, file-by-file implementation plan. Use before writing any code when the worklist is non-trivial.",
-        systemPrompt: [
-            `You plan ${languageLabel} conversion work.`,
-            "Given a worklist of `.human` files and inline `@human` markers, produce a concise, ordered list of concrete implementation steps.",
-            "Account for dependencies between steps (e.g. a marker that uses a symbol another marker declares).",
-            "Return only the plan as a numbered list. Write no code.",
-        ].join("\n"),
-    };
-}
-function implementerSubagent(languageLabel) {
-    return {
-        name: "implementer",
-        description: "Generate the exact code for one `.human` file or one inline `@human` marker. Delegate each concrete code-writing step to this subagent.",
-        systemPrompt: [
-            `You are a precise ${languageLabel} code generator.`,
-            "You are given one instruction and the relevant file context.",
-            "Return only the code that satisfies the instruction: for a whole-file request, the full file body; for an inline marker, only the replacement for that marker.",
-            "Reuse declarations already present in the file; never redeclare or duplicate them unless explicitly asked to shadow.",
-            "No explanations, no markdown fences, no comments describing your work.",
-        ].join("\n"),
-    };
-}
-function reviewerSubagent(languageLabel) {
-    return {
-        name: "reviewer",
-        description: "Check that generated code matches its instruction, is syntactically valid, and did not corrupt surrounding code. Use after each implementation step.",
-        systemPrompt: [
-            `You review generated ${languageLabel} code.`,
-            "Given the original instruction and the code that was written, confirm it satisfies the instruction, is syntactically plausible, and preserves unrelated surrounding code.",
-            "If it is correct, respond APPROVED with a one-line reason. If not, respond CHANGES with a concrete, minimal fix instruction.",
-        ].join("\n"),
-    };
+function subagentSystemPrompt(type, languageLabel) {
+    const shared = [
+        `You are a focused ${languageLabel} ${type} subagent.`,
+        "Complete only the delegated task. Use project-rooted tools, preserve unrelated code, and return a concise result.",
+        "Do not delegate again. Do not touch protected, dependency, credential, VCS, or tool-state paths.",
+    ];
+    if (type === "reviewer")
+        shared.push("Inspect the requested code and report concrete correctness problems. Do not edit unless the prompt explicitly asks for fixes.");
+    else if (type === "implementer")
+        shared.push("Read the relevant files, implement the requested code, and stop immediately after the necessary edit.");
+    else
+        shared.push("Research the project with Read, Glob, and Grep; edit only when the delegated prompt explicitly requests implementation.");
+    return shared.join("\n");
 }
-/** Backend paths are absolute, rooted at the project (e.g. `src/a.ts` -> `/src/a.ts`). */
 function backendPath(relativePath) {
-    return `/${relativePath.replace(/^\/+/u, "")}`;
+    return `/${relativePath.replace(/^\/+/, "")}`;
 }
 function taskPrompt(units, languageLabel) {
-    const pathRule = "All filesystem tool paths are absolute and rooted at the project: they must start with `/` (for example the file `src/a.ts` is `/src/a.ts`). Never pass a relative path.";
-    if (units.length === 0) {
-        return [
-            `Scan the project for any \`.human\` files or inline \`@human\` markers and convert them to ${languageLabel}.`,
-            pathRule,
-            "If there are none, report that nothing needs conversion.",
-        ].join("\n");
-    }
-    const worklist = units
-        .map((unit, index) => {
-        if (unit.kind === "file") {
-            return `${index + 1}. Whole file: read "${backendPath(unit.sourcePath)}" and write its generated ${languageLabel} into "${backendPath(unit.outputPath ?? unit.sourcePath)}". Instruction: ${unit.prompt}`;
-        }
-        return `${index + 1}. Inline marker in "${backendPath(unit.sourcePath)}": replace the @human marker in place, preserving surrounding code. Instruction: ${unit.prompt}`;
-    })
-        .join("\n");
+    if (units.length === 0)
+        return `Find and convert any .human files or inline @human markers to ${languageLabel}. If none exist, say so and stop.`;
+    const worklist = units.map((unit, index) => unit.kind === "file"
+        ? `${index + 1}. Whole file: Read ${backendPath(unit.sourcePath)} and create ${backendPath(unit.outputPath ?? unit.sourcePath)}. Instruction: ${unit.prompt}`
+        : `${index + 1}. Inline: Read ${backendPath(unit.sourcePath)} and replace only its @human marker. Instruction: ${unit.prompt}`).join("\n");
     return [
-        `Convert the following ${units.length} item(s) to ${languageLabel}.`,
-        pathRule,
-        "",
+        `Convert these ${units.length} ${languageLabel} worklist item(s):`,
         worklist,
         "",
-        "Plan once with write_todos, read each target file once, then write the code directly with write_file or edit_file (only delegating complex items to the implementer subagent). Report a short summary of what you wrote when done.",
+        "Start with TodoWrite. Implement in order. Stop immediately after every todo is completed.",
     ].join("\n");
 }
-/**
- * Construct a LangChain chat model for the configured provider.
- *
- * Both providers use the OpenAI-compatible chat client. Ollama is reached
- * through its `/v1` endpoint rather than `@langchain/ollama`'s native
- * `/api/chat`: the deep-agent harness emits tool messages with structured
- * (array) content, which the native Ollama adapter rejects, whereas the
- * OpenAI-compatible surface serializes them correctly.
- */
 export async function buildDeepAgentModel(options) {
     const { ChatOpenAI } = await import("@langchain/openai");
     if (options.provider === "openai") {
         return new ChatOpenAI({
             model: options.model,
             temperature: 0,
+            maxRetries: 1,
             ...(options.apiKey ? { apiKey: options.apiKey } : {}),
             ...(options.baseUrl ? { configuration: { baseURL: options.baseUrl } } : {}),
         });
@@ -151,115 +91,305 @@ export async function buildDeepAgentModel(options) {
         return new ChatOpenAI({
             model: options.model,
             temperature: 0,
-            // Ollama ignores the key but the OpenAI client requires a non-empty value.
+            maxRetries: 1,
             apiKey: options.apiKey ?? "ollama",
             configuration: { baseURL: `${root}/v1` },
         });
     }
-    throw new Error(`Provider '${options.provider}' has no deep-agent chat-model binding. Use openai or ollama.`);
+    throw new Error(`Provider '${options.provider}' has no agent chat-model binding. Use openai or ollama.`);
 }
-/**
- * Build (but do not run) the deep agent. Exposed so callers and tests can
- * inspect wiring without a live provider.
- */
-export async function buildDeepAgent(options) {
+function toolDescription(name) {
+    const descriptions = {
+        Task: "Launch one stateless subagent for a complex delegated task. Supply a short description, detailed prompt, and subagent_type.",
+        Bash: "Run one bounded shell command from the project root. Use only for builds, tests, and necessary development commands; background runs return a bash_id.",
+        Glob: "Find project files using a glob pattern. Paths are project-rooted.",
+        Grep: "Search project file contents with ripgrep and optional output controls.",
+        LS: "List one project directory.",
+        ExitPlanMode: "Record that planning is complete for this already-confirmed conversion and continue implementation.",
+        Read: "Read a project file with numbered lines. Must be called before editing an existing file.",
+        Edit: "Perform one exact, unique string replacement in a file previously read.",
+        MultiEdit: "Atomically perform several exact replacements in one file previously read.",
+        Write: "Create a file or overwrite a previously read file.",
+        NotebookEdit: "Replace, insert, or delete one Jupyter notebook cell.",
+        WebFetch: "Fetch one reviewed public HTTPS URL as bounded text.",
+        TodoWrite: "Create or update the complete todo list. Use pending, in_progress, and completed statuses with one in_progress item.",
+        WebSearch: "Search the public web for current programming information with optional domain filters.",
+        BashOutput: "Read only new output from a background Bash run.",
+        KillBash: "Terminate a background Bash run by shell_id.",
+    };
+    return descriptions[name] ?? `${name} tool.`;
+}
+function createAgentTools(runtime, taskRunner) {
+    const handler = (name) => async (input) => {
+        if (name === "Task") {
+            if (!taskRunner)
+                return "Task delegation is disabled inside a subagent; complete the delegated work directly.";
+            return taskRunner(input);
+        }
+        if (name === "Bash")
+            return runtime.bash(input);
+        if (name === "Glob")
+            return runtime.glob(input);
+        if (name === "Grep")
+            return runtime.grep(input);
+        if (name === "LS")
+            return runtime.ls(input);
+        if (name === "ExitPlanMode")
+            return `Plan recorded: ${String(input.plan ?? "")}. Continue implementation now.`;
+        if (name === "Read")
+            return runtime.read(input);
+        if (name === "Edit")
+            return runtime.edit(input);
+        if (name === "MultiEdit")
+            return runtime.multiEdit(input);
+        if (name === "Write")
+            return runtime.write(input);
+        if (name === "NotebookEdit")
+            return runtime.notebookEdit(input);
+        if (name === "WebFetch")
+            return runtime.webFetch(input);
+        if (name === "TodoWrite")
+            return `Todo list updated (${Array.isArray(input.todos) ? input.todos.length : 0} items).`;
+        if (name === "WebSearch")
+            return runtime.webSearch(input);
+        if (name === "BashOutput")
+            return runtime.bashOutput(input);
+        if (name === "KillBash")
+            return runtime.killBash(input);
+        throw new Error(`Unsupported agent tool ${name}.`);
+    };
+    return AGENT_TOOL_NAMES.map((name) => tool(handler(name), {
+        name,
+        description: toolDescription(name),
+        schema: AGENT_TOOL_SCHEMAS[name],
+    }));
+}
+function messageText(message) {
+    if (!message || typeof message !== "object")
+        return "";
+    const content = message.content;
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    return content.map((item) => item && typeof item === "object" && typeof item.text === "string"
+        ? item.text : "").join("\n").trim();
+}
+async function buildAgentBundle(options) {
     const label = languageProfile(options.language).label;
     const model = options.model_override ?? await buildDeepAgentModel(options);
-    const backend = new FilesystemBackend({ rootDir: options.root });
-    const permissions = [
-        { operations: ["write"], paths: [...DENY_WRITE_PATHS], mode: "deny" },
-    ];
-    return createDeepAgent({
+    const activity = (event) => {
+        if (event.kind === "output")
+            options.onProgress?.({ kind: "output", name: event.name, text: event.text });
+        else
+            options.onProgress?.({ kind: "diff", path: event.path, lines: event.lines });
+    };
+    const runtime = new AgentToolRuntime({ root: options.root, onActivity: activity });
+    const taskRunner = async (input) => {
+        const type = typeof input.subagent_type === "string" ? input.subagent_type : "general-purpose";
+        const prompt = typeof input.prompt === "string" ? input.prompt : "";
+        const subagent = createAgent({
+            model,
+            tools: createAgentTools(runtime),
+            systemPrompt: subagentSystemPrompt(type, label),
+        });
+        const result = await subagent.invoke({ messages: [{ role: "user", content: prompt }] }, { recursionLimit: 48, ...(options.signal ? { signal: options.signal } : {}) });
+        const messages = Array.isArray(result.messages) ? result.messages : [];
+        return messageText(messages.at(-1)) || "Subagent completed without a written summary.";
+    };
+    const agent = createAgent({
         model,
-        backend,
-        systemPrompt: mainSystemPrompt(label),
-        subagents: [plannerSubagent(label), implementerSubagent(label), reviewerSubagent(label)],
-        permissions,
+        tools: createAgentTools(runtime, taskRunner),
+        systemPrompt: agentSystemPrompt(label),
     });
+    return { agent, runtime };
+}
+export async function buildDeepAgent(options) {
+    return (await buildAgentBundle(options)).agent;
 }
 function normalizeTodos(raw) {
-    return raw.map((todo) => ({
+    return raw.map((todo, index) => ({
+        id: typeof todo.id === "string" ? todo.id : String(index + 1),
         content: typeof todo.content === "string" ? todo.content : String(todo.content ?? ""),
-        status: typeof todo.status === "string" ? todo.status : String(todo.status ?? ""),
+        status: typeof todo.status === "string" ? todo.status : String(todo.status ?? "pending"),
     }));
 }
-/** Short human detail for a tool call (the path it touches or subagent it invokes). */
+function todosFromArgs(args) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return undefined;
+    const raw = args.todos;
+    return Array.isArray(raw) ? normalizeTodos(raw) : undefined;
+}
 function toolDetail(name, args) {
-    if (!args)
+    if (!args || typeof args !== "object" || Array.isArray(args))
         return undefined;
-    if (name === "task") {
-        const sub = args.subagent_type ?? args.subagentType ?? args.name ?? args.description;
-        return typeof sub === "string" ? sub.split(/\s+/u).slice(0, 6).join(" ") : undefined;
+    const record = args;
+    if (name.toLowerCase() === "task") {
+        const value = record.subagent_type ?? record.subagentType ?? record.description;
+        return typeof value === "string" ? value : undefined;
     }
-    for (const key of ["file_path", "filePath", "path", "file"]) {
-        const value = args[key];
+    if (name === "Bash" || name === "execute") {
+        const value = record.description ?? record.command;
+        return typeof value === "string" ? value.slice(0, 100) : undefined;
+    }
+    for (const key of ["file_path", "notebook_path", "filePath", "path", "file"]) {
+        const value = record[key];
         if (typeof value === "string" && value.length > 0)
             return value;
     }
     return undefined;
 }
-/**
- * Run the deep agent against the discovered worklist, streaming live progress
- * (planning, tool calls, delegation) through `onProgress`. The agent edits
- * files on disk through its filesystem backend; this returns the final plan and
- * summary it produced for the report.
- */
+async function captureWorklist(units) {
+    return Promise.all(units.map(async (unit) => {
+        const target = unit.kind === "file" ? resolve(dirnameFor(unit.absoluteSource), unit.outputPath?.split("/").at(-1) ?? "") : unit.absoluteSource;
+        const initial = await readFile(target, "utf8").catch(() => undefined);
+        return { unit, initial };
+    }));
+}
+function dirnameFor(path) {
+    return path.slice(0, Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+}
+async function worklistComplete(root, states) {
+    if (states.length === 0)
+        return true;
+    for (const state of states) {
+        if (state.unit.kind === "file") {
+            const output = state.unit.outputPath;
+            if (!output)
+                return false;
+            const current = await readFile(resolve(root, output), "utf8").catch(() => undefined);
+            if (current === undefined || current.trim().length === 0 || current === state.initial)
+                return false;
+            continue;
+        }
+        const current = await readFile(state.unit.absoluteSource, "utf8").catch(() => undefined);
+        if (current === undefined || current === state.initial)
+            return false;
+        const markers = extractInlineMarkers(current);
+        if (markers.some((marker) => marker.prompt.trim() === state.unit.prompt.trim()))
+            return false;
+    }
+    return true;
+}
+function recursionFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /recursion limit|GRAPH_RECURSION_LIMIT/iu.test(message);
+}
+function defaultRecursionLimit(unitCount) {
+    return Math.min(120, Math.max(40, 28 + unitCount * 12));
+}
+function completedTodos(todos) {
+    return todos.map((todo) => ({ ...todo, status: "completed" }));
+}
 export async function runDeepAgentConversion(options) {
-    const agent = await buildDeepAgent(options);
+    const states = await captureWorklist(options.units);
+    const bundle = await buildAgentBundle(options);
     const label = languageProfile(options.language).label;
     const input = { messages: [{ role: "user", content: taskPrompt(options.units, label) }] };
-    const config = {
-        recursionLimit: options.recursionLimit ?? 150,
-        ...(options.signal ? { signal: options.signal } : {}),
-    };
+    const config = { recursionLimit: options.recursionLimit ?? defaultRecursionLimit(options.units.length), ...(options.signal ? { signal: options.signal } : {}) };
     const seenMessages = new Set();
     let todos = [];
     let lastTodosKey = "";
     let summary = "";
     let messageCount = 0;
-    const stream = await agent.stream(input, { ...config, streamMode: "updates" });
-    for await (const chunk of stream) {
-        for (const update of Object.values(chunk)) {
-            if (!update || typeof update !== "object")
-                continue;
-            const node = update;
-            if (Array.isArray(node.todos)) {
-                const next = normalizeTodos(node.todos);
-                const key = JSON.stringify(next);
-                if (key !== lastTodosKey) {
-                    lastTodosKey = key;
-                    todos = next;
-                    options.onProgress?.({ kind: "plan", todos: next });
+    let toolCount = 0;
+    let lastToolSignature = "";
+    let repeatedToolCalls = 0;
+    let stopReason = "model";
+    try {
+        const stream = await bundle.agent.stream(input, { ...config, streamMode: "updates" });
+        streamLoop: for await (const chunk of stream) {
+            for (const update of Object.values(chunk)) {
+                if (!update || typeof update !== "object")
+                    continue;
+                const node = update;
+                if (Array.isArray(node.todos)) {
+                    const next = normalizeTodos(node.todos);
+                    const key = JSON.stringify(next);
+                    if (key !== lastTodosKey) {
+                        lastTodosKey = key;
+                        todos = next;
+                        options.onProgress?.({ kind: "plan", todos: next });
+                    }
                 }
-            }
-            if (Array.isArray(node.messages)) {
-                for (const raw of node.messages) {
-                    const message = raw;
-                    const id = typeof message.id === "string" ? message.id : undefined;
-                    if (id) {
-                        if (seenMessages.has(id))
+                if (Array.isArray(node.messages)) {
+                    for (const raw of node.messages) {
+                        const message = raw;
+                        const id = typeof message.id === "string" ? message.id : undefined;
+                        if (id && seenMessages.has(id))
                             continue;
-                        seenMessages.add(id);
-                    }
-                    messageCount += 1;
-                    const type = typeof message.getType === "function" ? message.getType() : undefined;
-                    if (type === "ai") {
-                        if (Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+                        if (id)
+                            seenMessages.add(id);
+                        messageCount += 1;
+                        const type = typeof message.getType === "function" ? message.getType() : undefined;
+                        if (type === "ai" && Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
                             for (const call of message.tool_calls) {
                                 const name = typeof call.name === "string" ? call.name : "tool";
+                                const signature = `${name}:${JSON.stringify(call.args ?? {})}`;
+                                repeatedToolCalls = signature === lastToolSignature ? repeatedToolCalls + 1 : 1;
+                                lastToolSignature = signature;
+                                toolCount += 1;
                                 const detail = toolDetail(name, call.args);
                                 options.onProgress?.({ kind: "tool", name, ...(detail ? { detail } : {}) });
+                                if (name === "TodoWrite" || name === "write_todos") {
+                                    const next = todosFromArgs(call.args);
+                                    if (next) {
+                                        todos = next;
+                                        options.onProgress?.({ kind: "plan", todos: next });
+                                    }
+                                }
+                                if (repeatedToolCalls >= 4) {
+                                    if (await worklistComplete(options.root, states)) {
+                                        stopReason = "worklist_complete";
+                                        summary = "Implemented every requested conversion; stopped a repeated tool loop.";
+                                        todos = completedTodos(todos);
+                                        options.onProgress?.({ kind: "plan", todos });
+                                        break streamLoop;
+                                    }
+                                    throw new DeepAgentIncompleteError("TOOL_LOOP", `Agent stopped after repeating the same ${name} call four times. No further project changes were attempted.`);
+                                }
                             }
                         }
-                        else if (typeof message.content === "string" && message.content.trim().length > 0) {
-                            summary = message.content.trim();
-                            options.onProgress?.({ kind: "assistant", text: summary });
+                        else if (type === "ai") {
+                            const text = messageText(message);
+                            if (text.length > 0) {
+                                summary = text;
+                                options.onProgress?.({ kind: "assistant", text });
+                            }
                         }
                     }
                 }
             }
+            if (toolCount > 0 && await worklistComplete(options.root, states)) {
+                stopReason = "worklist_complete";
+                summary ||= "Implemented every requested conversion.";
+                todos = completedTodos(todos);
+                options.onProgress?.({ kind: "plan", todos });
+                break;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof DeepAgentIncompleteError)
+            throw error;
+        if (!recursionFailure(error))
+            throw error;
+        if (await worklistComplete(options.root, states)) {
+            stopReason = "worklist_complete";
+            summary = "Implemented every requested conversion before the agent step limit.";
+            todos = completedTodos(todos);
+            options.onProgress?.({ kind: "plan", todos });
         }
+        else {
+            throw new DeepAgentIncompleteError("STEP_LIMIT", `Agent reached its bounded ${config.recursionLimit}-step limit before completing the worklist. Partial edits were left visible for review; rerun with a more capable tool-calling model.`);
+        }
+    }
+    finally {
+        await bundle.runtime.cleanup();
+    }
+    if (states.length > 0 && !await worklistComplete(options.root, states)) {
+        throw new DeepAgentIncompleteError("INCOMPLETE", "Agent stopped without completing every discovered worklist item. Partial edits were left visible for review.");
     }
-    return { todos, messageCount, summary };
+    return { todos, messageCount, toolCount, summary, stopReason };
 }
 //# sourceMappingURL=deep-agent.js.map