@cuylabs/agent-core 0.8.0 → 0.10.0

package/dist/index-CWSchSql.d.ts

@@ -1,1058 +0,0 @@
-import { LanguageModel } from 'ai';
-import { P as Preset } from './types-BnpEOYV-.js';
-import { T as Tool } from './tool-BHbyUAy3.js';
-import { A as AgentMiddleware, d as StreamProvider, P as PromptConfig, M as MiddlewareRunner } from './runner-e2YRcUoX.js';
-import { S as SessionManager, f as SessionContext, i as SessionInfo } from './session-manager-B_CWGTsl.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-UpOWQMW3.js';
-import { P as PendingIntervention, g as InterventionController } from './types-KKDrdU9Y.js';
-import { s as DoomLoopHandler, o as AgentTurnStepRuntimeConfig } from './types-QKHHQLLq.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 loadedSessions;
-    private state;
-    /** Context manager for overflow detection and compaction */
-    private contextManager;
-    /** Tools that user said "remember" for doom loop (don't ask again) */
-    private rememberedDoomLoopTools;
-    /** Turn change tracker for file modification tracking */
-    private turnTracker;
-    /** Counter for turn IDs */
-    private turnCounter;
-    /** MCP manager for external tool servers */
-    private mcpManager?;
-    /** Whether MCP has been connected (lazy init) */
-    private mcpConnected;
-    /** 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;
-    /** 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;
-    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;
-    /**
-     * 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>;
-    /**
-     * Ensure a session is loaded or created
-     */
-    private ensureSession;
-    /**
-     * Send a message and wait for the complete response (non-streaming).
-     *
-     * This is a convenience wrapper around {@link chat} that buffers all
-     * events internally and returns the final response, usage, and tool
-     * call results. Prefer `chat()` when you need real-time streaming.
-     *
-     * @param sessionId - Session identifier
-     * @param message   - User message
-     * @param options   - Abort signal and optional system prompt override
-     */
-    send(sessionId: string, message: string, options?: {
-        abort?: AbortSignal;
-        system?: string;
-    }): Promise<{
-        response: string;
-        usage: TokenUsage;
-        toolCalls: Array<{
-            name: string;
-            result: unknown;
-        }>;
-    }>;
-    /** Add a tool at runtime */
-    addTool(tool: Tool.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.
-     *
-     * @param message - The user message to inject mid-turn
-     * @returns Intervention ID for tracking
-     *
-     * @example
-     * ```typescript
-     * // Start a streaming turn
-     * const stream = agent.chat("session-1", "refactor the auth module");
-     *
-     * // From a UI handler (another async context):
-     * agent.intervene("stop, focus only on JWT validation in auth.ts");
-     *
-     * // The stream will yield an intervention-applied event
-     * for await (const event of stream) {
-     *   if (event.type === "intervention-applied") {
-     *     console.log(`Redirected: ${event.message}`);
-     *   }
-     * }
-     * ```
-     */
-    intervene(message: string): string;
-    /**
-     * Queue a message for after the current turn completes.
-     *
-     * Unlike `intervene()`, this does **not** interrupt the current turn.
-     * The message is held and available via `drainQueuedNext()` after
-     * `chat()` finishes. The consumer decides whether to send it as a
-     * new turn.
-     *
-     * @param message - The message to queue
-     * @returns Intervention ID for tracking
-     *
-     * @example
-     * ```typescript
-     * agent.queueNext("now run the test suite");
-     *
-     * for await (const event of agent.chat("s1", "fix the bug")) {
-     *   // ... handle events
-     * }
-     *
-     * // After turn completes, check for queued messages
-     * if (agent.hasQueuedNext()) {
-     *   const next = agent.drainQueuedNext();
-     *   for (const item of next) {
-     *     // Send as a new turn
-     *     for await (const ev of agent.chat("s1", item.message)) { ... }
-     *   }
-     * }
-     * ```
-     */
-    queueNext(message: string): string;
-    /** Whether there are deferred messages queued for after the turn */
-    hasQueuedNext(): boolean;
-    /** Drain and return all deferred messages (clears the queue) */
-    drainQueuedNext(): PendingIntervention[];
-    /**
-     * Get the raw intervention controller for advanced use cases.
-     *
-     * Use this when you need fine-grained control over the intervention
-     * lifecycle (e.g., checking pending count, clearing queues, setting
-     * custom `onApplied` callbacks).
-     *
-     * @internal
-     */
-    getInterventionController(): InterventionController;
-    /**
-     * Get the unified diff for all file changes in the current/last turn.
-     *
-     * @example
-     * ```typescript
-     * const diff = await agent.getTurnDiff();
-     * if (diff) {
-     *   console.log('Changes this turn:\n', diff);
-     * }
-     * ```
-     */
-    getTurnDiff(): Promise<string | null>;
-    /**
-     * Get list of files being tracked in the current turn.
-     */
-    getTrackedFiles(): string[];
-    /**
-     * Undo all file changes from the current turn.
-     * Restores files to their state before the turn started.
-     *
-     * @example
-     * ```typescript
-     * const result = await agent.undoTurn();
-     * console.log(`Restored ${result.restored.length} files`);
-     * if (result.failed.length > 0) {
-     *   console.log('Failed to restore:', result.failed);
-     * }
-     * ```
-     */
-    undoTurn(): Promise<UndoResult>;
-    /**
-     * Undo changes to specific files only.
-     *
-     * @param files - Array of file paths to restore (relative to cwd)
-     */
-    undoFiles(files: string[]): Promise<UndoResult>;
-    /**
-     * Check if currently tracking a turn.
-     */
-    isTrackingTurn(): boolean;
-    /**
-     * Get access to the raw turn tracker for advanced use cases.
-     *
-     * @internal
-     */
-    getTurnTracker(): TurnChangeTracker;
-    /**
-     * Update system prompt.
-     *
-     * If the agent is using the prompt pipeline, calling this switches
-     * to flat string mode (disabling the pipeline). To modify the pipeline
-     * instead, use `getPromptBuilder()`.
-     */
-    setSystemPrompt(prompt: string): void;
-    /** Update working directory */
-    setCwd(cwd: string): void;
-    /** Update model */
-    setModel(model: LanguageModel): void;
-    /**
-     * Get the prompt builder (when using pipeline mode).
-     * Returns undefined if using flat string mode.
-     *
-     * Use this to add/remove sections, clear caches, or inspect
-     * the prompt composition without switching to flat mode.
-     *
-     * @example
-     * ```typescript
-     * const builder = agent.getPromptBuilder();
-     * if (builder) {
-     *   builder.addSection({
-     *     id: "task-context",
-     *     label: "Task Context",
-     *     content: "Focus on fixing authentication bugs.",
-     *     priority: 60,
-     *   });
-     * }
-     * ```
-     */
-    getPromptBuilder(): PromptBuilder | undefined;
-    /**
-     * Check if the agent is using the prompt pipeline.
-     */
-    isUsingPromptPipeline(): boolean;
-    /**
-     * 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[];
-
-export { type AgentConfig as A, type CompactionConfig as C, DEFAULT_MAX_CONCURRENT as D, PRUNE_PROTECTED_TOOLS as P, type SubAgentCompletedResult as S, type TracingConfig as T, Agent as a, type AgentProfile as b, DEFAULT_MAX_SPAWN_DEPTH as c, DEFAULT_SESSION_TITLE_PREFIX as d, type SubAgentHandle as e, type SubAgentStatus as f, type SubAgentToolConfig as g, SubAgentTracker as h, type SubAgentUsage as i, createAgent as j, createSubAgentTools as k };