@cuylabs/agent-core 0.9.0 → 0.11.0

package/dist/index-DQuTZ8xL.d.ts

@@ -1,1335 +0,0 @@
-import { LanguageModel } from 'ai';
-import { P as Preset } from './types-BlZwmnuW.js';
-import { T as Tool } from './tool-CZWN3KbO.js';
-import { A as AgentMiddleware, f as StreamProvider, d as PromptConfig } from './types-DTSkxakL.js';
-import { S as SessionManager, f as SessionContext, i as SessionInfo } from './session-manager-KbYt2WUh.js';
-import { T as ToolHost } from './types-CHiPh8U2.js';
-import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
-import { A as AgentEvent } from './events-CE72w8W4.js';
-import { R as ReasoningLevel } from './types-CQaXbRsS.js';
-import { a as MCPManager } from './types-VQgymC1N.js';
-import { A as AgentSignal } from './types-YuWV4ag7.js';
-import { U as UndoResult, T as TurnChangeTracker } from './tracker-DClqYqTj.js';
-import { P as PromptBuilder } from './builder-BgZ_j4Vs.js';
-import { P as PendingIntervention, n as InterventionController } from './types-BlOKk-Bb.js';
-import { M as MiddlewareRunner } from './runner-CI-XeR16.js';
-import { s as DoomLoopHandler, o as AgentTurnStepRuntimeConfig } from './types-DmDwi2zI.js';
-
-/**
- * Tools whose outputs should never be pruned automatically.
- */
-declare const PRUNE_PROTECTED_TOOLS: readonly ["skill"];
-/**
- * Configuration for automatic context compaction.
- */
-interface CompactionConfig {
-    /**
-     * Enable automatic compaction when context overflows.
-     * Default: true
-     */
-    auto?: boolean;
-    /**
-     * Enable pruning of old tool outputs before summarization.
-     * Default: true
-     */
-    prune?: boolean;
-    /**
-     * Protect this many recent tokens from pruning.
-     * Default: 40,000
-     */
-    protectedTokens?: number;
-    /**
-     * Minimum tokens to trigger pruning.
-     * Default: 20,000
-     */
-    pruneMinimum?: number;
-    /**
-     * Custom summarization prompt for compaction.
-     */
-    summaryPrompt?: string;
-    /**
-     * Model to use for summarization. Defaults to the agent model.
-     */
-    summaryModel?: LanguageModel;
-    /**
-     * Auto-continue after compaction with a continuation prompt.
-     * Default: true
-     */
-    autoContinue?: boolean;
-}
-
-/**
- * Tracing configuration for `createAgent({ tracing })`.
- *
- * When provided, the agent auto-creates the OTel middleware and AI SDK
- * telemetry settings, so callers do not need to wire them separately.
- */
-interface TracingConfig {
-    /** Agent description — recorded as `gen_ai.agent.description`. */
-    agentDescription?: string;
-    /** Record tool arguments and LLM prompts in spans. Defaults to `true`. */
-    recordInputs?: boolean;
-    /** Record tool results and LLM responses in spans. Defaults to `true`. */
-    recordOutputs?: boolean;
-    /** Emit `execute_tool` spans from our middleware. Defaults to `true`. */
-    emitToolSpans?: boolean;
-    /** TTL in ms for orphaned spans. Defaults to 5 minutes. */
-    spanTimeoutMs?: number;
-    /**
-     * An OTel `SpanProcessor` used to auto-create and register a tracer provider.
-     */
-    spanProcessor?: unknown;
-    /**
-     * OTel service name for the auto-created provider resource.
-     * Defaults to the agent `name`.
-     */
-    serviceName?: string;
-}
-
-/**
- * Public configuration surface for `createAgent()`.
- */
-interface AgentConfig {
-    /**
-     * Agent name — used as identity in spans, workflow names, and logs.
-     * Defaults to `"agent"`.
-     */
-    name?: string;
-    /** Vercel AI SDK model instance */
-    model: LanguageModel;
-    /** Flat system prompt */
-    systemPrompt?: string;
-    /** Working directory */
-    cwd?: string;
-    /**
-     * Execution environment for tools.
-     */
-    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 supported models */
-    reasoningLevel?: ReasoningLevel;
-    /** Require approval for dangerous operations */
-    requireApproval?: boolean;
-    /**
-     * Handler for doom-loop detection.
-     */
-    onDoomLoop?: DoomLoopHandler;
-    /**
-     * Strictly enforce doom-loop detection when no custom handler is provided.
-     * Default: true
-     */
-    enforceDoomLoop?: boolean;
-    /**
-     * Number of identical tool calls before triggering doom-loop handling.
-     * Default: 3
-     */
-    doomLoopThreshold?: number;
-    /**
-     * Automatic context compaction settings.
-     */
-    compaction?: CompactionConfig;
-    /**
-     * Middleware for the agent lifecycle.
-     */
-    middleware?: AgentMiddleware[];
-    /**
-     * Context window size in tokens for overflow detection.
-     * Defaults to 128,000.
-     */
-    contextWindow?: number;
-    /**
-     * Custom stream provider for specialized models.
-     */
-    streamProvider?: StreamProvider;
-    /**
-     * MCP manager for external tool servers.
-     */
-    mcp?: MCPManager;
-    /**
-     * Layered prompt pipeline configuration.
-     */
-    prompt?: PromptConfig;
-    /**
-     * Simplest way to enable tracing.
-     */
-    tracing?: TracingConfig;
-    /**
-     * Event signal for multi-consumer dispatch.
-     *
-     * Every event yielded by `chat()` is also emitted here, enabling
-     * passive observers (SSE routes, TUI renderers, plugins) to
-     * subscribe without consuming the primary generator.
-     *
-     * Defaults to an in-process `LocalSignal`.  A distributed runtime
-     * can supply its own implementation to bridge events externally.
-     */
-    signal?: AgentSignal;
-}
-
-interface AgentForkOptions {
-    name?: string;
-    systemPrompt?: string;
-    prompt?: PromptConfig;
-    model?: LanguageModel;
-    temperature?: number;
-    tools?: Tool.AnyInfo[];
-    maxSteps?: number;
-    reasoningLevel?: ReasoningLevel;
-    preset?: Preset;
-    middleware?: AgentMiddleware[];
-    additionalMiddleware?: AgentMiddleware[];
-}
-
-type AgentConstructionOptions = AgentConfig & {
-    tools?: Tool.AnyInfo[];
-    sessionManager?: SessionManager;
-};
-
-/**
- * Create an agent instance
- */
-declare function createAgent(config: AgentConstructionOptions): Agent;
-/**
- * Embeddable AI agent with tool support.
- *
- * The `Agent` class is the main entry-point for consumers. It manages:
- * - **Sessions** — persistent conversation history
- * - **Streaming** — real-time event generation via `chat()`
- * - **Tools** — registry + execution context
- * - **Context management** — overflow detection & auto-compaction
- * - **Reasoning** — configurable thinking levels per model
- * - **Sub-agents** — `fork()` / `run()` for parallel or specialised tasks
- *
- * @example
- * ```typescript
- * import { createAgent } from "@cuylabs/agent-core";
- * import { anthropic } from "@ai-sdk/anthropic";
- *
- * const agent = createAgent({
- *   model: anthropic("claude-sonnet-4-20250514"),
- *   cwd: "/path/to/project",
- * });
- *
- * // Streaming
- * for await (const event of agent.chat("session-1", "List all TypeScript files")) {
- *   if (event.type === "text-delta") process.stdout.write(event.text);
- * }
- *
- * // Non-streaming (convenience)
- * const result = await agent.send("session-1", "Fix the bug in utils.ts");
- * console.log(result.response);
- * ```
- */
-declare class Agent {
-    private config;
-    private tools;
-    private sessions;
-    private state;
-    /** Context manager for overflow detection and compaction */
-    private contextManager;
-    /** Tools that user said "remember" for doom loop (don't ask again) */
-    private rememberedDoomLoopTools;
-    /** Turn change tracker for file modification tracking */
-    private turnTracker;
-    /** Counter for turn IDs */
-    private turnCounter;
-    /** MCP manager for external tool servers */
-    private mcpManager?;
-    /** Whether MCP has been connected (lazy init) */
-    private mcpConnected;
-    /** Whether skill tools have been resolved (lazy init) */
-    private skillToolsResolved;
-    /** Cached MCP tools (refreshed on connect) */
-    private mcpToolsCache?;
-    /** Prompt pipeline builder (when using layered prompt mode) */
-    private promptBuilder?;
-    /** Intervention controller for mid-turn message injection */
-    private interventionCtrl;
-    /** Execution environment for tool operations */
-    private host;
-    /** Whether the agent owns the host and can safely recreate it on cwd changes */
-    private ownsHost;
-    /** Middleware runner for lifecycle hooks */
-    private middlewareRunner;
-    /** AI SDK telemetry settings (auto-created from `tracing` config) */
-    private telemetrySettings?;
-    /** Tracing shutdown function (from `tracing` config auto-setup) */
-    private tracingShutdown?;
-    /** Multi-consumer event dispatch */
-    private readonly _signal;
-    /** Number of active turns across all sessions */
-    private activeTurnCount;
-    /** Active turn intervention controllers, keyed by turn id */
-    private readonly activeTurns;
-    /** Per-session turn queue to prevent concurrent writes to the same history */
-    private readonly sessionLocks;
-    constructor(config: AgentConstructionOptions);
-    /**
-     * Event signal — subscribe to events without consuming the generator.
-     *
-     * Every event yielded by `chat()` is also dispatched here, allowing
-     * multiple passive observers (SSE routes, TUI, plugins) to listen
-     * concurrently.
-     */
-    get signal(): AgentSignal;
-    /** Agent name (identity for spans, Dapr workflows, etc.) */
-    get name(): string;
-    /** Working directory for file operations */
-    get cwd(): string;
-    /** Current model */
-    get model(): LanguageModel;
-    /** System prompt */
-    get systemPrompt(): string;
-    /** Is currently streaming */
-    get isStreaming(): boolean;
-    /** Current reasoning level */
-    get reasoningLevel(): ReasoningLevel;
-    /**
-     * Set reasoning level
-     * Will be clamped to available levels for the current model
-     */
-    setReasoningLevel(level: ReasoningLevel): void;
-    /**
-     * Get available reasoning levels for the current model
-     */
-    getAvailableReasoningLevels(): ReasoningLevel[];
-    /**
-     * Check if current model supports reasoning
-     */
-    supportsReasoning(): boolean;
-    /**
-     * Ensure skill tools are registered when `prompt.skills` is configured.
-     * Lazy initialization — resolves the registry and adds tools on first use.
-     */
-    private ensureSkillTools;
-    private resetPromptScopedTools;
-    private createSessionManager;
-    private acquireSessionLock;
-    private getActiveInterventionController;
-    private getInterventionControllerForTurn;
-    private createTurnInterventionController;
-    private releaseTurnInterventions;
-    private syncStreamingState;
-    private syncSessionView;
-    /**
-     * Ensure MCP is connected and return tools
-     * Lazy initialization - only connects on first use
-     */
-    private ensureMCPConnected;
-    /**
-     * Repair session history by synthesising missing tool-result messages.
-     *
-     * When a tool `execute()` throws, the AI SDK emits `tool-error` instead
-     * of `tool-result`. If the error event wasn't persisted (e.g. because
-     * the fix above wasn't in place), subsequent turns will fail with
-     * `MissingToolResultsError`. This method detects orphaned tool-call IDs
-     * and adds placeholder `tool` messages so the history is valid again.
-     */
-    private repairOrphanedToolCalls;
-    /**
-     * Convert internal {@link Message} array to Vercel AI SDK {@link ModelMessage} format.
-     *
-     * Handles the role-specific mappings:
-     * - `user` / `system` → pass-through
-     * - `assistant` with tool calls → `ToolCallPart[]` content
-     * - `tool` → `tool-result` content part
-     */
-    private toModelMessages;
-    /**
-     * Stream a chat response.
-     *
-     * Sends a user message and yields real-time {@link AgentEvent}s as the
-     * model responds, calls tools, and finishes. Conversation state is
-     * persisted to the session automatically.
-     *
-     * @param sessionId - Session identifier for conversation history
-     * @param message   - User message to send
-     * @param options   - Abort signal, system prompt override, and approval handler
-     * @yields {AgentEvent} Events as they occur during processing
-     */
-    chat(sessionId: string, message: string, options?: {
-        abort?: AbortSignal;
-        system?: string;
-    }): AsyncGenerator<AgentEvent>;
-    /**
-     * Send a message and wait for the complete response (non-streaming).
-     *
-     * This is a convenience wrapper around {@link chat} that buffers all
-     * events internally and returns the final response, usage, and tool
-     * call results. Prefer `chat()` when you need real-time streaming.
-     *
-     * @param sessionId - Session identifier
-     * @param message   - User message
-     * @param options   - Abort signal and optional system prompt override
-     */
-    send(sessionId: string, message: string, options?: {
-        abort?: AbortSignal;
-        system?: string;
-    }): Promise<{
-        response: string;
-        usage: TokenUsage;
-        toolCalls: Array<{
-            name: string;
-            result: unknown;
-        }>;
-    }>;
-    /** Add a tool at runtime */
-    addTool(tool: Tool.Info): void;
-    /** Remove a tool by ID */
-    removeTool(toolId: string): boolean;
-    /** Get all tool IDs */
-    getToolIds(): string[];
-    /** Get all tools */
-    getTools(): Tool.AnyInfo[];
-    /** Check if a tool exists */
-    hasTool(toolId: string): boolean;
-    /** Get session manager */
-    getSessionManager(): SessionManager;
-    /** Get current session context */
-    getSessionContext(): SessionContext;
-    /** Get messages from current session */
-    getMessages(): Message[];
-    /** Delete a session */
-    deleteSession(sessionId: string): Promise<boolean>;
-    /** List all sessions */
-    listSessions(): Promise<SessionInfo[]>;
-    /** Branch from current point */
-    branch(summary?: string): Promise<string>;
-    /**
-     * Get context window statistics.
-     *
-     * Useful for UI to display context utilization like:
-     * - Progress bar showing how full the context is
-     * - Warning when approaching limit
-     * - Info about when compaction will trigger
-     *
-     * @example
-     * ```typescript
-     * const stats = agent.getContextStats();
-     * console.log(`Context: ${stats.utilizationPercent}% used`);
-     * if (stats.shouldPrune) {
-     *   console.log('Context will be compacted soon');
-     * }
-     * ```
-     */
-    getContextStats(): {
-        tokens: number;
-        limit: number;
-        available: number;
-        utilizationPercent: number;
-        isOverflowing: boolean;
-        shouldPrune: boolean;
-    };
-    /**
-     * Manually trigger context compaction.
-     *
-     * Usually auto-compaction handles this, but you can trigger it manually
-     * if needed (e.g., before a long operation).
-     *
-     * @returns Pruning result with details about what was removed/summarized
-     */
-    compactContext(): Promise<{
-        removedCount: number;
-        tokensRemoved: number;
-        summarized: boolean;
-        summary?: string;
-    }>;
-    /**
-     * Clear remembered doom loop tools.
-     *
-     * When a user says "remember" for a doom loop, that tool is added
-     * to a set that skips future doom loop checks. Call this to reset.
-     */
-    clearRememberedDoomLoopTools(): void;
-    /**
-     * Inject a message at the next step boundary of a running turn.
-     *
-     * This is the primary redirection mechanism. When the agent is
-     * streaming a multi-step response (calling tools, reasoning, etc.),
-     * this injects a user message before the next LLM call. The LLM
-     * sees the intervention and can adjust its behavior.
-     *
-     * Uses Vercel AI SDK v6's `prepareStep` hook — no polling, no
-     * custom loop code. The SDK handles the injection naturally.
-     *
-     * Safe to call from any async context (UI event handlers, WebSocket
-     * callbacks, timers, etc.) while `chat()` is running.
-     *
-     * If called when no turn is active, the message will be picked up
-     * by the first step of the next `chat()` call.
-     * If multiple turns are active concurrently, this throws because the
-     * target turn would be ambiguous.
-     *
-     * @param message - The user message to inject mid-turn
-     * @returns Intervention ID for tracking
-     *
-     * @example
-     * ```typescript
-     * // Start a streaming turn
-     * const stream = agent.chat("session-1", "refactor the auth module");
-     *
-     * // From a UI handler (another async context):
-     * agent.intervene("stop, focus only on JWT validation in auth.ts");
-     *
-     * // The stream will yield an intervention-applied event
-     * for await (const event of stream) {
-     *   if (event.type === "intervention-applied") {
-     *     console.log(`Redirected: ${event.message}`);
-     *   }
-     * }
-     * ```
-     */
-    intervene(message: string): string;
-    /**
-     * Queue a message for after the current turn completes.
-     *
-     * Unlike `intervene()`, this does **not** interrupt the current turn.
-     * The message is held and available via `drainQueuedNext()` after
-     * `chat()` finishes. The consumer decides whether to send it as a
-     * new turn.
-     *
-     * If multiple turns are active concurrently, this throws because the
-     * target turn would be ambiguous.
-     *
-     * @param message - The message to queue
-     * @returns Intervention ID for tracking
-     *
-     * @example
-     * ```typescript
-     * agent.queueNext("now run the test suite");
-     *
-     * for await (const event of agent.chat("s1", "fix the bug")) {
-     *   // ... handle events
-     * }
-     *
-     * // After turn completes, check for queued messages
-     * if (agent.hasQueuedNext()) {
-     *   const next = agent.drainQueuedNext();
-     *   for (const item of next) {
-     *     // Send as a new turn
-     *     for await (const ev of agent.chat("s1", item.message)) { ... }
-     *   }
-     * }
-     * ```
-     */
-    queueNext(message: string): string;
-    /** Whether there are deferred messages queued for after the turn */
-    hasQueuedNext(): boolean;
-    /** Drain and return all deferred messages (clears the queue) */
-    drainQueuedNext(): PendingIntervention[];
-    /**
-     * Get the raw intervention controller for advanced use cases.
-     *
-     * Use this when you need fine-grained control over the intervention
-     * lifecycle (e.g., checking pending count, clearing queues, setting
-     * custom `onApplied` callbacks).
-     *
-     * @internal
-     */
-    getInterventionController(): InterventionController;
-    /**
-     * Get the unified diff for all file changes in the current/last turn.
-     *
-     * @example
-     * ```typescript
-     * const diff = await agent.getTurnDiff();
-     * if (diff) {
-     *   console.log('Changes this turn:\n', diff);
-     * }
-     * ```
-     */
-    getTurnDiff(): Promise<string | null>;
-    /**
-     * Get list of files being tracked in the current turn.
-     */
-    getTrackedFiles(): string[];
-    /**
-     * Undo all file changes from the current turn.
-     * Restores files to their state before the turn started.
-     *
-     * @example
-     * ```typescript
-     * const result = await agent.undoTurn();
-     * console.log(`Restored ${result.restored.length} files`);
-     * if (result.failed.length > 0) {
-     *   console.log('Failed to restore:', result.failed);
-     * }
-     * ```
-     */
-    undoTurn(): Promise<UndoResult>;
-    /**
-     * Undo changes to specific files only.
-     *
-     * @param files - Array of file paths to restore (relative to cwd)
-     */
-    undoFiles(files: string[]): Promise<UndoResult>;
-    /**
-     * Check if currently tracking a turn.
-     */
-    isTrackingTurn(): boolean;
-    /**
-     * Get access to the raw turn tracker for advanced use cases.
-     *
-     * @internal
-     */
-    getTurnTracker(): TurnChangeTracker;
-    /**
-     * Update system prompt.
-     *
-     * If the agent is using the prompt pipeline, calling this switches
-     * to flat string mode (disabling the pipeline). To modify the pipeline
-     * instead, use `getPromptBuilder()`.
-     */
-    setSystemPrompt(prompt: string): void;
-    /** Update working directory */
-    setCwd(cwd: string): void;
-    /** Update model */
-    setModel(model: LanguageModel): void;
-    /**
-     * Get the prompt builder (when using pipeline mode).
-     * Returns undefined if using flat string mode.
-     *
-     * Use this to add/remove sections, clear caches, or inspect
-     * the prompt composition without switching to flat mode.
-     *
-     * @example
-     * ```typescript
-     * const builder = agent.getPromptBuilder();
-     * if (builder) {
-     *   builder.addSection({
-     *     id: "task-context",
-     *     label: "Task Context",
-     *     content: "Focus on fixing authentication bugs.",
-     *     priority: 60,
-     *   });
-     * }
-     * ```
-     */
-    getPromptBuilder(): PromptBuilder | undefined;
-    /**
-     * Check if the agent is using the prompt pipeline.
-     */
-    isUsingPromptPipeline(): boolean;
-    /**
-     * Build the effective system prompts for a turn.
-     *
-     * This mirrors the prompt resolution path used by `chat()` so external host
-     * runtimes can start durable turns without duplicating prompt assembly.
-     */
-    buildSystemPrompts(sessionId: string, override?: string): Promise<string[]>;
-    /**
-     * Return the runtime configuration required by the extracted turn-step
-     * helpers.
-     */
-    getTurnRuntimeConfig(): AgentTurnStepRuntimeConfig;
-    /**
-     * Get the configured tool host.
-     */
-    getHost(): ToolHost;
-    /**
-     * Get the configured middleware runner.
-     *
-     * The runner is immutable after construction, so it is safe to reuse in
-     * durable activity helpers that need the same middleware stack.
-     */
-    getMiddlewareRunner(): MiddlewareRunner;
-    /**
-     * Fork this agent to create a sub-agent with modified configuration.
-     *
-     * Sub-agents share the same session manager but can have different:
-     * - System prompts (specialized for tasks)
-     * - Tools (restricted subset)
-     * - Models (cheaper/faster for simple tasks)
-     * - Reasoning levels
-     *
-     * @example
-     * ```typescript
-     * // Create an exploration sub-agent with read-only tools
-     * const explorer = agent.fork({
-     *   name: "explore",
-     *   systemPrompt: "You explore codebases. Only use read and search tools.",
-     *   tools: [readTool, grepTool, globTool],
-     * });
-     *
-     * // Run the sub-agent
-     * const result = await explorer.run({
-     *   parentSessionId: "main-session",
-     *   message: "Find all API endpoints",
-     * });
-     * ```
-     */
-    fork(options?: AgentForkOptions): Agent;
-    /**
-     * Create a sub-agent with a preset configuration.
-     *
-     * Convenience method that applies a preset and returns a forked agent.
-     *
-     * @example
-     * ```typescript
-     * import { Presets } from "@cuylabs/agent-core";
-     *
-     * // Create an exploration sub-agent
-     * const explorer = agent.withPreset(Presets.explore);
-     * const result = await explorer.run({
-     *   message: "Find all API routes in this project",
-     * });
-     *
-     * // Create a careful review sub-agent
-     * const reviewer = agent.withPreset(Presets.review);
-     * const review = await reviewer.run({
-     *   message: "Review src/auth.ts for security issues",
-     * });
-     * ```
-     */
-    withPreset(preset: Preset): Agent;
-    /**
-     * Run a task in an isolated sub-agent session.
-     *
-     * Creates a new session linked to the parent, runs the task to completion,
-     * and returns the result. The sub-agent session is preserved for inspection.
-     *
-     * @example
-     * ```typescript
-     * const result = await agent.run({
-     *   parentSessionId: "main-session",
-     *   message: "Review this code for security issues",
-     *   title: "Security Review",
-     * });
-     *
-     * console.log(result.response);
-     * console.log(`Sub-agent session: ${result.sessionId}`);
-     * ```
-     */
-    run(options: {
-        /** Parent session ID (for linking) */
-        parentSessionId?: string;
-        /** The task/message to execute */
-        message: string;
-        /** Title for the sub-agent session */
-        title?: string;
-        /** Abort signal */
-        abort?: AbortSignal;
-    }): Promise<{
-        /** Final response text */
-        response: string;
-        /** Sub-agent session ID */
-        sessionId: string;
-        /** Token usage */
-        usage: TokenUsage;
-        /** Tool calls made */
-        toolCalls: Array<{
-            name: string;
-            result: unknown;
-        }>;
-    }>;
-    /**
-     * Get the MCP manager (if configured)
-     */
-    getMCP(): MCPManager | undefined;
-    /**
-     * Check if MCP is configured
-     */
-    hasMCP(): boolean;
-    /**
-     * Reconnect to MCP servers
-     *
-     * Use this after network issues or when server availability changes.
-     * Clears tool cache and reconnects all servers.
-     */
-    reconnectMCP(): Promise<void>;
-    /**
-     * Close the agent and clean up resources
-     *
-     * Flushes and shuts down the tracing provider (when `tracing` was configured),
-     * closes MCP connections if configured.
-     * After calling close(), the agent should not be used.
-     */
-    close(): Promise<void>;
-}
-
-/**
- * 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.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:
- * - `invoke_agent` — spawn a sub-agent for a focused task
- * - `wait_agent` — collect async sub-agent results
- * - `close_agent` — cancel a running async sub-agent
- *
- * @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
- */
-declare function createSubAgentTools(parent: Agent, config: SubAgentToolConfig): Tool.AnyInfo[];
-
-/**
- * Markdown Agent Profile Parser
- *
- * Parses `.md` files into `AgentProfile` objects using a hybrid approach:
- *
- * - **Frontmatter** (YAML between `---` fences) maps to profile config
- * - **Body** (everything after frontmatter) becomes the system prompt
- * - **Preset references** compose with the existing TypeScript preset system
- * - **Tool modifiers** (`+tool`, `-tool*`) extend or restrict preset tool lists
- * - **Inheritance** (`extends: parent-name`) layers on top of another profile
- *
- * No external YAML library required — the frontmatter grammar is deliberately
- * restricted to flat key-value pairs and comma-separated lists.
- *
- * @packageDocumentation
- */
-
-/**
- * Raw frontmatter fields extracted from a markdown agent file.
- *
- * All values are strings at this stage — conversion to typed config
- * happens in {@link toAgentProfile}.
- */
-interface MarkdownAgentFrontmatter {
-    /** Agent name (required). Lowercase, no spaces. */
-    name: string;
-    /** LLM-facing description of when to use this agent (required). */
-    description: string;
-    /** Built-in preset to inherit from (e.g. "explore", "code", "plan"). */
-    preset?: string;
-    /** Parent agent name to extend. */
-    extends?: string;
-    /** Model identifier (e.g. "anthropic/claude-sonnet-4-6"). */
-    model?: string;
-    /** Maximum agentic loop steps. */
-    maxSteps?: string;
-    /** LLM temperature (0–1). */
-    temperature?: string;
-    /** Reasoning level: off, minimal, low, medium, high, xhigh. */
-    reasoning?: string;
-    /**
-     * Tool modifiers or explicit tool list.
-     *
-     * Three modes:
-     * - **Additive/subtractive**: `"+bash, -delete*, +fetch"` — patch the preset
-     * - **Explicit list**: `"read, grep, bash"` — ONLY these tools
-     * - **Absent**: inherit preset filtering unchanged
-     */
-    tools?: string;
-    /** Comma-separated skill names to activate for this agent. */
-    skills?: string;
-    /** Whether this agent can spawn further sub-agents. */
-    canSpawn?: string;
-}
-/**
- * Result of parsing a markdown agent file.
- */
-interface ParsedMarkdownAgent {
-    /** Parsed frontmatter fields. */
-    frontmatter: MarkdownAgentFrontmatter;
-    /** Markdown body — becomes the system prompt. */
-    body: string;
-    /** Original file path (for error messages). */
-    filePath: string;
-}
-/**
- * Parsed tool modifier from frontmatter `tools` field.
- */
-type ToolModifier = {
-    kind: "add";
-    pattern: string;
-} | {
-    kind: "remove";
-    pattern: string;
-};
-/**
- * Parsed tool specification from frontmatter.
- */
-type ParsedToolSpec = {
-    mode: "explicit";
-    patterns: string[];
-} | {
-    mode: "modifiers";
-    modifiers: ToolModifier[];
-} | {
-    mode: "inherit";
-};
-/**
- * Resolvers needed to convert parsed frontmatter into a full `AgentProfile`.
- *
- * These are injected by the caller so the parser stays pure (no I/O, no
- * global lookups).
- */
-interface ProfileResolvers {
-    /** Look up a built-in preset by name. Returns undefined if not found. */
-    resolvePreset?: (name: string) => Preset | undefined;
-    /** Look up a parent profile by name (for `extends`). */
-    resolveParent?: (name: string) => AgentProfile | undefined;
-}
-/**
- * Parse a YAML-like frontmatter block.
- *
- * Supports:
- * - `key: value` (string values, trimmed)
- * - `key: "quoted value"` (double-quoted, quotes stripped)
- * - `key: 'quoted value'` (single-quoted, quotes stripped)
- * - Multi-line values via `key: |` (indented block)
- * - Comments (`# ...`)
- * - Empty lines (skipped)
- *
- * Does NOT support nested objects, arrays, or advanced YAML features.
- * This is intentional — agent definitions should stay flat and readable.
- */
-declare function parseAgentFrontmatter(raw: string): Record<string, string>;
-/**
- * Parse a markdown agent file into structured frontmatter + body.
- *
- * @param content   File content (UTF-8 string)
- * @param filePath  Source file path (for error context)
- * @returns Parsed result, or null if the file lacks valid frontmatter
- */
-declare function parseMarkdownAgent(content: string, filePath: string): ParsedMarkdownAgent | null;
-/**
- * Parse the `tools` frontmatter field into a structured spec.
- *
- * - `"+bash, -delete*, +fetch"` → `{ mode: "modifiers", modifiers: [...] }`
- * - `"read, grep, bash"` → `{ mode: "explicit", patterns: ["read", "grep", "bash"] }`
- * - `undefined` → `{ mode: "inherit" }`
- */
-declare function parseToolSpec(raw: string | undefined): ParsedToolSpec;
-/**
- * Convert a parsed markdown agent into an `AgentProfile`.
- *
- * Resolution order for each field:
- * 1. Explicit frontmatter value (highest priority)
- * 2. Parent profile (via `extends`)
- * 3. Preset defaults
- * 4. Built-in defaults
- *
- * @param parsed    Parsed markdown agent
- * @param resolvers Injected lookup functions
- * @returns A fully-resolved `AgentProfile`
- */
-declare function toAgentProfile(parsed: ParsedMarkdownAgent, resolvers?: ProfileResolvers): AgentProfile;
-/**
- * An `AgentProfile` that originated from a markdown file.
- *
- * Carries extra metadata that the discovery/wiring layer can use
- * to resolve model strings and activate skills.
- */
-interface MarkdownAgentProfile extends AgentProfile {
-    /** Model identifier string (e.g. "anthropic/claude-sonnet-4-6"). */
-    _modelId?: string;
-    /** Skill names to activate for this agent. */
-    _skillNames?: string[];
-    /** Source file path. */
-    _source?: string;
-}
-/**
- * Type guard for markdown-sourced profiles.
- */
-declare function isMarkdownProfile(profile: AgentProfile): profile is MarkdownAgentProfile;
-
-/**
- * Agent Profile Discovery
- *
- * Discovers agent profiles from markdown files across multiple locations
- * and merges them with built-in TypeScript profiles.
- *
- * Discovery order (later wins by name):
- * 1. Built-in TypeScript profiles (e.g. explorer, coder, planner, runner)
- * 2. User global agents: `~/.cuylabs/agents/*.md`
- * 3. Project local agents: `.cuylabs/agents/*.md`
- * 4. Config-specified paths: `config.agents` array
- *
- * @packageDocumentation
- */
-
-/** Source tier for an agent profile. */
-type AgentSource = "builtin" | "user" | "project" | "config";
-/** Metadata attached to discovered profiles for debugging/logging. */
-interface DiscoveredProfile {
-    profile: AgentProfile;
-    source: AgentSource;
-    filePath?: string;
-}
-/**
- * Options for agent profile discovery.
- */
-interface AgentDiscoveryOptions {
-    /** Project working directory. Used to find `.cuylabs/agents/`. */
-    cwd: string;
-    /**
-     * User-global agents directory.
-     * @default `~/.cuylabs/agents`
-     */
-    userDir?: string;
-    /**
-     * Project-local agents directory name (relative to cwd).
-     * @default `.cuylabs/agents`
-     */
-    projectDir?: string;
-    /**
-     * Additional file paths from config.json `agents` array.
-     * Resolved relative to cwd.
-     */
-    configPaths?: string[];
-    /** Built-in TypeScript profiles to merge with. */
-    builtInProfiles?: AgentProfile[];
-    /**
-     * Custom preset resolver. Defaults to the built-in `Presets` map.
-     */
-    resolvePreset?: (name: string) => Preset | undefined;
-}
-/**
- * Result of agent profile discovery.
- */
-interface AgentDiscoveryResult {
-    /** Merged profiles (ready for `SubAgentToolConfig.profiles`). */
-    profiles: AgentProfile[];
-    /** All discovered entries with source metadata (for logging). */
-    discovered: DiscoveredProfile[];
-    /** Errors encountered during loading (non-fatal). */
-    errors: Array<{
-        path: string;
-        error: string;
-    }>;
-}
-/**
- * Discover agent profiles from markdown files and merge with built-in profiles.
- *
- * Merge strategy: later sources override earlier ones by profile name.
- * Within the same source tier, later files (alphabetical) override earlier ones.
- *
- * This means a project `.cuylabs/agents/explorer.md` overrides the built-in
- * `explorer` profile, and a user `~/.cuylabs/agents/explorer.md` overrides it
- * for all projects.
- *
- * @example
- * ```typescript
- * const { profiles } = discoverAgentProfiles({
- *   cwd: "/path/to/project",
- *   builtInProfiles: defaultCodingProfiles,
- * });
- *
- * // profiles now includes built-ins + user + project markdown agents
- * const config: SubAgentToolConfig = { profiles };
- * ```
- */
-declare function discoverAgentProfiles(options: AgentDiscoveryOptions): AgentDiscoveryResult;
-/**
- * Get the default user agents directory path.
- */
-declare function getUserAgentsDir(): string;
-/**
- * Get the project agents directory path for a given cwd.
- */
-declare function getProjectAgentsDir(cwd: string): string;
-
-export { type AgentConfig as A, parseToolSpec as B, type CompactionConfig as C, DEFAULT_MAX_CONCURRENT as D, toAgentProfile as E, type MarkdownAgentFrontmatter as M, PRUNE_PROTECTED_TOOLS as P, type SubAgentCompletedResult as S, type ToolModifier as T, Agent as a, type AgentDiscoveryOptions as b, type AgentDiscoveryResult as c, type AgentProfile as d, type AgentSource as e, DEFAULT_MAX_SPAWN_DEPTH as f, DEFAULT_SESSION_TITLE_PREFIX as g, type DiscoveredProfile as h, type MarkdownAgentProfile as i, type ParsedMarkdownAgent as j, type ParsedToolSpec as k, type ProfileResolvers as l, type SubAgentHandle as m, type SubAgentStatus as n, type SubAgentToolConfig as o, SubAgentTracker as p, type SubAgentUsage as q, type TracingConfig as r, createAgent as s, createSubAgentTools as t, discoverAgentProfiles as u, getProjectAgentsDir as v, getUserAgentsDir as w, isMarkdownProfile as x, parseAgentFrontmatter as y, parseMarkdownAgent as z };