@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/tools/deep-research-tool.js

@@ -0,0 +1,257 @@
+/**
+ * Deep Research tool adapter (`deep_research`).
+ *
+ * Exposes the mature Deep/Wide/STORM research pipeline — until now reachable
+ * ONLY from the `buddy research --deep/--iterations/--perspectives/--ckg` CLI —
+ * to the agent IN CONVERSATION, as a first-class, RAG-selectable, dispatchable
+ * tool. It is a thin ITool adapter: it resolves the ambient provider (same path
+ * as the CLI, `resolveCommandProvider`) and delegates to the SAME orchestrator
+ * (`WideResearchOrchestrator.deepResearch` / `.stormResearch` / `.research`) —
+ * it duplicates NO business logic.
+ *
+ * Two deliberate differences from the CLI path:
+ *   1. CONSERVATIVE in-chat bounds. A tool fired mid-conversation must not kick
+ *      off a massive web crawl, so the defaults are tighter than the CLI's
+ *      (3 sub-questions, 2 queries each, 3 results/query, a low global source
+ *      cap, 1 iteration). Optional params let the agent scale up ONLY when it
+ *      explicitly asks (still clamped).
+ *   2. NEVER-THROWS. Every failure degrades to `{ success:false, error }` — the
+ *      agentic loop never sees an exception from research.
+ *
+ * All side-effecting edges (provider resolution, orchestrator construction) are
+ * INJECTABLE so the delegation is unit-testable with zero network. Their
+ * defaults are resolved via dynamic `import()` so the heavy research graph stays
+ * off the hot import path.
+ *
+ * @module tools/deep-research-tool
+ */
+// ============================================================================
+// Conservative in-chat bounds (tighter than the CLI — a chat call stays cheap)
+// ============================================================================
+/** Report chars returned to the model (it re-reads the report; keep it bounded). */
+const MAX_OUTPUT_CHARS = 16_000;
+/** In-chat defaults — deliberately smaller than the CLI's Deep Research options. */
+const IN_CHAT_DEEP_DEFAULTS = {
+    maxSubQuestions: 3,
+    queriesPerSubQuestion: 2,
+    resultsPerQuery: 3,
+    /** Low global source cap by default (agent may raise via `max_sources`). */
+    maxSources: 6,
+    concurrency: 3,
+    perSourceChars: 2000,
+};
+/** Conservative wide-research fan-out (fewer, faster workers than the CLI's 5). */
+const IN_CHAT_WIDE_OPTIONS = {
+    workers: 3,
+    maxRoundsPerWorker: 6,
+    workerTimeoutMs: 60_000,
+    overallTimeoutMs: 180_000,
+};
+function clampInt(v, def, min, max) {
+    const n = typeof v === 'number' && Number.isFinite(v) ? Math.floor(v) : def;
+    return Math.max(min, Math.min(max, n));
+}
+// ============================================================================
+// The adapter
+// ============================================================================
+export class DeepResearchTool {
+    name = 'deep_research';
+    description = 'Run a bounded, multi-source, CITED research pipeline on a topic and return a structured report with a "## Références" section. Use for questions that need several web sources cross-checked into one report (state of the art, comparisons, "what does the literature say"), not a single quick lookup (use web_search for that).';
+    deps;
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        try {
+            const topic = typeof input.topic === 'string' ? input.topic.trim() : '';
+            if (!topic) {
+                return { success: false, error: 'deep_research requires a non-empty "topic".' };
+            }
+            const provider = await this.resolveProvider();
+            if (!provider) {
+                return {
+                    success: false,
+                    error: 'No LLM provider available for deep_research — set an API key, run `buddy login`, or point CODEBUDDY_PROVIDER=ollama at a local Ollama.',
+                };
+            }
+            // Record<string, unknown> so it threads straight into the orchestrator's
+            // provider-config param (the CLI passes the same { model, baseURL } shape).
+            const providerConfig = {
+                model: provider.model,
+                baseURL: provider.baseURL,
+            };
+            const mode = input.mode === 'wide' ? 'wide' : 'deep';
+            const orchestrator = await this.makeOrchestrator(IN_CHAT_WIDE_OPTIONS);
+            if (mode === 'wide') {
+                const result = await orchestrator.research(topic, provider.apiKey, providerConfig);
+                return { success: true, output: this.renderWide(topic, result) };
+            }
+            // Deep path (default). CONSERVATIVE bounds; agent-supplied knobs are clamped.
+            const maxSources = clampInt(input.max_sources, IN_CHAT_DEEP_DEFAULTS.maxSources, 1, 20);
+            const rounds = clampInt(input.iterations, 1, 1, 3);
+            const wantsStorm = typeof input.perspectives === 'number' && input.perspectives >= 2;
+            const ckgArg = input.ckg === true ? { enabled: true } : undefined;
+            if (wantsStorm && typeof orchestrator.stormResearch === 'function') {
+                const perspectives = clampInt(input.perspectives, 4, 2, 6);
+                const stormOptions = {
+                    ...IN_CHAT_DEEP_DEFAULTS,
+                    maxSources,
+                    perspectives,
+                };
+                const result = await orchestrator.stormResearch(topic, provider.apiKey, providerConfig, stormOptions, undefined, ckgArg);
+                return { success: true, output: this.renderDeep(topic, result) };
+            }
+            const deepOptions = {
+                ...IN_CHAT_DEEP_DEFAULTS,
+                maxSources,
+                rounds,
+            };
+            const result = await orchestrator.deepResearch(topic, provider.apiKey, providerConfig, deepOptions, undefined, ckgArg);
+            return { success: true, output: this.renderDeep(topic, result) };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Deep Research failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Default seams (dynamic import keeps the heavy graph off the hot path)
+    // --------------------------------------------------------------------------
+    async resolveProvider() {
+        if (this.deps.resolveProvider)
+            return this.deps.resolveProvider();
+        const { resolveCommandProvider } = await import('../commands/llm-provider-resolution.js');
+        return resolveCommandProvider();
+    }
+    async makeOrchestrator(options) {
+        if (this.deps.makeOrchestrator)
+            return this.deps.makeOrchestrator(options);
+        const { WideResearchOrchestrator } = await import('../agent/wide-research.js');
+        return new WideResearchOrchestrator(options);
+    }
+    // --------------------------------------------------------------------------
+    // Rendering (bounded — the model re-reads the report)
+    // --------------------------------------------------------------------------
+    renderDeep(topic, result) {
+        const loop = result;
+        const storm = result;
+        const isStorm = Array.isArray(storm.perspectives) && typeof storm.coWritten === 'boolean';
+        const header = [
+            `# Deep Research: ${topic}`,
+            '',
+            isStorm ? 'Mode: deep (STORM multi-perspective)' : 'Mode: deep',
+            `Sources: ${result.sources.length} (${result.duplicatesDropped} near-duplicate(s) dropped)`,
+            isStorm
+                ? `Perspectives: ${storm.perspectives.length}`
+                : typeof loop.rounds === 'number' && loop.rounds > 1
+                    ? `Rounds: ${loop.rounds} (${loop.converged ? 'converged' : 'round cap reached'})`
+                    : undefined,
+            `Planner: ${result.plannerLlmUsed ? 'LLM' : 'deterministic'} | Synthesis: ${result.synthesisLlmUsed ? 'LLM' : 'deterministic'}`,
+            `Duration: ${(result.durationMs / 1000).toFixed(1)}s`,
+            '',
+            '---',
+            '',
+        ].filter((l) => l !== undefined);
+        return this.truncate(`${header.join('\n')}${result.report}`);
+    }
+    renderWide(topic, result) {
+        const header = [
+            `# Wide Research: ${topic}`,
+            '',
+            'Mode: wide (parallel sub-agents)',
+            `Workers: ${result.successCount}/${result.subtopics.length} succeeded`,
+            `Duration: ${(result.durationMs / 1000).toFixed(1)}s`,
+            '',
+            '---',
+            '',
+        ];
+        return this.truncate(`${header.join('\n')}${result.report}`);
+    }
+    /** Truncate cleanly, appending a note so the model knows content was elided. */
+    truncate(text) {
+        if (text.length <= MAX_OUTPUT_CHARS)
+            return text;
+        return `${text.slice(0, MAX_OUTPUT_CHARS)}\n\n… [rapport tronqué à ${MAX_OUTPUT_CHARS} caractères — relancer avec une question plus ciblée pour le détail]`;
+    }
+    // --------------------------------------------------------------------------
+    // ITool boilerplate
+    // --------------------------------------------------------------------------
+    getSchema() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: {
+                type: 'object',
+                properties: {
+                    topic: {
+                        type: 'string',
+                        description: 'The research question or topic to investigate.',
+                    },
+                    mode: {
+                        type: 'string',
+                        enum: ['deep', 'wide'],
+                        description: "'deep' (default): deterministic cited pipeline (plan → search → scrape → dedup → synthesize). 'wide': parallel sub-agent research fan-out (broader, less citation-strict).",
+                    },
+                    iterations: {
+                        type: 'number',
+                        description: 'Deep only: number of gap-analysis rounds (1-3, default 1). >1 re-searches to fill gaps in the draft. Higher = slower/more thorough.',
+                    },
+                    perspectives: {
+                        type: 'number',
+                        description: 'Deep only: research the topic from N diversified perspectives (2-6) and co-write an outline-first cited article (STORM). Activates the multi-perspective pipeline.',
+                    },
+                    ckg: {
+                        type: 'boolean',
+                        description: 'Deep only: bridge the run to the Collective Knowledge Graph — recall prior collective knowledge and ingest the deduped sources for cross-run accumulation.',
+                    },
+                    max_sources: {
+                        type: 'number',
+                        description: 'Deep only: global cap on scraped sources (1-20, default 6). Raise only when the topic explicitly needs broader coverage (slower).',
+                    },
+                },
+                required: ['topic'],
+            },
+        };
+    }
+    validate(input) {
+        if (typeof input !== 'object' || input === null) {
+            return { valid: false, errors: ['Input must be an object'] };
+        }
+        const data = input;
+        if (typeof data.topic !== 'string' || data.topic.trim() === '') {
+            return { valid: false, errors: ['topic must be a non-empty string'] };
+        }
+        return { valid: true };
+    }
+    getMetadata() {
+        return {
+            name: this.name,
+            description: this.description,
+            category: 'web',
+            keywords: [
+                'research',
+                'deep research',
+                'investigate',
+                'sources',
+                'cite',
+                'citation',
+                'report',
+                'literature',
+                'state of the art',
+                "état de l'art",
+                'recherche approfondie',
+                'storm',
+                'perspectives',
+            ],
+            priority: 7,
+            modifiesFiles: false,
+            makesNetworkRequests: true,
+        };
+    }
+    isAvailable() {
+        return true;
+    }
+}
+//# sourceMappingURL=deep-research-tool.js.map

package/dist/tools/deferred-schema-state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deferred MCP-schema state — extracted so `tool_search` can read it WITHOUT
+ * importing `codebuddy/tools.ts` (which imports `tool_search`), breaking the
+ * `tools.ts ↔ tool-search.ts` import cycle. Both sides now depend one-way on
+ * this small state module; neither imports the other for deferred schemas.
+ *
+ * Deferred mode: when an MCP server exposes more tools than the threshold, only
+ * name+description stubs go to the LLM and the FULL schemas live here, resolved
+ * on demand by `tool_search`. This keeps the prompt small without losing reach.
+ */
+import type { CodeBuddyTool } from '../codebuddy/client.js';
+/** Replace the deferred-schema map (null = deferred mode off). Owned by the assembler in tools.ts. */
+export declare function setDeferredMCPSchemas(schemas: Map<string, CodeBuddyTool> | null): void;
+/** The deferred MCP schemas map (empty when off) — for tool_search to resolve full schemas. */
+export declare function getDeferredMCPSchemas(): Map<string, CodeBuddyTool>;
+/** True when deferred MCP schema loading is active (some schemas are held back as stubs). */
+export declare function isDeferredSchemaMode(): boolean;
+/** Resolve full schemas for MCP tools by name (called by tool_search). */
+export declare function resolveDeferredSchemas(toolNames: string[]): CodeBuddyTool[];

package/dist/tools/deferred-schema-state.js

@@ -0,0 +1,33 @@
+/**
+ * Deferred MCP-schema state — extracted so `tool_search` can read it WITHOUT
+ * importing `codebuddy/tools.ts` (which imports `tool_search`), breaking the
+ * `tools.ts ↔ tool-search.ts` import cycle. Both sides now depend one-way on
+ * this small state module; neither imports the other for deferred schemas.
+ *
+ * Deferred mode: when an MCP server exposes more tools than the threshold, only
+ * name+description stubs go to the LLM and the FULL schemas live here, resolved
+ * on demand by `tool_search`. This keeps the prompt small without losing reach.
+ */
+let _deferredMCPSchemas = null;
+/** Replace the deferred-schema map (null = deferred mode off). Owned by the assembler in tools.ts. */
+export function setDeferredMCPSchemas(schemas) {
+    _deferredMCPSchemas = schemas;
+}
+/** The deferred MCP schemas map (empty when off) — for tool_search to resolve full schemas. */
+export function getDeferredMCPSchemas() {
+    return _deferredMCPSchemas ?? new Map();
+}
+/** True when deferred MCP schema loading is active (some schemas are held back as stubs). */
+export function isDeferredSchemaMode() {
+    return _deferredMCPSchemas !== null && _deferredMCPSchemas.size > 0;
+}
+/** Resolve full schemas for MCP tools by name (called by tool_search). */
+export function resolveDeferredSchemas(toolNames) {
+    if (!_deferredMCPSchemas)
+        return [];
+    const map = _deferredMCPSchemas;
+    return toolNames
+        .map((name) => map.get(name))
+        .filter((t) => t !== undefined);
+}
+//# sourceMappingURL=deferred-schema-state.js.map

package/dist/tools/dep-inspect-tool.d.ts

@@ -0,0 +1,32 @@
+import type { ToolResult } from '../types/index.js';
+export interface DepInspectData {
+    root: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts: Record<string, string>;
+    engines: Record<string, string>;
+    totalDependencies: number;
+    lockfile?: string;
+}
+export declare class DepInspectTool {
+    readonly name = "dep_inspect";
+    readonly description = "Inspect package.json dependencies, scripts, engines, and local lockfile presence without network access.";
+    execute(input: unknown): Promise<ToolResult>;
+}
+export declare const DEP_INSPECT_TOOL_DEFINITION: {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                root: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};

package/dist/tools/dep-inspect-tool.js

@@ -0,0 +1,74 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+async function assertRoot(root) {
+    if (!path.isAbsolute(root))
+        throw new Error('root must be an absolute path');
+    const resolved = path.resolve(root);
+    if ([path.parse(resolved).root, '/etc', '/dev', '/proc', '/sys', '/run'].includes(resolved))
+        throw new Error(`Refusing unsafe root: ${resolved}`);
+    const stat = await fs.lstat(resolved);
+    if (!stat.isDirectory())
+        throw new Error(`root is not a directory: ${resolved}`);
+    return resolved;
+}
+async function firstExisting(root, names) {
+    for (const name of names) {
+        try {
+            await fs.access(path.join(root, name));
+            return name;
+        }
+        catch {
+            // continue
+        }
+    }
+    return undefined;
+}
+export class DepInspectTool {
+    name = 'dep_inspect';
+    description = 'Inspect package.json dependencies, scripts, engines, and local lockfile presence without network access.';
+    async execute(input) {
+        try {
+            if (!isRecord(input))
+                return { success: false, error: 'Input must be an object' };
+            if (typeof input.root !== 'string' || input.root.trim() === '')
+                return { success: false, error: 'root must be a non-empty absolute path' };
+            const root = await assertRoot(input.root);
+            const packagePath = path.join(root, 'package.json');
+            const pkg = JSON.parse(await fs.readFile(packagePath, 'utf8'));
+            const dependencies = stringRecord(pkg.dependencies);
+            const devDependencies = stringRecord(pkg.devDependencies);
+            const scripts = stringRecord(pkg.scripts);
+            const engines = stringRecord(pkg.engines);
+            const data = {
+                root,
+                dependencies,
+                devDependencies,
+                scripts,
+                engines,
+                totalDependencies: Object.keys(dependencies).length + Object.keys(devDependencies).length,
+                lockfile: await firstExisting(root, ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock']),
+            };
+            return { success: true, output: `Found ${data.totalDependencies} dependencies and ${Object.keys(scripts).length} scripts`, data };
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+export const DEP_INSPECT_TOOL_DEFINITION = {
+    type: 'function',
+    function: {
+        name: 'dep_inspect',
+        description: 'Inspect package.json dependencies, scripts, engines, and lockfile presence with no network access.',
+        parameters: { type: 'object', properties: { root: { type: 'string', description: 'Absolute project root' } }, required: ['root'] },
+    },
+};
+//# sourceMappingURL=dep-inspect-tool.js.map

package/dist/tools/design-system-tool.d.ts

@@ -0,0 +1,10 @@
+import type { ToolResult } from '../types/index.js';
+export interface DesignSystemToolArgs {
+    action?: 'list' | 'get';
+    id?: string;
+    category?: string;
+    query?: string;
+}
+export declare class DesignSystemTool {
+    execute(args: DesignSystemToolArgs): Promise<ToolResult>;
+}

package/dist/tools/design-system-tool.js

@@ -0,0 +1,95 @@
+import { buildDesignGuidance, getDesignSystem, listDesignSystems, loadCatalog, } from '../design/design-system-registry.js';
+export class DesignSystemTool {
+    async execute(args) {
+        try {
+            if (args.action === 'list') {
+                const systems = listDesignSystems({ category: args.category, query: args.query });
+                return { success: true, output: formatListOutput(systems, args) };
+            }
+            if (args.action === 'get') {
+                const id = args.id?.trim();
+                if (!id)
+                    return { success: false, error: 'Missing required design system id for action=get.' };
+                const detail = getDesignSystem(id);
+                if (!detail) {
+                    return {
+                        success: false,
+                        error: `Unknown design system id: ${id}. Suggestions: ${suggestIds(id).join(', ') || 'none'}`,
+                    };
+                }
+                const guidance = buildDesignGuidance(id);
+                if (!guidance) {
+                    return { success: false, error: `Unable to build guidance for design system id: ${id}` };
+                }
+                return { success: true, output: `${guidance}\n\n${formatTokenReminder(detail.designTokens)}` };
+            }
+            return { success: false, error: "Missing or invalid action. Use action='list' or action='get'." };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { success: false, error: `Design system tool failed: ${message}` };
+        }
+    }
+}
+function formatListOutput(systems, args) {
+    const filters = [args.category ? `category=${args.category}` : null, args.query ? `query=${args.query}` : null]
+        .filter((value) => value !== null)
+        .join(', ');
+    if (systems.length === 0) {
+        return `No design systems found${filters ? ` for ${filters}` : ''}. Total: 0.`;
+    }
+    const shouldGroup = !args.category && !args.query;
+    const lines = [`Found ${systems.length} design system(s)${filters ? ` for ${filters}` : ''}.`];
+    if (shouldGroup) {
+        const byCategory = new Map();
+        for (const system of systems) {
+            const group = byCategory.get(system.category) ?? [];
+            group.push(system);
+            byCategory.set(system.category, group);
+        }
+        for (const [category, entries] of byCategory) {
+            lines.push('', `## ${category}`);
+            lines.push(...entries.map(formatSummaryLine));
+        }
+    }
+    else {
+        lines.push('', ...systems.map(formatSummaryLine));
+    }
+    return lines.join('\n');
+}
+function formatSummaryLine(system) {
+    return `- \`${system.id}\` — ${system.name} — ${system.category} — ${system.tagline}`;
+}
+function formatTokenReminder(designTokens) {
+    if (typeof designTokens !== 'object' || designTokens === null) {
+        return 'Tokens clés: aucun design-tokens.json disponible.';
+    }
+    const record = designTokens;
+    const keys = Object.keys(record).slice(0, 12);
+    if (keys.length === 0)
+        return 'Tokens clés: design-tokens.json vide.';
+    return `Tokens clés disponibles: ${keys.map((key) => `\`${key}\``).join(', ')}.`;
+}
+function suggestIds(id) {
+    const query = id.toLowerCase();
+    return loadCatalog()
+        .map((system) => ({ id: system.id, score: scoreSuggestion(query, system) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, 4)
+        .map((entry) => entry.id);
+}
+function scoreSuggestion(query, system) {
+    const haystacks = [system.id, system.name, system.category, system.tagline].map((value) => value.toLowerCase());
+    let score = 0;
+    for (const value of haystacks) {
+        if (value === query)
+            score += 100;
+        if (value.startsWith(query) || query.startsWith(value))
+            score += 50;
+        if (value.includes(query) || query.includes(value))
+            score += 20;
+    }
+    return score;
+}
+//# sourceMappingURL=design-system-tool.js.map

package/dist/tools/device-tool.d.ts

@@ -6,7 +6,7 @@
  */
 import type { ToolResult } from '../types/index.js';
 export interface DeviceToolInput {
-    action: 'list' | 'pair' | 'remove' | 'snap' | 'screenshot' | 'record' | 'location' | 'run';
+    action: 'list' | 'pair' | 'remove' | 'snap' | 'screenshot' | 'record' | 'location' | 'calendar' | 'run';
     deviceId?: string;
     name?: string;
     transport?: 'ssh' | 'adb' | 'local';
@@ -16,6 +16,7 @@ export interface DeviceToolInput {
     keyPath?: string;
     command?: string;
     duration?: number;
+    days?: number;
 }
 export declare class DeviceTool {
     execute(input: DeviceToolInput): Promise<ToolResult>;

package/dist/tools/device-tool.js

@@ -82,6 +82,27 @@ export class DeviceTool {
                         ? { success: true, output: `Location: lat=${coords.lat}, lon=${coords.lon}` }
                         : { success: false, error: `Location unavailable for device ${input.deviceId}` };
                 }
+                case 'calendar': {
+                    if (!input.deviceId) {
+                        return { success: false, error: 'deviceId is required' };
+                    }
+                    const events = await manager.getCalendarEvents(input.deviceId, input.days);
+                    if (events === null) {
+                        return { success: false, error: `Calendar unavailable for device ${input.deviceId}` };
+                    }
+                    return {
+                        success: true,
+                        output: events.length === 0
+                            ? 'No calendar events found in the requested period.'
+                            : JSON.stringify({
+                                source: `device:${input.deviceId}`,
+                                periodDays: typeof input.days === 'number' && Number.isFinite(input.days)
+                                    ? Math.max(1, Math.min(31, Math.trunc(input.days)))
+                                    : 7,
+                                events,
+                            }, null, 2),
+                    };
+                }
                 case 'run': {
                     if (!input.deviceId || !input.command) {
                         return { success: false, error: 'deviceId and command are required' };

package/dist/tools/diagram-tool.js

@@ -355,12 +355,18 @@ export class DiagramTool {
                 data.push({ label: dataMatch[1], value: parseInt(dataMatch[2]) });
             }
         }
+        if (data.length === 0) {
+            return [title, '─'.repeat(40), '(no data)'].join('\n');
+        }
         const total = data.reduce((sum, d) => sum + d.value, 0);
         const maxLabelLen = Math.max(...data.map(d => d.label.length));
         const result = [title, '─'.repeat(40)];
         for (const item of data) {
-            const pct = ((item.value / total) * 100).toFixed(1);
-            const barLen = Math.round((item.value / total) * 20);
+            // Guard total === 0 (all-zero values): item.value / 0 is NaN, which used
+            // to render "NaN%" and break the bar. Fall back to a 0% empty bar.
+            const fraction = total > 0 ? item.value / total : 0;
+            const pct = (fraction * 100).toFixed(1);
+            const barLen = Math.max(0, Math.min(20, Math.round(fraction * 20)));
             const bar = '█'.repeat(barLen) + '░'.repeat(20 - barLen);
             result.push(`${item.label.padEnd(maxLabelLen)} │${bar}│ ${pct}%`);
         }

package/dist/tools/diff-files-tool.d.ts

@@ -0,0 +1,28 @@
+import type { ToolResult } from '../types/index.js';
+export declare class DiffFilesTool {
+    readonly name = "diff_files";
+    readonly description = "Produce a unified diff between two files under a bounded root using a simple LCS algorithm.";
+    execute(input: unknown): Promise<ToolResult>;
+}
+export declare const DIFF_FILES_TOOL_DEFINITION: {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                root: {
+                    type: string;
+                };
+                left: {
+                    type: string;
+                };
+                right: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};