goatchain 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,3479 @@
+import { CallToolResult, ContentBlock, ImageContent, TextContent, Tool } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/types/common.d.ts
+
+/**
+ * Message content can be a single block or array of blocks
+ */
+type MessageContent = string | ContentBlock | ContentBlock[];
+/**
+ * JSON Schema property definition for nested properties
+ */
+interface JSONSchemaProperty {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+  description?: string;
+  enum?: unknown[];
+  items?: JSONSchemaProperty;
+  properties?: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  default?: unknown;
+  /** Allow additional JSON Schema properties */
+  [key: string]: unknown;
+}
+/**
+ * MCP-compatible Tool input schema.
+ * Per MCP spec, tool inputSchema must have type "object".
+ */
+interface ToolInputSchema {
+  type: 'object';
+  properties?: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  /** Allow additional JSON Schema properties */
+  [key: string]: unknown;
+}
+/**
+ * Tool call request from LLM
+ */
+interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string | Record<string, unknown>;
+  };
+}
+/**
+ * Token usage statistics
+ */
+interface Usage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+//#endregion
+//#region src/model/types.d.ts
+type ProviderId = string;
+type ModelId = string;
+/**
+ * Options for chat completion requests
+ */
+interface ChatOptions {
+  /**
+   * Temperature for response randomness (0-2)
+   */
+  temperature?: number;
+  /**
+   * Maximum tokens to generate
+   */
+  maxTokens?: number;
+  /**
+   * Stop sequences
+   */
+  stop?: string[];
+  /**
+   * Tools available to the model
+   */
+  tools?: OpenAITool[];
+}
+/**
+ * OpenAI-compatible tool format
+ */
+interface OpenAITool {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+/**
+ * Non-streaming chat response
+ */
+interface ChatResponse {
+  message: Message;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+/**
+ * Stream event from model
+ */
+type StreamEvent = {
+  type: 'text_delta';
+  delta: string;
+} | {
+  type: 'tool_call';
+  toolCall: ToolCall;
+} | {
+  type: 'thinking_start';
+} | {
+  type: 'thinking_delta';
+  content: string;
+} | {
+  type: 'thinking_end';
+} | {
+  type: 'usage';
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+} | {
+  type: 'done';
+};
+/**
+ * Unified stream interface that supports both legacy and new API styles.
+ */
+interface ModelStreamFn {
+  /**
+   * Legacy stream method for BaseModel compatibility.
+   */
+  (messages: Message[], options?: ChatOptions): AsyncIterable<StreamEvent | ModelStreamEvent>;
+  /**
+   * New stream method for ModelContract compatibility.
+   */
+  (request: Omit<ModelRequest, 'model'> & {
+    model?: ModelRef;
+  }): AsyncIterable<StreamEvent | ModelStreamEvent>;
+}
+/**
+ * BaseModel-compatible model client interface.
+ *
+ * This matches the shape expected by `BaseModel`/Agent.
+ * It supports both legacy API (messages array) and new ModelContract API (request object).
+ */
+interface ModelClient {
+  readonly modelId: string;
+  /**
+   * Set a new default model ID for subsequent requests.
+   *
+   * This allows switching the model without recreating the entire client.
+   * Only works with models from the same provider.
+   *
+   * @param modelId - New model ID to use
+   *
+   * @example
+   * ```ts
+   * model.setModelId('gpt-4')
+   * // All subsequent requests will use gpt-4
+   * ```
+   */
+  setModelId?: (modelId: string) => void;
+  /**
+   * Legacy invoke method for BaseModel compatibility.
+   * Takes Message array and returns ChatResponse.
+   */
+  invoke: (messages: Message[], options?: ChatOptions) => Promise<ChatResponse>;
+  /**
+   * Stream method supporting both legacy and new API styles.
+   */
+  stream: ModelStreamFn;
+  /**
+   * Run method from ModelContractClient for new API style.
+   * Optional for legacy implementations.
+   */
+  run?: (request: Omit<ModelRequest, 'model'> & {
+    model?: ModelRef;
+  }) => Promise<ModelRunResult>;
+}
+type FeatureId = `${string}@${number}`;
+interface FeatureRequest {
+  required?: boolean;
+  config?: Record<string, unknown>;
+}
+type FeatureRequests = Record<FeatureId, FeatureRequest>;
+interface FeatureGrant {
+  granted: boolean;
+  downgraded?: boolean;
+  reason?: string;
+  effectiveConfig?: Record<string, unknown>;
+}
+type FeatureGrants = Record<FeatureId, FeatureGrant>;
+interface ModelRef {
+  provider: ProviderId;
+  modelId: ModelId;
+}
+interface CoreCapabilities {
+  streaming: boolean;
+  toolCalling: boolean;
+  vision: boolean;
+  audioIn: boolean;
+  audioOut: boolean;
+  jsonSchema: {
+    strict: boolean;
+  };
+  maxContextTokens: number;
+  maxOutputTokens?: number;
+  attachments: {
+    image: boolean;
+    file: boolean;
+    video: boolean;
+  };
+}
+type ModelStopReason = 'final' | 'tool_call' | 'length' | 'error' | 'cancelled';
+type ModelDeltaChunk = {
+  kind: 'text';
+  text: string;
+} | {
+  kind: 'tool_call_delta';
+  callId: string;
+  toolId?: string;
+  argsTextDelta?: string;
+} | {
+  kind: 'thinking_start';
+} | {
+  kind: 'thinking_delta';
+  text: string;
+} | {
+  kind: 'thinking_end';
+} | {
+  kind: 'citation_delta';
+  data: unknown;
+} | {
+  kind: 'annotation';
+  name: string;
+  data: unknown;
+};
+type ModelStreamEvent = {
+  type: 'response_start';
+  requestId: string;
+  model: ModelRef;
+  featureGrants: FeatureGrants;
+} | {
+  type: 'delta';
+  requestId: string;
+  chunk: ModelDeltaChunk;
+} | {
+  type: 'response_end';
+  requestId: string;
+  stopReason: ModelStopReason;
+  usage?: unknown;
+} | {
+  type: 'error';
+  requestId: string;
+  error: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+  };
+};
+interface ModelRequest {
+  requestId?: string;
+  model: ModelRef;
+  /**
+   * Simple text input (used when messages is not provided).
+   * Either `input` or `messages` should be provided.
+   */
+  input?: string;
+  instructions?: string;
+  /**
+   * Opaque metadata for tracing/auditing across systems.
+   * Keep it JSON-serializable; providers may impose size/shape limits.
+   */
+  metadata?: Record<string, string | number | boolean | null>;
+  /**
+   * Model "reasoning" / thinking controls (best-effort; provider-specific).
+   * For OpenAI Responses API this is passed through as `reasoning`.
+   */
+  reasoning?: Record<string, unknown>;
+  /**
+   * Messages in OpenAI format (for multi-turn conversations).
+   * If provided, this takes precedence over `input` for building the conversation.
+   */
+  messages?: Message[];
+  /**
+   * Tools available to the model in OpenAI format.
+   */
+  tools?: OpenAITool[];
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  seed?: number;
+  features?: FeatureRequests;
+  signal?: AbortSignal;
+  stream?: boolean;
+  timeoutMs?: number;
+}
+interface ModelRunResult {
+  requestId: string;
+  model: ModelRef;
+  text: string;
+  stopReason: ModelStopReason;
+  usage?: unknown;
+  featureGrants: FeatureGrants;
+}
+//#endregion
+//#region src/tool/types.d.ts
+/**
+ * Risk level classification for tools.
+ *
+ * Used to determine whether user approval is required before execution:
+ * - 'safe': No risk, read-only operations (e.g., Read, Glob, Grep)
+ * - 'low': Low risk, minimal side effects (e.g., WebSearch, TodoWrite)
+ * - 'medium': Medium risk, reversible changes
+ * - 'high': High risk, file modifications (e.g., Write, Edit)
+ * - 'critical': Critical risk, arbitrary command execution (e.g., Bash)
+ */
+type RiskLevel = 'safe' | 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Request payload for tool approval callback.
+ */
+interface ToolApprovalRequest {
+  /** Name of the tool requesting approval */
+  toolName: string;
+  /** The original tool call from the LLM */
+  toolCall: ToolCall;
+  /** Risk level of the tool */
+  riskLevel: RiskLevel;
+  /** Parsed arguments for the tool */
+  args: Record<string, unknown>;
+}
+/**
+ * Result of tool approval callback.
+ */
+interface ToolApprovalResult {
+  /** Whether the tool execution is approved */
+  approved: boolean;
+  /** Optional reason for rejection (shown in tool result) */
+  reason?: string;
+}
+/**
+ * Indicates tool approval is pending and execution should pause.
+ *
+ * Useful for UIs/servers that cannot keep a tool callback hanging while waiting
+ * for an end-user decision (e.g. HTTP request/response).
+ */
+interface ToolApprovalPending {
+  pending: true;
+  /**
+   * Optional hint shown to the user (or logged) while waiting.
+   */
+  reason?: string;
+}
+/**
+ * Result of tool approval callback.
+ *
+ * Backward compatible: existing callbacks can keep returning ToolApprovalResult.
+ */
+type ToolApprovalOutcome = ToolApprovalResult | ToolApprovalPending;
+type ToolApprovalStrategy = 'high_risk' | 'all';
+/**
+ * Configuration for tool approval behavior.
+ */
+interface ToolApprovalSettings {
+  /**
+   * Which tool calls require approval.
+   * - 'high_risk' (default): only riskLevel 'high' and 'critical'
+   * - 'all': every tool call
+   */
+  strategy?: ToolApprovalStrategy;
+  /**
+   * If true, skip all approval checks (useful for "autoApprove" mode).
+   */
+  autoApprove?: boolean;
+  /**
+   * Pre-supplied approval decisions keyed by tool_call_id.
+   * Useful for "pause → ask user → resume" flows without a live callback.
+   */
+  decisions?: Record<string, ToolApprovalResult>;
+}
+interface ToolFileSystemCapabilities {
+  readFile?: (path: string) => Promise<string>;
+  writeFile?: (path: string, content: string) => Promise<void>;
+}
+/**
+ * Tool-visible usage stats.
+ *
+ * Mirrors the common `Usage` shape and allows optional per-request breakdowns.
+ * This is local-only runtime data (not sent to the LLM).
+ */
+interface ToolRunUsage extends Usage {
+  requestUsageEntries?: unknown[];
+}
+/**
+ * Runtime context passed to tools during execution.
+ *
+ * This is intentionally small and capability-oriented:
+ * - identity: sessionId/agentId
+ * - control: AbortSignal
+ * - capabilities: optional external side-effectful APIs (fetch/fs/etc.)
+ */
+interface ToolExecutionContext<TContext = unknown> {
+  sessionId: string;
+  agentId: string;
+  /**
+   * User-provided runtime context for tool execution.
+   * This is local-only data and is NOT sent to the LLM.
+   *
+   * Put your dependencies/state/cache/logger/userId/db client here.
+   * Prefer providing a strongly-typed `TContext` instead of `any`.
+   */
+  context?: TContext;
+  signal?: AbortSignal;
+  /**
+   * Optional side-effectful capabilities.
+   * If a capability is undefined, tools should treat it as disabled.
+   */
+  capabilities?: {
+    fetch?: typeof fetch;
+    fs?: ToolFileSystemCapabilities;
+  };
+  usage?: ToolRunUsage;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Safe input shape for callers to provide context/capabilities/metadata.
+ * Identity fields are filled by the Agent at runtime.
+ */
+interface ToolExecutionContextInput<TContext = unknown> {
+  context?: TContext;
+  capabilities?: ToolExecutionContext['capabilities'];
+  metadata?: Record<string, unknown>;
+  /**
+   * Optional approval configuration.
+   */
+  approval?: ToolApprovalSettings;
+  /**
+   * Callback for tool approval before execution.
+   *
+   * When provided, this function will be called before executing tools
+   * with riskLevel 'high' or 'critical'. The tool will only execute
+   * if the callback returns { approved: true }.
+   *
+   * If not provided, all tools execute without approval (backward compatible).
+   *
+   * @example
+   * ```ts
+   * onToolApproval: async (req) => {
+   *   console.log(`Tool ${req.toolName} (${req.riskLevel}) wants to execute:`)
+   *   console.log(JSON.stringify(req.args, null, 2))
+   *   const answer = await readline.question('Allow? [y/n]: ')
+   *   return { approved: answer === 'y' }
+   * }
+   * ```
+   */
+  onToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalOutcome>;
+}
+//#endregion
+//#region src/session/base.d.ts
+/**
+ * Abstract base class for a session.
+ *
+ * A session represents a single conversation instance with an agent.
+ * One agent can have multiple concurrent sessions.
+ */
+declare abstract class BaseSession {
+  /**
+   * Unique session identifier
+   */
+  abstract readonly id: string;
+  /**
+   * Agent identifier this session belongs to
+   */
+  abstract readonly agentId: string;
+  /**
+   * Session creation timestamp (ms)
+   */
+  abstract readonly createdAt: number;
+  /**
+   * Custom metadata associated with the session
+   */
+  abstract metadata: Record<string, unknown>;
+  /**
+   * Current session status
+   */
+  abstract status: SessionStatus;
+  /**
+   * Session title (user-defined)
+   */
+  abstract title?: string;
+  /**
+   * Last update timestamp (ms)
+   */
+  abstract updatedAt: number;
+  /**
+   * Last activity timestamp (ms)
+   */
+  abstract lastActiveAt: number;
+  /**
+   * Error message if status is 'error'
+   */
+  abstract errorMessage?: string;
+  /**
+   * Session-level configuration overrides
+   */
+  abstract configOverride?: SessionConfigOverride;
+  /**
+   * Message history
+   */
+  abstract messages: Message[];
+  /**
+   * Number of tool calls made in this session
+   */
+  abstract toolCallCount: number;
+  /**
+   * Token usage statistics
+   */
+  abstract usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  /**
+   * Number of assistant responses
+   */
+  abstract responseCount: number;
+  /**
+   * Average response time in milliseconds
+   */
+  abstract avgResponseTime?: number;
+  /**
+   * Set model override for this session
+   *
+   * @param model - Model configuration to use for this session
+   */
+  setModelOverride(model: ModelConfig): void;
+  /**
+   * Clear model override (use agent's default model)
+   */
+  clearModelOverride(): void;
+  /**
+   * Set system prompt override for this session
+   *
+   * @param systemPrompt - System prompt to use for this session
+   */
+  setSystemPromptOverride(systemPrompt: string): void;
+  /**
+   * Clear system prompt override
+   */
+  clearSystemPromptOverride(): void;
+  /**
+   * Disable specific tools for this session
+   *
+   * @param toolNames - Names of tools to disable
+   */
+  disableTools(toolNames: string[]): void;
+  /**
+   * Re-enable all tools for this session
+   */
+  enableAllTools(): void;
+  /**
+   * Update session status
+   *
+   * @param status - New status
+   * @param errorMessage - Error message (if status is 'error')
+   */
+  setStatus(status: SessionStatus, errorMessage?: string): void;
+  /**
+   * Mark session as active (update lastActiveAt)
+   */
+  markActive(): void;
+  /**
+   * Add a message to the conversation history
+   *
+   * @param message - Message to add
+   */
+  addMessage(message: Message): void;
+  /**
+   * Get preview of the last message (truncated for display)
+   *
+   * @param maxLength - Maximum length of preview
+   * @returns Preview string or undefined if no messages
+   */
+  getLastMessagePreview(maxLength?: number): string | undefined;
+  /**
+   * Add usage statistics
+   *
+   * @param usage - Usage to add
+   * @param usage.promptTokens - Number of prompt tokens
+   * @param usage.completionTokens - Number of completion tokens
+   * @param usage.totalTokens - Total number of tokens
+   */
+  addUsage(usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  }): void;
+  /**
+   * Record a response with its duration
+   *
+   * @param durationMs - Response duration in milliseconds
+   */
+  recordResponse(durationMs: number): void;
+  /**
+   * Increment tool call count
+   */
+  incrementToolCallCount(): void;
+  /**
+   * Create a snapshot of the session for persistence
+   *
+   * @returns Session snapshot
+   */
+  toSnapshot(): SessionSnapshot;
+  /**
+   * Restore session state from a snapshot
+   *
+   * @param snapshot - Session snapshot to restore from
+   */
+  restoreFromSnapshot(snapshot: SessionSnapshot): void;
+}
+//#endregion
+//#region src/session/manager.d.ts
+/**
+ * Abstract base class for session management.
+ *
+ * Handles session lifecycle: creation, retrieval, listing, and destruction.
+ * Implement this class for different storage backends (e.g., Redis, SQLite, in-memory).
+ */
+declare abstract class BaseSessionManager {
+  /**
+   * Create a new session for an agent
+   *
+   * @param agentId - Agent identifier
+   * @param metadata - Optional session metadata
+   * @returns Newly created session
+   */
+  abstract create(agentId: string, metadata?: Record<string, unknown>): Promise<BaseSession>;
+  /**
+   * Get a session by ID
+   *
+   * @param sessionId - Session identifier
+   * @returns Session or undefined if not found
+   */
+  abstract get(sessionId: string): Promise<BaseSession | undefined>;
+  /**
+   * List all sessions for an agent
+   *
+   * @param agentId - Agent identifier
+   * @returns Array of sessions belonging to the agent
+   */
+  abstract list(agentId: string): Promise<BaseSession[]>;
+  /**
+   * Destroy a session
+   *
+   * @param sessionId - Session identifier to destroy
+   */
+  abstract destroy(sessionId: string): Promise<void>;
+}
+//#endregion
+//#region src/agent/middleware.d.ts
+/**
+ * Next function type for immutable middleware chain.
+ *
+ * Accepts the (potentially modified) state and returns the resulting state
+ * after all downstream middleware and core execution have completed.
+ */
+type NextFunction<State> = (state: State) => Promise<State>;
+/**
+ * Middleware function type (immutable pattern)
+ *
+ * Middleware can intercept and transform state at each iteration.
+ * Unlike mutable middleware, this pattern:
+ * - Receives state as input
+ * - Passes (potentially modified) state to next()
+ * - Returns the final state after downstream processing
+ *
+ * This ensures the original state is never mutated, allowing checkpoint
+ * to save original state while LLM receives processed state.
+ *
+ * @example
+ * ```ts
+ * // Logging middleware (pass-through)
+ * const loggingMiddleware: Middleware = async (state, next) => {
+ *   console.log(`Before iteration ${state.iteration}`);
+ *   const result = await next(state); // Pass state unchanged
+ *   console.log(`After iteration ${state.iteration}`);
+ *   return result;
+ * };
+ *
+ * // Transforming middleware (compression)
+ * const compressionMiddleware: Middleware = async (state, next) => {
+ *   const compressedState = { ...state, messages: compress(state.messages) };
+ *   return next(compressedState); // Pass modified state
+ * };
+ * ```
+ */
+type Middleware<State = AgentLoopState> = (state: State, next: NextFunction<State>) => Promise<State>;
+/**
+ * Compose multiple middleware functions into a single function.
+ *
+ * This implements an immutable onion model where each middleware:
+ * - Receives state from the previous middleware (or initial state)
+ * - Can transform state before passing to next()
+ * - Returns the result from downstream processing
+ *
+ * Execution order for each iteration:
+ * ```
+ * outer:before → inner:before → exec (model.stream) → inner:after → outer:after
+ * ```
+ *
+ * State flow:
+ * ```
+ * initialState → outer(transform?) → inner(transform?) → exec → result
+ * ```
+ *
+ * @param middleware - Array of middleware functions
+ * @returns Composed middleware function that can be invoked per iteration
+ *
+ * @example
+ * ```ts
+ * const composed = compose([
+ *   async (state, next) => {
+ *     console.log('outer:before');
+ *     const result = await next(state);
+ *     console.log('outer:after');
+ *     return result;
+ *   },
+ *   async (state, next) => {
+ *     console.log('inner:before');
+ *     // Transform state before passing down
+ *     const modified = { ...state, messages: compress(state.messages) };
+ *     const result = await next(modified);
+ *     console.log('inner:after');
+ *     return result;
+ *   },
+ * ]);
+ *
+ * // Execute with core function
+ * const result = await composed(initialState, async (s) => {
+ *   // Core execution receives transformed state
+ *   await model.stream(s.messages);
+ *   return s;
+ * });
+ * ```
+ */
+declare function compose<State = AgentLoopState>(middleware: Middleware<State>[]): (initialState: State, exec?: NextFunction<State>) => Promise<State>;
+//#endregion
+//#region src/agent/contextCompressionMiddleware.d.ts
+/**
+ * Configuration options for context compression middleware.
+ */
+interface ContextCompressionOptions {
+  /**
+   * Maximum context token limit (e.g., 128000 for GPT-4).
+   */
+  contextLimit: number;
+  /**
+   * Reserved tokens for model output.
+   * Compression triggers when used tokens > (contextLimit - outputLimit).
+   */
+  outputLimit: number;
+  /**
+   * Number of recent conversation turns to always protect (default: 2).
+   * A turn is a user message + assistant response pair.
+   */
+  protectedTurns?: number;
+  /**
+   * Maximum tokens of recent tool outputs to protect (default: 40000).
+   * Tool outputs within this limit won't be cleared.
+   */
+  protectedToolTokens?: number;
+  /**
+   * Threshold for trimming individual tool outputs (default: 20000).
+   * Protected tool outputs exceeding this will be truncated (not cleared).
+   */
+  trimToolOutputThreshold?: number;
+  /**
+   * Whether to generate a summary of cleared content (default: false).
+   * If true, requires model or getModel to be provided.
+   */
+  enableSummary?: boolean;
+  /**
+   * Model to use for generating summaries (only needed if enableSummary is true).
+   */
+  model?: ModelClient;
+  /**
+   * Function to get the model for generating summaries.
+   * Useful when you want to use the agent's model: `getModel: () => agent.model`
+   */
+  getModel?: () => ModelClient;
+  /**
+   * Custom prompt for summary generation.
+   * Supports template placeholders:
+   * - {{existingSummary}}: prior rolling summary (may be empty)
+   * - {{toolOutputs}}: formatted cleared tool outputs
+   */
+  summaryPrompt?: string;
+  /**
+   * State store for persisting compression state.
+   * If provided, compression stats, history, and summaries will be saved.
+   */
+  stateStore?: StateStore;
+  /**
+   * Function to get the state store.
+   * Useful when you want to use the agent's state store: `getStateStore: () => agent.stateStore`
+   */
+  getStateStore?: () => StateStore | undefined;
+  /**
+   * Whether to persist compressed messages to state store (default: false).
+   * When enabled, each compression will save a snapshot file with compressed messages.
+   * This requires stateStore or getStateStore to be provided.
+   *
+   * Each compression saves a separate file: `compression-snapshot-${timestamp}.json`
+   * Useful for debugging or auditing compressed message states.
+   */
+  persistClearedContent?: boolean;
+  /**
+   * Callback when compression is triggered.
+   */
+  onCompressionStart?: (stats: CompressionStats) => void;
+  /**
+   * Callback when compression completes.
+   */
+  onCompressionEnd?: (stats: CompressionStats) => void;
+}
+/**
+ * Statistics about the compression operation.
+ */
+interface CompressionStats {
+  /** Token count before compression */
+  tokensBefore: number;
+  /** Token count after compression */
+  tokensAfter: number;
+  /** Number of tool outputs that were cleared */
+  clearedToolOutputs: number;
+  /** Number of tool outputs that were trimmed (but not cleared) */
+  trimmedToolOutputs: number;
+  /** Whether a summary was generated */
+  summaryGenerated: boolean;
+  /** Timestamp when this compression occurred */
+  timestamp?: number;
+}
+/**
+ * Create a context compression middleware.
+ *
+ * This middleware automatically compresses conversation history when it exceeds
+ * the configured token limit. It follows an immutable pattern - original messages
+ * are never modified. Instead, compressed messages are passed to the LLM while
+ * the original messages remain unchanged (preserved for checkpoint).
+ *
+ * Compression strategy:
+ * 1. Preserve message structure (all messages remain, including tool calls)
+ * 2. Protect recent N turns completely
+ * 3. Protect recent tool outputs up to token limit
+ * 4. Clear old tool outputs with placeholder: "[Old tool result content cleared]"
+ * 5. Optionally generate a summary of cleared content
+ *
+ * @param options - Compression configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({ model, ... })
+ *
+ * // Basic usage - just clear old tool outputs
+ * agent.use(createContextCompressionMiddleware({
+ *   contextLimit: 128000,
+ *   outputLimit: 4096,
+ * }))
+ *
+ * // With summary generation and persistence
+ * agent.use(createContextCompressionMiddleware({
+ *   contextLimit: 128000,
+ *   outputLimit: 4096,
+ *   enableSummary: true,
+ *   getModel: () => agent.model,
+ *   getStateStore: () => agent.stateStore,
+ * }))
+ * ```
+ */
+declare function createContextCompressionMiddleware(options: ContextCompressionOptions): Middleware<AgentLoopState>;
+/**
+ * Options for manual compression.
+ */
+interface ManualCompressionOptions {
+  /**
+   * Session ID for the compression.
+   */
+  sessionId: string;
+  /**
+   * Full messages from the session (including all history).
+   * These should be the complete, uncompressed messages.
+   */
+  fullMessages: Message[];
+  /**
+   * Model to use for generating summary.
+   */
+  model: ModelClient;
+  /**
+   * State store for persisting compression state.
+   */
+  stateStore: StateStore;
+  /**
+   * Custom prompt for summary generation (optional).
+   * If not provided, uses DEFAULT_SUMMARY_PROMPT.
+   */
+  summaryPrompt?: string;
+}
+/**
+ * Result of manual compression.
+ */
+interface ManualCompressionResult {
+  /**
+   * Generated summary.
+   */
+  summary: string;
+  /**
+   * Number of messages processed.
+   */
+  messageCount: number;
+  /**
+   * Number of tool outputs found.
+   */
+  toolOutputCount: number;
+}
+/**
+ * Manually compress a session by generating a summary from full message history.
+ *
+ * This function extracts all tool outputs from the full messages and generates
+ * a new summary based on the complete context. The summary is saved to
+ * CompressionState and will be automatically loaded by the middleware on next run.
+ *
+ * @param options - Manual compression options
+ * @returns Compression result with generated summary
+ *
+ * @example
+ * ```ts
+ * const result = await compressSessionManually({
+ *   sessionId: 'session-123',
+ *   fullMessages: allMessages,
+ *   model: myModel,
+ *   stateStore: myStore,
+ * })
+ * console.log(`Generated summary: ${result.summary}`)
+ * ```
+ */
+declare function compressSessionManually(options: ManualCompressionOptions): Promise<ManualCompressionResult>;
+//#endregion
+//#region src/state/types.d.ts
+/**
+ * State store configuration options.
+ */
+interface StateStoreOptions {
+  /**
+   * When to save checkpoints:
+   * - 'before': Save before each iteration (default)
+   * - 'after': Save after each iteration
+   * - 'both': Save before and after
+   */
+  savePoint?: 'before' | 'after' | 'both';
+  /**
+   * Whether to delete the checkpoint after successful completion.
+   * Default: true
+   */
+  deleteOnComplete?: boolean;
+}
+/**
+ * Predefined state keys for common data types.
+ */
+declare const StateKeys: {
+  /** AgentLoopCheckpoint data */
+  readonly CHECKPOINT: "checkpoint";
+  /** CompressionState data */
+  readonly COMPRESSION: "compression";
+  /** SessionSnapshot data */
+  readonly SESSION: "session";
+  /**
+   * Compressed messages snapshot key pattern.
+   * Use with timestamp: `compression-snapshot-${timestamp}`
+   */
+  readonly COMPRESSION_SNAPSHOT: "compression-snapshot";
+};
+type StateKey = (typeof StateKeys)[keyof typeof StateKeys];
+/**
+ * Compression state for context compression middleware.
+ *
+ * This stores all compression-related data for a session,
+ * allowing the middleware to restore its state after a restart.
+ */
+interface CompressionState {
+  /**
+   * Statistics from the last compression operation.
+   */
+  lastStats?: CompressionStats;
+  /**
+   * History of all compression operations.
+   */
+  history: CompressionStats[];
+  /**
+   * Accumulated summary content from cleared tool outputs.
+   * This can be used when resuming from a checkpoint to provide context.
+   */
+  summary?: string;
+  /**
+   * Last update timestamp (ms).
+   */
+  updatedAt: number;
+}
+//#endregion
+//#region src/state/stateStore.d.ts
+/**
+ * Abstract base class for state storage.
+ *
+ * StateStore provides a session-centric storage abstraction where all data
+ * is organized by sessionId. Each session can have multiple keys storing
+ * different types of data (checkpoint, compression state, session info, etc.).
+ *
+ * Subclasses only need to implement the low-level storage primitives:
+ * - _write: Write data to a path
+ * - _read: Read data from a path
+ * - _delete: Delete data at a path
+ * - _exists: Check if data exists at a path
+ * - _list: List all paths with a given prefix
+ *
+ * The base class provides:
+ * - High-level API for session-based storage (save, load, delete, etc.)
+ * - Convenience methods for checkpoint operations
+ * - JSON serialization/deserialization
+ *
+ * @example
+ * ```typescript
+ * // Using with an agent
+ * const store = new FileStateStore({ dir: './state' })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ *
+ * // Manual state operations
+ * await store.save(sessionId, 'custom-key', { myData: 123 })
+ * const data = await store.load(sessionId, 'custom-key')
+ * ```
+ */
+declare abstract class StateStore {
+  /**
+   * When to save checkpoints during agent execution.
+   */
+  readonly savePoint: 'before' | 'after' | 'both';
+  /**
+   * Whether to delete checkpoint after successful completion.
+   */
+  readonly deleteOnComplete: boolean;
+  constructor(options?: StateStoreOptions);
+  /**
+   * Save data for a session under a specific key.
+   *
+   * @param sessionId - Session identifier
+   * @param key - Data key (e.g., 'checkpoint', 'compression', or custom keys)
+   * @param data - Data to save (will be JSON serialized)
+   */
+  save<T>(sessionId: string, key: string, data: T): Promise<void>;
+  /**
+   * Load data for a session by key.
+   *
+   * @param sessionId - Session identifier
+   * @param key - Data key
+   * @returns The data or undefined if not found
+   */
+  load<T>(sessionId: string, key: string): Promise<T | undefined>;
+  /**
+   * Delete data for a session by key.
+   *
+   * @param sessionId - Session identifier
+   * @param key - Data key
+   */
+  delete(sessionId: string, key: string): Promise<void>;
+  /**
+   * Delete all data for a session.
+   *
+   * @param sessionId - Session identifier
+   */
+  deleteSession(sessionId: string): Promise<void>;
+  /**
+   * List all keys for a session.
+   *
+   * @param sessionId - Session identifier
+   * @returns Array of keys
+   */
+  listKeys(sessionId: string): Promise<string[]>;
+  /**
+   * Check if data exists for a session key.
+   *
+   * @param sessionId - Session identifier
+   * @param key - Data key
+   * @returns True if data exists
+   */
+  exists(sessionId: string, key: string): Promise<boolean>;
+  /**
+   * Save an agent loop checkpoint.
+   *
+   * This is a convenience method that saves the checkpoint under the
+   * predefined CHECKPOINT key with additional metadata.
+   *
+   * @param checkpoint - Checkpoint to save
+   */
+  saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>;
+  /**
+   * Load an agent loop checkpoint by session ID.
+   *
+   * @param sessionId - Session identifier
+   * @returns Checkpoint or undefined if not found
+   */
+  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>;
+  /**
+   * Delete an agent loop checkpoint.
+   *
+   * @param sessionId - Session identifier
+   */
+  deleteCheckpoint(sessionId: string): Promise<void>;
+  /**
+   * List all checkpoints across all sessions.
+   *
+   * @returns Array of checkpoints
+   */
+  listCheckpoints(): Promise<AgentLoopCheckpoint[]>;
+  /**
+   * List all session IDs that have stored data.
+   *
+   * @returns Array of session IDs
+   */
+  listSessions(): Promise<string[]>;
+  /**
+   * Build a storage path from sessionId and key.
+   * Default format: `{sessionId}/{key}`
+   *
+   * Subclasses can override this for different path formats.
+   */
+  protected buildPath(sessionId: string, key: string): string;
+  /**
+   * Build a prefix for listing all data under a session.
+   * Default format: `{sessionId}/`
+   */
+  protected buildPrefix(sessionId: string): string;
+  /**
+   * Extract the key from a full path.
+   */
+  protected extractKey(sessionId: string, path: string): string;
+  /**
+   * Extract the sessionId from a full path.
+   */
+  protected extractSessionId(path: string): string | undefined;
+  /**
+   * Write data to a storage path.
+   *
+   * @param path - Storage path
+   * @param data - Serialized data string
+   */
+  protected abstract _write(path: string, data: string): Promise<void>;
+  /**
+   * Read data from a storage path.
+   *
+   * @param path - Storage path
+   * @returns Data string or undefined if not found
+   */
+  protected abstract _read(path: string): Promise<string | undefined>;
+  /**
+   * Delete data at a storage path.
+   *
+   * @param path - Storage path
+   */
+  protected abstract _delete(path: string): Promise<void>;
+  /**
+   * Check if data exists at a storage path.
+   *
+   * @param path - Storage path
+   * @returns True if data exists
+   */
+  protected abstract _exists(path: string): Promise<boolean>;
+  /**
+   * List all paths with a given prefix.
+   *
+   * @param prefix - Path prefix (empty string for all paths)
+   * @returns Array of full paths
+   */
+  protected abstract _list(prefix: string): Promise<string[]>;
+}
+//#endregion
+//#region src/state/FileStateStore.d.ts
+/**
+ * Options for creating a FileStateStore.
+ */
+interface FileStateStoreOptions extends StateStoreOptions {
+  /**
+   * Directory path for storing state files.
+   */
+  dir: string;
+}
+/**
+ * File-based implementation of StateStore.
+ *
+ * Stores state data as JSON files in a directory structure organized by session:
+ *
+ * ```
+ * <baseDir>/
+ *   <sessionId>/
+ *     checkpoint.json
+ *     compression.json
+ *     session.json
+ *     custom-key.json
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const store = new FileStateStore({
+ *   dir: './state',
+ *   savePoint: 'before',
+ *   deleteOnComplete: true,
+ * })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ * ```
+ */
+declare class FileStateStore extends StateStore {
+  private baseDir;
+  constructor(options: FileStateStoreOptions);
+  protected _write(storagePath: string, data: string): Promise<void>;
+  protected _read(storagePath: string): Promise<string | undefined>;
+  protected _delete(storagePath: string): Promise<void>;
+  protected _exists(storagePath: string): Promise<boolean>;
+  protected _list(prefix: string): Promise<string[]>;
+  /**
+   * Convert storage path to file system path.
+   * Storage path: `{sessionId}/{key}`
+   * File path: `{baseDir}/{sessionId}/{key}.json`
+   */
+  private toFilePath;
+  /**
+   * Ensure a directory exists.
+   */
+  private ensureDir;
+  /**
+   * List all JSON files in a directory.
+   */
+  private listJsonFiles;
+  /**
+   * Get the base directory path.
+   */
+  getBaseDir(): string;
+  /**
+   * Clear all state data from the store.
+   * WARNING: This will delete all files in the base directory.
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/state/InMemoryStateStore.d.ts
+/**
+ * In-memory implementation of StateStore.
+ *
+ * Useful for development, testing, and short-lived applications.
+ * Data is lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStateStore({
+ *   savePoint: 'before',
+ *   deleteOnComplete: true,
+ * })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ * ```
+ */
+declare class InMemoryStateStore extends StateStore {
+  /**
+   * Internal storage: path -> data
+   */
+  private store;
+  constructor(options?: StateStoreOptions);
+  protected _write(path: string, data: string): Promise<void>;
+  protected _read(path: string): Promise<string | undefined>;
+  protected _delete(path: string): Promise<void>;
+  protected _exists(path: string): Promise<boolean>;
+  protected _list(prefix: string): Promise<string[]>;
+  /**
+   * Clear all data from the store.
+   * Useful for testing.
+   */
+  clear(): void;
+  /**
+   * Get statistics about the store.
+   */
+  stats(): {
+    entryCount: number;
+    sessionCount: number;
+  };
+}
+//#endregion
+//#region src/tool/base.d.ts
+/**
+ * Helper to create a text content block for CallToolResult
+ */
+declare function textContent(text: string): CallToolResult;
+/**
+ * Helper to create an error result for CallToolResult
+ */
+declare function errorContent(error: string): CallToolResult;
+/**
+ * Helper to create an image content block for CallToolResult
+ */
+declare function imageContent(data: string, mimeType: string): CallToolResult;
+/**
+ * Abstract base class for tools.
+ *
+ * Tools are capabilities that the agent can invoke during execution.
+ * Implement this class to create custom tools.
+ *
+ * All tool execute() methods must return MCP SDK-compliant CallToolResult:
+ * - content: array of ContentBlock (TextContent, ImageContent, etc.)
+ * - isError: optional boolean to indicate error
+ * - structuredContent: optional structured data object
+ */
+declare abstract class BaseTool {
+  /**
+   * Unique name of the tool (used by LLM to invoke)
+   */
+  abstract readonly name: string;
+  /**
+   * Human-readable description of what the tool does
+   */
+  abstract readonly description: string;
+  /**
+   * JSON Schema defining the tool's input parameters
+   */
+  abstract readonly parameters: ToolInputSchema;
+  /**
+   * Risk level of the tool, used to determine if user approval is required.
+   *
+   * - 'safe': No risk, read-only operations (default)
+   * - 'low': Low risk, minimal side effects
+   * - 'medium': Medium risk, reversible changes
+   * - 'high': High risk, file modifications
+   * - 'critical': Critical risk, arbitrary command execution
+   */
+  readonly riskLevel: RiskLevel;
+  /**
+   * Execute the tool with given arguments
+   *
+   * @param args - Tool arguments matching the parameters schema
+   * @param ctx - Optional runtime context provided by the Agent
+   * @returns Tool execution result conforming to MCP SDK CallToolResult
+   */
+  abstract execute(args: Record<string, unknown>, ctx?: ToolExecutionContext<any>): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tool/builtin/glob.d.ts
+/**
+ * Result of a glob operation
+ */
+interface GlobResult {
+  /** List of matched file paths (sorted by modification time, newest first) */
+  files: string[];
+  /** Total number of matches found */
+  totalMatches: number;
+  /** Whether results were truncated */
+  truncated: boolean;
+}
+/**
+ * Arguments for the Glob tool
+ */
+interface GlobArgs {
+  /** The glob pattern to match files against */
+  pattern: string;
+  /** The directory to search in (defaults to cwd) */
+  path?: string;
+}
+/**
+ * Tool for finding files matching glob patterns.
+ *
+ * This tool provides fast file pattern matching that works with any codebase size,
+ * returning matching file paths sorted by modification time.
+ *
+ * @example
+ * ```typescript
+ * const globTool = new GlobTool()
+ * const result = await globTool.execute({
+ *   pattern: '**\/*.ts',
+ *   path: './src'
+ * })
+ * ```
+ */
+declare class GlobTool extends BaseTool {
+  readonly name = "Glob";
+  readonly description = "Fast file pattern matching tool that works with any codebase size.\n\nUsage notes:\n- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n- Returns matching file paths sorted by modification time (newest first)\n- Use this tool when you need to find files by name patterns\n- You can call multiple tools in a single response for parallel searches\n\nSupported patterns:\n- `*` matches any sequence of characters except path separator\n- `**` matches any sequence of characters including path separator\n- `?` matches any single character\n- `{a,b}` matches either a or b\n- `[abc]` matches any character in brackets";
+  readonly parameters: ToolInputSchema;
+  /** Current working directory for search */
+  private cwd;
+  constructor(options?: {
+    cwd?: string;
+  });
+  /**
+   * Set the current working directory
+   */
+  setCwd(cwd: string): void;
+  /**
+   * Get the current working directory
+   */
+  getCwd(): string;
+  /**
+   * Execute glob pattern matching
+   *
+   * @param args - Glob arguments
+   * @returns MCP-compliant CallToolResult with matching files
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Recursively walk directory and collect matching files
+   */
+  private walkDirectory;
+}
+//#endregion
+//#region src/tool/builtin/grep.d.ts
+/**
+ * Output modes for grep results
+ */
+type GrepOutputMode = 'content' | 'files_with_matches' | 'count';
+/**
+ * Result of a grep operation
+ */
+interface GrepResult {
+  /** Command exit code */
+  exitCode: number | null;
+  /** Backend used for the search */
+  engine?: 'rg' | 'grep';
+  /** Search output */
+  output: string;
+  /** Whether output was truncated */
+  truncated: boolean;
+  /** Whether search timed out */
+  timedOut: boolean;
+  /** Number of matches found (when available) */
+  matchCount?: number;
+}
+/**
+ * Arguments for the Grep tool
+ */
+interface GrepArgs {
+  /** The regular expression pattern to search for */
+  pattern: string;
+  /** File or directory to search in */
+  path?: string;
+  /** Glob pattern to filter files */
+  glob?: string;
+  /** Output mode */
+  output_mode?: GrepOutputMode;
+  /** Lines before match */
+  '-B'?: number;
+  /** Lines after match */
+  '-A'?: number;
+  /** Lines before and after match */
+  '-C'?: number;
+  /** Show line numbers */
+  '-n'?: boolean;
+  /** Case insensitive search */
+  '-i'?: boolean;
+  /** File type to search */
+  type?: string;
+  /** Limit output to first N lines/entries */
+  head_limit?: number;
+  /** Skip first N lines/entries */
+  offset?: number;
+  /** Enable multiline mode */
+  multiline?: boolean;
+}
+/**
+ * Tool for searching files using ripgrep.
+ *
+ * A powerful search tool built on ripgrep that supports regex patterns,
+ * multiple output modes, and various filtering options.
+ *
+ * @example
+ * ```typescript
+ * const grepTool = new GrepTool()
+ * const result = await grepTool.execute({
+ *   pattern: 'function\\s+\\w+',
+ *   path: './src',
+ *   type: 'ts'
+ * })
+ * ```
+ */
+declare class GrepTool extends BaseTool {
+  readonly name = "Grep";
+  readonly description = "A powerful search tool built on ripgrep.\n\nUsage notes:\n- Supports full regex syntax (e.g., \"log.*Error\", \"function\\s+\\w+\")\n- Filter files with glob parameter (e.g., \"*.js\", \"**/*.tsx\") or type parameter (e.g., \"js\", \"py\", \"rust\")\n- Output modes: \"content\" shows matching lines, \"files_with_matches\" shows only file paths (default), \"count\" shows match counts\n- Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n- Multiline matching: By default patterns match within single lines only. For cross-line patterns, use multiline: true";
+  readonly parameters: ToolInputSchema;
+  /** Current working directory for search */
+  private cwd;
+  /** Path to ripgrep binary */
+  private rgPath;
+  constructor(options?: {
+    cwd?: string;
+    rgPath?: string;
+  });
+  /**
+   * Set the current working directory
+   */
+  setCwd(cwd: string): void;
+  /**
+   * Get the current working directory
+   */
+  getCwd(): string;
+  /**
+   * Execute grep search
+   *
+   * @param args - Grep arguments
+   * @returns MCP-compliant CallToolResult with search results
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Build ripgrep command arguments
+   */
+  private buildRgArgs;
+  /**
+   * Run ripgrep command
+   */
+  private runRipgrep;
+  private runSystemGrep;
+}
+//#endregion
+//#region src/tool/builtin/read.d.ts
+/**
+ * Result of a file read operation
+ */
+interface ReadResult {
+  /** File content with line numbers */
+  content: string;
+  /** Total number of lines in file */
+  totalLines: number;
+  /** Number of lines returned */
+  linesReturned: number;
+  /** Starting line number (1-based) */
+  startLine: number;
+  /** Whether any lines were truncated */
+  truncated: boolean;
+  /** File size in bytes */
+  fileSize: number;
+  /** Whether this is a binary/image file */
+  isBinary: boolean;
+  /** MIME type if detected */
+  mimeType?: string;
+}
+/**
+ * Arguments for the Read tool
+ */
+interface ReadArgs {
+  /** The absolute path to the file to read */
+  file_path: string;
+  /** The line number to start reading from (1-based) */
+  offset?: number;
+  /** The number of lines to read */
+  limit?: number;
+}
+/**
+ * Tool for reading files from the filesystem.
+ *
+ * This tool reads files with line number formatting, supporting
+ * offset/limit for large files and detecting binary content.
+ *
+ * @example
+ * ```typescript
+ * const readTool = new ReadTool()
+ * const result = await readTool.execute({
+ *   file_path: '/path/to/file.ts',
+ *   offset: 100,
+ *   limit: 50
+ * })
+ * ```
+ *
+ * @example Restrict reads to a specific directory
+ * ```typescript
+ * const readTool = new ReadTool({
+ *   cwd: '/app/output',
+ *   restrictToDirectory: true
+ * })
+ * // All paths will be resolved relative to /app/output
+ * // Absolute paths and path traversal (../) will be blocked
+ * ```
+ */
+declare class ReadTool extends BaseTool {
+  readonly name = "Read";
+  /** Current working directory for resolving relative paths */
+  private _cwd;
+  /** Allowed directory for file operations (if set, restricts reads to this directory) */
+  private _allowedDirectory?;
+  constructor(options?: {
+    cwd?: string;
+    /** If set, restricts all file reads to this directory. Paths outside will be rejected. */
+    allowedDirectory?: string;
+  });
+  /**
+   * Dynamic description that includes allowed directory info if configured
+   */
+  get description(): string;
+  /**
+   * Dynamic parameters that include allowed directory info if configured
+   */
+  get parameters(): ToolInputSchema;
+  /**
+   * Set the current working directory
+   */
+  setCwd(cwd: string): void;
+  /**
+   * Get the current working directory
+   */
+  getCwd(): string;
+  /**
+   * Set the allowed directory for file operations
+   */
+  setAllowedDirectory(dir: string | undefined): void;
+  /**
+   * Get the allowed directory for file operations
+   */
+  getAllowedDirectory(): string | undefined;
+  /**
+   * Execute file read
+   *
+   * @param args - Read arguments
+   * @returns MCP-compliant CallToolResult with file content
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Handle binary file (images, PDFs, etc.)
+   */
+  private handleBinaryFile;
+  /**
+   * Handle Jupyter notebook file
+   */
+  private handleJupyterNotebook;
+  /**
+   * Handle text file
+   */
+  private handleTextFile;
+  /**
+   * Format output with line numbers and apply offset/limit
+   */
+  private formatOutput;
+  /**
+   * Format file size for display
+   */
+  private formatSize;
+}
+//#endregion
+//#region src/tool/builtin/edit.d.ts
+/**
+ * Result of an edit operation
+ */
+interface EditResult {
+  /** Whether the edit was successful */
+  success: boolean;
+  /** Number of replacements made */
+  replacements: number;
+  /** File path that was edited */
+  filePath: string;
+  /** Brief description of the edit */
+  message: string;
+}
+/**
+ * Arguments for the Edit tool
+ */
+interface EditArgs {
+  /** The absolute path to the file to modify */
+  file_path: string;
+  /** The text to replace */
+  old_string: string;
+  /** The text to replace it with */
+  new_string: string;
+  /** Replace all occurrences (default false) */
+  replace_all?: boolean;
+}
+/**
+ * Tool for performing exact string replacements in files.
+ *
+ * This tool finds and replaces text in files with careful handling
+ * of unique matches and the option to replace all occurrences.
+ *
+ * @example
+ * ```typescript
+ * const editTool = new EditTool()
+ * const result = await editTool.execute({
+ *   file_path: '/path/to/file.ts',
+ *   old_string: 'const foo = 1',
+ *   new_string: 'const foo = 2'
+ * })
+ * ```
+ */
+declare class EditTool extends BaseTool {
+  readonly name = "Edit";
+  readonly riskLevel: "high";
+  readonly description = "Performs exact string replacements in files.\n\nUsage notes:\n- When editing, preserve the exact indentation (tabs/spaces) from the original file\n- The edit will FAIL if old_string is not unique in the file unless replace_all is true\n- Use replace_all for replacing/renaming strings across the entire file\n- old_string and new_string must be different\n- ALWAYS prefer editing existing files over creating new ones";
+  readonly parameters: ToolInputSchema;
+  /** Current working directory for resolving relative paths */
+  private cwd;
+  constructor(options?: {
+    cwd?: string;
+  });
+  /**
+   * Set the current working directory
+   */
+  setCwd(cwd: string): void;
+  /**
+   * Get the current working directory
+   */
+  getCwd(): string;
+  /**
+   * Execute file edit
+   *
+   * @param args - Edit arguments
+   * @returns MCP-compliant CallToolResult with edit details
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Count occurrences of a substring in a string
+   */
+  private countOccurrences;
+  /**
+   * Truncate string for error messages
+   */
+  private truncateForError;
+}
+//#endregion
+//#region src/tool/builtin/write.d.ts
+/**
+ * Result of a write operation
+ */
+interface WriteResult {
+  /** Whether the write was successful */
+  success: boolean;
+  /** File path that was written */
+  filePath: string;
+  /** Number of bytes written */
+  bytesWritten: number;
+  /** Whether an existing file was overwritten */
+  overwritten: boolean;
+  /** Brief description of the operation */
+  message: string;
+}
+/**
+ * Arguments for the Write tool
+ */
+interface WriteArgs {
+  /** The absolute path to the file to write */
+  file_path: string;
+  /** The content to write to the file */
+  content: string;
+}
+/**
+ * Tool for writing files to the filesystem.
+ *
+ * This tool creates or overwrites files with the specified content,
+ * automatically creating parent directories if needed.
+ *
+ * @example
+ * ```typescript
+ * const writeTool = new WriteTool()
+ * const result = await writeTool.execute({
+ *   file_path: '/path/to/file.ts',
+ *   content: 'export const foo = 1'
+ * })
+ * ```
+ *
+ * @example Restrict writes to a specific directory
+ * ```typescript
+ * const writeTool = new WriteTool({
+ *   cwd: '/app/output',
+ *   restrictToDirectory: true
+ * })
+ * // All paths will be resolved relative to /app/output
+ * // Absolute paths and path traversal (../) will be blocked
+ * ```
+ */
+declare class WriteTool extends BaseTool {
+  readonly name = "Write";
+  readonly riskLevel: "high";
+  /** Current working directory for resolving relative paths */
+  private _cwd;
+  /** Allowed directory for file operations (if set, restricts writes to this directory) */
+  private _allowedDirectory?;
+  constructor(options?: {
+    cwd?: string;
+    /** If set, restricts all file writes to this directory. Paths outside will be rejected. */
+    allowedDirectory?: string;
+  });
+  /**
+   * Dynamic description that includes allowed directory info if configured
+   */
+  get description(): string;
+  /**
+   * Dynamic parameters that include allowed directory info if configured
+   */
+  get parameters(): ToolInputSchema;
+  /**
+   * Set the current working directory
+   */
+  setCwd(cwd: string): void;
+  /**
+   * Get the current working directory
+   */
+  getCwd(): string;
+  /**
+   * Set the allowed directory for file operations
+   */
+  setAllowedDirectory(dir: string | undefined): void;
+  /**
+   * Get the allowed directory for file operations
+   */
+  getAllowedDirectory(): string | undefined;
+  /**
+   * Execute file write
+   *
+   * @param args - Write arguments
+   * @returns MCP-compliant CallToolResult with write details
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Format file size for display
+   */
+  private formatSize;
+}
+//#endregion
+//#region src/tool/builtin/webSearch.d.ts
+/**
+ * A single search result item
+ */
+interface SearchResultItem {
+  /** Result title */
+  title: string;
+  /** Result URL */
+  link: string;
+  /** Result snippet/description */
+  snippet: string;
+  /** Position in search results */
+  position: number;
+}
+/**
+ * Result of a web search operation
+ */
+interface WebSearchResult {
+  /** Whether the search was successful */
+  success: boolean;
+  /** The search query used */
+  query: string;
+  /** List of search results */
+  results: SearchResultItem[];
+  /** Total number of results found */
+  totalResults: number;
+  /** Formatted markdown content with sources */
+  markdown: string;
+  /** Error message if search failed */
+  error?: string;
+}
+/**
+ * Arguments for the WebSearch tool
+ */
+interface WebSearchArgs {
+  /** The search query to use */
+  query: string;
+}
+/**
+ * Tool for searching the web using Serper API.
+ *
+ * This tool allows the agent to search the web and use the results
+ * to inform responses with up-to-date information.
+ *
+ * @example
+ * ```typescript
+ * const webSearchTool = new WebSearchTool({ apiKey: 'your-serper-api-key' })
+ * const result = await webSearchTool.execute({
+ *   query: 'latest TypeScript features 2025'
+ * })
+ * ```
+ */
+declare class WebSearchTool extends BaseTool {
+  readonly name = "WebSearch";
+  readonly description = "Allows the agent to search the web and use the results to inform responses.\n\nUsage notes:\n- Provides up-to-date information for current events and recent data\n- Returns search results with titles, links, and snippets\n- Use this tool for accessing information beyond the knowledge cutoff\n- After answering, include a \"Sources:\" section with relevant URLs as markdown hyperlinks";
+  readonly parameters: ToolInputSchema;
+  /** Serper API key */
+  private apiKey;
+  /** Serper API endpoint */
+  private apiEndpoint;
+  /** Number of results to return */
+  private numResults;
+  constructor(options?: {
+    apiKey?: string;
+    apiEndpoint?: string;
+    numResults?: number;
+  });
+  /**
+   * Set API key
+   */
+  setApiKey(apiKey: string): void;
+  /**
+   * Execute web search
+   *
+   * @param args - WebSearch arguments
+   * @returns MCP-compliant CallToolResult with search results
+   */
+  execute(args: Record<string, unknown>): Promise<CallToolResult>;
+  /**
+   * Validate and parse arguments
+   */
+  private validateArgs;
+  /**
+   * Format search results as markdown
+   */
+  private formatMarkdown;
+}
+//#endregion
+//#region src/tool/registry.d.ts
+/**
+ * Registry for managing tools.
+ *
+ * Provides methods to register, unregister, and look up tools,
+ * as well as convert to OpenAI-compatible format.
+ */
+declare class ToolRegistry {
+  private tools;
+  /**
+   * Register a tool
+   *
+   * @param tool - Tool to register
+   * @throws Error if tool with same name already exists
+   */
+  register(tool: BaseTool): void;
+  /**
+   * Unregister a tool by name
+   *
+   * @param name - Name of tool to remove
+   * @returns true if tool was found and removed
+   */
+  unregister(name: string): boolean;
+  /**
+   * Get a tool by name
+   *
+   * @param name - Tool name
+   * @returns Tool instance or undefined if not found
+   */
+  get(name: string): BaseTool | undefined;
+  /**
+   * List all registered tools
+   *
+   * @returns Array of all tools
+   */
+  list(): BaseTool[];
+  /**
+   * Check if a tool is registered
+   *
+   * @param name - Tool name
+   * @returns true if tool exists
+   */
+  has(name: string): boolean;
+  /**
+   * Get count of registered tools
+   */
+  get size(): number;
+  /**
+   * Convert all tools to OpenAI-compatible format
+   *
+   * @returns Array of tools in OpenAI function calling format
+   */
+  toOpenAIFormat(): OpenAITool[];
+}
+//#endregion
+//#region src/agent/types.d.ts
+/**
+ * Tool call with execution result
+ */
+interface ToolCallWithResult {
+  /**
+   * Original tool call from the LLM
+   */
+  toolCall: ToolCall;
+  /**
+   * Execution result (undefined if not yet executed)
+   */
+  result?: unknown;
+  /**
+   * Whether the execution resulted in an error
+   */
+  isError?: boolean;
+}
+/**
+ * Agent Loop State - the runtime state that flows through the agent loop.
+ *
+ * This is the core state object that gets passed between loop iterations,
+ * hooks, and middlewares. It contains everything needed to:
+ * - Continue the conversation
+ * - Execute pending tool calls
+ * - Track progress and prevent infinite loops
+ * - Accumulate the final response
+ */
+interface AgentLoopState {
+  /**
+   * Session ID for this execution
+   */
+  sessionId: string;
+  /**
+   * Agent ID
+   */
+  agentId: string;
+  /**
+   * Full message history including system, user, assistant, and tool messages.
+   * This is the primary state that gets updated each iteration.
+   */
+  messages: Message[];
+  /**
+   * Current loop iteration (0-indexed).
+   * Used for max iterations check and debugging.
+   */
+  iteration: number;
+  /**
+   * Pending tool calls from the current LLM response.
+   * These need to be executed before the next iteration.
+   */
+  pendingToolCalls: ToolCallWithResult[];
+  /**
+   * Text response accumulated so far in the current iteration.
+   */
+  currentResponse: string;
+  /**
+   * Thinking/reasoning content from the current iteration (if model supports it).
+   */
+  currentThinking?: string;
+  /**
+   * Whether the loop should continue.
+   * Set to false when:
+   * - LLM returns a final response without tool calls
+   * - Max iterations reached
+   * - An error occurs (depending on error handling strategy)
+   * - Explicitly stopped by a hook
+   */
+  shouldContinue: boolean;
+  /**
+   * Stop reason for debugging/logging.
+   */
+  stopReason?: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'hook_stopped';
+  /**
+   * The stop reason reported by the most recent model call (if available).
+   *
+   * Useful for debugging truncated outputs (e.g. `length`) vs normal completion (`final`).
+   */
+  lastModelStopReason?: ModelStopReason;
+  /**
+   * Cumulative token usage across all iterations.
+   */
+  usage: Usage;
+  /**
+   * Last error encountered (if any).
+   */
+  error?: Error;
+  /**
+   * Custom metadata for hooks and middlewares.
+   * Use this to pass data between different stages of the loop.
+   */
+  metadata: Record<string, unknown>;
+}
+/**
+ * Create initial AgentLoopState from AgentInput
+ */
+declare function createInitialLoopState(input: AgentInput<any>, agentId: string, systemPrompt: string): AgentLoopState;
+/**
+ * Input for agent execution that starts from an existing message history.
+ *
+ * Unlike {@link AgentInput}, this does not append a new user message.
+ * This is useful for "handoff" style orchestration where a different agent
+ * should continue from the same conversation state (with a new system prompt).
+ */
+interface AgentInputFromMessages<TContext = unknown> extends Omit<AgentInput<TContext>, 'input' | 'messages'> {
+  /**
+   * Full conversation history to continue from (system messages will be ignored).
+   */
+  messages: Message[];
+}
+/**
+ * Create initial AgentLoopState from an existing message history (no new user message appended).
+ */
+declare function createInitialLoopStateFromMessages(input: AgentInputFromMessages<any>, agentId: string, systemPrompt: string): AgentLoopState;
+/**
+ * Options for creating an Agent
+ */
+interface AgentOptions {
+  /**
+   * Unique identifier for the agent (auto-generated if not provided)
+   */
+  id?: string;
+  /**
+   * Human-readable name for the agent
+   */
+  name: string;
+  /**
+   * System prompt that defines the agent's behavior
+   */
+  systemPrompt: string;
+  /**
+   * LLM model to use
+   */
+  model: ModelClient;
+  /**
+   * Tool registry (optional)
+   */
+  tools?: ToolRegistry;
+  /**
+   * State storage backend (optional).
+   *
+   * When provided, the agent will automatically save checkpoints during execution,
+   * allowing interrupted executions to be resumed. The store can also be used
+   * by middlewares (like contextCompressionMiddleware) to persist their state.
+   *
+   * The state store contains its own configuration for when to save
+   * (savePoint) and whether to delete on completion (deleteOnComplete).
+   */
+  stateStore?: StateStore;
+  /**
+   * Session manager (optional)
+   */
+  sessionManager?: BaseSessionManager;
+}
+/**
+ * Input for agent execution
+ */
+interface AgentInput<TContext = unknown> {
+  /**
+   * Session ID for this execution
+   */
+  sessionId: string;
+  /**
+   * User input message
+   */
+  input: MessageContent;
+  /**
+   * Optional conversation history (caller manages this)
+   */
+  messages?: Message[];
+  /**
+   * Optional model override for this execution.
+   * If provided, this model will be used instead of the agent's default model.
+   *
+   * @example
+   * ```ts
+   * await agent.stream({
+   *   sessionId: 'xxx',
+   *   input: 'hello',
+   *   model: { provider: 'openai', modelId: 'gpt-4' },  // Use gpt-4 for this request only
+   * })
+   * ```
+   */
+  model?: ModelRef;
+  /**
+   * AbortSignal for cancellation support.
+   * When aborted, the agent loop will throw AgentAbortError.
+   */
+  signal?: AbortSignal;
+  /**
+   * Maximum number of loop iterations (default: 10).
+   * Prevents infinite loops when tools keep being called.
+   */
+  maxIterations?: number;
+  /**
+   * Optional tool execution context input.
+   *
+   * Use this to inject capabilities (e.g. fetch/fs) and metadata.
+   * Identity fields (sessionId/agentId) are filled by the Agent.
+   */
+  toolContext?: ToolExecutionContextInput<TContext>;
+  /**
+   * Optional model request parameters (temperature, maxTokens, etc.).
+   * These will be saved in checkpoints for resumption.
+   */
+  requestParams?: CheckpointRequestParams;
+}
+/**
+ * Input for agent execution that resumes from a saved checkpoint.
+ *
+ * Use this to resume interrupted executions from the exact state
+ * where they were saved.
+ */
+interface AgentInputFromCheckpoint<TContext = unknown> {
+  /**
+   * Checkpoint to resume from
+   */
+  checkpoint: AgentLoopCheckpoint;
+  /**
+   * Optional model override for this execution
+   */
+  model?: ModelRef;
+  /**
+   * AbortSignal for cancellation support
+   */
+  signal?: AbortSignal;
+  /**
+   * Maximum number of loop iterations (default: 10)
+   */
+  maxIterations?: number;
+  /**
+   * Optional tool execution context input
+   */
+  toolContext?: ToolExecutionContextInput<TContext>;
+  /**
+   * Optional model request parameters override.
+   * If not provided, uses the params from the checkpoint.
+   */
+  requestParams?: CheckpointRequestParams;
+}
+//#endregion
+//#region src/types/message.d.ts
+/**
+ * Role types for messages
+ */
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * System message for setting agent behavior
+ */
+interface SystemMessage {
+  role: 'system';
+  content: MessageContent;
+  tools?: Tool[];
+}
+/**
+ * User input message
+ */
+interface UserMessage {
+  role: 'user';
+  content: MessageContent;
+  name?: string;
+}
+/**
+ * Assistant response message
+ */
+interface AssistantMessage {
+  role: 'assistant';
+  content: MessageContent;
+  reasoning_content?: string;
+  tool_calls?: ToolCall[];
+}
+/**
+ * Tool execution result message
+ */
+interface ToolMessage {
+  role: 'tool';
+  content: MessageContent;
+  tool_call_id: string;
+  name?: string;
+  isError?: boolean;
+}
+/**
+ * Union type for all message types
+ */
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+//#endregion
+//#region src/types/snapshot.d.ts
+/**
+ * Model configuration for snapshots (serializable)
+ */
+interface ModelConfig {
+  /**
+   * Model identifier (e.g., "gpt-4o", "claude-3-opus")
+   */
+  modelId: string;
+  /**
+   * Provider name (e.g., "openai", "anthropic")
+   */
+  provider?: string;
+  /**
+   * Model-specific configuration
+   */
+  config?: Record<string, unknown>;
+}
+/**
+ * Default chat options that can be configured at agent level
+ */
+interface DefaultChatOptions {
+  /**
+   * Temperature for response randomness (0-2)
+   */
+  temperature?: number;
+  /**
+   * Maximum tokens to generate
+   */
+  maxTokens?: number;
+  /**
+   * Stop sequences
+   */
+  stop?: string[];
+}
+/**
+ * Agent configuration (mutable settings)
+ */
+interface AgentConfig {
+  /**
+   * System prompt that defines the agent's behavior
+   */
+  systemPrompt: string;
+  /**
+   * Current model configuration
+   */
+  model: ModelConfig;
+  /**
+   * List of registered tool names
+   */
+  tools: string[];
+  /**
+   * Default chat parameters
+   */
+  defaultChatOptions?: DefaultChatOptions;
+}
+/**
+ * Agent runtime statistics
+ */
+interface AgentStats {
+  /**
+   * Last update timestamp (ms)
+   */
+  updatedAt: number;
+  /**
+   * Total number of sessions ever created
+   */
+  totalSessions: number;
+  /**
+   * Number of currently active sessions
+   */
+  activeSessions: number;
+  /**
+   * Cumulative token usage across all sessions
+   */
+  totalUsage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+/**
+ * Complete Agent snapshot for serialization/persistence
+ */
+interface AgentSnapshot {
+  /**
+   * Unique agent identifier
+   */
+  id: string;
+  /**
+   * Human-readable name
+   */
+  name: string;
+  /**
+   * Creation timestamp (ms)
+   */
+  createdAt: number;
+  /**
+   * Agent configuration
+   */
+  config: AgentConfig;
+  /**
+   * Runtime statistics
+   */
+  stats: AgentStats;
+  /**
+   * User-defined metadata
+   */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Session status
+ */
+type SessionStatus = 'active' | 'paused' | 'completed' | 'error' | 'archived';
+/**
+ * Session state information
+ */
+interface SessionState {
+  /**
+   * Current session status
+   */
+  status: SessionStatus;
+  /**
+   * Last update timestamp (ms)
+   */
+  updatedAt: number;
+  /**
+   * Last activity timestamp (ms)
+   */
+  lastActiveAt: number;
+  /**
+   * User-defined session title
+   */
+  title?: string;
+  /**
+   * Error message if status is 'error'
+   */
+  errorMessage?: string;
+}
+/**
+ * Session-level configuration overrides
+ * These override the parent agent's configuration for this session only
+ */
+interface SessionConfigOverride {
+  /**
+   * Override model for this session
+   */
+  model?: ModelConfig;
+  /**
+   * Override system prompt for this session
+   */
+  systemPromptOverride?: string;
+  /**
+   * Override chat options for this session
+   */
+  chatOptions?: DefaultChatOptions;
+  /**
+   * Tools to disable for this session
+   */
+  disabledTools?: string[];
+}
+/**
+ * Conversation context containing message history
+ */
+interface ConversationContext {
+  /**
+   * Full message history
+   */
+  messages: Message[];
+  /**
+   * Total message count
+   */
+  messageCount: number;
+  /**
+   * Preview of the last message (for list display)
+   */
+  lastMessagePreview?: string;
+  /**
+   * Number of tool calls made in this session
+   */
+  toolCallCount: number;
+}
+/**
+ * Session usage statistics
+ */
+interface SessionStats {
+  /**
+   * Token usage for this session
+   */
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  /**
+   * Number of assistant responses
+   */
+  responseCount: number;
+  /**
+   * Average response time in milliseconds
+   */
+  avgResponseTime?: number;
+}
+/**
+ * Complete Session snapshot for serialization/persistence
+ */
+interface SessionSnapshot {
+  /**
+   * Unique session identifier
+   */
+  id: string;
+  /**
+   * Parent agent identifier
+   */
+  agentId: string;
+  /**
+   * Creation timestamp (ms)
+   */
+  createdAt: number;
+  /**
+   * Session state information
+   */
+  state: SessionState;
+  /**
+   * Session-level configuration overrides
+   */
+  configOverride?: SessionConfigOverride;
+  /**
+   * Conversation context with message history
+   */
+  context: ConversationContext;
+  /**
+   * Usage statistics
+   */
+  stats: SessionStats;
+  /**
+   * User-defined metadata
+   */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Model configuration stored in checkpoint (serializable)
+ */
+interface CheckpointModelConfig {
+  /**
+   * Model identifier (e.g., "gpt-4o", "claude-3-opus")
+   */
+  modelId: string;
+  /**
+   * Provider name (e.g., "openai", "anthropic")
+   */
+  provider?: string;
+  /**
+   * Model-specific configuration
+   */
+  config?: Record<string, unknown>;
+}
+/**
+ * Request parameters stored in checkpoint
+ */
+interface CheckpointRequestParams {
+  /**
+   * Temperature for response randomness
+   */
+  temperature?: number;
+  /**
+   * Maximum tokens to generate
+   */
+  maxTokens?: number;
+  /**
+   * Stop sequences
+   */
+  stop?: string[];
+  /**
+   * Additional model-specific parameters
+   */
+  [key: string]: unknown;
+}
+/**
+ * Checkpoint of AgentLoopState for persistence and resumption.
+ *
+ * This captures the complete runtime state of an agent loop execution,
+ * allowing it to be saved and restored for:
+ * - Resuming interrupted executions
+ * - Debugging and inspection
+ * - Audit logging
+ */
+interface AgentLoopCheckpoint {
+  /**
+   * Session ID for this execution
+   */
+  sessionId: string;
+  /**
+   * Agent ID
+   */
+  agentId: string;
+  /**
+   * Agent name (for display purposes)
+   */
+  agentName?: string;
+  /**
+   * Current loop iteration (0-indexed)
+   */
+  iteration: number;
+  /**
+   * Current phase of execution
+   */
+  phase?: 'llm_call' | 'tool_execution' | 'approval_pending' | 'completed';
+  /**
+   * Current status description (human readable)
+   */
+  status?: string;
+  /**
+   * Model configuration at checkpoint time
+   */
+  modelConfig?: CheckpointModelConfig;
+  /**
+   * Model request parameters at checkpoint time
+   */
+  requestParams?: CheckpointRequestParams;
+  /**
+   * Full message history
+   */
+  messages: Message[];
+  /**
+   * Pending tool calls (serialized)
+   */
+  pendingToolCalls: ToolCallWithResult[];
+  /**
+   * Text response accumulated so far
+   */
+  currentResponse: string;
+  /**
+   * Thinking/reasoning content (if any)
+   */
+  currentThinking?: string;
+  /**
+   * Whether the loop should continue
+   */
+  shouldContinue: boolean;
+  /**
+   * Stop reason (if stopped)
+   */
+  stopReason?: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'hook_stopped';
+  /**
+   * Stop reason reported by the last model call (if available).
+   */
+  lastModelStopReason?: ModelStopReason;
+  /**
+   * Cumulative token usage
+   */
+  usage: Usage;
+  /**
+   * Custom metadata
+   */
+  metadata: Record<string, unknown>;
+  /**
+   * Timestamp when this checkpoint was saved (ms)
+   */
+  savedAt: number;
+}
+//#endregion
+//#region src/types/event.d.ts
+/**
+ * Event types for streaming responses
+ */
+type AgentEventType = 'text_delta' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'tool_result' | 'tool_approval_requested' | 'requires_action' | 'tool_skipped' | 'thinking_start' | 'thinking_delta' | 'thinking_end' | 'usage' | 'error' | 'done' | 'iteration_start' | 'iteration_end';
+/**
+ * Base event interface
+ */
+interface BaseEvent {
+  type: AgentEventType;
+}
+/**
+ * Text delta event - partial text response
+ */
+interface TextDeltaEvent extends BaseEvent {
+  type: 'text_delta';
+  delta: string;
+}
+interface ToolCallStartEvent extends BaseEvent {
+  type: 'tool_call_start';
+  callId: string;
+  toolName?: string;
+}
+interface ToolCallDeltaEvent extends BaseEvent {
+  type: 'tool_call_delta';
+  callId: string;
+  toolName?: string;
+  argsTextDelta?: string;
+}
+interface ToolCallEndEvent extends BaseEvent {
+  type: 'tool_call_end';
+  toolCall: ToolCall;
+}
+/**
+ * Tool result event - tool execution completed
+ */
+interface ToolResultEvent extends BaseEvent {
+  type: 'tool_result';
+  tool_call_id: string;
+  result: unknown;
+  isError?: boolean;
+}
+/**
+ * Tool approval requested event - emitted when a high-risk tool requires approval
+ */
+interface ToolApprovalRequestedEvent extends BaseEvent {
+  type: 'tool_approval_requested';
+  /** Tool call ID */
+  tool_call_id: string;
+  /** Name of the tool */
+  toolName: string;
+  /** Risk level of the tool */
+  riskLevel: RiskLevel;
+  /** Parsed arguments */
+  args: Record<string, unknown>;
+}
+/**
+ * Requires action event - execution is paused awaiting external input.
+ *
+ * This is designed for "pause → user decides → resume from checkpoint" flows.
+ */
+interface RequiresActionEvent extends BaseEvent {
+  type: 'requires_action';
+  kind: 'tool_approval';
+  /** Tool call ID */
+  tool_call_id: string;
+  /** Name of the tool */
+  toolName: string;
+  /** Risk level of the tool */
+  riskLevel: RiskLevel;
+  /** Parsed arguments */
+  args: Record<string, unknown>;
+  /**
+   * Checkpoint to resume from.
+   * If a checkpoint store is configured, this may be omitted in favor of `checkpointRef`.
+   */
+  checkpoint?: AgentLoopCheckpoint;
+  /**
+   * Reference for loading checkpoint from a store.
+   */
+  checkpointRef?: {
+    sessionId: string;
+    agentId: string;
+  };
+}
+/**
+ * Tool skipped event - emitted when a tool execution is skipped (e.g., approval denied)
+ */
+interface ToolSkippedEvent extends BaseEvent {
+  type: 'tool_skipped';
+  /** Tool call ID */
+  tool_call_id: string;
+  /** Name of the tool */
+  toolName: string;
+  /** Reason for skipping */
+  reason: string;
+}
+/**
+ * Thinking start event - marks the beginning of a thinking phase
+ */
+interface ThinkingStartEvent extends BaseEvent {
+  type: 'thinking_start';
+}
+/**
+ * Thinking delta event - model's reasoning process (incremental)
+ */
+interface ThinkingDeltaEvent extends BaseEvent {
+  type: 'thinking_delta';
+  delta: string;
+}
+/**
+ * Thinking end event - marks the end of a thinking phase
+ */
+interface ThinkingEndEvent extends BaseEvent {
+  type: 'thinking_end';
+}
+/**
+ * Usage event - token consumption
+ */
+interface UsageEvent extends BaseEvent {
+  type: 'usage';
+  usage: Usage;
+}
+/**
+ * Error event - something went wrong
+ */
+interface ErrorEvent extends BaseEvent {
+  type: 'error';
+  error: Error;
+}
+/**
+ * Done event - stream completed
+ */
+interface DoneEvent extends BaseEvent {
+  type: 'done';
+  /** Final accumulated response text */
+  finalResponse?: string;
+  /** Stop reason for the loop */
+  stopReason?: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'hook_stopped';
+  /** Stop reason reported by the last model call (if available) */
+  modelStopReason?: ModelStopReason;
+}
+/**
+ * Iteration start event - beginning of a loop iteration
+ */
+interface IterationStartEvent extends BaseEvent {
+  type: 'iteration_start';
+  /** Current iteration number (0-indexed) */
+  iteration: number;
+}
+/**
+ * Iteration end event - end of a loop iteration
+ */
+interface IterationEndEvent extends BaseEvent {
+  type: 'iteration_end';
+  /** Current iteration number (0-indexed) */
+  iteration: number;
+  /** Whether the loop will continue to the next iteration */
+  willContinue: boolean;
+  /** Number of tool calls made in this iteration */
+  toolCallCount: number;
+}
+/**
+ * Union type for all agent events
+ */
+type AgentEvent = TextDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | ToolResultEvent | ToolApprovalRequestedEvent | RequiresActionEvent | ToolSkippedEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | UsageEvent | ErrorEvent | DoneEvent | IterationStartEvent | IterationEndEvent;
+//#endregion
+//#region src/model/base.d.ts
+/**
+ * Abstract base class for LLM model providers.
+ *
+ * Implement this class to create custom model integrations
+ * (e.g., OpenAI, Anthropic, local models).
+ */
+declare abstract class BaseModel {
+  /**
+   * Model identifier
+   */
+  abstract readonly modelId: string;
+  /**
+   * One-shot completion.
+   *
+   * @param messages - Conversation history
+   * @param options - Optional chat parameters
+   * @returns Complete response with message and usage
+   */
+  abstract invoke(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
+  /**
+   * Streaming completion.
+   *
+   * @param messages - Conversation history
+   * @param options - Optional chat parameters
+   * @returns Async iterable of stream events
+   */
+  abstract stream(messages: Message[], options?: ChatOptions): AsyncIterable<StreamEvent>;
+}
+//#endregion
+//#region src/model/adapter.d.ts
+interface ModelAdapter {
+  readonly provider: string;
+  readonly defaultModelId?: string;
+  getDefaultCapabilities?: (modelId: string) => Partial<CoreCapabilities>;
+  supportsFeature?: (modelId: string, featureId: string) => boolean;
+  stream: (args: {
+    request: ModelRequest;
+    featureGrants: FeatureGrants;
+    featureRequests?: FeatureRequests;
+  }) => AsyncIterable<ModelStreamEvent>;
+}
+//#endregion
+//#region src/model/utils/retry.d.ts
+/**
+ * Retry strategies for calculating delay between attempts.
+ *
+ * - exponential: delay = base * 2^(attempt-1) — doubles each time (most common for APIs)
+ * - linear: delay = base * attempt — increases linearly
+ * - fixed: delay = base — constant delay
+ */
+type RetryStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * Jitter strategies to avoid thundering herd problem.
+ *
+ * - full: delay = random(0, calculatedDelay)
+ * - equal: delay = calculatedDelay/2 + random(0, calculatedDelay/2)
+ * - decorrelated: delay = random(base, previousDelay * 3) — AWS-style
+ * - none: no jitter
+ */
+type JitterStrategy = 'full' | 'equal' | 'decorrelated' | 'none';
+interface RetryPolicyOptions {
+  /**
+   * Maximum number of attempts (including the first one).
+   * @default 3
+   */
+  maxAttempts?: number;
+  /**
+   * Base delay in milliseconds.
+   * @default 500
+   */
+  baseDelayMs?: number;
+  /**
+   * Maximum delay cap in milliseconds.
+   * @default 30000
+   */
+  maxDelayMs?: number;
+  /**
+   * Backoff strategy.
+   * @default 'exponential'
+   */
+  strategy?: RetryStrategy;
+  /**
+   * Jitter strategy to randomize delays.
+   * @default 'equal'
+   */
+  jitter?: JitterStrategy;
+  /**
+   * Multiplier for exponential/linear backoff.
+   * For exponential: delay = base * multiplier^(attempt-1)
+   * @default 2
+   */
+  multiplier?: number;
+}
+/**
+ * Retry policy for model requests with exponential backoff and jitter.
+ *
+ * Implements industry-standard retry patterns:
+ * - Exponential backoff: prevents overwhelming recovering services
+ * - Jitter: prevents thundering herd when many clients retry simultaneously
+ * - Max delay cap: prevents unbounded wait times
+ *
+ * @example
+ * ```ts
+ * // Default: exponential backoff with equal jitter
+ * const policy = new RetryPolicy()
+ *
+ * // Custom: 5 attempts, 1s base, 60s max, full jitter
+ * const policy = new RetryPolicy({
+ *   maxAttempts: 5,
+ *   baseDelayMs: 1000,
+ *   maxDelayMs: 60000,
+ *   jitter: 'full',
+ * })
+ *
+ * // Usage
+ * for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+ *   try {
+ *     await makeRequest()
+ *     break
+ *   } catch (err) {
+ *     if (!policy.canRetry(attempt)) throw err
+ *     await sleep(policy.getDelay(attempt))
+ *   }
+ * }
+ * ```
+ */
+declare class RetryPolicy {
+  readonly maxAttempts: number;
+  readonly baseDelayMs: number;
+  readonly maxDelayMs: number;
+  readonly strategy: RetryStrategy;
+  readonly jitter: JitterStrategy;
+  readonly multiplier: number;
+  private _previousDelay;
+  constructor(options?: RetryPolicyOptions);
+  /**
+   * Calculate delay for a given attempt.
+   *
+   * @param attempt - Current attempt number (1-indexed)
+   * @returns Delay in milliseconds with jitter applied
+   */
+  getDelay(attempt: number): number;
+  /**
+   * Apply jitter to the calculated delay.
+   */
+  private applyJitter;
+  /**
+   * Check if another retry is allowed.
+   *
+   * @param attempt - Current attempt number (1-indexed)
+   * @returns true if more retries are allowed
+   */
+  canRetry(attempt: number): boolean;
+  /**
+   * Reset internal state (useful for decorrelated jitter).
+   */
+  reset(): void;
+  /**
+   * Get a human-readable description of the policy.
+   */
+  toString(): string;
+  /**
+   * Create default retry policy for API calls.
+   * - 3 attempts
+   * - 500ms base delay
+   * - 30s max delay
+   * - Exponential backoff with equal jitter
+   */
+  static readonly default: RetryPolicy;
+  /**
+   * Create aggressive retry policy for critical operations.
+   * - 5 attempts
+   * - 1s base delay
+   * - 60s max delay
+   */
+  static readonly aggressive: RetryPolicy;
+  /**
+   * Create gentle retry policy for rate-limited APIs.
+   * - 3 attempts
+   * - 2s base delay
+   * - 30s max delay
+   * - Full jitter for better spread
+   */
+  static readonly gentle: RetryPolicy;
+}
+//#endregion
+//#region src/model/health.d.ts
+/**
+ * Health state for a single model.
+ */
+interface ModelHealthState {
+  failures: number;
+  nextRetryAt: number;
+  lastError?: {
+    code: string;
+    message: string;
+  };
+}
+/**
+ * Model health manager.
+ * Follows SRP: only handles health state tracking.
+ */
+declare class ModelHealth {
+  private readonly state;
+  get(ref: ModelRef): ModelHealthState;
+  markSuccess(ref: ModelRef): void;
+  markFailure(ref: ModelRef, options: {
+    now: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    code: string;
+    message: string;
+  }): void;
+  isAvailable(ref: ModelRef, now: number): boolean;
+  private keyOf;
+}
+/**
+ * In-memory implementation for backward compatibility.
+ */
+declare class InMemoryModelHealth extends ModelHealth {}
+//#endregion
+//#region src/model/errors.d.ts
+/**
+ * Model error class.
+ * Follows SRP: only handles error representation.
+ */
+declare class ModelError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly status?: number;
+  constructor(message: string, options: {
+    code: string;
+    retryable?: boolean;
+    status?: number;
+  });
+}
+//#endregion
+//#region src/model/createModel.d.ts
+/**
+ * Model client returned by createModel with guaranteed setModelId method
+ */
+interface CreateModelResult extends Omit<ModelClient, 'setModelId'> {
+  setModelId: (modelId: string) => void;
+}
+interface CreateModelOptions {
+  /**
+   * Provider adapters。
+   *
+   * 为什么是数组：
+   * - 一个 `ModelClient` 通常需要同时支持多个 provider（openai/anthropic/...），因此需要"可插拔"的 adapter 列表。
+   * - `createModel()` 会把它们按 `adapter.provider` 建索引，在路由/降级时根据 `ModelRef.provider` 选择对应 adapter。
+   *
+   * 约束：同一个 `provider` 只应出现一次（后者会覆盖前者的索引键）。
+   */
+  adapters: ModelAdapter[];
+  /**
+   * 路由与降级策略。
+   *
+   * 作用：当调用方没有在 `client.stream/run({ model })` 明确指定模型时，`createModel()` 会：
+   * - 根据 `fallbackOrder` 给出"尝试顺序"（primary + fallback）。
+   * - 结合 `health`（熔断/退避窗口）跳过当前不可用的模型。
+   * - 结合 `features` 里 `required:true` 的 feature 做硬筛选（必须满足才会尝试）。
+   *
+   * @remarks 如果不提供，会自动从 adapters 的 `defaultModelId` 推导。
+   */
+  routing?: {
+    /**
+     * 候选模型的尝试顺序（从前到后）。
+     *
+     * - 当某个模型在本次尝试中失败（或被熔断判定暂不可用）时，会继续尝试下一个。
+     * - 如果所有模型都失败，`createModel()` 会抛出最后一个错误。
+     */
+    fallbackOrder: ModelRef[];
+  };
+  /**
+   * 重试策略（可选）。
+   *
+   * 注意：这里是 "per-model 重试" —— 每个候选模型都会单独做最多 N 次重试；
+   * 若该模型最终失败，会进入 `fallbackOrder` 的下一个模型。
+   *
+   * 支持 Exponential Backoff（指数退避）+ Jitter（随机抖动）：
+   * - 指数退避：防止压垮正在恢复的服务
+   * - 随机抖动：防止多个客户端同时重试（雷群效应）
+   */
+  retry?: {
+    /**
+     * 单个模型的最大尝试次数（包含第一次请求）。
+     *
+     * - 例如 `3` 表示：首次失败且可重试时，最多再重试 2 次。
+     * - 仅当错误被判定为 `retryable`（见 `ModelError.retryable` / http 408/409/429/5xx 等）才会触发重试。
+     * @default 3
+     */
+    maxAttemptsPerModel?: number;
+    /**
+     * 重试基础延迟（毫秒）。
+     * @default 500
+     */
+    baseDelayMs?: number;
+    /**
+     * 最大退避延迟上限（毫秒）。
+     * @default 30000
+     */
+    maxDelayMs?: number;
+    /**
+     * 退避策略。
+     * - exponential: delay = base * 2^(attempt-1) — 每次翻倍（最常用）
+     * - linear: delay = base * attempt — 线性增长
+     * - fixed: delay = base — 固定延迟
+     * @default 'exponential'
+     */
+    strategy?: RetryStrategy;
+    /**
+     * 随机抖动策略，防止雷群效应。
+     * - full: delay = random(0, calculatedDelay)
+     * - equal: delay = calculatedDelay/2 + random(0, calculatedDelay/2)
+     * - decorrelated: AWS 风格，基于上次延迟计算
+     * - none: 不加抖动
+     * @default 'equal'
+     */
+    jitter?: JitterStrategy;
+    /**
+     * 重试时的回调函数，用于 debug 或日志记录。
+     *
+     * @param info - 重试信息
+     * @param info.attempt - 当前尝试次数（1-indexed）
+     * @param info.maxAttempts - 最大尝试次数
+     * @param info.delayMs - 即将等待的延迟时间（毫秒）
+     * @param info.error - 导致重试的错误
+     * @param info.model - 当前尝试的模型
+     * @param info.request - 请求详细内容（用于调试）
+     */
+    onRetry?: (info: {
+      attempt: number;
+      maxAttempts: number;
+      delayMs: number;
+      error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+      };
+      model: ModelRef;
+      request: ModelRequest;
+    }) => void;
+  };
+  /**
+   * 默认超时时间（毫秒）。
+   *
+   * - 如果单次请求未显式传 `request.timeoutMs`，就使用这里的默认值。
+   * - 超时通过 `AbortController` 触发取消，adapter 应尊重 `request.signal`。
+   */
+  timeoutMs?: number;
+  /**
+   * 模型健康度/熔断状态（可选）。
+   *
+   * - 默认使用内置 `InMemoryModelHealth`（进程内存级别）。
+   * - 当某模型失败时，会记录 failures 并计算 `nextRetryAt`，在该时间之前路由会尽量跳过它。
+   * - 你可以注入自己的实例来共享健康状态（例如在同进程多处创建 client 时复用）。
+   */
+  health?: InMemoryModelHealth;
+}
+declare function createModel(options: CreateModelOptions): CreateModelResult;
+//#endregion
+//#region src/model/utils/secrets.d.ts
+interface SecretProvider {
+  get: (name: string) => string | undefined;
+}
+//#endregion
+//#region src/model/openai/createOpenAIAdapter.d.ts
+interface OpenAIAdapterOptions {
+  baseUrl?: string;
+  apiKeySecretName?: string;
+  secretProvider?: SecretProvider;
+  defaultModelId?: string;
+  organization?: string;
+  project?: string;
+}
+declare function createOpenAIAdapter(options?: OpenAIAdapterOptions): ModelAdapter;
+//#endregion
+//#region src/agent/agent.d.ts
+/**
+ * Agent class - the main orchestrator.
+ *
+ * Agent is a blueprint/configuration that can handle multiple sessions.
+ * It composes model, tools, state store, and session manager.
+ *
+ * Supports middleware pattern for extensible hooks at each loop iteration.
+ */
+declare class Agent {
+  readonly id: string;
+  readonly name: string;
+  readonly systemPrompt: string;
+  readonly createdAt: number;
+  private _model;
+  private _tools?;
+  private _stateStore?;
+  private _sessionManager?;
+  private _metadata?;
+  private _middlewares;
+  private _stats;
+  constructor(options: AgentOptions);
+  /**
+   * Get the current model
+   */
+  get model(): ModelClient;
+  /**
+   * Get the tool registry
+   */
+  get tools(): ToolRegistry | undefined;
+  /**
+   * Get the state store
+   */
+  get stateStore(): StateStore | undefined;
+  /**
+   * Get the session manager
+   */
+  get sessionManager(): BaseSessionManager | undefined;
+  /**
+   * Get runtime statistics
+   */
+  get stats(): {
+    updatedAt: number;
+    totalSessions: number;
+    activeSessions: number;
+    totalUsage: {
+      promptTokens: number;
+      completionTokens: number;
+      totalTokens: number;
+    };
+  };
+  /**
+   * Get metadata
+   */
+  get metadata(): Record<string, unknown> | undefined;
+  /**
+   * Set metadata
+   */
+  set metadata(value: Record<string, unknown> | undefined);
+  /**
+   * Add middleware to the agent.
+   *
+   * Middleware runs at each loop iteration and can intercept/transform the loop state.
+   * Middleware follows an immutable pattern - it receives state and returns new state via next().
+   *
+   * @param fn - Middleware function
+   * @returns this for chaining
+   *
+   * @example
+   * ```ts
+   * // Logging middleware (pass-through)
+   * agent.use(async (state, next) => {
+   *   console.log('Before iteration', state.iteration);
+   *   const result = await next(state);
+   *   console.log('After iteration', state.iteration);
+   *   return result;
+   * });
+   *
+   * // Transforming middleware (e.g., compression)
+   * agent.use(async (state, next) => {
+   *   const compressed = { ...state, messages: compress(state.messages) };
+   *   return next(compressed);
+   * });
+   * ```
+   */
+  use(fn: Middleware<AgentLoopState>): this;
+  /**
+   * Switch to a different model
+   *
+   * @param model - New model to use
+   */
+  setModel(model: ModelClient): void;
+  /**
+   * Update session counts
+   *
+   * @param total - Total sessions
+   * @param active - Active sessions
+   */
+  updateSessionCounts(total: number, active: number): void;
+  /**
+   * Add to total usage statistics
+   *
+   * @param usage - Usage to add
+   * @param usage.promptTokens - Number of prompt tokens
+   * @param usage.completionTokens - Number of completion tokens
+   * @param usage.totalTokens - Total number of tokens
+   */
+  addUsage(usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  }): void;
+  /**
+   * Create a snapshot of the agent for persistence
+   *
+   * @returns Agent snapshot
+   */
+  toSnapshot(): AgentSnapshot;
+  /**
+   * Restore agent state from a snapshot
+   *
+   * Note: This restores mutable state (stats, metadata) from a snapshot.
+   * The model and tools must be provided separately as they contain runtime instances.
+   *
+   * @param snapshot - Agent snapshot to restore from
+   */
+  restoreFromSnapshot(snapshot: AgentSnapshot): void;
+  /**
+   * Execute model stream and collect events.
+   * This is the core execution that middleware wraps around.
+   */
+  private executeModelStream;
+  /**
+   * Execute a single tool call and return the result event.
+   */
+  private executeToolCall;
+  private createToolExecutionContext;
+  /**
+   * Merge execution results from processedState back to original state.
+   *
+   * This preserves original messages (for checkpoint) while keeping:
+   * - currentResponse, currentThinking (from LLM)
+   * - pendingToolCalls (from LLM)
+   * - usage (accumulated)
+   * - metadata (middleware may update this)
+   *
+   * Note: If processedState shares references with state (shallow copy),
+   * some fields are already synced. This method ensures all fields are merged.
+   */
+  private mergeStateResults;
+  /**
+   * Add tool result to message history.
+   */
+  private addToolResultToHistory;
+  /**
+   * Add assistant message with tool calls to history.
+   */
+  private addAssistantMessageWithToolCalls;
+  /**
+   * Add final assistant response to history.
+   */
+  private addFinalAssistantMessage;
+  /**
+   * Stream agent execution with proper agentic loop.
+   *
+   * The execution follows an immutable middleware pattern with checkpoint support:
+   * ```
+   * checkpoint:before (save original state)
+   *   → middleware chain (transforms state immutably)
+   *     → exec (model.stream with processed state)
+   *   → merge results back (except messages)
+   * checkpoint:after (save original state with original messages)
+   * ```
+   *
+   * Key invariant: checkpoint always saves the original messages, while
+   * LLM receives potentially transformed messages (e.g., compressed).
+   */
+  private streamWithState;
+  stream<TContext = unknown>(input: AgentInput<TContext>): AsyncIterable<AgentEvent>;
+  /**
+   * Stream agent execution starting from an existing message history (no new user message appended).
+   *
+   * Useful for orchestration patterns like "handoff", where a different agent should
+   * continue the same conversation state under a different system prompt.
+   */
+  streamFromMessages<TContext = unknown>(input: AgentInputFromMessages<TContext>): AsyncIterable<AgentEvent>;
+  /**
+   * Stream agent execution from a saved checkpoint.
+   *
+   * This allows resuming interrupted executions from the exact state
+   * where they were saved (e.g., during tool approval waiting).
+   *
+   * @param input - Input containing the checkpoint to resume from
+   *
+   * @example
+   * ```typescript
+   * // Load checkpoint from store
+   * const checkpoint = await store.loadLoopCheckpoint(sessionId)
+   *
+   * if (checkpoint) {
+   *   // Resume execution from checkpoint
+   *   for await (const event of agent.streamFromCheckpoint({
+   *     checkpoint,
+   *     maxIterations: 10,
+   *   })) {
+   *     console.log(event)
+   *   }
+   * }
+   * ```
+   */
+  streamFromCheckpoint<TContext = unknown>(input: AgentInputFromCheckpoint<TContext>): AsyncIterable<AgentEvent>;
+  /**
+   * Risk levels that require user approval before execution.
+   */
+  private static readonly APPROVAL_REQUIRED_LEVELS;
+  /**
+   * Check if a tool requires approval based on its risk level.
+   */
+  private requiresApproval;
+  /**
+   * Handle tool calls: execute tools, yield results, continue loop.
+   */
+  private handleToolCalls;
+  /**
+   * Handle final response: add to history, emit done.
+   */
+  private handleFinalResponse;
+}
+//#endregion
+//#region src/agent/checkpointMiddleware.d.ts
+/**
+ * Options for converting AgentLoopState to checkpoint
+ */
+interface ToCheckpointOptions {
+  agentName?: string;
+  phase?: 'llm_call' | 'tool_execution' | 'approval_pending' | 'completed';
+  status?: string;
+  /**
+   * Model configuration to save in checkpoint
+   */
+  modelConfig?: CheckpointModelConfig;
+  /**
+   * Model request parameters to save in checkpoint
+   */
+  requestParams?: CheckpointRequestParams;
+}
+/**
+ * Convert AgentLoopState to AgentLoopCheckpoint
+ */
+declare function toLoopCheckpoint(state: AgentLoopState, options?: ToCheckpointOptions): AgentLoopCheckpoint;
+/**
+ * Restore AgentLoopState from AgentLoopCheckpoint
+ *
+ * Note: agentName, phase, and status are display-only fields and are not
+ * part of AgentLoopState. They will be recalculated when a new checkpoint is saved.
+ */
+declare function fromLoopCheckpoint(checkpoint: AgentLoopCheckpoint): AgentLoopState;
+//#endregion
+//#region src/agent/errors.d.ts
+/**
+ * Error thrown when agent execution is aborted via AbortSignal
+ */
+declare class AgentAbortError extends Error {
+  constructor(message?: string);
+}
+/**
+ * Error thrown when agent exceeds maximum iterations
+ */
+declare class AgentMaxIterationsError extends Error {
+  readonly iterations: number;
+  constructor(iterations: number, message?: string);
+}
+/**
+ * Check if the abort signal has been triggered and throw if so.
+ *
+ * @param signal - AbortSignal to check
+ * @param context - Optional context for error message
+ * @throws AgentAbortError if signal is aborted
+ */
+declare function ensureNotAborted(signal?: AbortSignal, context?: string): void;
+//#endregion
+export { Agent, AgentAbortError, type AgentEvent, type AgentEventType, type AgentInput, type AgentInputFromCheckpoint, type AgentInputFromMessages, type AgentLoopCheckpoint, type AgentLoopState, AgentMaxIterationsError, type AgentOptions, type AssistantMessage, type BaseEvent, BaseModel, BaseSession, BaseSessionManager, BaseTool, type CallToolResult, type ChatOptions, type ChatResponse, type StateStore as CheckpointStore, StateStore, type StateStoreOptions as CheckpointStoreOptions, type StateStoreOptions, type CompressionState, type CompressionStats, type ContentBlock, type ContextCompressionOptions, CreateModelResult, type DoneEvent, type EditArgs, type EditResult, EditTool, type ErrorEvent, FeatureGrant, FeatureGrants, FeatureId, FeatureRequest, FeatureRequests, FileStateStore as FileCheckpointStore, FileStateStore, type FileStateStoreOptions as FileCheckpointStoreOptions, type FileStateStoreOptions, type GlobArgs, type GlobResult, GlobTool, type GrepArgs, type GrepOutputMode, type GrepResult, GrepTool, type ImageContent, InMemoryStateStore as InMemoryCheckpointStore, InMemoryStateStore, InMemoryModelHealth, type IterationEndEvent, type IterationStartEvent, type JSONSchemaProperty, JitterStrategy, type ManualCompressionOptions, type ManualCompressionResult, type Message, type MessageContent, type MessageRole, type Middleware, type ModelAdapter, ModelClient, ModelDeltaChunk, ModelError, ModelId, ModelRef, ModelRequest, ModelRunResult, ModelStopReason, ModelStreamEvent, ModelStreamFn, type NextFunction, OpenAIAdapterOptions, type OpenAITool, ProviderId, type ReadArgs, type ReadResult, ReadTool, RetryPolicy, RetryPolicyOptions, RetryStrategy, type RiskLevel, type StateKey, StateKeys, type StreamEvent, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingDeltaEvent, type ToCheckpointOptions, type Tool, type ToolApprovalOutcome, type ToolApprovalPending, type ToolApprovalRequest, type ToolApprovalResult, type ToolApprovalSettings, type ToolApprovalStrategy, type ToolCall, type ToolCallDeltaEvent, type ToolCallEndEvent, type ToolCallStartEvent, type ToolCallWithResult, type ToolExecutionContext, type ToolExecutionContextInput, type ToolFileSystemCapabilities, type ToolMessage, ToolRegistry, type ToolResultEvent, type ToolRunUsage, type Usage, type UsageEvent, type UserMessage, type WebSearchArgs, type WebSearchResult, WebSearchTool, type WriteArgs, type WriteResult, WriteTool, compose, compressSessionManually, createContextCompressionMiddleware, createInitialLoopState, createInitialLoopStateFromMessages, createModel, createOpenAIAdapter, ensureNotAborted, errorContent, fromLoopCheckpoint, imageContent, textContent, toLoopCheckpoint };