@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/task-planner.js

@@ -4,17 +4,15 @@
  * planMultiTask() builds the plan incrementally: the LLM calls add_task one
  * task at a time, with per-task validation. Progress is yielded as task_update
  * events (TaskPlanned) so clients can watch the plan take shape in real time.
- *
- * plan() (single-task) keeps the original one-shot create_task tool.
  */
-import { withAgentSpanGen } from "@nodetool-ai/runtime";
+import { budgetFromContext, isProviderStop, withAgentSpanGen } from "@nodetool-ai/runtime";
+import { linkAbort } from "./utils/link-abort.js";
 import { createLogger } from "@nodetool-ai/config";
 import { TaskUpdateEvent } from "@nodetool-ai/protocol";
 const log = createLogger("nodetool.agents.planner");
-import { CreateTaskPlanTool } from "./tools/create-task-tool.js";
+import { Tool } from "./tools/base-tool.js";
 import { PlanBuilder, AddTaskTool, RemoveTaskTool, FinishPlanTool } from "./tools/plan-builder-tools.js";
-import { rejectAgenticProvider } from "./reject-agentic-provider.js";
-const MAX_RETRIES = 3;
+import { isNonEmptyString, isObjectLike, isString } from "./utils/type-guards.js";
 const MAX_PER_TASK_RETRIES = 3;
 const DEFAULT_PLANNING_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose objectives into parallel executable plans by calling tools.
 
@@ -25,9 +23,13 @@ const DEFAULT_PLANNING_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose objec
 4. If you added a task in error, call \`remove_task\` with its id.
 5. When all tasks are added, call \`finish_plan\` with the overall plan title.
 
+## User-Facing Status
+- Every tool's input schema includes a \`_message\` string field. Set it on EVERY call to a short (5-12 words), present-continuous status describing what you're doing (e.g. "Adding research task", "Removing duplicate summarize task", "Finalizing 5-task plan"). This is shown live in the UI while the planner runs.
+
 ## Structure
 - Task: { id, title, depends_on[], steps[] } — each task runs as an independent sub-agent.
 - Step: { id, instructions, depends_on[], output_schema?, tools? }
+- The LAST step of a task is the task's result: it runs after every sibling step and must consume their results.
 
 ## ID Rules (violations cause retries)
 - Task IDs: descriptive snake_case, e.g. "research_nlp", "write_summary".
@@ -37,26 +39,46 @@ const DEFAULT_PLANNING_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose objec
 ## Parallelism
 - Independent work goes in separate tasks (they run concurrently).
 - Only add \`depends_on\` when one task genuinely needs another's output.
-- Add a final aggregation task (depending on all others) when results need combining.
+
+## Final Synthesis Is NOT Your Job
+- Do NOT create an "assemble", "aggregate", "synthesize", "compile",
+  "combine", or "final report" task or step. The loop that ran your plan
+  writes the answer on its next turn, reading every task result you produced.
+- Plan tasks should GATHER and PRODUCE concrete artifacts (search results,
+  generated media, computed values, written sections, extracted facts).
+  Each task's result is stored in shared memory under \`task:<task_id>\`,
+  which is where that loop reads it.
+- The schema shown below is informational — it tells you what facts the
+  answer will need so you can plan tasks that produce them. Do NOT attach
+  it to any step's \`output_schema\`.
 
 ## Step Instructions
 - Specific and concise. State exactly what to do, not the whole objective.
-- Reference available tools by name.
 - Bad: "Research NLP and write a summary including main ideas and relevance."
-- Good: "Use google_search to find recent NLP advances. Summarize key findings in 2-3 sentences."
+- Good: "Summarize the three most cited NLP advances of the last year in 2-3 sentences."
 
 ## Step Granularity (hard rule)
 - One step = one focused operation that a sub-agent can finish in ~3 LLM turns.
   Typical shapes: a single search + summarize, a single image/video render, a single file write.
-- NEVER combine N independent items into one step (e.g. "research 3 games and render an image for each"
-  is 6 steps minimum, not 1). Fan out into N parallel steps/tasks, then an aggregation step.
 - If a step would need more than 2 tool calls of different kinds, split it.
 - Prefer many small parallel steps over a few wide ones — steps are iteration-capped, parallelism is cheap.
 
 ## Output Schemas
-- Include \`output_schema\` (as a JSON schema string) for steps that produce structured data.
-- The aggregation step MUST have an \`output_schema\` matching the plan's overall output schema.
+- Include \`output_schema\` (as a JSON schema string) on steps that produce
+  structured data the next step needs to consume programmatically.
+- Do NOT attach the overall plan output schema to any step — the final
+  schema-conformant result is assembled after the plan finishes.
 - Use type "object" at the top level.
+`;
+/**
+ * Appended to the planner contract only when the run actually carries
+ * execution tools. Advertising `find_model` / `generate_image` / `save_asset`
+ * to a planner whose steps have an empty toolbelt made it plan work no step
+ * could do, against the one line that said so.
+ */
+const TOOL_ENABLED_PLANNING_SECTIONS = `
+## Step Instructions (tools)
+- Reference available tools by name, e.g. "Use google_search to find recent NLP advances."
 
 ## Models & Media (use the right tools)
 - Before generating media, call \`find_model\` once for the relevant capability
@@ -64,13 +86,29 @@ const DEFAULT_PLANNING_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose objec
   generate_embedding) and pass the resulting \`provider\` + \`model\` to the
   generation tool.
 - Generation tools: \`generate_image\`, \`edit_image\`, \`generate_video\`,
-  \`animate_image\`, \`generate_speech\`, \`transcribe_audio\`, \`embed_text\`.
+  \`animate_image\`, \`generate_video_from_references\` (several image/video
+  references condition one clip), \`generate_speech\`, \`transcribe_audio\`,
+  \`embed_text\`.
 - These tools save outputs as ASSETS automatically — the result includes
   \`asset_id\` and \`asset_uri\` ("asset://<id>.<ext>"). Reference those in
   later steps and in the final response so the chat UI can show them.
 - For non-media artifacts the user should keep (reports, JSON, manifests),
   call \`save_asset\` with \`name\` + \`content\` (text) or \`content_base64\`
   (binary). Use \`read_asset\` / \`list_assets\` / \`get_asset\` to retrieve.`;
+/**
+ * Appended instead when the toolbelt is empty. Without it the planner writes
+ * "research and enumerate" steps that no step can carry out, and the run
+ * returns the model's own recall formatted as findings.
+ */
+const NO_TOOL_PLANNING_SECTIONS = `
+## No Execution Tools
+- This run has NO execution tools. Steps cannot search the web, read files,
+  call APIs, or generate media.
+- Plan only steps a model can complete from its own knowledge and from the
+  results of earlier steps. Never instruct a step to search, fetch, or download.
+- If the objective genuinely requires tools this run does not have, say so in
+  the first task's instructions instead of planning around it.
+`;
 const DEFAULT_SINGLE_TASK_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose objectives into executable step plans.
 
 ## Structure
@@ -85,6 +123,9 @@ const DEFAULT_SINGLE_TASK_SYSTEM_PROMPT = `You are a TaskArchitect. Decompose ob
 - Include \`output_schema\` (JSON schema string) for steps producing structured data.
 - Dependencies must form a valid DAG (no cycles).
 
+## User-Facing Status
+- Set the \`_message\` field on EVERY tool call to a short (5-12 words), present-continuous status describing what you're doing (e.g. "Creating 3-step research plan"). This is shown live in the UI.
+
 Call the \`create_task\` tool with your task plan.`;
 const PLAN_CREATION_PROMPT_TEMPLATE = `Build an executable TaskPlan by calling add_task once per task, then finish_plan.
 
@@ -93,125 +134,44 @@ Objective: {{objective}}
 Available tools (reference by name in step instructions):
 {{toolsInfo}}
 
-Output schema for the final aggregation step:
+Final result schema (informational — assembled from your tasks' results after the plan finishes; do NOT attach it to any step):
 {{outputSchema}}
 
-Remember: prefix step IDs with their task ID (e.g. "task1_search", "task1_summarize") to avoid collisions. Call add_task for each task in dependency order.`;
-const TASK_CREATION_PROMPT_TEMPLATE = `Create an executable task plan using the create_task tool.
-
-Objective: {{objective}}
-
-Available tools (reference by name in step instructions):
-{{toolsInfo}}
-
-Output schema for the final step:
-{{outputSchema}}`;
+Remember:
+- Prefix step IDs with their task ID (e.g. "task1_search", "task1_summarize") to avoid collisions.
+- List each task's steps so the last one is the task's result and consumes its siblings.
+- Call add_task for each task in dependency order.
+- Do NOT add an aggregation/synthesis/assemble task — the loop that ran the plan reads each task's result from memory and writes the answer itself.`;
 export class TaskPlanner {
     provider;
     model;
-    reasoningModel;
     tools;
     systemPrompt;
+    preamble;
     outputSchema;
     inputs;
-    maxRetries;
     threadId;
+    budget;
+    signal;
     constructor(opts) {
         this.provider = opts.provider;
         this.model = opts.model;
-        this.reasoningModel = opts.reasoningModel ?? opts.model;
         this.tools = opts.tools ?? [];
+        // A caller-supplied prompt is a PREAMBLE, not a replacement — the same rule
+        // the step executors already follow. It used to replace the whole contract,
+        // and every AgentNode supplies one ("You are a friendly assistant"), so a
+        // node-driven run planned with no ID rules, no parallelism rules, no
+        // output-schema rules and no "synthesis is not your job".
+        this.preamble =
+            opts.systemPrompt && opts.systemPrompt !== DEFAULT_PLANNING_SYSTEM_PROMPT
+                ? opts.systemPrompt
+                : undefined;
         this.systemPrompt = opts.systemPrompt ?? DEFAULT_PLANNING_SYSTEM_PROMPT;
         this.outputSchema = opts.outputSchema;
         this.inputs = opts.inputs ?? {};
-        this.maxRetries = opts.maxRetries ?? MAX_RETRIES;
         this.threadId = opts.threadId;
-    }
-    // ---------------------------------------------------------------------------
-    // Single-task planning (legacy one-shot)
-    // ---------------------------------------------------------------------------
-    async *plan(objective, context) {
-        return yield* withAgentSpanGen("plan", {
-            objective,
-            provider: this.provider.provider,
-            model: this.model,
-            toolsCount: this.tools.length,
-            extra: { "agent.plan.kind": "single" }
-        }, () => this._planImpl(objective, context));
-    }
-    async *_planImpl(objective, _context) {
-        rejectAgenticProvider(this.provider, "TaskPlanner.plan");
-        const toolsInfo = this.formatToolsInfo();
-        const userPrompt = TASK_CREATION_PROMPT_TEMPLATE
-            .replace("{{objective}}", objective)
-            .replace("{{toolsInfo}}", toolsInfo)
-            .replace("{{outputSchema}}", this.outputSchema
-            ? JSON.stringify(this.outputSchema, null, 2)
-            : "None specified");
-        const systemPrompt = this.systemPrompt !== DEFAULT_PLANNING_SYSTEM_PROMPT
-            ? this.systemPrompt
-            : DEFAULT_SINGLE_TASK_SYSTEM_PROMPT;
-        const messages = [
-            { role: "system", content: systemPrompt },
-            { role: "user", content: userPrompt }
-        ];
-        yield {
-            type: "planning_update",
-            phase: "initialization",
-            status: "started",
-            content: "Starting task planning..."
-        };
-        const createTaskTool = new CreateTaskPlanTool(this.inputs);
-        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
-            yield {
-                type: "planning_update",
-                phase: "generation",
-                status: "running",
-                content: attempt > 0
-                    ? `Retry attempt ${attempt + 1}/${this.maxRetries}...`
-                    : "Generating plan..."
-            };
-            const toolCallResult = yield* this.callSingleTaskTool(messages, createTaskTool);
-            if (createTaskTool.task) {
-                yield {
-                    type: "planning_update",
-                    phase: "complete",
-                    status: "success",
-                    content: `Plan created: ${createTaskTool.task.title} (${createTaskTool.task.steps.length} steps)`
-                };
-                return createTaskTool.task;
-            }
-            const errorMsg = toolCallResult.error ??
-                `Planning tool was not called successfully on attempt ${attempt + 1}/${this.maxRetries}`;
-            yield {
-                type: "planning_update",
-                phase: "validation",
-                status: "failed",
-                content: errorMsg
-            };
-            if (toolCallResult.assistantContent) {
-                messages.push({
-                    role: "assistant",
-                    content: toolCallResult.assistantContent
-                });
-            }
-            messages.push({
-                role: "user",
-                content: `Error: ${errorMsg}. Please call the create_task tool with a corrected plan.`
-            });
-        }
-        yield {
-            type: "chunk",
-            content: `\nFailed to generate a task plan after ${this.maxRetries} attempts.\n`,
-            done: true
-        };
-        yield {
-            type: "planning_update",
-            phase: "complete",
-            status: "failed",
-            content: `Plan generation failed after ${this.maxRetries} attempts`
-        };
-        return null;
+        this.budget = opts.budget;
+        this.signal = opts.signal;
     }
     // ---------------------------------------------------------------------------
     // Multi-task planning (incremental)
@@ -225,16 +185,15 @@ export class TaskPlanner {
             extra: { "agent.plan.kind": "multi" }
         }, () => this._planMultiTaskImpl(objective, context));
     }
-    async *_planMultiTaskImpl(objective, _context) {
+    async *_planMultiTaskImpl(objective, context) {
         const toolsInfo = this.formatToolsInfo();
-        const userPrompt = PLAN_CREATION_PROMPT_TEMPLATE
-            .replace("{{objective}}", objective)
+        const userPrompt = PLAN_CREATION_PROMPT_TEMPLATE.replace("{{objective}}", objective)
             .replace("{{toolsInfo}}", toolsInfo)
             .replace("{{outputSchema}}", this.outputSchema
             ? JSON.stringify(this.outputSchema, null, 2)
             : "None specified");
         const messages = [
-            { role: "system", content: this.systemPrompt },
+            { role: "system", content: this.buildSystemPrompt(false) },
             { role: "user", content: userPrompt }
         ];
         yield {
@@ -243,7 +202,16 @@ export class TaskPlanner {
             status: "started",
             content: "Starting parallel task planning..."
         };
-        rejectAgenticProvider(this.provider, "TaskPlanner.planMultiTask");
+        // A plan whose steps have no toolbelt can only produce what the model
+        // already knows. Say it once, where the reader of the run will see it.
+        if (this.tools.length === 0) {
+            yield {
+                type: "planning_update",
+                phase: "initialization",
+                status: "running",
+                content: "No execution tools available — steps cannot search, fetch, read files or generate media."
+            };
+        }
         const builder = new PlanBuilder(this.inputs);
         const addTaskTool = new AddTaskTool(builder);
         const removeTaskTool = new RemoveTaskTool(builder);
@@ -253,238 +221,268 @@ export class TaskPlanner {
             [removeTaskTool.name, removeTaskTool],
             [finishPlanTool.name, finishPlanTool]
         ]);
-        const providerTools = [
-            addTaskTool.toProviderTool(),
-            removeTaskTool.toProviderTool(),
-            finishPlanTool.toProviderTool()
-        ];
         const perTaskFailures = new Map();
         const MAX_CALLS = 100;
-        for (let call = 0; call < MAX_CALLS; call++) {
-            const pendingToolCalls = [];
-            let assistantText = "";
-            const stream = this.provider.generateMessagesTraced({
-                messages: [...messages],
-                model: this.model,
-                tools: providerTools,
-                toolChoice: "any",
-                threadId: this.threadId
-            });
-            for await (const item of stream) {
-                if ("type" in item && item.type === "chunk") {
-                    const chunk = item;
-                    if (typeof chunk.content === "string" && chunk.content.length > 0) {
-                        assistantText += chunk.content;
-                        yield {
-                            type: "chunk",
-                            content: chunk.content,
-                            done: false
-                        };
-                    }
-                }
-                if ("id" in item && "name" in item && "args" in item) {
-                    pendingToolCalls.push(item);
+        // Delegate the tool loop to the provider so backends that run their own
+        // agent loop (e.g. the Claude Agent SDK) work. Each plan tool carries its
+        // own `execute` closure that mutates the shared builder and buffers the UI
+        // events its result implies; the stream consumer below drains that buffer
+        // in order.
+        //
+        // `finish_plan` is only *conditionally* terminal: on a valid plan it
+        // commits and aborts the loop; on a validation failure it returns the
+        // errors as the tool result and does NOT abort, so the model iterates and
+        // fixes the plan within the call budget. The static `terminal` flag can't
+        // express that, so the AbortController stops the loop on a successful
+        // finish. It also short-circuits when a single task fails validation too
+        // many times (an early-stop that is not a terminal tool).
+        const abort = new AbortController();
+        // External cancellation (user pressed Stop) fires the same controller.
+        const unlinkAbort = linkAbort(abort, this.signal);
+        const uiEvents = [];
+        let finished = false;
+        let abortedReason = null;
+        const addTaskExecute = async (args) => {
+            const result = (await Tool.executeTool(addTaskTool, context, args));
+            const status = result["status"];
+            const taskId = isString(args["id"]) ? args["id"] : undefined;
+            if (status === "task_added") {
+                const added = builder.currentTasks[builder.currentTasks.length - 1];
+                // The task landed, so its earlier rejections are spent: the counter
+                // must not carry over and abort a later, unrelated correction.
+                perTaskFailures.delete(taskId ?? "_");
+                if (added)
+                    uiEvents.push(this.taskPlannedEvent(added));
+                uiEvents.push({
+                    type: "planning_update",
+                    phase: "generation",
+                    status: "running",
+                    content: `Added task ${builder.taskCount}: ${added?.title ?? taskId ?? ""}`
+                });
+            }
+            else if (status === "validation_failed") {
+                const errors = result["errors"] ?? [];
+                const count = (perTaskFailures.get(taskId ?? "_") ?? 0) + 1;
+                perTaskFailures.set(taskId ?? "_", count);
+                uiEvents.push({
+                    type: "planning_update",
+                    phase: "validation",
+                    status: "failed",
+                    content: `Task '${taskId ?? "?"}' validation failed (${count}/${MAX_PER_TASK_RETRIES}): ${errors.join("; ")}`
+                });
+                if (count >= MAX_PER_TASK_RETRIES) {
+                    abortedReason = `Task '${taskId ?? "?"}' failed validation ${count} times. Aborting plan.`;
+                    abort.abort();
                 }
             }
-            // Record assistant turn with any tool calls.
-            messages.push({
-                role: "assistant",
-                content: assistantText,
-                toolCalls: pendingToolCalls.length > 0 ? pendingToolCalls : undefined
-            });
-            if (pendingToolCalls.length === 0) {
-                messages.push({
-                    role: "user",
-                    content: "No tool call in your response. Call add_task, remove_task, or finish_plan to continue."
+            return JSON.stringify(result);
+        };
+        const removeTaskExecute = async (args) => {
+            const result = (await Tool.executeTool(removeTaskTool, context, args));
+            const status = result["status"];
+            const removedId = isString(args["id"]) ? args["id"] : "";
+            if (status === "task_removed") {
+                uiEvents.push({
+                    type: "task_update",
+                    event: TaskUpdateEvent.TaskRemoved,
+                    task: { id: removedId }
+                });
+                perTaskFailures.delete(removedId);
+                uiEvents.push({
+                    type: "planning_update",
+                    phase: "generation",
+                    status: "running",
+                    content: `Removed task: ${removedId}`
                 });
-                continue;
             }
-            let aborted = null;
-            let finished = false;
-            for (const tc of pendingToolCalls) {
-                const tool = toolsByName.get(tc.name);
-                if (!tool) {
-                    messages.push({
-                        role: "tool",
-                        toolCallId: tc.id,
-                        content: JSON.stringify({
-                            status: "error",
-                            error: `Unknown tool: ${tc.name}. Use add_task, remove_task, or finish_plan.`
-                        })
-                    });
-                    continue;
-                }
-                const args = (tc.args ?? {});
-                yield {
-                    type: "tool_call_update",
-                    node_id: "",
-                    name: tc.name,
-                    args,
-                    message: tool.userMessage(args)
-                };
-                const result = (await tool.process({}, args));
-                messages.push({
-                    role: "tool",
-                    toolCallId: tc.id,
-                    content: JSON.stringify(result)
+            return JSON.stringify(result);
+        };
+        const finishPlanExecute = async (args) => {
+            const result = (await Tool.executeTool(finishPlanTool, context, args));
+            const status = result["status"];
+            if (status === "plan_finished" && builder.plan) {
+                const plan = builder.plan;
+                const totalSteps = plan.tasks.reduce((s, t) => s + t.steps.length, 0);
+                const independent = plan.tasks.filter((t) => !t.dependsOn || t.dependsOn.length === 0).length;
+                log.info("Multi-task plan created", {
+                    title: plan.title,
+                    tasks: plan.tasks.length,
+                    steps: totalSteps,
+                    parallelizable: independent,
+                    // The shape is the thing worth reading back: a plan of six tasks in
+                    // a chain and one of six in parallel logged identically before this.
+                    plan: plan.tasks.map((t) => ({
+                        id: t.id,
+                        dependsOn: t.dependsOn ?? [],
+                        steps: t.steps.map((st) => st.id)
+                    }))
                 });
-                const status = result["status"];
-                if (tc.name === addTaskTool.name) {
-                    const taskId = typeof args["id"] === "string" ? args["id"] : undefined;
-                    if (status === "task_added") {
-                        const added = builder.currentTasks[builder.currentTasks.length - 1];
-                        if (added)
-                            yield this.taskPlannedEvent(added);
-                        yield {
-                            type: "planning_update",
-                            phase: "generation",
-                            status: "running",
-                            content: `Added task ${builder.taskCount}: ${added?.title ?? taskId ?? ""}`
-                        };
-                    }
-                    else if (status === "validation_failed") {
-                        const errors = result["errors"] ?? [];
-                        const count = (perTaskFailures.get(taskId ?? "_") ?? 0) + 1;
-                        perTaskFailures.set(taskId ?? "_", count);
-                        yield {
-                            type: "planning_update",
-                            phase: "validation",
-                            status: "failed",
-                            content: `Task '${taskId ?? "?"}' validation failed (${count}/${MAX_PER_TASK_RETRIES}): ${errors.join("; ")}`
-                        };
-                        if (count >= MAX_PER_TASK_RETRIES) {
-                            aborted = `Task '${taskId ?? "?"}' failed validation ${count} times. Aborting plan.`;
-                            break;
-                        }
-                    }
+                uiEvents.push({
+                    type: "planning_update",
+                    phase: "complete",
+                    status: "success",
+                    content: `Plan created: ${plan.title} (${plan.tasks.length} tasks, ${totalSteps} steps, ${independent} parallelizable)`
+                });
+                finished = true;
+                abort.abort();
+            }
+            else if (status === "validation_failed") {
+                const errors = result["errors"] ?? [];
+                uiEvents.push({
+                    type: "planning_update",
+                    phase: "validation",
+                    status: "failed",
+                    content: `finish_plan failed: ${errors.join("; ")}`
+                });
+            }
+            return JSON.stringify(result);
+        };
+        const providerTools = [
+            { ...addTaskTool.toProviderTool(), execute: addTaskExecute },
+            { ...removeTaskTool.toProviderTool(), execute: removeTaskExecute },
+            {
+                ...finishPlanTool.toProviderTool(),
+                execute: finishPlanExecute
+            }
+        ];
+        const drainUi = function* () {
+            while (uiEvents.length > 0)
+                yield uiEvents.shift();
+        };
+        // The run's budget, never a fresh one: planning turns spend the same cap,
+        // deadline and turn count as the steps the plan will run.
+        const budget = this.budget ?? budgetFromContext(context);
+        const loopArgs = {
+            messages,
+            model: this.model,
+            tools: providerTools,
+            toolChoice: "any",
+            threadId: this.threadId,
+            maxIterations: MAX_CALLS,
+            sequentialTools: true,
+            signal: abort.signal
+        };
+        if (budget)
+            loopArgs.turnBudget = budget;
+        const stream = this.provider.generateLoop(loopArgs);
+        // Why the provider loop stopped, when it was not the model ending its turn.
+        let providerStop = null;
+        try {
+            for await (const item of stream) {
+                // Planning is over: the plan committed, a task exhausted its retries,
+                // or the user cancelled. The loop is aborting, so anything the provider
+                // still emits describes work it can no longer do — including the model
+                // narrating a retry of the finish_plan call that just succeeded. Drop
+                // it instead of showing the user a contradiction.
+                if (finished || abortedReason !== null || abort.signal.aborted)
+                    break;
+                if (isProviderStop(item)) {
+                    providerStop = item;
+                    yield* drainUi();
+                    continue;
                 }
-                else if (tc.name === removeTaskTool.name) {
-                    const removedId = typeof args["id"] === "string" ? args["id"] : "";
-                    if (status === "task_removed") {
-                        yield {
-                            type: "task_update",
-                            event: TaskUpdateEvent.TaskRemoved,
-                            task: { id: removedId }
-                        };
-                        perTaskFailures.delete(removedId);
+                // A tool call is announced before it runs — surface it for live display.
+                if ("id" in item && "name" in item && "args" in item) {
+                    const tc = item;
+                    const tool = toolsByName.get(tc.name);
+                    if (tool) {
+                        const args = tc.args ?? {};
                         yield {
-                            type: "planning_update",
-                            phase: "generation",
-                            status: "running",
-                            content: `Removed task: ${removedId}`
+                            type: "tool_call_update",
+                            node_id: "",
+                            name: tc.name,
+                            args,
+                            message: Tool.resolveMessage(tool, args)
                         };
                     }
+                    yield* drainUi();
+                    continue;
                 }
-                else if (tc.name === finishPlanTool.name) {
-                    if (status === "plan_finished" && builder.plan) {
-                        const plan = builder.plan;
-                        const totalSteps = plan.tasks.reduce((s, t) => s + t.steps.length, 0);
-                        const independent = plan.tasks.filter((t) => !t.dependsOn || t.dependsOn.length === 0).length;
-                        log.info("Multi-task plan created", {
-                            title: plan.title,
-                            tasks: plan.tasks.length
-                        });
-                        yield {
-                            type: "planning_update",
-                            phase: "complete",
-                            status: "success",
-                            content: `Plan created: ${plan.title} (${plan.tasks.length} tasks, ${totalSteps} steps, ${independent} parallelizable)`
-                        };
-                        finished = true;
-                        break;
-                    }
-                    if (status === "validation_failed") {
-                        const errors = result["errors"] ?? [];
+                if ("type" in item && item.type === "chunk") {
+                    const chunk = item;
+                    if (isNonEmptyString(chunk.content) &&
+                        !chunk.done) {
                         yield {
-                            type: "planning_update",
-                            phase: "validation",
-                            status: "failed",
-                            content: `finish_plan failed: ${errors.join("; ")}`
+                            type: "chunk",
+                            content: chunk.content,
+                            done: false
                         };
                     }
+                    yield* drainUi();
+                    continue;
                 }
+                // Assistant/tool message events: a tool result just landed — flush its UI.
+                yield* drainUi();
             }
-            if (finished)
-                return builder.plan;
-            if (aborted) {
-                yield {
-                    type: "planning_update",
-                    phase: "complete",
-                    status: "failed",
-                    content: aborted
-                };
-                return null;
-            }
         }
-        log.error("Multi-task plan exhausted call budget", {
-            tasksSoFar: builder.taskCount
+        finally {
+            unlinkAbort();
+        }
+        yield* drainUi();
+        if (finished) {
+            return builder.plan;
+        }
+        if (abortedReason) {
+            yield {
+                type: "planning_update",
+                phase: "complete",
+                status: "failed",
+                content: abortedReason
+            };
+            return null;
+        }
+        // The loop ran out of something — the run's budget, deadline or turn
+        // count, or the planner's own call cap. Name the limit the budget recorded
+        // rather than reporting a model that "ended without finish_plan".
+        if (providerStop && providerStop.reason !== "aborted") {
+            const detail = providerStop.reason === "budget" || providerStop.reason === "deadline"
+                ? (budget?.exhausted?.detail ?? providerStop.detail)
+                : providerStop.detail;
+            log.warn("Multi-task planning stopped", {
+                reason: providerStop.reason,
+                detail,
+                tasksSoFar: builder.taskCount
+            });
+            yield {
+                type: "planning_update",
+                phase: "complete",
+                status: "failed",
+                content: `Planning stopped after ${builder.taskCount} task(s): ${detail}`
+            };
+            return null;
+        }
+        // The user pressed Stop. That is not a planning defect, and reporting it as
+        // an exhausted call budget sends the reader looking for a bug.
+        if (this.signal?.aborted) {
+            log.info("Multi-task planning cancelled", {
+                tasksSoFar: builder.taskCount
+            });
+            yield {
+                type: "planning_update",
+                phase: "complete",
+                status: "failed",
+                content: "Planning cancelled."
+            };
+            return null;
+        }
+        // The stream ended without finish_plan. Report what actually happened —
+        // "exhausted N calls" was printed for a model that simply stopped after one
+        // task, which sends the reader after a budget that was never spent.
+        log.error("Multi-task planning ended without finish_plan", {
+            tasksSoFar: builder.taskCount,
+            maxCalls: MAX_CALLS
         });
         yield {
             type: "planning_update",
             phase: "complete",
             status: "failed",
-            content: `Plan generation exhausted ${MAX_CALLS} calls without calling finish_plan`
+            content: builder.taskCount === 0
+                ? "Planning ended without adding any task."
+                : `Planning ended after ${builder.taskCount} task(s) without calling finish_plan (call budget ${MAX_CALLS}).`
         };
         return null;
     }
     // ---------------------------------------------------------------------------
-    // Single-task one-shot call
-    // ---------------------------------------------------------------------------
-    async *callSingleTaskTool(messages, planningTool) {
-        let content = "";
-        let toolCallArgs = null;
-        const providerTool = planningTool.toProviderTool();
-        const onToolCall = async (name, args) => {
-            if (name === planningTool.name) {
-                toolCallArgs = args;
-                return JSON.stringify({ status: "tool_called" });
-            }
-            return JSON.stringify({ error: `Unknown tool: ${name}` });
-        };
-        const stream = this.provider.generateMessagesTraced({
-            messages: [...messages],
-            model: this.model,
-            tools: [providerTool],
-            toolChoice: planningTool.name,
-            threadId: this.threadId,
-            onToolCall
-        });
-        for await (const item of stream) {
-            if ("type" in item &&
-                item["type"] === "chunk") {
-                const chunk = item;
-                if (typeof chunk.content === "string") {
-                    content += chunk.content;
-                    yield {
-                        type: "chunk",
-                        content: chunk.content,
-                        done: false
-                    };
-                }
-            }
-            if ("name" in item && item.name === planningTool.name) {
-                toolCallArgs = item.args;
-            }
-        }
-        if (!toolCallArgs) {
-            return {
-                error: `LLM did not call ${planningTool.name} tool`,
-                assistantContent: content || undefined
-            };
-        }
-        const result = await planningTool.process({}, toolCallArgs);
-        if (typeof result === "object" &&
-            result !== null &&
-            result["status"] === "validation_failed") {
-            const errors = result["errors"];
-            return {
-                error: `Plan validation failed:\n${errors.map((e) => `- ${e}`).join("\n")}`,
-                assistantContent: content || undefined
-            };
-        }
-        return { assistantContent: content || undefined };
-    }
-    // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
     taskPlannedEvent(task) {
@@ -504,14 +502,30 @@ export class TaskPlanner {
             }
         };
     }
+    /**
+     * The planner contract, with the caller's prompt in front of it and the
+     * tool-dependent sections included only when this run has tools.
+     */
+    buildSystemPrompt(singleTask) {
+        const contract = singleTask
+            ? DEFAULT_SINGLE_TASK_SYSTEM_PROMPT
+            : DEFAULT_PLANNING_SYSTEM_PROMPT +
+                (this.tools.length > 0
+                    ? TOOL_ENABLED_PLANNING_SECTIONS
+                    : NO_TOOL_PLANNING_SECTIONS);
+        return this.preamble ? `${this.preamble}\n\n${contract}` : contract;
+    }
     formatToolsInfo() {
-        if (this.tools.length === 0)
-            return "No execution tools available.";
+        if (this.tools.length === 0) {
+            return ("No execution tools available. Steps run with no tools at all: they " +
+                "cannot search the web, read or write files, call APIs, or generate " +
+                "media. Plan only steps a model can complete from its own knowledge.");
+        }
         const lines = ["Available execution tools for steps:"];
         for (const tool of this.tools) {
             let schemaInfo = "";
             const schema = tool.inputSchema;
-            if (schema && typeof schema === "object" && "properties" in schema) {
+            if (isObjectLike(schema) && "properties" in schema) {
                 const props = Object.keys(schema.properties);
                 const required = Array.isArray(schema.required)
                     ? schema.required