@openharness/core 0.5.2 → 0.6.0

package/dist/agent.js

@@ -1,10 +1,14 @@
 import { tool, streamText, stepCountIs, } from "ai";
 import { z } from "zod";
+import { Session } from "./session.js";
 import { loadInstructions } from "./instructions.js";
 import { connectMCPServers, closeMCPClients, } from "./mcp.js";
-import { discoverSkills } from "./skills.js";
+import { discoverSkills, } from "./skills.js";
+import { InMemorySubagentSessionMetadataStore, isSubagentCatalog, } from "./subagents.js";
 import { createSkillTool } from "./tools/skill.js";
 import { AgentRegistry, normalizeBackgroundConfig, } from "./agent-registry.js";
+const SUBAGENT_SESSION_RUNTIME = new WeakMap();
+const TASK_SESSION_MODES = ["stateless", "new", "resume", "fork"];
 // ── Agent ────────────────────────────────────────────────────────────
 export class Agent {
     name;
@@ -18,11 +22,13 @@ export class Agent {
     maxSubagentDepth;
     approve;
     onSubagentEvent;
-    /** Original subagent templates (stored so nested children can inherit them). */
+    /** Original subagent templates or catalog (stored for nested children). */
     subagents;
+    /** Optional resumable subagent session config. */
+    subagentSessions;
     /** Background config (stored so nested children can inherit it). */
     subagentBackground;
-    /** Registry for background subagents. Only present when `subagentBackground` is configured. */
+    /** Registry for background subagents. Only present when configured. */
     agentRegistry;
     /** Static tools provided at construction time. */
     tools;
@@ -31,8 +37,8 @@ export class Agent {
     mcpConnection = null;
     /** Skills config — discovered lazily on first run. */
     skillsConfig;
-    cachedSkills = null; // null = not loaded yet
-    cachedInstructions = null; // null = not loaded yet
+    cachedSkills = null;
+    cachedInstructions = null;
     constructor(options) {
         this.name = options.name;
         this.description = options.description;
@@ -46,32 +52,19 @@ export class Agent {
         this.approve = options.approve;
         this.onSubagentEvent = options.onSubagentEvent;
         this.subagents = options.subagents;
+        this.subagentSessions = options.subagentSessions;
         this.subagentBackground = options.subagentBackground;
         this.mcpServerConfigs = options.mcpServers;
         this.skillsConfig = options.skills;
-        // Merge the task tool into the toolset when subagents are provided and depth > 0
-        if (options.subagents?.length && this.maxSubagentDepth > 0) {
-            const bgConfig = options.subagentBackground
-                ? normalizeBackgroundConfig(options.subagentBackground)
-                : undefined;
-            const registry = bgConfig ? new AgentRegistry(bgConfig) : undefined;
-            this.agentRegistry = registry;
-            this.tools = {
-                ...(options.tools ?? {}),
-                task: createTaskTool(options.subagents, this.maxSubagentDepth, this.onSubagentEvent, registry),
-                ...(registry && bgConfig.tools.status
-                    ? { agent_status: createStatusTool(registry) }
-                    : {}),
-                ...(registry && bgConfig.tools.cancel
-                    ? { agent_cancel: createCancelTool(registry) }
-                    : {}),
-                ...(registry && bgConfig.tools.await
-                    ? { agent_await: createAwaitTool(registry, bgConfig.tools.await) }
-                    : {}),
-            };
+        this.tools = options.tools;
+        if (options.subagentSessions) {
+            getSubagentSessionRuntime(options.subagentSessions);
         }
-        else {
-            this.tools = options.tools;
+        if (options.subagents && this.maxSubagentDepth > 0 && options.subagentBackground) {
+            const bgConfig = normalizeBackgroundConfig(options.subagentBackground);
+            if (bgConfig) {
+                this.agentRegistry = new AgentRegistry(bgConfig);
+            }
         }
     }
     /**
@@ -87,7 +80,6 @@ export class Agent {
         }
     }
     async *run(history, input, options) {
-        // Build messages: history + new input (Agent does NOT mutate history)
         const messages = [...history];
         if (typeof input === "string") {
             messages.push({ role: "user", content: input });
@@ -95,25 +87,25 @@ export class Agent {
         else {
             messages.push(...input);
         }
-        // Load AGENTS.md once per agent lifetime
         if (this.instructions && this.cachedInstructions === null) {
             this.cachedInstructions = await loadInstructions();
         }
-        // Connect MCP servers once per agent lifetime
         if (this.mcpServerConfigs && !this.mcpConnection) {
             this.mcpConnection = await connectMCPServers(this.mcpServerConfigs);
         }
-        // Discover skills once per agent lifetime
         if (this.skillsConfig && this.cachedSkills === null) {
             this.cachedSkills = await discoverSkills(this.skillsConfig);
         }
         const systemParts = [this.systemPrompt, this.cachedInstructions].filter(Boolean);
         const system = systemParts.length > 0 ? systemParts.join("\n\n") : undefined;
-        // Merge static tools with MCP tools and skill tool
+        const subagentTools = await createSubagentTools(this.subagents, this.maxSubagentDepth, this.onSubagentEvent, this.agentRegistry, this.subagentBackground, this.subagentSessions);
         const allTools = {
-            ...(this.cachedSkills?.length ? { skill: createSkillTool(this.cachedSkills) } : {}),
+            ...(this.cachedSkills?.length
+                ? { skill: createSkillTool(this.cachedSkills) }
+                : {}),
             ...(this.mcpConnection?.tools ?? {}),
             ...(this.tools ?? {}),
+            ...(subagentTools ?? {}),
         };
         const tools = this.approve && Object.keys(allTools).length > 0
             ? wrapToolsWithApproval(allTools, this.approve)
@@ -201,7 +193,9 @@ export class Agent {
                     case "error":
                         yield {
                             type: "error",
-                            error: part.error instanceof Error ? part.error : new Error(String(part.error)),
+                            error: part.error instanceof Error
+                                ? part.error
+                                : new Error(String(part.error)),
                         };
                         break;
                     case "finish": {
@@ -258,12 +252,40 @@ export class Agent {
                 type: "done",
                 result: "error",
                 messages,
-                totalUsage: { inputTokens: undefined, outputTokens: undefined, totalTokens: undefined },
+                totalUsage: {
+                    inputTokens: undefined,
+                    outputTokens: undefined,
+                    totalTokens: undefined,
+                },
             };
         }
     }
 }
 // ── Subagent tools ──────────────────────────────────────────────────
+async function createSubagentTools(subagents, remainingDepth, onSubagentEvent, registry, backgroundConfig, sessionConfig) {
+    if (!subagents || remainingDepth <= 0)
+        return undefined;
+    if (Array.isArray(subagents) && subagents.length === 0)
+        return undefined;
+    const bgConfig = registry && backgroundConfig
+        ? normalizeBackgroundConfig(backgroundConfig)
+        : undefined;
+    const task = await createTaskTool(subagents, remainingDepth, onSubagentEvent, registry, sessionConfig);
+    return {
+        task,
+        ...(registry && bgConfig?.tools.status
+            ? { agent_status: createStatusTool(registry) }
+            : {}),
+        ...(registry && bgConfig?.tools.cancel
+            ? { agent_cancel: createCancelTool(registry) }
+            : {}),
+        ...(registry && bgConfig?.tools.await
+            ? {
+                agent_await: createAwaitTool(registry, bgConfig.tools.await),
+            }
+            : {}),
+    };
+}
 function createChildFromTemplate(template, remainingDepth, onSubagentEvent) {
     const nextDepth = remainingDepth - 1;
     const childOnSubagentEvent = onSubagentEvent
@@ -279,11 +301,10 @@ function createChildFromTemplate(template, remainingDepth, onSubagentEvent) {
         temperature: template.temperature,
         maxTokens: template.maxTokens,
         instructions: template.instructions,
-        // No approve — subagents run autonomously
-        // Pass subagents + background config through when there is remaining depth
-        ...(nextDepth > 0 && template.subagents?.length
+        ...(nextDepth > 0 && template.subagents
             ? {
                 subagents: template.subagents,
+                subagentSessions: template.subagentSessions,
                 maxSubagentDepth: nextDepth,
                 onSubagentEvent: childOnSubagentEvent,
                 subagentBackground: template.subagentBackground,
@@ -291,86 +312,128 @@ function createChildFromTemplate(template, remainingDepth, onSubagentEvent) {
             : {}),
     });
 }
-function createTaskTool(subagents, remainingDepth, onSubagentEvent, registry) {
-    const names = subagents.map((a) => a.name);
-    const byName = new Map(subagents.map((a) => [a.name, a]));
-    const listing = subagents.map((a) => `- ${a.name}: ${a.description ?? a.name}`).join("\n");
+async function createTaskTool(subagents, remainingDepth, onSubagentEvent, registry, sessionConfig) {
+    const descriptors = await listSubagentDescriptors(subagents);
+    const names = descriptors.map((subagent) => subagent.name);
+    const listing = descriptors
+        .map((subagent) => `- ${subagent.name}: ${subagent.description ?? subagent.name}`)
+        .join("\n");
     const descriptionLines = [
         "Spawn a subagent to handle a task autonomously.",
         "The subagent runs with its own tools, completes the work, and returns the result.",
         "Launch multiple agents concurrently when possible by calling this tool multiple times in one response.",
     ];
+    if (sessionConfig) {
+        descriptionLines.push("", "Set session.mode=new to create a resumable subagent session.", "Set session.mode=resume with session.id to continue an earlier subagent session.", "Set session.mode=fork with session.id to clone an earlier session into a new one.", 'When session is omitted, the default mode is "' +
+            (sessionConfig.defaultMode ?? "stateless") +
+            '".');
+    }
     if (registry) {
-        descriptionLines.push("", "Set background=true to spawn the agent in the background and return immediately with an agent ID.", "Use agent_status, agent_await, or agent_cancel to manage background agents.");
+        descriptionLines.push("", "Set background=true to spawn the agent in the background and return immediately with a run ID.", "Use agent_status, agent_await, or agent_cancel to manage background runs.");
+    }
+    if (listing) {
+        descriptionLines.push("", "Available agents:", listing);
+    }
+    else if (isSubagentCatalog(subagents)) {
+        descriptionLines.push("", "Available agents are resolved dynamically at runtime.");
     }
-    descriptionLines.push("", "Available agents:", listing);
     const baseSchema = z.object({
-        agent: z.enum(names).describe("Which agent to use"),
+        agent: createAgentSelectionSchema(names).describe("Which agent to use"),
         prompt: z.string().describe("Detailed task description for the subagent"),
     });
-    const bgSchema = baseSchema.extend({
-        background: z
-            .boolean()
-            .optional()
-            .describe("If true, spawn in background and return immediately with an agent ID"),
-    });
-    const inputSchema = registry ? bgSchema : baseSchema;
+    const withSession = sessionConfig
+        ? baseSchema.extend({
+            session: createTaskSessionSchema()
+                .optional()
+                .describe("Optional resumable session instructions"),
+        })
+        : baseSchema;
+    const inputSchema = registry
+        ? withSession.extend({
+            background: z
+                .boolean()
+                .optional()
+                .describe("If true, spawn in background and return immediately with a run ID"),
+        })
+        : withSession;
     return tool({
         description: descriptionLines.join("\n"),
         inputSchema,
         execute: async (rawInput, { abortSignal }) => {
-            const { agent: agentName, prompt, background } = rawInput;
-            const template = byName.get(agentName);
-            const child = createChildFromTemplate(template, remainingDepth, onSubagentEvent);
-            // Background mode: spawn and return immediately
+            const { agent: agentName, prompt } = rawInput;
+            const background = "background" in rawInput ? rawInput.background : undefined;
+            const session = "session" in rawInput ? rawInput.session : undefined;
+            const template = await resolveSubagent(subagents, agentName);
+            if (!template) {
+                const suffix = names.length > 0 ? ` Available agents: ${names.join(", ")}.` : "";
+                throw new Error(`Unknown subagent "${agentName}".${suffix}`);
+            }
+            const prepared = sessionConfig
+                ? await prepareSubagentChild({
+                    agentName,
+                    template,
+                    remainingDepth,
+                    onSubagentEvent,
+                    sessionConfig,
+                    session,
+                })
+                : {
+                    child: createChildFromTemplate(template, remainingDepth, onSubagentEvent),
+                    sessionId: undefined,
+                };
+            const { child, sessionId } = prepared;
             if (background && registry) {
                 const id = registry.spawn(agentName, child, prompt, {
                     signal: abortSignal,
                     onEvent: onSubagentEvent,
+                    sessionId,
                 });
-                return `<background_spawn agent_id="${id}">\nAgent "${agentName}" spawned in background with id "${id}".\nUse agent_status, agent_await, or agent_cancel to manage it.\n</background_spawn>`;
+                return formatBackgroundSpawn(agentName, id, sessionId);
             }
-            // Foreground mode: run to completion
             let lastText = "";
-            for await (const event of child.run([], prompt, { signal: abortSignal })) {
-                onSubagentEvent?.([agentName], event);
-                if (event.type === "text.done") {
-                    lastText = event.text;
+            try {
+                for await (const event of child.run([], prompt, { signal: abortSignal })) {
+                    onSubagentEvent?.([agentName], event);
+                    if (event.type === "text.done") {
+                        lastText = event.text;
+                    }
                 }
             }
-            await child.close();
-            return `<task_result>\n${lastText || "(no output)"}\n</task_result>`;
+            finally {
+                await child.close();
+            }
+            return formatTaskResult(lastText || "(no output)", sessionId);
         },
     });
 }
 function createStatusTool(registry) {
     return tool({
-        description: "Check the status of a background agent without blocking.",
+        description: "Check the status of a background run without blocking.",
         inputSchema: z.object({
-            id: z.string().describe("The agent ID returned by a background task spawn"),
+            id: z.string().describe("The run ID returned by a background task spawn"),
         }),
         execute: async ({ id }) => {
             const status = registry.getStatus(id);
             if (!status)
                 return `Agent "${id}" not found.`;
             if (status.status === "done") {
-                return `<agent_status id="${id}" status="done">\n${status.result}\n</agent_status>`;
+                return formatAgentStatus(id, status.status, status.result, undefined, status.sessionId);
             }
             if (status.status === "failed") {
-                return `<agent_status id="${id}" status="failed" error="${status.error ?? "unknown"}" />`;
+                return formatAgentStatus(id, status.status, undefined, status.error ?? "unknown", status.sessionId);
             }
             if (status.status === "cancelled") {
-                return `<agent_status id="${id}" status="cancelled" />`;
+                return formatAgentStatus(id, status.status, undefined, undefined, status.sessionId);
             }
-            return `<agent_status id="${id}" status="running" />`;
+            return formatAgentStatus(id, status.status, undefined, undefined, status.sessionId);
         },
     });
 }
 function createCancelTool(registry) {
     return tool({
-        description: "Cancel a running background agent.",
+        description: "Cancel a running background run.",
         inputSchema: z.object({
-            id: z.string().describe("The agent ID to cancel"),
+            id: z.string().describe("The run ID to cancel"),
         }),
         execute: async ({ id }) => {
             const cancelled = registry.cancel(id);
@@ -389,42 +452,46 @@ function createAwaitTool(registry, modes) {
     };
     return tool({
         description: [
-            "Wait for one or more background agents to complete.",
+            "Wait for one or more background runs to complete.",
             "",
             "Modes:",
-            ...modes.map((m) => `- ${modeDescriptions[m]}`),
+            ...modes.map((mode) => `- ${modeDescriptions[mode]}`),
         ].join("\n"),
         inputSchema: z.object({
-            ids: z.array(z.string()).min(1).describe("Agent IDs to wait for"),
-            mode: z.enum(modes).describe("How to wait for agents"),
+            ids: z.array(z.string()).min(1).describe("Run IDs to wait for"),
+            mode: z.enum(modes).describe("How to wait for runs"),
         }),
         execute: async ({ ids, mode }) => {
             switch (mode) {
                 case "all": {
                     try {
                         const results = await registry.awaitAll(ids);
-                        const entries = [...results.entries()].map(([id, result]) => `<agent id="${id}">\n${result}\n</agent>`);
+                        const entries = [...results.entries()].map(([id, result]) => {
+                            const sessionId = registry.getStatus(id)?.sessionId;
+                            return `<agent id="${id}"${formatOptionalAttr("session_id", sessionId)}>\n${result}\n</agent>`;
+                        });
                         return `<await_result mode="all">\n${entries.join("\n")}\n</await_result>`;
                     }
-                    catch (e) {
-                        const msg = e instanceof Error ? e.message : String(e);
-                        return `<await_result mode="all" error="${msg}" />`;
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return `<await_result mode="all" error="${message}" />`;
                     }
                 }
                 case "allSettled": {
                     const results = await registry.awaitAllSettled(ids);
-                    const entries = [...results.entries()].map(([id, r]) => {
-                        if (r.status === "done") {
-                            return `<agent id="${id}" status="done">\n${r.result}\n</agent>`;
+                    const entries = [...results.entries()].map(([id, result]) => {
+                        const sessionAttr = formatOptionalAttr("session_id", result.sessionId);
+                        if (result.status === "done") {
+                            return `<agent id="${id}" status="done"${sessionAttr}>\n${result.result}\n</agent>`;
                         }
-                        return `<agent id="${id}" status="${r.status}" error="${r.error ?? "unknown"}" />`;
+                        return `<agent id="${id}" status="${result.status}"${sessionAttr} error="${result.error ?? "unknown"}" />`;
                     });
                     return `<await_result mode="allSettled">\n${entries.join("\n")}\n</await_result>`;
                 }
                 case "any": {
                     try {
-                        const { id, result } = await registry.awaitAny(ids);
-                        return `<await_result mode="any" winner="${id}">\n${result}\n</await_result>`;
+                        const { id, sessionId, result } = await registry.awaitAny(ids);
+                        return `<await_result mode="any" winner="${id}"${formatOptionalAttr("session_id", sessionId)}>\n${result}\n</await_result>`;
                     }
                     catch {
                         return `<await_result mode="any" error="All agents failed." />`;
@@ -432,15 +499,227 @@ function createAwaitTool(registry, modes) {
                 }
                 case "race": {
                     const settled = await registry.awaitRace(ids);
+                    const sessionAttr = formatOptionalAttr("session_id", settled.sessionId);
                     if (settled.error) {
-                        return `<await_result mode="race" settled="${settled.id}" status="failed" error="${settled.error}" />`;
+                        return `<await_result mode="race" settled="${settled.id}"${sessionAttr} status="failed" error="${settled.error}" />`;
                     }
-                    return `<await_result mode="race" settled="${settled.id}">\n${settled.result}\n</await_result>`;
+                    return `<await_result mode="race" settled="${settled.id}"${sessionAttr}>\n${settled.result}\n</await_result>`;
                 }
             }
         },
     });
 }
+async function prepareSubagentChild(params) {
+    const { agentName, template, remainingDepth, onSubagentEvent, sessionConfig, session, } = params;
+    const child = createChildFromTemplate(template, remainingDepth, onSubagentEvent);
+    const mode = session?.mode ?? sessionConfig.defaultMode ?? "stateless";
+    if (mode === "stateless") {
+        return { child };
+    }
+    const runtime = getSubagentSessionRuntime(sessionConfig);
+    const now = new Date().toISOString();
+    let sessionId;
+    let initialMessages = [];
+    let metadata;
+    try {
+        switch (mode) {
+            case "new":
+                sessionId = crypto.randomUUID();
+                metadata = {
+                    sessionId,
+                    agentName,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                await runtime.metadataStore.save(metadata);
+                break;
+            case "resume": {
+                sessionId = requireSessionId(session, mode);
+                metadata = await loadRequiredSessionMetadata(runtime.metadataStore, sessionId, agentName);
+                const storedMessages = await sessionConfig.messages.load(sessionId);
+                if (!storedMessages) {
+                    throw new Error(`Subagent session "${sessionId}" could not be loaded.`);
+                }
+                initialMessages = structuredClone(storedMessages);
+                metadata = { ...metadata, updatedAt: now };
+                break;
+            }
+            case "fork": {
+                const sourceId = requireSessionId(session, mode);
+                await loadRequiredSessionMetadata(runtime.metadataStore, sourceId, agentName);
+                const sourceMessages = await sessionConfig.messages.load(sourceId);
+                if (!sourceMessages) {
+                    throw new Error(`Subagent session "${sourceId}" could not be loaded.`);
+                }
+                sessionId = crypto.randomUUID();
+                initialMessages = structuredClone(sourceMessages);
+                metadata = {
+                    sessionId,
+                    agentName,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                await runtime.metadataStore.save(metadata);
+                await sessionConfig.messages.save(sessionId, initialMessages);
+                break;
+            }
+            default:
+                return { child };
+        }
+    }
+    catch (error) {
+        await child.close();
+        throw error;
+    }
+    if (runtime.activeSessionIds.has(sessionId)) {
+        await child.close();
+        throw new Error(`Subagent session "${sessionId}" is already running.`);
+    }
+    runtime.activeSessionIds.add(sessionId);
+    let released = false;
+    const close = async () => {
+        if (released)
+            return;
+        released = true;
+        runtime.activeSessionIds.delete(sessionId);
+        await child.close();
+    };
+    const statefulChild = {
+        run: async function* (_history, input, options) {
+            const session = new Session({
+                agent: child,
+                sessionId,
+                sessionStore: sessionConfig.messages,
+                ...(sessionConfig.sessionOptions ?? {}),
+            });
+            session.messages = structuredClone(initialMessages);
+            try {
+                for await (const event of session.send(input, options)) {
+                    if (event.type === "turn.start" ||
+                        event.type === "turn.done" ||
+                        event.type === "compaction.start" ||
+                        event.type === "compaction.pruned" ||
+                        event.type === "compaction.summary" ||
+                        event.type === "compaction.done" ||
+                        event.type === "retry") {
+                        continue;
+                    }
+                    yield event;
+                }
+                await runtime.metadataStore.save({
+                    sessionId,
+                    agentName,
+                    createdAt: metadata.createdAt,
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+            catch (error) {
+                await runtime.metadataStore.save({
+                    sessionId,
+                    agentName,
+                    createdAt: metadata.createdAt,
+                    updatedAt: new Date().toISOString(),
+                });
+                throw error;
+            }
+        },
+        close,
+    };
+    return { child: statefulChild, sessionId };
+}
+function getSubagentSessionRuntime(config) {
+    let runtime = SUBAGENT_SESSION_RUNTIME.get(config);
+    if (!runtime) {
+        runtime = {
+            activeSessionIds: new Set(),
+            metadataStore: config.metadata ?? new InMemorySubagentSessionMetadataStore(),
+        };
+        SUBAGENT_SESSION_RUNTIME.set(config, runtime);
+    }
+    return runtime;
+}
+function createAgentSelectionSchema(names) {
+    if (names.length > 0) {
+        return z.enum(names);
+    }
+    return z.string().min(1);
+}
+function createTaskSessionSchema() {
+    return z
+        .object({
+        mode: z.enum(TASK_SESSION_MODES).describe("How to handle subagent memory"),
+        id: z.string().optional().describe("Existing session ID to resume or fork"),
+    })
+        .superRefine((value, ctx) => {
+        if ((value.mode === "resume" || value.mode === "fork") && !value.id) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `session.id is required when session.mode="${value.mode}"`,
+                path: ["id"],
+            });
+        }
+        if ((value.mode === "stateless" || value.mode === "new") && value.id) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `session.id is not used when session.mode="${value.mode}"`,
+                path: ["id"],
+            });
+        }
+    });
+}
+async function listSubagentDescriptors(subagents) {
+    if (Array.isArray(subagents)) {
+        return subagents.map((agent) => ({
+            name: agent.name,
+            description: agent.description,
+        }));
+    }
+    return subagents.list();
+}
+async function resolveSubagent(subagents, name) {
+    if (Array.isArray(subagents)) {
+        return subagents.find((agent) => agent.name === name);
+    }
+    return subagents.resolve(name);
+}
+async function loadRequiredSessionMetadata(store, sessionId, agentName) {
+    const metadata = await store.load(sessionId);
+    if (!metadata) {
+        throw new Error(`Unknown subagent session "${sessionId}".`);
+    }
+    if (metadata.agentName !== agentName) {
+        throw new Error(`Subagent session "${sessionId}" belongs to "${metadata.agentName}", not "${agentName}".`);
+    }
+    return metadata;
+}
+function requireSessionId(session, mode) {
+    if (!session?.id) {
+        throw new Error(`session.id is required when session.mode="${mode}".`);
+    }
+    return session.id;
+}
+function formatBackgroundSpawn(agentName, runId, sessionId) {
+    return `<background_spawn agent_id="${runId}"${formatOptionalAttr("session_id", sessionId)}>\nAgent "${agentName}" spawned in background with id "${runId}".\nUse agent_status, agent_await, or agent_cancel to manage it.\n</background_spawn>`;
+}
+function formatTaskResult(result, sessionId) {
+    return `<task_result${formatOptionalAttr("session_id", sessionId)}>\n${result}\n</task_result>`;
+}
+function formatAgentStatus(runId, status, result, error, sessionId) {
+    const sessionAttr = formatOptionalAttr("session_id", sessionId);
+    if (status === "done") {
+        return `<agent_status id="${runId}" status="done"${sessionAttr}>\n${result}\n</agent_status>`;
+    }
+    if (status === "failed") {
+        return `<agent_status id="${runId}" status="failed"${sessionAttr} error="${error ?? "unknown"}" />`;
+    }
+    if (status === "cancelled") {
+        return `<agent_status id="${runId}" status="cancelled"${sessionAttr} />`;
+    }
+    return `<agent_status id="${runId}" status="running"${sessionAttr} />`;
+}
+function formatOptionalAttr(name, value) {
+    return value ? ` ${name}="${value}"` : "";
+}
 // ── Helpers ──────────────────────────────────────────────────────────
 function toTokenUsage(usage) {
     return {
@@ -468,14 +747,14 @@ function buildAbortedStepMessages(text, reasoning) {
 }
 function wrapToolsWithApproval(tools, approve) {
     const wrapped = {};
-    for (const [name, t] of Object.entries(tools)) {
-        if (!t.execute) {
-            wrapped[name] = t;
+    for (const [name, toolDef] of Object.entries(tools)) {
+        if (!toolDef.execute) {
+            wrapped[name] = toolDef;
             continue;
         }
-        const originalExecute = t.execute;
+        const originalExecute = toolDef.execute;
         wrapped[name] = {
-            ...t,
+            ...toolDef,
             execute: async (input, options) => {
                 const allowed = await approve({
                     toolName: name,