@cuylabs/agent-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4414 @@
+import * as ai from 'ai';
+import { LanguageModel, Tool, StreamTextResult, ToolSet, Output, ModelMessage } from 'ai';
+import { T as ToolHost, a as Tool$1, F as FileOperationMeta, b as TurnTrackerContext } from './index-eud06GDQ.js';
+export { D as DirEntry, E as ExecOptions, c as ExecResult, d as FileStat, M as MAX_BYTES, e as MAX_LINES, f as TRUNCATE_DIR, g as TRUNCATE_GLOB, h as ToolContext, i as ToolMetadata, j as ToolRegistry, k as ToolResult, l as ToolSpec, m as TruncateResult, n as defaultRegistry, o as defineTool, p as formatSize, t as truncateOutput } from './index-eud06GDQ.js';
+import { ProviderOptions } from '@ai-sdk/provider-utils';
+import 'zod';
+
+/**
+ * Storage Types
+ *
+ * Core types for session storage with tree structure support.
+ * Designed for append-only event sourcing with branching.
+ */
+/**
+ * Base interface for all session entries
+ * Supports tree structure via id/parentId
+ */
+interface EntryBase {
+    /** Unique entry ID (8-char hex) */
+    id: string;
+    /** Parent entry ID (null for first entry after header) */
+    parentId: string | null;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Session header - always first entry in file
+ */
+interface SessionHeader {
+    type: "header";
+    /** Storage format version */
+    version: number;
+    /** Session ID */
+    id: string;
+    /** Working directory */
+    cwd: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Session title */
+    title?: string;
+}
+/**
+ * Serialized message (dates as ISO strings)
+ */
+interface SerializedMessage {
+    id: string;
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    createdAt: string;
+    system?: string;
+    finish?: string;
+    tokens?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    cost?: number;
+    error?: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+    /** Tool calls for assistant messages with finish=tool-calls */
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }>;
+    toolCallId?: string;
+    toolName?: string;
+    result?: unknown;
+}
+/**
+ * Message entry
+ */
+interface MessageEntry extends EntryBase {
+    type: "message";
+    message: SerializedMessage;
+}
+/**
+ * Compaction/summarization entry
+ * Replaces old messages with a summary
+ */
+interface CompactionEntry extends EntryBase {
+    type: "compaction";
+    /** Summary of compacted messages */
+    summary: string;
+    /** ID of first entry that was kept (not compacted) */
+    firstKeptEntryId: string;
+    /** Token count before compaction */
+    tokensBefore: number;
+    /** Token count after compaction */
+    tokensAfter: number;
+    /** Files that were read during compacted messages */
+    readFiles?: string[];
+    /** Files that were modified during compacted messages */
+    modifiedFiles?: string[];
+}
+/**
+ * Session info/metadata update
+ */
+interface MetadataEntry extends EntryBase {
+    type: "metadata";
+    /** Updated title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+}
+/**
+ * Branch marker - indicates a branch point
+ */
+interface BranchEntry extends EntryBase {
+    type: "branch";
+    /** ID of the entry we're branching from */
+    branchFromId: string;
+    /** Optional summary of the branch */
+    summary?: string;
+}
+/**
+ * Model/config change entry
+ */
+interface ConfigChangeEntry extends EntryBase {
+    type: "config_change";
+    /** What changed */
+    change: "model" | "reasoning_level" | "temperature" | "other";
+    /** Previous value */
+    from?: string;
+    /** New value */
+    to: string;
+}
+/**
+ * All entry types (excluding header)
+ */
+type SessionEntry = MessageEntry | CompactionEntry | MetadataEntry | BranchEntry | ConfigChangeEntry;
+/**
+ * All file entries (including header)
+ */
+type FileEntry = SessionHeader | SessionEntry;
+/**
+ * Session summary info (lightweight, for listing)
+ */
+interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** File path */
+    path: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Creation time */
+    createdAt: Date;
+    /** Last modified time */
+    updatedAt: Date;
+    /** Number of message entries */
+    messageCount: number;
+    /** First user message (preview) */
+    firstMessage?: string;
+}
+/**
+ * Session storage interface
+ * Pluggable backend for session persistence
+ */
+interface SessionStorage {
+    /**
+     * Create a new session
+     */
+    create(header: SessionHeader): Promise<void>;
+    /**
+     * Append an entry to a session
+     */
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    /**
+     * Append multiple entries atomically
+     */
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    /**
+     * Read all entries from a session
+     */
+    read(sessionId: string): Promise<FileEntry[]>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * List all sessions (lightweight info only)
+     */
+    list(): Promise<SessionInfo[]>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Current storage format version
+ */
+declare const STORAGE_VERSION = 1;
+
+/**
+ * Message and token types for @cuylabs/agent-core
+ *
+ * Defines the message model used across conversations,
+ * including all role variants and token usage tracking.
+ */
+/**
+ * Message roles
+ */
+type MessageRole = "user" | "assistant" | "tool" | "system";
+/**
+ * Base message interface
+ */
+interface MessageBase {
+    id: string;
+    role: MessageRole;
+    createdAt: Date;
+}
+/**
+ * User message
+ */
+interface UserMessage extends MessageBase {
+    role: "user";
+    content: string;
+    /** Optional custom system prompt for this message */
+    system?: string;
+}
+/**
+ * Assistant message
+ */
+interface AssistantMessage extends MessageBase {
+    role: "assistant";
+    content: string;
+    /** Finish reason */
+    finish?: "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown";
+    /** Token usage for this response */
+    tokens?: TokenUsage;
+    /** Cost in USD */
+    cost?: number;
+    /** Error if any */
+    error?: MessageError;
+    /** Tool calls made by the assistant (when finish === "tool-calls") */
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }>;
+}
+/**
+ * Tool result message
+ */
+interface ToolMessage extends MessageBase {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    /**
+     * Timestamp when this tool result was compacted/pruned.
+     * Matches OpenCode's part.state.time.compacted pattern.
+     * Once set, this message won't be pruned again.
+     */
+    compactedAt?: number;
+}
+/**
+ * System message
+ */
+interface SystemMessage extends MessageBase {
+    role: "system";
+    content: string;
+}
+/**
+ * Union of all message types
+ */
+type Message = UserMessage | AssistantMessage | ToolMessage | SystemMessage;
+/**
+ * Error in a message
+ */
+interface MessageError {
+    name: string;
+    message: string;
+    code?: string;
+    status?: number;
+}
+/**
+ * Token usage statistics
+ */
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** Cache read tokens (if supported) */
+    cacheReadTokens?: number;
+    /** Cache write tokens (if supported) */
+    cacheWriteTokens?: number;
+}
+/**
+ * Session state
+ */
+interface Session {
+    id: string;
+    messages: Message[];
+    createdAt: Date;
+    updatedAt: Date;
+    /** Optional title */
+    title?: string;
+    /** Parent session ID for forking */
+    parentID?: string;
+}
+
+/**
+ * Stream types for @cuylabs/agent-core
+ *
+ * Defines the canonical StreamChunk union and related types
+ * for both AI SDK native and custom stream providers.
+ */
+/**
+ * Stream chunk types (AI SDK compatible + custom streams)
+ *
+ * This is the single canonical definition — used by both the
+ * streaming module and custom stream providers.
+ */
+type StreamChunk = {
+    type: "text-start";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "text-end";
+} | {
+    type: "reasoning-start";
+    id: string;
+} | {
+    type: "reasoning-delta";
+    id: string;
+    text: string;
+} | {
+    type: "reasoning-end";
+    id: string;
+} | {
+    type: "tool-call";
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+} | {
+    type: "tool-result";
+    toolName: string;
+    toolCallId: string;
+    output: unknown;
+} | {
+    type: "tool-error";
+    toolName: string;
+    toolCallId: string;
+    error: unknown;
+} | {
+    type: "finish-step";
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    finishReason?: string;
+} | {
+    type: "finish";
+    totalUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+} | {
+    type: "error";
+    error: unknown;
+} | {
+    type: "start-step";
+} | {
+    type: "start";
+} | {
+    type: "abort";
+} | {
+    type: "computer-call";
+    callId: string;
+    action: unknown;
+    pendingSafetyChecks?: unknown[];
+} | {
+    type: "step-usage";
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+};
+/**
+ * Custom stream provider function type.
+ *
+ * This matches the signature needed for agent-core's LLM module,
+ * returning a StreamProviderResult-compatible object.
+ */
+type StreamProvider = (input: StreamProviderInput) => Promise<StreamProviderResult>;
+/**
+ * Input for custom stream providers
+ */
+interface StreamProviderInput {
+    /** System prompt */
+    system: string;
+    /** Messages to send */
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+    /** Max iterations */
+    maxSteps?: number;
+}
+/**
+ * Result from custom stream providers (AI SDK StreamTextResult compatible)
+ */
+interface StreamProviderResult {
+    /** Async iterable of stream chunks */
+    fullStream: AsyncIterable<StreamChunk>;
+    /** Promise resolving to final text */
+    text: Promise<string>;
+    /** Promise resolving to usage stats */
+    usage: Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }>;
+    /** Promise resolving to finish reason */
+    finishReason: Promise<string>;
+}
+/**
+ * Configuration for stream provider factory.
+ * Contains everything needed to create a stream provider for a specific model.
+ */
+interface StreamProviderConfig {
+    /** API key to use */
+    apiKey?: string;
+    /** Display dimensions */
+    display?: {
+        width: number;
+        height: number;
+    };
+    /** Environment type */
+    environment?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Stream provider factory - creates a stream provider for a given model.
+ *
+ * This is attached to enhanced tools (like computer tools) to allow
+ * the Agent to automatically configure the right stream provider
+ * when a model requires custom handling (e.g., OpenAI computer-use-preview).
+ */
+type StreamProviderFactory = (modelId: string, config: StreamProviderConfig) => StreamProvider;
+/**
+ * Enhanced tools array with additional capabilities.
+ *
+ * This extends the standard Tool.AnyInfo[] with optional metadata
+ * that the Agent can use for automatic configuration.
+ */
+interface EnhancedTools extends Array<unknown> {
+    /**
+     * Factory to create a stream provider for models that need custom streaming.
+     * Called by the Agent when it detects a model that requires special handling.
+     */
+    __streamProviderFactory?: StreamProviderFactory;
+    /**
+     * Model patterns that require the custom stream provider.
+     * Used by the Agent to detect when to use the factory.
+     * Default patterns: ["computer-use-preview"]
+     */
+    __customStreamModels?: string[];
+}
+
+/** Agent status for UI display */
+type AgentStatus = "idle" | "processing" | "thinking" | "reasoning" | "calling-tool" | "waiting-approval" | "error";
+/** Approval request for UI */
+interface ApprovalEvent {
+    id: string;
+    tool: string;
+    args: unknown;
+    description: string;
+    risk: "safe" | "moderate" | "dangerous";
+}
+/**
+ * Events emitted during agent execution
+ *
+ * These events are designed for UI consumption:
+ * - status: Overall agent state for status indicators
+ * - approval-request: User confirmation needed
+ * - progress: Step counts for progress bars
+ */
+type AgentEvent = {
+    type: "status";
+    status: AgentStatus;
+} | {
+    type: "approval-request";
+    request: ApprovalEvent;
+} | {
+    type: "approval-resolved";
+    id: string;
+    action: "allow" | "deny" | "remember";
+} | {
+    type: "step-start";
+    step: number;
+    maxSteps: number;
+} | {
+    type: "step-finish";
+    step: number;
+    usage?: TokenUsage;
+    finishReason?: string;
+} | {
+    type: "message";
+    message: Message;
+} | {
+    type: "text-start";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "text-end";
+} | {
+    type: "reasoning-start";
+    id: string;
+} | {
+    type: "reasoning-delta";
+    id: string;
+    text: string;
+} | {
+    type: "reasoning-end";
+    id: string;
+} | {
+    type: "tool-start";
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+} | {
+    type: "tool-result";
+    toolName: string;
+    toolCallId: string;
+    result: unknown;
+} | {
+    type: "tool-error";
+    toolName: string;
+    toolCallId: string;
+    error: string;
+} | {
+    type: "computer-call";
+    callId: string;
+    action: unknown;
+    pendingSafetyChecks?: unknown[];
+} | {
+    type: "computer-result";
+    callId: string;
+    result: unknown;
+} | {
+    type: "intervention-applied";
+    id: string;
+    message: string;
+} | {
+    type: "doom-loop";
+    toolName: string;
+    repeatCount: number;
+} | {
+    type: "context-overflow";
+    inputTokens: number;
+    limit: number;
+} | {
+    type: "turn-summary";
+    turnId: string;
+    files: Array<{
+        path: string;
+        type: "created" | "modified" | "deleted" | "unchanged";
+        additions: number;
+        deletions: number;
+    }>;
+    additions: number;
+    deletions: number;
+} | {
+    type: "retry";
+    attempt: number;
+    delayMs: number;
+    error: Error;
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "complete";
+    usage?: TokenUsage;
+};
+/**
+ * Processor result - what happens after processing a turn
+ */
+type ProcessorResult = "continue" | "stop" | "compact";
+/**
+ * Stream input for the LLM
+ */
+interface StreamInput {
+    sessionID: string;
+    model: ai.LanguageModel;
+    system: string[];
+    messages: ai.ModelMessage[];
+    abort: AbortSignal;
+    tools: Record<string, unknown>;
+}
+
+/**
+ * Reasoning Types & Constants
+ *
+ * Shared type definitions, level constants, and small helpers
+ * used across the reasoning subsystem.
+ */
+/**
+ * Standard reasoning / thinking levels.
+ *
+ * | Level      | Description                        |
+ * |------------|------------------------------------|
+ * | `"off"`    | No reasoning (fastest)             |
+ * | `"minimal"`| Very light reasoning               |
+ * | `"low"`    | Light reasoning                    |
+ * | `"medium"` | Balanced reasoning                 |
+ * | `"high"`   | Deep reasoning                     |
+ * | `"xhigh"`  | Maximum reasoning (where supported)|
+ */
+type ReasoningLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Provider-specific reasoning configuration returned by
+ * {@link getReasoningConfig} / {@link getReasoningConfigSync}.
+ */
+interface ReasoningConfig {
+    /** Whether the model supports reasoning at all */
+    supportsReasoning: boolean;
+    /** Reasoning levels available for this model */
+    availableLevels: ReasoningLevel[];
+    /** Build provider options for a given level */
+    getProviderOptions: (level: ReasoningLevel) => Record<string, unknown> | undefined;
+}
+
+/**
+ * Model Capability Types for @cuylabs/agent-core
+ *
+ * Defines the structure for model capabilities that can be sourced from
+ * static patterns, local cache, or remote APIs.
+ */
+/**
+ * Input modalities a model can accept
+ */
+type InputModality = "text" | "image" | "audio" | "video" | "pdf";
+/**
+ * Output modalities a model can produce
+ */
+type OutputModality = "text" | "image" | "audio" | "video";
+/**
+ * Comprehensive model capabilities
+ */
+interface ModelCapabilities {
+    /** Model supports extended reasoning/thinking */
+    reasoning: boolean;
+    /** Model supports function/tool calling */
+    toolCalling: boolean;
+    /** Model supports temperature adjustment */
+    temperature: boolean;
+    /** Model supports file attachments */
+    attachments: boolean;
+    /** Model supports streaming responses */
+    streaming: boolean;
+    /** Supported input modalities */
+    inputModalities: InputModality[];
+    /** Supported output modalities */
+    outputModalities: OutputModality[];
+    /** Maximum context window in tokens */
+    contextWindow?: number;
+    /** Maximum output tokens */
+    maxOutput?: number;
+}
+/**
+ * Provider-specific compatibility flags
+ * These handle quirks in different provider implementations
+ */
+interface ProviderCompatibility {
+    /** Supports OpenAI-style reasoning_effort parameter */
+    supportsReasoningEffort?: boolean;
+    /** Supports developer/system role distinction */
+    supportsDeveloperRole?: boolean;
+    /** Field name for max tokens (varies by provider) */
+    maxTokensField?: "max_tokens" | "max_completion_tokens";
+    /** Requires thinking as text tags vs structured */
+    requiresThinkingTags?: boolean;
+    /** Provider-specific thinking format */
+    thinkingFormat?: "openai" | "anthropic" | "google" | "zai";
+}
+/**
+ * Complete model entry with metadata
+ */
+interface ModelEntry {
+    /** Model identifier (e.g., "gpt-4o", "claude-sonnet-4") */
+    id: string;
+    /** Human-readable model name */
+    name: string;
+    /** Provider identifier (e.g., "openai", "anthropic") */
+    provider: string;
+    /** Model capabilities */
+    capabilities: ModelCapabilities;
+    /** Provider-specific compatibility settings */
+    compatibility?: ProviderCompatibility;
+    /** Cost per million tokens (input) */
+    costInput?: number;
+    /** Cost per million tokens (output) */
+    costOutput?: number;
+    /** When this entry was last updated */
+    updatedAt?: string;
+}
+/**
+ * Priority levels for capability sources
+ */
+declare enum SourcePriority {
+    /** User configuration overrides everything */
+    UserConfig = 0,
+    /** Local cache from previous fetch */
+    LocalCache = 1,
+    /** Bundled static data (build-time) */
+    BundledData = 2,
+    /** Pattern-based inference (fallback) */
+    PatternMatch = 3,
+    /** Remote API (if network available) */
+    RemoteAPI = 4
+}
+/**
+ * Options for the capability resolver
+ */
+interface ResolverOptions {
+    /** Enable remote API fetching (default: false) */
+    enableRemoteFetch?: boolean;
+    /** Remote API URL (default: https://models.dev) */
+    remoteApiUrl?: string;
+    /** Cache directory path */
+    cachePath?: string;
+    /** Cache TTL in milliseconds (default: 1 hour) */
+    cacheTtlMs?: number;
+    /** Network timeout in milliseconds (default: 10 seconds) */
+    networkTimeoutMs?: number;
+    /** Custom user overrides for specific models */
+    modelOverrides?: Record<string, Partial<ModelCapabilities>>;
+}
+
+/**
+ * Extract a model ID string from a LanguageModel instance.
+ */
+declare function getModelId(model: LanguageModel): string;
+/**
+ * Extract a provider identifier from a LanguageModel instance.
+ */
+declare function getProviderId(model: LanguageModel): string | undefined;
+
+/**
+ * Remote Capability Fetching for @cuylabs/agent-core
+ *
+ * Handles fetching model capabilities from remote APIs (e.g., models.dev).
+ * Includes network status detection, timeout handling, and retry logic.
+ */
+
+/**
+ * Network status information
+ */
+interface NetworkStatus {
+    /** Whether we believe the network is available */
+    online: boolean;
+    /** Last successful fetch timestamp */
+    lastSuccess?: number;
+    /** Last error if any */
+    lastError?: string;
+    /** Number of consecutive failures */
+    failureCount: number;
+}
+/**
+ * Get current network status
+ */
+declare function getNetworkStatus(): NetworkStatus;
+
+/**
+ * Model Capability Resolver for @cuylabs/agent-core
+ *
+ * Main orchestrator that combines multiple capability sources:
+ * 1. User overrides (highest priority)
+ * 2. Local cache (fast, persisted)
+ * 3. Pattern matching (always available)
+ * 4. Remote API (optional, network-dependent)
+ *
+ * Designed for the Vercel AI SDK v6 ecosystem.
+ */
+
+/**
+ * Resolution result with source information
+ */
+interface ResolutionResult {
+    /** The resolved model entry */
+    entry: ModelEntry;
+    /** Which source provided the primary result */
+    source: SourcePriority;
+    /** Whether this is a confident match */
+    confident: boolean;
+    /** Resolution timing in ms */
+    resolveTimeMs: number;
+}
+/**
+ * Model Capability Resolver
+ *
+ * Provides a unified API for querying model capabilities with
+ * automatic fallback through multiple sources.
+ */
+declare class ModelCapabilityResolver {
+    private options;
+    private cache;
+    private sources;
+    private initialized;
+    private initPromise;
+    constructor(options?: Partial<ResolverOptions>);
+    /**
+     * Initialize the resolver (load cache, optionally fetch remote)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Resolve capabilities for a model
+     */
+    resolve(model: LanguageModel): Promise<ResolutionResult>;
+    /**
+     * Quick check if a model supports reasoning
+     * Uses cache/patterns only for speed
+     */
+    supportsReasoning(model: LanguageModel): Promise<boolean>;
+    /**
+     * Get capabilities for a model
+     */
+    getCapabilities(model: LanguageModel): Promise<ModelCapabilities>;
+    /**
+     * Get provider compatibility settings
+     */
+    getCompatibility(model: LanguageModel): Promise<ProviderCompatibility | undefined>;
+    /**
+     * Force refresh from remote API
+     */
+    refreshRemote(): Promise<void>;
+    /**
+     * Get current network status
+     */
+    getNetworkStatus(): NetworkStatus;
+    /**
+     * Get resolver statistics
+     */
+    getStats(): {
+        cacheSize: number;
+        cacheLoaded: boolean;
+        remoteFetchEnabled: boolean;
+        networkOnline: boolean;
+    };
+    /**
+     * Clear all cached data
+     */
+    clearCache(): Promise<void>;
+    /**
+     * List all available models
+     * Fetches from remote if cache is empty and remote is enabled
+     */
+    listModels(): Promise<ModelEntry[]>;
+    /**
+     * List all available models grouped by provider
+     */
+    listModelsByProvider(): Promise<Record<string, ModelEntry[]>>;
+}
+/**
+ * Get the default resolver instance
+ */
+declare function getDefaultResolver(): ModelCapabilityResolver;
+/**
+ * Configure the default resolver with custom options
+ */
+declare function configureResolver(options: Partial<ResolverOptions>): void;
+
+/**
+ * Reasoning Configuration & Option Builders
+ *
+ * Orchestrates capability detection and provider-specific option
+ * building to produce ready-to-use `providerOptions` for the
+ * Vercel AI SDK.
+ *
+ * Two flavours of every function are provided:
+ * - **Async** (`getReasoningConfig`, `buildReasoningOptions`) —
+ *   uses the full capability resolver (network + cache).
+ * - **Sync** (`getReasoningConfigSync`, `buildReasoningOptionsSync`) —
+ *   uses fast pattern-matching only (no network).
+ */
+
+/**
+ * Get the reasoning configuration for a model.
+ *
+ * Uses the full capability resolver (including network lookups)
+ * for the most accurate result.
+ */
+declare function getReasoningConfig(model: LanguageModel): Promise<ReasoningConfig>;
+/**
+ * Synchronous reasoning config using pattern-matching only.
+ *
+ * Faster but less accurate than {@link getReasoningConfig}.
+ * Good for hot paths where async is impractical.
+ */
+declare function getReasoningConfigSync(model: LanguageModel): ReasoningConfig;
+/**
+ * Build `providerOptions` for a reasoning level (async).
+ *
+ * Returns `undefined` when reasoning is off or unsupported.
+ */
+declare function buildReasoningOptions(model: LanguageModel, level: ReasoningLevel): Promise<ProviderOptions | undefined>;
+/**
+ * Build `providerOptions` for a reasoning level (sync / pattern-only).
+ */
+declare function buildReasoningOptionsSync(model: LanguageModel, level: ReasoningLevel): ProviderOptions | undefined;
+/**
+ * Check whether a model supports reasoning (async, full resolver).
+ */
+declare function supportsReasoning(model: LanguageModel): Promise<boolean>;
+/**
+ * Synchronous check using pattern-matching only.
+ */
+declare function supportsReasoningSync(model: LanguageModel): boolean;
+
+/**
+ * MCP (Model Context Protocol) Integration for @cuylabs/agent-core
+ *
+ * Provides seamless integration with MCP servers, allowing agents to
+ * use tools, resources, and prompts from external MCP-compatible services.
+ *
+ * Built on top of @ai-sdk/mcp for the core client functionality.
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, createMCPManager } from "@cuylabs/agent-core";
+ *
+ * const mcp = createMCPManager({
+ *   filesystem: {
+ *     transport: "stdio",
+ *     command: "npx",
+ *     args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
+ *   },
+ *   weather: {
+ *     transport: "http",
+ *     url: "https://weather-mcp.example.com/mcp",
+ *   },
+ * });
+ *
+ * const agent = createAgent({
+ *   model: openai("gpt-4o"),
+ *   mcp,
+ * });
+ * ```
+ */
+
+/**
+ * Stdio transport configuration for local MCP servers
+ */
+interface StdioTransportConfig {
+    transport: "stdio";
+    /** Command to execute */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Working directory */
+    cwd?: string;
+}
+/**
+ * HTTP transport configuration for remote MCP servers
+ */
+interface HttpTransportConfig {
+    transport: "http";
+    /** Server URL */
+    url: string;
+    /** HTTP headers (e.g., Authorization) */
+    headers?: Record<string, string>;
+}
+/**
+ * SSE transport configuration for remote MCP servers
+ */
+interface SseTransportConfig {
+    transport: "sse";
+    /** Server URL */
+    url: string;
+    /** HTTP headers (e.g., Authorization) */
+    headers?: Record<string, string>;
+}
+/**
+ * MCP server configuration
+ */
+type MCPServerConfig = (StdioTransportConfig | HttpTransportConfig | SseTransportConfig) & {
+    /** Whether this server is enabled (default: true) */
+    enabled?: boolean;
+    /** Connection timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Human-readable name for the server */
+    name?: string;
+};
+/**
+ * MCP manager configuration - map of server name to config
+ */
+type MCPConfig = Record<string, MCPServerConfig>;
+/**
+ * Server connection status
+ */
+type MCPServerStatus = {
+    status: "disconnected";
+} | {
+    status: "connecting";
+} | {
+    status: "connected";
+    toolCount: number;
+} | {
+    status: "error";
+    error: string;
+} | {
+    status: "disabled";
+};
+/**
+ * MCP resource (from server)
+ */
+interface MCPResource {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    server: string;
+}
+/**
+ * MCP prompt (from server)
+ */
+interface MCPPrompt {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    server: string;
+}
+/**
+ * MCP Manager - handles connections to multiple MCP servers
+ */
+interface MCPManager {
+    /**
+     * Connect to all configured servers
+     * @returns Map of server names to their status
+     */
+    connect(): Promise<Map<string, MCPServerStatus>>;
+    /**
+     * Get all tools from connected servers
+     * Returns AI SDK compatible tools ready for use with streamText/generateText
+     */
+    getTools(): Promise<Record<string, Tool>>;
+    /**
+     * Get status of a specific server
+     */
+    getStatus(serverName: string): MCPServerStatus;
+    /**
+     * Get status of all servers
+     */
+    getAllStatus(): Map<string, MCPServerStatus>;
+    /**
+     * List available resources from all connected servers
+     */
+    listResources(): Promise<MCPResource[]>;
+    /**
+     * Read a resource by URI
+     */
+    readResource(uri: string): Promise<{
+        contents: Array<{
+            uri: string;
+            text?: string;
+            blob?: string;
+            mimeType?: string;
+        }>;
+    }>;
+    /**
+     * List available prompts from all connected servers
+     */
+    listPrompts(): Promise<MCPPrompt[]>;
+    /**
+     * Get a prompt with optional arguments
+     */
+    getPrompt(serverName: string, promptName: string, args?: Record<string, unknown>): Promise<{
+        description?: string;
+        messages: Array<{
+            role: string;
+            content: unknown;
+        }>;
+    }>;
+    /**
+     * Close all connections
+     */
+    close(): Promise<void>;
+    /**
+     * Check if manager has any connected servers
+     */
+    isConnected(): boolean;
+}
+/**
+ * Create an MCP manager for connecting to multiple MCP servers
+ *
+ * @example
+ * ```typescript
+ * const mcp = createMCPManager({
+ *   // Local filesystem server via stdio
+ *   filesystem: {
+ *     transport: "stdio",
+ *     command: "npx",
+ *     args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
+ *   },
+ *   // Remote weather API via HTTP
+ *   weather: {
+ *     transport: "http",
+ *     url: "https://weather.example.com/mcp",
+ *     headers: { Authorization: "Bearer xxx" },
+ *   },
+ * });
+ *
+ * // Connect to all servers
+ * await mcp.connect();
+ *
+ * // Get all tools for use with AI SDK
+ * const tools = await mcp.getTools();
+ * ```
+ */
+declare function createMCPManager(config: MCPConfig): MCPManager;
+/**
+ * Helper to define a single MCP server config
+ * Useful for building configs programmatically
+ */
+declare function defineServer(config: MCPServerConfig): MCPServerConfig;
+/**
+ * Helper to create a stdio server config
+ */
+declare function stdioServer(command: string, args?: string[], options?: Omit<StdioTransportConfig, "transport" | "command" | "args">): StdioTransportConfig;
+/**
+ * Helper to create an HTTP server config
+ */
+declare function httpServer(url: string, options?: Omit<HttpTransportConfig, "transport" | "url">): HttpTransportConfig;
+/**
+ * Helper to create an SSE server config
+ */
+declare function sseServer(url: string, options?: Omit<SseTransportConfig, "transport" | "url">): SseTransportConfig;
+
+/**
+ * Prompt Pipeline Types
+ *
+ * Types for the layered system prompt architecture.
+ * The prompt pipeline composes a system prompt from multiple sources:
+ *
+ *   Base Template → Environment → Instructions → Custom Sections → Per-Turn
+ *
+ * Each layer is optional, composable, and can be toggled on/off.
+ */
+
+/**
+ * Model family identifier for prompt template selection.
+ *
+ * Each family gets a base template optimized for its strengths:
+ * - `anthropic`: Claude models — structured sections with XML tags
+ * - `openai`: GPT/o-series models — clear directives with markdown
+ * - `google`: Gemini models — balanced approach
+ * - `deepseek`: DeepSeek models — code-focused emphasis
+ * - `default`: Generic template for any model
+ */
+type ModelFamily = "anthropic" | "openai" | "google" | "deepseek" | "default";
+/**
+ * Runtime environment information injected into the system prompt.
+ * Gives the model awareness of the working context.
+ */
+interface EnvironmentInfo {
+    /** Current working directory */
+    cwd: string;
+    /** Operating system (e.g. "macOS (darwin arm64)") */
+    platform: string;
+    /** Current date/time formatted string */
+    date: string;
+    /** User's shell (e.g. "/bin/zsh") */
+    shell?: string;
+    /** Active git branch, if inside a repo */
+    gitBranch?: string;
+    /** Whether the working tree is clean */
+    gitClean?: boolean;
+    /** Git repo root path */
+    gitRoot?: string;
+}
+/**
+ * An instruction file discovered on disk (e.g. AGENTS.md).
+ *
+ * Instruction files provide project-specific or workspace-level guidance
+ * that gets injected into every prompt. They're discovered by walking up
+ * the directory tree from cwd.
+ */
+interface InstructionFile {
+    /** Absolute path to the file */
+    path: string;
+    /** File content (trimmed) */
+    content: string;
+    /** How the file was discovered */
+    source: "project" | "workspace" | "global";
+    /** Depth from cwd (0 = same directory) */
+    depth: number;
+}
+/**
+ * A composable section in the prompt pipeline.
+ *
+ * Sections are the building blocks of the final system prompt.
+ * Each section has a priority that determines its position in the output.
+ *
+ * Default priority ranges:
+ * - 10: Base template
+ * - 20: Environment block
+ * - 30: Instruction files
+ * - 50: Custom sections (default for user-added)
+ * - 70: Reserved for future use (e.g. Skills)
+ * - 90: Per-turn overrides
+ */
+interface PromptSection {
+    /** Unique identifier for this section */
+    id: string;
+    /** Human-readable label (useful for debugging/logging) */
+    label: string;
+    /** The text content of this section */
+    content: string;
+    /** Sort priority — lower values appear earlier (default: 50) */
+    priority?: number;
+    /** Whether this section is active (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Context passed to the builder for each prompt build.
+ *
+ * This provides the runtime information needed to compose
+ * the system prompt for a specific conversation turn.
+ */
+interface PromptBuildContext {
+    /** Current working directory */
+    cwd: string;
+    /** The language model being used */
+    model: LanguageModel;
+    /** Names of available tools (for template customization) */
+    toolNames?: string[];
+    /** Per-turn additional instructions (from chat options) */
+    override?: string;
+    /** Current session ID */
+    sessionId?: string;
+}
+/**
+ * Configuration for the prompt pipeline.
+ *
+ * Controls which layers are active and how they behave.
+ * All options have sensible defaults — an empty config `{}` gives you
+ * the full pipeline with auto-detection.
+ *
+ * @example
+ * ```typescript
+ * // Minimal — use all defaults
+ * const builder = createPromptBuilder();
+ *
+ * // Custom base template but keep environment + instructions
+ * const builder = createPromptBuilder({
+ *   baseTemplate: "You are a security auditor...",
+ *   includeEnvironment: true,
+ *   includeInstructions: true,
+ * });
+ *
+ * // Fully custom — disable auto features, add your own sections
+ * const builder = createPromptBuilder({
+ *   includeEnvironment: false,
+ *   includeInstructions: false,
+ *   sections: [
+ *     { id: "role", label: "Role", content: "You audit code.", priority: 10 },
+ *     { id: "rules", label: "Rules", content: "Never modify files.", priority: 20 },
+ *   ],
+ * });
+ * ```
+ */
+interface PromptConfig {
+    /**
+     * Override the base template entirely.
+     * If set, replaces the model-family-specific template.
+     */
+    baseTemplate?: string;
+    /**
+     * Force a specific model family for template selection.
+     * Auto-detected from the model if not provided.
+     */
+    modelFamily?: ModelFamily;
+    /**
+     * Inject runtime environment info (cwd, platform, git, date).
+     * @default true
+     */
+    includeEnvironment?: boolean;
+    /**
+     * Discover and include instruction files (AGENTS.md, etc.).
+     * @default true
+     */
+    includeInstructions?: boolean;
+    /**
+     * File name patterns to search for when discovering instructions.
+     * Searched in each directory walking up from cwd.
+     *
+     * @default ["AGENTS.md", "CLAUDE.md", "COPILOT.md", ".cuylabs/instructions.md"]
+     */
+    instructionPatterns?: string[];
+    /**
+     * Absolute paths to global instruction files (always included
+     * regardless of cwd). Useful for organization-wide rules.
+     */
+    globalInstructions?: string[];
+    /**
+     * Maximum depth to walk up from cwd when searching for instructions.
+     * Prevents scanning the entire filesystem.
+     * @default 10
+     */
+    instructionMaxDepth?: number;
+    /**
+     * Maximum file size in bytes for instruction files.
+     * Files larger than this are skipped to avoid bloating the prompt.
+     * @default 51200 (50KB)
+     */
+    instructionMaxSize?: number;
+    /**
+     * Pre-defined sections to include in every prompt build.
+     * These are merged with auto-generated sections (template, environment, etc.).
+     */
+    sections?: PromptSection[];
+    /**
+     * Separator between sections in the final composed prompt.
+     * @default "\n\n"
+     */
+    separator?: string;
+}
+
+/**
+ * Agent configuration and state types for @cuylabs/agent-core
+ *
+ * Defines AgentConfig (the main config surface), AgentState,
+ * doom-loop types, and compaction configuration.
+ */
+
+/**
+ * Agent configuration
+ */
+interface AgentConfig {
+    /** Vercel AI SDK model instance */
+    model: LanguageModel;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Working directory */
+    cwd?: string;
+    /**
+     * Execution environment for tools.
+     *
+     * Controls *where* tools run — local machine, Docker container, SSH host, etc.
+     * When not provided, defaults to `localHost(cwd)` which uses the local
+     * filesystem and shell directly.
+     *
+     * @example
+     * ```typescript
+     * import { localHost } from "@cuylabs/agent-core";
+     *
+     * // Explicit local host (same as default)
+     * const agent = createAgent({ host: localHost("/my/project") });
+     *
+     * // Future: Docker host
+     * // const agent = createAgent({ host: dockerHost("my-container") });
+     * ```
+     */
+    host?: ToolHost;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** Top-p sampling */
+    topP?: number;
+    /** Max output tokens */
+    maxOutputTokens?: number;
+    /** Maximum steps (tool call iterations) */
+    maxSteps?: number;
+    /** Reasoning/thinking level for models that support it */
+    reasoningLevel?: ReasoningLevel;
+    /** Require approval for dangerous operations */
+    requireApproval?: boolean;
+    /**
+     * Handler for doom loop detection.
+     *
+     * When the agent detects repeated identical tool calls (default: 3 times),
+     * this handler is called to decide what to do.
+     *
+     * If not provided:
+     * - enforceDoomLoop=true (default): throws DoomLoopError
+     * - enforceDoomLoop=false: logs warning and continues
+     *
+     * @see DoomLoopHandler
+     */
+    onDoomLoop?: DoomLoopHandler;
+    /**
+     * Strictly enforce doom loop (throw error).
+     * Only used when onDoomLoop is not provided.
+     * Default: true
+     */
+    enforceDoomLoop?: boolean;
+    /**
+     * Number of identical tool calls before triggering doom loop.
+     * Default: 3 (like OpenCode's DOOM_LOOP_THRESHOLD)
+     */
+    doomLoopThreshold?: number;
+    /**
+     * Context compaction configuration.
+     * Controls automatic management of the context window.
+     *
+     * @see CompactionConfig
+     */
+    compaction?: CompactionConfig;
+    /**
+     * Context window size in tokens (for overflow detection).
+     * If not provided, defaults to 128,000 tokens.
+     *
+     * This should match your model's context limit.
+     */
+    contextWindow?: number;
+    /**
+     * Custom stream provider for specialized models (e.g., OpenAI computer use).
+     *
+     * When provided, this function will be called instead of the default
+     * AI SDK streamText(). This allows packages like @cuylabs/computer-agent
+     * to inject custom streaming implementations without circular dependencies.
+     *
+     * The returned object must have a `fullStream` async iterable that yields
+     * AI SDK compatible chunks (text-delta, tool-call, tool-result, etc.).
+     */
+    streamProvider?: StreamProvider;
+    /**
+     * MCP (Model Context Protocol) manager for external tool servers.
+     *
+     * When provided, the agent will connect to configured MCP servers
+     * and make their tools available alongside local tools.
+     *
+     * @example
+     * ```typescript
+     * import { createMCPManager } from "@cuylabs/agent-core";
+     *
+     * const mcp = createMCPManager({
+     *   filesystem: {
+     *     transport: "stdio",
+     *     command: "npx",
+     *     args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+     *   },
+     * });
+     *
+     * const agent = createAgent({
+     *   model: openai("gpt-4o"),
+     *   mcp,
+     * });
+     * ```
+     */
+    mcp?: MCPManager;
+    /**
+     * Prompt pipeline configuration.
+     *
+     * When provided, enables the layered prompt system that automatically
+     * composes system prompts from:
+     * - Model-family-optimized base templates
+     * - Runtime environment info (cwd, platform, git branch)
+     * - Instruction files (AGENTS.md, CLAUDE.md discovered on disk)
+     * - Custom sections you define
+     * - Per-turn overrides from chat options
+     *
+     * When neither `prompt` nor `systemPrompt` is provided, the pipeline
+     * is enabled with sensible defaults.
+     *
+     * When `systemPrompt` is provided without `prompt`, the flat string
+     * is used directly (backward compatible).
+     *
+     * @example
+     * ```typescript
+     * const agent = createAgent({
+     *   model: anthropic("claude-sonnet-4-20250514"),
+     *   prompt: {
+     *     includeEnvironment: true,
+     *     includeInstructions: true,
+     *     sections: [
+     *       { id: "team", label: "Team Rules", content: "Use strict TypeScript." },
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    prompt?: PromptConfig;
+}
+/**
+ * Agent state
+ */
+interface AgentState {
+    model: LanguageModel;
+    systemPrompt: string;
+    cwd: string;
+    isStreaming: boolean;
+    /** Current reasoning level */
+    reasoningLevel: ReasoningLevel;
+    error?: Error;
+}
+/**
+ * Doom loop handler response - what to do when a doom loop is detected.
+ *
+ * Aligned with OpenCode's PermissionNext.Reply:
+ * - "once" (OpenCode) → "allow" - Allow this once
+ * - "always" (OpenCode) → "remember" - Allow and remember for this session
+ * - "reject" (OpenCode) → "deny" - Reject and throw error
+ */
+type DoomLoopAction = "allow" | "deny" | "remember";
+/**
+ * Doom loop detection request.
+ * Sent to the handler when repeated tool calls are detected.
+ */
+interface DoomLoopRequest {
+    /** The tool being called repeatedly */
+    tool: string;
+    /** How many times it's been called with same input */
+    repeatCount: number;
+    /** The input being passed (for context) */
+    input: unknown;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * Handler for doom loop situations.
+ *
+ * Return:
+ * - "allow": Continue despite the loop (like OpenCode's "once")
+ * - "deny": Stop execution and throw error (like OpenCode's "reject")
+ * - "remember": Allow and don't ask again for this tool in this session (like OpenCode's "always")
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   onDoomLoop: async (req) => {
+ *     // Show UI asking user
+ *     const action = await showConfirmDialog(
+ *       `${req.tool} called ${req.repeatCount} times with same input. Continue?`
+ *     );
+ *     return action;
+ *   },
+ * });
+ * ```
+ */
+type DoomLoopHandler = (request: DoomLoopRequest) => Promise<DoomLoopAction>;
+/**
+ * Configuration for automatic context compaction.
+ *
+ * Aligned with OpenCode's SessionCompaction:
+ * - Auto-pruning of old tool outputs
+ * - LLM-based summarization
+ * - Auto-continue after compaction
+ */
+interface CompactionConfig {
+    /**
+     * Enable automatic compaction when context overflows.
+     * Default: true (matches OpenCode's default)
+     */
+    auto?: boolean;
+    /**
+     * Enable pruning of old tool outputs before summarization.
+     * This is a lightweight operation that removes tool result content.
+     * Default: true
+     */
+    prune?: boolean;
+    /**
+     * Protect this many recent tokens from pruning.
+     * Default: 40,000 (like OpenCode's PRUNE_PROTECT)
+     */
+    protectedTokens?: number;
+    /**
+     * Minimum tokens to trigger pruning.
+     * Default: 20,000 (like OpenCode's PRUNE_MINIMUM)
+     */
+    pruneMinimum?: number;
+    /**
+     * Custom summarization prompt for compaction.
+     * If not provided, uses default prompt asking for continuation context.
+     */
+    summaryPrompt?: string;
+    /**
+     * Model to use for summarization (optional).
+     * If not provided, uses the same model as the agent.
+     * You might want to use a cheaper/faster model here.
+     */
+    summaryModel?: LanguageModel;
+    /**
+     * Auto-continue after compaction with "Continue if you have next steps".
+     * Like OpenCode's behavior.
+     * Default: true
+     */
+    autoContinue?: boolean;
+}
+
+/**
+ * Session Manager
+ *
+ * High-level API for session management with tree structure support.
+ * Uses pluggable storage backend.
+ */
+
+/**
+ * Options for creating a new session
+ */
+interface CreateSessionOptions {
+    /** Custom session ID (auto-generated if not provided) */
+    id?: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** Parent session ID (if forking) */
+    parentSessionId?: string;
+}
+/**
+ * Session context for LLM
+ */
+interface SessionContext {
+    /** Messages for LLM context */
+    messages: Message[];
+    /** Current leaf entry ID */
+    leafId: string | null;
+    /** Session metadata */
+    metadata: {
+        id: string;
+        cwd: string;
+        title?: string;
+        name?: string;
+    };
+}
+/**
+ * Session Manager
+ *
+ * Manages session lifecycle with tree-structured entries.
+ * Supports branching, compaction, and pluggable storage.
+ */
+declare class SessionManager {
+    private storage;
+    private currentSessionId;
+    private currentLeafId;
+    private entriesCache;
+    private idsCache;
+    constructor(storage?: SessionStorage);
+    /**
+     * Create a new session
+     */
+    create(options: CreateSessionOptions): Promise<string>;
+    /**
+     * Load an existing session
+     */
+    load(sessionId: string): Promise<void>;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Get current leaf ID
+     */
+    getLeafId(): string | null;
+    /**
+     * Add a message to the session
+     */
+    addMessage(message: Message): Promise<string>;
+    /**
+     * Add multiple messages atomically
+     */
+    addMessages(messages: Message[]): Promise<string[]>;
+    /**
+     * Get messages for LLM context
+     */
+    getMessages(leafId?: string): Message[];
+    /**
+     * Add a compaction entry (after pruning context)
+     */
+    addCompaction(options: {
+        summary: string;
+        firstKeptEntryId: string;
+        tokensBefore: number;
+        tokensAfter: number;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
+    /**
+     * Branch from a specific entry
+     * Sets the leaf to that entry so new messages continue from there
+     */
+    branch(fromEntryId: string, summary?: string): Promise<string>;
+    /**
+     * Switch to a different leaf (navigate to a branch)
+     */
+    switchToLeaf(leafId: string): void;
+    /**
+     * Update session metadata
+     */
+    updateMetadata(updates: {
+        title?: string;
+        name?: string;
+    }): Promise<void>;
+    /**
+     * Get full session context for LLM
+     */
+    getContext(): SessionContext;
+    /**
+     * Get all entries (for debugging/inspection)
+     */
+    getEntries(): FileEntry[];
+    /**
+     * Get header
+     */
+    getHeader(): SessionHeader | null;
+    /**
+     * List all sessions
+     */
+    listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Get underlying storage
+     */
+    getStorage(): SessionStorage;
+}
+/**
+ * Get default session manager instance
+ */
+declare function getDefaultSessionManager(): SessionManager;
+/**
+ * Configure default session manager with custom storage
+ */
+declare function configureDefaultSessionManager(storage: SessionStorage): SessionManager;
+
+/**
+ * Storage Utilities
+ *
+ * Helper functions for session storage operations.
+ */
+
+/**
+ * Generate a unique 8-character hex ID
+ * Collision-checked against existing IDs
+ */
+declare function generateEntryId(existingIds?: Set<string>): string;
+/**
+ * Parse JSONL content into entries
+ * Handles malformed lines gracefully
+ */
+declare function parseJSONL<T>(content: string): T[];
+/**
+ * Serialize entry to JSONL line
+ */
+declare function toJSONL(entry: FileEntry): string;
+/**
+ * Serialize a Message to storage format
+ */
+declare function serializeMessage(message: Message): SerializedMessage;
+/**
+ * Deserialize a stored message back to Message
+ */
+declare function deserializeMessage(serialized: SerializedMessage): Message;
+/**
+ * Get leaf entry ID (last entry in the chain)
+ */
+declare function getLeafId(entries: FileEntry[]): string | null;
+/**
+ * Build messages array from entries for a specific leaf
+ * Handles compaction summaries
+ */
+declare function buildMessagesFromEntries(entries: FileEntry[], leafId?: string): Message[];
+
+/**
+ * Memory Session Storage
+ *
+ * In-memory implementation of SessionStorage.
+ * Useful for testing and ephemeral sessions.
+ */
+
+/**
+ * In-memory session storage
+ */
+declare class MemoryStorage implements SessionStorage {
+    private sessions;
+    create(header: SessionHeader): Promise<void>;
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    read(sessionId: string): Promise<FileEntry[]>;
+    delete(sessionId: string): Promise<boolean>;
+    exists(sessionId: string): Promise<boolean>;
+    list(): Promise<SessionInfo[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * File Session Storage
+ *
+ * JSONL file-based implementation of SessionStorage.
+ * Each session is stored as a separate .jsonl file with append-only writes.
+ *
+ * Features:
+ * - Async I/O (non-blocking)
+ * - Append-only writes (crash-safe)
+ * - In-memory cache for fast reads
+ * - Tree structure support via id/parentId
+ */
+
+/**
+ * Options for file storage
+ */
+interface FileStorageOptions {
+    /** Directory to store session files */
+    directory: string;
+    /** File extension (default: .jsonl) */
+    extension?: string;
+    /** Enable in-memory cache (default: true) */
+    cache?: boolean;
+}
+/**
+ * JSONL file-based session storage
+ */
+declare class FileStorage implements SessionStorage {
+    private readonly directory;
+    private readonly extension;
+    private readonly useCache;
+    private cache;
+    private initialized;
+    constructor(options: FileStorageOptions);
+    /**
+     * Ensure directory exists
+     */
+    private ensureDir;
+    /**
+     * Get file path for a session
+     */
+    private getPath;
+    /**
+     * Load entries from disk
+     */
+    private loadFromDisk;
+    /**
+     * Get entries (from cache or disk)
+     */
+    private getEntries;
+    create(header: SessionHeader): Promise<void>;
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    read(sessionId: string): Promise<FileEntry[]>;
+    delete(sessionId: string): Promise<boolean>;
+    exists(sessionId: string): Promise<boolean>;
+    list(): Promise<SessionInfo[]>;
+    clear(): Promise<void>;
+    /**
+     * Flush cache (force reload from disk on next read)
+     */
+    flushCache(): void;
+    /**
+     * Reload a session from disk (bypass cache)
+     */
+    reload(sessionId: string): Promise<FileEntry[]>;
+    /**
+     * Get session IDs without loading full data
+     */
+    listIds(): Promise<string[]>;
+    /**
+     * Get file stats for a session
+     */
+    getStats(sessionId: string): Promise<{
+        size: number;
+        mtime: Date;
+    } | null>;
+}
+
+/**
+ * Default paths for storage
+ *
+ * Follows platform conventions:
+ * - macOS: ~/.cuylabs/
+ * - Linux: $XDG_DATA_HOME/cuylabs/ or ~/.local/share/cuylabs/
+ * - Windows: %APPDATA%/cuylabs/
+ *
+ * Project identification:
+ * - Uses git root commit hash (like OpenCode) for git repos
+ * - Falls back to encoded path for non-git directories
+ */
+/**
+ * Get the default data directory for cuylabs
+ */
+declare function getDataDir(appName?: string): string;
+/**
+ * Get the default sessions directory
+ */
+declare function getSessionsDir(appName?: string): string;
+/**
+ * Get sessions directory for a specific project/cwd
+ */
+declare function getProjectSessionsDir(cwd: string, appName?: string): string;
+
+/**
+ * Agent Presets — Reusable Configuration Profiles
+ *
+ * Presets are domain-agnostic agent configurations that can be applied
+ * to `fork()` calls. They control tool selection, system prompt,
+ * temperature, and other parameters.
+ *
+ * Design principles:
+ * 1. **Composable** — Merge multiple presets: `mergePresets(explore, careful)`
+ * 2. **Pattern-based** — Filter tools with glob patterns: `allowTools: ["read*"]`
+ * 3. **Embeddable** — No coupling to CLI, file system, or any specific domain
+ *
+ * @example
+ * ```typescript
+ * import { Presets, applyPreset } from "@cuylabs/agent-core";
+ *
+ * // Apply a built-in preset
+ * const explorer = agent.fork(applyPreset(Presets.explore, agent.getTools()));
+ * const result = await explorer.run({ message: "Find relevant components" });
+ *
+ * // Create a custom preset
+ * const myPreset: Preset = {
+ *   name: "analyst",
+ *   description: "Read-only analytical mode",
+ *   allowTools: ["read*", "grep*", "search*"],
+ *   denyTools: ["write*", "exec*"],
+ *   systemPrompt: "Analyse thoroughly and report findings.",
+ *   temperature: 0.1,
+ * };
+ * ```
+ */
+
+/**
+ * Agent preset - a reusable configuration profile
+ *
+ * Presets define specialized behavior without coupling to specific tools.
+ * Tool filtering uses glob-like patterns that match at runtime.
+ */
+interface Preset {
+    /** Unique identifier for this preset */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /**
+     * Tool allow patterns (glob-like).
+     * If provided, only tools matching these patterns are allowed.
+     * Patterns support: `*` (any chars), `?` (single char)
+     *
+     * @example ["read*", "search*", "glob*"] - Read-only tools
+     * @example ["*"] - All tools
+     */
+    allowTools?: string[];
+    /**
+     * Tool deny patterns (glob-like).
+     * Tools matching these patterns are excluded (applied AFTER allow).
+     *
+     * @example ["bash*", "write*", "delete*"] - Deny destructive tools
+     */
+    denyTools?: string[];
+    /**
+     * Override system prompt.
+     * Use `{basePrompt}` placeholder to include parent's system prompt.
+     *
+     * @example "{basePrompt}\n\nYou are in exploration mode. Be thorough."
+     */
+    systemPrompt?: string;
+    /**
+     * Override temperature (0-1).
+     * Lower = more deterministic, higher = more creative.
+     */
+    temperature?: number;
+    /**
+     * Override max steps.
+     */
+    maxSteps?: number;
+    /**
+     * Override reasoning level.
+     */
+    reasoningLevel?: ReasoningLevel;
+    /**
+     * Override model.
+     * Useful for using cheaper models for simple tasks.
+     */
+    model?: LanguageModel;
+}
+/**
+ * Result of applying a preset - ready for fork()
+ */
+interface AppliedPreset {
+    name: string;
+    systemPrompt?: string;
+    tools?: Tool$1.AnyInfo[];
+    maxSteps?: number;
+    reasoningLevel?: ReasoningLevel;
+    model?: LanguageModel;
+}
+/**
+ * Filter tools based on allow/deny patterns
+ *
+ * Patterns match against tool IDs (the first argument to Tool.define).
+ */
+declare function filterTools(tools: Tool$1.AnyInfo[], options: {
+    allow?: string[];
+    deny?: string[];
+}): Tool$1.AnyInfo[];
+/**
+ * Apply a preset to create fork() options
+ *
+ * Takes a preset definition and the available tools, returns options
+ * ready for agent.fork().
+ *
+ * @param preset - The preset configuration
+ * @param availableTools - All tools from the parent agent
+ * @param baseSystemPrompt - Parent's system prompt (for {basePrompt} substitution)
+ * @returns Options object for agent.fork()
+ *
+ * @example
+ * ```typescript
+ * // Apply the explore preset
+ * const options = applyPreset(Presets.explore, agent.getTools(), agent.systemPrompt);
+ * const explorer = agent.fork(options);
+ * ```
+ */
+declare function applyPreset(preset: Preset, availableTools: Tool$1.AnyInfo[], baseSystemPrompt?: string): AppliedPreset;
+/**
+ * Merge multiple presets (later presets override earlier ones)
+ *
+ * Tool patterns are combined:
+ * - allowTools: intersection (only tools matching ALL presets)
+ * - denyTools: union (deny if ANY preset denies)
+ *
+ * @example
+ * ```typescript
+ * // Combine explore (read-only) with careful (low temp)
+ * const merged = mergePresets(Presets.explore, Presets.careful);
+ * ```
+ */
+declare function mergePresets(...presets: Preset[]): Preset;
+/**
+ * All built-in presets
+ */
+declare const Presets: {
+    readonly explore: Preset;
+    readonly plan: Preset;
+    readonly review: Preset;
+    readonly quick: Preset;
+    readonly careful: Preset;
+};
+/**
+ * Create a custom preset with defaults
+ */
+declare function createPreset(options: Partial<Preset> & {
+    name: string;
+}): Preset;
+
+/**
+ * Turn Change Tracker - Per-turn file modification tracking
+ *
+ * Tracks file changes within a single agent turn for undo/diff capabilities.
+ * Unlike checkpoints (which are session-level snapshots), this provides
+ * granular per-turn tracking with minimal overhead - only touched files
+ * are captured.
+ *
+ * Inspired by OpenCode's Snapshot system and Codex's TurnDiffTracker.
+ *
+ * @example
+ * ```typescript
+ * const tracker = createTurnTracker({ cwd: '/project' });
+ *
+ * // Start tracking a turn
+ * tracker.startTurn('turn-1');
+ *
+ * // Before modifying a file (auto-called by wrapped tools)
+ * await tracker.beforeWrite('/project/src/foo.ts');
+ *
+ * // ... tool makes changes ...
+ *
+ * // End turn and get summary
+ * const summary = await tracker.endTurn();
+ * console.log(summary.diff); // Unified diff of all changes
+ *
+ * // Or undo all changes from this turn
+ * await tracker.undoTurn();
+ * ```
+ */
+/** Configuration for turn tracker */
+interface TurnTrackerConfig {
+    /** Working directory (absolute path) - all paths resolved relative to this */
+    cwd: string;
+    /** Whether to use git for diffs (requires git repo). Default: auto-detect */
+    useGit?: boolean;
+    /** Maximum files to track per turn (prevents memory issues). Default: 100 */
+    maxTrackedFiles?: number;
+}
+/** File baseline captured before modification */
+interface FileBaseline {
+    /** Absolute path */
+    path: string;
+    /** Content before modification (null if file didn't exist) */
+    content: string | null;
+    /** File mode (permissions) */
+    mode: number | null;
+    /** Hash of original content for quick comparison */
+    hash: string | null;
+    /** When baseline was captured */
+    capturedAt: Date;
+}
+/** Single file change within a turn */
+interface TurnFileChange {
+    /** Relative path (from cwd) */
+    path: string;
+    /** Type of change */
+    type: "created" | "modified" | "deleted" | "unchanged";
+    /** Lines added */
+    additions: number;
+    /** Lines removed */
+    deletions: number;
+    /** Unified diff for this file */
+    diff?: string;
+}
+/** Summary of a completed turn */
+interface TurnSummary {
+    /** Turn identifier */
+    turnId: string;
+    /** Files changed */
+    files: TurnFileChange[];
+    /** Total files tracked */
+    totalTracked: number;
+    /** Total additions across all files */
+    additions: number;
+    /** Total deletions across all files */
+    deletions: number;
+    /** Combined unified diff for all changes */
+    diff: string | null;
+    /** Turn duration in ms */
+    duration: number;
+}
+/** Result of undo operation */
+interface UndoResult {
+    /** Files restored */
+    restored: string[];
+    /** Files that couldn't be restored (with reasons) */
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+
+/** Extended tool metadata with file operation info */
+interface TrackedToolMetadata {
+    /** File operation metadata for auto-tracking */
+    fileOps?: FileOperationMeta;
+    /** Other metadata */
+    [key: string]: unknown;
+}
+/**
+ * Turn Change Tracker
+ *
+ * Maintains in-memory baselines of files before they're modified,
+ * enabling diffs and undo for the current turn.
+ */
+declare class TurnChangeTracker {
+    private config;
+    private currentTurn;
+    private gitRoot;
+    private gitDetected;
+    constructor(config: TurnTrackerConfig);
+    /**
+     * Start tracking a new turn.
+     * Clears any baselines from previous turn.
+     */
+    startTurn(turnId: string): void;
+    /**
+     * End the current turn and get a summary of changes.
+     * After this, baselines are kept until next startTurn().
+     */
+    endTurn(): Promise<TurnSummary>;
+    /**
+     * Check if currently in an active turn
+     */
+    isInTurn(): boolean;
+    /**
+     * Get current turn ID (if active)
+     */
+    getCurrentTurnId(): string | null;
+    /**
+     * Capture baseline for a file BEFORE it's modified.
+     * Call this before any write/delete operation.
+     * Returns true if baseline was captured, false if already tracked or limit reached.
+     */
+    beforeWrite(filePath: string): Promise<boolean>;
+    /**
+     * Get list of files being tracked in current turn
+     */
+    getTrackedFiles(): string[];
+    /**
+     * Check if a specific file is being tracked
+     */
+    isTracking(filePath: string): boolean;
+    /**
+     * Get unified diff for all changes in current turn.
+     * Can be called before endTurn() for live preview.
+     */
+    getDiff(): Promise<string | null>;
+    /**
+     * Get diff for a single file
+     */
+    getFileDiff(filePath: string): Promise<string | null>;
+    /**
+     * Undo all changes from current turn - restore all files to baseline state
+     */
+    undoTurn(): Promise<UndoResult>;
+    /**
+     * Undo changes to specific files only
+     */
+    undoFiles(filePaths: string[]): Promise<UndoResult>;
+    /** Capture current state of a file as baseline */
+    private captureBaseline;
+    /** Restore a file to its baseline state */
+    private restoreFile;
+    /** Compute change info for a single file */
+    private computeFileChange;
+    /** Generate unified diff between old and new content */
+    private generateDiff;
+    /** Simple unified diff implementation */
+    private simpleDiff;
+    /**
+     * Generate diff using git (placeholder for future enhancement)
+     *
+     * Note: git diff --no-index requires two files on disk, which makes
+     * it tricky to use with in-memory content. For now, we always use
+     * the simple diff implementation. A future enhancement could write
+     * temp files or use a proper diff library like 'diff' from npm.
+     */
+    private gitDiff;
+    /** Check if we're in a git repository */
+    private isInGitRepo;
+    /** Count additions and deletions from a diff string */
+    private countDiffStats;
+    /** Hash content for quick comparison */
+    private hashContent;
+}
+/**
+ * Create a new turn change tracker
+ */
+declare function createTurnTracker(config: TurnTrackerConfig): TurnChangeTracker;
+/**
+ * Extract file paths from tool arguments based on metadata
+ */
+declare function extractFilePathsFromArgs(args: Record<string, unknown>, meta: FileOperationMeta): string[];
+/**
+ * Check if a tool operation should trigger baseline capture
+ */
+declare function shouldCaptureBaseline(meta: FileOperationMeta): boolean;
+/**
+ * Wrap a tool execute function with automatic file tracking
+ */
+declare function withFileTracking<T extends (...args: unknown[]) => Promise<unknown>>(tracker: TurnChangeTracker, meta: FileOperationMeta, execute: T): T;
+
+/**
+ * Prompt Templates — Base system prompts per model family
+ *
+ * agent-core provides **generic, domain-agnostic** templates.
+ * These establish the agent's general approach and tool-use discipline
+ * without assuming a specific domain (coding, browsing, etc.).
+ *
+ * Domain-specific templates belong in consumer packages:
+ * - agent-code → coding templates ("read files before editing", etc.)
+ * - computer-agent → computer-use templates
+ * - your-custom-agent → whatever you need
+ *
+ * Consumer packages inject their templates via:
+ *   createPromptBuilder({ baseTemplate: MY_CODING_TEMPLATE })
+ *   builder.addSection({ id: "coding", ... })
+ *
+ * This file also contains model family detection, which IS infrastructure
+ * and belongs here — any consumer benefits from knowing the model family
+ * to optimize prompt formatting.
+ */
+
+/**
+ * Detect which model family a LanguageModel belongs to.
+ *
+ * Uses the provider string first (most reliable), then falls back
+ * to pattern matching on the model ID.
+ *
+ * @example
+ * ```typescript
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * detectModelFamily(anthropic("claude-sonnet-4-20250514")); // "anthropic"
+ *
+ * import { openai } from "@ai-sdk/openai";
+ * detectModelFamily(openai("gpt-4o")); // "openai"
+ * ```
+ */
+declare function detectModelFamily(model: LanguageModel): ModelFamily;
+/**
+ * Get the base template for a model family.
+ *
+ * @param family - Model family identifier
+ * @returns The generic system prompt template
+ */
+declare function getTemplate(family: ModelFamily): string;
+/**
+ * Get all available template families.
+ * Useful for debugging or letting users choose.
+ */
+declare function getAvailableFamilies(): ModelFamily[];
+
+/**
+ * Environment Block — Runtime context for the system prompt
+ *
+ * Gathers information about the working environment (cwd, platform,
+ * git status, date, shell) and formats it as a structured block
+ * that gets injected into the prompt at priority 20.
+ *
+ * This gives the model awareness of:
+ * - Where it's working (directory, project)
+ * - What platform it's on (affects path separators, commands)
+ * - Current time (useful for time-sensitive tasks)
+ * - Git state (branch, clean/dirty)
+ */
+
+/**
+ * Gather runtime environment information.
+ *
+ * Collects cwd, platform, git status, date, and shell.
+ * Git commands use a short timeout to avoid hanging on slow repos.
+ *
+ * @param cwd - Working directory to gather info for
+ * @returns Environment info object
+ */
+declare function gatherEnvironment(cwd: string): EnvironmentInfo;
+/**
+ * Format environment info as a prompt-friendly block.
+ *
+ * Output example:
+ * ```
+ * <workspace>
+ * Directory: /Users/dev/my-project
+ * Project: my-project
+ * Platform: macOS (darwin arm64)
+ * Date: Saturday, February 8, 2026
+ * Shell: /bin/zsh
+ * Git: main (clean)
+ * </workspace>
+ * ```
+ */
+declare function formatEnvironment(info: EnvironmentInfo): string;
+/**
+ * Create a short one-line summary of the environment.
+ * Useful for compact contexts or logging.
+ */
+declare function summarizeEnvironment(info: EnvironmentInfo): string;
+
+/**
+ * Instruction File Discovery — Project rules from the filesystem
+ *
+ * Discovers instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.)
+ * by walking up the directory tree from cwd. These files provide
+ * project-specific or workspace-level guidance to the agent.
+ *
+ * Discovery order (general → specific):
+ * 1. Global instruction files (from config)
+ * 2. Workspace-level files (found near git root or higher directories)
+ * 3. Project-level files (found in or near cwd)
+ *
+ * All discovered files are included, ordered from most general to most
+ * specific. This means project-level instructions appear last and
+ * effectively take precedence in case of conflicting guidance.
+ *
+ * Compatible with:
+ * - OpenCode's AGENTS.md convention
+ * - Claude's CLAUDE.md convention
+ * - GitHub Copilot's COPILOT.md convention
+ * - CuyLabs' own .cuylabs/instructions.md
+ */
+
+/**
+ * Default file patterns to search for.
+ * Checked in each directory when walking up from cwd.
+ */
+declare const DEFAULT_INSTRUCTION_PATTERNS: string[];
+/**
+ * Maximum file size for instruction files (50KB).
+ * Files larger than this are skipped to prevent prompt bloat.
+ */
+declare const DEFAULT_MAX_FILE_SIZE = 51200;
+/**
+ * Maximum directories to walk up from cwd.
+ */
+declare const DEFAULT_MAX_DEPTH = 10;
+/**
+ * Discover instruction files by walking up the directory tree from cwd.
+ *
+ * Searches for files matching the given patterns in each directory,
+ * starting from `cwd` and walking up to the filesystem root (or until
+ * `maxDepth` is reached).
+ *
+ * Results are ordered from **most general** (shallowest/root-level) to
+ * **most specific** (deepest/cwd-level), so that specific project rules
+ * appear last and take natural precedence.
+ *
+ * @param cwd - Starting directory for the search
+ * @param patterns - File name patterns to look for (e.g. ["AGENTS.md"])
+ * @param options - Discovery options
+ * @returns Array of discovered instruction files, general → specific
+ *
+ * @example
+ * ```typescript
+ * const files = await discoverInstructions("/Users/dev/project/src", [
+ *   "AGENTS.md",
+ *   "CLAUDE.md",
+ * ]);
+ *
+ * // Might find:
+ * // 1. /Users/dev/project/AGENTS.md (depth: 1, workspace)
+ * // 2. /Users/dev/project/src/AGENTS.md (depth: 0, project)
+ * ```
+ */
+declare function discoverInstructions(cwd: string, patterns?: string[], options?: {
+    maxDepth?: number;
+    maxFileSize?: number;
+    stopAtGitRoot?: boolean;
+}): Promise<InstructionFile[]>;
+/**
+ * Load global instruction files from explicit paths.
+ *
+ * Global instructions are always included regardless of cwd.
+ * Useful for organization-wide coding standards or team rules.
+ *
+ * @param paths - Absolute paths to global instruction files
+ * @param maxSize - Maximum file size in bytes
+ * @returns Array of loaded instruction files
+ */
+declare function loadGlobalInstructions(paths: string[], maxSize?: number): Promise<InstructionFile[]>;
+/**
+ * Format discovered instruction files into a prompt block.
+ *
+ * Each file is wrapped in a tagged block with its source path
+ * for transparency. Files are already ordered general → specific.
+ *
+ * Output example:
+ * ```
+ * <project-instructions>
+ *
+ * <instructions source="AGENTS.md" scope="workspace">
+ * ... workspace-level content ...
+ * </instructions>
+ *
+ * <instructions source="src/AGENTS.md" scope="project">
+ * ... project-specific content ...
+ * </instructions>
+ *
+ * </project-instructions>
+ * ```
+ */
+declare function formatInstructions(files: InstructionFile[], basePath?: string): string;
+
+/**
+ * PromptBuilder — The pipeline orchestrator
+ *
+ * Assembles a system prompt from composable layers:
+ *
+ *   ┌──────────────────┐
+ *   │  Base Template    │  priority 10 — model-family-specific guidelines
+ *   ├──────────────────┤
+ *   │  Environment      │  priority 20 — cwd, platform, git, date
+ *   ├──────────────────┤
+ *   │  Instructions     │  priority 30 — AGENTS.md, CLAUDE.md files
+ *   ├──────────────────┤
+ *   │  Custom Sections  │  priority 50 — user-defined content
+ *   ├──────────────────┤
+ *   │  (Skills slot)    │  priority 70 — reserved for future skill injection
+ *   ├──────────────────┤
+ *   │  Per-Turn Override │  priority 90 — session-specific context
+ *   └──────────────────┘
+ *
+ * Each layer is optional. Sections are sorted by priority (lower = earlier)
+ * and composed into a single string.
+ *
+ * @example
+ * ```typescript
+ * import { createPromptBuilder } from "@cuylabs/agent-core";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ *
+ * const builder = createPromptBuilder({
+ *   includeEnvironment: true,
+ *   includeInstructions: true,
+ * });
+ *
+ * const prompt = await builder.build({
+ *   cwd: "/path/to/project",
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ * });
+ * ```
+ */
+
+/** Priority for the base template section */
+declare const PRIORITY_BASE = 10;
+/** Priority for the environment block section */
+declare const PRIORITY_ENVIRONMENT = 20;
+/** Priority for instruction files section */
+declare const PRIORITY_INSTRUCTIONS = 30;
+/** Priority for custom user-defined sections (default) */
+declare const PRIORITY_CUSTOM = 50;
+/** Priority reserved for future skill injections */
+declare const PRIORITY_SKILLS = 70;
+/** Priority for per-turn override content */
+declare const PRIORITY_OVERRIDE = 90;
+/**
+ * PromptBuilder composes system prompts from layered sections.
+ *
+ * It handles:
+ * - Automatic model family detection and template selection
+ * - Runtime environment injection (cwd, git, platform)
+ * - Instruction file discovery (AGENTS.md, etc.)
+ * - Custom section management (add/remove/toggle)
+ * - Caching to avoid repeated filesystem I/O
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder();
+ *
+ * // Add a custom section
+ * builder.addSection({
+ *   id: "safety",
+ *   label: "Safety Rules",
+ *   content: "Never delete files without explicit confirmation.",
+ *   priority: 40,
+ * });
+ *
+ * const prompt = await builder.build({
+ *   cwd: "/my/project",
+ *   model: myModel,
+ * });
+ * ```
+ */
+declare class PromptBuilder {
+    private readonly config;
+    /** User-added sections (persist across builds) */
+    private customSections;
+    /** Cached environment info */
+    private envCache?;
+    /** Cached instruction files */
+    private instructionCache?;
+    constructor(config?: PromptConfig);
+    /**
+     * Build the complete system prompt from all active layers.
+     *
+     * This is the main entry point. Call it before each LLM request
+     * to get a fully composed system prompt with all context.
+     *
+     * Sections are sorted by priority (lower = earlier) and joined
+     * with the configured separator.
+     *
+     * @param context - Build context with cwd, model, and optional override
+     * @returns The composed system prompt string
+     */
+    build(context: PromptBuildContext): Promise<string>;
+    /**
+     * Add or replace a custom section.
+     *
+     * Custom sections persist across builds. Use this to inject
+     * context that should be present in every prompt (e.g. team rules,
+     * project constraints, skill content).
+     *
+     * @param section - The section to add
+     *
+     * @example
+     * ```typescript
+     * builder.addSection({
+     *   id: "no-delete",
+     *   label: "File Safety",
+     *   content: "Never delete files without asking the user first.",
+     *   priority: 40,
+     * });
+     * ```
+     */
+    addSection(section: PromptSection): void;
+    /**
+     * Remove a custom section by its ID.
+     *
+     * @param id - Section ID to remove
+     * @returns true if a section was removed
+     */
+    removeSection(id: string): boolean;
+    /**
+     * Toggle a custom section on or off without removing it.
+     *
+     * @param id - Section ID to toggle
+     * @param enabled - Whether the section should be active
+     */
+    toggleSection(id: string, enabled: boolean): void;
+    /**
+     * Get all currently registered sections (including auto-generated labels).
+     * Useful for debugging or building UIs that show prompt composition.
+     *
+     * @returns Array of all custom sections
+     */
+    getSections(): PromptSection[];
+    /**
+     * Check if a section with the given ID exists.
+     */
+    hasSection(id: string): boolean;
+    /**
+     * Clear all cached data (environment info, discovered instructions).
+     *
+     * Call this when:
+     * - The working directory changes
+     * - Instruction files are modified
+     * - You want to force a refresh on the next build()
+     */
+    clearCache(): void;
+    /**
+     * Get the model family that would be used for a given model.
+     * Useful for debugging template selection.
+     */
+    getModelFamily(model: PromptBuildContext["model"]): ModelFamily;
+    /**
+     * Get the base template that would be used for a given model.
+     */
+    getBaseTemplate(model: PromptBuildContext["model"]): string;
+    /**
+     * Preview the sections that would be generated for a given context.
+     * Returns section metadata without the full content (for logging/debugging).
+     */
+    preview(context: PromptBuildContext): Promise<Array<{
+        id: string;
+        label: string;
+        priority: number;
+        size: number;
+    }>>;
+    /**
+     * Get environment info, using cache if available for the same cwd.
+     */
+    private getEnvironment;
+    /**
+     * Get instruction files, using cache if available for the same cwd.
+     */
+    private getInstructions;
+}
+/**
+ * Create a new PromptBuilder instance.
+ *
+ * This is the recommended way to create a builder. It accepts
+ * an optional configuration and returns a ready-to-use instance.
+ *
+ * @param config - Optional pipeline configuration
+ * @returns A new PromptBuilder
+ *
+ * @example
+ * ```typescript
+ * // Full pipeline with defaults
+ * const builder = createPromptBuilder();
+ *
+ * // Custom configuration
+ * const builder = createPromptBuilder({
+ *   includeEnvironment: true,
+ *   includeInstructions: true,
+ *   modelFamily: "anthropic",
+ *   sections: [
+ *     { id: "team", label: "Team Rules", content: "Use TypeScript strict mode." },
+ *   ],
+ * });
+ *
+ * // Build a prompt
+ * const systemPrompt = await builder.build({
+ *   cwd: process.cwd(),
+ *   model: myModel,
+ * });
+ * ```
+ */
+declare function createPromptBuilder(config?: PromptConfig): PromptBuilder;
+
+/**
+ * Intervention Controller for @cuylabs/agent-core
+ *
+ * Manages mid-turn message injection into running agent turns.
+ * Uses Vercel AI SDK v6's `prepareStep` hook for zero-overhead
+ * integration at step boundaries (between LLM calls in a multi-step turn).
+ *
+ * Instead of polling a queue after each tool execution (like pi-mono's
+ * "steering"), this leverages the SDK's native step lifecycle. The
+ * `prepareStep` callback fires before every LLM call, giving us a
+ * natural injection point with no custom loop machinery.
+ *
+ * Two injection modes:
+ * - **Immediate**: `intervene(msg)` — injected at the next step boundary
+ * - **Deferred**: `queueNext(msg)` — held until the turn completes
+ */
+/** A queued intervention message waiting to be applied */
+interface PendingIntervention {
+    /** Unique identifier for tracking */
+    readonly id: string;
+    /** The user message to inject */
+    readonly message: string;
+    /** When the intervention was created */
+    readonly createdAt: Date;
+}
+/**
+ * Callback fired when an intervention is applied to a step.
+ *
+ * The agent uses this to push `intervention-applied` events into
+ * the streaming event queue so they reach the consumer in the
+ * correct order relative to other events.
+ */
+type OnInterventionApplied = (intervention: PendingIntervention) => void;
+/**
+ * Manages mid-turn message injection for agents.
+ *
+ * This is the core primitive that connects user redirection intent
+ * to the AI SDK's multi-step loop. The flow:
+ *
+ * 1. Consumer calls `agent.intervene("focus on auth.ts")` from any async context
+ * 2. The message is queued as a `PendingIntervention`
+ * 3. At the next step boundary, `prepareStep` drains the queue
+ * 4. The message is appended to the LLM's input messages
+ * 5. The LLM responds to the redirect naturally
+ *
+ * Thread safety: All operations are synchronous and run on the
+ * same event loop. No locks needed — Node.js guarantees ordering.
+ *
+ * @example
+ * ```typescript
+ * const ctrl = new InterventionController();
+ *
+ * // Queue an intervention (from a UI handler, WebSocket, etc.)
+ * const id = ctrl.intervene("stop refactoring, fix the failing test first");
+ *
+ * // Later, in prepareStep:
+ * const pending = ctrl.drainImmediate();
+ * // → [{ id, message: "stop refactoring...", createdAt }]
+ * ```
+ */
+declare class InterventionController {
+    /** Immediate interventions — applied at the next step boundary */
+    private immediate;
+    /** Deferred messages — held until the turn completes */
+    private deferred;
+    /**
+     * Callback fired when an intervention is wired into a step.
+     * Set by the Agent before starting a chat turn, cleared after.
+     */
+    onApplied?: OnInterventionApplied;
+    /**
+     * Inject a message at the next LLM step boundary.
+     *
+     * The message is appended as a user message to the conversation
+     * before the next LLM call in the current multi-step turn. The
+     * LLM will see it and can adjust its behavior accordingly.
+     *
+     * Safe to call from any async context while `chat()` is running.
+     * If called when no turn is active, the message will be picked up
+     * by the first step of the next `chat()` call.
+     *
+     * @param message - The user message to inject
+     * @returns Intervention ID for tracking
+     */
+    intervene(message: string): string;
+    /**
+     * Drain and return all pending immediate interventions.
+     * The internal queue is cleared atomically.
+     *
+     * @internal Called by the LLM stream's `prepareStep` hook
+     */
+    drainImmediate(): PendingIntervention[];
+    /** Whether there are pending immediate interventions */
+    get hasPending(): boolean;
+    /** Number of pending immediate interventions */
+    get pendingCount(): number;
+    /**
+     * Queue a message for after the current turn completes.
+     *
+     * Unlike `intervene()`, this does **not** inject mid-turn. The
+     * message is held and available via `drainDeferred()` after
+     * `chat()` finishes. The consumer decides whether to send it
+     * as a new turn.
+     *
+     * @param message - The message to queue
+     * @returns Intervention ID for tracking
+     */
+    queueNext(message: string): string;
+    /**
+     * Drain and return all deferred messages.
+     * The internal queue is cleared atomically.
+     */
+    drainDeferred(): PendingIntervention[];
+    /** Whether there are deferred messages */
+    get hasDeferred(): boolean;
+    /** Number of deferred messages */
+    get deferredCount(): number;
+    /** Clear all queues (immediate + deferred) */
+    clear(): void;
+    /** Reset the controller for a new turn (clears onApplied, keeps queues) */
+    resetCallbacks(): void;
+}
+
+/**
+ * Sub-agent run result
+ */
+interface SubAgentResult {
+    /** Final response text */
+    response: string;
+    /** Sub-agent session ID */
+    sessionId: string;
+    /** Token usage */
+    usage: TokenUsage;
+    /** Tool calls made */
+    toolCalls: Array<{
+        name: string;
+        result: unknown;
+    }>;
+}
+/**
+ * Create an agent instance
+ */
+declare function createAgent(config: AgentConfig & {
+    tools?: Tool$1.AnyInfo[];
+    sessionManager?: SessionManager;
+}): Agent;
+/**
+ * Run multiple sub-agent tasks concurrently.
+ *
+ * Useful for parallelizing independent research or analysis tasks.
+ * Results are returned in the same order as tasks.
+ *
+ * **IMPORTANT: Concurrency Considerations**
+ *
+ * When multiple tasks use the same `Agent` instance, they share the same
+ * `SessionManager`. To avoid state conflicts:
+ *
+ * 1. Use distinct `parentSessionId` values for each task
+ * 2. Or create separate `Agent` instances via `agent.fork()` for each task
+ * 3. Or ensure tasks use unique session IDs (auto-generated if not specified)
+ *
+ * Tasks modifying the same session concurrently may cause race conditions.
+ *
+ * @example
+ * ```typescript
+ * const explorer = agent.fork({ name: "explore", ... });
+ *
+ * const results = await runConcurrent([
+ *   { agent: explorer, message: "Find all API endpoints" },
+ *   { agent: explorer, message: "Find all database queries" },
+ *   { agent: explorer, message: "Find all auth middleware" },
+ * ], { maxConcurrency: 3 });
+ * ```
+ */
+declare function runConcurrent(tasks: Array<{
+    agent: Agent;
+    message: string;
+    parentSessionId?: string;
+    title?: string;
+}>, options?: {
+    /** Maximum concurrent tasks (default: 5) */
+    maxConcurrency?: number;
+    /** Abort signal for all tasks */
+    abort?: AbortSignal;
+}): Promise<SubAgentResult[]>;
+/**
+ * Embeddable AI agent with tool support.
+ *
+ * The `Agent` class is the main entry-point for consumers. It manages:
+ * - **Sessions** — persistent conversation history
+ * - **Streaming** — real-time event generation via `chat()`
+ * - **Tools** — registry + execution context
+ * - **Context management** — overflow detection & auto-compaction
+ * - **Reasoning** — configurable thinking levels per model
+ * - **Sub-agents** — `fork()` / `run()` for parallel or specialised tasks
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from "@cuylabs/agent-core";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   cwd: "/path/to/project",
+ * });
+ *
+ * // Streaming
+ * for await (const event of agent.chat("session-1", "List all TypeScript files")) {
+ *   if (event.type === "text-delta") process.stdout.write(event.text);
+ * }
+ *
+ * // Non-streaming (convenience)
+ * const result = await agent.send("session-1", "Fix the bug in utils.ts");
+ * console.log(result.response);
+ * ```
+ */
+declare class Agent {
+    private config;
+    private tools;
+    private sessions;
+    private loadedSessions;
+    private state;
+    /** Context manager for overflow detection and compaction */
+    private contextManager;
+    /** Tools that user said "remember" for doom loop (don't ask again) */
+    private rememberedDoomLoopTools;
+    /** Turn change tracker for file modification tracking */
+    private turnTracker;
+    /** Counter for turn IDs */
+    private turnCounter;
+    /** MCP manager for external tool servers */
+    private mcpManager?;
+    /** Whether MCP has been connected (lazy init) */
+    private mcpConnected;
+    /** Cached MCP tools (refreshed on connect) */
+    private mcpToolsCache?;
+    /** Prompt pipeline builder (when using layered prompt mode) */
+    private promptBuilder?;
+    /** Intervention controller for mid-turn message injection */
+    private interventionCtrl;
+    /** Execution environment for tool operations */
+    private host;
+    constructor(config: AgentConfig & {
+        tools?: Tool$1.AnyInfo[];
+        sessionManager?: SessionManager;
+    });
+    /** Working directory for file operations */
+    get cwd(): string;
+    /** Current model */
+    get model(): LanguageModel;
+    /** System prompt */
+    get systemPrompt(): string;
+    /** Is currently streaming */
+    get isStreaming(): boolean;
+    /** Current reasoning level */
+    get reasoningLevel(): ReasoningLevel;
+    /**
+     * Set reasoning level
+     * Will be clamped to available levels for the current model
+     */
+    setReasoningLevel(level: ReasoningLevel): void;
+    /**
+     * Get available reasoning levels for the current model
+     */
+    getAvailableReasoningLevels(): ReasoningLevel[];
+    /**
+     * Check if current model supports reasoning
+     */
+    supportsReasoning(): boolean;
+    /**
+     * Ensure MCP is connected and return tools
+     * Lazy initialization - only connects on first use
+     */
+    private ensureMCPConnected;
+    /**
+     * Repair session history by synthesising missing tool-result messages.
+     *
+     * When a tool `execute()` throws, the AI SDK emits `tool-error` instead
+     * of `tool-result`. If the error event wasn't persisted (e.g. because
+     * the fix above wasn't in place), subsequent turns will fail with
+     * `MissingToolResultsError`. This method detects orphaned tool-call IDs
+     * and adds placeholder `tool` messages so the history is valid again.
+     */
+    private repairOrphanedToolCalls;
+    /**
+     * Convert internal {@link Message} array to Vercel AI SDK {@link ModelMessage} format.
+     *
+     * Handles the role-specific mappings:
+     * - `user` / `system` → pass-through
+     * - `assistant` with tool calls → `ToolCallPart[]` content
+     * - `tool` → `tool-result` content part
+     */
+    private toModelMessages;
+    /**
+     * Stream a chat response.
+     *
+     * Sends a user message and yields real-time {@link AgentEvent}s as the
+     * model responds, calls tools, and finishes. Conversation state is
+     * persisted to the session automatically.
+     *
+     * @param sessionId - Session identifier for conversation history
+     * @param message   - User message to send
+     * @param options   - Abort signal, system prompt override, and approval handler
+     * @yields {AgentEvent} Events as they occur during processing
+     */
+    chat(sessionId: string, message: string, options?: {
+        abort?: AbortSignal;
+        system?: string;
+        onApproval?: (request: {
+            tool: string;
+            args: unknown;
+            description: string;
+        }) => Promise<"allow" | "deny">;
+    }): AsyncGenerator<AgentEvent>;
+    /**
+     * Ensure a session is loaded or created
+     */
+    private ensureSession;
+    /**
+     * Send a message and wait for the complete response (non-streaming).
+     *
+     * This is a convenience wrapper around {@link chat} that buffers all
+     * events internally and returns the final response, usage, and tool
+     * call results. Prefer `chat()` when you need real-time streaming.
+     *
+     * @param sessionId - Session identifier
+     * @param message   - User message
+     * @param options   - Abort signal and optional system prompt override
+     */
+    send(sessionId: string, message: string, options?: {
+        abort?: AbortSignal;
+        system?: string;
+    }): Promise<{
+        response: string;
+        usage: TokenUsage;
+        toolCalls: Array<{
+            name: string;
+            result: unknown;
+        }>;
+    }>;
+    /** Add a tool at runtime */
+    addTool(tool: Tool$1.Info): void;
+    /** Remove a tool by ID */
+    removeTool(toolId: string): boolean;
+    /** Get all tool IDs */
+    getToolIds(): string[];
+    /** Get all tools */
+    getTools(): Tool$1.AnyInfo[];
+    /** Check if a tool exists */
+    hasTool(toolId: string): boolean;
+    /** Get session manager */
+    getSessionManager(): SessionManager;
+    /** Get current session context */
+    getSessionContext(): SessionContext;
+    /** Get messages from current session */
+    getMessages(): Message[];
+    /** Delete a session */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /** List all sessions */
+    listSessions(): Promise<SessionInfo[]>;
+    /** Branch from current point */
+    branch(summary?: string): Promise<string>;
+    /**
+     * Get context window statistics.
+     *
+     * Useful for UI to display context utilization like:
+     * - Progress bar showing how full the context is
+     * - Warning when approaching limit
+     * - Info about when compaction will trigger
+     *
+     * @example
+     * ```typescript
+     * const stats = agent.getContextStats();
+     * console.log(`Context: ${stats.utilizationPercent}% used`);
+     * if (stats.shouldPrune) {
+     *   console.log('Context will be compacted soon');
+     * }
+     * ```
+     */
+    getContextStats(): {
+        tokens: number;
+        limit: number;
+        available: number;
+        utilizationPercent: number;
+        isOverflowing: boolean;
+        shouldPrune: boolean;
+    };
+    /**
+     * Manually trigger context compaction.
+     *
+     * Usually auto-compaction handles this, but you can trigger it manually
+     * if needed (e.g., before a long operation).
+     *
+     * @returns Pruning result with details about what was removed/summarized
+     */
+    compactContext(): Promise<{
+        removedCount: number;
+        tokensRemoved: number;
+        summarized: boolean;
+        summary?: string;
+    }>;
+    /**
+     * Clear remembered doom loop tools.
+     *
+     * When a user says "remember" for a doom loop, that tool is added
+     * to a set that skips future doom loop checks. Call this to reset.
+     */
+    clearRememberedDoomLoopTools(): void;
+    /**
+     * Inject a message at the next step boundary of a running turn.
+     *
+     * This is the primary redirection mechanism. When the agent is
+     * streaming a multi-step response (calling tools, reasoning, etc.),
+     * this injects a user message before the next LLM call. The LLM
+     * sees the intervention and can adjust its behavior.
+     *
+     * Uses Vercel AI SDK v6's `prepareStep` hook — no polling, no
+     * custom loop code. The SDK handles the injection naturally.
+     *
+     * Safe to call from any async context (UI event handlers, WebSocket
+     * callbacks, timers, etc.) while `chat()` is running.
+     *
+     * If called when no turn is active, the message will be picked up
+     * by the first step of the next `chat()` call.
+     *
+     * @param message - The user message to inject mid-turn
+     * @returns Intervention ID for tracking
+     *
+     * @example
+     * ```typescript
+     * // Start a streaming turn
+     * const stream = agent.chat("session-1", "refactor the auth module");
+     *
+     * // From a UI handler (another async context):
+     * agent.intervene("stop, focus only on JWT validation in auth.ts");
+     *
+     * // The stream will yield an intervention-applied event
+     * for await (const event of stream) {
+     *   if (event.type === "intervention-applied") {
+     *     console.log(`Redirected: ${event.message}`);
+     *   }
+     * }
+     * ```
+     */
+    intervene(message: string): string;
+    /**
+     * Queue a message for after the current turn completes.
+     *
+     * Unlike `intervene()`, this does **not** interrupt the current turn.
+     * The message is held and available via `drainQueuedNext()` after
+     * `chat()` finishes. The consumer decides whether to send it as a
+     * new turn.
+     *
+     * @param message - The message to queue
+     * @returns Intervention ID for tracking
+     *
+     * @example
+     * ```typescript
+     * agent.queueNext("now run the test suite");
+     *
+     * for await (const event of agent.chat("s1", "fix the bug")) {
+     *   // ... handle events
+     * }
+     *
+     * // After turn completes, check for queued messages
+     * if (agent.hasQueuedNext()) {
+     *   const next = agent.drainQueuedNext();
+     *   for (const item of next) {
+     *     // Send as a new turn
+     *     for await (const ev of agent.chat("s1", item.message)) { ... }
+     *   }
+     * }
+     * ```
+     */
+    queueNext(message: string): string;
+    /** Whether there are deferred messages queued for after the turn */
+    hasQueuedNext(): boolean;
+    /** Drain and return all deferred messages (clears the queue) */
+    drainQueuedNext(): PendingIntervention[];
+    /**
+     * Get the raw intervention controller for advanced use cases.
+     *
+     * Use this when you need fine-grained control over the intervention
+     * lifecycle (e.g., checking pending count, clearing queues, setting
+     * custom `onApplied` callbacks).
+     *
+     * @internal
+     */
+    getInterventionController(): InterventionController;
+    /**
+     * Get the unified diff for all file changes in the current/last turn.
+     *
+     * @example
+     * ```typescript
+     * const diff = await agent.getTurnDiff();
+     * if (diff) {
+     *   console.log('Changes this turn:\n', diff);
+     * }
+     * ```
+     */
+    getTurnDiff(): Promise<string | null>;
+    /**
+     * Get list of files being tracked in the current turn.
+     */
+    getTrackedFiles(): string[];
+    /**
+     * Undo all file changes from the current turn.
+     * Restores files to their state before the turn started.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.undoTurn();
+     * console.log(`Restored ${result.restored.length} files`);
+     * if (result.failed.length > 0) {
+     *   console.log('Failed to restore:', result.failed);
+     * }
+     * ```
+     */
+    undoTurn(): Promise<UndoResult>;
+    /**
+     * Undo changes to specific files only.
+     *
+     * @param files - Array of file paths to restore (relative to cwd)
+     */
+    undoFiles(files: string[]): Promise<UndoResult>;
+    /**
+     * Check if currently tracking a turn.
+     */
+    isTrackingTurn(): boolean;
+    /**
+     * Get access to the raw turn tracker for advanced use cases.
+     *
+     * @internal
+     */
+    getTurnTracker(): TurnChangeTracker;
+    /**
+     * Update system prompt.
+     *
+     * If the agent is using the prompt pipeline, calling this switches
+     * to flat string mode (disabling the pipeline). To modify the pipeline
+     * instead, use `getPromptBuilder()`.
+     */
+    setSystemPrompt(prompt: string): void;
+    /** Update working directory */
+    setCwd(cwd: string): void;
+    /** Update model */
+    setModel(model: LanguageModel): void;
+    /**
+     * Get the prompt builder (when using pipeline mode).
+     * Returns undefined if using flat string mode.
+     *
+     * Use this to add/remove sections, clear caches, or inspect
+     * the prompt composition without switching to flat mode.
+     *
+     * @example
+     * ```typescript
+     * const builder = agent.getPromptBuilder();
+     * if (builder) {
+     *   builder.addSection({
+     *     id: "task-context",
+     *     label: "Task Context",
+     *     content: "Focus on fixing authentication bugs.",
+     *     priority: 60,
+     *   });
+     * }
+     * ```
+     */
+    getPromptBuilder(): PromptBuilder | undefined;
+    /**
+     * Check if the agent is using the prompt pipeline.
+     */
+    isUsingPromptPipeline(): boolean;
+    /**
+     * Fork this agent to create a sub-agent with modified configuration.
+     *
+     * Sub-agents share the same session manager but can have different:
+     * - System prompts (specialized for tasks)
+     * - Tools (restricted subset)
+     * - Models (cheaper/faster for simple tasks)
+     * - Reasoning levels
+     *
+     * @example
+     * ```typescript
+     * // Create an exploration sub-agent with read-only tools
+     * const explorer = agent.fork({
+     *   name: "explore",
+     *   systemPrompt: "You explore codebases. Only use read and search tools.",
+     *   tools: [readTool, grepTool, globTool],
+     * });
+     *
+     * // Run the sub-agent
+     * const result = await explorer.run({
+     *   parentSessionId: "main-session",
+     *   message: "Find all API endpoints",
+     * });
+     * ```
+     */
+    fork(options?: {
+        /** Name for the sub-agent (used in session titles) */
+        name?: string;
+        /** Override system prompt (switches to flat string mode) */
+        systemPrompt?: string;
+        /** Override prompt pipeline configuration */
+        prompt?: PromptConfig;
+        /** Override model */
+        model?: LanguageModel;
+        /** Override tools (if not provided, inherits parent's tools) */
+        tools?: Tool$1.AnyInfo[];
+        /** Override max steps */
+        maxSteps?: number;
+        /** Override reasoning level */
+        reasoningLevel?: ReasoningLevel;
+        /** Apply a preset configuration */
+        preset?: Preset;
+    }): Agent;
+    /**
+     * Create a sub-agent with a preset configuration.
+     *
+     * Convenience method that applies a preset and returns a forked agent.
+     *
+     * @example
+     * ```typescript
+     * import { Presets } from "@cuylabs/agent-core";
+     *
+     * // Create an exploration sub-agent
+     * const explorer = agent.withPreset(Presets.explore);
+     * const result = await explorer.run({
+     *   message: "Find all API routes in this project",
+     * });
+     *
+     * // Create a careful review sub-agent
+     * const reviewer = agent.withPreset(Presets.review);
+     * const review = await reviewer.run({
+     *   message: "Review src/auth.ts for security issues",
+     * });
+     * ```
+     */
+    withPreset(preset: Preset): Agent;
+    /**
+     * Run a task in an isolated sub-agent session.
+     *
+     * Creates a new session linked to the parent, runs the task to completion,
+     * and returns the result. The sub-agent session is preserved for inspection.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run({
+     *   parentSessionId: "main-session",
+     *   message: "Review this code for security issues",
+     *   title: "Security Review",
+     * });
+     *
+     * console.log(result.response);
+     * console.log(`Sub-agent session: ${result.sessionId}`);
+     * ```
+     */
+    run(options: {
+        /** Parent session ID (for linking) */
+        parentSessionId?: string;
+        /** The task/message to execute */
+        message: string;
+        /** Title for the sub-agent session */
+        title?: string;
+        /** Abort signal */
+        abort?: AbortSignal;
+    }): Promise<{
+        /** Final response text */
+        response: string;
+        /** Sub-agent session ID */
+        sessionId: string;
+        /** Token usage */
+        usage: TokenUsage;
+        /** Tool calls made */
+        toolCalls: Array<{
+            name: string;
+            result: unknown;
+        }>;
+    }>;
+    /**
+     * Get the MCP manager (if configured)
+     */
+    getMCP(): MCPManager | undefined;
+    /**
+     * Check if MCP is configured
+     */
+    hasMCP(): boolean;
+    /**
+     * Reconnect to MCP servers
+     *
+     * Use this after network issues or when server availability changes.
+     * Clears tool cache and reconnects all servers.
+     */
+    reconnectMCP(): Promise<void>;
+    /**
+     * Close the agent and clean up resources
+     *
+     * Closes MCP connections if configured.
+     * After calling close(), the agent should not be used.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Error classification and handling for @cuylabs/agent-core
+ *
+ * Provides structured error types with retryability detection,
+ * header parsing, and error categorization.
+ */
+/**
+ * Categories of errors that can occur during LLM operations
+ */
+type ErrorCategory = "rate_limit" | "overloaded" | "auth" | "invalid_request" | "context_overflow" | "content_filter" | "network" | "timeout" | "cancelled" | "unknown";
+/**
+ * Determines if an error category is typically retryable
+ */
+declare function isRetryableCategory(category: ErrorCategory): boolean;
+/**
+ * Headers from an API response
+ */
+interface ResponseHeaders {
+    "retry-after"?: string;
+    "retry-after-ms"?: string;
+    "x-ratelimit-remaining"?: string;
+    "x-ratelimit-reset"?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Options for creating an LLMError
+ */
+interface LLMErrorOptions {
+    message: string;
+    category?: ErrorCategory;
+    status?: number;
+    headers?: ResponseHeaders;
+    cause?: Error;
+    provider?: string;
+    model?: string;
+}
+/**
+ * Structured error for LLM operations
+ */
+declare class LLMError extends Error {
+    readonly category: ErrorCategory;
+    readonly status?: number;
+    readonly headers?: ResponseHeaders;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly isRetryable: boolean;
+    readonly retryDelayMs?: number;
+    constructor(options: LLMErrorOptions);
+    /**
+     * Create from an unknown error
+     */
+    static from(error: unknown, context?: Partial<LLMErrorOptions>): LLMError;
+    /**
+     * Human-readable description
+     */
+    get description(): string;
+}
+/**
+ * Check if an error is retryable
+ */
+declare function isRetryable(error: unknown): boolean;
+/**
+ * Get retry delay for an error (returns undefined if not retryable)
+ */
+declare function getRetryDelay(error: unknown): number | undefined;
+/**
+ * Get error category
+ */
+declare function getErrorCategory(error: unknown): ErrorCategory;
+
+/**
+ * Retry logic with exponential backoff for @cuylabs/agent-core
+ *
+ * Provides configurable retry behavior with header-aware delays,
+ * exponential backoff, and abort signal support.
+ */
+
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in ms (default: 2000) */
+    initialDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffFactor?: number;
+    /** Maximum delay without headers in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Whether to jitter delays (default: true) */
+    jitter?: boolean;
+    /** Callback when retrying */
+    onRetry?: (attempt: number, delayMs: number, error: LLMError) => void;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: Required<Omit<RetryConfig, "onRetry">>;
+/**
+ * Tracks retry state across attempts
+ */
+interface RetryState {
+    /** Current attempt number (1-indexed) */
+    attempt: number;
+    /** Total errors encountered */
+    errors: LLMError[];
+    /** Whether more retries are available */
+    canRetry: boolean;
+    /** Delay until next retry (if applicable) */
+    nextDelayMs?: number;
+}
+/**
+ * Creates initial retry state
+ */
+declare function createRetryState(): RetryState;
+/**
+ * Calculate delay for a retry attempt
+ */
+declare function calculateDelay(attempt: number, error: LLMError | undefined, config: Required<Omit<RetryConfig, "onRetry">>): number;
+/**
+ * Sleep for a duration, respecting abort signal
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Execute a function with retry logic
+ */
+declare function withRetry<T>(fn: (attempt: number) => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+/**
+ * Options for retry handler
+ */
+interface RetryHandlerOptions extends RetryConfig {
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Creates a retry handler that wraps stream creation
+ */
+declare function createRetryHandler(options?: RetryHandlerOptions): <T>(createStream: (attempt: number) => Promise<T>) => Promise<T>;
+/**
+ * Checks if more retries should be attempted
+ */
+declare function shouldRetry(error: unknown, attempt: number, maxAttempts?: number): boolean;
+
+/**
+ * LLM integration for @cuylabs/agent-core
+ *
+ * Handles the actual Vercel AI SDK streamText calls with
+ * integrated retry logic and error handling.
+ */
+
+/** Stream result type - uses default Output for text streaming */
+type LLMStreamResult = StreamTextResult<ToolSet, Output.Output<string, string, never>>;
+
+/**
+ * Custom stream result type - compatible shape from external providers.
+ * This is what packages like computer-agent return for OpenAI computer use.
+ */
+type CustomStreamResult = {
+    fullStream: AsyncIterable<StreamChunk>;
+    text: Promise<string>;
+    usage: Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }>;
+    finishReason: Promise<string>;
+};
+/** Union type for stream results - either AI SDK or custom */
+type AnyStreamResult = LLMStreamResult | CustomStreamResult;
+/** Default max output tokens */
+declare const OUTPUT_TOKEN_MAX = 32000;
+/**
+ * @deprecated Use StreamProvider from types instead
+ */
+type CustomStreamProvider = StreamProvider;
+/**
+ * Input for LLM stream
+ */
+interface LLMStreamInput {
+    /** Session ID */
+    sessionID: string;
+    /** Model to use */
+    model: LanguageModel;
+    /** System prompt parts */
+    system: string[];
+    /** Messages to send */
+    messages: ModelMessage[];
+    /** Abort signal */
+    abort: AbortSignal;
+    /** Tools to use */
+    tools: Record<string, Tool$1.Info>;
+    /** Working directory */
+    cwd: string;
+    /** Execution environment for tools. When provided, passed into ToolContext. */
+    host?: ToolHost;
+    /** Temperature */
+    temperature?: number;
+    /** Top-p */
+    topP?: number;
+    /** Max output tokens */
+    maxOutputTokens?: number;
+    /** Max steps (tool iterations) */
+    maxSteps?: number;
+    /** Reasoning level for extended thinking models */
+    reasoningLevel?: ReasoningLevel;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Callback for step completion */
+    onStepFinish?: (step: StepInfo) => void | Promise<void>;
+    /**
+     * Custom stream provider - when set, bypasses AI SDK streamText.
+     * Used for OpenAI computer use and other specialized models.
+     */
+    customStreamProvider?: StreamProvider;
+    /**
+     * Turn tracker for automatic file baseline capture.
+     * When provided, tools that declare fileOps will have
+     * their file modifications tracked for undo/diff.
+     */
+    turnTracker?: TurnTrackerContext;
+    /**
+     * Pre-built MCP tools (already in AI SDK format).
+     * These are merged with local tools before passing to streamText.
+     */
+    mcpTools?: ToolSet;
+    /**
+     * Intervention controller for mid-turn message injection.
+     *
+     * When provided, a `prepareStep` hook is registered with `streamText()`
+     * that checks for pending interventions before each LLM call. Pending
+     * messages are appended as user messages to the step's conversation.
+     *
+     * Only works with the standard AI SDK path (not custom stream providers).
+     */
+    intervention?: InterventionController;
+}
+/**
+ * Step information
+ */
+interface StepInfo {
+    toolResults?: Array<{
+        toolName: string;
+        toolCallId: string;
+        output: unknown;
+    }>;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    finishReason?: string;
+}
+/**
+ * LLM module - handles Vercel AI SDK calls
+ */
+declare namespace LLM {
+    /**
+     * Build Vercel AI SDK ToolSet from Tool.Info definitions
+     *
+     * @param tools - Tool definitions to build
+     * @param cwd - Working directory for file operations
+     * @param sessionID - Current session ID
+     * @param messageID - Current message ID
+     * @param abort - Abort signal for cancellation
+     * @param turnTracker - Optional turn tracker for automatic file baseline capture
+     * @param host - Optional execution environment for tools
+     */
+    function buildToolSet(tools: Record<string, Tool$1.Info>, cwd: string, sessionID: string, messageID: string, abort: AbortSignal, turnTracker?: TurnTrackerContext, host?: ToolHost): Promise<ToolSet>;
+    /**
+     * Create a stream for LLM completion with retry support
+     */
+    function stream(input: LLMStreamInput): Promise<AnyStreamResult>;
+    /**
+     * Create a stream without retry (for when caller handles retry externally)
+     */
+    function streamOnce(input: LLMStreamInput): Promise<AnyStreamResult>;
+}
+
+/**
+ * Stream processor for @cuylabs/agent-core
+ *
+ * Processes the LLM stream and emits events.
+ * Includes doom loop detection and context overflow monitoring.
+ */
+
+/**
+ * Doom loop error thrown when repeated tool calls are detected
+ */
+declare class DoomLoopError extends Error {
+    readonly toolName: string;
+    readonly repeatCount: number;
+    readonly input: unknown;
+    constructor(toolName: string, repeatCount: number, input: unknown);
+}
+/**
+ * Context overflow error
+ */
+declare class ContextOverflowError extends Error {
+    readonly inputTokens: number;
+    readonly limit: number;
+    constructor(inputTokens: number, limit: number);
+}
+/**
+ * Processor options
+ */
+interface ProcessorOptions {
+    /** Session ID (optional - for tracking purposes) */
+    sessionID?: string;
+    /** Abort signal */
+    abort: AbortSignal;
+    /** Event callback */
+    onEvent: (event: AgentEvent) => void | Promise<void>;
+    /** Doom loop threshold (default: 3) */
+    doomLoopThreshold?: number;
+    /** Enforce doom loop (throw error vs just warn) - only used when onDoomLoop is not provided */
+    enforceDoomLoop?: boolean;
+    /**
+     * Handler for doom loop detection.
+     * When provided, this is called instead of throwing DoomLoopError.
+     * Allows user to choose: allow (continue), deny (stop), or remember (allow + skip future).
+     */
+    onDoomLoop?: DoomLoopHandler;
+    /** Tools that are "remembered" (allowed without asking) */
+    rememberedDoomLoopTools?: Set<string>;
+    /** Token limit for context overflow detection */
+    contextTokenLimit?: number;
+    /** Callback for context overflow (allows custom handling) */
+    onContextOverflow?: (tokens: number, limit: number) => void | Promise<void>;
+    /** Current step number (for progress events) */
+    currentStep?: number;
+    /** Max steps (for progress events) */
+    maxSteps?: number;
+}
+/**
+ * Processor result with collected data
+ */
+interface ProcessorOutput {
+    /** Processing result */
+    result: ProcessorResult;
+    /** Accumulated text */
+    text: string;
+    /** Tool results */
+    toolResults: Array<{
+        toolName: string;
+        toolCallId: string;
+        result: unknown;
+    }>;
+    /** Final usage */
+    usage?: TokenUsage;
+    /** Error if any */
+    error?: Error;
+}
+/**
+ * Process an LLM stream and emit events
+ *
+ * AI SDK 5 fullStream events:
+ * - text-start, text-delta, text-end
+ * - reasoning-start, reasoning-delta, reasoning-end
+ * - tool-call, tool-result, tool-error
+ * - start-step, finish-step
+ * - start, finish, abort, error
+ *
+ * Also supports custom stream results from providers like OpenAI computer use.
+ */
+declare function processStream(stream: AnyStreamResult, options: ProcessorOptions): Promise<ProcessorOutput>;
+
+/**
+ * Approval System
+ *
+ * Handles user confirmations before potentially dangerous operations.
+ * UI applications can intercept approval requests and prompt users.
+ *
+ * Design principles:
+ * - Simple: 3 actions (allow, deny, remember)
+ * - Safe: Default deny for unknown operations
+ * - Async: Promise-based for UI integration
+ * - Typed: Full type safety for tool arguments
+ */
+/** Risk level for operations */
+type RiskLevel = "safe" | "moderate" | "dangerous";
+/** User's response to an approval request */
+type ApprovalAction = "allow" | "deny" | "remember";
+/** Approval request sent to the UI/handler */
+interface ApprovalRequest {
+    /** Unique request ID */
+    id: string;
+    /** Session ID */
+    sessionId: string;
+    /** Tool name */
+    tool: string;
+    /** Tool arguments */
+    args: unknown;
+    /** Human-readable description */
+    description: string;
+    /** Risk level */
+    risk: RiskLevel;
+    /** Patterns that would be remembered if "remember" is chosen */
+    patterns: string[];
+    /** Timestamp */
+    timestamp: number;
+}
+/** Rule for auto-approving/denying operations */
+interface ApprovalRule {
+    /** Pattern to match (glob-style) */
+    pattern: string;
+    /** Tool to match (* for all) */
+    tool: string;
+    /** Action to take */
+    action: "allow" | "deny";
+}
+/** Configuration for the approval handler */
+interface ApprovalConfig {
+    /** Default action when no rule matches (default: "ask") */
+    defaultAction?: "allow" | "deny" | "ask";
+    /** Pre-configured rules */
+    rules?: ApprovalRule[];
+    /** Handler for approval requests */
+    onRequest?: (request: ApprovalRequest) => Promise<ApprovalAction>;
+    /** Timeout for approval requests in ms (default: 5 minutes) */
+    timeout?: number;
+}
+/**
+ * Get risk level for a tool
+ */
+declare function getToolRisk(tool: string, customRisks?: Record<string, RiskLevel>): RiskLevel;
+/** Thrown when user denies an operation */
+declare class ApprovalDeniedError extends Error {
+    readonly tool: string;
+    readonly args: unknown;
+    constructor(tool: string, args: unknown, message?: string);
+}
+/** Thrown when approval request times out */
+declare class ApprovalTimeoutError extends Error {
+    readonly tool: string;
+    readonly timeoutMs: number;
+    constructor(tool: string, timeoutMs: number);
+}
+/**
+ * Creates an approval handler for managing tool execution permissions.
+ *
+ * @example
+ * ```typescript
+ * const approvals = createApprovalHandler({
+ *   rules: [
+ *     { pattern: "src/*", tool: "edit_file", action: "allow" },
+ *     { pattern: "*", tool: "bash", action: "deny" },
+ *   ],
+ *   onRequest: async (req) => {
+ *     // Show UI dialog
+ *     const userChoice = await showConfirmDialog(req);
+ *     return userChoice; // "allow" | "deny" | "remember"
+ *   },
+ * });
+ * ```
+ */
+declare function createApprovalHandler(config?: ApprovalConfig): {
+    request: (sessionId: string, tool: string, args: unknown, customRisks?: Record<string, RiskLevel>) => Promise<void>;
+    cancelAll: (reason?: string) => void;
+    addRule: (rule: ApprovalRule) => void;
+    getRules: () => readonly ApprovalRule[];
+    clearSessionRules: () => void;
+};
+/** Type for the approval handler */
+type ApprovalHandler = ReturnType<typeof createApprovalHandler>;
+
+/**
+ * Checkpoint System - Git-based file state tracking and recovery
+ *
+ * Provides undo/restore capabilities for agent file operations by maintaining
+ * an isolated git repository that tracks working directory changes.
+ *
+ * @example
+ * ```typescript
+ * const checkpoints = await createCheckpointManager({ workDir: '/project' });
+ *
+ * // Save state before risky operation
+ * const id = await checkpoints.save('before refactoring');
+ *
+ * // After operation completes, see what changed
+ * const changes = await checkpoints.changes(id);
+ * console.log('Modified files:', changes.files);
+ *
+ * // If something went wrong, restore
+ * await checkpoints.restore(id);
+ *
+ * // Or undo just specific files
+ * await checkpoints.undoFiles(id, ['src/broken.ts']);
+ * ```
+ */
+/** Configuration for creating a checkpoint manager */
+interface CheckpointConfig {
+    /** Working directory to track (absolute path) */
+    workDir: string;
+    /** Optional custom storage directory (defaults to ~/.cuylabs/checkpoints/{project-hash}/) */
+    storageDir?: string;
+    /** Whether to track file contents (enables restore). Default: true */
+    trackContent?: boolean;
+    /** Patterns to exclude from tracking (gitignore format) */
+    exclude?: string[];
+    /** Maximum number of checkpoints to retain. Default: 100 */
+    maxCheckpoints?: number;
+}
+/** A saved checkpoint representing a point-in-time state */
+interface Checkpoint {
+    /** Unique checkpoint identifier (git tree hash) */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** When the checkpoint was created */
+    createdAt: Date;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** File change information between checkpoints */
+interface FileChange {
+    /** Relative file path */
+    path: string;
+    /** Type of change */
+    type: 'added' | 'modified' | 'deleted';
+    /** Lines added (for text files) */
+    additions?: number;
+    /** Lines removed (for text files) */
+    deletions?: number;
+}
+/** Changes detected between a checkpoint and current state */
+interface ChangeSet {
+    /** Checkpoint being compared from */
+    fromCheckpoint: string;
+    /** List of changed files */
+    files: FileChange[];
+    /** Unified diff output */
+    diff: string;
+}
+/** Checkpoint manager interface */
+interface CheckpointManager {
+    /** Save current state as a checkpoint */
+    save(label?: string, metadata?: Record<string, unknown>): Promise<Checkpoint>;
+    /** Restore all files to a checkpoint state */
+    restore(checkpointId: string): Promise<void>;
+    /** Get changes since a checkpoint */
+    changes(checkpointId: string): Promise<ChangeSet>;
+    /** Undo changes to specific files (restore them from checkpoint) */
+    undoFiles(checkpointId: string, files: string[]): Promise<void>;
+    /** List all checkpoints (newest first) */
+    list(): Promise<Checkpoint[]>;
+    /** Delete a specific checkpoint */
+    remove(checkpointId: string): Promise<void>;
+    /** Prune old checkpoints beyond maxCheckpoints limit */
+    prune(): Promise<number>;
+    /** Get the latest checkpoint */
+    latest(): Promise<Checkpoint | null>;
+    /** Get file content at a specific checkpoint */
+    getFileAt(checkpointId: string, filePath: string): Promise<string | null>;
+    /** Check if manager is initialized */
+    isInitialized(): boolean;
+    /** Close and cleanup resources */
+    close(): Promise<void>;
+}
+/**
+ * Creates a checkpoint manager for tracking file state changes
+ *
+ * @param config - Configuration options
+ * @returns Initialized checkpoint manager
+ */
+declare function createCheckpointManager(config: CheckpointConfig): Promise<CheckpointManager>;
+/**
+ * Clear all checkpoint data for a working directory
+ *
+ * @param workDir - Working directory whose checkpoints to clear
+ */
+declare function clearCheckpoints(workDir: string): Promise<void>;
+
+/**
+ * Token Estimation Utilities
+ *
+ * Provides lightweight heuristic-based token counting for messages
+ * and conversations. Uses the chars/4 approximation — simple but
+ * effective for context-window planning decisions.
+ *
+ * These are *estimates*, not exact counts. For billing or hard limits,
+ * use the provider's native tokeniser instead.
+ */
+
+/**
+ * Estimate token count for a plain string.
+ *
+ * Uses the widely-accepted `chars / 4` heuristic.
+ *
+ * @param text - Text to estimate
+ * @returns Estimated token count (always ≥ 1 for non-empty input)
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate token count for a single message.
+ *
+ * Handles:
+ * - Plain string content
+ * - Multi-part / multimodal arrays (text parts + images)
+ *
+ * @param message - A `Message` (internal) or `ModelMessage` (AI SDK)
+ * @returns Estimated token count
+ */
+declare function estimateMessageTokens(message: Message | ModelMessage): number;
+/**
+ * Estimate total tokens for an entire conversation.
+ *
+ * Adds a small per-message overhead (≈ 4 tokens) for message
+ * framing (`role`, delimiters, etc.).
+ *
+ * @param messages - Array of messages to estimate
+ * @returns Estimated total token count
+ */
+declare function estimateConversationTokens(messages: (Message | ModelMessage)[]): number;
+
+/**
+ * Context Overflow Detection & Pruning
+ *
+ * Detects when a conversation is approaching the model's context-window
+ * limit and prunes old / redundant content to stay within bounds.
+ *
+ * Two pruning strategies are available:
+ * 1. **Tool-result pruning** — replaces large, stale tool outputs with
+ *    compact placeholders (lightweight, no model call).
+ * 2. **Conversation cutting** — identifies a safe cut-point and removes
+ *    older messages entirely (optionally summarised by the manager).
+ */
+
+/**
+ * Context limits configuration.
+ *
+ * All values are in *estimated* tokens (see {@link estimateTokens}).
+ */
+interface ContextLimits {
+    /** Maximum context window size in tokens */
+    contextWindow: number;
+    /** Reserve tokens for output generation */
+    reserveTokens: number;
+    /** Protect this many recent tokens from pruning */
+    protectedTokens: number;
+    /** Minimum tokens to trigger pruning (avoid pruning tiny contexts) */
+    pruneMinimum: number;
+}
+/**
+ * Default context limits.
+ * Based on typical 128 k context-window models.
+ */
+declare const DEFAULT_CONTEXT_LIMITS: ContextLimits;
+/**
+ * Check whether the context is overflowing.
+ *
+ * @param tokens - Current estimated token count
+ * @param limits - Context limits (defaults to 128 k window)
+ * @returns `true` if context exceeds the safe threshold
+ */
+declare function isContextOverflowing(tokens: number, limits?: ContextLimits): boolean;
+/**
+ * Check whether pruning should be triggered.
+ *
+ * Returns `false` when the conversation is still small enough that
+ * pruning would be wasteful (below {@link ContextLimits.pruneMinimum}).
+ */
+declare function shouldPruneContext(tokens: number, limits?: ContextLimits): boolean;
+/**
+ * Result of a pruning operation.
+ */
+interface PruneResult {
+    /** Messages after pruning (may include a summary message) */
+    messages: Message[];
+    /** Number of messages removed */
+    removedCount: number;
+    /** Estimated tokens removed */
+    tokensRemoved: number;
+    /** Whether summarisation was used */
+    summarized: boolean;
+    /** The summary content, if generated */
+    summary?: string;
+}
+/**
+ * Find a safe index at which the conversation can be "cut".
+ *
+ * Rules:
+ * - Never cut in the middle of a tool-call sequence
+ * - Prefer cutting after assistant / user messages
+ * - Keep at least {@link protectedTokens} tokens at the end
+ *
+ * @param messages       - Full message array
+ * @param protectedTokens - Tokens to preserve at the end
+ * @returns Cut index (exclusive — remove messages *before* this index).
+ *          Returns `0` when no safe cut-point exists.
+ */
+declare function findCutPoint(messages: Message[], protectedTokens?: number): number;
+/**
+ * Prune old, large tool results from the conversation.
+ *
+ * This mirrors OpenCode's `SessionCompaction.prune()` pattern:
+ * - Walks backwards through messages
+ * - Protects recent outputs (within {@link protectedTokens})
+ * - Skips protected tools (e.g. "skill")
+ * - Stamps pruned messages with a `compactedAt` timestamp
+ *
+ * @param messages       - Messages to prune
+ * @param protectedTokens - Don't prune tool results in the last N tokens
+ * @param options        - Extra tool names to protect
+ * @returns New message array with large tool outputs replaced
+ */
+declare function pruneToolResults(messages: Message[], protectedTokens?: number, options?: {
+    /** Additional tools to protect from pruning */
+    protectedTools?: string[];
+}): Message[];
+
+/**
+ * Context Summarisation
+ *
+ * When tool-result pruning alone isn't enough to stay within the
+ * context window, the manager can *cut* the conversation and replace
+ * the removed portion with an LLM-generated summary.
+ *
+ * This module provides the summary-generation logic and the
+ * top-level `pruneContext()` orchestration function.
+ */
+
+/**
+ * Options for summary generation.
+ */
+interface SummarizationOptions {
+    /** Model used to generate the summary */
+    model: LanguageModel;
+    /** Max tokens for the summary output */
+    maxTokens?: number;
+    /** Custom summarisation system prompt */
+    customPrompt?: string;
+}
+/**
+ * Options for {@link pruneContext}.
+ */
+interface PruneContextOptions {
+    /** Model for summarisation (omit to skip summary generation) */
+    model?: LanguageModel;
+    /** Context limits to enforce */
+    limits?: ContextLimits;
+    /** Custom summarisation prompt */
+    summaryPrompt?: string;
+}
+/**
+ * Generate a natural-language summary of a message sequence.
+ *
+ * @param messages - Messages to summarise
+ * @param options  - Model & prompt configuration
+ * @returns Summary text
+ */
+declare function generateSummary(messages: Message[], options: SummarizationOptions): Promise<string>;
+/**
+ * Prune a conversation to fit within context-window limits.
+ *
+ * Strategy (in order):
+ * 1. Prune old tool outputs (lightweight, no model call)
+ * 2. If still overflowing, find a safe cut-point and remove
+ *    older messages — optionally generating an LLM summary.
+ *
+ * @param messages - Current message array
+ * @param options  - Limits, model, and prompt overrides
+ * @returns A {@link PruneResult} with the trimmed messages
+ */
+declare function pruneContext(messages: Message[], options?: PruneContextOptions): Promise<PruneResult>;
+
+/**
+ * Context Manager
+ *
+ * Stateful wrapper around the context-management primitives.
+ * Tracks per-session context limits and provides a single entry
+ * point for token estimation, overflow detection, and pruning.
+ */
+
+/**
+ * Per-session context manager.
+ *
+ * Holds the active context-window limits and provides convenience
+ * methods for checking, reporting, and pruning context.
+ *
+ * @example
+ * ```typescript
+ * const ctx = new ContextManager({ limits: { contextWindow: 200_000 } });
+ *
+ * if (ctx.shouldPrune(messages)) {
+ *   const result = await ctx.prune(messages);
+ *   console.log(`Removed ${result.removedCount} messages`);
+ * }
+ * ```
+ */
+declare class ContextManager {
+    private limits;
+    private model?;
+    private summaryPrompt?;
+    constructor(options?: {
+        limits?: Partial<ContextLimits>;
+        model?: LanguageModel;
+        summaryPrompt?: string;
+    });
+    /** Get a copy of the current context limits. */
+    getLimits(): ContextLimits;
+    /** Update context limits (e.g. when switching models). */
+    setLimits(limits: Partial<ContextLimits>): void;
+    /** Set the model used for summarisation. */
+    setModel(model: LanguageModel): void;
+    /** Estimate total tokens for a message array. */
+    estimateTokens(messages: (Message | ModelMessage)[]): number;
+    /** Check whether the context is overflowing. */
+    isOverflowing(messages: (Message | ModelMessage)[]): boolean;
+    /** Check whether pruning should be triggered. */
+    shouldPrune(messages: (Message | ModelMessage)[]): boolean;
+    /** Prune context to fit within limits. */
+    prune(messages: Message[]): Promise<PruneResult>;
+    /**
+     * Get a snapshot of token statistics.
+     *
+     * Useful for dashboards, logging, or deciding whether to prune.
+     */
+    getStats(messages: (Message | ModelMessage)[]): {
+        tokens: number;
+        limit: number;
+        available: number;
+        utilizationPercent: number;
+        isOverflowing: boolean;
+        shouldPrune: boolean;
+    };
+}
+
+/**
+ * LocalHost — executes tools on the local machine.
+ *
+ * Default ToolHost implementation. Uses Node's `child_process.spawn`
+ * for commands and `node:fs/promises` for file operations.
+ */
+
+/**
+ * Create a ToolHost that runs everything on the local machine.
+ *
+ * @param defaultCwd  Working directory for commands when none is specified.
+ *                    Defaults to `process.cwd()`.
+ */
+declare function localHost(defaultCwd?: string): ToolHost;
+
+/**
+ * DockerHost — executes tools inside a Docker container.
+ *
+ * Requires `dockerode` as a peer dependency. Install it with:
+ *
+ *   npm install dockerode
+ *
+ * All file operations and process execution happen inside the container
+ * via `docker exec`. File reads/writes use shell commands piped through
+ * the Docker API — no volumes or bind mounts required.
+ *
+ * ### Quick start — build a sandbox and wire it up
+ *
+ * ```typescript
+ * import Dockerode from "dockerode";
+ * import { dockerHost, createAgent, Tool } from "@cuylabs/agent-core";
+ * import { openai } from "@ai-sdk/openai";
+ * import { z } from "zod";
+ *
+ * // 1. Build a lightweight sandbox container
+ * const docker = new Dockerode();
+ * await new Promise<void>((res, rej) =>
+ *   docker.pull("alpine:3.19", {}, (e, s) =>
+ *     e ? rej(e) : docker.modem.followProgress(s, (err) => (err ? rej(err) : res())),
+ *   ),
+ * );
+ * const container = await docker.createContainer({
+ *   Image: "alpine:3.19",
+ *   name: "agent-sandbox",
+ *   Cmd: [
+ *     "sh", "-c",
+ *     "apk add --no-cache bash coreutils python3 && tail -f /dev/null",
+ *   ],
+ *   WorkingDir: "/workspace",
+ * });
+ * await container.start();
+ *
+ * // 2. Create a dockerHost pointed at the running container
+ * const host = await dockerHost({
+ *   container: "agent-sandbox",
+ *   workdir: "/workspace",
+ * });
+ *
+ * // 3. Define tools — they call ctx.host.exec(), ctx.host.writeFile(), etc.
+ * //    The SAME tool code works on localHost() or dockerHost().
+ * const runCmd = Tool.define("run", {
+ *   description: "Run a shell command",
+ *   parameters: z.object({ command: z.string() }),
+ *   execute: async ({ command }, ctx) => {
+ *     const r = await ctx.host!.exec(command);
+ *     return { title: command, output: r.stdout + r.stderr, metadata: {} };
+ *   },
+ * });
+ *
+ * // 4. Create agent — all tools execute inside the container
+ * const agent = createAgent({ model: openai("gpt-4o-mini"), host, tools: [runCmd] });
+ * for await (const ev of agent.chat("s1", "Run: python3 -c 'print(42)'")) {
+ *   if (ev.type === "text-delta") process.stdout.write(ev.text);
+ * }
+ *
+ * // 5. Clean up
+ * await container.stop();
+ * await container.remove();
+ * ```
+ *
+ * ### Passing a Container object directly
+ *
+ * ```typescript
+ * import Dockerode from "dockerode";
+ * const docker = new Dockerode();
+ * const host = await dockerHost({
+ *   container: docker.getContainer("my-container"),
+ *   user: "root",
+ *   workdir: "/workspace",
+ * });
+ * ```
+ *
+ * See `examples/14-docker-host.ts` for a fully runnable version.
+ */
+
+/**
+ * Configuration for creating a Docker ToolHost.
+ */
+interface DockerHostOptions {
+    /**
+     * The container to connect to. Either:
+     * - A string container name or ID
+     * - A Dockerode Container object (from `docker.getContainer(...)`)
+     */
+    container: string | {
+        id: string;
+    };
+    /** User to run commands as inside the container (default: container default). */
+    user?: string;
+    /** Default working directory inside the container (default: "/"). */
+    workdir?: string;
+    /**
+     * Dockerode constructor options. Only used when `container` is a string.
+     * Passed directly to `new Dockerode(options)`.
+     *
+     * @example
+     * ```typescript
+     * { socketPath: "/var/run/docker.sock" }
+     * // or
+     * { host: "192.168.1.10", port: 2376 }
+     * ```
+     */
+    dockerOptions?: Record<string, unknown>;
+}
+/**
+ * Create a ToolHost that runs everything inside a Docker container.
+ *
+ * Requires `dockerode` to be installed as a peer dependency.
+ * The container **must already be running** — use `container.start()`
+ * before calling this factory.
+ *
+ * @param options  Container configuration.
+ * @param options.container  Container name/ID string, or a Dockerode `Container` object.
+ * @param options.user       User to run commands as (default: container's default user).
+ * @param options.workdir    Default working directory (default: "/").
+ * @param options.dockerOptions  Dockerode constructor options (socket path, remote host, etc.).
+ *                               Only used when `container` is a string.
+ * @returns A ToolHost whose `exec`, `readFile`, `writeFile`, etc. all operate
+ *          inside the container.
+ *
+ * @throws If `dockerode` is not installed.
+ * @throws If the container does not exist or is not running (on first operation).
+ *
+ * @example Build a container, wire it up, clean up
+ * ```typescript
+ * import Dockerode from "dockerode";
+ * import { dockerHost, createAgent } from "@cuylabs/agent-core";
+ *
+ * const docker = new Dockerode();
+ * const ctr = await docker.createContainer({
+ *   Image: "node:22-alpine",
+ *   Cmd: ["tail", "-f", "/dev/null"],
+ *   WorkingDir: "/app",
+ * });
+ * await ctr.start();
+ *
+ * const host = await dockerHost({ container: ctr, workdir: "/app" });
+ * const agent = createAgent({ host, model: openai("gpt-4o") });
+ *
+ * // ... use agent ...
+ *
+ * await ctr.stop();
+ * await ctr.remove();
+ * ```
+ */
+declare function dockerHost(options: DockerHostOptions): Promise<ToolHost>;
+
+type AdapterKind = "openai" | "anthropic" | "google" | "openai-compatible";
+type AdapterSettings = {
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    extra?: Record<string, unknown>;
+};
+type EngineSpec = {
+    adapter: AdapterKind | string;
+    settings?: AdapterSettings;
+    build?: (modelId: string, settings: AdapterSettings) => LanguageModel;
+};
+type ModelSpec = {
+    engine: string;
+    id: string;
+    settings?: AdapterSettings;
+};
+type Directory = {
+    engines: Record<string, EngineSpec>;
+    entries?: Record<string, ModelSpec>;
+};
+type Resolver = (key: string) => LanguageModel;
+declare function createResolver(directory: Directory): Resolver;
+
+export { type AdapterSettings, Agent, type AgentConfig, type AgentEvent, type AgentState, type AgentStatus, type AnyStreamResult, type AppliedPreset, type ApprovalAction, type ApprovalConfig, ApprovalDeniedError, type ApprovalEvent, type ApprovalHandler, type ApprovalRequest, type ApprovalRule, ApprovalTimeoutError, type AssistantMessage, type BranchEntry, type ChangeSet, type Checkpoint, type CheckpointConfig, type CheckpointManager, type CompactionConfig, type CompactionEntry, type ContextLimits, ContextManager, ContextOverflowError, type CreateSessionOptions, type CustomStreamProvider, type CustomStreamResult, DEFAULT_CONTEXT_LIMITS, DEFAULT_INSTRUCTION_PATTERNS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_RETRY_CONFIG, type DockerHostOptions, type DoomLoopAction, DoomLoopError, type DoomLoopHandler, type DoomLoopRequest, type EngineSpec, type EnhancedTools, type EnvironmentInfo, type ErrorCategory, type FileBaseline, type FileChange, type FileEntry, FileOperationMeta, FileStorage, type FileStorageOptions, type HttpTransportConfig, type InstructionFile, InterventionController, LLM, LLMError, type LLMErrorOptions, type LLMStreamInput, type LLMStreamResult, type MCPConfig, type MCPManager, type MCPPrompt, type MCPResource, type MCPServerConfig, type MCPServerStatus, MemoryStorage, type Message, type MessageBase, type MessageEntry, type MessageError, type MessageRole, type MetadataEntry, type ModelCapabilities, ModelCapabilityResolver, type Directory as ModelDirectory, type ModelEntry, type ModelFamily, type Resolver as ModelResolver, type ModelSpec, type NetworkStatus, OUTPUT_TOKEN_MAX, type OnInterventionApplied, PRIORITY_BASE, PRIORITY_CUSTOM, PRIORITY_ENVIRONMENT, PRIORITY_INSTRUCTIONS, PRIORITY_OVERRIDE, PRIORITY_SKILLS, type PendingIntervention, type Preset, Presets, type ProcessorOptions, type ProcessorOutput, type ProcessorResult, type PromptBuildContext, PromptBuilder, type PromptConfig, type PromptSection, type ProviderCompatibility, type PruneContextOptions, type PruneResult, type ReasoningConfig, type ReasoningLevel, type ResolverOptions, type ResponseHeaders, type RetryConfig, type RetryHandlerOptions, type RetryState, type RiskLevel, STORAGE_VERSION, type Session, type SessionContext, type SessionEntry, type SessionHeader, type SessionInfo, SessionManager, type SessionStorage, type SseTransportConfig, type StdioTransportConfig, type StepInfo, type StreamChunk, type StreamInput, type StreamProvider, type StreamProviderConfig, type StreamProviderFactory, type StreamProviderInput, type StreamProviderResult, type SubAgentResult, type SummarizationOptions, type SystemMessage, type TokenUsage, Tool$1 as Tool, ToolHost, type ToolMessage, type TrackedToolMetadata, TurnChangeTracker, type TurnFileChange, type TurnSummary, type TurnTrackerConfig, TurnTrackerContext, type UndoResult, type UserMessage, applyPreset, buildMessagesFromEntries, buildReasoningOptions, buildReasoningOptionsSync, calculateDelay, clearCheckpoints, configureDefaultSessionManager, configureResolver, createAgent, createApprovalHandler, createCheckpointManager, createMCPManager, createPreset, createPromptBuilder, createResolver, createRetryHandler, createRetryState, createTurnTracker, defineServer, deserializeMessage, detectModelFamily, discoverInstructions, dockerHost, estimateConversationTokens, estimateMessageTokens, estimateTokens, extractFilePathsFromArgs, filterTools, findCutPoint, formatEnvironment, formatInstructions, gatherEnvironment, generateEntryId, generateSummary, getAvailableFamilies, getDataDir, getDefaultResolver, getDefaultSessionManager, getErrorCategory, getLeafId, getModelId, getNetworkStatus, getProjectSessionsDir, getProviderId, getReasoningConfig, getReasoningConfigSync, getRetryDelay, getSessionsDir, getTemplate, getToolRisk, httpServer, isContextOverflowing, isRetryable, isRetryableCategory, loadGlobalInstructions, localHost, mergePresets, parseJSONL, processStream, pruneContext, pruneToolResults, runConcurrent, serializeMessage, shouldCaptureBaseline, shouldPruneContext, shouldRetry, sleep, sseServer, stdioServer, summarizeEnvironment, supportsReasoning, supportsReasoningSync, toJSONL, withFileTracking, withRetry };