@tintinweb/pi-subagents 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-03-11
+
+### Fixed
+- **Graceful shutdown in headless mode** — the CLI now waits for all running and queued background agents to complete before exiting (`waitForAll` on `session_shutdown`). Previously, background agents could be silently killed mid-execution when the session ended. Only affects headless/non-interactive mode; interactive sessions already kept the process alive.
+
+### Added
+- `hasRunning()` / `waitForAll()` methods on `AgentManager`.
+- **Cross-package manager access** — agent manager exposed via `Symbol.for("pi-subagents:manager")` on `globalThis` for other extensions to check status or await completion.
+
 ## [0.4.0] - 2026-03-11
 
 ### Added
@@ -188,6 +197,7 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.1]: https://github.com/tintinweb/pi-subagents/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/tintinweb/pi-subagents/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/tintinweb/pi-subagents/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/tintinweb/pi-subagents/compare/v0.2.7...v0.3.0

package/dist/agent-manager.d.ts

@@ -0,0 +1,70 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import type { ExtensionContext, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@mariozechner/pi-ai";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import { type ToolActivity } from "./agent-runner.js";
+import type { SubagentType, AgentRecord, ThinkingLevel } from "./types.js";
+export type OnAgentComplete = (record: AgentRecord) => void;
+interface SpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    /** Called on tool start/end with activity info (for streaming progress to UI). */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    /** Called when the agent session is created (for accessing session stats). */
+    onSessionCreated?: (session: AgentSession) => void;
+}
+export declare class AgentManager {
+    private agents;
+    private cleanupInterval;
+    private onComplete?;
+    private maxConcurrent;
+    /** Queue of background agents waiting to start. */
+    private queue;
+    /** Number of currently running background agents. */
+    private runningBackground;
+    constructor(onComplete?: OnAgentComplete, maxConcurrent?: number);
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n: number): void;
+    getMaxConcurrent(): number;
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
+    /** Actually start an agent (called immediately or from queue drain). */
+    private startAgent;
+    /** Start queued agents up to the concurrency limit. */
+    private drainQueue;
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     */
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">): Promise<AgentRecord>;
+    /**
+     * Resume an existing agent session with a new prompt.
+     */
+    resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+    getRecord(id: string): AgentRecord | undefined;
+    listAgents(): AgentRecord[];
+    abort(id: string): boolean;
+    private cleanup;
+    /** Whether any agents are still running or queued. */
+    hasRunning(): boolean;
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    waitForAll(): Promise<void>;
+    dispose(): void;
+}
+export {};

package/dist/agent-manager.js

@@ -0,0 +1,236 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import { randomUUID } from "node:crypto";
+import { runAgent, resumeAgent } from "./agent-runner.js";
+/** Default max concurrent background agents. */
+const DEFAULT_MAX_CONCURRENT = 4;
+export class AgentManager {
+    agents = new Map();
+    cleanupInterval;
+    onComplete;
+    maxConcurrent;
+    /** Queue of background agents waiting to start. */
+    queue = [];
+    /** Number of currently running background agents. */
+    runningBackground = 0;
+    constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT) {
+        this.onComplete = onComplete;
+        this.maxConcurrent = maxConcurrent;
+        // Cleanup completed agents after 10 minutes (but keep sessions for resume)
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    }
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n) {
+        this.maxConcurrent = Math.max(1, n);
+        // Start queued agents if the new limit allows
+        this.drainQueue();
+    }
+    getMaxConcurrent() {
+        return this.maxConcurrent;
+    }
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi, ctx, type, prompt, options) {
+        const id = randomUUID().slice(0, 17);
+        const abortController = new AbortController();
+        const record = {
+            id,
+            type,
+            description: options.description,
+            status: options.isBackground ? "queued" : "running",
+            toolUses: 0,
+            startedAt: Date.now(),
+            abortController,
+        };
+        this.agents.set(id, record);
+        const args = { pi, ctx, type, prompt, options };
+        if (options.isBackground && this.runningBackground >= this.maxConcurrent) {
+            // Queue it — will be started when a running agent completes
+            this.queue.push({ id, args });
+            return id;
+        }
+        this.startAgent(id, record, args);
+        return id;
+    }
+    /** Actually start an agent (called immediately or from queue drain). */
+    startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        record.status = "running";
+        record.startedAt = Date.now();
+        if (options.isBackground)
+            this.runningBackground++;
+        const promise = runAgent(ctx, type, prompt, {
+            pi,
+            model: options.model,
+            maxTurns: options.maxTurns,
+            isolated: options.isolated,
+            inheritContext: options.inheritContext,
+            thinkingLevel: options.thinkingLevel,
+            signal: record.abortController.signal,
+            onToolActivity: (activity) => {
+                if (activity.type === "end")
+                    record.toolUses++;
+                options.onToolActivity?.(activity);
+            },
+            onTextDelta: options.onTextDelta,
+            onSessionCreated: (session) => {
+                record.session = session;
+                options.onSessionCreated?.(session);
+            },
+        })
+            .then(({ responseText, session, aborted, steered }) => {
+            // Don't overwrite status if externally stopped via abort()
+            if (record.status !== "stopped") {
+                record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+            }
+            record.result = responseText;
+            record.session = session;
+            record.completedAt ??= Date.now();
+            if (options.isBackground) {
+                this.runningBackground--;
+                this.onComplete?.(record);
+                this.drainQueue();
+            }
+            return responseText;
+        })
+            .catch((err) => {
+            // Don't overwrite status if externally stopped via abort()
+            if (record.status !== "stopped") {
+                record.status = "error";
+            }
+            record.error = err instanceof Error ? err.message : String(err);
+            record.completedAt ??= Date.now();
+            if (options.isBackground) {
+                this.runningBackground--;
+                this.onComplete?.(record);
+                this.drainQueue();
+            }
+            return "";
+        });
+        record.promise = promise;
+    }
+    /** Start queued agents up to the concurrency limit. */
+    drainQueue() {
+        while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+            const next = this.queue.shift();
+            const record = this.agents.get(next.id);
+            if (!record || record.status !== "queued")
+                continue;
+            this.startAgent(next.id, record, next.args);
+        }
+    }
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     */
+    async spawnAndWait(pi, ctx, type, prompt, options) {
+        const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+        const record = this.agents.get(id);
+        await record.promise;
+        return record;
+    }
+    /**
+     * Resume an existing agent session with a new prompt.
+     */
+    async resume(id, prompt, signal) {
+        const record = this.agents.get(id);
+        if (!record?.session)
+            return undefined;
+        record.status = "running";
+        record.startedAt = Date.now();
+        record.completedAt = undefined;
+        record.result = undefined;
+        record.error = undefined;
+        try {
+            const responseText = await resumeAgent(record.session, prompt, {
+                onToolActivity: (activity) => {
+                    if (activity.type === "end")
+                        record.toolUses++;
+                },
+                signal,
+            });
+            record.status = "completed";
+            record.result = responseText;
+            record.completedAt = Date.now();
+        }
+        catch (err) {
+            record.status = "error";
+            record.error = err instanceof Error ? err.message : String(err);
+            record.completedAt = Date.now();
+        }
+        return record;
+    }
+    getRecord(id) {
+        return this.agents.get(id);
+    }
+    listAgents() {
+        return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt);
+    }
+    abort(id) {
+        const record = this.agents.get(id);
+        if (!record)
+            return false;
+        // Remove from queue if queued
+        if (record.status === "queued") {
+            this.queue = this.queue.filter(q => q.id !== id);
+            record.status = "stopped";
+            record.completedAt = Date.now();
+            return true;
+        }
+        if (record.status !== "running")
+            return false;
+        record.abortController?.abort();
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        return true;
+    }
+    cleanup() {
+        const cutoff = Date.now() - 10 * 60_000;
+        for (const [id, record] of this.agents) {
+            if (record.status === "running" || record.status === "queued")
+                continue;
+            if ((record.completedAt ?? 0) >= cutoff)
+                continue;
+            // Dispose and clear session so memory can be reclaimed
+            if (record.session) {
+                record.session.dispose();
+                record.session = undefined;
+            }
+            this.agents.delete(id);
+        }
+    }
+    /** Whether any agents are still running or queued. */
+    hasRunning() {
+        return [...this.agents.values()].some(r => r.status === "running" || r.status === "queued");
+    }
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    async waitForAll() {
+        // Loop because drainQueue respects the concurrency limit — as running
+        // agents finish they start queued ones, which need awaiting too.
+        while (true) {
+            this.drainQueue();
+            const pending = [...this.agents.values()]
+                .filter(r => r.status === "running" || r.status === "queued")
+                .map(r => r.promise)
+                .filter(Boolean);
+            if (pending.length === 0)
+                break;
+            await Promise.allSettled(pending);
+        }
+    }
+    dispose() {
+        clearInterval(this.cleanupInterval);
+        // Clear queue
+        this.queue = [];
+        for (const record of this.agents.values()) {
+            record.session?.dispose();
+        }
+        this.agents.clear();
+    }
+}

package/dist/agent-runner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+import { type AgentSession, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@mariozechner/pi-ai";
+import type { SubagentType, ThinkingLevel } from "./types.js";
+/** Get the default max turns value. */
+export declare function getDefaultMaxTurns(): number;
+/** Set the default max turns value (minimum 1). */
+export declare function setDefaultMaxTurns(n: number): void;
+/** Get the grace turns value. */
+export declare function getGraceTurns(): number;
+/** Set the grace turns value (minimum 1). */
+export declare function setGraceTurns(n: number): void;
+/** Info about a tool event in the subagent. */
+export interface ToolActivity {
+    type: "start" | "end";
+    toolName: string;
+}
+export interface RunOptions {
+    /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
+    pi: ExtensionAPI;
+    model?: Model<any>;
+    maxTurns?: number;
+    signal?: AbortSignal;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    /** Called on tool start/end with activity info. */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    onSessionCreated?: (session: AgentSession) => void;
+}
+export interface RunResult {
+    responseText: string;
+    session: AgentSession;
+    /** True if the agent was hard-aborted (max_turns + grace exceeded). */
+    aborted: boolean;
+    /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
+    steered: boolean;
+}
+export declare function runAgent(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+/**
+ * Send a new prompt to an existing session (resume).
+ */
+export declare function resumeAgent(session: AgentSession, prompt: string, options?: {
+    onToolActivity?: (activity: ToolActivity) => void;
+    signal?: AbortSignal;
+}): Promise<string>;
+/**
+ * Send a steering message to a running subagent.
+ * The message will interrupt the agent after its current tool execution.
+ */
+export declare function steerAgent(session: AgentSession, message: string): Promise<void>;
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export declare function getAgentConversation(session: AgentSession): string;

package/dist/agent-runner.js

@@ -0,0 +1,265 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
+import { getToolsForType, getConfig, getAgentConfig } from "./agent-types.js";
+import { buildAgentPrompt } from "./prompts.js";
+import { buildParentContext, extractText } from "./context.js";
+import { detectEnv } from "./env.js";
+/** Names of tools registered by this extension that subagents must NOT inherit. */
+const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+/** Default max turns to prevent subagents from looping indefinitely. */
+let defaultMaxTurns = 50;
+/** Get the default max turns value. */
+export function getDefaultMaxTurns() { return defaultMaxTurns; }
+/** Set the default max turns value (minimum 1). */
+export function setDefaultMaxTurns(n) { defaultMaxTurns = Math.max(1, n); }
+/** Additional turns allowed after the soft limit steer message. */
+let graceTurns = 5;
+/** Get the grace turns value. */
+export function getGraceTurns() { return graceTurns; }
+/** Set the grace turns value (minimum 1). */
+export function setGraceTurns(n) { graceTurns = Math.max(1, n); }
+/**
+ * Try to find the right model for an agent type.
+ * Priority: explicit option > config.model > parent model.
+ */
+function resolveDefaultModel(parentModel, registry, configModel) {
+    if (configModel) {
+        const slashIdx = configModel.indexOf("/");
+        if (slashIdx !== -1) {
+            const provider = configModel.slice(0, slashIdx);
+            const modelId = configModel.slice(slashIdx + 1);
+            // Build a set of available model keys for fast lookup
+            const available = registry.getAvailable?.();
+            const availableKeys = available
+                ? new Set(available.map((m) => `${m.provider}/${m.id}`))
+                : undefined;
+            const isAvailable = (p, id) => !availableKeys || availableKeys.has(`${p}/${id}`);
+            const found = registry.find(provider, modelId);
+            if (found && isAvailable(provider, modelId))
+                return found;
+        }
+    }
+    return parentModel;
+}
+/**
+ * Subscribe to a session and collect the last assistant message text.
+ * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ */
+function collectResponseText(session) {
+    let text = "";
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_start") {
+            text = "";
+        }
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+            text += event.assistantMessageEvent.delta;
+        }
+    });
+    return { getText: () => text, unsubscribe };
+}
+/**
+ * Wire an AbortSignal to abort a session.
+ * Returns a cleanup function to remove the listener.
+ */
+function forwardAbortSignal(session, signal) {
+    if (!signal)
+        return () => { };
+    const onAbort = () => session.abort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    return () => signal.removeEventListener("abort", onAbort);
+}
+export async function runAgent(ctx, type, prompt, options) {
+    const config = getConfig(type);
+    const agentConfig = getAgentConfig(type);
+    const env = await detectEnv(options.pi, ctx.cwd);
+    // Get parent system prompt for append-mode agents
+    const parentSystemPrompt = ctx.getSystemPrompt();
+    // Build system prompt from agent config
+    let systemPrompt;
+    if (agentConfig) {
+        systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env, parentSystemPrompt);
+    }
+    else {
+        // Unknown type fallback: general-purpose (defensive — unreachable in practice
+        // since index.ts resolves unknown types to "general-purpose" before calling runAgent)
+        systemPrompt = buildAgentPrompt({
+            name: type,
+            description: "General-purpose agent",
+            systemPrompt: "",
+            promptMode: "append",
+            extensions: true,
+            skills: true,
+            inheritContext: false,
+            runInBackground: false,
+            isolated: false,
+        }, ctx.cwd, env, parentSystemPrompt);
+    }
+    const tools = getToolsForType(type, ctx.cwd);
+    // Resolve extensions/skills: isolated overrides to false
+    const extensions = options.isolated ? false : config.extensions;
+    const skills = options.isolated ? false : config.skills;
+    // Load extensions/skills: true or string[] → load; false → don't
+    const loader = new DefaultResourceLoader({
+        cwd: ctx.cwd,
+        noExtensions: extensions === false,
+        noSkills: skills === false,
+        noPromptTemplates: true,
+        noThemes: true,
+        systemPromptOverride: () => systemPrompt,
+    });
+    await loader.reload();
+    // Resolve model: explicit option > config.model > parent model
+    const model = options.model ?? resolveDefaultModel(ctx.model, ctx.modelRegistry, agentConfig?.model);
+    // Resolve thinking level: explicit option > agent config > undefined (inherit)
+    const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
+    const sessionOpts = {
+        cwd: ctx.cwd,
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        settingsManager: SettingsManager.create(),
+        modelRegistry: ctx.modelRegistry,
+        model,
+        tools,
+        resourceLoader: loader,
+    };
+    if (thinkingLevel) {
+        sessionOpts.thinkingLevel = thinkingLevel;
+    }
+    // createAgentSession's type signature may not include thinkingLevel yet
+    const { session } = await createAgentSession(sessionOpts);
+    // Filter active tools: remove our own tools to prevent nesting,
+    // and apply extension allowlist if specified
+    if (extensions !== false) {
+        const builtinToolNames = new Set(tools.map(t => t.name));
+        const activeTools = session.getActiveToolNames().filter((t) => {
+            if (EXCLUDED_TOOL_NAMES.includes(t))
+                return false;
+            if (builtinToolNames.has(t))
+                return true;
+            if (Array.isArray(extensions)) {
+                return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
+            }
+            return true;
+        });
+        session.setActiveToolsByName(activeTools);
+    }
+    options.onSessionCreated?.(session);
+    // Track turns for graceful max_turns enforcement
+    let turnCount = 0;
+    const maxTurns = options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns;
+    let softLimitReached = false;
+    let aborted = false;
+    let currentMessageText = "";
+    const unsubTurns = session.subscribe((event) => {
+        if (event.type === "turn_end") {
+            turnCount++;
+            if (!softLimitReached && turnCount >= maxTurns) {
+                softLimitReached = true;
+                session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
+            }
+            else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
+                aborted = true;
+                session.abort();
+            }
+        }
+        if (event.type === "message_start") {
+            currentMessageText = "";
+        }
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+            currentMessageText += event.assistantMessageEvent.delta;
+            options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+        }
+        if (event.type === "tool_execution_start") {
+            options.onToolActivity?.({ type: "start", toolName: event.toolName });
+        }
+        if (event.type === "tool_execution_end") {
+            options.onToolActivity?.({ type: "end", toolName: event.toolName });
+        }
+    });
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, options.signal);
+    // Build the effective prompt: optionally prepend parent context
+    let effectivePrompt = prompt;
+    if (options.inheritContext) {
+        const parentContext = buildParentContext(ctx);
+        if (parentContext) {
+            effectivePrompt = parentContext + prompt;
+        }
+    }
+    try {
+        await session.prompt(effectivePrompt);
+    }
+    finally {
+        unsubTurns();
+        collector.unsubscribe();
+        cleanupAbort();
+    }
+    return { responseText: collector.getText(), session, aborted, steered: softLimitReached };
+}
+/**
+ * Send a new prompt to an existing session (resume).
+ */
+export async function resumeAgent(session, prompt, options = {}) {
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, options.signal);
+    const unsubToolUse = options.onToolActivity
+        ? session.subscribe((event) => {
+            if (event.type === "tool_execution_start")
+                options.onToolActivity({ type: "start", toolName: event.toolName });
+            if (event.type === "tool_execution_end")
+                options.onToolActivity({ type: "end", toolName: event.toolName });
+        })
+        : () => { };
+    try {
+        await session.prompt(prompt);
+    }
+    finally {
+        collector.unsubscribe();
+        unsubToolUse();
+        cleanupAbort();
+    }
+    return collector.getText();
+}
+/**
+ * Send a steering message to a running subagent.
+ * The message will interrupt the agent after its current tool execution.
+ */
+export async function steerAgent(session, message) {
+    await session.steer(message);
+}
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session) {
+    const parts = [];
+    for (const msg of session.messages) {
+        if (msg.role === "user") {
+            const text = typeof msg.content === "string"
+                ? msg.content
+                : extractText(msg.content);
+            if (text.trim())
+                parts.push(`[User]: ${text.trim()}`);
+        }
+        else if (msg.role === "assistant") {
+            const textParts = [];
+            const toolCalls = [];
+            for (const c of msg.content) {
+                if (c.type === "text" && c.text)
+                    textParts.push(c.text);
+                else if (c.type === "toolCall")
+                    toolCalls.push(`  Tool: ${c.toolName ?? "unknown"}`);
+            }
+            if (textParts.length > 0)
+                parts.push(`[Assistant]: ${textParts.join("\n")}`);
+            if (toolCalls.length > 0)
+                parts.push(`[Tool Calls]:\n${toolCalls.join("\n")}`);
+        }
+        else if (msg.role === "toolResult") {
+            const text = extractText(msg.content);
+            const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+            parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+        }
+    }
+    return parts.join("\n\n");
+}