@compilr-dev/agents 0.3.12 → 0.3.14

package/dist/agent.d.ts

@@ -576,6 +576,19 @@ export interface AgentConfig {
      * ```
      */
     enableFileTracking?: boolean;
+    /**
+     * Options for file context restoration after compaction.
+     *
+     * Controls how file contents are re-injected into the context after
+     * compaction. Small files get their content inlined; large files get
+     * reference-only hints.
+     *
+     * Only applies when `enableFileTracking` is true.
+     */
+    fileRestoration?: {
+        /** Max total tokens for inline file content after compaction (default: 4000) */
+        maxInlineTokens?: number;
+    };
 }
 /**
  * Options for a single run
@@ -861,6 +874,10 @@ export declare class Agent {
      * File access tracker for context restoration hints
      */
     private readonly fileTracker?;
+    /**
+     * File restoration options for post-compaction content injection
+     */
+    private readonly fileRestorationConfig?;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1278,7 +1295,8 @@ export declare class Agent {
     formatRestorationHints(): string;
     /**
      * Inject context restoration hints into messages after compaction/summarization.
-     * Modifies messages array in place if hints are available.
+     * Uses content-aware format: small files get content inlined, large files get
+     * reference-only notes. Each file is injected as a separate user message.
      *
      * @internal
      */

package/dist/agent.js

@@ -93,6 +93,10 @@ export class Agent {
      * File access tracker for context restoration hints
      */
     fileTracker;
+    /**
+     * File restoration options for post-compaction content injection
+     */
+    fileRestorationConfig;
     constructor(config) {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
@@ -215,6 +219,7 @@ export class Agent {
         // File tracking for context restoration hints
         if (config.enableFileTracking && config.contextManager) {
             this.fileTracker = new FileAccessTracker();
+            this.fileRestorationConfig = config.fileRestoration;
             const trackingHook = createFileTrackingHook(this.fileTracker);
             hooksConfig.afterTool = hooksConfig.afterTool ?? [];
             hooksConfig.afterTool.push(trackingHook);
@@ -825,7 +830,8 @@ export class Agent {
     }
     /**
      * Inject context restoration hints into messages after compaction/summarization.
-     * Modifies messages array in place if hints are available.
+     * Uses content-aware format: small files get content inlined, large files get
+     * reference-only notes. Each file is injected as a separate user message.
      *
      * @internal
      */
@@ -833,17 +839,22 @@ export class Agent {
         if (!this.fileTracker || this.fileTracker.size === 0) {
             return;
         }
-        const hints = this.formatRestorationHints();
-        if (!hints) {
+        const hints = this.fileTracker.formatRestorationHintsWithContent({
+            maxInlineTokens: this.fileRestorationConfig?.maxInlineTokens ?? 4000,
+        });
+        if (hints.length === 0) {
             return;
         }
-        // Inject as a user message after the last system message
+        // Insert after system prompt, each as a separate user message
         const systemIndex = messages.findIndex((m) => m.role === 'system');
         const insertIndex = systemIndex >= 0 ? systemIndex + 1 : 0;
-        messages.splice(insertIndex, 0, {
-            role: 'user',
-            content: hints,
-        });
+        // Insert in reverse order so they end up in the correct order
+        for (let i = hints.length - 1; i >= 0; i--) {
+            messages.splice(insertIndex, 0, {
+                role: 'user',
+                content: hints[i].text,
+            });
+        }
     }
     // ==========================================================================
     // Context Compaction
@@ -1532,6 +1543,7 @@ export class Agent {
                 this.contextManager.updateCategoryUsage('system', systemTokens);
             }
             // Check if we need to manage context before starting
+            // Order: emergency (95%) → compaction (50%/20 turns) → warning (90%)
             if (this.contextManager.needsEmergencySummarization()) {
                 emit({
                     type: 'context_warning',
@@ -1550,6 +1562,27 @@ export class Agent {
                     rounds: result.rounds,
                 });
             }
+            else if (this.contextManager.needsCompaction()) {
+                // Proactive compaction (50% utilization or 20+ turns since last compaction)
+                // compact() reads this.conversationHistory which has all previous runs' messages
+                const compactResult = await this.compact({ useSmartCompaction: true });
+                if (compactResult.success) {
+                    // Rebuild messages: compacted history + current userMsg (still in newMessages)
+                    messages = this.systemPrompt
+                        ? [
+                            { role: 'system', content: this.systemPrompt },
+                            ...this.conversationHistory,
+                            ...newMessages,
+                        ]
+                        : [...this.conversationHistory, ...newMessages];
+                    // Don't touch newMessages — it still has [userMsg] which finally needs to append
+                    emit({
+                        type: 'context_compacted',
+                        tokensBefore: compactResult.originalTokens,
+                        tokensAfter: compactResult.summaryTokens,
+                    });
+                }
+            }
             else if (this.contextManager.needsSummarization()) {
                 emit({
                     type: 'context_warning',
@@ -2077,6 +2110,36 @@ export class Agent {
                         completedWithText: false,
                     });
                 }
+                // Auto-compaction: check if context needs compaction after this iteration
+                if (this.contextManager && this.autoContextManagement) {
+                    await this.contextManager.updateTokenCount(messages);
+                    if (this.contextManager.needsCompaction()) {
+                        // Flush current run's messages to conversationHistory so compact() can see them.
+                        // compact() reads this.conversationHistory, which normally only updates in finally.
+                        this.conversationHistory.push(...newMessages);
+                        newMessages.length = 0;
+                        const compactResult = await this.compact({ useSmartCompaction: true });
+                        if (compactResult.success) {
+                            // compact() already replaced this.conversationHistory with compacted version.
+                            // Rebuild local messages array from it.
+                            messages = this.systemPrompt
+                                ? [
+                                    { role: 'system', content: this.systemPrompt },
+                                    ...this.conversationHistory,
+                                ]
+                                : [...this.conversationHistory];
+                            // newMessages stays empty — subsequent iterations will push new messages into it,
+                            // and finally block will correctly append only post-compaction messages.
+                            emit({
+                                type: 'context_compacted',
+                                tokensBefore: compactResult.originalTokens,
+                                tokensAfter: compactResult.summaryTokens,
+                            });
+                        }
+                        // If compact() failed, messages are already flushed to conversationHistory.
+                        // newMessages is empty so finally won't double-push.
+                    }
+                }
                 emit({ type: 'iteration_end', iteration: iterations });
                 // Check if we're about to hit the iteration limit
                 // If callback is defined, ask if we should continue
@@ -2302,13 +2365,15 @@ export class Agent {
      * @param signal - Optional abort signal
      */
     chatWithRetry(messages, options, emit, signal) {
+        // Merge signal into chat options so providers can abort the request
+        const chatOptions = signal ? { ...options, signal } : options;
         // If retry is disabled, return the raw provider stream
         if (!this.retryConfig.enabled) {
-            return this.provider.chat(messages, options);
+            return this.provider.chat(messages, chatOptions);
         }
         const providerName = this.provider.name;
         const { maxAttempts, baseDelayMs, maxDelayMs } = this.retryConfig;
-        return withRetryGenerator(() => this.provider.chat(messages, options), {
+        return withRetryGenerator(() => this.provider.chat(messages, chatOptions), {
             maxAttempts,
             baseDelayMs,
             maxDelayMs,

package/dist/context/file-tracker.d.ts

@@ -32,6 +32,10 @@ export interface FileAccess {
     lineCount?: number;
     /** Optional summary of what was found/changed */
     summary?: string;
+    /** Stored file content (only for small reads, used for post-compaction restoration) */
+    content?: string;
+    /** Token count of stored content */
+    tokenCount?: number;
 }
 /**
  * Options for FileAccessTracker constructor
@@ -47,6 +51,18 @@ export interface FileAccessTrackerOptions {
      * @default true
      */
     deduplicateReferences?: boolean;
+    /**
+     * Maximum line count for a file to have its content stored inline.
+     * Files with more lines than this threshold will only store path/lineCount.
+     * @default 200
+     */
+    inlineThreshold?: number;
+    /**
+     * Maximum number of files that can have stored content at once.
+     * When exceeded, oldest content entries are evicted (path still tracked).
+     * @default 10
+     */
+    maxContentEntries?: number;
 }
 /**
  * Options for formatting restoration hints
@@ -65,6 +81,19 @@ export interface FormatHintsOptions {
     /** Verbosity level (adjusts format automatically) */
     verbosityLevel?: VerbosityLevel;
 }
+/**
+ * A single restoration hint message for post-compaction context injection
+ */
+export interface RestorationHintMessage {
+    /** File path */
+    path: string;
+    /** Whether content is inlined or just referenced */
+    type: 'inline' | 'reference';
+    /** The formatted hint text */
+    text: string;
+    /** Estimated token count of this hint */
+    tokens: number;
+}
 /**
  * Statistics about file accesses
  */
@@ -95,11 +124,13 @@ export declare class FileAccessTracker {
     private readonly accesses;
     private readonly maxEntries;
     private readonly deduplicateReferences;
+    private readonly inlineThreshold;
+    private readonly maxContentEntries;
     constructor(options?: FileAccessTrackerOptions);
     /**
      * Track a file that was fully read
      */
-    trackRead(filePath: string, lineCount: number, summary?: string): void;
+    trackRead(filePath: string, lineCount: number, summary?: string, content?: string): void;
     /**
      * Track a file that was referenced (e.g., appeared in grep/glob results)
      */
@@ -135,6 +166,23 @@ export declare class FileAccessTracker {
      * Format restoration hints for injection after compaction
      */
     formatRestorationHints(options?: FormatHintsOptions): string;
+    /**
+     * Format restoration hints with inline file content (Claude Code style).
+     *
+     * Small files with stored content are inlined up to a token budget.
+     * Large files or files exceeding the budget get reference-only hints.
+     * Each file produces a separate hint message for individual injection.
+     *
+     * Priority order for inlining:
+     * 1. Modified files (most critical context)
+     * 2. Read files, most recent first
+     * 3. Once budget exhausted → remaining become reference-only
+     * 4. Referenced-only files → always reference-only
+     */
+    formatRestorationHintsWithContent(options?: {
+        /** Total token budget for all inline content (default: 4000) */
+        maxInlineTokens?: number;
+    }): RestorationHintMessage[];
     /**
      * Clear all tracked accesses
      */
@@ -143,6 +191,16 @@ export declare class FileAccessTracker {
      * Get the number of tracked files
      */
     get size(): number;
+    /**
+     * Rough token estimate (4 chars ≈ 1 token). Avoids heavy tiktoken dependency
+     * in the tracker — exact counts aren't critical for budget enforcement.
+     */
+    private estimateTokens;
+    /**
+     * Evict oldest stored content when maxContentEntries is exceeded.
+     * Only drops the `content`/`tokenCount` fields — the access entry itself is preserved.
+     */
+    private enforceMaxContentEntries;
     private normalizePath;
     private enforceMaxEntries;
     private getEffectiveMaxFiles;

package/dist/context/file-tracker.js

@@ -38,9 +38,13 @@ export class FileAccessTracker {
     accesses = new Map();
     maxEntries;
     deduplicateReferences;
+    inlineThreshold;
+    maxContentEntries;
     constructor(options = {}) {
         this.maxEntries = options.maxEntries ?? 100;
         this.deduplicateReferences = options.deduplicateReferences ?? true;
+        this.inlineThreshold = options.inlineThreshold ?? 200;
+        this.maxContentEntries = options.maxContentEntries ?? 10;
     }
     // ==========================================================================
     // Track Methods
@@ -48,13 +52,15 @@ export class FileAccessTracker {
     /**
      * Track a file that was fully read
      */
-    trackRead(filePath, lineCount, summary) {
+    trackRead(filePath, lineCount, summary, content) {
         const normalizedPath = this.normalizePath(filePath);
         // Read supersedes reference - remove any existing reference
         const existing = this.accesses.get(normalizedPath);
         if (existing && existing.type === 'referenced') {
             this.accesses.delete(normalizedPath);
         }
+        // Store content only for small files
+        const shouldStoreContent = content !== undefined && lineCount <= this.inlineThreshold;
         // Update or create read entry
         this.accesses.set(normalizedPath, {
             path: normalizedPath,
@@ -62,7 +68,12 @@ export class FileAccessTracker {
             timestamp: Date.now(),
             lineCount,
             summary,
+            content: shouldStoreContent ? content : undefined,
+            tokenCount: shouldStoreContent ? this.estimateTokens(content) : undefined,
         });
+        if (shouldStoreContent) {
+            this.enforceMaxContentEntries();
+        }
         this.enforceMaxEntries();
     }
     /**
@@ -184,6 +195,65 @@ export class FileAccessTracker {
             includeTimestamp,
         });
     }
+    /**
+     * Format restoration hints with inline file content (Claude Code style).
+     *
+     * Small files with stored content are inlined up to a token budget.
+     * Large files or files exceeding the budget get reference-only hints.
+     * Each file produces a separate hint message for individual injection.
+     *
+     * Priority order for inlining:
+     * 1. Modified files (most critical context)
+     * 2. Read files, most recent first
+     * 3. Once budget exhausted → remaining become reference-only
+     * 4. Referenced-only files → always reference-only
+     */
+    formatRestorationHintsWithContent(options) {
+        if (this.accesses.size === 0) {
+            return [];
+        }
+        const maxInlineTokens = options?.maxInlineTokens ?? 4000;
+        const allAccesses = this.getAccesses();
+        const hints = [];
+        let usedTokens = 0;
+        // Sort by priority: modified first, then read (most recent first), then referenced
+        const prioritized = [...allAccesses].sort((a, b) => {
+            const typePriority = { modified: 0, read: 1, referenced: 2 };
+            const aPriority = typePriority[a.type];
+            const bPriority = typePriority[b.type];
+            if (aPriority !== bPriority)
+                return aPriority - bPriority;
+            return b.timestamp - a.timestamp; // most recent first within same type
+        });
+        for (const access of prioritized) {
+            // Referenced files are always reference-only (no content was read)
+            if (access.type === 'referenced') {
+                continue; // Skip referenced files — they add noise without value
+            }
+            const canInline = access.content !== undefined &&
+                access.tokenCount !== undefined &&
+                usedTokens + access.tokenCount <= maxInlineTokens;
+            if (canInline) {
+                // Inline: simulate a read_file tool call result
+                // canInline guarantees content and tokenCount are defined
+                const fileContent = access.content;
+                const tokens = access.tokenCount;
+                const text = `Note: ${access.path} was read before the last conversation was compacted.\n` +
+                    `<file_content>\n${fileContent}\n</file_content>`;
+                usedTokens += tokens;
+                hints.push({ path: access.path, type: 'inline', text, tokens });
+            }
+            else {
+                // Reference-only
+                const lineInfo = access.lineCount !== undefined ? ` (${String(access.lineCount)} lines)` : '';
+                const text = `Note: ${access.path}${lineInfo} was read before the last conversation was compacted, ` +
+                    `but the contents are too large to include. Use read_file if you need to access it.`;
+                const tokens = this.estimateTokens(text);
+                hints.push({ path: access.path, type: 'reference', text, tokens });
+            }
+        }
+        return hints;
+    }
     // ==========================================================================
     // Lifecycle Methods
     // ==========================================================================
@@ -202,6 +272,31 @@ export class FileAccessTracker {
     // ==========================================================================
     // Private Helpers
     // ==========================================================================
+    /**
+     * Rough token estimate (4 chars ≈ 1 token). Avoids heavy tiktoken dependency
+     * in the tracker — exact counts aren't critical for budget enforcement.
+     */
+    estimateTokens(text) {
+        if (!text)
+            return 0;
+        return Math.ceil(text.length / 4);
+    }
+    /**
+     * Evict oldest stored content when maxContentEntries is exceeded.
+     * Only drops the `content`/`tokenCount` fields — the access entry itself is preserved.
+     */
+    enforceMaxContentEntries() {
+        const entriesWithContent = Array.from(this.accesses.values())
+            .filter((a) => a.content !== undefined)
+            .sort((a, b) => a.timestamp - b.timestamp); // oldest first
+        while (entriesWithContent.length > this.maxContentEntries) {
+            const oldest = entriesWithContent.shift();
+            if (oldest) {
+                oldest.content = undefined;
+                oldest.tokenCount = undefined;
+            }
+        }
+    }
     normalizePath(filePath) {
         // Resolve to absolute path
         return path.resolve(filePath);

package/dist/context/file-tracking-hook.js

@@ -32,18 +32,23 @@ export function createFileTrackingHook(tracker) {
             case TOOL_NAMES.READ_FILE: {
                 const readInput = input;
                 const readResult = result;
-                const lineCount = readResult.result?.lineCount ?? 0;
-                tracker.trackRead(readInput.file_path, lineCount);
+                const content = readResult.result?.content;
+                // totalLines is set when maxLines/startLine used or content truncated;
+                // linesReturned is the actual slice size; fall back to counting content lines
+                const lineCount = readResult.result?.totalLines ??
+                    readResult.result?.linesReturned ??
+                    (content ? content.split('\n').length : 0);
+                tracker.trackRead(readInput.path, lineCount, undefined, content);
                 break;
             }
             case TOOL_NAMES.WRITE_FILE: {
                 const writeInput = input;
-                tracker.trackModification(writeInput.file_path, 'File written');
+                tracker.trackModification(writeInput.path, 'File written');
                 break;
             }
             case TOOL_NAMES.EDIT: {
                 const editInput = input;
-                tracker.trackModification(editInput.file_path, 'File edited');
+                tracker.trackModification(editInput.filePath, 'File edited');
                 break;
             }
             case TOOL_NAMES.GREP: {

package/dist/context/index.d.ts

@@ -11,7 +11,7 @@
 export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';
 export type { ContextManagerOptions } from './manager.js';
 export { FileAccessTracker } from './file-tracker.js';
-export type { FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, } from './file-tracker.js';
+export type { FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, RestorationHintMessage, } from './file-tracker.js';
 export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';
 export type { ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, CategorizedMessages, SmartCompactOptions, SmartCompactionResult, } from './types.js';
 export { DelegatedResultStore } from './delegated-result-store.js';

package/dist/context/tool-result-delegator.js

@@ -70,6 +70,10 @@ export class ToolResultDelegator {
      * Perform the actual delegation (async path).
      */
     async delegateResult(context, content, tokens, toolConfig) {
+        // If already aborted, skip delegation entirely — return original result
+        if (context.signal?.aborted) {
+            return { result: context.result };
+        }
         // Generate delegation ID
         const id = this.store.generateId();
         this.onEvent?.({
@@ -84,7 +88,7 @@ export class ToolResultDelegator {
             let summary;
             let usedStrategy = strategy;
             if (strategy === 'llm') {
-                const llmSummary = await this.summarizeLLM(content, context.toolName);
+                const llmSummary = await this.summarizeLLM(content, context.toolName, context.signal);
                 if (llmSummary !== null) {
                     summary = llmSummary;
                     usedStrategy = 'llm';
@@ -97,7 +101,7 @@ export class ToolResultDelegator {
             }
             else if (toolConfig.strategy === 'auto') {
                 // Auto: try LLM first, fall back to extractive
-                const llmSummary = await this.summarizeLLM(content, context.toolName);
+                const llmSummary = await this.summarizeLLM(content, context.toolName, context.signal);
                 if (llmSummary !== null) {
                     summary = llmSummary;
                     usedStrategy = 'llm';
@@ -261,8 +265,10 @@ export class ToolResultDelegator {
      * LLM-based summarization using the provider.
      * Returns null if the LLM call fails.
      */
-    async summarizeLLM(content, toolName) {
+    async summarizeLLM(content, toolName, signal) {
         try {
+            if (signal?.aborted)
+                return null;
             const messages = [
                 {
                     role: 'system',
@@ -278,7 +284,10 @@ export class ToolResultDelegator {
                 maxTokens: this.config.summaryMaxTokens,
                 temperature: 0,
                 model: undefined, // Use the provider's default model
+                signal,
             })) {
+                if (signal?.aborted)
+                    break;
                 if (chunk.type === 'text' && chunk.text) {
                     text += chunk.text;
                 }

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export { generateId, sleep, retry, truncate, withRetryGenerator, calculateBackof
 export type { RetryConfig as LLMRetryConfig, WithRetryOptions } from './utils/index.js';
 export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
 export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DELEGATION_CONFIG, } from './context/index.js';
-export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, DelegatedResultStoreStats, ToolResultDelegatorOptions, DelegationConfig, StoredResult, DelegationEvent, } from './context/index.js';
+export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, RestorationHintMessage, DelegatedResultStoreStats, ToolResultDelegatorOptions, DelegationConfig, StoredResult, DelegationEvent, } from './context/index.js';
 export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
 export type { Skill, SkillInvocationResult, SkillInvokeOptions } from './skills/index.js';
 export { JsonSerializer, CompactJsonSerializer, defaultSerializer, MemoryCheckpointer, FileCheckpointer, StateError, StateErrorCode, CURRENT_STATE_VERSION, } from './state/index.js';

package/dist/mcp/client.js

@@ -20,15 +20,17 @@ async function getMCPSDK() {
         return sdkCache;
     try {
         // Dynamic imports to keep SDK optional
-        const [clientModule, stdioModule, httpModule] = await Promise.all([
+        const [clientModule, stdioModule, httpModule, typesModule] = await Promise.all([
             import('@modelcontextprotocol/sdk/client/index.js'),
             import('@modelcontextprotocol/sdk/client/stdio.js'),
             import('@modelcontextprotocol/sdk/client/streamableHttp.js'),
+            import('@modelcontextprotocol/sdk/types.js'),
         ]);
         sdkCache = {
             Client: clientModule.Client,
             StdioClientTransport: stdioModule.StdioClientTransport,
             StreamableHTTPClientTransport: httpModule.StreamableHTTPClientTransport,
+            ToolListChangedNotificationSchema: typesModule.ToolListChangedNotificationSchema,
         };
         // Non-null assertion safe: we just assigned sdkCache above
         return sdkCache;
@@ -112,6 +114,7 @@ export class MCPClient {
                     args: this.config.stdio.args,
                     env: this.config.stdio.env,
                     cwd: this.config.stdio.cwd,
+                    stderr: 'pipe', // Capture stderr to prevent bleeding into host terminal
                 });
             }
             else if (this.config.transport === 'http' && this.config.http) {
@@ -123,7 +126,8 @@ export class MCPClient {
                 version: this.config.clientVersion ?? '1.0.0',
             });
             // Set up notification handler for tools changed
-            this.client.setNotificationHandler('notifications/tools/list_changed', () => {
+            // SDK 1.26+ requires Zod schema instead of string for notification handlers
+            this.client.setNotificationHandler(sdk.ToolListChangedNotificationSchema, () => {
                 this.cachedTools = null; // Invalidate cache
                 this.emit({ type: 'tools_changed', serverName: this.name });
             });

package/dist/providers/claude.js

@@ -74,7 +74,9 @@ export class ClaudeProvider {
             if (thinking) {
                 Object.assign(params, { thinking });
             }
-            const stream = this.client.messages.stream(params);
+            // Pass abort signal to SDK for immediate cancellation
+            const requestOptions = options?.signal ? { signal: options.signal } : undefined;
+            const stream = this.client.messages.stream(params, requestOptions);
             const model = options?.model ?? this.defaultModel;
             let currentToolId = '';
             let currentToolName = '';

package/dist/providers/gemini-native.js

@@ -67,6 +67,10 @@ export class GeminiNativeProvider {
             if (tools.length > 0) {
                 config.tools = [{ functionDeclarations: tools }];
             }
+            // Check abort before starting the request
+            if (options?.signal?.aborted) {
+                throw new Error('Aborted');
+            }
             // Request streaming response
             const streamResponse = await this.client.models.generateContentStream({
                 model,
@@ -82,6 +86,9 @@ export class GeminiNativeProvider {
             let lastUsageMetadata;
             // Process stream chunks
             for await (const chunk of streamResponse) {
+                // Check abort between chunks
+                if (options?.signal?.aborted)
+                    break;
                 const streamChunks = this.processChunk(chunk, currentToolId, currentToolName, toolInputJson, inThinkingBlock);
                 for (const streamChunk of streamChunks) {
                     // Update tracking state

package/dist/providers/openai-compatible.js

@@ -99,6 +99,17 @@ export class OpenAICompatibleProvider {
         let usage;
         try {
             const controller = new AbortController();
+            // Chain user abort signal to our controller
+            if (options?.signal) {
+                if (options.signal.aborted) {
+                    controller.abort();
+                }
+                else {
+                    options.signal.addEventListener('abort', () => {
+                        controller.abort();
+                    }, { once: true });
+                }
+            }
             const timeoutId = setTimeout(() => {
                 controller.abort();
             }, this.timeout);

package/dist/providers/types.d.ts

@@ -147,6 +147,11 @@ export interface ChatOptions {
      * ```
      */
     thinking?: ThinkingConfig;
+    /**
+     * AbortSignal for cancelling the LLM request.
+     * When aborted, the provider should stop streaming and throw/return immediately.
+     */
+    signal?: AbortSignal;
     /**
      * Enable prompt caching for system prompt and tools (Claude-specific)
      *

package/dist/tools/builtin/task.js

@@ -183,6 +183,7 @@ export function createTaskTool(options) {
                     };
                 }
                 const resultPromise = parentAgent.runSubAgent(subAgentName, prompt, {
+                    signal: context?.abortSignal,
                     onEvent: eventHandler,
                 });
                 const result = await Promise.race([resultPromise, timeoutPromise]);

package/dist/tools/builtin/todo.d.ts

@@ -38,6 +38,11 @@ export interface TodoItem {
      * If undefined/null, the task is unassigned
      */
     owner?: string;
+    /**
+     * 1-based task numbers this task is blocked by.
+     * References positions in the todo array.
+     */
+    blockedBy?: number[];
     /**
      * Creation timestamp
      */
@@ -60,6 +65,7 @@ export interface TodoWriteInput {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }>;
 }
 /**
@@ -110,6 +116,7 @@ export declare class TodoStore {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }>): void;
     /**
      * Add a single todo
@@ -120,6 +127,7 @@ export declare class TodoStore {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }): TodoItem;
     /**
      * Update a todo by ID

package/dist/tools/builtin/todo.js

@@ -64,6 +64,7 @@ export class TodoStore {
                 activeForm: todo.activeForm,
                 priority: todo.priority,
                 owner: todo.owner,
+                blockedBy: todo.blockedBy,
                 createdAt: now,
                 updatedAt: now,
             });
@@ -82,6 +83,7 @@ export class TodoStore {
             activeForm: todo.activeForm,
             priority: todo.priority,
             owner: todo.owner,
+            blockedBy: todo.blockedBy,
             createdAt: now,
             updatedAt: now,
         };
@@ -158,7 +160,8 @@ export const todoWriteTool = defineTool({
     name: 'todo_write',
     description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
         'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
-        'Provide the complete list to replace current todos.',
+        'Provide the complete list to replace current todos. ' +
+        'Use blockedBy to declare task dependencies (1-based positions in the array).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -189,6 +192,11 @@ export const todoWriteTool = defineTool({
                             type: 'string',
                             description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned tasks.',
                         },
+                        blockedBy: {
+                            type: 'array',
+                            items: { type: 'number' },
+                            description: 'Array of 1-based task numbers this task depends on (e.g., [3, 4] means blocked by task #3 and #4)',
+                        },
                     },
                     required: ['content', 'status'],
                 },
@@ -268,6 +276,7 @@ export const todoReadTool = defineTool({
                 activeForm: t.activeForm,
                 priority: t.priority,
                 owner: t.owner,
+                blockedBy: t.blockedBy,
             })),
             counts,
             total: todos.length,
@@ -282,7 +291,8 @@ export function createTodoTools(store) {
     const todoWrite = defineTool({
         name: 'todo_write',
         description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
-            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools.',
+            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
+            'Use blockedBy to declare task dependencies (1-based positions in the array).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -297,6 +307,11 @@ export function createTodoTools(store) {
                             activeForm: { type: 'string' },
                             priority: { type: 'number' },
                             owner: { type: 'string' },
+                            blockedBy: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: '1-based task numbers this task depends on',
+                            },
                         },
                         required: ['content', 'status'],
                     },
@@ -368,6 +383,7 @@ export function createTodoTools(store) {
                     activeForm: t.activeForm,
                     priority: t.priority,
                     owner: t.owner,
+                    blockedBy: t.blockedBy,
                 })),
                 counts,
                 total: todos.length,

package/dist/utils/tokenizer.d.ts

@@ -6,7 +6,8 @@
  */
 import type { Message } from '../providers/types.js';
 /**
- * Count tokens in a text string using tiktoken
+ * Count tokens in a text string using tiktoken.
+ * Falls back to chars/4 heuristic for very large or pathologically repetitive strings.
  */
 export declare function countTokens(text: string): number;
 /**

package/dist/utils/tokenizer.js

@@ -14,11 +14,48 @@ function getEncoder() {
     return encoder;
 }
 /**
- * Count tokens in a text string using tiktoken
+ * Maximum text length for tiktoken encoding.
+ * Beyond this, fall back to chars/4 heuristic to avoid pathological BPE performance.
+ */
+const MAX_TIKTOKEN_LENGTH = 10000;
+/**
+ * Minimum length at which we check for low-entropy (repetitive) content.
+ * Repetitive single-character strings like 'a'.repeat(5000) cause O(n²+)
+ * performance in js-tiktoken's BPE merge loop.
+ */
+const ENTROPY_CHECK_THRESHOLD = 2000;
+/**
+ * Check if a string is low-entropy (highly repetitive), which causes
+ * pathological BPE performance in js-tiktoken.
+ *
+ * Samples characters from the string and checks unique character ratio.
+ * A ratio below 0.01 (e.g., 'aaaa...') triggers the heuristic fallback.
+ */
+function isLowEntropy(text) {
+    // Sample up to 200 characters evenly across the string
+    const sampleSize = Math.min(200, text.length);
+    const step = Math.max(1, Math.floor(text.length / sampleSize));
+    const seen = new Set();
+    for (let i = 0; i < text.length && seen.size < 20; i += step) {
+        seen.add(text[i]);
+    }
+    // If unique chars / length ratio is very low, it's repetitive
+    return seen.size / Math.min(sampleSize, text.length) < 0.02;
+}
+/**
+ * Count tokens in a text string using tiktoken.
+ * Falls back to chars/4 heuristic for very large or pathologically repetitive strings.
  */
 export function countTokens(text) {
     if (!text)
         return 0;
+    if (text.length > MAX_TIKTOKEN_LENGTH) {
+        return Math.ceil(text.length / 4);
+    }
+    // Detect low-entropy strings that cause O(n²+) BPE performance
+    if (text.length >= ENTROPY_CHECK_THRESHOLD && isLowEntropy(text)) {
+        return Math.ceil(text.length / 4);
+    }
     return getEncoder().encode(text).length;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -77,10 +77,12 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@google/genai": "^1.38.0",
+    "@google/genai": "^1.42.0",
     "js-tiktoken": "^1.0.21"
   },
   "overrides": {
-    "hono": "^4.11.7"
+    "hono": "^4.11.10",
+    "minimatch": ">=10.2.1",
+    "glob": ">=11.0.0"
   }
 }