@cuylabs/agent-core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,211 +1,10 @@
 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-QR704uRr.js';
-export { C as CompatibleSchema, D as DirEntry, E as ExecOptions, c as ExecResult, d as FileStat, I as InferSchemaOutput, 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-QR704uRr.js';
+import { T as ToolHost, a as ToolContext, b as Tool$1, F as FileOperationMeta, c as TurnTrackerContext } from './index-BlSTfS-W.js';
+export { C as CompatibleSchema, D as DirEntry, E as ExecOptions, d as ExecResult, e as FileStat, I as InferSchemaOutput, M as MAX_BYTES, f as MAX_LINES, g as TRUNCATE_DIR, h as TRUNCATE_GLOB, 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-BlSTfS-W.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
  *
@@ -265,7 +64,6 @@ interface ToolMessage extends MessageBase {
     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;
@@ -316,19 +114,47 @@ interface Session {
     parentID?: 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";
+}
 /**
- * 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)
+ * Events emitted during agent execution
  *
- * This is the single canonical definition — used by both the
- * streaming module and custom stream providers.
+ * 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 StreamChunk = {
+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";
@@ -346,7 +172,7 @@ type StreamChunk = {
     type: "reasoning-end";
     id: string;
 } | {
-    type: "tool-call";
+    type: "tool-start";
     toolName: string;
     toolCallId: string;
     input: unknown;
@@ -354,206 +180,12 @@ type StreamChunk = {
     type: "tool-result";
     toolName: string;
     toolCallId: string;
-    output: unknown;
+    result: 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;
+    error: string;
 } | {
     type: "computer-call";
     callId: string;
@@ -615,304 +247,956 @@ interface StreamInput {
 }
 
 /**
- * Reasoning Types & Constants
+ * Skill System Types
  *
- * Shared type definitions, level constants, and small helpers
- * used across the reasoning subsystem.
+ * Skills are modular, on-demand knowledge packs that extend an agent's
+ * capabilities with specialized instructions, workflows, and resources.
+ *
+ * Design principles:
+ *
+ * 1. **Progressive disclosure** — summaries always in context,
+ *    full content loaded only when needed. Minimizes baseline token cost.
+ *
+ * 2. **Scoped priority** — project skills override user skills
+ *    override global skills. Closest scope wins on name collision.
+ *
+ * 3. **Agent-initiated loading** — the agent decides when to
+ *    activate a skill by calling the `skill` tool. No guesswork.
+ *
+ * 4. **Bundled resources** — skills can ship scripts,
+ *    references, assets, and examples alongside instructions.
+ *
+ * 5. **Remote sources** — skills can be fetched from URLs,
+ *    enabling shared skill repositories across teams.
+ *
+ * The lifecycle:
+ *
+ *   Discovery → Registry → Summary injection → Agent tool call → Full load
+ *
+ * @packageDocumentation
  */
 /**
- * Standard reasoning / thinking levels.
+ * Where a skill was discovered, determining its override priority.
  *
- * | Level      | Description                        |
- * |------------|------------------------------------|
- * | `"off"`    | No reasoning (fastest)             |
- * | `"minimal"`| Very light reasoning               |
- * | `"low"`    | Light reasoning                    |
- * | `"medium"` | Balanced reasoning                 |
- * | `"high"`   | Deep reasoning                     |
- * | `"xhigh"`  | Maximum reasoning (where supported)|
+ * When two skills share the same name, the narrower scope wins:
+ *   project > user > global > builtin
+ *
+ * Uses a 4-tier hierarchy with names that are intuitive for
+ * library consumers.
  */
-type ReasoningLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+type SkillScope = "project" | "user" | "global" | "builtin";
 /**
- * Provider-specific reasoning configuration returned by
- * {@link getReasoningConfig} / {@link getReasoningConfigSync}.
+ * How a skill was obtained — local filesystem or remote URL.
  */
-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;
+type SkillSourceType = "local" | "remote";
+/**
+ * Where a skill came from, for provenance tracking.
+ */
+interface SkillSource {
+    /** Local or remote origin */
+    type: SkillSourceType;
+    /** Root directory or URL this skill was discovered under */
+    root: string;
 }
-
 /**
- * Model Capability Types for @cuylabs/agent-core
+ * Classification of bundled resources within a skill directory.
  *
- * Defines the structure for model capabilities that can be sourced from
- * static patterns, local cache, or remote APIs.
+ * Resource taxonomy:
+ * - `script`    — executable code for deterministic tasks (can be run without reading)
+ * - `reference` — documentation loaded into context on demand
+ * - `asset`     — templates, images, fonts used in output (not read into context)
+ * - `example`   — working code samples for the agent to learn from
  */
+type SkillResourceType = "script" | "reference" | "asset" | "example";
 /**
- * Input modalities a model can accept
+ * A file bundled with a skill.
+ *
+ * Resources are discovered but NOT loaded into memory until the agent
+ * explicitly requests them. This is the L3 layer of progressive disclosure.
  */
-type InputModality = "text" | "image" | "audio" | "video" | "pdf";
+interface SkillResource {
+    /** Path relative to the skill's base directory */
+    relativePath: string;
+    /** Classified resource type */
+    type: SkillResourceType;
+    /** Absolute path on disk (for local resources) */
+    absolutePath: string;
+}
 /**
- * Output modalities a model can produce
+ * Lightweight skill metadata parsed from SKILL.md YAML frontmatter.
+ *
+ * This is the **L1 layer** — always present in the system prompt so the
+ * agent knows which skills exist. Kept intentionally small (~100 words each)
+ * to minimize baseline context cost.
+ *
+ * Uses YAML frontmatter in a SKILL.md file — the widely-adopted
+ * canonical format for skill definitions.
  */
-type OutputModality = "text" | "image" | "audio" | "video";
+interface SkillMetadata {
+    /** Unique skill identifier (from frontmatter `name`) */
+    name: string;
+    /**
+     * When to use this skill — the single most important field.
+     *
+     * This description is what the agent reads to decide whether to
+     * activate the skill. Should contain trigger phrases that match
+     * task types. Written for another LLM to consume, not humans.
+     */
+    description: string;
+    /** Semantic version (from frontmatter, optional) */
+    version?: string;
+    /** Scope that determines override priority */
+    scope: SkillScope;
+    /** How this skill was obtained */
+    source: SkillSource;
+    /** Absolute path to the SKILL.md file */
+    filePath: string;
+    /** Directory containing the skill (parent of SKILL.md) */
+    baseDir: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+    /**
+     * Names of skills this skill depends on.
+     * When this skill is loaded, its dependencies are suggested to be loaded too.
+     */
+    dependencies?: string[];
+}
 /**
- * Comprehensive model capabilities
+ * Full skill content including the markdown body and resource listing.
+ *
+ * This is the **L2 layer** — loaded only when the agent calls the skill
+ * tool. Contains the actual instructions plus awareness of bundled resources.
  */
-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;
+interface SkillContent extends SkillMetadata {
+    /**
+     * The full markdown body of SKILL.md (everything below the frontmatter).
+     * This is the core instructional content injected into the conversation.
+     */
+    body: string;
+    /**
+     * Bundled resources discovered in the skill directory.
+     * Listed so the agent knows what's available but not yet loaded.
+     */
+    resources: SkillResource[];
 }
 /**
- * Get current network status
- */
-declare function getNetworkStatus(): NetworkStatus;
-
-/**
- * Model Capability Resolver for @cuylabs/agent-core
+ * Configuration for skill discovery and loading.
  *
- * 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
+ * Controls where skills are found, how deep to scan, and which
+ * external conventions to support.
  *
- * Provides a unified API for querying model capabilities with
- * automatic fallback through multiple sources.
+ * @example
+ * ```typescript
+ * const skillConfig: SkillConfig = {
+ *   // Scan standard locations
+ *   externalDirs: [".agents", ".claude"],
+ *   // Add custom skill roots
+ *   roots: ["./company-skills"],
+ *   // Limit scan depth for performance
+ *   maxScanDepth: 4,
+ * };
+ * ```
  */
-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>;
+interface SkillConfig {
     /**
-     * Get capabilities for a model
+     * Additional directories to scan for skills (absolute or relative to cwd).
+     * Each directory is scanned recursively for SKILL.md files.
      */
-    getCapabilities(model: LanguageModel): Promise<ModelCapabilities>;
+    roots?: string[];
     /**
-     * Get provider compatibility settings
+     * External skill directory names to scan in project and home directories.
+     *
+     * These are checked as `<project>/<dir>/skills/` and `~/<dir>/skills/`.
+     * Supports `.claude` and `.agents` directory conventions.
+     *
+     * @default [".agents", ".claude"]
      */
-    getCompatibility(model: LanguageModel): Promise<ProviderCompatibility | undefined>;
+    externalDirs?: string[];
     /**
-     * Force refresh from remote API
+     * Maximum directory depth to scan within each root.
+     * Higher values find more deeply nested skills but take longer.
+     *
+     * @default 4
      */
-    refreshRemote(): Promise<void>;
+    maxScanDepth?: number;
     /**
-     * Get current network status
+     * Maximum file size for SKILL.md files in bytes.
+     * Skills larger than this are skipped with a warning.
+     *
+     * @default 102400 (100KB)
      */
-    getNetworkStatus(): NetworkStatus;
+    maxFileSize?: number;
     /**
-     * Get resolver statistics
+     * Enable fetching skills from remote URLs.
+     * When false, `remoteUrls` is ignored.
+     *
+     * @default false
      */
-    getStats(): {
-        cacheSize: number;
-        cacheLoaded: boolean;
-        remoteFetchEnabled: boolean;
-        networkOnline: boolean;
-    };
+    enableRemote?: boolean;
     /**
-     * Clear all cached data
+     * Remote skill index URLs to fetch.
+     *
+     * Each URL should serve a JSON index listing available skills.
+     * See `RemoteSkillIndex` for the expected format.
+     *
+     * @example
+     * ```typescript
+     * remoteUrls: ["https://skills.example.com/index.json"]
+     * ```
      */
-    clearCache(): Promise<void>;
+    remoteUrls?: string[];
     /**
-     * List all available models
-     * Fetches from remote if cache is empty and remote is enabled
+     * Cache directory for remote skills.
+     * Defaults to `~/.cache/cuylabs/skills/`.
      */
-    listModels(): Promise<ModelEntry[]>;
+    remoteCacheDir?: string;
     /**
-     * List all available models grouped by provider
+     * Include built-in skills bundled with agent-core.
+     * Currently reserved for future use.
+     *
+     * @default true
      */
-    listModelsByProvider(): Promise<Record<string, ModelEntry[]>>;
+    includeBuiltin?: boolean;
 }
 /**
- * Get the default resolver instance
+ * Schema for remote skill index JSON files.
+ *
+ * Hosted at a URL like `https://skills.example.com/index.json`.
+ * Enables team-wide or organization-wide skill sharing.
+ *
+ * @example
+ * ```json
+ * {
+ *   "version": 1,
+ *   "skills": [
+ *     {
+ *       "name": "testing",
+ *       "files": ["SKILL.md", "scripts/run-tests.sh", "references/patterns.md"]
+ *     }
+ *   ]
+ * }
+ * ```
  */
-declare function getDefaultResolver(): ModelCapabilityResolver;
+interface RemoteSkillIndex {
+    /** Schema version (currently 1) */
+    version: number;
+    /** List of available skills */
+    skills: RemoteSkillEntry[];
+}
 /**
- * Configure the default resolver with custom options
+ * A single skill listing in a remote index.
  */
-declare function configureResolver(options: Partial<ResolverOptions>): void;
+interface RemoteSkillEntry {
+    /** Skill name (must match the `name` in SKILL.md frontmatter) */
+    name: string;
+    /** Relative file paths to download (SKILL.md is required) */
+    files: string[];
+}
+/**
+ * Result of a full skill discovery pass.
+ */
+interface SkillDiscoveryResult {
+    /** All discovered skills (deduplicated, scope-prioritized) */
+    skills: SkillMetadata[];
+    /** Skills that failed to load with reasons */
+    errors: SkillDiscoveryError[];
+    /** Total directories scanned */
+    dirsScanned: number;
+    /** Discovery duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * An error encountered during skill discovery.
+ */
+interface SkillDiscoveryError {
+    /** Path that caused the error */
+    path: string;
+    /** What went wrong */
+    reason: string;
+}
 
 /**
- * Reasoning Configuration & Option Builders
+ * Prompt Pipeline Types
  *
- * Orchestrates capability detection and provider-specific option
- * building to produce ready-to-use `providerOptions` for the
- * Vercel AI SDK.
+ * Types for the layered system prompt architecture.
+ * The prompt pipeline composes a system prompt from multiple sources:
  *
- * 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).
+ *   Base Template → Environment → Instructions → Custom Sections → Per-Turn
+ *
+ * Each layer is optional, composable, and can be toggled on/off.
  */
 
 /**
- * Get the reasoning configuration for a model.
+ * Model family identifier for prompt template selection.
  *
- * Uses the full capability resolver (including network lookups)
- * for the most accurate result.
+ * 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
  */
-declare function getReasoningConfig(model: LanguageModel): Promise<ReasoningConfig>;
+type ModelFamily = "anthropic" | "openai" | "google" | "deepseek" | "default";
 /**
- * Synchronous reasoning config using pattern-matching only.
- *
- * Faster but less accurate than {@link getReasoningConfig}.
- * Good for hot paths where async is impractical.
- */
+ * 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;
+    /**
+     * Skill discovery and loading configuration.
+     *
+     * When provided, the prompt pipeline will:
+     * 1. Discover SKILL.md files from project, user, and global directories
+     * 2. Inject skill summaries at PRIORITY_SKILLS (70) in the system prompt
+     * 3. Make `skill` and `skill_resource` tools available to the agent
+     *
+     * Skills use progressive disclosure:
+     * - L1 (summary): always in system prompt — names + descriptions
+     * - L2 (content): loaded on demand via `skill` tool
+     * - L3 (resources): loaded on demand via `skill_resource` tool
+     *
+     * @example
+     * ```typescript
+     * const agent = createAgent({
+     *   model: anthropic("claude-sonnet-4-20250514"),
+     *   prompt: {
+     *     skills: {
+     *       externalDirs: [".agents", ".claude"],
+     *       roots: ["./company-skills"],
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    skills?: SkillConfig;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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).
@@ -1159,456 +1443,633 @@ declare function httpServer(url: string, options?: Omit<HttpTransportConfig, "tr
 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
+ * Agent configuration and state types for @cuylabs/agent-core
  *
- * Each layer is optional, composable, and can be toggled on/off.
+ * Defines AgentConfig (the main config surface), AgentState,
+ * doom-loop types, and compaction configuration.
  */
 
 /**
- * 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.
+ * Agent configuration
  */
-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;
+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
+     */
+    doomLoopThreshold?: number;
+    /**
+     * Context compaction configuration.
+     * Controls automatic management of the context window.
+     *
+     * @see CompactionConfig
+     */
+    compaction?: CompactionConfig;
+    /**
+     * Middleware for agent lifecycle hooks.
+     *
+     * Middleware runs in array order for "before" operations and reverse
+     * order for "after" operations. Each middleware is a plain object with
+     * optional hook methods — no classes or registration required.
+     *
+     * Middleware hooks:
+     * - `beforeToolCall` — intercept tool calls (approve/deny)
+     * - `afterToolCall` — transform tool results
+     * - `promptSections` — inject dynamic prompt content
+     * - `onEvent` — observe streaming events
+     * - `onChatStart` / `onChatEnd` — lifecycle callbacks
+     *
+     * @example
+     * ```typescript
+     * const agent = createAgent({
+     *   middleware: [
+     *     approvalMiddleware({ onRequest: askUser }),
+     *     { name: "logger", onEvent: (e) => console.log(e.type) },
+     *   ],
+     * });
+     * ```
+     */
+    middleware?: AgentMiddleware[];
+    /**
+     * 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;
 }
 /**
- * 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.
+ * Agent state
  */
-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;
+interface AgentState {
+    model: LanguageModel;
+    systemPrompt: string;
+    cwd: string;
+    isStreaming: boolean;
+    /** Current reasoning level */
+    reasoningLevel: ReasoningLevel;
+    error?: Error;
 }
 /**
- * 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.
+ * Doom loop handler response - what to do when a doom loop is detected.
  *
- * 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
+ * Actions:
+ * - "allow" - Allow this once
+ * - "remember" - Allow and remember for this session
+ * - "deny" - Reject and throw error
  */
-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;
-}
+type DoomLoopAction = "allow" | "deny" | "remember";
 /**
- * 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.
+ * Doom loop detection request.
+ * Sent to the handler when repeated tool calls are detected.
  */
-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;
+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;
 }
 /**
- * Configuration for the prompt pipeline.
+ * Handler for doom loop situations.
  *
- * 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.
+ * Return:
+ * - "allow": Continue despite the loop
+ * - "deny": Stop execution and throw error
+ * - "remember": Allow and don't ask again for this tool in this session
  *
  * @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 },
- *   ],
+ * 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;
+ *   },
  * });
  * ```
  */
-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;
+type DoomLoopHandler = (request: DoomLoopRequest) => Promise<DoomLoopAction>;
+/**
+ * Configuration for automatic context compaction.
+ *
+ * Features:
+ * - Auto-pruning of old tool outputs
+ * - LLM-based summarization
+ * - Auto-continue after compaction
+ */
+interface CompactionConfig {
     /**
-     * Discover and include instruction files (AGENTS.md, etc.).
-     * @default true
+     * Enable automatic compaction when context overflows.
+     * Default: true
      */
-    includeInstructions?: boolean;
+    auto?: 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"]
+     * Enable pruning of old tool outputs before summarization.
+     * This is a lightweight operation that removes tool result content.
+     * Default: true
      */
-    instructionPatterns?: string[];
+    prune?: boolean;
     /**
-     * Absolute paths to global instruction files (always included
-     * regardless of cwd). Useful for organization-wide rules.
+     * Protect this many recent tokens from pruning.
+     * Default: 40,000
      */
-    globalInstructions?: string[];
+    protectedTokens?: number;
     /**
-     * Maximum depth to walk up from cwd when searching for instructions.
-     * Prevents scanning the entire filesystem.
-     * @default 10
+     * Minimum tokens to trigger pruning.
+     * Default: 20,000
      */
-    instructionMaxDepth?: number;
+    pruneMinimum?: number;
     /**
-     * Maximum file size in bytes for instruction files.
-     * Files larger than this are skipped to avoid bloating the prompt.
-     * @default 51200 (50KB)
+     * Custom summarization prompt for compaction.
+     * If not provided, uses default prompt asking for continuation context.
      */
-    instructionMaxSize?: number;
+    summaryPrompt?: string;
     /**
-     * Pre-defined sections to include in every prompt build.
-     * These are merged with auto-generated sections (template, environment, etc.).
+     * 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.
      */
-    sections?: PromptSection[];
+    summaryModel?: LanguageModel;
     /**
-     * Separator between sections in the final composed prompt.
-     * @default "\n\n"
+     * Auto-continue after compaction with "Continue if you have next steps".
+     * Default: true
      */
-    separator?: string;
+    autoContinue?: boolean;
 }
 
 /**
- * Agent configuration and state types for @cuylabs/agent-core
+ * Middleware Types
  *
- * Defines AgentConfig (the main config surface), AgentState,
- * doom-loop types, and compaction configuration.
+ * Defines the composable middleware interface for agent lifecycle hooks.
+ *
+ * Middleware is just a plain object with optional hook methods — no
+ * base classes, no discovery, no installation. Pass it in code:
+ *
+ * ```typescript
+ * const agent = createAgent({
+ *   middleware: [myLoggerMiddleware, myApprovalMiddleware],
+ * });
+ * ```
+ *
+ * Hooks run in array order for "before" operations and reverse order
+ * for "after" operations (like middleware stacks everywhere).
  */
 
 /**
- * Agent configuration
+ * Action returned by `beforeToolCall` — determines whether
+ * the tool call proceeds or is blocked.
  */
-interface AgentConfig {
-    /** Vercel AI SDK model instance */
-    model: LanguageModel;
-    /** System prompt */
-    systemPrompt?: string;
-    /** Working directory */
-    cwd?: string;
+interface ToolCallDecision {
+    /** Whether to allow or deny the tool call */
+    action: "allow" | "deny";
+    /** Reason for denial — returned to the model as the tool output */
+    reason?: string;
+}
+/**
+ * Agent middleware — composable lifecycle hooks.
+ *
+ * All methods are optional. Implement only what you need.
+ *
+ * Ordering:
+ * - `beforeToolCall`: runs in array order, first "deny" wins
+ * - `afterToolCall`: runs in reverse order (innermost first)
+ * - `promptSections`: all run, sections merged
+ * - `onEvent`: all run in parallel (non-blocking)
+ * - `onChatStart` / `onChatEnd`: run in array order, awaited sequentially
+ *
+ * @example
+ * ```typescript
+ * // A simple logging middleware
+ * const logger: AgentMiddleware = {
+ *   name: "logger",
+ *   beforeToolCall: async (tool, args) => {
+ *     console.log(`→ ${tool}`, args);
+ *     return { action: "allow" };
+ *   },
+ *   afterToolCall: async (tool, args, result) => {
+ *     console.log(`← ${tool}`, result.title);
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+interface AgentMiddleware {
+    /** Middleware name (for logging and debugging) */
+    name: string;
     /**
-     * Execution environment for tools.
+     * Intercept a tool call before execution.
      *
-     * 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";
+     * Return `{ action: "allow" }` to proceed, or `{ action: "deny", reason }` to
+     * block the call. When denied, `reason` is returned to the model as the tool
+     * output so it can adjust its approach.
      *
-     * // Explicit local host (same as default)
-     * const agent = createAgent({ host: localHost("/my/project") });
+     * Runs in array order. The first middleware that returns "deny" short-circuits
+     * the chain — remaining middleware and the tool itself are skipped.
      *
-     * // Future: Docker host
-     * // const agent = createAgent({ host: dockerHost("my-container") });
-     * ```
+     * @param tool   - Tool name (e.g. "bash", "write_file")
+     * @param args   - Parsed tool arguments
+     * @param ctx    - Tool execution context (cwd, sessionID, host, etc.)
      */
-    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;
+    beforeToolCall?(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
     /**
-     * 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
+     * Transform or observe a tool result after execution.
      *
-     * @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.
+     * Receives the result and must return a result (can be the same object
+     * or a modified copy). Runs in reverse array order so the outermost
+     * middleware sees the final transformed result.
      *
-     * @see CompactionConfig
+     * @param tool   - Tool name
+     * @param args   - Original tool arguments
+     * @param result - Tool execution result
+     * @param ctx    - Tool execution context
      */
-    compaction?: CompactionConfig;
+    afterToolCall?(tool: string, args: unknown, result: Tool$1.ExecuteResult, ctx: ToolContext): Promise<Tool$1.ExecuteResult>;
     /**
-     * Context window size in tokens (for overflow detection).
-     * If not provided, defaults to 128,000 tokens.
+     * Inject dynamic prompt sections at build time.
      *
-     * This should match your model's context limit.
-     */
-    contextWindow?: number;
-    /**
-     * Custom stream provider for specialized models (e.g., OpenAI computer use).
+     * Called during `PromptBuilder.build()` for each middleware. Return one
+     * or more sections to inject into the system prompt. Return `undefined`
+     * or an empty array to inject nothing.
      *
-     * 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.
+     * Sections follow the same priority system as static sections — use
+     * `priority` to control placement relative to base template (10),
+     * environment (20), instructions (30), custom (50), skills (70),
+     * and per-turn overrides (90).
      *
-     * The returned object must have a `fullStream` async iterable that yields
-     * AI SDK compatible chunks (text-delta, tool-call, tool-result, etc.).
+     * @param ctx - Build context with cwd, model, toolNames, sessionId
      */
-    streamProvider?: StreamProvider;
+    promptSections?(ctx: PromptBuildContext): PromptSection | PromptSection[] | undefined;
     /**
-     * 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.
+     * Observe agent events (read-only, non-blocking).
      *
-     * @example
-     * ```typescript
-     * import { createMCPManager } from "@cuylabs/agent-core";
+     * Fires for every event emitted during `chat()`. Errors thrown by
+     * handlers are caught and logged — they never interrupt the stream.
      *
-     * const mcp = createMCPManager({
-     *   filesystem: {
-     *     transport: "stdio",
-     *     command: "npx",
-     *     args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
-     *   },
-     * });
+     * This is intentionally synchronous (void return) to prevent
+     * event observers from blocking the streaming pipeline.
      *
-     * const agent = createAgent({
-     *   model: openai("gpt-4o"),
-     *   mcp,
-     * });
-     * ```
+     * @param event - The agent event
      */
-    mcp?: MCPManager;
+    onEvent?(event: AgentEvent): void;
     /**
-     * Prompt pipeline configuration.
+     * Called when `chat()` starts, before the LLM stream is created.
      *
-     * 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
+     * Use this for setup: initializing loggers, recording start time,
+     * resetting per-turn state, etc. Runs in array order, awaited
+     * sequentially.
      *
-     * When neither `prompt` nor `systemPrompt` is provided, the pipeline
-     * is enabled with sensible defaults.
+     * @param sessionId - Session identifier
+     * @param message   - The user message being sent
+     */
+    onChatStart?(sessionId: string, message: string): Promise<void>;
+    /**
+     * Called when `chat()` completes (or errors), after all events
+     * have been yielded.
      *
-     * When `systemPrompt` is provided without `prompt`, the flat string
-     * is used directly (backward compatible).
+     * Use this for teardown: flushing logs, recording metrics, etc.
+     * Runs in array order, awaited sequentially. Always called, even
+     * if the stream errored.
      *
-     * @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." },
-     *     ],
-     *   },
-     * });
-     * ```
+     * @param sessionId - Session identifier
+     * @param result    - Completion info (usage stats and optional error)
      */
-    prompt?: PromptConfig;
+    onChatEnd?(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+    }): Promise<void>;
+}
+
+/**
+ * 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;
 }
 /**
- * Agent state
+ * Model/config change entry
  */
-interface AgentState {
-    model: LanguageModel;
-    systemPrompt: string;
-    cwd: string;
-    isStreaming: boolean;
-    /** Current reasoning level */
-    reasoningLevel: ReasoningLevel;
-    error?: Error;
+interface ConfigChangeEntry extends EntryBase {
+    type: "config_change";
+    /** What changed */
+    change: "model" | "reasoning_level" | "temperature" | "other";
+    /** Previous value */
+    from?: string;
+    /** New value */
+    to: string;
 }
 /**
- * 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
+ * All entry types (excluding header)
  */
-type DoomLoopAction = "allow" | "deny" | "remember";
+type SessionEntry = MessageEntry | CompactionEntry | MetadataEntry | BranchEntry | ConfigChangeEntry;
 /**
- * Doom loop detection request.
- * Sent to the handler when repeated tool calls are detected.
+ * All file entries (including header)
  */
-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;
-}
+type FileEntry = SessionHeader | SessionEntry;
 /**
- * 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;
- *   },
- * });
- * ```
+ * Session summary info (lightweight, for listing)
  */
-type DoomLoopHandler = (request: DoomLoopRequest) => Promise<DoomLoopAction>;
+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;
+}
 /**
- * Configuration for automatic context compaction.
- *
- * Aligned with OpenCode's SessionCompaction:
- * - Auto-pruning of old tool outputs
- * - LLM-based summarization
- * - Auto-continue after compaction
+ * Session storage interface
+ * Pluggable backend for session persistence
  */
-interface CompactionConfig {
+interface SessionStorage {
     /**
-     * Enable automatic compaction when context overflows.
-     * Default: true (matches OpenCode's default)
+     * Create a new session
      */
-    auto?: boolean;
+    create(header: SessionHeader): Promise<void>;
     /**
-     * Enable pruning of old tool outputs before summarization.
-     * This is a lightweight operation that removes tool result content.
-     * Default: true
+     * Append an entry to a session
      */
-    prune?: boolean;
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
     /**
-     * Protect this many recent tokens from pruning.
-     * Default: 40,000 (like OpenCode's PRUNE_PROTECT)
+     * Append multiple entries atomically
      */
-    protectedTokens?: number;
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
     /**
-     * Minimum tokens to trigger pruning.
-     * Default: 20,000 (like OpenCode's PRUNE_MINIMUM)
+     * Read all entries from a session
      */
-    pruneMinimum?: number;
+    read(sessionId: string): Promise<FileEntry[]>;
     /**
-     * Custom summarization prompt for compaction.
-     * If not provided, uses default prompt asking for continuation context.
+     * Delete a session
      */
-    summaryPrompt?: string;
+    delete(sessionId: string): Promise<boolean>;
     /**
-     * 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.
+     * Check if session exists
      */
-    summaryModel?: LanguageModel;
+    exists(sessionId: string): Promise<boolean>;
     /**
-     * Auto-continue after compaction with "Continue if you have next steps".
-     * Like OpenCode's behavior.
-     * Default: true
+     * List all sessions (lightweight info only)
      */
-    autoContinue?: boolean;
+    list(): Promise<SessionInfo[]>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
 }
+/**
+ * Current storage format version
+ */
+declare const STORAGE_VERSION = 1;
 
 /**
  * Session Manager
@@ -1900,7 +2361,7 @@ declare class FileStorage implements SessionStorage {
  * - Windows: %APPDATA%/cuylabs/
  *
  * Project identification:
- * - Uses git root commit hash (like OpenCode) for git repos
+ * - Uses git root commit hash for git repos
  * - Falls back to encoded path for non-git directories
  */
 /**
@@ -2063,6 +2524,8 @@ declare const Presets: {
     readonly review: Preset;
     readonly quick: Preset;
     readonly careful: Preset;
+    readonly code: Preset;
+    readonly watch: Preset;
 };
 /**
  * Create a custom preset with defaults
@@ -2079,8 +2542,6 @@ declare function createPreset(options: Partial<Preset> & {
  * 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' });
@@ -2388,9 +2849,9 @@ declare function summarizeEnvironment(info: EnvironmentInfo): string;
  * 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
+ * - AGENTS.md convention
+ * - CLAUDE.md convention
+ * - COPILOT.md convention
  * - CuyLabs' own .cuylabs/instructions.md
  */
 
@@ -2475,6 +2936,242 @@ declare function loadGlobalInstructions(paths: string[], maxSize?: number): Prom
  */
 declare function formatInstructions(files: InstructionFile[], basePath?: string): string;
 
+/**
+ * Skill Registry — in-memory store for discovered skills
+ *
+ * The registry is the central coordination point for the skill system.
+ * It holds discovered metadata (L1), handles on-demand content loading
+ * (L2/L3), provides the prompt summary for injection, and manages
+ * the lifecycle of skill state.
+ *
+ * ```
+ *   discoverSkills() → SkillRegistry → promptSummary (L1 → system prompt)
+ *                                     → loadSkill()   (L2 → tool response)
+ *                                     → loadResource  (L3 → tool response)
+ * ```
+ *
+ * The registry is designed to be created once per agent and shared
+ * across the agent's lifetime, including across forked sub-agents.
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ * });
+ *
+ * // L1: summary goes into system prompt
+ * const summary = registry.formatSummary();
+ *
+ * // L2: agent calls skill tool → full content loaded
+ * const content = await registry.loadContent("testing");
+ *
+ * // L3: agent reads a bundled reference
+ * const ref = await registry.loadResource("testing", "references/patterns.md");
+ * ```
+ */
+
+/**
+ * In-memory registry of discovered skills with lazy content loading.
+ *
+ * Holds L1 metadata for all skills. Content (L2) and resources (L3)
+ * are loaded on demand and cached for the registry's lifetime.
+ */
+declare class SkillRegistry {
+    /** All discovered skill metadata indexed by name */
+    private readonly skills;
+    /** Cached full content for skills that have been loaded */
+    private readonly contentCache;
+    /** Discovery metadata */
+    readonly discoveryResult: SkillDiscoveryResult;
+    constructor(discoveryResult: SkillDiscoveryResult);
+    /** Get a skill's metadata by name. Returns undefined if not found. */
+    get(name: string): SkillMetadata | undefined;
+    /** Check if a skill exists by name. */
+    has(name: string): boolean;
+    /** Get all skill metadata entries. */
+    list(): SkillMetadata[];
+    /** Number of registered skills. */
+    get size(): number;
+    /** Skill names as an array. */
+    get names(): string[];
+    /**
+     * Load a skill's full content (L2: body + resource listing).
+     *
+     * Results are cached — subsequent calls return the cached content
+     * without re-reading the filesystem.
+     *
+     * @param name Skill name
+     * @returns Full skill content, or null if the skill doesn't exist
+     */
+    loadContent(name: string): Promise<SkillContent | null>;
+    /**
+     * Load a specific bundled resource from a skill (L3).
+     *
+     * The skill's content must be loaded first (via `loadContent`)
+     * so the resource listing is available.
+     *
+     * @param skillName  Skill name
+     * @param relativePath  Relative path to the resource within the skill dir
+     * @returns Resource file content as UTF-8 string
+     * @throws If the skill or resource doesn't exist
+     */
+    loadResource(skillName: string, relativePath: string): Promise<string>;
+    /**
+     * Get the list of resources for a loaded skill.
+     *
+     * @param name Skill name
+     * @returns Resource list, or empty array if skill isn't loaded yet
+     */
+    getResources(name: string): SkillResource[];
+    /**
+     * Format a summary of all available skills for injection into the system prompt.
+     *
+     * This is the L1 layer — the agent sees names and descriptions of all
+     * available skills, enabling it to decide which to activate via tool calls.
+     *
+     * The output format uses XML tags (consistent with the instruction format
+     * in `formatInstructions`) for clear delineation in the prompt.
+     *
+     * Returns empty string if no skills are available.
+     *
+     * @example Output:
+     * ```xml
+     * <available-skills>
+     *
+     * You have access to the following skills. To activate a skill and load its
+     * full instructions, call the `skill` tool with the skill's name.
+     *
+     * <skill name="testing" scope="project">
+     * Write comprehensive test suites with vitest, covering unit, integration,
+     * and snapshot testing patterns.
+     * </skill>
+     *
+     * <skill name="frontend-design" scope="user">
+     * Create distinctive, production-grade frontend interfaces with high design quality.
+     * </skill>
+     *
+     * </available-skills>
+     * ```
+     */
+    formatSummary(): string;
+    /**
+     * Format the full content of a loaded skill for a tool response.
+     *
+     * Wraps the skill body in XML with metadata, and lists bundled resources
+     * so the agent knows what's available at L3.
+     *
+     * @param content Previously loaded skill content
+     * @returns Formatted string for tool response
+     */
+    formatContent(content: SkillContent): string;
+    /** Clear the content cache, forcing reloads on next access. */
+    clearContentCache(): void;
+    /** Check if a skill's content has been loaded and cached. */
+    isContentLoaded(name: string): boolean;
+}
+/**
+ * Create a skill registry by discovering all available skills.
+ *
+ * This is the recommended way to initialize the skill system.
+ * It runs discovery, deduplicates by scope priority, and returns
+ * a ready-to-use registry.
+ *
+ * @param cwd     Current working directory
+ * @param config  Skill configuration
+ * @returns A populated SkillRegistry
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ *   roots: ["./company-skills"],
+ * });
+ *
+ * console.log(`Found ${registry.size} skills`);
+ * console.log(registry.formatSummary());
+ * ```
+ */
+declare function createSkillRegistry(cwd: string, config?: SkillConfig): Promise<SkillRegistry>;
+/**
+ * Create an empty skill registry (for agents that don't use skills).
+ */
+declare function emptySkillRegistry(): SkillRegistry;
+
+/**
+ * Middleware Runner
+ *
+ * Executes middleware hooks in the correct order with proper
+ * error handling and short-circuit semantics.
+ *
+ * This is the internal engine — consumers never see it.
+ * They interact with middleware through AgentConfig.middleware.
+ */
+
+/**
+ * Middleware runner — holds an ordered list of middleware and
+ * exposes methods to run each hook type with correct semantics.
+ *
+ * Immutable after construction. Fork creates a new runner
+ * (with inherited + additional middleware).
+ */
+declare class MiddlewareRunner {
+    private readonly stack;
+    constructor(middleware?: AgentMiddleware[]);
+    /** Number of registered middleware */
+    get count(): number;
+    /** Whether any middleware is registered */
+    get hasMiddleware(): boolean;
+    /** Get the middleware list (for fork inheritance) */
+    getMiddleware(): readonly AgentMiddleware[];
+    /**
+     * Run all `beforeToolCall` hooks in order.
+     *
+     * Returns `{ action: "allow" }` if all middleware allow (or have no hook).
+     * Returns `{ action: "deny", reason }` on first denial — remaining
+     * middleware are skipped.
+     */
+    runBeforeToolCall(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Run all `afterToolCall` hooks in reverse order.
+     *
+     * Each hook receives the result from the previous hook (or the
+     * original tool result for the first hook). Errors are caught
+     * and logged — the original result passes through.
+     */
+    runAfterToolCall(tool: string, args: unknown, result: Tool$1.ExecuteResult, ctx: ToolContext): Promise<Tool$1.ExecuteResult>;
+    /**
+     * Collect prompt sections from all middleware.
+     *
+     * Returns a flat array of sections. Each middleware can return a single
+     * section, an array of sections, or undefined/empty.
+     */
+    collectPromptSections(ctx: PromptBuildContext): PromptSection[];
+    /**
+     * Broadcast an event to all middleware observers.
+     *
+     * Non-blocking — errors are caught and logged. This never
+     * slows down the streaming pipeline.
+     */
+    emitEvent(event: AgentEvent): void;
+    /**
+     * Run all `onChatStart` hooks in order.
+     *
+     * Errors are caught and logged — a broken logger should not
+     * prevent the chat from starting.
+     */
+    runChatStart(sessionId: string, message: string): Promise<void>;
+    /**
+     * Run all `onChatEnd` hooks in order.
+     *
+     * Always called, even when the stream errored. Errors in handlers
+     * are caught and logged.
+     */
+    runChatEnd(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+    }): Promise<void>;
+}
+
 /**
  * PromptBuilder — The pipeline orchestrator
  *
@@ -2489,7 +3186,7 @@ declare function formatInstructions(files: InstructionFile[], basePath?: string)
  *   ├──────────────────┤
  *   │  Custom Sections  │  priority 50 — user-defined content
  *   ├──────────────────┤
- *   │  (Skills slot)    │  priority 70 — reserved for future skill injection
+ *   │  Skills Summary    │  priority 70 — L1 skill names + descriptions
  *   ├──────────────────┤
  *   │  Per-Turn Override │  priority 90 — session-specific context
  *   └──────────────────┘
@@ -2522,7 +3219,7 @@ declare const PRIORITY_ENVIRONMENT = 20;
 declare const PRIORITY_INSTRUCTIONS = 30;
 /** Priority for custom user-defined sections (default) */
 declare const PRIORITY_CUSTOM = 50;
-/** Priority reserved for future skill injections */
+/** Priority for skill summary injection (L1 names + descriptions) */
 declare const PRIORITY_SKILLS = 70;
 /** Priority for per-turn override content */
 declare const PRIORITY_OVERRIDE = 90;
@@ -2562,6 +3259,8 @@ declare class PromptBuilder {
     private envCache?;
     /** Cached instruction files */
     private instructionCache?;
+    /** Cached skill registry */
+    private skillRegistryCache?;
     constructor(config?: PromptConfig);
     /**
      * Build the complete system prompt from all active layers.
@@ -2573,9 +3272,10 @@ declare class PromptBuilder {
      * with the configured separator.
      *
      * @param context - Build context with cwd, model, and optional override
+     * @param middleware - Optional middleware runner to collect dynamic sections from
      * @returns The composed system prompt string
      */
-    build(context: PromptBuildContext): Promise<string>;
+    build(context: PromptBuildContext, middleware?: MiddlewareRunner): Promise<string>;
     /**
      * Add or replace a custom section.
      *
@@ -2630,6 +3330,16 @@ declare class PromptBuilder {
      * - You want to force a refresh on the next build()
      */
     clearCache(): void;
+    /**
+     * Get the skill registry for the current working directory.
+     *
+     * Runs skill discovery on first call and caches the result.
+     * Consumers can use this to get the registry for creating skill tools.
+     *
+     * @param cwd Working directory for skill discovery
+     * @returns The skill registry (may be empty if no skills config)
+     */
+    getSkillRegistry(cwd: string): Promise<SkillRegistry>;
     /**
      * Get the model family that would be used for a given model.
      * Useful for debugging template selection.
@@ -2698,8 +3408,8 @@ declare function createPromptBuilder(config?: PromptConfig): PromptBuilder;
  * 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
+ * Instead of polling a queue after each tool execution, 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.
  *
@@ -2933,6 +3643,8 @@ declare class Agent {
     private interventionCtrl;
     /** Execution environment for tool operations */
     private host;
+    /** Middleware runner for lifecycle hooks */
+    private middlewareRunner;
     constructor(config: AgentConfig & {
         tools?: Tool$1.AnyInfo[];
         sessionManager?: SessionManager;
@@ -2999,11 +3711,6 @@ declare class Agent {
     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
@@ -3305,6 +4012,10 @@ declare class Agent {
         reasoningLevel?: ReasoningLevel;
         /** Apply a preset configuration */
         preset?: Preset;
+        /** Override middleware (if not provided, inherits parent's middleware) */
+        middleware?: AgentMiddleware[];
+        /** Additional middleware appended after inherited middleware */
+        additionalMiddleware?: AgentMiddleware[];
     }): Agent;
     /**
      * Create a sub-agent with a preset configuration.
@@ -3628,6 +4339,13 @@ interface LLMStreamInput {
      * Only works with the standard AI SDK path (not custom stream providers).
      */
     intervention?: InterventionController;
+    /**
+     * Middleware runner for lifecycle hooks.
+     *
+     * When provided, tool calls are wrapped with before/after hooks
+     * from registered middleware.
+     */
+    middleware?: MiddlewareRunner;
 }
 /**
  * Step information
@@ -3660,7 +4378,7 @@ declare namespace LLM {
      * @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>;
+    function buildToolSet(tools: Record<string, Tool$1.Info>, cwd: string, sessionID: string, messageID: string, abort: AbortSignal, turnTracker?: TurnTrackerContext, host?: ToolHost, middleware?: MiddlewareRunner): Promise<ToolSet>;
     /**
      * Create a stream for LLM completion with retry support
      */
@@ -4087,7 +4805,7 @@ declare function findCutPoint(messages: Message[], protectedTokens?: number): nu
 /**
  * Prune old, large tool results from the conversation.
  *
- * This mirrors OpenCode's `SessionCompaction.prune()` pattern:
+ * Prune strategy:
  * - Walks backwards through messages
  * - Protects recent outputs (within {@link protectedTokens})
  * - Skips protected tools (e.g. "skill")
@@ -4208,17 +4926,80 @@ declare class ContextManager {
     /**
      * Get a snapshot of token statistics.
      *
-     * Useful for dashboards, logging, or deciding whether to prune.
+     * 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;
+    };
+}
+
+/**
+ * Approval Middleware
+ *
+ * Wraps the existing approval system as an AgentMiddleware.
+ * This is how approval finally gets wired into the tool execution
+ * pipeline — no more dead code.
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, approvalMiddleware } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: [read, write, bash],
+ *   middleware: [
+ *     approvalMiddleware({
+ *       rules: [
+ *         { pattern: "src/*", tool: "read_file", action: "allow" },
+ *       ],
+ *       onRequest: async (req) => {
+ *         // Prompt user in your UI
+ *         return await askUser(req);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for the approval middleware.
+ *
+ * Extends the existing ApprovalConfig with middleware-specific options.
+ */
+interface ApprovalMiddlewareConfig extends ApprovalConfig {
+    /**
+     * Custom risk classification for tools.
+     *
+     * Overrides the built-in risk map. Tools not listed here
+     * fall back to the default classification.
+     *
+     * @example
+     * ```typescript
+     * customRisks: {
+     *   "my_deploy_tool": "dangerous",
+     *   "my_lint_tool": "safe",
+     * }
+     * ```
      */
-    getStats(messages: (Message | ModelMessage)[]): {
-        tokens: number;
-        limit: number;
-        available: number;
-        utilizationPercent: number;
-        isOverflowing: boolean;
-        shouldPrune: boolean;
-    };
+    customRisks?: Record<string, RiskLevel>;
 }
+/**
+ * Create an approval middleware from an ApprovalConfig.
+ *
+ * This bridges the existing `createApprovalHandler` into the middleware
+ * system. The `beforeToolCall` hook checks rules, classifies risk,
+ * and calls the approval handler when needed.
+ *
+ * @param config - Approval configuration (rules, handler, timeout, etc.)
+ * @returns An AgentMiddleware that gates tool execution
+ */
+declare function approvalMiddleware(config?: ApprovalMiddlewareConfig): AgentMiddleware;
 
 /**
  * LocalHost — executes tools on the local machine.
@@ -4387,6 +5168,620 @@ interface DockerHostOptions {
  */
 declare function dockerHost(options: DockerHostOptions): Promise<ToolHost>;
 
+/**
+ * Skill Loader — parses SKILL.md files with YAML frontmatter
+ *
+ * Handles the core I/O of reading a SKILL.md file and extracting:
+ * - YAML frontmatter → SkillMetadata (L1)
+ * - Markdown body → SkillContent (L2)
+ * - Directory scan → SkillResource[] (L3)
+ *
+ * The frontmatter format follows the widely-adopted SKILL.md convention:
+ *
+ * ```markdown
+ * ---
+ * name: my-skill
+ * description: When to use this skill...
+ * version: 1.0.0
+ * tags: [testing, typescript]
+ * dependencies: [another-skill]
+ * ---
+ *
+ * # Skill Instructions
+ *
+ * The full markdown body with instructions for the agent...
+ * ```
+ *
+ * We parse YAML manually (no external dependency) since frontmatter
+ * is simple key-value pairs. This keeps agent-core dependency-free.
+ */
+
+/** The canonical skill definition filename */
+declare const SKILL_FILENAME = "SKILL.md";
+/** Maximum file size for SKILL.md (100KB) */
+declare const DEFAULT_SKILL_MAX_SIZE = 102400;
+/**
+ * Parse YAML frontmatter from a markdown file content string.
+ *
+ * Handles the `---` delimited frontmatter block at the start of the file.
+ * Returns the parsed key-value pairs and the remaining markdown body.
+ *
+ * We intentionally avoid a YAML library dependency — skill frontmatter
+ * is simple enough that a lightweight parser covers all real-world cases.
+ */
+declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+/**
+ * Load skill metadata from a SKILL.md file path.
+ *
+ * This is the lightweight L1 load — reads just enough to populate the
+ * skill summary that goes into the system prompt. Does NOT load the
+ * full body content or scan for resources.
+ *
+ * @param filePath  Absolute path to a SKILL.md file
+ * @param scope     The scope this skill belongs to
+ * @param source    How this skill was discovered
+ * @param maxSize   Maximum file size (skips oversized files)
+ * @returns Parsed metadata, or null if the file is invalid/missing
+ */
+declare function loadSkillMetadata(filePath: string, scope: SkillScope, source: SkillSource, maxSize?: number): Promise<SkillMetadata | null>;
+/**
+ * Load the full skill content including body and resources.
+ *
+ * This is the L2+L3 load — called when the agent activates a skill.
+ * Reads the full markdown body and scans for bundled resource files.
+ *
+ * @param metadata  Previously loaded skill metadata (L1)
+ * @returns Full skill content with body and resource listing
+ */
+declare function loadSkillContent(metadata: SkillMetadata): Promise<SkillContent>;
+/**
+ * Load a specific resource file's content.
+ *
+ * This is the deepest level of progressive disclosure — called only
+ * when the agent explicitly requests a bundled file.
+ *
+ * @param resource The resource to read
+ * @returns File content as UTF-8 string
+ * @throws If the file doesn't exist or can't be read
+ */
+declare function loadResourceContent(resource: SkillResource): Promise<string>;
+/**
+ * Infer the resource type from a file's location and extension.
+ *
+ * Used for files that aren't in a typed subdirectory.
+ * Falls back to "reference" for unknown types.
+ */
+declare function inferResourceType(filePath: string): SkillResourceType;
+
+/**
+ * Skill Discovery — finds SKILL.md files across the filesystem
+ *
+ * Scans multiple roots with scope-based priority to build a complete
+ * picture of available skills. Combines the best discovery patterns:
+ *
+ * - **Hierarchical walk**: scans `.agents/skills/` directories
+ *   between project root and cwd, so subdirectory skills override parents
+ * - **Multi-source approach**: project dirs, user home dirs,
+ *   external convention dirs (.claude, .agents), config-specified paths
+ * - **Standard layout**: `skills/<name>/SKILL.md` directory structure
+ *
+ * Discovery roots are scanned in order of increasing priority:
+ *
+ *   1. Built-in skills (lowest priority, reserved for future)
+ *   2. Global config paths (user-specified `roots`)
+ *   3. User home directory (`~/.agents/skills/`, `~/.claude/skills/`)
+ *   4. Project tree walk (from git root to cwd)
+ *   5. Project local (`.agents/skills/`, `.claude/skills/` in cwd)
+ *
+ * When two skills have the same name, the higher-priority root wins.
+ */
+
+/** Default external dirs to scan for skills (standard conventions) */
+declare const DEFAULT_EXTERNAL_DIRS: string[];
+/** Default max scan depth within each root */
+declare const DEFAULT_MAX_SCAN_DEPTH = 4;
+/**
+ * Discover all skills from configured roots and conventions.
+ *
+ * This is the main discovery function. It scans all roots, loads
+ * metadata for each SKILL.md found, and returns deduplicated results
+ * with scope-based priority (narrower scope wins).
+ *
+ * @param cwd     Current working directory
+ * @param config  Skill configuration (roots, external dirs, etc.)
+ * @returns Discovery result with skills, errors, and timing
+ *
+ * @example
+ * ```typescript
+ * const result = await discoverSkills("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ *   roots: ["./extra-skills"],
+ *   maxScanDepth: 4,
+ * });
+ *
+ * console.log(`Found ${result.skills.length} skills in ${result.durationMs}ms`);
+ * for (const skill of result.skills) {
+ *   console.log(`  ${skill.name} (${skill.scope}): ${skill.description}`);
+ * }
+ * ```
+ */
+declare function discoverSkills(cwd: string, config?: SkillConfig): Promise<SkillDiscoveryResult>;
+
+/**
+ * Skill Tools — built-in tools for agent-initiated skill loading
+ *
+ * Provides two tools that enable the agent to activate skills on demand:
+ *
+ * 1. **`skill`** — Load a skill's full instructions (L2).
+ *    The agent calls this when it recognizes a task matching a skill's
+ *    description. Returns the complete skill body with resource listings.
+ *
+ * 2. **`skill_resource`** — Read a specific bundled resource (L3).
+ *    After loading a skill, the agent can read scripts, references,
+ *    examples, or assets bundled with it.
+ *
+ * These tools expose skills as regular tools the agent can call,
+ * using progressive disclosure so context is used efficiently.
+ *
+ * The tool descriptions are dynamic — they list all available skill names
+ * and descriptions so the agent knows what's available without needing
+ * a separate discovery step.
+ *
+ * @example
+ * ```typescript
+ * import { createSkillTools, createSkillRegistry } from "@cuylabs/agent-core";
+ *
+ * const registry = await createSkillRegistry(cwd, skillConfig);
+ * const tools = createSkillTools(registry);
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: [...myTools, ...tools],
+ * });
+ * ```
+ */
+
+/**
+ * Create the built-in `skill` tool that lets the agent load skill instructions.
+ *
+ * The tool's description is dynamically generated to include all available
+ * skill names and summaries, so the agent knows exactly what's available.
+ *
+ * @param registry The skill registry to load from
+ * @returns A Tool.Info for the `skill` tool
+ */
+declare function createSkillTool(registry: SkillRegistry): Tool$1.AnyInfo;
+/**
+ * Create the built-in `skill_resource` tool for reading bundled files.
+ *
+ * This is the L3 layer — the agent calls this to read specific scripts,
+ * references, examples, or assets bundled with a skill.
+ *
+ * @param registry The skill registry to load from
+ * @returns A Tool.Info for the `skill_resource` tool
+ */
+declare function createSkillResourceTool(registry: SkillRegistry): Tool$1.AnyInfo;
+/**
+ * Create both skill tools (skill + skill_resource) for an agent.
+ *
+ * Returns an empty array if the registry has no skills, so the tools
+ * don't clutter the agent's tool list when skills aren't in use.
+ *
+ * @param registry The skill registry
+ * @returns Array of Tool.AnyInfo (0 or 2 tools)
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry(cwd, config);
+ * const skillTools = createSkillTools(registry);
+ *
+ * const agent = createAgent({
+ *   model: myModel,
+ *   tools: [...codeTools, ...skillTools],
+ * });
+ * ```
+ */
+declare function createSkillTools(registry: SkillRegistry): Tool$1.AnyInfo[];
+
+/**
+ * Sub-Agent Types
+ *
+ * Type definitions for the sub-agent system: profiles, lifecycle status,
+ * handles, and configuration.
+ *
+ * Following PowerShell verb-noun naming (Invoke-Agent, Get-Agent, Stop-Agent).
+ *
+ * Designed for agent-core's composable library architecture.
+ *
+ * Key design decisions:
+ *
+ * 1. **Library-first**: Unlike CLI-embedded tools, these
+ *    are importable building blocks. The consumer creates them with
+ *    `createSubAgentTools(parent)` and opts in — nothing auto-registered.
+ *
+ * 2. **Agent profiles over role configs**: Instead of TOML files or markdown
+ *    agents, we use composable `AgentProfile` objects that wrap existing
+ *    `Preset` + extra metadata the LLM can read.
+ *
+ * 3. **Progressive lifecycle**: Start with synchronous `invoke_agent` (simplest),
+ *    add `wait_agent`/`close_agent` only when async profiles exist.
+ *
+ * 4. **Depth safety**: Hard limit on nesting with configurable max depth.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * An agent profile defines a specialized sub-agent personality.
+ *
+ * Profiles combine a `Preset` (tool filtering, temperature, etc.) with
+ * LLM-facing metadata (name, description, examples) so the model knows
+ * when and how to delegate.
+ *
+ * Profiles define specialized sub-agent personalities with roles
+ * like explorer, worker, planner, and reviewer.
+ *
+ * @example
+ * ```typescript
+ * const explorer: AgentProfile = {
+ *   name: "explorer",
+ *   description: "Fast, read-only codebase exploration. Use when you need to find files, search code, or understand project structure.",
+ *   preset: Presets.explore,
+ *   maxSteps: 30,
+ * };
+ * ```
+ */
+interface AgentProfile {
+    /** Unique identifier used in tool calls (lowercase, no spaces) */
+    name: string;
+    /**
+     * When to use this sub-agent — written for the LLM to consume.
+     *
+     * This is the most important field. The parent LLM reads this to decide
+     * whether to delegate. Include clear trigger phrases.
+     */
+    description: string;
+    /**
+     * Preset to apply (tool filtering, temperature, system prompt, etc.).
+     * If omitted, inherits the parent agent's configuration.
+     */
+    preset?: Preset;
+    /**
+     * Override system prompt for this profile.
+     * Takes precedence over preset's systemPrompt.
+     * Use `{basePrompt}` to include the parent's system prompt.
+     */
+    systemPrompt?: string;
+    /**
+     * Override model for this profile.
+     * Useful for using cheaper/faster models for simple tasks.
+     */
+    model?: LanguageModel;
+    /** Max steps for this sub-agent (default: parent's maxSteps) */
+    maxSteps?: number;
+    /**
+     * Additional middleware appended to the parent's middleware stack.
+     * Useful for adding logging or guardrails specific to this profile.
+     */
+    additionalMiddleware?: AgentMiddleware[];
+    /**
+     * Additional tools beyond what the preset allows.
+     * These are merged with the preset-filtered tools.
+     */
+    additionalTools?: Tool$1.AnyInfo[];
+    /**
+     * Whether this sub-agent can itself spawn further sub-agents.
+     * When false, the `invoke_agent` tool is removed from the child.
+     *
+     * @default false — sub-agents cannot nest by default (safe default)
+     */
+    canSpawn?: boolean;
+}
+/**
+ * Lifecycle status of a running or completed sub-agent.
+ *
+ * Simplified lifecycle for the fire-and-forget-with-optional-wait model.
+ */
+type SubAgentStatus = {
+    state: "running";
+} | {
+    state: "completed";
+    response: string;
+    usage: SubAgentUsage;
+} | {
+    state: "errored";
+    error: string;
+} | {
+    state: "cancelled";
+};
+/**
+ * Token usage tracking for a sub-agent run.
+ */
+interface SubAgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * A handle to a running or completed sub-agent.
+ *
+ * Returned by async invocations. Allows the parent to wait for completion,
+ * check status, or cancel.
+ */
+interface SubAgentHandle {
+    /** Unique ID for this sub-agent invocation */
+    id: string;
+    /** Human-readable name (from profile or auto-generated) */
+    name: string;
+    /** Session ID of the child agent's session */
+    sessionId: string;
+    /** Current status */
+    status: SubAgentStatus;
+    /** The promise that resolves when the sub-agent completes */
+    promise: Promise<SubAgentCompletedResult>;
+    /** Abort controller to cancel this sub-agent */
+    abort: AbortController;
+}
+/**
+ * The final result of a completed sub-agent.
+ */
+interface SubAgentCompletedResult {
+    /** Final response text */
+    response: string;
+    /** Session ID (for audit/inspection) */
+    sessionId: string;
+    /** Token usage */
+    usage: SubAgentUsage;
+    /** Tool calls the sub-agent made */
+    toolCalls: Array<{
+        name: string;
+        result: unknown;
+    }>;
+}
+/**
+ * Configuration for `createSubAgentTools()`.
+ *
+ * Controls which profiles are available, concurrency limits,
+ * depth limits, and whether async mode is enabled.
+ */
+interface SubAgentToolConfig {
+    /**
+     * Available sub-agent profiles.
+     * Each profile defines a specialized persona the LLM can invoke.
+     * At least one profile is required.
+     */
+    profiles: AgentProfile[];
+    /**
+     * Maximum concurrent sub-agents (across all profiles).
+     * @default 6
+     */
+    maxConcurrent?: number;
+    /**
+     * Maximum nesting depth for recursive sub-agent spawning.
+     * Depth 0 = no spawning, 1 = one level of sub-agents, etc.
+     *
+     * When a sub-agent reaches the depth limit, the `invoke_agent`
+     * tool is automatically removed from its tool set.
+     *
+     * @default 2
+     */
+    maxDepth?: number;
+    /**
+     * Current depth (internal — incremented when creating child tools).
+     * Users should not set this directly.
+     *
+     * @internal
+     */
+    currentDepth?: number;
+    /**
+     * Enable async mode with `wait_agent` and `close_agent` tools.
+     *
+     * When false (default), `invoke_agent` blocks until the sub-agent
+     * completes and returns the result directly — simpler but sequential.
+     *
+     * When true, `invoke_agent` returns immediately with an agent ID,
+     * and the LLM must call `wait_agent` to collect results. This enables
+     * parallel sub-agent execution.
+     *
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Title prefix for sub-agent sessions.
+     * @default "Sub-agent"
+     */
+    sessionTitlePrefix?: string;
+}
+/** Default maximum concurrent sub-agents */
+declare const DEFAULT_MAX_CONCURRENT = 6;
+/** Default maximum nesting depth */
+declare const DEFAULT_MAX_SPAWN_DEPTH = 2;
+/** Default session title prefix */
+declare const DEFAULT_SESSION_TITLE_PREFIX = "Sub-agent";
+
+/**
+ * Sub-Agent Tracker — in-memory state for active sub-agents
+ *
+ * Manages the lifecycle of running sub-agents: slots, handles,
+ * concurrency limits, and depth enforcement.
+ *
+ * Handles spawn slot reservation and depth checking, designed for
+ * single-process TypeScript/async usage.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Tracks active sub-agent handles and enforces concurrency/depth limits.
+ *
+ * One tracker is created per `createSubAgentTools()` call and shared
+ * across all sub-agent tool instances for that parent agent.
+ */
+declare class SubAgentTracker {
+    /** Active sub-agent handles by ID */
+    private readonly handles;
+    /** Maximum concurrent sub-agents */
+    readonly maxConcurrent: number;
+    /** Maximum nesting depth */
+    readonly maxDepth: number;
+    /** Current depth in the spawn hierarchy */
+    readonly currentDepth: number;
+    constructor(config?: Partial<SubAgentToolConfig>);
+    /** Number of currently active (running) sub-agents */
+    get activeCount(): number;
+    /** Total tracked handles (including completed) */
+    get totalCount(): number;
+    /**
+     * Check if a new sub-agent can be spawned.
+     * Returns an error message if not, undefined if OK.
+     */
+    canSpawn(): string | undefined;
+    /** Whether the current depth allows further spawning */
+    get canNest(): boolean;
+    /** Register a new sub-agent handle */
+    register(handle: SubAgentHandle): void;
+    /** Get a handle by ID */
+    get(id: string): SubAgentHandle | undefined;
+    /** Update a handle's status */
+    updateStatus(id: string, status: SubAgentStatus): void;
+    /** Get all handles */
+    list(): SubAgentHandle[];
+    /** Get all running handles */
+    running(): SubAgentHandle[];
+    /** Get all completed handles */
+    completed(): SubAgentHandle[];
+    /**
+     * Cancel a running sub-agent.
+     * Signals the abort controller and updates status.
+     */
+    cancel(id: string): boolean;
+    /**
+     * Cancel all running sub-agents.
+     */
+    cancelAll(): void;
+    /**
+     * Wait for a specific sub-agent to complete.
+     * Returns the result or throws if not found.
+     */
+    wait(id: string, timeoutMs?: number): Promise<SubAgentCompletedResult>;
+    /**
+     * Wait for any one of the given sub-agents to complete.
+     * Returns the first result.
+     */
+    waitAny(ids: string[], timeoutMs?: number): Promise<{
+        id: string;
+        result: SubAgentCompletedResult;
+    } | {
+        timedOut: true;
+    }>;
+    /**
+     * Create a child tracker configuration for a nested sub-agent.
+     * Increments the depth counter.
+     */
+    childConfig(): Partial<SubAgentToolConfig>;
+}
+
+/**
+ * Sub-Agent Tools — LLM-callable tools for delegating work to specialized agents
+ *
+ * Provides three tools following PowerShell verb-noun naming:
+ *
+ * 1. **`invoke_agent`** — Spawn a sub-agent for a focused task.
+ *    In sync mode, blocks until completion and returns the result.
+ *    In async mode, returns an agent ID immediately.
+ *
+ * 2. **`wait_agent`** — Wait for one or more async sub-agents to complete.
+ *    Supports timeout. Only available in async mode.
+ *
+ * 3. **`close_agent`** — Cancel a running sub-agent.
+ *    Only available in async mode.
+ *
+ * These tools bridge agent-core's existing `fork().run()` primitives
+ * into the LLM's tool-calling interface, letting the model itself
+ * decide when to delegate.
+ *
+ * Key differentiators from competitors:
+ * - **Library-first**: Created via `createSubAgentTools(parent)`, not auto-registered
+ * - **Profile-based**: Sub-agent types defined as composable `AgentProfile` objects
+ * - **Depth-safe**: Automatic depth limiting removes `invoke_agent` at max depth
+ * - **Dual-mode**: Sync (simple) or async (parallel) — consumer chooses
+ *
+ * @example
+ * ```typescript
+ * import { createSubAgentTools, createAgent, Presets } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({ model, tools: codeTools });
+ * const subAgentTools = createSubAgentTools(agent, {
+ *   profiles: [
+ *     { name: "explorer", description: "Fast read-only search", preset: Presets.explore },
+ *     { name: "reviewer", description: "Thorough code review", preset: Presets.review },
+ *   ],
+ * });
+ *
+ * const fullAgent = createAgent({
+ *   model,
+ *   tools: [...codeTools, ...subAgentTools],
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create the sub-agent tools for an agent.
+ *
+ * Returns an array of tools that the LLM can call to delegate tasks:
+ * - `invoke_agent` — always included
+ * - `wait_agent` — only in async mode
+ * - `close_agent` — only in async mode
+ *
+ * These tools use the parent agent's `fork().run()` under the hood,
+ * so sub-agents inherit the parent's storage, host, MCP connections,
+ * and (optionally) middleware.
+ *
+ * @param parent The parent agent that sub-agents will be forked from
+ * @param config Sub-agent configuration (profiles, limits, mode)
+ * @returns Array of Tool.AnyInfo to add to the agent's tools
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAgent,
+ *   createSubAgentTools,
+ *   Presets,
+ * } from "@cuylabs/agent-core";
+ *
+ * const parent = createAgent({ model, tools: codeTools });
+ *
+ * // Sync mode (simple — invoke blocks until done)
+ * const subTools = createSubAgentTools(parent, {
+ *   profiles: [
+ *     { name: "explorer", description: "Read-only search", preset: Presets.explore },
+ *     { name: "reviewer", description: "Code review", preset: Presets.review },
+ *   ],
+ * });
+ *
+ * // Async mode (parallel — invoke returns ID, wait collects result)
+ * const asyncSubTools = createSubAgentTools(parent, {
+ *   profiles: [
+ *     { name: "explorer", description: "Read-only search", preset: Presets.explore },
+ *     { name: "worker", description: "Implementation", preset: Presets.careful },
+ *   ],
+ *   async: true,
+ *   maxConcurrent: 4,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: [...codeTools, ...subTools],
+ * });
+ * ```
+ */
+declare function createSubAgentTools(parent: Agent, config: SubAgentToolConfig): Tool$1.AnyInfo[];
+
 type AdapterKind = "openai" | "anthropic" | "google" | "openai-compatible";
 type AdapterSettings = {
     apiKey?: string;
@@ -4416,4 +5811,4 @@ type Resolver = (key: string) => Promise<LanguageModel>;
 type SyncResolver = (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 SyncResolver, 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 };
+export { type AdapterSettings, Agent, type AgentConfig, type AgentEvent, type AgentMiddleware, type AgentProfile, type AgentState, type AgentStatus, type AnyStreamResult, type AppliedPreset, type ApprovalAction, type ApprovalConfig, ApprovalDeniedError, type ApprovalEvent, type ApprovalHandler, type ApprovalMiddlewareConfig, 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_EXTERNAL_DIRS, DEFAULT_INSTRUCTION_PATTERNS, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_SCAN_DEPTH, DEFAULT_MAX_SPAWN_DEPTH, DEFAULT_RETRY_CONFIG, DEFAULT_SESSION_TITLE_PREFIX, DEFAULT_SKILL_MAX_SIZE, 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, MiddlewareRunner, 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 RemoteSkillEntry, type RemoteSkillIndex, type ResolverOptions, type ResponseHeaders, type RetryConfig, type RetryHandlerOptions, type RetryState, type RiskLevel, SKILL_FILENAME, STORAGE_VERSION, type Session, type SessionContext, type SessionEntry, type SessionHeader, type SessionInfo, SessionManager, type SessionStorage, type SkillConfig, type SkillContent, type SkillDiscoveryError, type SkillDiscoveryResult, type SkillMetadata, SkillRegistry, type SkillResource, type SkillResourceType, type SkillScope, type SkillSource, type SkillSourceType, type SseTransportConfig, type StdioTransportConfig, type StepInfo, type StreamChunk, type StreamInput, type StreamProvider, type StreamProviderConfig, type StreamProviderFactory, type StreamProviderInput, type StreamProviderResult, type SubAgentCompletedResult, type SubAgentHandle, type SubAgentResult, type SubAgentStatus, type SubAgentToolConfig, SubAgentTracker, type SubAgentUsage, type SummarizationOptions, type SyncResolver, type SystemMessage, type TokenUsage, Tool$1 as Tool, type ToolCallDecision, ToolContext, ToolHost, type ToolMessage, type TrackedToolMetadata, TurnChangeTracker, type TurnFileChange, type TurnSummary, type TurnTrackerConfig, TurnTrackerContext, type UndoResult, type UserMessage, applyPreset, approvalMiddleware, buildMessagesFromEntries, buildReasoningOptions, buildReasoningOptionsSync, calculateDelay, clearCheckpoints, configureDefaultSessionManager, configureResolver, createAgent, createApprovalHandler, createCheckpointManager, createMCPManager, createPreset, createPromptBuilder, createResolver, createRetryHandler, createRetryState, createSkillRegistry, createSkillResourceTool, createSkillTool, createSkillTools, createSubAgentTools, createTurnTracker, defineServer, deserializeMessage, detectModelFamily, discoverInstructions, discoverSkills, dockerHost, emptySkillRegistry, 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, inferResourceType, isContextOverflowing, isRetryable, isRetryableCategory, loadGlobalInstructions, loadResourceContent, loadSkillContent, loadSkillMetadata, localHost, mergePresets, parseFrontmatter, parseJSONL, processStream, pruneContext, pruneToolResults, runConcurrent, serializeMessage, shouldCaptureBaseline, shouldPruneContext, shouldRetry, sleep, sseServer, stdioServer, summarizeEnvironment, supportsReasoning, supportsReasoningSync, toJSONL, withFileTracking, withRetry };