@cuylabs/agent-core 0.4.0 → 0.5.0

package/dist/index-p0kOsVsE.d.ts

@@ -0,0 +1,1067 @@
+import { LanguageModel } from 'ai';
+import { R as ReasoningLevel } from './types-CQaXbRsS.js';
+import { T as Tool } from './tool-pFAnJc5Y.js';
+import { f as AgentMiddleware, P as PromptConfig, A as AgentEvent, M as MiddlewareRunner } from './runner-C7aMP_x3.js';
+import { g as SessionManager, c as SessionContext, f as SessionInfo } from './session-manager-Uawm2Le7.js';
+import { d as ToolHost } from './tool-DYp6-cC3.js';
+import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
+import { a as MCPManager } from './types-VQgymC1N.js';
+import { U as UndoResult, T as TurnChangeTracker } from './tracker-DClqYqTj.js';
+import { P as PromptBuilder } from './builder-RcTZuYnO.js';
+import { x as DoomLoopHandler, Z as StreamProvider, J as PendingIntervention, I as InterventionController, q as AgentTurnStepRuntimeConfig } from './types-MM1JoX5T.js';
+
+/**
+ * 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;
+}
+
+/**
+ * Agent preset - a reusable configuration profile.
+ */
+interface Preset {
+    /** Unique identifier for this preset */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /**
+     * Tool allow patterns (glob-like).
+     * If provided, only tools matching these patterns are candidates.
+     */
+    allowTools?: string[];
+    /**
+     * Tool deny patterns (glob-like).
+     * Deny patterns apply only after allow matching, so explicit allows win.
+     */
+    denyTools?: string[];
+    /**
+     * Override system prompt.
+     * Use `{basePrompt}` to include the parent's system prompt.
+     */
+    systemPrompt?: string;
+    /** Override temperature (0-1). */
+    temperature?: number;
+    /** Override max steps. */
+    maxSteps?: number;
+    /** Override reasoning level. */
+    reasoningLevel?: ReasoningLevel;
+    /** Override model. */
+    model?: LanguageModel;
+}
+/**
+ * Result of applying a preset - ready for `fork()`.
+ */
+interface AppliedPreset {
+    name: string;
+    systemPrompt?: string;
+    tools?: Tool.AnyInfo[];
+    temperature?: number;
+    maxSteps?: number;
+    reasoningLevel?: ReasoningLevel;
+    model?: LanguageModel;
+}
+
+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;
+    /** 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?;
+    constructor(config: AgentConstructionOptions);
+    /** 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 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 AppliedPreset as A, type CompactionConfig as C, DEFAULT_MAX_CONCURRENT as D, type Preset as P, type SubAgentCompletedResult as S, type TracingConfig as T, Agent as a, type AgentConfig as b, type AgentProfile as c, DEFAULT_MAX_SPAWN_DEPTH as d, DEFAULT_SESSION_TITLE_PREFIX as e, type SubAgentHandle as f, type SubAgentStatus as g, type SubAgentToolConfig as h, SubAgentTracker as i, type SubAgentUsage as j, createAgent as k, createSubAgentTools as l };