bernard-agent 0.8.1 → 0.9.0

package/dist/tool-call-repair.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRepairHook = makeRepairHook;
+const ai_1 = require("ai");
+const index_js_1 = require("./providers/index.js");
+const logger_js_1 = require("./logger.js");
+/**
+ * Heuristic detector for tool-call argument truncation. When the model emits a
+ * massive single string argument (e.g. a 16 KB heredoc inside a `command`
+ * field), the response may be cut off mid-string, producing
+ * "Unterminated string in JSON" or similar from JSON.parse.
+ */
+function looksLikeTruncationError(message) {
+    return (/unterminated string/i.test(message) ||
+        /unexpected end of (json|input)/i.test(message) ||
+        /expected.*after.*in json/i.test(message));
+}
+/**
+ * Produces an `experimental_repairToolCall` hook for `generateText`. When the
+ * AI SDK fails to parse a model's tool-call arguments (or the model targets a
+ * nonexistent tool), the hook runs ONE focused generation asking the model to
+ * re-emit a valid tool call. Returns the corrected call, or `null` to let the
+ * SDK throw.
+ *
+ * The repair attempt is bounded to a single retry per failed tool call — no
+ * looping, no escalation. Failures are logged to the debug stream.
+ *
+ * Special-cases JSON truncation (the model packed too much content into a
+ * single string arg) by hinting at `file_write` + `shell` as the safe pattern
+ * for large payloads.
+ */
+function makeRepairHook(opts) {
+    const { config, provider, model, label, abortSignal } = opts;
+    const resolvedProvider = provider ?? config.provider;
+    const resolvedModel = model ?? config.model;
+    return async ({ toolCall, tools, parameterSchema, messages, system, error }) => {
+        try {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const isInvalidArgs = ai_1.InvalidToolArgumentsError.isInstance(error);
+            const isNoSuchTool = ai_1.NoSuchToolError.isInstance(error);
+            let hint = '';
+            if (isInvalidArgs && looksLikeTruncationError(errorMessage)) {
+                hint =
+                    '\n\nThe arguments appear to have been truncated mid-string. For payloads larger than ~1 KB (file contents, scripts, JSON bodies), write the content to a file using `file_write` (or save a script with `file_write` and execute it with `shell`) instead of inlining it as a tool-call argument.';
+            }
+            else if (isNoSuchTool) {
+                const available = Object.keys(tools).slice(0, 25).join(', ');
+                hint = `\n\nThe tool "${toolCall.toolName}" does not exist. Available tools include: ${available}.`;
+            }
+            let schemaText = '';
+            try {
+                const schema = parameterSchema({ toolName: toolCall.toolName });
+                schemaText = `\n\nExpected parameter schema for \`${toolCall.toolName}\`:\n\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\``;
+            }
+            catch {
+                // No schema available (e.g. unknown tool) — skip.
+            }
+            const recoveryMessage = {
+                role: 'user',
+                content: `Your previous tool call to \`${toolCall.toolName}\` failed to parse:\n\n${errorMessage}${schemaText}${hint}\n\nRe-emit the tool call with valid arguments. Do not explain — just call the tool.`,
+            };
+            const repairMessages = [...messages, recoveryMessage];
+            const result = await (0, ai_1.generateText)({
+                model: (0, index_js_1.getModelForConfig)(config, resolvedProvider, resolvedModel),
+                providerOptions: (0, index_js_1.getProviderOptionsForConfig)(config, resolvedProvider),
+                tools,
+                toolChoice: isNoSuchTool ? 'auto' : { type: 'tool', toolName: toolCall.toolName },
+                maxSteps: 1,
+                maxTokens: config.maxTokens,
+                system,
+                messages: repairMessages,
+                abortSignal,
+            });
+            const repaired = result.toolCalls?.[0];
+            if (!repaired) {
+                (0, logger_js_1.debugLog)(`tool-call-repair:${label}:no-call`, {
+                    toolName: toolCall.toolName,
+                    errorMessage,
+                });
+                return null;
+            }
+            (0, logger_js_1.debugLog)(`tool-call-repair:${label}:ok`, {
+                original: toolCall.toolName,
+                repaired: repaired.toolName,
+            });
+            return {
+                toolCallType: 'function',
+                toolCallId: toolCall.toolCallId,
+                toolName: repaired.toolName,
+                args: JSON.stringify(repaired.args),
+            };
+        }
+        catch (err) {
+            (0, logger_js_1.debugLog)(`tool-call-repair:${label}:error`, err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    };
+}
+//# sourceMappingURL=tool-call-repair.js.map

package/dist/tool-call-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-repair.js","sourceRoot":"","sources":["../src/tool-call-repair.ts"],"names":[],"mappings":"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"}

package/dist/tool-profiles.d.ts

@@ -0,0 +1,70 @@
+export interface ToolProfileExample {
+    summary: string;
+    args: string;
+    note?: string;
+}
+export interface ToolProfileBadExample {
+    summary: string;
+    args: string;
+    errorSnippet: string;
+    fix: string;
+    note?: string;
+}
+export interface ToolProfile {
+    toolName: string;
+    category?: string;
+    guidelines: string[];
+    goodExamples: ToolProfileExample[];
+    badExamples: ToolProfileBadExample[];
+    createdAt: string;
+    updatedAt: string;
+    errorCount: number;
+    successCount: number;
+}
+export declare const MAX_PROFILE_EXAMPLES = 5;
+/** Classifies a shell command string into a sub-category for profile lookup. */
+export declare function classifyShellCommand(command: string): string;
+export type ToolErrorInfo = {
+    isError: true;
+    snippet: string;
+} | {
+    isError: false;
+};
+/**
+ * Detects whether a tool's return value indicates an error. Each tool has a
+ * different error shape so we normalize them into a single discriminated union.
+ */
+export declare function detectToolError(toolName: string, result: unknown): ToolErrorInfo;
+export declare class ToolProfileStore {
+    private dirReady;
+    constructor();
+    private ensureDir;
+    private filePath;
+    get(toolKey: string): ToolProfile | undefined;
+    getOrCreate(toolKey: string): ToolProfile;
+    save(profile: ToolProfile): void;
+    recordBadExample(toolKey: string, args: string, errorSnippet: string): void;
+    recordGoodExample(toolKey: string, args: string, note?: string): void;
+    /**
+     * After a bad example with `fix === '(awaiting successful retry)'`, if the
+     * same tool key succeeds, patch the most recent unfixed bad example with the
+     * working args.
+     */
+    patchLastBadWithFix(toolKey: string, workingArgs: string): void;
+    list(): ToolProfile[];
+    private seedDefaults;
+}
+/**
+ * Approximate character budget for the rendered profiles block. At ~4 chars/token
+ * this gives ~1000 tokens — enough for guidance without crowding the context.
+ * Profiles are sorted by error count (highest first) so the most valuable
+ * guidance survives when the budget is tight.
+ */
+export declare const MAX_PROFILE_PROMPT_CHARS = 4000;
+/**
+ * Renders tool profiles into a compact system-prompt block. Only profiles with
+ * at least one guideline or bad example are included. At most 2 bad examples
+ * shown per tool. Profiles are sorted by error count (most errors first) and
+ * the total output is capped at {@link MAX_PROFILE_PROMPT_CHARS}.
+ */
+export declare function buildToolProfilesPrompt(store: ToolProfileStore): string;

package/dist/tool-profiles.js

@@ -0,0 +1,385 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PROFILE_PROMPT_CHARS = exports.ToolProfileStore = exports.MAX_PROFILE_EXAMPLES = void 0;
+exports.classifyShellCommand = classifyShellCommand;
+exports.detectToolError = detectToolError;
+exports.buildToolProfilesPrompt = buildToolProfilesPrompt;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const paths_js_1 = require("./paths.js");
+const fs_utils_js_1 = require("./fs-utils.js");
+exports.MAX_PROFILE_EXAMPLES = 5;
+const SEED_MARKER = '.seeded-v1';
+// ---------------------------------------------------------------------------
+// Shell command classification
+// ---------------------------------------------------------------------------
+const SHELL_CATEGORIES = [
+    { pattern: /^\s*git\b/, category: 'git' },
+    { pattern: /^\s*gh\b/, category: 'gh' },
+    { pattern: /^\s*(docker|docker-compose)\b/, category: 'docker' },
+    { pattern: /^\s*(npm|yarn|pnpm|bun)\b/, category: 'npm' },
+    {
+        pattern: /^\s*(ls|find|cp|mv|mkdir|rm|cat|head|tail|stat|chmod|chown|ln|du|df|wc)\b/,
+        category: 'fs',
+    },
+    { pattern: /^\s*(curl|wget)\b/, category: 'http' },
+    { pattern: /^\s*(systemctl|service|journalctl)\b/, category: 'systemd' },
+    { pattern: /^\s*(python3?|node|ruby|perl|tsx|ts-node)\b/, category: 'runtime' },
+];
+/** Classifies a shell command string into a sub-category for profile lookup. */
+function classifyShellCommand(command) {
+    for (const { pattern, category } of SHELL_CATEGORIES) {
+        if (pattern.test(command))
+            return category;
+    }
+    return 'general';
+}
+/**
+ * Detects whether a tool's return value indicates an error. Each tool has a
+ * different error shape so we normalize them into a single discriminated union.
+ */
+function detectToolError(toolName, result) {
+    if (result === null || result === undefined)
+        return { isError: false };
+    // shell: { output: string, is_error: boolean }
+    if (toolName === 'shell' && typeof result === 'object') {
+        const r = result;
+        if (r.is_error === true) {
+            return { isError: true, snippet: String(r.output ?? '').slice(0, 200) };
+        }
+        return { isError: false };
+    }
+    // web_read: returns string starting with "Error:"
+    if (toolName === 'web_read' && typeof result === 'string') {
+        if (result.startsWith('Error:')) {
+            return { isError: true, snippet: result.slice(0, 200) };
+        }
+        return { isError: false };
+    }
+    // web_search: provider failures / no-result diagnostics are returned as strings
+    if (toolName === 'web_search' && typeof result === 'string') {
+        if (result.startsWith('web_search returned no results')) {
+            return { isError: true, snippet: result.slice(0, 200) };
+        }
+        return { isError: false };
+    }
+    // file_read_lines, file_edit_lines: { error: string }
+    if ((toolName === 'file_read_lines' || toolName === 'file_edit_lines') &&
+        typeof result === 'object') {
+        const r = result;
+        if (typeof r.error === 'string') {
+            return { isError: true, snippet: r.error.slice(0, 200) };
+        }
+        return { isError: false };
+    }
+    // Generic fallback for MCP and unknown tools: string starting with "Error"
+    if (typeof result === 'string' && result.startsWith('Error')) {
+        return { isError: true, snippet: result.slice(0, 200) };
+    }
+    return { isError: false };
+}
+// ---------------------------------------------------------------------------
+// Seeded profiles
+// ---------------------------------------------------------------------------
+const SEEDED_PROFILES = {
+    'shell.git': {
+        guidelines: [
+            'Always check `git status` before destructive operations.',
+            'Use `--oneline` for compact log output.',
+            'Prefer `git log main..HEAD` to see branch-only commits.',
+        ],
+        goodExamples: [
+            {
+                summary: 'Log branch commits vs main',
+                args: '{"command":"git log --oneline main..HEAD"}',
+            },
+        ],
+    },
+    'shell.gh': {
+        guidelines: [
+            'Use `gh issue list --json` for machine-parseable output.',
+            'Always pass `--repo owner/repo` when context is ambiguous.',
+        ],
+        goodExamples: [],
+    },
+    'shell.docker': {
+        guidelines: [
+            'Prefer `docker compose` (v2) over `docker-compose` (v1).',
+            'Use `--format json` with inspect commands for reliable parsing.',
+        ],
+        goodExamples: [],
+    },
+    'shell.npm': {
+        guidelines: [
+            'Use `--json` flag where available for structured output.',
+            'Prefer `npm ci` over `npm install` in CI/scripts for reproducibility.',
+        ],
+        goodExamples: [],
+    },
+    'shell.fs': {
+        guidelines: [
+            'Quote all paths to handle spaces.',
+            'Use `find -print0 | xargs -0` for filenames with spaces/newlines.',
+            'Prefer `file_read_lines`/`file_edit_lines` over `cat`/`sed` for reading and editing files.',
+        ],
+        goodExamples: [],
+    },
+    'shell.http': {
+        guidelines: [
+            'Use `-s` (silent) with curl to suppress progress bars.',
+            'Always set a timeout with `-m` or `--max-time` to avoid hangs.',
+        ],
+        goodExamples: [],
+    },
+    web_read: {
+        guidelines: [
+            'Always pass a CSS selector to scope large pages.',
+            'URL must start with http:// or https://.',
+        ],
+        goodExamples: [
+            {
+                summary: 'Fetch docs with article selector',
+                args: '{"url":"https://example.com/docs","selector":"article"}',
+            },
+        ],
+    },
+    file_read_lines: {
+        guidelines: [
+            'Use offset+limit to paginate files larger than ~200 lines.',
+            'Always read before editing to get current line numbers.',
+        ],
+        goodExamples: [],
+    },
+    file_edit_lines: {
+        guidelines: [
+            'Read first with file_read_lines to get exact line numbers — they shift after edits.',
+            'Edits are atomic: all operations succeed or all revert.',
+        ],
+        goodExamples: [],
+    },
+};
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+class ToolProfileStore {
+    dirReady = false;
+    constructor() {
+        this.ensureDir();
+        this.seedDefaults();
+    }
+    ensureDir() {
+        if (this.dirReady)
+            return;
+        fs.mkdirSync(paths_js_1.TOOL_PROFILES_DIR, { recursive: true });
+        this.dirReady = true;
+    }
+    filePath(toolKey) {
+        const safe = toolKey.replace(/[^a-zA-Z0-9._-]/g, '-');
+        return path.join(paths_js_1.TOOL_PROFILES_DIR, `${safe}.json`);
+    }
+    get(toolKey) {
+        try {
+            return JSON.parse(fs.readFileSync(this.filePath(toolKey), 'utf-8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getOrCreate(toolKey) {
+        const existing = this.get(toolKey);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        return {
+            toolName: toolKey,
+            guidelines: [],
+            goodExamples: [],
+            badExamples: [],
+            createdAt: now,
+            updatedAt: now,
+            errorCount: 0,
+            successCount: 0,
+        };
+    }
+    save(profile) {
+        this.ensureDir();
+        const updated = { ...profile, updatedAt: new Date().toISOString() };
+        (0, fs_utils_js_1.atomicWriteFileSync)(this.filePath(profile.toolName), JSON.stringify(updated, null, 2));
+    }
+    recordBadExample(toolKey, args, errorSnippet) {
+        const profile = this.getOrCreate(toolKey);
+        const bad = {
+            summary: `Failed: ${args.slice(0, 80)}`,
+            args: args.slice(0, 200),
+            errorSnippet,
+            fix: '(awaiting successful retry)',
+        };
+        const updated = [...profile.badExamples, bad].slice(-exports.MAX_PROFILE_EXAMPLES);
+        this.save({ ...profile, badExamples: updated, errorCount: profile.errorCount + 1 });
+    }
+    recordGoodExample(toolKey, args, note) {
+        const profile = this.getOrCreate(toolKey);
+        const good = {
+            summary: 'Successful call',
+            args: args.slice(0, 200),
+            note,
+        };
+        const updated = [...profile.goodExamples, good].slice(-exports.MAX_PROFILE_EXAMPLES);
+        this.save({ ...profile, goodExamples: updated, successCount: profile.successCount + 1 });
+    }
+    /**
+     * After a bad example with `fix === '(awaiting successful retry)'`, if the
+     * same tool key succeeds, patch the most recent unfixed bad example with the
+     * working args.
+     */
+    patchLastBadWithFix(toolKey, workingArgs) {
+        const profile = this.get(toolKey);
+        if (!profile || profile.badExamples.length === 0)
+            return;
+        const bads = [...profile.badExamples];
+        const last = bads[bads.length - 1];
+        if (last.fix === '(awaiting successful retry)') {
+            bads[bads.length - 1] = { ...last, fix: `Use instead: ${workingArgs.slice(0, 200)}` };
+            this.save({ ...profile, badExamples: bads });
+        }
+    }
+    list() {
+        try {
+            return fs
+                .readdirSync(paths_js_1.TOOL_PROFILES_DIR)
+                .filter((f) => f.endsWith('.json'))
+                .flatMap((f) => {
+                try {
+                    return [
+                        JSON.parse(fs.readFileSync(path.join(paths_js_1.TOOL_PROFILES_DIR, f), 'utf-8')),
+                    ];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    seedDefaults() {
+        const markerPath = path.join(paths_js_1.TOOL_PROFILES_DIR, SEED_MARKER);
+        if (fs.existsSync(markerPath))
+            return;
+        try {
+            const now = new Date().toISOString();
+            for (const [toolKey, seed] of Object.entries(SEEDED_PROFILES)) {
+                if (this.get(toolKey))
+                    continue;
+                const profile = {
+                    toolName: toolKey,
+                    guidelines: seed.guidelines,
+                    goodExamples: seed.goodExamples,
+                    badExamples: [],
+                    createdAt: now,
+                    updatedAt: now,
+                    errorCount: 0,
+                    successCount: 0,
+                };
+                this.save(profile);
+            }
+            fs.writeFileSync(markerPath, now, 'utf-8');
+        }
+        catch {
+            // best-effort; never block startup
+        }
+    }
+}
+exports.ToolProfileStore = ToolProfileStore;
+// ---------------------------------------------------------------------------
+// System prompt rendering
+// ---------------------------------------------------------------------------
+/**
+ * Approximate character budget for the rendered profiles block. At ~4 chars/token
+ * this gives ~1000 tokens — enough for guidance without crowding the context.
+ * Profiles are sorted by error count (highest first) so the most valuable
+ * guidance survives when the budget is tight.
+ */
+exports.MAX_PROFILE_PROMPT_CHARS = 4000;
+/**
+ * Renders tool profiles into a compact system-prompt block. Only profiles with
+ * at least one guideline or bad example are included. At most 2 bad examples
+ * shown per tool. Profiles are sorted by error count (most errors first) and
+ * the total output is capped at {@link MAX_PROFILE_PROMPT_CHARS}.
+ */
+function buildToolProfilesPrompt(store) {
+    const profiles = store
+        .list()
+        .filter((p) => p.guidelines.length > 0 || p.badExamples.length > 0)
+        .sort((a, b) => b.errorCount - a.errorCount);
+    if (profiles.length === 0)
+        return '';
+    const header = '## Tool Usage Profiles\n\nThe following notes apply when calling these tools:\n';
+    let totalChars = header.length;
+    const sections = [header];
+    for (const profile of profiles) {
+        const label = profile.toolName.startsWith('shell.')
+            ? `shell (${profile.toolName.slice(6)} commands)`
+            : profile.toolName;
+        const sectionLines = [`### ${label}`];
+        for (const g of profile.guidelines) {
+            sectionLines.push(`- ${g}`);
+        }
+        const shownBad = profile.badExamples.slice(-2);
+        if (shownBad.length > 0) {
+            sectionLines.push('');
+            sectionLines.push('Avoid these patterns (observed errors):');
+            for (const b of shownBad) {
+                sectionLines.push(`- BAD: ${b.args} -> Error: ${b.errorSnippet}`);
+                if (b.fix && b.fix !== '(awaiting successful retry)') {
+                    sectionLines.push(`  FIX: ${b.fix}`);
+                }
+            }
+        }
+        sectionLines.push('');
+        const section = sectionLines.join('\n');
+        if (totalChars + section.length > exports.MAX_PROFILE_PROMPT_CHARS)
+            break;
+        totalChars += section.length;
+        sections.push(section);
+    }
+    // Only the header — nothing fit the budget (unlikely but safe)
+    if (sections.length <= 1)
+        return '';
+    return sections.join('\n');
+}
+//# sourceMappingURL=tool-profiles.js.map

package/dist/tool-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-profiles.js","sourceRoot":"","sources":["../src/tool-profiles.ts"],"names":[],"mappings":"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"}

package/dist/tools/activity-summary.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds a deterministic Markdown summary of every tool call recorded by a
+ * `generateText` run. Used as a post-run activity log so callers can verify
+ * what a sub-agent or specialist actually did, even when the model's prose
+ * output is empty or under-reports the side effects.
+ */
+export declare function buildActivitySummary(steps: unknown[] | undefined): string;
+/**
+ * Returns the model's text with an Activity Log appended. When the text is
+ * empty or whitespace-only, emits a preamble explaining that the activity was
+ * reconstructed from the tool-call log.
+ *
+ * `agentLabel` identifies the caller in the empty-text preamble (e.g. "specialist", "subagent").
+ */
+export declare function appendActivitySummary(text: string, steps: unknown[] | undefined, agentLabel: string): string;

package/dist/tools/activity-summary.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildActivitySummary = buildActivitySummary;
+exports.appendActivitySummary = appendActivitySummary;
+const critic_js_1 = require("../critic.js");
+const ARG_PREVIEW = 200;
+const RESULT_PREVIEW = 400;
+function previewValue(v, limit) {
+    const s = typeof v === 'string' ? v : JSON.stringify(v ?? null);
+    return s.slice(0, limit);
+}
+/**
+ * Builds a deterministic Markdown summary of every tool call recorded by a
+ * `generateText` run. Used as a post-run activity log so callers can verify
+ * what a sub-agent or specialist actually did, even when the model's prose
+ * output is empty or under-reports the side effects.
+ */
+function buildActivitySummary(steps) {
+    const log = (0, critic_js_1.extractToolCallLog)((steps ?? []));
+    if (log.length === 0) {
+        return '## Activity Log\n(no tool calls)';
+    }
+    const lines = log.map((e, i) => `${i + 1}. ${e.toolName}(${previewValue(e.args, ARG_PREVIEW)})\n   → ${previewValue(e.result, RESULT_PREVIEW)}`);
+    return ['## Activity Log', `${log.length} tool call(s):`, ...lines].join('\n');
+}
+/**
+ * Returns the model's text with an Activity Log appended. When the text is
+ * empty or whitespace-only, emits a preamble explaining that the activity was
+ * reconstructed from the tool-call log.
+ *
+ * `agentLabel` identifies the caller in the empty-text preamble (e.g. "specialist", "subagent").
+ */
+function appendActivitySummary(text, steps, agentLabel) {
+    const summary = buildActivitySummary(steps);
+    if (!text.trim()) {
+        return [
+            `(${agentLabel} produced no text summary; activity reconstructed from tool-call log)`,
+            '',
+            summary,
+        ].join('\n');
+    }
+    return `${text.trimEnd()}\n\n${summary}`;
+}
+//# sourceMappingURL=activity-summary.js.map

package/dist/tools/activity-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-summary.js","sourceRoot":"","sources":["../../src/tools/activity-summary.ts"],"names":[],"mappings":";;AAgBA,oDAUC;AASD,sDAcC;AAjDD,4CAAkD;AAElD,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,SAAS,YAAY,CAAC,CAAU,EAAE,KAAa;IAC7C,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IAChE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,KAA4B;IAC/D,MAAM,GAAG,GAAG,IAAA,8BAAkB,EAAC,CAAC,KAAK,IAAI,EAAE,CAA6C,CAAC,CAAC;IAC1F,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,kCAAkC,CAAC;IAC5C,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CACnB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAClH,CAAC;IACF,OAAO,CAAC,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,gBAAgB,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,IAAY,EACZ,KAA4B,EAC5B,UAAkB;IAElB,MAAM,OAAO,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACjB,OAAO;YACL,IAAI,UAAU,uEAAuE;YACrF,EAAE;YACF,OAAO;SACR,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,OAAO,EAAE,CAAC;AAC3C,CAAC"}