@compilr-dev/agents 0.0.1

package/dist/agent.d.ts

@@ -0,0 +1,1272 @@
+/**
+ * Agent - The main class for running AI agents with tool use
+ */
+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 { 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';
+import type { ToolPermission, PermissionLevel, PermissionManagerOptions } from './permissions/types.js';
+import type { ProjectMemoryOptions, ProjectMemory } from './memory/types.js';
+import type { UsageTrackerOptions, UsageStats, BudgetStatus, TokenUsage } from './costs/types.js';
+import type { HooksConfig } from './hooks/types.js';
+import { PermissionManager } from './permissions/manager.js';
+import { ContextManager } from './context/manager.js';
+import { AnchorManager } from './anchors/manager.js';
+import { GuardrailManager } from './guardrails/manager.js';
+/**
+ * Event types emitted during agent execution
+ */
+export type AgentEvent = {
+    type: 'iteration_start';
+    iteration: number;
+} | {
+    type: 'llm_start';
+} | {
+    type: 'llm_chunk';
+    chunk: StreamChunk;
+} | {
+    type: 'llm_end';
+    text: string;
+    hasToolUses: boolean;
+} | {
+    type: 'tool_start';
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_end';
+    name: string;
+    result: ToolExecutionResult;
+} | {
+    type: 'iteration_end';
+    iteration: number;
+} | {
+    type: 'done';
+    response: string;
+} | {
+    type: 'context_warning';
+    utilization: number;
+    threshold: number;
+} | {
+    type: 'context_compacted';
+    tokensBefore: number;
+    tokensAfter: number;
+} | {
+    type: 'context_summarized';
+    tokensBefore: number;
+    tokensAfter: number;
+    rounds: number;
+} | {
+    type: 'context_overflow';
+    utilization: number;
+} | {
+    type: 'subagent_start';
+    name: string;
+    task: string;
+} | {
+    type: 'subagent_end';
+    name: string;
+    result: SubAgentResult;
+} | {
+    type: 'tool_loop_warning';
+    toolName: string;
+    consecutiveCalls: number;
+} | {
+    type: 'abort_checkpoint_saved';
+    sessionId: string;
+    reason: 'aborted' | 'error';
+} | {
+    type: 'abort_checkpoint_failed';
+    error: string;
+} | {
+    type: 'custom';
+    name: string;
+    data: unknown;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'anchor_added';
+    anchor: Anchor;
+} | {
+    type: 'anchor_removed';
+    anchorId: string;
+} | {
+    type: 'guardrail_triggered';
+    result: GuardrailResult;
+} | {
+    type: 'guardrail_blocked';
+    result: GuardrailResult;
+    message: string;
+} | {
+    type: 'guardrail_warning';
+    result: GuardrailResult;
+    message: string;
+} | {
+    type: 'permission_granted';
+    toolName: string;
+    level: PermissionLevel;
+} | {
+    type: 'permission_denied';
+    toolName: string;
+    level: PermissionLevel;
+    reason?: string;
+} | {
+    type: 'permission_asked';
+    toolName: string;
+    level: PermissionLevel;
+} | {
+    type: 'usage_recorded';
+    tokens: TokenUsage;
+    model: string;
+} | {
+    type: 'usage_budget_warning';
+    status: BudgetStatus;
+    threshold: number;
+} | {
+    type: 'usage_budget_exceeded';
+    status: BudgetStatus;
+};
+/**
+ * Event handler function type
+ */
+export type AgentEventHandler = (event: AgentEvent) => void;
+/**
+ * Stream writer for emitting custom events during execution.
+ *
+ * Tools and middleware can use this to stream custom events to the client.
+ * Inspired by LangGraph's get_stream_writer() pattern.
+ *
+ * @example
+ * ```typescript
+ * // In a tool executor:
+ * const writer = agent.getStreamWriter();
+ * writer('Processing step 1...', { step: 1 });
+ * // ... do work ...
+ * writer('Processing step 2...', { step: 2 });
+ * ```
+ */
+export type StreamWriter = (data: unknown, metadata?: Record<string, unknown>) => void;
+/**
+ * Custom event configuration
+ */
+export interface CustomEventConfig {
+    /**
+     * Event name (used for filtering/routing)
+     */
+    name: string;
+    /**
+     * Event data payload
+     */
+    data: unknown;
+    /**
+     * Optional metadata (preserved through the event pipeline)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent configuration options
+ */
+export interface AgentConfig {
+    /**
+     * The LLM provider to use
+     */
+    provider: LLMProvider;
+    /**
+     * System prompt for the agent
+     */
+    systemPrompt?: string;
+    /**
+     * Maximum iterations for tool use loops (default: 10)
+     */
+    maxIterations?: number;
+    /**
+     * Maximum consecutive identical tool calls before throwing ToolLoopError (default: 3).
+     * Set to 0 to disable loop detection.
+     */
+    maxConsecutiveToolCalls?: number;
+    /**
+     * Behavior when max iterations is reached (default: 'error').
+     * - 'error': Throw MaxIterationsError immediately
+     * - 'summarize': Generate a final summary response before throwing
+     * - 'continue': Return partial result without throwing (response will be empty)
+     */
+    iterationLimitBehavior?: 'error' | 'summarize' | 'continue';
+    /**
+     * Chat options (model, temperature, etc.)
+     */
+    chatOptions?: ChatOptions;
+    /**
+     * Custom tool registry (optional, creates new one if not provided)
+     */
+    toolRegistry?: ToolRegistry;
+    /**
+     * Context manager for tracking and managing context window usage.
+     * If not provided, context management is disabled.
+     */
+    contextManager?: ContextManager;
+    /**
+     * Enable automatic context management (compaction, summarization).
+     * Requires contextManager to be set. Default: true when contextManager is provided.
+     */
+    autoContextManagement?: boolean;
+    /**
+     * Event handler for monitoring agent execution
+     */
+    onEvent?: AgentEventHandler;
+    /**
+     * Checkpointer for persisting agent state.
+     * If provided, enables checkpoint() and resume() functionality.
+     */
+    checkpointer?: Checkpointer;
+    /**
+     * Session ID for this agent instance.
+     * If not provided, a new session ID is generated automatically.
+     */
+    sessionId?: string;
+    /**
+     * Automatically save state after each run() call.
+     * Requires checkpointer to be set. Default: false.
+     */
+    autoCheckpoint?: boolean;
+    /**
+     * Save a partial checkpoint when run is aborted or encounters an error.
+     * This allows recovery from interrupted runs.
+     * Requires checkpointer to be set. Default: false.
+     *
+     * Inspired by LangGraph issue #5672: Cancellation causes loss of
+     * streamed state not yet persisted as checkpoint.
+     */
+    checkpointOnAbort?: boolean;
+    /**
+     * Anchor manager options for critical information that survives context compaction.
+     *
+     * Anchors are pieces of information that:
+     * - Never get compacted - Survive all context management
+     * - Always re-injected - Present in every LLM call
+     * - Scoped - Session, persistent, or temporary
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   anchors: {
+     *     maxAnchors: 20,
+     *     maxTokens: 2000,
+     *     persistPath: '~/.myapp/anchors.json',
+     *     includeDefaults: true, // Include built-in safety anchors
+     *   }
+     * });
+     * ```
+     */
+    anchors?: AnchorManagerOptions;
+    /**
+     * Guardrail options for pattern-based safety checks.
+     *
+     * Guardrails scan tool inputs before execution and can:
+     * - warn: Log a warning but proceed
+     * - confirm: Require confirmation (via onTriggered handler)
+     * - block: Prevent execution entirely
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   guardrails: {
+     *     enabled: true,
+     *     includeDefaults: true, // Include built-in guardrails
+     *     custom: [
+     *       {
+     *         id: 'no-prod',
+     *         name: 'Production Protection',
+     *         description: 'Block operations on production',
+     *         patterns: [/prod/i],
+     *         action: 'block',
+     *         message: 'Production operations are blocked',
+     *       }
+     *     ],
+     *     onTriggered: async (result, context) => {
+     *       // Return true to proceed, false to block
+     *       return await askUser(result.guardrail.message);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    guardrails?: GuardrailManagerOptions;
+    /**
+     * Permission options for tool-level access control.
+     *
+     * Permissions allow fine-grained control over which tools can execute
+     * and when user approval is required.
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   permissions: {
+     *     defaultLevel: 'always', // Default: allow all tools
+     *     rules: [
+     *       { toolName: 'bash', level: 'once', description: 'Shell commands' },
+     *       { toolName: 'write_file', level: 'session', description: 'File writes' },
+     *       { toolName: 'delete_*', level: 'deny' }, // Wildcard: block all delete tools
+     *     ],
+     *     onPermissionRequest: async (request) => {
+     *       // Return true to allow, false to deny
+     *       return await showConfirmDialog(
+     *         `Allow ${request.toolName}?`,
+     *         request.preview
+     *       );
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    permissions?: PermissionManagerOptions;
+    /**
+     * Pre-loaded project memory to prepend to system prompt.
+     *
+     * Use `Agent.createWithMemory()` to automatically load from files,
+     * or pass a pre-loaded ProjectMemory object.
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Use the factory method (recommended)
+     * const agent = await Agent.createWithMemory({
+     *   provider,
+     *   systemPrompt: 'You are a helpful assistant.',
+     *   projectMemoryOptions: {
+     *     providers: ['claude', 'gemini'],
+     *     includeGeneric: true,
+     *   },
+     *   projectMemoryDir: '/path/to/project',
+     * });
+     *
+     * // Option 2: Pre-load memory manually
+     * const loader = new ProjectMemoryLoader({ providers: 'claude' });
+     * const memory = await loader.load('/path/to/project');
+     *
+     * const agent = new Agent({
+     *   provider,
+     *   systemPrompt: 'You are a helpful assistant.',
+     *   projectMemory: memory, // Pre-loaded memory
+     * });
+     * ```
+     */
+    projectMemory?: ProjectMemory;
+    /**
+     * Usage tracking options for monitoring token usage.
+     *
+     * Note: We track tokens only, not dollar costs. Pricing changes frequently
+     * and providing potentially inaccurate cost information would be misleading.
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   usage: {
+     *     enabled: true,
+     *     budget: {
+     *       maxTotalTokens: 100000,  // 100k token limit
+     *       warningThreshold: 0.8,   // Warn at 80%
+     *     },
+     *   },
+     * });
+     *
+     * // After runs, check usage
+     * console.log(agent.getUsageStats());
+     * console.log(agent.getTotalTokens());
+     *
+     * // Listen for budget events
+     * agent.onEvent((event) => {
+     *   if (event.type === 'usage_budget_warning') {
+     *     console.log('Budget warning!', event.status);
+     *   }
+     * });
+     * ```
+     */
+    usage?: UsageTrackerOptions;
+    /**
+     * Hooks for customizing agent behavior at various lifecycle points.
+     *
+     * Hooks provide extension points without subclassing for:
+     * - Logging and tracing
+     * - Input/output transformation
+     * - Custom validation
+     * - Metrics collection
+     * - Integration with external systems
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   hooks: {
+     *     beforeTool: [
+     *       async (ctx) => {
+     *         console.log(`Tool ${ctx.toolName} starting...`);
+     *       }
+     *     ],
+     *     afterTool: [
+     *       async (ctx) => {
+     *         console.log(`Tool ${ctx.toolName} completed in ${ctx.durationMs}ms`);
+     *         // Optionally modify result
+     *         return { result: ctx.result };
+     *       }
+     *     ],
+     *     beforeLLM: [
+     *       async (ctx) => {
+     *         // Optionally inject or transform messages
+     *         return { messages: ctx.messages };
+     *       }
+     *     ],
+     *     onError: [
+     *       async (ctx) => {
+     *         console.error(`Error in ${ctx.phase}:`, ctx.error);
+     *       }
+     *     ]
+     *   }
+     * });
+     * ```
+     */
+    hooks?: HooksConfig;
+}
+/**
+ * Options for a single run
+ */
+export interface RunOptions {
+    /**
+     * AbortSignal for cancellation
+     */
+    signal?: AbortSignal;
+    /**
+     * Override max iterations for this run
+     */
+    maxIterations?: number;
+    /**
+     * Override chat options for this run
+     */
+    chatOptions?: ChatOptions;
+    /**
+     * Event handler for this run (in addition to config handler)
+     */
+    onEvent?: AgentEventHandler;
+}
+/**
+ * Agent run result
+ */
+export interface AgentRunResult {
+    /**
+     * Final text response from the agent
+     */
+    response: string;
+    /**
+     * All messages in the conversation
+     */
+    messages: Message[];
+    /**
+     * Number of iterations (tool use loops) executed
+     */
+    iterations: number;
+    /**
+     * Tool calls made during execution
+     */
+    toolCalls: Array<{
+        name: string;
+        input: Record<string, unknown>;
+        result: ToolExecutionResult;
+    }>;
+    /**
+     * Whether the run was aborted
+     */
+    aborted: boolean;
+    /**
+     * Context statistics (if context manager is enabled)
+     */
+    contextStats?: ContextStats;
+}
+/**
+ * Configuration for creating a sub-agent
+ */
+export interface SubAgentConfig {
+    /**
+     * Unique name for this sub-agent
+     */
+    name: string;
+    /**
+     * Description of what this sub-agent specializes in.
+     * Used for automatic delegation decisions.
+     */
+    description?: string;
+    /**
+     * System prompt for this sub-agent.
+     * If not provided, inherits from parent.
+     */
+    systemPrompt?: string;
+    /**
+     * Context mode for this sub-agent.
+     * - 'isolated': Fresh context, no parent history (default)
+     * - 'inherited': Receives a summary of parent context
+     * - 'shared': Full access to parent context (not recommended for large contexts)
+     */
+    contextMode?: 'isolated' | 'inherited' | 'shared';
+    /**
+     * Tools available to this sub-agent.
+     * - If not specified, inherits parent's tools
+     * - Can be a subset of parent's tools for safety
+     */
+    tools?: Tool[];
+    /**
+     * Maximum iterations for this sub-agent (default: 5)
+     */
+    maxIterations?: number;
+    /**
+     * Chat options override for this sub-agent
+     */
+    chatOptions?: ChatOptions;
+    /**
+     * Maximum tokens for this sub-agent's context budget.
+     * Default: 25% of parent's context budget.
+     */
+    contextBudget?: number;
+    /**
+     * Automatically dispose the sub-agent after each execution.
+     * This releases memory but requires re-creation for subsequent runs.
+     * Default: false (sub-agent persists for reuse)
+     */
+    autoDispose?: boolean;
+    /**
+     * Maximum size (in bytes) for tool result data returned in SubAgentResult.
+     * Larger results are truncated to prevent memory bloat.
+     * Default: 50KB
+     */
+    maxToolResultSize?: number;
+    /**
+     * Enable state isolation for this sub-agent.
+     *
+     * When true, the sub-agent uses an isolated todo store instead of the
+     * shared default store. This prevents state leakage between parallel
+     * sub-agent executions.
+     *
+     * Automatically enabled when using runParallelSubAgents().
+     *
+     * Inspired by LangGraph issue #6446: Parallel subgraphs with shared
+     * state keys cause InvalidUpdateError.
+     *
+     * Default: false (uses shared store)
+     */
+    stateIsolation?: boolean;
+}
+/**
+ * Result from a sub-agent execution
+ */
+export interface SubAgentResult {
+    /**
+     * Name of the sub-agent that executed
+     */
+    name: string;
+    /**
+     * Final response from the sub-agent
+     */
+    response: string;
+    /**
+     * Whether the execution was successful
+     */
+    success: boolean;
+    /**
+     * Error message if execution failed
+     */
+    error?: string;
+    /**
+     * Number of iterations used
+     */
+    iterations: number;
+    /**
+     * Tool calls made by the sub-agent
+     */
+    toolCalls: AgentRunResult['toolCalls'];
+    /**
+     * Context stats for the sub-agent's execution
+     */
+    contextStats?: ContextStats;
+}
+/**
+ * Agent class - orchestrates LLM interactions with tool use
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   provider: new ClaudeProvider({ apiKey: 'sk-...' }),
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ *
+ * agent.registerTool(readFileTool);
+ * agent.registerTool(writeFileTool);
+ *
+ * const result = await agent.run('Read the contents of package.json');
+ * console.log(result.response);
+ * ```
+ */
+export declare class Agent {
+    private readonly provider;
+    private readonly systemPrompt;
+    private readonly maxIterations;
+    private readonly maxConsecutiveToolCalls;
+    private readonly iterationLimitBehavior;
+    private readonly chatOptions;
+    private readonly toolRegistry;
+    private readonly contextManager?;
+    private readonly autoContextManagement;
+    private readonly onEvent?;
+    private readonly checkpointer?;
+    private readonly _sessionId;
+    private readonly autoCheckpoint;
+    private readonly checkpointOnAbort;
+    private _createdAt;
+    private _totalTokensUsed;
+    private _currentIteration;
+    /**
+     * Conversation history - persists across run() calls
+     */
+    private conversationHistory;
+    /**
+     * Registered sub-agents
+     */
+    private readonly subAgents;
+    /**
+     * Anchor manager for critical information that survives context compaction
+     */
+    private readonly anchorManager?;
+    /**
+     * Guardrail manager for pattern-based safety checks
+     */
+    private readonly guardrailManager?;
+    /**
+     * Permission manager for tool-level access control
+     */
+    private readonly permissionManager?;
+    /**
+     * Loaded project memory (instructions from CLAUDE.md, etc.)
+     */
+    private readonly projectMemory?;
+    /**
+     * Usage tracker for token usage monitoring
+     */
+    private readonly usageTracker?;
+    /**
+     * Hooks manager for lifecycle hooks
+     */
+    private readonly hooksManager?;
+    constructor(config: AgentConfig);
+    /**
+     * Create an agent with project memory loaded from files.
+     *
+     * This factory method automatically discovers and loads project-specific
+     * instructions from files like CLAUDE.md, GEMINI.md, PROJECT.md, etc.
+     *
+     * @param config - Agent configuration
+     * @param memoryOptions - Project memory loading options
+     * @param memoryDir - Directory to search for memory files (defaults to cwd)
+     * @returns Agent instance with loaded project memory
+     *
+     * @example
+     * ```typescript
+     * // Load Claude-specific instructions
+     * const agent = await Agent.createWithMemory(
+     *   {
+     *     provider,
+     *     systemPrompt: 'You are a helpful assistant.',
+     *   },
+     *   { providers: 'claude' },
+     *   '/path/to/project'
+     * );
+     *
+     * // Load instructions for multiple providers
+     * const agent = await Agent.createWithMemory(
+     *   { provider },
+     *   { providers: ['claude', 'gemini'], includeGeneric: true }
+     * );
+     *
+     * // Access loaded memory
+     * const memory = agent.getProjectMemory();
+     * console.log(`Loaded ${memory?.files.length} memory files`);
+     * ```
+     */
+    static createWithMemory(config: Omit<AgentConfig, 'projectMemory'>, memoryOptions?: ProjectMemoryOptions, memoryDir?: string): Promise<Agent>;
+    /**
+     * Get the session ID for this agent instance
+     */
+    get sessionId(): string;
+    /**
+     * Get the loaded project memory (if any).
+     *
+     * Project memory contains instructions loaded from files like
+     * CLAUDE.md, GEMINI.md, PROJECT.md, etc.
+     *
+     * @returns The loaded project memory, or undefined if none was loaded
+     *
+     * @example
+     * ```typescript
+     * const memory = agent.getProjectMemory();
+     * if (memory) {
+     *   console.log(`Loaded ${memory.files.length} instruction files`);
+     *   console.log(`Total tokens: ~${memory.estimatedTokens}`);
+     *   for (const file of memory.files) {
+     *     console.log(`  - ${file.relativePath}`);
+     *   }
+     * }
+     * ```
+     */
+    getProjectMemory(): ProjectMemory | undefined;
+    /**
+     * Check if project memory was loaded
+     */
+    hasProjectMemory(): boolean;
+    /**
+     * Get usage tracking statistics.
+     *
+     * @returns Usage statistics or undefined if usage tracking is not enabled
+     *
+     * @example
+     * ```typescript
+     * const stats = agent.getUsageStats();
+     * if (stats) {
+     *   console.log(`Total calls: ${stats.totalCalls}`);
+     *   console.log(`Total tokens: ${stats.totalTokens}`);
+     *   console.log(`Input tokens: ${stats.totalInputTokens}`);
+     *   console.log(`Output tokens: ${stats.totalOutputTokens}`);
+     * }
+     * ```
+     */
+    getUsageStats(): UsageStats | undefined;
+    /**
+     * Get total tokens used across all LLM calls.
+     */
+    getTotalTokens(): number;
+    /**
+     * Get total input tokens used across all LLM calls.
+     */
+    getTotalInputTokens(): number;
+    /**
+     * Get total output tokens used across all LLM calls.
+     */
+    getTotalOutputTokens(): number;
+    /**
+     * Get budget status.
+     */
+    getBudgetStatus(): BudgetStatus | undefined;
+    /**
+     * Check if budget is exceeded.
+     */
+    isBudgetExceeded(): boolean;
+    /**
+     * Get a human-readable usage summary.
+     */
+    getUsageSummary(): string | undefined;
+    /**
+     * Reset usage tracking data.
+     */
+    resetUsageTracking(): void;
+    /**
+     * Check if usage tracking is enabled.
+     */
+    hasUsageTracking(): boolean;
+    /**
+     * Record usage manually (for custom provider integrations).
+     *
+     * @internal
+     */
+    recordUsage(model: string, provider: string, tokens: TokenUsage): void;
+    /**
+     * Add an anchor (critical information that survives context compaction).
+     *
+     * Anchors are injected into every LLM call and never get compacted.
+     * Use them for information that must not be forgotten.
+     *
+     * @param input - Anchor input
+     * @returns The created anchor, or undefined if anchors are not enabled
+     *
+     * @example
+     * ```typescript
+     * // Session anchor - lives for this session only
+     * agent.addAnchor({
+     *   content: 'This session we implemented: edit tool, grep tool',
+     *   priority: 'critical',
+     *   scope: 'session',
+     * });
+     *
+     * // Safety anchor - persisted across sessions
+     * agent.addAnchor({
+     *   content: 'Never delete files in /important without confirmation',
+     *   priority: 'safety',
+     *   scope: 'persistent',
+     * });
+     *
+     * // Temporary anchor - expires after 1 hour
+     * agent.addAnchor({
+     *   content: 'Currently working on feature X',
+     *   priority: 'info',
+     *   scope: 'temporary',
+     *   expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+     * });
+     * ```
+     */
+    addAnchor(input: AnchorInput): Anchor | undefined;
+    /**
+     * Get an anchor by ID
+     */
+    getAnchor(id: string): Anchor | undefined;
+    /**
+     * Get all anchors, optionally filtered
+     *
+     * @param options - Query options for filtering
+     * @returns Array of anchors
+     *
+     * @example
+     * ```typescript
+     * // Get all anchors
+     * const all = agent.getAnchors();
+     *
+     * // Get only safety anchors
+     * const safety = agent.getAnchors({ priority: 'safety' });
+     *
+     * // Get session anchors with specific tags
+     * const tagged = agent.getAnchors({ scope: 'session', tags: ['files'] });
+     * ```
+     */
+    getAnchors(options?: AnchorQueryOptions): Anchor[];
+    /**
+     * Check if an anchor exists
+     */
+    hasAnchor(id: string): boolean;
+    /**
+     * Remove an anchor by ID
+     *
+     * @returns true if anchor was removed, false if not found
+     */
+    removeAnchor(id: string): boolean;
+    /**
+     * Clear anchors based on criteria
+     *
+     * @param options - Clear options for filtering which anchors to remove
+     * @returns Number of anchors removed
+     *
+     * @example
+     * ```typescript
+     * // Clear all session anchors
+     * agent.clearAnchors({ scope: 'session' });
+     *
+     * // Clear expired temporary anchors
+     * agent.clearAnchors({ expiredOnly: true });
+     *
+     * // Clear anchors with specific tags
+     * agent.clearAnchors({ tags: ['auto'] });
+     * ```
+     */
+    clearAnchors(options?: AnchorClearOptions): number;
+    /**
+     * Get the anchor manager (if configured)
+     */
+    getAnchorManager(): AnchorManager | undefined;
+    /**
+     * Check if anchors are enabled
+     */
+    hasAnchors(): boolean;
+    /**
+     * Add a custom guardrail
+     *
+     * @param input - Guardrail definition
+     * @returns The created guardrail, or undefined if guardrails are not enabled
+     *
+     * @example
+     * ```typescript
+     * agent.addGuardrail({
+     *   id: 'no-delete-important',
+     *   name: 'Important Files Protection',
+     *   description: 'Prevent deletion of important files',
+     *   patterns: [/rm.*important/i, /delete.*important/i],
+     *   action: 'block',
+     *   message: 'Cannot delete files marked as important',
+     *   scope: ['bash'],
+     * });
+     * ```
+     */
+    addGuardrail(input: GuardrailInput): Guardrail | undefined;
+    /**
+     * Get a guardrail by ID
+     */
+    getGuardrail(id: string): Guardrail | undefined;
+    /**
+     * Get all guardrails
+     */
+    getGuardrails(): Guardrail[];
+    /**
+     * Check if a guardrail exists
+     */
+    hasGuardrail(id: string): boolean;
+    /**
+     * Remove a guardrail by ID
+     */
+    removeGuardrail(id: string): boolean;
+    /**
+     * Enable a guardrail by ID
+     */
+    enableGuardrail(id: string): boolean;
+    /**
+     * Disable a guardrail by ID
+     */
+    disableGuardrail(id: string): boolean;
+    /**
+     * Get the guardrail manager (if configured)
+     */
+    getGuardrailManager(): GuardrailManager | undefined;
+    /**
+     * Check if guardrails are enabled
+     */
+    hasGuardrails(): boolean;
+    /**
+     * Add a permission rule for a tool
+     *
+     * @param rule - Permission rule to add
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * agent.addPermission({
+     *   toolName: 'bash',
+     *   level: 'once',
+     *   description: 'Execute shell commands',
+     * });
+     * ```
+     */
+    addPermission(rule: ToolPermission): this;
+    /**
+     * Remove a permission rule by tool name
+     */
+    removePermission(toolName: string): boolean;
+    /**
+     * Get a permission rule by tool name
+     */
+    getPermission(toolName: string): ToolPermission | undefined;
+    /**
+     * Get all permission rules
+     */
+    getPermissions(): ToolPermission[];
+    /**
+     * Set the permission level for a tool
+     *
+     * @param toolName - Tool name or pattern
+     * @param level - Permission level
+     * @param description - Optional description
+     */
+    setPermissionLevel(toolName: string, level: PermissionLevel, description?: string): this;
+    /**
+     * Get the effective permission level for a tool
+     */
+    getPermissionLevel(toolName: string): PermissionLevel;
+    /**
+     * Grant session-level permission for a tool
+     */
+    grantSessionPermission(toolName: string): this;
+    /**
+     * Revoke session-level permission for a tool
+     */
+    revokeSessionPermission(toolName: string): boolean;
+    /**
+     * Clear all session-level permissions
+     */
+    clearSessionPermissions(): this;
+    /**
+     * Get all tools with session-level permission
+     */
+    getSessionPermissions(): string[];
+    /**
+     * Get the permission manager (if configured)
+     */
+    getPermissionManager(): PermissionManager | undefined;
+    /**
+     * Check if permissions are enabled
+     */
+    hasPermissions(): boolean;
+    /**
+     * Emit a custom event that will be streamed to event handlers.
+     *
+     * This allows tools, middleware, and user code to emit custom events
+     * that are streamed alongside built-in agent events.
+     *
+     * Inspired by LangGraph's get_stream_writer() pattern.
+     * Addresses issues like LangGraph #6330 (preserve event metadata).
+     *
+     * @param config - Custom event configuration
+     *
+     * @example
+     * ```typescript
+     * agent.emitCustomEvent({
+     *   name: 'progress',
+     *   data: { step: 1, total: 5, message: 'Processing...' },
+     *   metadata: { toolName: 'myTool' },
+     * });
+     * ```
+     */
+    emitCustomEvent(config: CustomEventConfig): void;
+    /**
+     * Get a stream writer function for emitting custom events.
+     *
+     * This returns a simple function that can be passed to tools or
+     * middleware for streaming progress updates.
+     *
+     * @param eventName - Name for all events emitted by this writer
+     * @returns A stream writer function
+     *
+     * @example
+     * ```typescript
+     * const writer = agent.getStreamWriter('myTool');
+     * writer('Starting...', { phase: 'init' });
+     * writer('Processing...', { phase: 'work', progress: 50 });
+     * writer('Done!', { phase: 'complete' });
+     * ```
+     */
+    getStreamWriter(eventName?: string): StreamWriter;
+    /**
+     * Clear conversation history to start fresh
+     */
+    clearHistory(): this;
+    /**
+     * Get the current conversation history
+     */
+    getHistory(): Message[];
+    /**
+     * Get the context manager (if configured)
+     */
+    getContextManager(): ContextManager | undefined;
+    /**
+     * Get context statistics
+     */
+    getContextStats(): ContextStats | undefined;
+    /**
+     * Get current verbosity level based on context pressure
+     */
+    getVerbosityLevel(): VerbosityLevel;
+    /**
+     * Serialize the current agent state to an AgentState object.
+     * This can be used for manual persistence or transferring state.
+     *
+     * @example
+     * ```typescript
+     * const state = agent.serialize();
+     * const json = JSON.stringify(state);
+     * // Store json somewhere...
+     * ```
+     */
+    serialize(): AgentState;
+    /**
+     * Save the current state using the configured checkpointer.
+     * Throws if no checkpointer is configured.
+     *
+     * @param metadata - Optional metadata overrides
+     * @returns The session ID
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   checkpointer: new FileCheckpointer('~/.myapp/sessions/'),
+     * });
+     *
+     * await agent.run('Hello!');
+     * const sessionId = await agent.checkpoint();
+     * console.log(`Saved as: ${sessionId}`);
+     * ```
+     */
+    checkpoint(metadata?: Partial<SessionMetadata>): Promise<string>;
+    /**
+     * Check if a checkpointer is configured
+     */
+    hasCheckpointer(): boolean;
+    /**
+     * Save a partial checkpoint on abort or error.
+     * This is called internally when checkpointOnAbort is enabled.
+     *
+     * @param reason - Why the checkpoint was saved ('aborted' or 'error')
+     * @param emit - Event emitter function
+     * @returns Promise that resolves when checkpoint is saved
+     */
+    private saveAbortCheckpoint;
+    /**
+     * Resume an agent from a saved session.
+     *
+     * @param sessionId - Session ID to resume
+     * @param options - Resume options (provider and checkpointer required)
+     *
+     * @example
+     * ```typescript
+     * const checkpointer = new FileCheckpointer('~/.myapp/sessions/');
+     *
+     * // Resume a previous session
+     * const agent = await Agent.resume('session_abc123', {
+     *   provider: new ClaudeProvider({ apiKey: '...' }),
+     *   checkpointer,
+     * });
+     *
+     * // Continue the conversation
+     * await agent.run('Continue where we left off...');
+     * ```
+     */
+    static resume(sessionId: string, options: {
+        provider: LLMProvider;
+        checkpointer: Checkpointer;
+        systemPrompt?: string;
+        tools?: Tool[];
+        onEvent?: AgentEventHandler;
+    }): Promise<Agent>;
+    /**
+     * Create an agent from a serialized AgentState object.
+     *
+     * @param state - The serialized agent state
+     * @param options - Options for the new agent
+     *
+     * @example
+     * ```typescript
+     * // Load state from somewhere
+     * const json = await fs.readFile('session.json', 'utf-8');
+     * const state = JSON.parse(json);
+     *
+     * // Create agent from state
+     * const agent = Agent.fromState(state, { provider });
+     * await agent.run('Continue...');
+     * ```
+     */
+    static fromState(state: AgentState, options: {
+        provider: LLMProvider;
+        checkpointer?: Checkpointer;
+        tools?: Tool[];
+        onEvent?: AgentEventHandler;
+        systemPrompt?: string;
+    }): Agent;
+    /**
+     * Create and register a sub-agent with isolated context.
+     *
+     * Sub-agents are specialized agents that handle discrete tasks independently.
+     * They have their own context window and can have different tools/permissions.
+     *
+     * @example
+     * ```typescript
+     * agent.createSubAgent({
+     *   name: 'code-reviewer',
+     *   description: 'Reviews code for security and quality issues',
+     *   systemPrompt: 'You are a code review specialist...',
+     *   tools: [readFileTool], // Restricted tools
+     *   contextMode: 'isolated',
+     * });
+     *
+     * const result = await agent.runSubAgent('code-reviewer', 'Review src/auth.ts');
+     * ```
+     */
+    createSubAgent(config: SubAgentConfig): this;
+    /**
+     * Run a sub-agent with a specific task.
+     *
+     * The sub-agent executes independently with its own context and returns
+     * the result to the parent agent.
+     *
+     * @param name - Name of the registered sub-agent
+     * @param task - Task description for the sub-agent
+     * @param options - Optional run options
+     */
+    runSubAgent(name: string, task: string, options?: RunOptions): Promise<SubAgentResult>;
+    /**
+     * Run multiple sub-agents in parallel with proper state isolation.
+     *
+     * This method ensures that parallel sub-agents don't share mutable state,
+     * preventing race conditions and state leakage between concurrent runs.
+     *
+     * Inspired by LangGraph issue #6446: Parallel subgraphs with shared
+     * state keys cause InvalidUpdateError.
+     *
+     * @param tasks - Array of {name, task} objects to run in parallel
+     * @param options - Optional run options applied to all sub-agents
+     * @returns Array of results in the same order as tasks
+     *
+     * @example
+     * ```typescript
+     * // Run code review and security scan in parallel
+     * const results = await agent.runParallelSubAgents([
+     *   { name: 'code-reviewer', task: 'Review src/auth.ts' },
+     *   { name: 'security-scanner', task: 'Scan src/auth.ts for vulnerabilities' },
+     * ]);
+     * ```
+     */
+    runParallelSubAgents(tasks: Array<{
+        name: string;
+        task: string;
+    }>, options?: RunOptions): Promise<SubAgentResult[]>;
+    /**
+     * Get a registered sub-agent by name
+     */
+    getSubAgent(name: string): Agent | undefined;
+    /**
+     * Get all registered sub-agent names
+     */
+    getSubAgentNames(): string[];
+    /**
+     * Remove a registered sub-agent (alias for disposeSubAgent)
+     */
+    removeSubAgent(name: string): boolean;
+    /**
+     * Dispose a sub-agent and release its resources.
+     *
+     * This clears the sub-agent's:
+     * - Conversation history
+     * - Context manager state
+     * - Tool registry
+     *
+     * After disposal, the sub-agent must be re-created to use again.
+     */
+    disposeSubAgent(name: string): boolean;
+    /**
+     * Dispose all sub-agents and release their resources.
+     *
+     * Useful for cleanup when the parent agent is done or
+     * to free memory during long-running sessions.
+     */
+    disposeAllSubAgents(): void;
+    /**
+     * Generate a concise summary of context for inherited mode
+     */
+    private generateContextSummary;
+    /**
+     * Register a tool for the agent to use
+     */
+    registerTool(tool: Tool): this;
+    /**
+     * Register multiple tools at once
+     */
+    registerTools(tools: Tool[]): this;
+    /**
+     * Get all registered tool definitions
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Run the agent with a user message
+     */
+    run(userMessage: string, options?: RunOptions): Promise<AgentRunResult>;
+    /**
+     * Stream the agent's response with full tool use support
+     *
+     * Yields AgentEvent objects as the agent executes, allowing
+     * real-time monitoring of the agentic loop.
+     */
+    stream(userMessage: string, options?: RunOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Process stream chunks into text, tool uses, and usage data
+     */
+    private processChunks;
+    /**
+     * Generate a summary of messages using the LLM provider.
+     * Used for context summarization when approaching limits.
+     */
+    private generateSummary;
+    /**
+     * Generate a summary when the agent hits max iterations.
+     * This provides a graceful fallback instead of just throwing an error.
+     */
+    private generateIterationLimitSummary;
+}