@xingjisoft/neutrino 0.5.1 → 0.6.0

package/dist/llm/codeExecutor.js

@@ -0,0 +1,239 @@
+import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
+const DEFAULT_LIMITS = { cpuMs: 3000, memoryBytes: 32 * 1024 * 1024, idleMs: 30_000 };
+/** The worker owns QuickJS; only named tool RPCs can reach the host. */
+export class LocalCodeExecutor {
+    signal;
+    limits;
+    constructor(signal, limits = {}) {
+        this.signal = signal;
+        this.limits = limits;
+    }
+    async execute(code, providersOrFns) {
+        if (this.signal?.aborted)
+            return { result: null, error: "Execution cancelled" };
+        const providers = Array.isArray(providersOrFns)
+            ? providersOrFns : [{ name: "codemode", fns: providersOrFns }];
+        const limits = { ...DEFAULT_LIMITS, ...this.limits };
+        return new Promise(resolve => {
+            const worker = new Worker(new URL(import.meta.url), {
+                execArgv: process.execArgv.filter(arg => !arg.startsWith("--input-type")),
+                workerData: { neutrinoCode: true, code, limits, providers: providers.map(p => ({ name: p.name, tools: Object.keys(p.fns) })) },
+            });
+            let finished = false;
+            let finalResultReceived = false;
+            let pending = 0;
+            let lastActivity = Date.now();
+            let calls = 0;
+            // The existing approval UI has one active decision. Serialize RPCs so a
+            // Promise.all cannot overwrite an earlier approval or race side effects.
+            let queue = Promise.resolve();
+            const finish = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearInterval(watchdog);
+                this.signal?.removeEventListener("abort", abort);
+                void worker.terminate();
+                resolve(result);
+            };
+            const abort = () => finish({ result: null, error: String(this.signal?.reason ?? "Execution cancelled") });
+            const watchdog = setInterval(() => {
+                if (!pending && Date.now() - lastActivity > limits.idleMs)
+                    finish({ result: null, error: "Program timed out without completing" });
+            }, 100);
+            this.signal?.addEventListener("abort", abort, { once: true });
+            if (this.signal?.aborted) {
+                abort();
+                return;
+            }
+            worker.on("error", error => finish({ result: null, error: error.message }));
+            worker.on("exit", code => { if (!finished && !finalResultReceived)
+                finish({ result: null, error: `Execution worker exited (${code})` }); });
+            worker.on("message", message => {
+                if (finished)
+                    return;
+                lastActivity = Date.now();
+                if (message.type === "result") {
+                    finalResultReceived = true;
+                    // Report promptly so the program owner can abort host operations,
+                    // including an outstanding human approval, then settle its ledger.
+                    finish(pending && !message.value.error
+                        ? { ...message.value, error: "Program returned with unawaited tool calls; inspect completed operations" }
+                        : message.value);
+                    return;
+                }
+                if (message.type !== "tool")
+                    return;
+                if (++calls > 256) {
+                    finish({ result: null, error: "Program exceeded 256 tool/progress calls" });
+                    return;
+                }
+                pending++;
+                queue = queue.then(async () => {
+                    if (finished || finalResultReceived) {
+                        pending--;
+                        return;
+                    }
+                    let value;
+                    let error;
+                    try {
+                        const provider = providers.find(p => p.name === message.provider);
+                        if (!provider || !Object.hasOwn(provider.fns, message.name))
+                            throw new Error("Unknown program tool");
+                        value = await provider.fns[message.name](message.args);
+                    }
+                    catch (err) {
+                        error = err instanceof Error ? err.message : String(err);
+                    }
+                    finally {
+                        pending--;
+                        lastActivity = Date.now();
+                    }
+                    if (!finished && !finalResultReceived)
+                        worker.postMessage({ type: "tool-result", id: message.id, value, error });
+                }).catch(error => finish({ result: null, error: String(error) }));
+            });
+        });
+    }
+}
+async function runSandbox() {
+    const { getQuickJS } = await import("quickjs-emscripten");
+    const module = await getQuickJS();
+    const runtime = module.newRuntime();
+    runtime.setMemoryLimit(workerData.limits.memoryBytes);
+    runtime.setMaxStackSize(256 * 1024);
+    const vm = runtime.newContext();
+    const pending = new Map();
+    const logs = [];
+    let logSize = 0;
+    let nextId = 0;
+    let remainingCpu = workerData.limits.cpuMs;
+    let sliceStart = Date.now();
+    let closed = false;
+    runtime.setInterruptHandler(() => Date.now() - sliceStart >= remainingCpu);
+    const run = (operation) => {
+        sliceStart = Date.now();
+        try {
+            return operation();
+        }
+        finally {
+            remainingCpu -= Date.now() - sliceStart;
+        }
+    };
+    const errorText = (value) => typeof value === "object" && value && "message" in value
+        ? String(value.message) : String(value);
+    const complete = (value) => {
+        if (closed)
+            return;
+        closed = true;
+        parentPort.postMessage({ type: "result", value: { ...value, logs } });
+    };
+    for (const provider of workerData.providers) {
+        const object = vm.newObject();
+        for (const name of provider.tools) {
+            const fn = vm.newFunction(name, args => {
+                const deferred = vm.newPromise();
+                const id = ++nextId;
+                pending.set(id, deferred);
+                parentPort.postMessage({ type: "tool", id, provider: provider.name, name, args: args ? vm.dump(args) : {} });
+                return deferred.handle;
+            });
+            vm.setProp(object, name, fn);
+            fn.dispose();
+        }
+        vm.setProp(vm.global, provider.name, object);
+        object.dispose();
+    }
+    const consoleObject = vm.newObject();
+    for (const name of ["log", "warn", "error"]) {
+        const fn = vm.newFunction(name, (...args) => {
+            if (logSize >= 8000)
+                return;
+            const line = args.map(arg => {
+                const value = vm.dump(arg);
+                return typeof value === "string" ? value : JSON.stringify(value);
+            }).join(" ").slice(0, 8000 - logSize);
+            logs.push(line);
+            logSize += line.length;
+        });
+        vm.setProp(consoleObject, name, fn);
+        fn.dispose();
+    }
+    vm.setProp(vm.global, "console", consoleObject);
+    consoleObject.dispose();
+    parentPort.on("message", message => {
+        if (closed || message.type !== "tool-result")
+            return;
+        const deferred = pending.get(message.id);
+        if (!deferred)
+            return;
+        pending.delete(message.id);
+        try {
+            if (message.error) {
+                const error = vm.newError(message.error);
+                deferred.reject(error);
+                error.dispose();
+            }
+            else {
+                const handle = run(() => vm.unwrapResult(vm.evalCode(`(${JSON.stringify(message.value ?? null)})`)));
+                deferred.resolve(handle);
+                handle.dispose();
+            }
+        }
+        catch (error) {
+            complete({ result: null, error: errorText(error) });
+        }
+        finally {
+            deferred.dispose();
+        }
+    });
+    const program = String(workerData.code).trim().replace(/;+\s*$/, "");
+    const evaluated = run(() => vm.evalCode(`(${program})()`));
+    if (evaluated.error) {
+        const error = errorText(vm.dump(evaluated.error));
+        evaluated.dispose();
+        complete({ result: null, error });
+    }
+    else {
+        const resultHandle = evaluated.value;
+        while (!closed) {
+            if (remainingCpu <= 0) {
+                complete({ result: null, error: "Program exceeded CPU time limit" });
+                break;
+            }
+            const jobs = run(() => runtime.executePendingJobs(100));
+            if (jobs.error) {
+                const error = errorText(vm.dump(jobs.error));
+                jobs.dispose();
+                complete({ result: null, error });
+                break;
+            }
+            const state = run(() => vm.getPromiseState(resultHandle));
+            if (state.type === "fulfilled") {
+                try {
+                    complete({ result: vm.dump(state.value), ...(pending.size ? { error: "Program returned with unawaited tool calls; inspect completed operations" } : {}) });
+                }
+                finally {
+                    state.value.dispose();
+                }
+                break;
+            }
+            if (state.type === "rejected") {
+                const error = errorText(vm.dump(state.error));
+                state.error.dispose();
+                complete({ result: null, error });
+                break;
+            }
+            await new Promise(resolve => setTimeout(resolve, 2));
+        }
+        resultHandle.dispose();
+    }
+    for (const deferred of pending.values())
+        deferred.dispose();
+    vm.dispose();
+    runtime.dispose();
+    parentPort.close();
+}
+if (!isMainThread && workerData?.neutrinoCode) {
+    void runSandbox().catch(error => parentPort.postMessage({ type: "result", value: { result: null, error: String(error) } }));
+}

package/dist/llm/codemode.js

@@ -0,0 +1,164 @@
+import { createBrowserCodeTool } from "@cloudflare/codemode/browser";
+import ts from "typescript";
+import { getToolDefinitions } from "./tools.js";
+import { LocalCodeExecutor } from "./codeExecutor.js";
+export const CODE_TOOL = "execute_ts";
+export class ProgramToolDenied extends Error {
+}
+function descriptors(call, step) {
+    const tools = {};
+    for (const definition of getToolDefinitions()) {
+        const { name, description, parameters } = definition.function;
+        tools[name] = {
+            description, inputSchema: parameters, outputSchema: { type: "string" },
+            // Approval is inside the callback. SDK needsApproval would exclude tools
+            // entirely rather than use Neutrino's per-call, argument-aware gate.
+            execute: async (args) => {
+                if (!args || typeof args !== "object" || Array.isArray(args))
+                    throw new Error(`${name} needs an argument object`);
+                const properties = parameters.properties;
+                for (const required of parameters.required ?? []) {
+                    if (typeof args[required] !== properties[required]?.type || (typeof args[required] === "string" && !args[required].trim())) {
+                        throw new Error(`${name}: invalid or missing ${required}`);
+                    }
+                }
+                if (typeof args.reason !== "string" || !args.reason.trim())
+                    throw new Error(`${name} needs an honest reason`);
+                return call(name, args);
+            },
+        };
+    }
+    for (const [name, status] of [["set_step", "active"], ["complete_step", "done"]]) {
+        tools[name] = {
+            description: `${status === "active" ? "Start" : "Complete after verification"} a zero-based step of this execution's plan.`,
+            inputSchema: { type: "object", properties: { index: { type: "integer" } }, required: ["index"] },
+            outputSchema: { type: "string" },
+            execute: async (args) => { step(Number(args.index), status); return "Progress recorded"; },
+        };
+    }
+    return tools;
+}
+const DESCRIPTION = `Plan-Then-Code: execute a TypeScript async arrow function to compose multiple tool operations.
+Supply a short plan before the code. All external work uses codemode tools below;
+each actual call must include a reason and passes the normal approval gate.
+Use codemode.set_step({index}) and codemode.complete_step({index}) for progress.
+Imports, process, require, direct network and host filesystem APIs are unavailable.
+Keep intermediate data local and return only necessary evidence. console output is bounded.
+Tool RPCs are serialized; Promise.all preserves correctness but does not parallelize side effects.
+On error, inspect completed calls before continuing; never blindly repeat writes or commands.
+Available typed API:
+{{types}}`;
+let definition;
+export function getCodeToolDefinition() {
+    if (definition)
+        return definition;
+    const descriptor = createBrowserCodeTool({
+        tools: descriptors(async () => "", () => { }),
+        executor: new LocalCodeExecutor(), description: DESCRIPTION,
+    });
+    return definition = {
+        type: "function",
+        function: {
+            name: CODE_TOOL, description: descriptor.description,
+            parameters: {
+                type: "object",
+                properties: {
+                    plan: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 10, description: "Short ordered steps, written before the code." },
+                    code: { type: "string", description: "An async TypeScript arrow function: async () => { ...; return evidence; }" },
+                    reason: { type: "string", description: "An honest sentence explaining why this execution is needed." },
+                },
+                required: ["plan", "code", "reason"],
+            },
+        },
+    };
+}
+/** Only the program's return, bounded logs and completion ledger enter LLM context. */
+export async function executeCodeProgram(args, options) {
+    const completed = [];
+    const controller = new AbortController();
+    const inFlight = new Set();
+    const abort = () => controller.abort(options.signal?.reason ?? "Execution cancelled");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    let plan;
+    try {
+        if (typeof args.code !== "string" || !args.code.trim() || args.code.length > 200_000)
+            throw new Error("code must contain at most 200000 characters");
+        if (typeof args.reason !== "string" || !args.reason.trim())
+            throw new Error("execute_ts needs an honest reason");
+        if (!Array.isArray(args.plan) || args.plan.length < 1 || args.plan.length > 10 || args.plan.some(s => typeof s !== "string" || !s.trim() || s.length > 160)) {
+            throw new Error("plan must contain 1–10 short nonempty steps (160 characters each)");
+        }
+        if (controller.signal.aborted)
+            throw new Error("Execution cancelled");
+        plan = { goal: args.reason, steps: args.plan.map(title => ({ title: title.trim(), status: "pending" })) };
+        options.onPlan(plan);
+        options.onStep(0, "active");
+        const source = args.code.trim().replace(/^```(?:typescript|ts|javascript|js)?\s*\n([\s\S]*?)\n```$/i, "$1");
+        const compiled = ts.transpileModule(source, {
+            compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext },
+            fileName: "agent-program.ts", reportDiagnostics: true,
+        });
+        const errors = compiled.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+        if (errors.length)
+            throw new Error(errors.map(d => ts.flattenDiagnosticMessageText(d.messageText, "\n")).join("\n"));
+        const tool = createBrowserCodeTool({
+            executor: new LocalCodeExecutor(controller.signal), description: DESCRIPTION,
+            tools: descriptors(async (name, callArgs) => {
+                if (controller.signal.aborted)
+                    throw new Error("Execution cancelled");
+                try {
+                    const operation = options.call(name, callArgs, controller.signal);
+                    inFlight.add(operation);
+                    let value;
+                    try {
+                        value = await operation;
+                    }
+                    finally {
+                        inFlight.delete(operation);
+                    }
+                    const target = typeof callArgs.path === "string" ? callArgs.path : typeof callArgs.command === "string" ? callArgs.command.slice(0, 200) : undefined;
+                    completed.push({ tool: name, ...(target ? { target } : {}) });
+                    return value;
+                }
+                catch (error) {
+                    // Once denied, even code that catches the exception cannot issue a
+                    // different tool call to work around the verdict.
+                    if (error instanceof ProgramToolDenied)
+                        controller.abort(error.message);
+                    throw error;
+                }
+            }, (index, status) => {
+                if (!Number.isInteger(index) || index < 0 || index >= plan.steps.length)
+                    throw new Error("Invalid plan step index");
+                options.onStep(index, status);
+            }),
+        });
+        const output = await tool.execute({ code: compiled.outputText });
+        if (plan.steps.length === 1)
+            options.onStep(0, "done");
+        if (plan.steps.some(s => s.status !== "done"))
+            plan.stopped = true;
+        return boundedJson({ ok: true, ...output, completed });
+    }
+    catch (error) {
+        controller.abort(error instanceof Error ? error.message : String(error));
+        await Promise.allSettled([...inFlight]);
+        if (plan) {
+            for (const step of plan.steps)
+                if (step.status === "active")
+                    step.status = "failed";
+            plan.stopped = true;
+        }
+        return boundedJson({ ok: false, error: error instanceof Error ? error.message : String(error), completed,
+            instruction: "Inspect the completed-call ledger and saved tool results. Do not replay completed side effects. Respect any approval denial." });
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abort);
+    }
+}
+function boundedJson(value) {
+    const text = JSON.stringify(value, (_key, v) => typeof v === "bigint" ? String(v) : v);
+    return text.length > 16_000 ? `${text.slice(0, 16_000)}\n[Program result truncated; return a smaller summary.]` : text;
+}

package/dist/llm/context.js

@@ -0,0 +1,97 @@
+import { TaskControlError } from "./runtime.js";
+/** Spend only the root's reserved report request; local evidence remains the fallback. */
+export async function finalTaskReport(runtime, createClient, onUsage) {
+    const recorded = runtime.partialReport();
+    try {
+        const client = createClient();
+        const report = await client.complete("The task stopped at a shared budget limit. Produce a brief partial report in the user's language using only the recorded operations. State what was actually completed and what remains unverified. Do not claim the entire task succeeded. No tools or further work are available.", JSON.stringify({ request: runtime.originalRequest, evidence: recorded }), { signal: runtime.signal, final: true, maxOutputTokens: 1024 });
+        if (client.usage)
+            onUsage?.(client.usage);
+        if (client.outcome?.status === "completed" && report.trim())
+            return `${report}\n\n[Task result is partial: shared budget exhausted.]`;
+    }
+    catch { /* A request/token limit may leave no reporting capacity. */ }
+    return recorded;
+}
+/** Context scheduling estimate for mixed ASCII/CJK; provider usage is also checked. */
+export function estimateTokens(value) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    let ascii = 0;
+    let other = 0;
+    for (const char of text) {
+        if (char.codePointAt(0) < 128)
+            ascii++;
+        else
+            other++;
+    }
+    return Math.ceil(ascii / 3) + other;
+}
+export const DEFAULT_OUTPUT_TOKENS = 16_384;
+export function outputAllowance(capacity) { return Math.max(64, Math.min(DEFAULT_OUTPUT_TOKENS, Math.floor(capacity * 0.1))); }
+/** Reserve a byte-based upper estimate, including framing, when usage is unknown. */
+export function inputTokenBound(value) { return Buffer.byteLength(JSON.stringify(value), "utf8") + 512; }
+function truncate(text, tokens) {
+    if (tokens <= 0)
+        return "";
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (estimateTokens(text.slice(0, mid)) <= tokens)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return text.slice(0, low);
+}
+/** Compact complete assistant/tool groups before any request, including wrap-up. */
+export async function prepareContext(options) {
+    const { messages, tools, capacity } = options;
+    const schema = estimateTokens(tools) + 32;
+    const allowance = outputAllowance(capacity);
+    const limit = Math.floor(capacity * 0.8) - schema - allowance;
+    if (Math.max(estimateTokens(messages), (options.lastPromptTokens ?? 0) - schema) <= limit)
+        return;
+    // Keep the system policy and current user input intact. Earlier history is evidence.
+    let lastUser = -1;
+    for (let i = 0; i < messages.length; i++)
+        if (messages[i].role === "user")
+            lastUser = i;
+    // A wrap-up instruction is appended after preparation, so this is the actual brief.
+    const head = options.preserveBrief ? messages.slice(0, 2) : [messages[0], ...(lastUser > 0 ? [messages[lastUser]] : [])];
+    const available = limit - estimateTokens(head) - 64;
+    if (available < 64)
+        throw new TaskControlError("context_capacity", "The task brief and tool definitions exceed this model's context capacity");
+    const body = options.preserveBrief ? messages.slice(2) : messages.filter((_, index) => index > 0 && index !== lastUser);
+    if (!body.length)
+        return;
+    options.onProgress?.();
+    const starts = body.flatMap((message, index) => message.role === "assistant" ? [index] : []);
+    let keep = starts.at(-1) ?? body.length;
+    if (estimateTokens(body.slice(keep)) > available * 0.45)
+        keep = body.length;
+    const transcript = JSON.stringify(body.slice(0, keep));
+    const inputBudget = Math.max(64, Math.floor(capacity * 0.45));
+    const input = estimateTokens(transcript) > inputBudget
+        ? `${truncate(transcript, Math.floor(inputBudget / 2))}\n[Truncated; full tool records remain in the task ledger]\n${[...truncate([...transcript].reverse().join(""), Math.floor(inputBudget / 2))].reverse().join("")}`
+        : transcript;
+    let summary = "";
+    try {
+        const client = options.createClient();
+        summary = await client.summarize(input, { ...options.stream, maxOutputTokens: Math.min(allowance, Math.floor(available / 2)) });
+        if (client.usage)
+            options.onUsage?.(client.usage);
+    }
+    catch { /* Fall back to a bounded local record, never erase the durable ledger. */ }
+    if (options.stream?.cancelled?.() || options.stream?.signal?.aborted)
+        throw new TaskControlError("cancelled", "Task cancelled during context compression");
+    const retained = body.slice(keep);
+    const fallback = "Earlier activity is recorded in the task ledger. Unverified work remains incomplete.\n" +
+        body.filter(message => message.role === "tool").slice(-12).map(message => `${message.tool_call_id}: ${message.content?.slice(0, 160) ?? ""}`).join("\n");
+    const summaryBudget = Math.max(32, available - estimateTokens(retained) - 32);
+    const compacted = { role: "assistant", content: truncate(summary || fallback, summaryBudget) };
+    messages.splice(0, messages.length, ...head, compacted, ...retained);
+    if (estimateTokens(messages) > limit) {
+        messages.splice(head.length, messages.length - head.length, { role: "assistant", content: truncate(summary || fallback, available - 32) });
+    }
+}

package/dist/llm/plan.js

@@ -12,6 +12,9 @@
  * The model calls themselves live in the two agent loops.
  */
 import { displayWidth, ellipsize } from "../width.js";
+import fs from "node:fs";
+import path from "node:path";
+import { currentTask } from "./runtime.js";
 /**
  * One step is not a plan, it is the answer: such a turn runs as a plain turn.
  * The ceiling keeps the card readable and the turn's cost proportionate.
@@ -89,10 +92,15 @@ function normalizeStep(value) {
     if (!title)
         return null;
     const detail = cleanText(o.detail ?? o.description ?? o.how ?? o.acceptance, PLAN_MAX_DETAIL);
-    return { title, status: "pending", ...(detail ? { detail } : {}) };
+    const id = cleanText(o.id, 80);
+    const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string").slice(0, 10).map(v => cleanText(v, PLAN_MAX_DETAIL)) : undefined;
+    const dependsOn = strings(o.dependsOn ?? o.depends_on);
+    const acceptanceCriteria = strings(o.acceptanceCriteria ?? o.acceptance_criteria);
+    return { title, status: "pending", ...(detail ? { detail } : {}), ...(id ? { id } : {}),
+        ...(dependsOn ? { dependsOn } : {}), ...(acceptanceCriteria ? { acceptanceCriteria } : {}) };
 }
 /** Turn an already-parsed planner answer into a plan, or null when unusable. */
-export function normalizePlan(value) {
+export function normalizePlan(value, minSteps = PLAN_MIN_STEPS) {
     if (!value || typeof value !== "object")
         return null;
     const o = value;
@@ -107,7 +115,7 @@ export function normalizePlan(value) {
         if (steps.length >= PLAN_MAX_STEPS)
             break;
     }
-    if (steps.length < PLAN_MIN_STEPS)
+    if (steps.length < minSteps)
         return null;
     const goal = cleanText(o.goal ?? o.title ?? o.summary ?? o.request, 240);
     return { goal, steps };
@@ -157,7 +165,7 @@ function jsonCandidates(text) {
     return out;
 }
 /** A numbered or bulleted list, for a planner that answered in prose. */
-function planFromList(text) {
+function planFromList(text, minSteps = PLAN_MIN_STEPS) {
     const steps = [];
     for (const line of text.split("\n")) {
         // "1." "1)" "1、" and bullets all show up in practice, with or without a
@@ -172,7 +180,7 @@ function planFromList(text) {
         if (steps.length >= PLAN_MAX_STEPS)
             break;
     }
-    if (steps.length < PLAN_MIN_STEPS)
+    if (steps.length < minSteps)
         return null;
     return { goal: "", steps };
 }
@@ -181,7 +189,7 @@ function planFromList(text) {
  * then a numbered list so a model that ignores the format still produces a
  * usable plan. Anything else is "no plan": the turn then runs as before.
  */
-export function parsePlan(text) {
+export function parsePlan(text, minSteps = PLAN_MIN_STEPS) {
     const raw = String(text ?? "").trim();
     if (!raw || /^\[Error/.test(raw))
         return null;
@@ -193,11 +201,11 @@ export function parsePlan(text) {
         catch {
             continue;
         }
-        const plan = normalizePlan(value);
+        const plan = normalizePlan(value, minSteps);
         if (plan)
             return plan;
     }
-    return planFromList(raw);
+    return planFromList(raw, minSteps);
 }
 /**
  * The user turn handed to the planner agent. The planner gets no tools, so
@@ -281,7 +289,7 @@ export function resumePlan(loaded) {
         return null;
     loaded.steps = steps;
     for (const step of steps) {
-        if (step.status !== "pending" && step.status !== "active" && step.status !== "done" && step.status !== "failed") {
+        if (!["pending", "active", "done", "failed", "blocked", "cancelled", "skipped"].includes(step.status)) {
             step.status = "pending";
         }
         if (step.status === "active") {
@@ -372,6 +380,9 @@ const STEP_GLYPH = {
     active: "●",
     done: "✓",
     failed: "✗",
+    blocked: "!",
+    cancelled: "⊘",
+    skipped: "–",
 };
 /**
  * Lay the plan out as a vertical timeline, top to bottom in execution order.
@@ -450,3 +461,80 @@ export function planRowsWidth(rows) {
         width = Math.max(width, displayWidth(row.text));
     return width;
 }
+/** Pro plans use explicit step acceptance instead of inferring success from prose. */
+export const FINISH_STEP_TOOL = "finish_step";
+export const FINISH_STEP_DEFINITION = {
+    type: "function", function: {
+        name: FINISH_STEP_TOOL,
+        description: "Record acceptance of one plan step. Only the main coordinator can accept steps. For done, reference actual successful evidence IDs or existing artifact paths, or provide the final text deliverable. Use blocked/failed for unresolved work. Finishing a reply never completes plan steps automatically.",
+        parameters: { type: "object", properties: {
+                step_id: { type: "string" },
+                status: { type: "string", enum: ["done", "blocked", "failed", "skipped"] },
+                summary: { type: "string" },
+                evidence_ids: { type: "array", items: { type: "string" } },
+                artifact_paths: { type: "array", items: { type: "string" } },
+                deliverable: { type: "string", description: "The actual final content, only for a text deliverable." },
+                reason: { type: "string" },
+            }, required: ["step_id", "status", "summary", "reason"] },
+    },
+};
+export function preparePlan(plan) {
+    const ids = new Set();
+    for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        step.id ||= `step-${i + 1}`;
+        if (ids.has(step.id))
+            throw new Error("Plan contains duplicate step IDs");
+        const dependencies = step.dependsOn ?? (i ? [plan.steps[i - 1].id] : []);
+        if (dependencies.some(id => !ids.has(id)))
+            throw new Error("Plan dependencies must refer to earlier steps");
+        ids.add(step.id);
+        step.dependsOn = dependencies;
+        step.acceptanceCriteria ??= [step.detail || step.title];
+    }
+    return plan;
+}
+export function finishPlanStep(plan, args, runtime) {
+    if (currentTask()?.runId !== runtime.rootRunId)
+        return "[Error: only the root coordinator can accept plan steps]";
+    const step = plan?.steps.find(entry => entry.id === args.step_id);
+    if (!plan || !step)
+        return "[Error: unknown plan step_id]";
+    const status = String(args.status);
+    if (!["done", "blocked", "failed", "skipped"].includes(status) || typeof args.summary !== "string" || !args.summary.trim()) {
+        return "[Error: finish_step requires a valid status and a nonempty summary]";
+    }
+    const ids = Array.isArray(args.evidence_ids) ? args.evidence_ids.filter((id) => typeof id === "string") : [];
+    const artifacts = Array.isArray(args.artifact_paths) ? args.artifact_paths.filter((p) => typeof p === "string") : [];
+    if (status === "done") {
+        if (step.dependsOn?.some(id => plan.steps.find(entry => entry.id === id)?.status !== "done"))
+            return "[Error: step dependencies have not been completed]";
+        if (ids.some(id => !runtime.evidence.some(entry => entry.id === id && entry.status === "completed")))
+            return "[Error: completion references missing or unsuccessful evidence]";
+        if (artifacts.some(p => !fs.existsSync(path.resolve(runtime.cwd, p))))
+            return "[Error: completion references a missing artifact]";
+        if (!ids.length && !artifacts.length && !(typeof args.deliverable === "string" && args.deliverable.trim())) {
+            return "[Error: done requires actual evidence, an existing artifact, or the final text deliverable]";
+        }
+    }
+    step.status = status;
+    step.summary = args.summary.trim();
+    if (typeof args.deliverable === "string")
+        step.deliverable = args.deliverable;
+    step.evidenceIds = ids;
+    step.artifacts = artifacts;
+    plan.stopped = plan.steps.some(entry => ["blocked", "failed", "cancelled"].includes(entry.status));
+    const next = plan.steps.find(entry => entry.status === "pending" && entry.dependsOn?.every(id => plan.steps.find(s => s.id === id)?.status === "done"));
+    if (status === "done" && next)
+        next.status = "active";
+    return JSON.stringify({ step_id: step.id, status: step.status, summary: step.summary });
+}
+export function settlePlan(plan, cancelled = false) {
+    if (!plan)
+        return;
+    for (const step of plan.steps)
+        if (step.status === "active")
+            step.status = cancelled ? "cancelled" : "blocked";
+    if (plan.steps.some(step => step.status !== "done" && step.status !== "skipped"))
+        plan.stopped = true;
+}