@animus-labs/cortex 0.2.0

package/dist/sub-agent-manager.js

@@ -0,0 +1,192 @@
+/**
+ * SubAgentManager: tracks active sub-agents, enforces concurrency limits,
+ * manages lifecycle, and delivers background completion notifications.
+ *
+ * Each sub-agent is an independent CortexAgent instance tracked by task ID.
+ * The manager does not own the CortexAgent; it tracks references and
+ * coordinates lifecycle events for the consumer.
+ *
+ * References:
+ *   - docs/cortex/tools/sub-agent.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+// ---------------------------------------------------------------------------
+// SubAgentManager
+// ---------------------------------------------------------------------------
+export class SubAgentManager {
+    agents = new Map();
+    maxConcurrent;
+    hooks = {};
+    constructor(config) {
+        this.maxConcurrent = config?.maxConcurrent ?? 4;
+    }
+    /**
+     * Set lifecycle hooks. Called by CortexAgent to wire consumer event handlers.
+     */
+    setHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Check if another sub-agent can be spawned within the concurrency limit.
+     */
+    canSpawn() {
+        return this.agents.size < this.maxConcurrent;
+    }
+    /**
+     * Get the number of currently active sub-agents.
+     */
+    get activeCount() {
+        return this.agents.size;
+    }
+    /**
+     * Get the concurrency limit.
+     */
+    get limit() {
+        return this.maxConcurrent;
+    }
+    /**
+     * Register a newly spawned sub-agent.
+     * Returns false if the concurrency limit would be exceeded.
+     */
+    track(entry) {
+        if (this.agents.size >= this.maxConcurrent) {
+            return false;
+        }
+        this.agents.set(entry.taskId, entry);
+        // Fire lifecycle hook
+        try {
+            this.hooks.onSpawned?.(entry.taskId, entry.instructions, entry.background);
+        }
+        catch {
+            // Swallow hook errors
+        }
+        return true;
+    }
+    /**
+     * Mark a sub-agent as completed and remove it from tracking.
+     */
+    complete(taskId, result) {
+        const entry = this.agents.get(taskId);
+        if (!entry)
+            return;
+        this.agents.delete(taskId);
+        // Resolve the completion promise
+        entry.resolve(result);
+        // Fire lifecycle hook (pass full result metadata including toolCalls)
+        try {
+            const usageWithToolCalls = { ...result.usage };
+            if (result.toolCalls) {
+                usageWithToolCalls['toolCalls'] = result.toolCalls;
+            }
+            this.hooks.onCompleted?.(taskId, result.output, result.status, usageWithToolCalls);
+        }
+        catch {
+            // Swallow hook errors
+        }
+    }
+    /**
+     * Mark a sub-agent as failed and remove it from tracking.
+     */
+    fail(taskId, error) {
+        const entry = this.agents.get(taskId);
+        if (!entry)
+            return;
+        this.agents.delete(taskId);
+        // Resolve the completion promise with a failed result
+        entry.resolve({
+            output: '',
+            status: 'failed',
+            usage: { turns: 0, cost: 0, durationMs: Date.now() - entry.spawnedAt, contextTokens: 0 },
+        });
+        // Fire lifecycle hook
+        try {
+            this.hooks.onFailed?.(taskId, error);
+        }
+        catch {
+            // Swallow hook errors
+        }
+    }
+    /**
+     * Get a tracked sub-agent by task ID.
+     */
+    get(taskId) {
+        return this.agents.get(taskId);
+    }
+    /**
+     * Update tool activity for a running sub-agent.
+     * Called when child tool_call_start events are forwarded via EventBridge.
+     */
+    updateToolActivity(taskId, toolName, summary) {
+        const entry = this.agents.get(taskId);
+        if (!entry)
+            return;
+        entry.toolCount++;
+        entry.lastToolName = toolName;
+        entry.lastToolSummary = summary;
+        entry.lastToolStartedAt = Date.now();
+    }
+    /**
+     * Get all active sub-agent task IDs.
+     */
+    getActiveTaskIds() {
+        return [...this.agents.keys()];
+    }
+    /**
+     * Get completion promises for all background sub-agents.
+     * Used to build follow-up messages when background agents complete.
+     */
+    getBackgroundCompletions() {
+        const results = [];
+        for (const [taskId, entry] of this.agents) {
+            if (entry.background) {
+                results.push({ taskId, completion: entry.completion });
+            }
+        }
+        return results;
+    }
+    /**
+     * Cancel all active sub-agents. Called during parent destroy().
+     * Aborts each sub-agent and removes it from tracking.
+     *
+     * @param abortFn - Function to abort a CortexAgent (passed to avoid circular dep)
+     */
+    async cancelAll(abortFn) {
+        const entries = [...this.agents.values()];
+        this.agents.clear();
+        const settled = await Promise.allSettled(entries.map(async (entry) => {
+            try {
+                await abortFn(entry.agent);
+            }
+            catch {
+                // Best-effort abort
+            }
+            // Resolve the completion promise as cancelled
+            entry.resolve({
+                output: '',
+                status: 'cancelled',
+                usage: { turns: 0, cost: 0, durationMs: Date.now() - entry.spawnedAt, contextTokens: 0 },
+            });
+            // Fire failure hook
+            try {
+                this.hooks.onFailed?.(entry.taskId, 'Parent agent destroyed');
+            }
+            catch {
+                // Swallow hook errors
+            }
+        }));
+        // Log any unexpected errors (consumer should provide logging)
+        for (const result of settled) {
+            if (result.status === 'rejected') {
+                // Swallowed: best-effort cleanup
+            }
+        }
+    }
+    /**
+     * Clean up all state. Called during parent destroy().
+     */
+    destroy() {
+        this.agents.clear();
+        this.hooks = {};
+    }
+}
+//# sourceMappingURL=sub-agent-manager.js.map

package/dist/sub-agent-manager.js.map

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

package/dist/token-estimator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Heuristic token estimation.
+ *
+ * Uses character-based heuristic (chars / 4), the community standard and
+ * closest to Anthropic's official recommendation (chars / 3.5).
+ * Character-based is more stable than word-based across content types
+ * (prose, code, JSON, markdown).
+ *
+ * This is a duplicate of the same utility in @animus-labs/shared,
+ * kept inline to avoid a dependency from cortex to shared.
+ */
+/**
+ * Estimate the number of tokens in a text string.
+ *
+ * Uses chars / 4 heuristic (community standard, ~15% underestimate for Claude).
+ * Not a tokenizer; a fast estimation for budget decisions and compaction triggers.
+ * For exact counts, use the Anthropic count_tokens API.
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (always at least 0, rounded up)
+ */
+export declare function estimateTokens(text: string): number;
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../src/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD"}

package/dist/token-estimator.js

@@ -0,0 +1,27 @@
+/**
+ * Heuristic token estimation.
+ *
+ * Uses character-based heuristic (chars / 4), the community standard and
+ * closest to Anthropic's official recommendation (chars / 3.5).
+ * Character-based is more stable than word-based across content types
+ * (prose, code, JSON, markdown).
+ *
+ * This is a duplicate of the same utility in @animus-labs/shared,
+ * kept inline to avoid a dependency from cortex to shared.
+ */
+/**
+ * Estimate the number of tokens in a text string.
+ *
+ * Uses chars / 4 heuristic (community standard, ~15% underestimate for Claude).
+ * Not a tokenizer; a fast estimation for budget decisions and compaction triggers.
+ * For exact counts, use the Anthropic count_tokens API.
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (always at least 0, rounded up)
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/token-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.js","sourceRoot":"","sources":["../src/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/tool-contract.d.ts

@@ -0,0 +1,68 @@
+import type { ToolExecuteContext } from './types.js';
+/**
+ * Cortex's canonical in-process tool contract.
+ *
+ * All tools registered with CortexAgent are normalized to this signature.
+ * Cortex adapts this shape to pi-agent-core's execute signature at the
+ * registration boundary.
+ */
+export interface CortexTool<TParams = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute: (params: TParams, context?: ToolExecuteContext) => Promise<TResult>;
+    /**
+     * Marks this tool as eligible for deferred loading. When the agent has
+     * `deferredTools.enabled = true`, deferred tools are NOT included in the
+     * `tools` array sent to the model on every turn. Instead, only their names
+     * appear in the `_available_tools` slot, and the model uses ToolSearch to
+     * load full schemas on demand.
+     *
+     * MCP tools get `isMcp: true` set automatically by the MCP client and are
+     * deferred when `deferredTools.deferMcp` is true (default). Built-in or
+     * consumer-supplied tools can opt in via `shouldDefer: true`.
+     */
+    shouldDefer?: boolean;
+    /**
+     * Forces this tool to always be sent in the `tools` array, even if it
+     * matches deferral criteria (e.g., an MCP tool the consumer wants always
+     * available). Overrides `shouldDefer` and the `deferMcp` config.
+     */
+    alwaysLoad?: boolean;
+    /**
+     * Marker indicating this tool was wrapped from an MCP server. Set
+     * automatically by the MCP client. Consumers should not set this manually.
+     */
+    isMcp?: boolean;
+    /**
+     * Optional pi-agent-core execution hint. Use "sequential" for tools that
+     * must update shared agent state before later tool calls in the same batch.
+     */
+    executionMode?: 'sequential' | 'parallel';
+}
+/**
+ * Raw pi-agent-core tool contract.
+ *
+ * Use fromPiAgentTool() to explicitly adapt a tool with this signature into
+ * Cortex's canonical CortexTool shape.
+ */
+export interface PiAgentTool<TParams = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: unknown;
+    executionMode?: 'sequential' | 'parallel';
+    execute: (toolCallId: string, params: TParams, signal?: AbortSignal, onUpdate?: (partialResult: unknown) => void) => Promise<TResult>;
+}
+/**
+ * Explicitly adapt a pi-agent-core-style tool into Cortex's canonical tool contract.
+ */
+export declare function fromPiAgentTool<TParams = unknown, TResult = unknown>(tool: PiAgentTool<TParams, TResult>): CortexTool<TParams, TResult>;
+/**
+ * Validate that a tool matches Cortex's canonical execute signature.
+ *
+ * Cortex does not infer tool execution contracts from function arity. Tools
+ * that already use pi-agent-core's raw execute signature must be adapted
+ * explicitly with fromPiAgentTool().
+ */
+export declare function assertValidCortexTool(tool: CortexTool): CortexTool;
+//# sourceMappingURL=tool-contract.d.ts.map

package/dist/tool-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.d.ts","sourceRoot":"","sources":["../src/tool-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7E;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IAC1C,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,KACxC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClE,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,GAClC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAkB9B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAalE"}

package/dist/tool-contract.js

@@ -0,0 +1,35 @@
+/**
+ * Explicitly adapt a pi-agent-core-style tool into Cortex's canonical tool contract.
+ */
+export function fromPiAgentTool(tool) {
+    const cortexTool = {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        execute: (params, context) => {
+            return tool.execute(context?.toolCallId ?? `${tool.name}-direct`, params, context?.signal, context?.onUpdate);
+        },
+    };
+    if (tool.executionMode) {
+        cortexTool.executionMode = tool.executionMode;
+    }
+    return cortexTool;
+}
+/**
+ * Validate that a tool matches Cortex's canonical execute signature.
+ *
+ * Cortex does not infer tool execution contracts from function arity. Tools
+ * that already use pi-agent-core's raw execute signature must be adapted
+ * explicitly with fromPiAgentTool().
+ */
+export function assertValidCortexTool(tool) {
+    if (typeof tool.execute !== 'function') {
+        throw new Error(`Tool "${tool.name}" is missing an execute() function.`);
+    }
+    if (tool.execute.length > 2) {
+        throw new Error(`Tool "${tool.name}" does not use Cortex's execute(params, context?) contract. ` +
+            'Wrap raw pi-agent-core tools with fromPiAgentTool() before passing them to CortexAgent.create().');
+    }
+    return tool;
+}
+//# sourceMappingURL=tool-contract.js.map

package/dist/tool-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.js","sourceRoot":"","sources":["../src/tool-contract.ts"],"names":[],"mappings":"AAmEA;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAmC;IAEnC,MAAM,UAAU,GAAiC;QAC/C,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,CAAC,MAAe,EAAE,OAA4B,EAAE,EAAE;YACzD,OAAO,IAAI,CAAC,OAAO,CACjB,OAAO,EAAE,UAAU,IAAI,GAAG,IAAI,CAAC,IAAI,SAAS,EAC5C,MAAM,EACN,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,QAA0D,CACpE,CAAC;QACJ,CAAC;KACF,CAAC;IACF,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAgB;IACpD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,qCAAqC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,IAAI,8DAA8D;YAChF,kGAAkG,CACnG,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tool-result-persistence.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Tool result persistence: bookend-and-persist for oversized tool results.
+ *
+ * Sits at the tool execution boundary (refreshTools wrapper). After a tool
+ * returns its result, this module checks whether the text content exceeds
+ * the per-result threshold and either:
+ *   - passes through unchanged (under threshold or skipped tool)
+ *   - persists to disk (when `persistResult` is configured) and returns
+ *     a bookend preview (head + tail) plus a file reference
+ *   - returns a bookend preview only (when no `persistResult` is configured)
+ *
+ * This replaces ad-hoc per-tool truncation (Grep, Bash, WebFetch) with a
+ * single, uniform mechanism. Reuses `applyBookend` and `getToolCategory`
+ * from the existing compaction infrastructure.
+ *
+ * Reference: docs/cortex/tool-result-persistence.md
+ */
+import type { PersistResultFn, ToolCategory } from './types.js';
+/** Default per-tool token threshold. Results larger than this trigger persistence/bookend. */
+export declare const MAX_RESULT_TOKENS = 25000;
+/** Bookend size for the preview (head and tail each). 1,500 chars ≈ 375 tokens. */
+export declare const BOOKEND_CHARS = 1500;
+/**
+ * Tools whose results bypass the interceptor entirely.
+ *
+ * Either inherently bounded (Edit, Write, Glob) or content already on disk
+ * where the model can use offset/limit on the original file (Read).
+ */
+export declare const SKIP_RESULT_PERSISTENCE: Set<string>;
+/**
+ * Built-in per-tool threshold overrides. Tools listed here use a different
+ * token limit than `MAX_RESULT_TOKENS` (25K).
+ *
+ * Rationale per tool:
+ * - Bash: command output is verbose with low signal density (logs, stack
+ *   traces, build spam). A tighter cap reduces noise in context while still
+ *   preserving full output via persistence.
+ *
+ * Consumers can extend or override this map via `CortexAgentConfig.toolResultThresholds`.
+ */
+export declare const DEFAULT_TOOL_THRESHOLDS: Record<string, number>;
+/**
+ * Resolve the effective threshold for a tool.
+ * Order of precedence: consumer overrides > built-in defaults > MAX_RESULT_TOKENS.
+ */
+export declare function resolveThreshold(toolName: string, consumerOverrides?: Record<string, number>): number;
+export interface ApplyPersistenceOptions {
+    toolName: string;
+    toolCallId: string;
+    persistResult?: PersistResultFn | undefined;
+    toolCategories?: Record<string, ToolCategory> | undefined;
+    /** Consumer-provided per-tool threshold overrides (in tokens). */
+    thresholds?: Record<string, number> | undefined;
+}
+/**
+ * Options for processing a full tool result (with potentially multiple parts).
+ * Same shape as ApplyPersistenceOptions minus the per-call identifiers.
+ */
+export interface ProcessResultOptions {
+    toolName: string;
+    toolCallId: string;
+    persistResult?: PersistResultFn | undefined;
+    toolCategories?: Record<string, ToolCategory> | undefined;
+    thresholds?: Record<string, number> | undefined;
+}
+/**
+ * Process a tool result text part for size limiting.
+ *
+ * - Under threshold or skipped tool: returns content unchanged
+ * - Over threshold + `persistResult` configured: persists, returns bookend + file ref
+ * - Over threshold + no `persistResult`: returns bookend only (lossy, but bounded)
+ *
+ * Pure async helper; never throws. Persist failures fall back to bookend-only.
+ */
+export declare function applyResultPersistence(content: string, options: ApplyPersistenceOptions): Promise<string>;
+/**
+ * Process a full tool result (potentially multi-part) through the
+ * persistence interceptor.
+ *
+ * - Iterates the `content` array
+ * - For each `text` part, runs `applyResultPersistence`
+ * - Other part types (e.g., `image`) pass through unchanged
+ * - Returns the same object reference if nothing changed (no allocation)
+ *
+ * Used by `CortexAgent.refreshTools()` at the tool execution boundary.
+ * Exported so the wrapper logic is unit-testable.
+ */
+export declare function processToolResult(result: unknown, options: ProcessResultOptions): Promise<unknown>;
+//# sourceMappingURL=tool-result-persistence.d.ts.map

package/dist/tool-result-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-persistence.d.ts","sourceRoot":"","sources":["../src/tool-result-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQhE,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,mFAAmF;AACnF,eAAO,MAAM,aAAa,OAAQ,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,aAMlC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE1D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAIR;AAMD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAC1D,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAkClB"}

package/dist/tool-result-persistence.js

@@ -0,0 +1,152 @@
+/**
+ * Tool result persistence: bookend-and-persist for oversized tool results.
+ *
+ * Sits at the tool execution boundary (refreshTools wrapper). After a tool
+ * returns its result, this module checks whether the text content exceeds
+ * the per-result threshold and either:
+ *   - passes through unchanged (under threshold or skipped tool)
+ *   - persists to disk (when `persistResult` is configured) and returns
+ *     a bookend preview (head + tail) plus a file reference
+ *   - returns a bookend preview only (when no `persistResult` is configured)
+ *
+ * This replaces ad-hoc per-tool truncation (Grep, Bash, WebFetch) with a
+ * single, uniform mechanism. Reuses `applyBookend` and `getToolCategory`
+ * from the existing compaction infrastructure.
+ *
+ * Reference: docs/cortex/tool-result-persistence.md
+ */
+import { applyBookend, getToolCategory } from './compaction/microcompaction.js';
+import { estimateTokens } from './token-estimator.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default per-tool token threshold. Results larger than this trigger persistence/bookend. */
+export const MAX_RESULT_TOKENS = 25_000;
+/** Bookend size for the preview (head and tail each). 1,500 chars ≈ 375 tokens. */
+export const BOOKEND_CHARS = 1_500;
+/**
+ * Tools whose results bypass the interceptor entirely.
+ *
+ * Either inherently bounded (Edit, Write, Glob) or content already on disk
+ * where the model can use offset/limit on the original file (Read).
+ */
+export const SKIP_RESULT_PERSISTENCE = new Set([
+    'Read',
+    'Edit',
+    'UndoEdit',
+    'Write',
+    'Glob',
+]);
+/**
+ * Built-in per-tool threshold overrides. Tools listed here use a different
+ * token limit than `MAX_RESULT_TOKENS` (25K).
+ *
+ * Rationale per tool:
+ * - Bash: command output is verbose with low signal density (logs, stack
+ *   traces, build spam). A tighter cap reduces noise in context while still
+ *   preserving full output via persistence.
+ *
+ * Consumers can extend or override this map via `CortexAgentConfig.toolResultThresholds`.
+ */
+export const DEFAULT_TOOL_THRESHOLDS = {
+    Bash: 7_500,
+};
+/**
+ * Resolve the effective threshold for a tool.
+ * Order of precedence: consumer overrides > built-in defaults > MAX_RESULT_TOKENS.
+ */
+export function resolveThreshold(toolName, consumerOverrides) {
+    if (consumerOverrides && toolName in consumerOverrides)
+        return consumerOverrides[toolName];
+    if (toolName in DEFAULT_TOOL_THRESHOLDS)
+        return DEFAULT_TOOL_THRESHOLDS[toolName];
+    return MAX_RESULT_TOKENS;
+}
+/**
+ * Process a tool result text part for size limiting.
+ *
+ * - Under threshold or skipped tool: returns content unchanged
+ * - Over threshold + `persistResult` configured: persists, returns bookend + file ref
+ * - Over threshold + no `persistResult`: returns bookend only (lossy, but bounded)
+ *
+ * Pure async helper; never throws. Persist failures fall back to bookend-only.
+ */
+export async function applyResultPersistence(content, options) {
+    if (SKIP_RESULT_PERSISTENCE.has(options.toolName))
+        return content;
+    const threshold = resolveThreshold(options.toolName, options.thresholds);
+    const tokens = estimateTokens(content);
+    if (tokens <= threshold)
+        return content;
+    const bookended = applyBookend(content, BOOKEND_CHARS, BOOKEND_CHARS, tokens);
+    if (options.persistResult) {
+        const category = getToolCategory(options.toolName, options.toolCategories) ?? 'ephemeral';
+        try {
+            const path = await options.persistResult(content, {
+                toolName: options.toolName,
+                toolCallId: options.toolCallId,
+                category,
+            });
+            return [
+                `[Result persisted: ${path} (${content.length.toLocaleString()} chars, ~${tokens.toLocaleString()} tokens)]`,
+                '',
+                bookended,
+                '',
+                'Use the Read tool with offset/limit to examine specific sections.',
+            ].join('\n');
+        }
+        catch {
+            // Persist failed; fall through to bookend-only path below.
+        }
+    }
+    return [
+        `[Result truncated: ~${tokens.toLocaleString()} tokens exceeded ${threshold.toLocaleString()} token limit]`,
+        '',
+        bookended,
+    ].join('\n');
+}
+/**
+ * Process a full tool result (potentially multi-part) through the
+ * persistence interceptor.
+ *
+ * - Iterates the `content` array
+ * - For each `text` part, runs `applyResultPersistence`
+ * - Other part types (e.g., `image`) pass through unchanged
+ * - Returns the same object reference if nothing changed (no allocation)
+ *
+ * Used by `CortexAgent.refreshTools()` at the tool execution boundary.
+ * Exported so the wrapper logic is unit-testable.
+ */
+export async function processToolResult(result, options) {
+    if (!result || typeof result !== 'object')
+        return result;
+    const asObj = result;
+    const content = asObj['content'];
+    if (!Array.isArray(content) || content.length === 0)
+        return result;
+    let modified = false;
+    const newContent = await Promise.all(content.map(async (part) => {
+        if (part &&
+            typeof part === 'object' &&
+            part['type'] === 'text' &&
+            typeof part['text'] === 'string') {
+            const text = part.text;
+            const processed = await applyResultPersistence(text, {
+                toolName: options.toolName,
+                toolCallId: options.toolCallId,
+                persistResult: options.persistResult,
+                toolCategories: options.toolCategories,
+                thresholds: options.thresholds,
+            });
+            if (processed !== text) {
+                modified = true;
+                return { ...part, text: processed };
+            }
+        }
+        return part;
+    }));
+    if (!modified)
+        return result;
+    return { ...asObj, content: newContent };
+}
+//# sourceMappingURL=tool-result-persistence.js.map

package/dist/tool-result-persistence.js.map

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