@compilr-dev/agents 0.0.1 → 0.2.0

package/dist/agent.d.ts

@@ -3,7 +3,7 @@
  */
 import type { LLMProvider, Message, ChatOptions, StreamChunk } from './providers/types.js';
 import type { Tool, ToolDefinition, ToolRegistry, ToolExecutionResult } from './tools/types.js';
-import type { ContextStats, VerbosityLevel } from './context/types.js';
+import type { ContextStats, VerbosityLevel, SmartCompactionResult } from './context/types.js';
 import type { AgentState, Checkpointer, SessionMetadata } from './state/types.js';
 import type { Anchor, AnchorInput, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions } from './anchors/types.js';
 import type { Guardrail, GuardrailInput, GuardrailResult, GuardrailManagerOptions } from './guardrails/types.js';
@@ -13,6 +13,7 @@ import type { UsageTrackerOptions, UsageStats, BudgetStatus, TokenUsage } from '
 import type { HooksConfig } from './hooks/types.js';
 import { PermissionManager } from './permissions/manager.js';
 import { ContextManager } from './context/manager.js';
+import { FileAccessTracker } from './context/file-tracker.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 /**
@@ -125,6 +126,18 @@ export type AgentEvent = {
 } | {
     type: 'usage_budget_exceeded';
     status: BudgetStatus;
+} | {
+    type: 'suggest';
+    action: string;
+    reason?: string;
+} | {
+    type: 'iteration_limit_reached';
+    iteration: number;
+    maxIterations: number;
+} | {
+    type: 'iteration_limit_extended';
+    newMaxIterations: number;
+    addedIterations: number;
 };
 /**
  * Event handler function type
@@ -189,8 +202,36 @@ export interface AgentConfig {
      * - 'error': Throw MaxIterationsError immediately
      * - 'summarize': Generate a final summary response before throwing
      * - 'continue': Return partial result without throwing (response will be empty)
+     *
+     * Note: If onIterationLimitReached callback is provided, it takes precedence.
      */
     iterationLimitBehavior?: 'error' | 'summarize' | 'continue';
+    /**
+     * Callback invoked when the agent reaches its iteration limit.
+     * Allows the caller to decide whether to continue or stop.
+     *
+     * @param context - Information about the current state
+     * @returns Promise resolving to:
+     *   - `false` to stop the agent gracefully
+     *   - A positive number to continue with that many additional iterations
+     *
+     * If this callback is provided and returns a number, the agent will continue
+     * running with the extended iteration limit. This takes precedence over
+     * iterationLimitBehavior.
+     *
+     * @example
+     * ```typescript
+     * onIterationLimitReached: async ({ iteration, toolCallCount }) => {
+     *   const answer = await askUser(`Agent used ${iteration} iterations. Continue?`);
+     *   return answer === 'yes' ? 50 : false; // Add 50 more or stop
+     * }
+     * ```
+     */
+    onIterationLimitReached?: (context: {
+        iteration: number;
+        maxIterations: number;
+        toolCallCount: number;
+    }) => Promise<number | false>;
     /**
      * Chat options (model, temperature, etc.)
      */
@@ -199,6 +240,12 @@ export interface AgentConfig {
      * Custom tool registry (optional, creates new one if not provided)
      */
     toolRegistry?: ToolRegistry;
+    /**
+     * Default timeout for tool execution in milliseconds (default: 30000 = 30s).
+     * Set to 0 to disable timeout. Only used when toolRegistry is not provided.
+     * Sub-agents inherit this timeout from the parent agent.
+     */
+    toolTimeoutMs?: number;
     /**
      * Context manager for tracking and managing context window usage.
      * If not provided, context management is disabled.
@@ -428,6 +475,31 @@ export interface AgentConfig {
      * ```
      */
     hooks?: HooksConfig;
+    /**
+     * Enable file access tracking for context restoration hints.
+     *
+     * When enabled, the agent tracks which files were read, referenced (grep/glob),
+     * and modified during execution. After context compaction, these hints are
+     * injected to help the LLM understand what files it previously accessed.
+     *
+     * Requires contextManager to be set (hints are injected after compaction).
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   contextManager: new ContextManager({ provider }),
+     *   enableFileTracking: true, // Automatically track file accesses
+     * });
+     *
+     * // After compaction, the agent will inject hints like:
+     * // [Context compacted. Previously accessed files:]
+     * // Read (3 files): file1.ts (100 lines), file2.ts (50 lines)...
+     * ```
+     */
+    enableFileTracking?: boolean;
 }
 /**
  * Options for a single run
@@ -449,6 +521,21 @@ export interface RunOptions {
      * Event handler for this run (in addition to config handler)
      */
     onEvent?: AgentEventHandler;
+    /**
+     * Filter tools for this run.
+     * - If provided, only these tool names will be available
+     * - Reduces token usage by not sending unused tool definitions
+     * - Tools must be registered with the agent
+     *
+     * @example
+     * ```typescript
+     * // Only allow file and search tools for this request
+     * await agent.run(message, {
+     *   toolFilter: ['read_file', 'write_file', 'grep', 'glob'],
+     * });
+     * ```
+     */
+    toolFilter?: string[];
 }
 /**
  * Agent run result
@@ -616,6 +703,7 @@ export declare class Agent {
     private readonly contextManager?;
     private readonly autoContextManagement;
     private readonly onEvent?;
+    private readonly onIterationLimitReached?;
     private readonly checkpointer?;
     private readonly _sessionId;
     private readonly autoCheckpoint;
@@ -655,6 +743,10 @@ export declare class Agent {
      * Hooks manager for lifecycle hooks
      */
     private readonly hooksManager?;
+    /**
+     * File access tracker for context restoration hints
+     */
+    private readonly fileTracker?;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1033,6 +1125,11 @@ export declare class Agent {
      * Get the current conversation history
      */
     getHistory(): Message[];
+    /**
+     * Set the conversation history (for manual compaction/restoration)
+     * Also updates the context manager's token count if configured.
+     */
+    setHistory(messages: Message[]): Promise<this>;
     /**
      * Get the context manager (if configured)
      */
@@ -1045,6 +1142,96 @@ export declare class Agent {
      * Get current verbosity level based on context pressure
      */
     getVerbosityLevel(): VerbosityLevel;
+    /**
+     * Get the file access tracker (if file tracking is enabled)
+     */
+    getFileTracker(): FileAccessTracker | undefined;
+    /**
+     * Format context restoration hints based on tracked file accesses.
+     * Returns empty string if no files have been accessed or file tracking is disabled.
+     */
+    formatRestorationHints(): string;
+    /**
+     * Inject context restoration hints into messages after compaction/summarization.
+     * Modifies messages array in place if hints are available.
+     *
+     * @internal
+     */
+    private injectRestorationHints;
+    /**
+     * Compact the conversation context to reduce token usage.
+     *
+     * This is the recommended way to trigger context compaction externally.
+     * It handles:
+     * 1. Summarizing older messages
+     * 2. Repairing tool use/result pairing (prevents API errors)
+     * 3. Injecting context restoration hints (if file tracking is enabled)
+     * 4. Updating the conversation history
+     *
+     * @param options - Compaction options
+     * @returns Compaction result with statistics
+     *
+     * @example
+     * ```typescript
+     * // Basic compaction
+     * const result = await agent.compact();
+     * console.log(`Reduced from ${result.originalTokens} to ${result.summaryTokens} tokens`);
+     *
+     * // Compaction without restoration hints
+     * await agent.compact({ injectRestorationHints: false });
+     *
+     * // Emergency compaction (more aggressive)
+     * await agent.compact({ emergency: true });
+     * ```
+     */
+    compact(options?: {
+        /**
+         * Inject file restoration hints after compaction.
+         * Only applies if file tracking is enabled.
+         * Default: true (if file tracking is enabled)
+         */
+        injectRestorationHints?: boolean;
+        /**
+         * Use emergency mode (more aggressive summarization).
+         * Default: auto-detect based on context utilization
+         */
+        emergency?: boolean;
+        /**
+         * Target utilization after compaction (0-1).
+         * Default: from context manager config (typically 0.5)
+         */
+        targetUtilization?: number;
+        /**
+         * Use smart category-aware compaction instead of simple summarization.
+         * Smart compaction:
+         * - Preserves system and recent messages completely
+         * - Saves large tool results to files
+         * - Summarizes history with LLM
+         * Default: true
+         */
+        useSmartCompaction?: boolean;
+    }): Promise<{
+        /** Whether compaction was successful */
+        success: boolean;
+        /** Original token count */
+        originalTokens: number;
+        /** Token count after compaction */
+        summaryTokens: number;
+        /** Number of summarization rounds performed */
+        rounds: number;
+        /** Number of messages preserved (not summarized) */
+        messagesPreserved: number;
+        /** Whether restoration hints were injected */
+        restorationHintsInjected: boolean;
+        /** Number of orphaned tool_results removed */
+        toolResultsRepaired: number;
+        /** The generated summary (for debugging/display) */
+        summary: string;
+        /** Files created during smart compaction (tool results saved to files) */
+        filesCreated?: string[];
+        /** Category-specific statistics (only for smart compaction) */
+        categoryStats?: SmartCompactionResult['categoryStats'];
+    }>;
     /**
      * Serialize the current agent state to an AgentState object.
      * This can be used for manual persistence or transferring state.