@librechat/agents 3.1.68 → 3.1.70

package/dist/cjs/tools/skillCatalog.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+const HEADER = '## Available Skills';
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+const DEFAULT_BUDGET_PERCENT = 0.01;
+const DEFAULT_MAX_ENTRY_CHARS = 250;
+const DEFAULT_MIN_DESC_LENGTH = 20;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+function formatSkillCatalog(skills, opts) {
+    if (skills.length === 0)
+        return '';
+    const contextWindowTokens = opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+    const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
+    const maxEntryChars = Math.max(1, opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS);
+    const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
+    const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    const budgetChars = Math.floor(contextWindowTokens * budgetPercent * charsPerToken);
+    const capped = skills.map((s) => ({
+        name: s.name,
+        description: s.description.length > maxEntryChars
+            ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
+            : s.description,
+    }));
+    const fullOutput = formatEntries(capped);
+    if (fullOutput.length <= budgetChars)
+        return fullOutput;
+    const headerLen = HEADER.length + 2;
+    const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
+    const availableChars = budgetChars - headerLen - newlineChars;
+    const perEntryOverhead = 4;
+    const nameCharsTotal = capped.reduce((sum, s) => sum + s.name.length + perEntryOverhead, 0);
+    const availableForDescs = availableChars - nameCharsTotal;
+    if (availableForDescs <= 0) {
+        return fitNamesOnly(capped, budgetChars);
+    }
+    const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
+    if (maxDescPerEntry < minDescLength) {
+        return fitNamesOnly(capped, budgetChars);
+    }
+    const truncated = capped.map((s) => ({
+        name: s.name,
+        description: s.description.length > maxDescPerEntry
+            ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
+            : s.description,
+    }));
+    const result = formatEntries(truncated);
+    if (result.length <= budgetChars)
+        return result;
+    return fitNamesOnly(capped, budgetChars);
+}
+function formatEntries(entries) {
+    const lines = entries.map((e) => e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`);
+    return `${HEADER}\n\n${lines.join('\n')}`;
+}
+/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
+function fitNamesOnly(entries, budgetChars) {
+    // Format: "HEADER\n\n- name1\n- name2\n..."
+    // Running sum avoids O(n²) repeated string construction.
+    const prefix = HEADER.length + 2; // "HEADER\n\n"
+    const entryOverhead = 2; // "- "
+    let total = prefix;
+    let fitCount = 0;
+    for (let i = 0; i < entries.length; i++) {
+        const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
+        if (total + added > budgetChars)
+            break;
+        total += added;
+        fitCount = i + 1;
+    }
+    if (fitCount === 0)
+        return '';
+    const namesOnly = entries
+        .slice(0, fitCount)
+        .map((s) => ({ name: s.name, description: '' }));
+    return formatEntries(namesOnly);
+}
+
+exports.formatSkillCatalog = formatSkillCatalog;
+//# sourceMappingURL=skillCatalog.cjs.map

package/dist/cjs/tools/skillCatalog.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillCatalog.cjs","sources":["../../../src/tools/skillCatalog.ts"],"sourcesContent":["// src/tools/skillCatalog.ts\nimport type { SkillCatalogEntry } from '@/types';\n\nconst HEADER = '## Available Skills';\nconst DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;\nconst DEFAULT_BUDGET_PERCENT = 0.01;\nconst DEFAULT_MAX_ENTRY_CHARS = 250;\nconst DEFAULT_MIN_DESC_LENGTH = 20;\nconst DEFAULT_CHARS_PER_TOKEN = 4;\n\nexport type SkillCatalogOptions = {\n  /** Total context window in tokens. Default: 200_000 */\n  contextWindowTokens?: number;\n  /** Fraction of context budget for catalog. Default: 0.01 (1%) */\n  budgetPercent?: number;\n  /** Max chars per entry description. Default: 250 */\n  maxEntryChars?: number;\n  /** Descriptions below this length trigger names-only fallback. Default: 20 */\n  minDescLength?: number;\n  /** Approximate chars per token for budget calculation. Default: 4 */\n  charsPerToken?: number;\n};\n\n/**\n * Formats a skill catalog for injection into agent context.\n * Uses a truncation ladder: full descriptions, proportional truncation, names-only.\n * Returns empty string for empty input.\n */\nexport function formatSkillCatalog(\n  skills: SkillCatalogEntry[],\n  opts?: SkillCatalogOptions\n): string {\n  if (skills.length === 0) return '';\n\n  const contextWindowTokens =\n    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;\n  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;\n  const maxEntryChars = Math.max(\n    1,\n    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS\n  );\n  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;\n  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;\n\n  const budgetChars = Math.floor(\n    contextWindowTokens * budgetPercent * charsPerToken\n  );\n\n  const capped = skills.map((s) => ({\n    name: s.name,\n    description:\n      s.description.length > maxEntryChars\n        ? s.description.slice(0, maxEntryChars - 1) + '\\u2026'\n        : s.description,\n  }));\n\n  const fullOutput = formatEntries(capped);\n  if (fullOutput.length <= budgetChars) return fullOutput;\n\n  const headerLen = HEADER.length + 2;\n  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;\n  const availableChars = budgetChars - headerLen - newlineChars;\n  const perEntryOverhead = 4;\n  const nameCharsTotal = capped.reduce(\n    (sum, s) => sum + s.name.length + perEntryOverhead,\n    0\n  );\n  const availableForDescs = availableChars - nameCharsTotal;\n\n  if (availableForDescs <= 0) {\n    return fitNamesOnly(capped, budgetChars);\n  }\n\n  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);\n\n  if (maxDescPerEntry < minDescLength) {\n    return fitNamesOnly(capped, budgetChars);\n  }\n\n  const truncated = capped.map((s) => ({\n    name: s.name,\n    description:\n      s.description.length > maxDescPerEntry\n        ? s.description.slice(0, maxDescPerEntry - 1) + '\\u2026'\n        : s.description,\n  }));\n\n  const result = formatEntries(truncated);\n  if (result.length <= budgetChars) return result;\n  return fitNamesOnly(capped, budgetChars);\n}\n\nfunction formatEntries(\n  entries: { name: string; description: string }[]\n): string {\n  const lines = entries.map((e) =>\n    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`\n  );\n  return `${HEADER}\\n\\n${lines.join('\\n')}`;\n}\n\n/** Names-only fallback that drops trailing entries if the list still exceeds budget. */\nfunction fitNamesOnly(\n  entries: { name: string }[],\n  budgetChars: number\n): string {\n  // Format: \"HEADER\\n\\n- name1\\n- name2\\n...\"\n  // Running sum avoids O(n²) repeated string construction.\n  const prefix = HEADER.length + 2; // \"HEADER\\n\\n\"\n  const entryOverhead = 2; // \"- \"\n  let total = prefix;\n  let fitCount = 0;\n\n  for (let i = 0; i < entries.length; i++) {\n    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;\n    if (total + added > budgetChars) break;\n    total += added;\n    fitCount = i + 1;\n  }\n\n  if (fitCount === 0) return '';\n  const namesOnly = entries\n    .slice(0, fitCount)\n    .map((s) => ({ name: s.name, description: '' }));\n  return formatEntries(namesOnly);\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/tools/subagent/SubagentExecutor.cjs

@@ -0,0 +1,511 @@
+'use strict';
+
+var nanoid = require('nanoid');
+var base = require('@langchain/core/callbacks/base');
+var messages = require('@langchain/core/messages');
+var _enum = require('../../common/enum.cjs');
+var executeHooks = require('../../hooks/executeHooks.cjs');
+
+const DEFAULT_MAX_TURNS = 25;
+const RECURSION_MULTIPLIER = 3;
+const ERROR_MESSAGE_MAX_CHARS = 200;
+const HOOK_FALLBACK = Object.freeze({
+    additionalContexts: [],
+    errors: [],
+});
+class SubagentExecutor {
+    configs;
+    parentSignal;
+    hookRegistry;
+    parentRunId;
+    parentAgentId;
+    tokenCounter;
+    maxDepth;
+    createChildGraph;
+    resolveParentHandlerRegistry;
+    constructor(options) {
+        this.configs = options.configs;
+        this.parentSignal = options.parentSignal;
+        this.hookRegistry = options.hookRegistry;
+        this.parentRunId = options.parentRunId;
+        this.parentAgentId = options.parentAgentId;
+        this.tokenCounter = options.tokenCounter;
+        this.maxDepth = options.maxDepth ?? 1;
+        this.createChildGraph = options.createChildGraph;
+        const rawRegistry = options.parentHandlerRegistry;
+        if (typeof rawRegistry === 'function') {
+            this.resolveParentHandlerRegistry = rawRegistry;
+        }
+        else if (rawRegistry != null) {
+            this.resolveParentHandlerRegistry = () => rawRegistry;
+        }
+    }
+    /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
+    getParentHandlerRegistry() {
+        return this.resolveParentHandlerRegistry?.();
+    }
+    async execute(params) {
+        const { description, subagentType, threadId, parentToolCallId } = params;
+        const config = this.configs.get(subagentType);
+        if (!config) {
+            const available = [...this.configs.keys()].join(', ');
+            return {
+                content: `Error: Unknown subagent type "${subagentType}". Available types: ${available}`,
+                messages: [],
+            };
+        }
+        if (this.maxDepth <= 0) {
+            return {
+                content: 'Error: Maximum subagent nesting depth exceeded.',
+                messages: [],
+            };
+        }
+        const childAgentId = config.agentInputs.agentId ||
+            `${this.parentAgentId ?? 'agent'}_sub_${nanoid.nanoid(8)}`;
+        if (this.hookRegistry?.hasHookFor('SubagentStart', this.parentRunId) === true) {
+            const hookResult = await executeHooks.executeHooks({
+                registry: this.hookRegistry,
+                input: {
+                    hook_event_name: 'SubagentStart',
+                    runId: this.parentRunId,
+                    threadId,
+                    parentAgentId: this.parentAgentId,
+                    agentId: childAgentId,
+                    agentType: subagentType,
+                    inputs: [new messages.HumanMessage(description)],
+                },
+                sessionId: this.parentRunId,
+                matchQuery: subagentType,
+            }).catch(() => HOOK_FALLBACK);
+            /**
+             * `ask` is treated identically to `deny` in the subagent context:
+             * subagents are non-interactive, so there is no prompt path for `ask`.
+             * Both decisions block execution and return a "Blocked" tool result.
+             */
+            if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {
+                return {
+                    content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
+                    messages: [],
+                };
+            }
+        }
+        const parentRegistry = this.getParentHandlerRegistry();
+        const forwardingEnabled = parentRegistry != null;
+        /**
+         * Keep `toolDefinitions` only when the host has actually wired an
+         * `ON_TOOL_EXECUTE` handler. `Run` always constructs a `HandlerRegistry`,
+         * so treating any registry as "forwarding enabled" would leak
+         * `toolDefinitions` into children whose hosts cannot execute them — the
+         * child's `ToolNode` batch promise would hang forever with no handler to
+         * resolve/reject. Gating on the tool-execute handler preserves the
+         * recoverable "no tools" path for registry-but-no-handler configs.
+         */
+        const hasToolExecuteHandler = parentRegistry?.getHandler(_enum.GraphEvents.ON_TOOL_EXECUTE) != null;
+        const childInputs = buildChildInputs(config, childAgentId, this.maxDepth, 
+        /* keepToolDefinitions */ hasToolExecuteHandler);
+        const childRunId = `${this.parentRunId}_sub_${nanoid.nanoid(8)}`;
+        const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+        const childGraph = this.createChildGraph({
+            runId: childRunId,
+            signal: this.parentSignal,
+            agents: [childInputs],
+            tokenCounter: this.tokenCounter,
+        });
+        const forwarder = forwardingEnabled
+            ? this.createForwarderCallback({
+                parentRegistry: parentRegistry,
+                subagentType,
+                subagentAgentId: childAgentId,
+                childRunId,
+                parentToolCallId,
+            })
+            : undefined;
+        if (forwarder) {
+            await this.emitSubagentUpdate(parentRegistry, {
+                childRunId,
+                subagentType,
+                subagentAgentId: childAgentId,
+                parentToolCallId,
+                phase: 'start',
+                label: `Subagent "${subagentType}" started`,
+            });
+        }
+        let result;
+        try {
+            const workflow = childGraph.createWorkflow();
+            /**
+             * When `parentHandlerRegistry` is provided (forwarding mode), attach a
+             * lightweight callback that intercepts the child's `on_custom_event`
+             * dispatches and routes them to the parent's registry — either as
+             * operational events (ON_TOOL_EXECUTE) or wrapped ON_SUBAGENT_UPDATE
+             * envelopes. Native LangChain streaming events (on_chat_model_stream,
+             * etc.) still do NOT propagate to the parent's outer streamEvents
+             * iterator — the `callbacks` array REPLACES the inherited chain, so
+             * parent handlers won't receive child stream chunks and raise "No
+             * agent context found" lookups on the parent's agentContexts map.
+             *
+             * When no registry is provided (legacy isolation), `callbacks: []`
+             * fully detaches the child.
+             *
+             * `runName` gives the child a distinct LangSmith trace root (avoids
+             * nested trace pollution).
+             */
+            const callbacks = forwarder ? [forwarder] : [];
+            result = await workflow.invoke({ messages: [new messages.HumanMessage(description)] }, {
+                recursionLimit: maxTurns * RECURSION_MULTIPLIER,
+                signal: this.parentSignal,
+                callbacks,
+                runName: `subagent:${subagentType}`,
+                configurable: {
+                    thread_id: childRunId,
+                },
+            });
+        }
+        catch (error) {
+            const errorMessage = truncateErrorMessage(error);
+            if (forwarder) {
+                await this.emitSubagentUpdate(parentRegistry, {
+                    childRunId,
+                    subagentType,
+                    subagentAgentId: childAgentId,
+                    parentToolCallId,
+                    phase: 'error',
+                    label: `Subagent "${subagentType}" errored: ${errorMessage}`,
+                    data: { message: errorMessage },
+                });
+            }
+            childGraph.clearHeavyState();
+            return {
+                content: `Subagent error: ${errorMessage}`,
+                messages: [],
+            };
+        }
+        const filteredContent = filterSubagentResult(result.messages);
+        if (this.hookRegistry?.hasHookFor('SubagentStop', this.parentRunId) === true) {
+            /**
+             * Awaited (not fire-and-forget) for deterministic test synchronization
+             * and consistency with PostCompact. The parent is already waiting on the
+             * tool result, so the small extra latency is acceptable. Errors are
+             * swallowed — SubagentStop is observational.
+             */
+            await executeHooks.executeHooks({
+                registry: this.hookRegistry,
+                input: {
+                    hook_event_name: 'SubagentStop',
+                    runId: this.parentRunId,
+                    threadId,
+                    agentId: childAgentId,
+                    agentType: subagentType,
+                    messages: result.messages,
+                },
+                sessionId: this.parentRunId,
+                matchQuery: subagentType,
+            }).catch(() => {
+                /* SubagentStop is observational — swallow errors */
+            });
+        }
+        if (forwarder) {
+            await this.emitSubagentUpdate(parentRegistry, {
+                childRunId,
+                subagentType,
+                subagentAgentId: childAgentId,
+                parentToolCallId,
+                phase: 'stop',
+                label: `Subagent "${subagentType}" finished`,
+            });
+        }
+        childGraph.clearHeavyState();
+        return { content: filteredContent, messages: result.messages };
+    }
+    /**
+     * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
+     * parent's handler registry. Silent no-op when no parent registry is set.
+     * Errors are swallowed — update events are observational.
+     */
+    async emitSubagentUpdate(parentRegistry, args) {
+        const handler = parentRegistry.getHandler(_enum.GraphEvents.ON_SUBAGENT_UPDATE);
+        if (!handler) {
+            return;
+        }
+        const event = {
+            runId: this.parentRunId,
+            subagentRunId: args.childRunId,
+            subagentType: args.subagentType,
+            subagentAgentId: args.subagentAgentId,
+            parentAgentId: this.parentAgentId,
+            parentToolCallId: args.parentToolCallId,
+            phase: args.phase,
+            data: args.data,
+            label: args.label,
+            timestamp: new Date().toISOString(),
+        };
+        try {
+            await handler.handle(_enum.GraphEvents.ON_SUBAGENT_UPDATE, event);
+        }
+        catch {
+            /* observational — swallow */
+        }
+    }
+    /**
+     * Builds a BaseCallbackHandler that intercepts the child graph's custom
+     * events. Routing rules:
+     *   - `ON_TOOL_EXECUTE` → forwarded as-is to the parent's ON_TOOL_EXECUTE
+     *     handler (so event-driven tools work identically for child and parent).
+     *   - `ON_RUN_STEP` / `ON_RUN_STEP_DELTA` / `ON_RUN_STEP_COMPLETED` /
+     *     `ON_MESSAGE_DELTA` / `ON_REASONING_DELTA` → wrapped in a
+     *     {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope with a human-readable
+     *     label, delivered to the parent's subagent-update handler.
+     *   - Everything else → ignored (keeps parent's UI scoped to the events it
+     *     cares about; host apps can extend by registering more phases).
+     */
+    createForwarderCallback(args) {
+        const { parentRegistry, subagentType, subagentAgentId, childRunId, parentToolCallId, } = args;
+        const parentRunId = this.parentRunId;
+        const parentAgentId = this.parentAgentId;
+        const wrap = async (eventName, phase, data) => {
+            const handler = parentRegistry.getHandler(_enum.GraphEvents.ON_SUBAGENT_UPDATE);
+            if (!handler) {
+                return;
+            }
+            const event = {
+                runId: parentRunId,
+                subagentRunId: childRunId,
+                subagentType,
+                subagentAgentId,
+                parentAgentId,
+                parentToolCallId,
+                phase,
+                data,
+                label: summarizeEvent(eventName, data),
+                timestamp: new Date().toISOString(),
+            };
+            try {
+                await handler.handle(_enum.GraphEvents.ON_SUBAGENT_UPDATE, event);
+            }
+            catch {
+                /* observational — swallow */
+            }
+        };
+        const handler = base.BaseCallbackHandler.fromMethods({
+            [_enum.Callback.CUSTOM_EVENT]: async (eventName, data) => {
+                if (eventName === _enum.GraphEvents.ON_TOOL_EXECUTE) {
+                    const toolHandler = parentRegistry.getHandler(_enum.GraphEvents.ON_TOOL_EXECUTE);
+                    if (toolHandler) {
+                        await toolHandler.handle(_enum.GraphEvents.ON_TOOL_EXECUTE, data);
+                    }
+                    /**
+                     * We also surface a short notice in the subagent-update stream so
+                     * the UI can show "calling <tool>" for each tool the child spawns.
+                     */
+                    await wrap(eventName, 'run_step', data);
+                    return;
+                }
+                if (eventName === _enum.GraphEvents.ON_RUN_STEP) {
+                    await wrap(eventName, 'run_step', data);
+                    return;
+                }
+                if (eventName === _enum.GraphEvents.ON_RUN_STEP_DELTA) {
+                    await wrap(eventName, 'run_step_delta', data);
+                    return;
+                }
+                if (eventName === _enum.GraphEvents.ON_RUN_STEP_COMPLETED) {
+                    await wrap(eventName, 'run_step_completed', data);
+                    return;
+                }
+                if (eventName === _enum.GraphEvents.ON_MESSAGE_DELTA) {
+                    await wrap(eventName, 'message_delta', data);
+                    return;
+                }
+                if (eventName === _enum.GraphEvents.ON_REASONING_DELTA) {
+                    await wrap(eventName, 'reasoning_delta', data);
+                    return;
+                }
+            },
+        });
+        /**
+         * `awaitHandlers = true` is required so the child's `ToolNode` actually
+         * blocks on the parent's `ON_TOOL_EXECUTE` handler until it resolves
+         * the batch request. The same flag applies to observational events
+         * (message_delta, run_step, …), which means a slow
+         * `ON_SUBAGENT_UPDATE` handler on the host serializes the child
+         * stream. If host-side latency becomes a concern, a future
+         * refinement could split operational and observational events into
+         * separate callback handlers with distinct await semantics.
+         */
+        handler.awaitHandlers = true;
+        return handler;
+    }
+}
+/**
+ * Produces a short single-line label for an arbitrary forwarded child event.
+ * Used to populate {@link SubagentUpdateEvent.label} so the host UI can show
+ * a compact status ticker without parsing the raw payload.
+ */
+function summarizeEvent(eventName, data) {
+    if (eventName === _enum.GraphEvents.ON_TOOL_EXECUTE) {
+        const req = data;
+        const names = (req.toolCalls ?? [])
+            .map((c) => c.name)
+            .filter((n) => typeof n === 'string');
+        return names.length > 0 ? `Calling ${names.join(', ')}` : 'Calling tool';
+    }
+    if (eventName === _enum.GraphEvents.ON_RUN_STEP) {
+        const step = data;
+        const detailType = step.stepDetails?.type ?? step.type ?? 'step';
+        if (detailType === 'tool_calls') {
+            const names = (step.stepDetails?.tool_calls ?? [])
+                .map((c) => c.name)
+                .filter((n) => typeof n === 'string');
+            return names.length > 0
+                ? `Using tool: ${names.join(', ')}`
+                : 'Planning tool call';
+        }
+        if (detailType === 'message_creation') {
+            return 'Thinking…';
+        }
+        return `Step: ${detailType}`;
+    }
+    if (eventName === _enum.GraphEvents.ON_RUN_STEP_COMPLETED) {
+        const step = data;
+        const tool = step.result?.tool_call;
+        if (tool?.name != null && tool.name !== '') {
+            return `Tool ${tool.name} complete`;
+        }
+        return 'Step complete';
+    }
+    if (eventName === _enum.GraphEvents.ON_MESSAGE_DELTA) {
+        return 'Streaming…';
+    }
+    return eventName;
+}
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+function filterSubagentResult(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]._getType() !== 'ai') {
+            continue;
+        }
+        const content = messages[i].content;
+        if (typeof content === 'string') {
+            if (content)
+                return content;
+            continue;
+        }
+        if (!Array.isArray(content)) {
+            continue;
+        }
+        const textParts = [];
+        for (const block of content) {
+            if (typeof block === 'string') {
+                textParts.push(block);
+            }
+            else if ('type' in block && block.type === 'text' && 'text' in block) {
+                textParts.push(block.text);
+            }
+        }
+        if (textParts.length > 0) {
+            return textParts.join('\n');
+        }
+    }
+    return 'Task completed';
+}
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+function resolveSubagentConfigs(configs, parentContext) {
+    const resolved = configs
+        .map((config) => {
+        if (config.agentInputs != null) {
+            return config;
+        }
+        if (config.self !== true || parentContext._sourceInputs == null) {
+            return null;
+        }
+        return {
+            ...config,
+            agentInputs: { ...parentContext._sourceInputs },
+        };
+    })
+        .filter((c) => c != null);
+    const seenTypes = new Set();
+    for (const config of resolved) {
+        if (seenTypes.has(config.type)) {
+            throw new Error(`Duplicate subagent type "${config.type}". Each SubagentConfig must have a unique "type" field.`);
+        }
+        seenTypes.add(config.type);
+    }
+    return resolved;
+}
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * (optionally) event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * When `keepToolDefinitions` is `true`, the child retains the parent's
+ * `toolDefinitions` so event-driven tools remain usable. This is only safe
+ * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
+ * registered handler — otherwise the child will hang on tool dispatch.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+function buildChildInputs(config, childAgentId, parentMaxDepth, keepToolDefinitions = false) {
+    const { agentInputs } = config;
+    const childInputs = {
+        ...agentInputs,
+        agentId: childAgentId,
+        toolDefinitions: keepToolDefinitions
+            ? agentInputs.toolDefinitions
+            : undefined,
+        /**
+         * Subagents run in an isolated context by contract. Parent-run-scoped
+         * fields that would otherwise survive the shallow-spread clone — the
+         * cross-run conversation summary and the prior-turn tool-discovery
+         * set — are cleared here so the child starts fresh. Host applications
+         * that want a subagent to see parent context must thread it in
+         * explicitly (e.g. via the `description` argument to the subagent
+         * tool), not via inherited state.
+         */
+        initialSummary: undefined,
+        discoveredTools: undefined,
+    };
+    if (config.allowNested === true) {
+        childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);
+    }
+    else {
+        childInputs.subagentConfigs = undefined;
+        childInputs.maxSubagentDepth = undefined;
+    }
+    return childInputs;
+}
+function truncateErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.length <= ERROR_MESSAGE_MAX_CHARS) {
+        return message;
+    }
+    return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}...`;
+}
+
+exports.SubagentExecutor = SubagentExecutor;
+exports.buildChildInputs = buildChildInputs;
+exports.filterSubagentResult = filterSubagentResult;
+exports.resolveSubagentConfigs = resolveSubagentConfigs;
+exports.summarizeEvent = summarizeEvent;
+//# sourceMappingURL=SubagentExecutor.cjs.map