@lleverage-ai/agent-sdk 0.0.2 → 0.0.4

package/dist/agent.js

@@ -13,6 +13,7 @@ import { createRetryLoopState, handleGenerationError, invokePreGenerateHooks, no
 import { aggregatePermissionDecisions, extractUpdatedInput, extractUpdatedResult, invokeHooksWithTimeout, invokeMatchingHooks, } from "./hooks.js";
 import { MCPManager } from "./mcp/manager.js";
 import { applyMiddleware, mergeHooks, setupMiddleware } from "./middleware/index.js";
+import { createDefaultPromptBuilder } from "./prompt-builder/components.js";
 import { ACCEPT_EDITS_BLOCKED_PATTERNS } from "./security/index.js";
 import { TaskManager } from "./task-manager.js";
 import { coreToolsToToolSet, createCoreTools, createSearchToolsTool, createTaskOutputTool, createTaskTool, } from "./tools/factory.js";
@@ -41,6 +42,46 @@ class InterruptSignal extends Error {
 function isInterruptSignal(error) {
     return error instanceof InterruptSignal;
 }
+/**
+ * Outermost tool wrapper that intercepts flow-control signals.
+ *
+ * When a tool throws `InterruptSignal`, this wrapper catches it before the AI
+ * SDK can, stores it in the shared `signalState`, and returns a placeholder
+ * string. Combined with a custom `stopWhen` condition, this cleanly stops
+ * generation and allows `generate()` to inspect `signalState` in the normal
+ * return path (not the catch block).
+ *
+ * @internal
+ */
+function wrapToolsWithSignalCatching(tools, signalState) {
+    const wrapped = {};
+    for (const [name, toolDef] of Object.entries(tools)) {
+        if (!toolDef.execute) {
+            wrapped[name] = toolDef;
+            continue;
+        }
+        const originalExecute = toolDef.execute;
+        wrapped[name] = {
+            ...toolDef,
+            execute: async (input, options) => {
+                try {
+                    return await originalExecute.call(toolDef, input, options);
+                }
+                catch (error) {
+                    if (isInterruptSignal(error)) {
+                        if (signalState.interrupt) {
+                            throw error; // Already have a signal — let AI SDK handle this one
+                        }
+                        signalState.interrupt = error;
+                        return "[Interrupt requested]";
+                    }
+                    throw error;
+                }
+            },
+        };
+    }
+    return wrapped;
+}
 /**
  * File edit tool names that get auto-approved in acceptEdits mode.
  * @internal
@@ -456,17 +497,21 @@ function wrapToolsWithHooks(tools, hookRegistration, agent, sessionId) {
                     return output;
                 }
                 catch (error) {
-                    // Invoke PostToolUseFailure hooks
-                    if (hookRegistration?.PostToolUseFailure?.length) {
-                        const failureInput = {
-                            hook_event_name: "PostToolUseFailure",
-                            session_id: sessionId,
-                            cwd: process.cwd(),
-                            tool_name: name,
-                            tool_input: input,
-                            error: error instanceof Error ? error : new Error(String(error)),
-                        };
-                        await invokeMatchingHooks(hookRegistration.PostToolUseFailure, name, failureInput, toolUseId, agent);
+                    // Skip PostToolUseFailure for flow-control signals — these are not
+                    // actual failures but intentional control flow (interrupt).
+                    if (!isInterruptSignal(error)) {
+                        // Invoke PostToolUseFailure hooks
+                        if (hookRegistration?.PostToolUseFailure?.length) {
+                            const failureInput = {
+                                hook_event_name: "PostToolUseFailure",
+                                session_id: sessionId,
+                                cwd: process.cwd(),
+                                tool_name: name,
+                                tool_input: input,
+                                error: error instanceof Error ? error : new Error(String(error)),
+                            };
+                            await invokeMatchingHooks(hookRegistration.PostToolUseFailure, name, failureInput, toolUseId, agent);
+                        }
                     }
                     throw error;
                 }
@@ -527,10 +572,21 @@ function isBackendFactory(value) {
  */
 export function createAgent(options) {
     const id = `agent-${++agentIdCounter}`;
+    // Validate mutually exclusive prompt options
+    if (options.systemPrompt !== undefined && options.promptBuilder) {
+        throw new Error("Cannot specify both systemPrompt and promptBuilder - they are mutually exclusive");
+    }
+    // Determine prompt mode
+    // - 'static': Use systemPrompt string directly
+    // - 'builder': Use PromptBuilder to generate dynamic prompts
+    const promptMode = options.systemPrompt !== undefined ? "static" : "builder";
+    // Get or create prompt builder
+    const promptBuilder = options.promptBuilder ?? (promptMode === "builder" ? createDefaultPromptBuilder() : undefined);
     // Process middleware to get hooks (middleware hooks come before explicit hooks)
     const middleware = options.middleware ?? [];
     const middlewareHooks = applyMiddleware(middleware);
-    const mergedHooks = mergeHooks(middlewareHooks, options.hooks);
+    const pluginHooks = (options.plugins ?? []).filter((p) => p.hooks).map((p) => p.hooks);
+    const mergedHooks = mergeHooks(middlewareHooks, ...pluginHooks, options.hooks);
     // Create options with merged hooks for all hook lookups
     const effectiveHooks = mergedHooks;
     // Permission mode (mutable for setPermissionMode)
@@ -561,6 +617,18 @@ export function createAgent(options) {
     }
     // Initialize task manager for background task tracking
     const taskManager = new TaskManager();
+    // Background task completion options
+    const waitForBackgroundTasks = options.waitForBackgroundTasks ?? true;
+    const formatTaskCompletion = options.formatTaskCompletion ??
+        ((task) => {
+            const command = task.metadata?.command ?? "unknown command";
+            return `[Background task completed: ${task.id}]\nCommand: ${command}\nOutput:\n${task.result ?? "(no output)"}`;
+        });
+    const formatTaskFailure = options.formatTaskFailure ??
+        ((task) => {
+            const command = task.metadata?.command ?? "unknown command";
+            return `[Background task failed: ${task.id}]\nCommand: ${command}\nError: ${task.error ?? "Unknown error"}`;
+        });
     // Determine plugin loading mode
     // Track whether it was explicitly set to distinguish from default
     const explicitPluginLoading = options.pluginLoading !== undefined;
@@ -811,10 +879,71 @@ export function createAgent(options) {
         }
         return filtered;
     };
-    // Helper to get current active tools (core + MCP + dynamically loaded from registry)
+    // Helper to build prompt context from current agent state
+    const buildPromptContext = (messages, threadId) => {
+        // Get filtered tools (respecting allowedTools/disallowedTools) so the prompt
+        // only advertises tools the agent will actually expose
+        const filteredTools = filterToolsByAllowed((() => {
+            const allTools = { ...coreTools };
+            Object.assign(allTools, runtimeTools);
+            Object.assign(allTools, mcpManager.getToolSet());
+            if (toolRegistry) {
+                Object.assign(allTools, toolRegistry.getLoadedTools());
+            }
+            return allTools;
+        })());
+        // Extract tool metadata for context
+        const toolsMetadata = Object.entries(filteredTools).map(([name, tool]) => ({
+            name,
+            description: tool.description ?? "",
+        }));
+        // Extract skills metadata from the skills array
+        const skillsMetadata = skills.map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+        }));
+        // Extract plugins metadata
+        const pluginsMetadata = (options.plugins ?? []).map((plugin) => ({
+            name: plugin.name,
+            description: plugin.description ?? "",
+        }));
+        // Build backend info
+        const backendInfo = {
+            type: backend.constructor.name.toLowerCase().replace("backend", "") || "unknown",
+            hasExecuteCapability: hasExecuteCapability(backend),
+            rootDir: "rootDir" in backend ? backend.rootDir : undefined,
+        };
+        return {
+            tools: toolsMetadata.length > 0 ? toolsMetadata : undefined,
+            skills: skillsMetadata.length > 0 ? skillsMetadata : undefined,
+            plugins: pluginsMetadata.length > 0 ? pluginsMetadata : undefined,
+            backend: backendInfo,
+            state,
+            // Model ID extraction is not reliable across all LanguageModel types
+            // Users can access the full model via their custom context if needed
+            model: undefined,
+            maxSteps: options.maxSteps,
+            permissionMode,
+            currentMessages: messages,
+            threadId,
+        };
+    };
+    // Helper to get system prompt (either static or built from context)
+    const getSystemPrompt = (context) => {
+        if (promptMode === "static") {
+            return options.systemPrompt;
+        }
+        // Build prompt using prompt builder
+        return promptBuilder.build(context);
+    };
+    // Runtime tools added/removed dynamically by plugins at runtime
+    const runtimeTools = {};
+    // Helper to get current active tools (core + runtime + MCP + dynamically loaded from registry)
     const getActiveToolSet = (threadId) => {
         // Start with core tools
         const allTools = { ...coreTools };
+        // Add runtime tools (added by plugins at runtime)
+        Object.assign(allTools, runtimeTools);
         // Add MCP tools from plugin registrations
         const mcpTools = mcpManager.getToolSet();
         Object.assign(allTools, mcpTools);
@@ -843,6 +972,8 @@ export function createAgent(options) {
     const getActiveToolSetWithStreaming = (streamingContext, threadId, step) => {
         // Start with core tools
         const allTools = { ...coreTools };
+        // Add runtime tools (added by plugins at runtime)
+        Object.assign(allTools, runtimeTools);
         // Process plugins - invoke function-based tools with streaming context
         for (const plugin of options.plugins ?? []) {
             if (plugin.tools) {
@@ -1155,6 +1286,34 @@ export function createAgent(options) {
             usage: step.usage,
         }));
     }
+    /**
+     * Get the next actionable task prompt from the background task queue.
+     *
+     * Waits for a task to reach terminal state, skips already-consumed and killed
+     * tasks, formats the result as a prompt, removes the task, and returns it.
+     * Returns null when no more tasks need processing.
+     */
+    async function getNextTaskPrompt() {
+        while (taskManager.hasActiveTasks() || taskManager.hasTerminalTasks()) {
+            const completedTask = await taskManager.waitForNextCompletion();
+            // Dedup: skip if already consumed via task_output tool
+            if (!taskManager.getTask(completedTask.id)) {
+                continue;
+            }
+            // Skip killed tasks (user already knows)
+            if (completedTask.status === "killed") {
+                taskManager.removeTask(completedTask.id);
+                continue;
+            }
+            // Format as follow-up prompt
+            const prompt = completedTask.status === "completed"
+                ? formatTaskCompletion(completedTask)
+                : formatTaskFailure(completedTask);
+            taskManager.removeTask(completedTask.id);
+            return prompt;
+        }
+        return null;
+    }
     const agent = {
         id,
         options,
@@ -1184,11 +1343,22 @@ export function createAgent(options) {
                     lastBuiltMessages = messages;
                     const maxSteps = options.maxSteps ?? 10;
                     const startStep = checkpoint?.step ?? 0;
+                    // Shared signal state: flow-control signals (interrupt) thrown by tools
+                    // are caught by the outermost wrapper and stored here. A custom
+                    // stopWhen condition stops generation after the current step completes.
+                    const signalState = {};
                     // Build initial params - use active tools (core + dynamically loaded + task)
-                    // Apply hooks AFTER adding task tool so task tool is also wrapped
-                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped.
+                    // Then wrap with signal catching as the outermost layer so that
+                    // InterruptSignal is intercepted before the AI SDK can catch it and
+                    // convert it to a tool-error result.
+                    const hookedTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const activeTools = wrapToolsWithSignalCatching(hookedTools, signalState);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1198,6 +1368,9 @@ export function createAgent(options) {
                         providerOptions: effectiveGenOptions.providerOptions,
                         headers: effectiveGenOptions.headers,
                     };
+                    // Stop condition: stop when an interrupt signal was caught, OR when
+                    // the step count reaches maxSteps (whichever comes first).
+                    const signalStopCondition = () => signalState.interrupt != null;
                     // Execute generation
                     const response = await generateText({
                         model: retryState.currentModel,
@@ -1208,13 +1381,53 @@ export function createAgent(options) {
                         temperature: initialParams.temperature,
                         stopSequences: initialParams.stopSequences,
                         abortSignal: initialParams.abortSignal,
-                        stopWhen: stepCountIs(maxSteps),
+                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
                         // Passthrough AI SDK options
                         output: effectiveGenOptions.output,
                         // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
                         providerOptions: initialParams.providerOptions,
                         headers: initialParams.headers,
                     });
+                    // Check for intercepted interrupt signal (cooperative path)
+                    if (signalState.interrupt) {
+                        const interrupt = signalState.interrupt.interrupt;
+                        // Save the interrupt to checkpoint
+                        if (effectiveGenOptions.threadId && options.checkpointer) {
+                            const checkpoint = await options.checkpointer.load(effectiveGenOptions.threadId);
+                            if (checkpoint) {
+                                const updatedCheckpoint = updateCheckpoint(checkpoint, {
+                                    pendingInterrupt: interrupt,
+                                });
+                                await options.checkpointer.save(updatedCheckpoint);
+                            }
+                        }
+                        // Emit InterruptRequested hook
+                        const interruptRequestedHooks = effectiveHooks?.InterruptRequested ?? [];
+                        if (interruptRequestedHooks.length > 0) {
+                            const hookInput = {
+                                hook_event_name: "InterruptRequested",
+                                session_id: effectiveGenOptions.threadId ?? "default",
+                                cwd: process.cwd(),
+                                interrupt_id: interrupt.id,
+                                interrupt_type: interrupt.type,
+                                tool_call_id: interrupt.toolCallId,
+                                tool_name: interrupt.toolName,
+                                request: interrupt.request,
+                            };
+                            await invokeHooksWithTimeout(interruptRequestedHooks, hookInput, null, agent);
+                        }
+                        // Return interrupted result with partial results from the response
+                        const interruptedResult = {
+                            status: "interrupted",
+                            interrupt,
+                            partial: {
+                                text: response.text,
+                                steps: mapSteps(response.steps),
+                                usage: response.usage,
+                            },
+                        };
+                        return interruptedResult;
+                    }
                     // Only access output if an output schema was provided
                     // (accessing response.output throws AI_NoOutputGeneratedError otherwise)
                     let output;
@@ -1272,7 +1485,39 @@ export function createAgent(options) {
                             finalResult = updatedResult;
                         }
                     }
-                    return finalResult;
+                    // --- Background task completion loop ---
+                    if (!waitForBackgroundTasks) {
+                        return finalResult;
+                    }
+                    // When checkpointing is active, the checkpoint already contains the
+                    // full conversation history (saved above). Passing explicit messages
+                    // would cause buildMessages() to load checkpoint messages AND append
+                    // the same messages again, causing duplication.
+                    const hasCheckpointing = !!(effectiveGenOptions.threadId && options.checkpointer);
+                    let lastResult = finalResult;
+                    let runningMessages = hasCheckpointing
+                        ? []
+                        : [...messages, { role: "assistant", content: finalResult.text }];
+                    let followUpPrompt = await getNextTaskPrompt();
+                    while (followUpPrompt !== null) {
+                        lastResult = await agent.generate({
+                            ...genOptions,
+                            prompt: followUpPrompt,
+                            messages: hasCheckpointing ? undefined : runningMessages,
+                        });
+                        if (lastResult.status === "interrupted") {
+                            return lastResult;
+                        }
+                        if (!hasCheckpointing) {
+                            runningMessages = [
+                                ...runningMessages,
+                                { role: "user", content: followUpPrompt },
+                                { role: "assistant", content: lastResult.text },
+                            ];
+                        }
+                        followUpPrompt = await getNextTaskPrompt();
+                    }
+                    return lastResult;
                 }
                 catch (error) {
                     // Check if this is an InterruptSignal (new interrupt system)
@@ -1451,11 +1696,18 @@ export function createAgent(options) {
                     const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
                     const maxSteps = options.maxSteps ?? 10;
                     const startStep = checkpoint?.step ?? 0;
+                    // Signal state for cooperative signal catching in streaming mode
+                    const signalState = {};
                     // Build initial params - use active tools (core + dynamically loaded + task)
-                    // Apply hooks AFTER adding task tool so task tool is also wrapped
-                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped.
+                    // Then wrap with signal catching as the outermost layer.
+                    const hookedTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const activeTools = wrapToolsWithSignalCatching(hookedTools, signalState);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1465,6 +1717,9 @@ export function createAgent(options) {
                         providerOptions: effectiveGenOptions.providerOptions,
                         headers: effectiveGenOptions.headers,
                     };
+                    // Stop condition: stop when an interrupt signal was caught, OR when
+                    // the step count reaches maxSteps.
+                    const signalStopCondition = () => signalState.interrupt != null;
                     // Execute stream
                     const response = streamText({
                         model: retryState.currentModel,
@@ -1475,7 +1730,7 @@ export function createAgent(options) {
                         temperature: initialParams.temperature,
                         stopSequences: initialParams.stopSequences,
                         abortSignal: initialParams.abortSignal,
-                        stopWhen: stepCountIs(maxSteps),
+                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
                         // Passthrough AI SDK options
                         output: genOptions.output,
                         // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
@@ -1559,7 +1814,36 @@ export function createAgent(options) {
                         await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
                         // Note: updatedResult is not applied for streaming since the stream has already been sent
                     }
-                    // Success - break out of retry loop
+                    // --- Background task completion loop ---
+                    if (!waitForBackgroundTasks || signalState.interrupt) {
+                        return;
+                    }
+                    const hasCheckpointing = !!(effectiveGenOptions.threadId && options.checkpointer);
+                    let currentMessages = hasCheckpointing
+                        ? []
+                        : [...messages, { role: "assistant", content: text }];
+                    let followUpPrompt = await getNextTaskPrompt();
+                    while (followUpPrompt !== null) {
+                        const followUpGen = agent.stream({
+                            ...genOptions,
+                            prompt: followUpPrompt,
+                            messages: hasCheckpointing ? undefined : currentMessages,
+                        });
+                        let followUpText = "";
+                        for await (const part of followUpGen) {
+                            yield part;
+                            if (part.type === "text-delta")
+                                followUpText += part.text;
+                        }
+                        if (!hasCheckpointing) {
+                            currentMessages = [
+                                ...currentMessages,
+                                { role: "user", content: followUpPrompt },
+                                { role: "assistant", content: followUpText },
+                            ];
+                        }
+                        followUpPrompt = await getNextTaskPrompt();
+                    }
                     return;
                 }
                 catch (error) {
@@ -1609,11 +1893,18 @@ export function createAgent(options) {
                     const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
                     const maxSteps = options.maxSteps ?? 10;
                     const startStep = checkpoint?.step ?? 0;
+                    // Signal state for cooperative signal catching in streaming mode
+                    const signalState = {};
                     // Build initial params - use active tools (core + dynamically loaded + task)
-                    // Apply hooks AFTER adding task tool so task tool is also wrapped
-                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped.
+                    // Then wrap with signal catching as the outermost layer.
+                    const hookedTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const activeTools = wrapToolsWithSignalCatching(hookedTools, signalState);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1623,11 +1914,18 @@ export function createAgent(options) {
                         providerOptions: effectiveGenOptions.providerOptions,
                         headers: effectiveGenOptions.headers,
                     };
+                    // Capture currentModel for use in the callback closure
+                    const modelToUse = retryState.currentModel;
+                    // Stop condition: stop when an interrupt signal was caught, OR when
+                    // the step count reaches maxSteps.
+                    const signalStopCondition = () => signalState.interrupt != null;
                     // Track step count for incremental checkpointing
                     let currentStepCount = 0;
-                    // Execute stream
+                    // Execute streamText OUTSIDE createUIMessageStream so errors propagate
+                    // to the retry loop (if streamText throws synchronously on creation,
+                    // e.g. rate limit, the catch block handles retry/fallback).
                     const result = streamText({
-                        model: retryState.currentModel,
+                        model: modelToUse,
                         system: initialParams.system,
                         messages: initialParams.messages,
                         tools: initialParams.tools,
@@ -1635,7 +1933,7 @@ export function createAgent(options) {
                         temperature: initialParams.temperature,
                         stopSequences: initialParams.stopSequences,
                         abortSignal: initialParams.abortSignal,
-                        stopWhen: stepCountIs(maxSteps),
+                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
                         // Passthrough AI SDK options
                         output: effectiveGenOptions.output,
                         // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
@@ -1698,10 +1996,93 @@ export function createAgent(options) {
                             }
                         },
                     });
-                    // Return AI SDK compatible response for use with useChat
-                    // Note: Not passing originalMessages since ModelMessage[] != UIMessage[]
-                    // The AI SDK will reconstruct messages from the stream
-                    return result.toUIMessageStreamResponse();
+                    // Use createUIMessageStream to control stream lifecycle for background task follow-ups
+                    const stream = createUIMessageStream({
+                        execute: async ({ writer }) => {
+                            // Merge initial generation into the stream
+                            writer.merge(result.toUIMessageStream());
+                            // Wait for initial generation to complete to get final text
+                            const text = await result.text;
+                            // --- Background task completion loop ---
+                            if (waitForBackgroundTasks) {
+                                // Track accumulated steps for checkpoint saves
+                                const initialSteps = await result.steps;
+                                let accumulatedStepCount = initialSteps.length;
+                                let currentMessages = [
+                                    ...messages,
+                                    { role: "assistant", content: text },
+                                ];
+                                let followUpPrompt = await getNextTaskPrompt();
+                                while (followUpPrompt !== null) {
+                                    // Stream follow-up generation into the same writer
+                                    const followUpResult = streamText({
+                                        model: modelToUse,
+                                        system: initialParams.system,
+                                        messages: [
+                                            ...currentMessages,
+                                            { role: "user", content: followUpPrompt },
+                                        ],
+                                        tools: initialParams.tools,
+                                        maxOutputTokens: initialParams.maxTokens,
+                                        temperature: initialParams.temperature,
+                                        stopSequences: initialParams.stopSequences,
+                                        abortSignal: initialParams.abortSignal,
+                                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
+                                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                                        providerOptions: initialParams.providerOptions,
+                                        headers: initialParams.headers,
+                                    });
+                                    writer.merge(followUpResult.toUIMessageStream());
+                                    const followUpText = await followUpResult.text;
+                                    currentMessages = [
+                                        ...currentMessages,
+                                        { role: "user", content: followUpPrompt },
+                                        { role: "assistant", content: followUpText },
+                                    ];
+                                    // --- Post-completion bookkeeping for follow-ups ---
+                                    const followUpSteps = await followUpResult.steps;
+                                    accumulatedStepCount += followUpSteps.length;
+                                    // Checkpoint save
+                                    if (effectiveGenOptions.threadId && options.checkpointer) {
+                                        await saveCheckpoint(effectiveGenOptions.threadId, currentMessages, startStep + accumulatedStepCount);
+                                    }
+                                    // Context manager update
+                                    const followUpUsage = await followUpResult.usage;
+                                    if (options.contextManager?.updateUsage && followUpUsage) {
+                                        options.contextManager.updateUsage({
+                                            inputTokens: followUpUsage.inputTokens,
+                                            outputTokens: followUpUsage.outputTokens,
+                                            totalTokens: followUpUsage.totalTokens,
+                                        });
+                                    }
+                                    // PostGenerate hooks
+                                    const followUpPostGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                                    if (followUpPostGenerateHooks.length > 0) {
+                                        const followUpFinishReason = await followUpResult.finishReason;
+                                        const followUpHookResult = {
+                                            status: "complete",
+                                            text: followUpText,
+                                            usage: followUpUsage,
+                                            finishReason: followUpFinishReason,
+                                            output: undefined,
+                                            steps: mapSteps(followUpSteps),
+                                        };
+                                        const followUpPostGenerateInput = {
+                                            hook_event_name: "PostGenerate",
+                                            session_id: effectiveGenOptions.threadId ?? "default",
+                                            cwd: process.cwd(),
+                                            options: effectiveGenOptions,
+                                            result: followUpHookResult,
+                                        };
+                                        await invokeHooksWithTimeout(followUpPostGenerateHooks, followUpPostGenerateInput, null, agent);
+                                    }
+                                    followUpPrompt = await getNextTaskPrompt();
+                                }
+                            }
+                        },
+                    });
+                    // Convert the stream to a Response
+                    return createUIMessageStreamResponse({ stream });
                 }
                 catch (error) {
                     // Normalize error to AgentError
@@ -1740,11 +2121,18 @@ export function createAgent(options) {
                     const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
                     const maxSteps = options.maxSteps ?? 10;
                     const startStep = checkpoint?.step ?? 0;
+                    // Signal state for cooperative signal catching in streaming mode
+                    const signalState = {};
                     // Build initial params - use active tools (core + dynamically loaded + task)
-                    // Apply hooks AFTER adding task tool so task tool is also wrapped
-                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped.
+                    // Then wrap with signal catching as the outermost layer.
+                    const hookedTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const activeTools = wrapToolsWithSignalCatching(hookedTools, signalState);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1756,6 +2144,9 @@ export function createAgent(options) {
                     };
                     // Track step count for incremental checkpointing
                     let currentStepCount = 0;
+                    // Stop condition: stop when an interrupt signal was caught, OR when
+                    // the step count reaches maxSteps.
+                    const signalStopCondition = () => signalState.interrupt != null;
                     // Execute stream
                     const result = streamText({
                         model: retryState.currentModel,
@@ -1766,7 +2157,7 @@ export function createAgent(options) {
                         temperature: initialParams.temperature,
                         stopSequences: initialParams.stopSequences,
                         abortSignal: initialParams.abortSignal,
-                        stopWhen: stepCountIs(maxSteps),
+                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
                         // Passthrough AI SDK options
                         output: effectiveGenOptions.output,
                         // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
@@ -1889,12 +2280,19 @@ export function createAgent(options) {
                             }
                             // Create streaming context for tools
                             const streamingContext = { writer };
+                            // Signal state for cooperative signal catching in streaming mode
+                            const signalState = {};
                             // Build tools with streaming context and task tool
-                            // Apply hooks AFTER adding task tool so task tool is also wrapped
-                            const streamingTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSetWithStreaming(streamingContext, effectiveGenOptions.threadId), streamingContext), effectiveGenOptions.threadId);
+                            // Apply hooks AFTER adding task tool so task tool is also wrapped.
+                            // Then wrap with signal catching as the outermost layer.
+                            const hookedStreamingTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSetWithStreaming(streamingContext, effectiveGenOptions.threadId), streamingContext), effectiveGenOptions.threadId);
+                            const streamingTools = wrapToolsWithSignalCatching(hookedStreamingTools, signalState);
+                            // Build prompt context and generate system prompt
+                            const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                            const systemPrompt = getSystemPrompt(promptContext);
                             // Build initial params with streaming-aware tools
                             const initialParams = {
-                                system: options.systemPrompt,
+                                system: systemPrompt,
                                 messages,
                                 tools: streamingTools,
                                 maxTokens: effectiveGenOptions.maxTokens,
@@ -1906,6 +2304,9 @@ export function createAgent(options) {
                             };
                             // Track step count for incremental checkpointing
                             let currentStepCount = 0;
+                            // Stop condition: stop when a flow-control signal was caught, OR when
+                            // the step count reaches maxSteps.
+                            const signalStopCondition = () => signalState.interrupt != null;
                             // Execute stream
                             const result = streamText({
                                 model: modelToUse,
@@ -1916,7 +2317,7 @@ export function createAgent(options) {
                                 temperature: initialParams.temperature,
                                 stopSequences: initialParams.stopSequences,
                                 abortSignal: initialParams.abortSignal,
-                                stopWhen: stepCountIs(maxSteps),
+                                stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
                                 // Passthrough AI SDK options
                                 output: effectiveGenOptions.output,
                                 // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
@@ -1984,6 +2385,84 @@ export function createAgent(options) {
                             });
                             // Merge the streamText output into the UI message stream
                             writer.merge(result.toUIMessageStream());
+                            // Wait for initial generation to complete to get final text
+                            const text = await result.text;
+                            // --- Background task completion loop ---
+                            if (waitForBackgroundTasks) {
+                                // Track accumulated steps for checkpoint saves
+                                const initialSteps = await result.steps;
+                                let accumulatedStepCount = initialSteps.length;
+                                let currentMessages = [
+                                    ...messages,
+                                    { role: "assistant", content: text },
+                                ];
+                                let followUpPrompt = await getNextTaskPrompt();
+                                while (followUpPrompt !== null) {
+                                    // Stream follow-up generation into the same writer
+                                    const followUpResult = streamText({
+                                        model: modelToUse,
+                                        system: initialParams.system,
+                                        messages: [
+                                            ...currentMessages,
+                                            { role: "user", content: followUpPrompt },
+                                        ],
+                                        tools: initialParams.tools,
+                                        maxOutputTokens: initialParams.maxTokens,
+                                        temperature: initialParams.temperature,
+                                        stopSequences: initialParams.stopSequences,
+                                        abortSignal: initialParams.abortSignal,
+                                        stopWhen: [signalStopCondition, stepCountIs(maxSteps)],
+                                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                                        providerOptions: initialParams.providerOptions,
+                                        headers: initialParams.headers,
+                                    });
+                                    writer.merge(followUpResult.toUIMessageStream());
+                                    const followUpText = await followUpResult.text;
+                                    currentMessages = [
+                                        ...currentMessages,
+                                        { role: "user", content: followUpPrompt },
+                                        { role: "assistant", content: followUpText },
+                                    ];
+                                    // --- Post-completion bookkeeping for follow-ups ---
+                                    const followUpSteps = await followUpResult.steps;
+                                    accumulatedStepCount += followUpSteps.length;
+                                    // Checkpoint save
+                                    if (effectiveGenOptions.threadId && options.checkpointer) {
+                                        await saveCheckpoint(effectiveGenOptions.threadId, currentMessages, startStep + accumulatedStepCount);
+                                    }
+                                    // Context manager update
+                                    const followUpUsage = await followUpResult.usage;
+                                    if (options.contextManager?.updateUsage && followUpUsage) {
+                                        options.contextManager.updateUsage({
+                                            inputTokens: followUpUsage.inputTokens,
+                                            outputTokens: followUpUsage.outputTokens,
+                                            totalTokens: followUpUsage.totalTokens,
+                                        });
+                                    }
+                                    // PostGenerate hooks
+                                    const followUpPostGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                                    if (followUpPostGenerateHooks.length > 0) {
+                                        const followUpFinishReason = await followUpResult.finishReason;
+                                        const followUpHookResult = {
+                                            status: "complete",
+                                            text: followUpText,
+                                            usage: followUpUsage,
+                                            finishReason: followUpFinishReason,
+                                            output: undefined,
+                                            steps: mapSteps(followUpSteps),
+                                        };
+                                        const followUpPostGenerateInput = {
+                                            hook_event_name: "PostGenerate",
+                                            session_id: effectiveGenOptions.threadId ?? "default",
+                                            cwd: process.cwd(),
+                                            options: effectiveGenOptions,
+                                            result: followUpHookResult,
+                                        };
+                                        await invokeHooksWithTimeout(followUpPostGenerateHooks, followUpPostGenerateInput, null, agent);
+                                    }
+                                    followUpPrompt = await getNextTaskPrompt();
+                                }
+                            }
                         },
                     });
                     // Convert the stream to a Response
@@ -2013,6 +2492,14 @@ export function createAgent(options) {
         getActiveTools() {
             return getActiveToolSet();
         },
+        addRuntimeTools(tools) {
+            Object.assign(runtimeTools, tools);
+        },
+        removeRuntimeTools(toolNames) {
+            for (const name of toolNames) {
+                delete runtimeTools[name];
+            }
+        },
         loadTools(toolNames) {
             if (!toolRegistry) {
                 // No registry in eager mode - all tools already loaded