@24klynx/agent 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1316 @@
+import { ContentBlock, Message, Session, SessionId } from "@lynx/core";
+import { ToolDescriptor, ToolHandler } from "@lynx/tools";
+import { ChildProcess } from "node:child_process";
+import { ChatMessage, LlmProvider, StreamEvent } from "@lynx/llm";
+
+//#region src/types.d.ts
+/** Configuration passed to createQueryEngine at bootstrap time. */
+interface AgentConfig {
+  /** LLM provider the engine should use for every turn. */
+  provider: LlmProvider;
+  /** Default model id (can be overridden per‑session). */
+  model: string;
+  /** System prompt template (assembled with project context + skills). */
+  systemPrompt: string;
+  /** Maximum tokens per request (input + output). */
+  maxTokens: number;
+  /** Maximum consecutive auto‑compaction failures before giving up. */
+  maxCompactionFailures: number;
+  /** Hard budget caps (set to Infinity to disable). */
+  budget: {
+    /** Maximum total input + output tokens across all turns. */maxTokens: number; /** Maximum USD spend (approximate, based on provider pricing). */
+    maxUsd: number; /** Maximum number of LLM turns before auto‑terminating. */
+    maxTurns: number;
+  };
+}
+type AgentStatus = "idle" | "running" | "aborting" | "compacting";
+interface AgentState {
+  status: AgentStatus;
+  /** How many turns have been executed in the current run. */
+  turnIndex: number;
+  /** Total error count since the session started. */
+  errorCount: number;
+  /** Number of consecutive auto‑compaction failures. */
+  consecutiveCompactionFailures: number;
+}
+/**
+ * Immutable snapshot of everything the query loop needs
+ * for a single invocation of the LLM.
+ */
+interface TurnContext {
+  session: Session;
+  /** Visible tools for this turn (after availability evaluation). */
+  visibleTools: ToolDescriptor[];
+  /** Agent lifecycle state at turn start. */
+  state: Readonly<AgentState>;
+  /** Abort signal for this turn. */
+  signal: AbortSignal;
+}
+/**
+ * The public API of the agent engine.
+ *
+ * Every method returns plain values — no internal mutable state leaks.
+ */
+interface QueryEngine {
+  /** Submit user input and begin streaming agent responses. */
+  submit(session: Session, userMessage: Message, signal: AbortSignal): AsyncGenerator<StreamEvent, void, void>;
+  /** Abort the currently running turn (first Ctrl+C). */
+  abort(): void;
+  /** Force immediate compaction of the session messages. */
+  compact(session: Session): Promise<Session>;
+  /** Take a snapshot of the current state for crash recovery. */
+  snapshot(session: Session): AgentSnapshot;
+  /** Restore agent state from a previous snapshot. */
+  restore(snapshot: AgentSnapshot): Promise<Session>;
+  /** Clean up resources (timers, MCP connections, sub‑agent pools). */
+  destroy(): void;
+}
+interface AgentSnapshot {
+  sessionId: SessionId;
+  turnIndex: number;
+  /** Serialised messages at the time of the snapshot. */
+  messages: ContentBlock[];
+  createdAt: number;
+}
+type CompactionStrategy = "auto" | "reactive" | "snip" | "seam";
+interface CompactionResult {
+  /** Compressed messages that replace the original session content. */
+  compacted: ContentBlock[];
+  /** How many tokens were saved. */
+  tokensSaved: number;
+  /** Strategy that was applied. */
+  strategy: CompactionStrategy;
+}
+interface SubAgentResult {
+  agentId: string;
+  output: string;
+  tokensUsed: number;
+}
+interface SkillDefinition {
+  name: string;
+  description: string;
+  /** Relative path to the SKILL.md file. */
+  path: string;
+  /** The skill body (loaded on demand). */
+  body?: string;
+}
+type McpTransportKind = "stdio" | "sse" | "ws" | "inproc";
+/** OAuth 2.0 PKCE 认证配置。 */
+interface McpOAuthConfig {
+  /** 授权端点 URL。 */
+  authorizationEndpoint: string;
+  /** Token 端点 URL。 */
+  tokenEndpoint: string;
+  /** OAuth 客户端 ID。 */
+  clientId: string;
+  /** 回调 URL（默认 http://localhost:<随机端口>/callback）。 */
+  redirectUri?: string;
+  /** 请求的权限范围。 */
+  scopes?: string[];
+}
+/** XAA (Cross-Agent Authentication) 企业身份认证配置。 */
+interface McpXaaConfig {
+  /** IdP 提供商 URL。 */
+  idpUrl: string;
+  /** 客户端 ID。 */
+  clientId: string;
+  /** 回调 URL。 */
+  redirectUri?: string;
+}
+interface McpServerConfig {
+  name: string;
+  /** Transport type — "stdio" spawns a process, "sse" connects to an HTTP endpoint, "ws" uses WebSocket, "inproc" uses an in-process linked pair. */
+  transport?: McpTransportKind;
+  /** Command to spawn (stdio transport). */
+  command?: string;
+  /** Arguments for the command (stdio transport). */
+  args?: string[];
+  /** Extra env vars (stdio transport). */
+  env?: Record<string, string>;
+  /** URL to connect to (sse transport, e.g. "http://localhost:8080/mcp"). */
+  url?: string;
+  /** WebSocket URL (ws transport). */
+  wsUrl?: string;
+  /** Custom headers for SSE/HTTP requests. */
+  headers?: Record<string, string>;
+  /** Static tool list for test/fallback (when no command is configured). */
+  tools?: ToolDescriptor[];
+  /** OAuth 2.0 PKCE 认证配置（可选）。 */
+  oauth?: McpOAuthConfig;
+  /** XAA 企业身份认证配置（可选）。 */
+  xaa?: McpXaaConfig;
+  /** 是否支持 MCP resources 协议。 */
+  resourcesCapable?: boolean;
+  /** In-process transport peer handle (inproc transport). */
+  inProcPeer?: {
+    send(message: string): void;
+    onMessage: ((data: string) => void) | null;
+    close(): void;
+  };
+}
+/** Reason a connection status changed. */
+type McpStatusEvent = {
+  type: "connecting";
+  serverName: string;
+} | {
+  type: "connected";
+  serverName: string;
+  toolCount: number;
+} | {
+  type: "disconnected";
+  serverName: string;
+} | {
+  type: "error";
+  serverName: string;
+  message: string;
+} | {
+  type: "reconnecting";
+  serverName: string;
+  attempt: number;
+  delayMs: number;
+};
+type McpStatusListener = (event: McpStatusEvent) => void;
+/** Tool metadata for display in the MCP detail panel. */
+interface McpToolMeta {
+  name: string;
+  description: string;
+}
+/** Resource metadata for display in the MCP detail panel. */
+interface McpResourceMeta {
+  name: string;
+  uri: string;
+}
+interface McpConnection {
+  serverName: string;
+  status: "disconnected" | "connecting" | "connected" | "error";
+  /** Available tools exposed by this MCP server. */
+  tools: ToolDescriptor[];
+  /** Error message if status === "error". */
+  errorMessage?: string;
+  /** Transport type. */
+  transport?: "stdio" | "sse" | "ws" | "inproc";
+  /** Authentication status for OAuth/XAA-enabled servers. */
+  authStatus?: "none" | "authenticated" | "expired";
+  /** Number of resources exposed by this server. */
+  resourceCount?: number;
+  /** Resources exposed by this server (for detail display). */
+  resources?: McpResourceMeta[];
+  /** Tool metadata for detail display (name + description). */
+  toolsMeta?: McpToolMeta[];
+}
+//#endregion
+//#region src/engine.d.ts
+interface EngineDeps {
+  config: AgentConfig;
+  provider: LlmProvider;
+  /** Map from executor ref → tool handler. */
+  toolHandlers: Map<string, ToolHandler>;
+  /** All registered tool descriptors. */
+  allTools: ToolDescriptor[];
+  /**
+   * Called before executing each tool. Returns true if execution is allowed.
+   * The callback may be async (e.g. to show a permission dialog).
+   * If omitted, all tools execute without permission checks.
+   */
+  checkPermission?: (toolName: string, safety: string, description: string) => Promise<boolean>;
+  /** Discovered skills for progressive disclosure in the system prompt. */
+  skills?: SkillDefinition[];
+  /** Persistent memory facts to inject into the system prompt each turn. */
+  memoryFacts?: string[];
+  /** Textual rules/instructions to inject into the system prompt each turn. */
+  rules?: string[];
+}
+/**
+ * Create a QueryEngine instance.
+ *
+ * One engine per application — it manages the lifecycle
+ * of all active sessions, sub‑agents, and MCP connections.
+ */
+declare function createQueryEngine(deps: EngineDeps): QueryEngine;
+//#endregion
+//#region src/loop.d.ts
+interface LoopDeps {
+  config: AgentConfig;
+  provider: LlmProvider;
+  /** Map from executor ref → handler. */
+  toolHandlers: Map<string, ToolHandler>;
+  /** All registered tool descriptors (for planning). */
+  allTools: ToolDescriptor[];
+  /**
+   * Called before executing each tool. Returns true if execution is allowed.
+   * The callback may be async (e.g. to show a permission dialog).
+   * If omitted, all tools execute without permission checks.
+   */
+  checkPermission?: (toolName: string, safety: string, description: string) => Promise<boolean>;
+  /** Discovered skills (name + description only) for progressive disclosure. */
+  skills?: SkillDefinition[];
+  /** Persistent memory facts to inject into the system prompt each turn. */
+  memoryFacts?: string[];
+  /** Textual rules/instructions to inject into the system prompt each turn. */
+  rules?: string[];
+}
+declare function queryLoop(deps: LoopDeps, sessionMessages: Message[], workspace: string, signal: AbortSignal): AsyncGenerator<StreamEvent, void, void>;
+//#endregion
+//#region src/budget.d.ts
+interface BudgetTracker {
+  /** Record token consumption after a turn completes. */
+  spend(inputTokens: number, outputTokens: number): void;
+  /** Record another turn has elapsed. */
+  incrementTurn(): void;
+  /** Whether at least one budget cap has been reached. */
+  isExhausted(): boolean;
+  /** Human‑readable summary of remaining budget. */
+  summary(): string;
+  readonly tokensUsed: number;
+  readonly turnsUsed: number;
+  readonly usdUsed: number;
+  readonly maxTokens: number;
+  readonly maxTurns: number;
+  readonly maxUsd: number;
+}
+/**
+ * Create a BudgetTracker from the agent configuration.
+ *
+ * Token counting is approximate (3.5 chars ≈ 1 token for English,
+ * ~1 char ≈ 1 token for CJK). For precise tracking, use the
+ * provider‑returned `totalTokens` in the `done` event.
+ */
+declare function createBudgetTracker(config: AgentConfig): BudgetTracker;
+//#endregion
+//#region src/state.d.ts
+/** Create a fresh idle agent state. */
+declare function createAgentState(): AgentState;
+/**
+ * Transition the agent to a new status.
+ *
+ * Throws if the transition is not valid (e.g. idle → aborting,
+ * running → running, aborting → compacting).
+ */
+declare function transition(state: AgentState, status: AgentStatus): AgentState;
+/** Advance the turn counter after a successful LLM round‑trip. */
+declare function advanceTurn(state: AgentState): AgentState;
+/** Record a non‑fatal error (bumps the counter). */
+declare function recordError(state: AgentState): AgentState;
+/** Record a successful compaction (resets the failure tally). */
+declare function recordCompactionSuccess(state: AgentState): AgentState;
+/** Record a failed compaction attempt. */
+declare function recordCompactionFailure(state: AgentState): AgentState;
+/**
+ * Check whether the compaction circuit breaker has tripped.
+ *
+ * After MAX failures, auto‑compaction is disabled for the
+ * remainder of the session to prevent infinite loops.
+ */
+declare function isCompactionCircuitOpen(state: AgentState, maxFailures: number): boolean;
+//#endregion
+//#region src/compaction/manager.d.ts
+interface CompactionManager {
+  /** Check whether compaction is needed and return the recommended strategy. */
+  evaluate(messages: Message[]): CompactionStrategy | undefined;
+  /** Execute compaction using the given strategy. */
+  compact(messages: Message[], strategy: CompactionStrategy): CompactionResult;
+  /** Estimate total tokens across all messages. */
+  estimateTokens(messages: Message[]): number;
+}
+/**
+ * Create a compaction manager.
+ *
+ * Each strategy preserves the most recent messages while
+ * compressing or dropping older ones. The `seam` strategy
+ * additionally preserves the system prompt prefix so the
+ * LLM's prefix cache stays warm.
+ */
+declare function createCompactionManager(): CompactionManager;
+//#endregion
+//#region src/prompt/base.d.ts
+/**
+ * Lynx 基础系统提示词 — 对照 Claude Code prompts.ts 结构逐节适配。
+ *
+ * CC 结构: Intro → System → Doing Tasks → Actions → Using Your Tools → Tone → Output
+ * 静态节放这里，动态节（工具列表、环境、记忆等）仍由 assembler.ts 组装。
+ */
+/**
+ * Lynx 完整基础系统提示词。
+ *
+ * 动态部分（工具列表、环境信息、记忆、规则、MCP 工具等）
+ * 由 assembler.ts 在每回合动态组装。
+ */
+declare function getBaseSystemPrompt(): string;
+//#endregion
+//#region src/prompt/handoff.d.ts
+interface HandoffContext {
+  /** Concise summary of completed work. */
+  completed: string;
+  /** What is currently in progress. */
+  inProgress: string;
+  /** Any blockers the next session should know about. */
+  blockers: string[];
+  /** Important files or paths modified. */
+  touchedFiles: string[];
+}
+/**
+ * Generate a handoff message from the last N messages in the session.
+ *
+ * Extracts file paths from tool results and builds a structured
+ * summary that can be injected as a system message in the next turn.
+ */
+declare function generateHandoff(lastMessages: Message[]): HandoffContext;
+/**
+ * Render a HandoffContext as a system message content block.
+ */
+declare function renderHandoffBlock(ctx: HandoffContext): ContentBlock;
+/**
+ * Check whether a session needs a handoff (more than N messages).
+ */
+declare function needsHandoff(messages: Message[], threshold?: number): boolean;
+//#endregion
+//#region src/prompt/assembler.d.ts
+/** Options for controlling prompt assembly. */
+interface AssembleOptions {
+  /** Visible tools for this turn. */
+  visibleTools: ToolDescriptor[];
+  /** Discovered skills (may be empty). */
+  skills?: SkillDefinition[];
+  /** Optional handoff from a previous session. */
+  handoff?: HandoffContext;
+  /** Language direction override from config/CLAUDE.md. */
+  languageDirection?: string;
+  /** Workspace path for loading project context. */
+  workspace?: string;
+  /** MCP tools from connected servers. */
+  mcpTools?: ToolDescriptor[];
+  /** Persistent memory facts to inject. */
+  memoryFacts?: string[];
+  /** Permission rules to inject. */
+  rules?: string[];
+}
+/**
+ * Assemble the complete system prompt for a turn.
+ *
+ * Called at the start of every LLM invocation — the prompt may
+ * change between turns (tool visibility can shift due to permissions,
+ * new skills may be loaded, handoff may be injected).
+ */
+declare function assembleSystemPrompt(config: AgentConfig, opts: AssembleOptions | ToolDescriptor[]): string;
+//#endregion
+//#region src/prompt/context.d.ts
+/**
+ * Build the ChatMessage array for a single LLM invocation.
+ *
+ * Converts session Message[] history into ChatMessage[] (with roles preserved)
+ * and prepends project context as a system‑level message.
+ */
+declare function buildMessagesForTurn(messages: Message[], _visibleTools: ToolDescriptor[], workspace?: string): ChatMessage[];
+/**
+ * Walk up from `workspace` looking for instruction files.
+ *
+ * The first file found at each directory level is loaded;
+ * higher‑priority files (CLAUDE.md) shadow lower ones.
+ * We stop at the filesystem root or when we've collected
+ * all known file names.
+ */
+declare function loadProjectContext(workspace?: string): string | undefined;
+//#endregion
+//#region src/prompt/hash.d.ts
+/**
+ * Prompt hash computation — used to detect when the system prompt
+ * has changed enough to invalidate the prefix cache.
+ *
+ * The hash is computed only over the "frozen" zone (everything before
+ * the tool catalog). When tools change, the hash changes and the cache
+ * is invalidated — which is correct, since tool schemas are part of
+ * the prompt.
+ */
+/**
+ * Compute a SHA‑256 hash of the frozen prefix zone.
+ *
+ * This hash is used as a cache key — if the frozen zone hasn't
+ * changed between turns, the LLM can reuse cached KV pairs.
+ */
+declare function computeFrozenHash(prompt: string): string;
+/**
+ * Check if two prompts share the same frozen prefix.
+ */
+declare function sameFrozenPrefix(a: string, b: string): boolean;
+/**
+ * Extract the frozen zone from the full prompt.
+ * Everything before "## Available Tools" is considered frozen.
+ */
+declare function extractFrozenZone(prompt: string): string;
+/**
+ * Extract the warm zone (tool catalog) from the full prompt.
+ */
+declare function extractWarmZone(prompt: string): string;
+/**
+ * Extract the hot zone (session‑specific suffix) from the full prompt.
+ */
+declare function extractHotZone(prompt: string): string;
+//#endregion
+//#region src/cache/prefix.d.ts
+/**
+ * Prefix cache stability manager — three‑zone model.
+ *
+ * DeepSeek and Anthropic both implement automatic prefix caching:
+ * the first N tokens of the system prompt that don't change between
+ * requests are cached server‑side, reducing latency and cost.
+ *
+ * Zones:
+ *   1. Frozen prefix  — never changes (tool catalog header, core rules)
+ *   2. Warm prefix    — changes rarely (skill list, date)
+ *   3. Hot suffix     — changes every turn (tool schema, session state)
+ *
+ * The manager computes a hash of each zone and emits a "stability"
+ * score — higher scores mean more tokens benefit from the cache.
+ */
+interface PrefixCacheManager {
+  /** Compute the stability score for a given system prompt. */
+  computeStability(prompt: string): PrefixStabilityReport;
+  /** Verify that the frozen prefix matches the expected hash. */
+  verifyFrozenPrefix(prompt: string, expectedHash: string): boolean;
+  /** Compute the SHA‑256 hash of the frozen zone. */
+  hashFrozenPrefix(prompt: string): string;
+}
+interface PrefixStabilityReport {
+  /** How many tokens (estimated) are within the frozen zone. */
+  frozenTokens: number;
+  /** How many tokens are within the warm zone. */
+  warmTokens: number;
+  /** How many tokens are in the hot suffix (no cache benefit). */
+  hotTokens: number;
+  /** Fraction of the prompt that is stable (0–1). */
+  stabilityScore: number;
+}
+/**
+ * Create a prefix cache manager.
+ *
+ * The frozen zone is everything before the tool catalog;
+ * the warm zone is the tool catalog itself; the hot zone
+ * is the session‑specific suffix.
+ */
+declare function createPrefixCacheManager(): PrefixCacheManager;
+//#endregion
+//#region src/skills/loader.d.ts
+interface SkillRegistry {
+  /** List all discovered skills (name + description only). */
+  list(): SkillDefinition[];
+  /** Load the full body of a skill by name. */
+  load(name: string): SkillDefinition | undefined;
+  /** Force a re‑scan of ALL registered skill directories. */
+  reload(): void;
+  /** Add an additional directory to scan for skills. */
+  addDirectory(dir: string): void;
+  /** Returns the primary skills directory. */
+  readonly skillsDir: string;
+}
+/**
+ * Create a skill registry that watches the given directory.
+ *
+ * If the directory doesn't exist, the registry starts empty
+ * and skills can be added later via reload().
+ */
+declare function createSkillRegistry(skillsDir: string): SkillRegistry;
+//#endregion
+//#region src/skills/render.d.ts
+/**
+ * Render the short form (name + description) for injection
+ * into the system prompt.
+ */
+declare function renderSkillSummary(skill: SkillDefinition): string;
+/**
+ * Render the full body of a skill as a markdown block that
+ * can be inserted into the conversation as a user‑visible message.
+ */
+declare function renderSkillBody(skill: SkillDefinition): string;
+/**
+ * Render all known skill summaries as a section for the system prompt.
+ */
+declare function renderSkillCatalog(skills: SkillDefinition[]): string;
+//#endregion
+//#region src/skills/tool.d.ts
+/** The tool name the model uses to request skill bodies. */
+declare const SKILL_TOOL_NAME = "Skill";
+/**
+ * Create a ToolHandler that serves skill bodies on demand.
+ *
+ * The handler looks up the requested skill by name and returns
+ * its full body as a tool result.
+ */
+declare function createSkillToolHandler(registry: SkillRegistry): ToolHandler;
+//#endregion
+//#region src/skills/state.d.ts
+type SkillLoadStatus = "unloaded" | "loading" | "loaded" | "failed";
+interface SkillEntry {
+  definition: SkillDefinition;
+  status: SkillLoadStatus;
+  errorMessage?: string;
+}
+interface SkillState {
+  /** Get the tracked state for a skill by name. */
+  get(name: string): SkillEntry | undefined;
+  /** Mark a skill as loading. */
+  setLoading(name: string): void;
+  /** Mark a skill as loaded with its full definition. */
+  setLoaded(name: string, def: SkillDefinition): void;
+  /** Mark a skill as failed. */
+  setFailed(name: string, error: string): void;
+  /** List all tracked skills. */
+  list(): SkillEntry[];
+  /** Check if a skill is ready to use. */
+  isReady(name: string): boolean;
+}
+/**
+ * Create a skill state tracker.
+ *
+ * Tracks the lifecycle of each skill through unloaded → loading → loaded
+ * (or failed), so the prompt assembly knows which skills to include.
+ */
+declare function createSkillState(): SkillState;
+//#endregion
+//#region src/skills/watcher.d.ts
+interface SkillWatcher {
+  /** Start watching the skills directory. */
+  start(): void;
+  /** Stop watching. */
+  stop(): void;
+  /** Whether the watcher is currently active. */
+  readonly active: boolean;
+}
+/**
+ * Create a file watcher that auto‑reloads the skill registry
+ * when SKILL.md files change.
+ *
+ * Fail‑safe: file watch errors are logged but never crash the agent.
+ * If the directory doesn't exist, the watcher stays idle.
+ */
+declare function createSkillWatcher(registry: SkillRegistry): SkillWatcher;
+//#endregion
+//#region src/snapshot/capture.d.ts
+/** Capture a snapshot of the current agent state. */
+declare function captureSnapshot(sessionId: SessionId, turnIndex: number, messages: ContentBlock[]): AgentSnapshot;
+/** Check whether a snapshot is still within the valid time window. */
+declare function isSnapshotValid(snapshot: AgentSnapshot, maxAgeMs?: number): boolean;
+/** Estimate the token count of a snapshot's messages. */
+declare function estimateSnapshotTokens(snapshot: AgentSnapshot): number;
+/**
+ * Merge snapshot messages into an existing session message list.
+ *
+ * Preserves existing blocks before the snapshot's turn boundary
+ * and appends snapshot messages after. This avoids duplicating
+ * messages that were already persisted.
+ */
+declare function mergeSnapshot(existing: ContentBlock[], snapshot: AgentSnapshot): ContentBlock[];
+//#endregion
+//#region src/subagent/spawn.d.ts
+interface SubAgentConfig {
+  /** Human‑readable label for logging. */
+  label: string;
+  /** System prompt override (if empty, uses parent config). */
+  systemPrompt?: string;
+  /** Tools this sub‑agent is allowed to use. */
+  allowedTools: string[];
+  /** Maximum turns before auto‑termination. */
+  maxTurns: number;
+  /**
+   * Called when the sub‑agent completes to deduct token usage
+   * from the parent agent's budget. Receives total tokens consumed.
+   */
+  onTokensUsed?: (tokens: number) => void;
+}
+/** Options for {@link spawnSubAgent}. */
+interface SpawnSubAgentOptions {
+  /** LLM provider for sub‑agent queries. */
+  provider: LlmProvider;
+  /** Tool handlers available to the sub‑agent. */
+  tools: Map<string, ToolHandler>;
+  /** All visible tool descriptors. */
+  allTools: ToolDescriptor[];
+  /** Parent agent configuration to inherit from. */
+  parentConfig: AgentConfig;
+  /** Sub‑agent configuration (restricted tools, budget, etc.). */
+  subConfig: SubAgentConfig;
+  /** The task description for the sub‑agent. */
+  task: string;
+  /** Workspace directory for the sub‑agent. */
+  workspace: string;
+  /** Abort signal for cancellation. */
+  signal: AbortSignal;
+}
+/**
+ * Spawn a sub‑agent to handle a specific task.
+ *
+ * The sub‑agent runs the same query loop as the parent but
+ * with a restricted tool set and budget. Results are collected
+ * and returned when the sub‑agent completes.
+ */
+declare function spawnSubAgent(opts: SpawnSubAgentOptions): Promise<SubAgentResult>;
+//#endregion
+//#region src/subagent/lane.d.ts
+interface LaneJob {
+  id: string;
+  config: SubAgentConfig;
+  task: string;
+  workspace: string;
+}
+interface LaneResult {
+  jobId: string;
+  result: SubAgentResult;
+}
+interface LaneDispatcher {
+  /** Submit a job to a lane. Returns the result when the sub‑agent completes. */
+  dispatch(job: LaneJob, signal: AbortSignal): Promise<LaneResult>;
+  /** How many lanes are currently busy. */
+  readonly activeCount: number;
+  /** How many jobs are queued. */
+  readonly queueSize: number;
+}
+/** Options for {@link createLaneDispatcher}. */
+interface LaneDispatcherOptions {
+  /** LLM provider shared across all lanes. */
+  provider: LlmProvider;
+  /** Tool handlers shared across all lanes. */
+  tools: Map<string, ToolHandler>;
+  /** All visible tool descriptors. */
+  allTools: ToolDescriptor[];
+  /** Parent agent configuration. */
+  parentConfig: AgentConfig;
+  /** Maximum concurrent sub‑agents (default 4). */
+  maxLanes?: number;
+}
+/**
+ * Create a lane dispatcher for sub‑agent concurrency.
+ *
+ * Jobs exceeding the concurrency cap are queued and dequeued
+ * in FIFO order as lanes become free.
+ */
+declare function createLaneDispatcher(opts: LaneDispatcherOptions): LaneDispatcher;
+//#endregion
+//#region src/subagent/bridge.d.ts
+interface PermissionScope {
+  /** Tools the sub‑agent is allowed to call. */
+  allowedTools: Set<string>;
+  /** Whether dangerous tools are auto‑denied for the sub‑agent. */
+  denyDangerous: boolean;
+  /** Whether workspace‑safe tools auto‑approve. */
+  autoApproveWorkspaceSafe: boolean;
+  /** Whether the sub‑agent can escalate to ask the user. */
+  canEscalate: boolean;
+}
+interface PermissionBridge {
+  /** Build a restricted tool list for a sub‑agent scope. */
+  filterTools(allTools: ToolDescriptor[], scope: PermissionScope): ToolDescriptor[];
+  /** Check whether a specific tool is allowed in the given scope. */
+  isAllowed(toolName: string, scope: PermissionScope): boolean;
+  /** Create a default restrictive scope for sub‑agents. */
+  createRestrictiveScope(allowedTools: string[]): PermissionScope;
+}
+/**
+ * Create a permission bridge for sub‑agent delegation.
+ *
+ * The bridge enforces that sub‑agents can never have more
+ * permissions than their parent.
+ */
+declare function createPermissionBridge(): PermissionBridge;
+//#endregion
+//#region src/subagent/parallel.d.ts
+interface ParallelTask {
+  /** Human‑readable label for logging. */
+  label: string;
+  /** The task description sent to the sub‑agent. */
+  task: string;
+  /** Tools this sub‑agent can use. */
+  allowedTools: string[];
+}
+interface ParallelResult {
+  label: string;
+  result: SubAgentResult | null;
+  error?: string;
+}
+/** Options for {@link runInParallel}. */
+interface RunInParallelOptions {
+  /** LLM provider shared across all sub‑agents. */
+  provider: LlmProvider;
+  /** Tool handlers shared across all sub‑agents. */
+  tools: Map<string, ToolHandler>;
+  /** All visible tool descriptors. */
+  allTools: ToolDescriptor[];
+  /** Parent agent configuration. */
+  parentConfig: AgentConfig;
+  /** Tasks to fan‑out to sub‑agents. */
+  tasks: ParallelTask[];
+  /** Workspace directory for sub‑agents. */
+  workspace: string;
+  /** Abort signal for cancellation. */
+  signal: AbortSignal;
+  /** Maximum concurrent lanes (default 4). */
+  maxLanes?: number;
+}
+/**
+ * Run multiple sub‑agent tasks in parallel.
+ *
+ * Uses a lane dispatcher to control concurrency. Each task
+ * gets a unique sub‑agent instance. Failed tasks return null
+ * and an error string — the caller decides how to handle them.
+ */
+declare function runInParallel(opts: RunInParallelOptions): Promise<ParallelResult[]>;
+//#endregion
+//#region src/mcp/connection.d.ts
+/** An MCP resource exposed by a connected server. */
+interface McpResource {
+  uri: string;
+  name: string;
+  mimeType?: string;
+  description?: string;
+  server: string;
+}
+interface McpManager {
+  /** Connect to a configured MCP server. */
+  connect(config: McpServerConfig): Promise<McpConnection>;
+  /** Disconnect from a server and remove its tools. */
+  disconnect(serverName: string): Promise<void>;
+  /** Reconnect to a previously configured server with exponential backoff. */
+  reconnect(serverName: string): Promise<McpConnection>;
+  /** List all active connections. */
+  listConnections(): McpConnection[];
+  /** Get all tools from all connected servers. */
+  getAllTools(): ToolDescriptor[];
+  /**
+   * Call a tool on a connected MCP server.
+   *
+   * The `toolName` should be the namespaced name
+   * (e.g. `mcp__filesystem__read_file`).
+   */
+  callTool(toolName: string, args: Record<string, unknown>): Promise<{
+    content: string;
+    isError: boolean;
+  }>;
+  /** List all resources from all connected servers. */
+  getAllResources(): McpResource[];
+  /** Read a specific resource by URI from a server. */
+  readResource(serverName: string, uri: string): Promise<{
+    contents: unknown[];
+  }>;
+  /** Check if any connected server supports resources. */
+  hasResourceCapability(): boolean;
+  /**
+   * Subscribe to connection status changes.
+   * Returns an unsubscribe function.
+   */
+  onStatus(listener: McpStatusListener): () => void;
+  /** Shut down all connections. */
+  destroy(): Promise<void>;
+}
+/**
+ * Create an MCP connection manager.
+ *
+ * Manages the lifecycle of multiple MCP server connections,
+ * including connect, disconnect, tool call forwarding,
+ * automatic reconnection with exponential backoff,
+ * resource discovery, and status event emission.
+ */
+declare function createMcpManager(): McpManager;
+//#endregion
+//#region src/mcp/transport.d.ts
+/** Result of a tools/call request. */
+interface CallToolResult {
+  content: Array<{
+    type: "text" | "resource";
+    text?: string;
+    resource?: unknown;
+  }>;
+  isError?: boolean;
+}
+/**
+ * Connect to an MCP server over stdio transport.
+ *
+ * Spawns the server as a child process, performs the MCP
+ * initialization handshake, and discovers tools.
+ */
+/**
+ * Options for {@link connectStdioTransport}.
+ */
+interface ConnectStdioOptions {
+  /** Called immediately after the child process is spawned, before the handshake. */
+  onProcessSpawned?: (proc: ChildProcess) => void;
+}
+declare function connectStdioTransport(config: McpServerConfig, opts?: ConnectStdioOptions): Promise<{
+  connection: McpConnection;
+  process: ChildProcess;
+  tools: ToolDescriptor[];
+}>;
+/**
+ * Safely disconnect from an MCP server.
+ */
+declare function disconnectStdioTransport(proc: ChildProcess): void;
+/**
+ * Extract the original server‑side tool name from a namespaced MCP tool name.
+ *
+ * Inverse of {@link mcpToolName}: `mcp__myserver__read_file` → `read_file`.
+ */
+declare function extractMcpToolName(namespaced: string): string;
+/**
+ * Extract the server name from a namespaced MCP tool name.
+ *
+ * `mcp__myserver__read_file` → `myserver`.
+ */
+declare function extractMcpServerName(namespaced: string): string;
+//#endregion
+//#region src/mcp/transport-sse.d.ts
+/** Result of a tools/call request. */
+interface CallToolResult$1 {
+  content: Array<{
+    type: "text" | "resource";
+    text?: string;
+    resource?: unknown;
+  }>;
+  isError?: boolean;
+}
+/**
+ * Lightweight SSE connection — manages the HTTP transport lifecycle
+ * for a single MCP server. The server must support the MCP streamable
+ * HTTP transport (SSE for server→client, POST for client→server).
+ */
+interface SseMcpConnection {
+  /** The MCP endpoint URL (e.g. "http://localhost:8080/mcp"). */
+  url: string;
+  /** Close the SSE stream and abort any in‑flight requests. */
+  close(): void;
+}
+/**
+ * Connect to an MCP server over SSE (HTTP) transport.
+ *
+ * Performs the MCP initialization handshake via HTTP POST,
+ * discovers tools, and returns the connection metadata.
+ * No persistent SSE stream is kept open — tool calls are
+ * also sent via POST for simplicity (MCP streamable HTTP spec).
+ */
+declare function connectSseTransport(config: McpServerConfig): Promise<{
+  connection: McpConnection;
+  sessionId?: string;
+  tools: ToolDescriptor[];
+}>;
+/** Options for {@link callToolSse}. */
+interface CallToolSseOpts {
+  toolName: string;
+  args: Record<string, unknown>;
+  serverName: string;
+  headers?: Record<string, string>;
+  sessionId?: string;
+}
+/**
+ * Call a tool on an MCP server over SSE (HTTP) transport.
+ *
+ * Sends `tools/call` via HTTP POST and returns the parsed result.
+ * The `toolName` is the ORIGINAL server‑side name (not namespaced).
+ */
+declare function callToolSse(url: string, opts: CallToolSseOpts): Promise<CallToolResult$1>;
+//#endregion
+//#region src/mcp/transport-ws.d.ts
+/** Result of a tools/call request. */
+interface CallToolResult$2 {
+  content: Array<{
+    type: "text" | "resource";
+    text?: string;
+    resource?: unknown;
+  }>;
+  isError?: boolean;
+}
+/** WebSocket 连接句柄 — 管理一个 WS 连接的生命周期。 */
+interface WebSocketConnection {
+  ws: WebSocket;
+  /** 关闭 WebSocket 连接并清理待处理请求。 */
+  close(): void;
+}
+/**
+ * 通过 WebSocket 连接到 MCP 服务器。
+ *
+ * 握手序列：new WebSocket(wsUrl) → onopen → initialize → notifications/initialized → tools/list。
+ * 使用 Node.js 22+ 内置 WebSocket API。
+ *
+ * 如果 initialize 在 CONNECT_TIMEOUT_MS 内未完成，则拒绝并关闭连接。
+ */
+declare function connectWsTransport(config: McpServerConfig): Promise<{
+  connection: McpConnection;
+  conn: WebSocketConnection;
+  tools: ToolDescriptor[];
+}>;
+/**
+ * 通过 WebSocket 调用 MCP 服务器上的工具。
+ *
+ * `toolName` 是原始服务器端名称（非命名空间格式）。
+ */
+declare function callToolWs(conn: WebSocketConnection, toolName: string, args: Record<string, unknown>, serverName: string): Promise<CallToolResult$2>;
+//#endregion
+//#region src/mcp/transport-inproc.d.ts
+/**
+ * In‑process 传输端点 — 链接对中的一端。
+ * 参考 Claude Code 的 InProcessTransport 设计。
+ */
+interface InProcTransport {
+  /** 向对端发送 JSON‑RPC 消息字符串。 */
+  send(message: string): void;
+  /** 对端消息到达时的回调。 */
+  onMessage: ((data: string) => void) | null;
+  /** 关闭此端点。 */
+  close(): void;
+}
+/**
+ * 创建一对链接的 in‑process transport 端点。
+ *
+ * send() 在一端调用，通过 queueMicrotask 异步传递到对端的 onMessage。
+ * 返回 `[client, server]` — client 端由 Lynx MCP manager 持有，
+ * server 端交给 in‑process MCP server 使用。
+ *
+ * 两个端点共享一个消息队列，每个 send() 追加消息并调度一个 microtask
+ * 来排空队列并投递到对端的 onMessage。
+ */
+declare function createInProcPair(): [InProcTransport, InProcTransport];
+/**
+ * 通过 in‑process transport 连接到 MCP 服务器。
+ *
+ * 在指定的端点 peer 上执行标准 MCP 握手：
+ *   1. 发送 initialize → 等待响应
+ *   2. 发送 notifications/initialized
+ *   3. 发送 tools/list → 构建 ToolDescriptor 列表
+ *
+ * In‑process 传输不需要超时保护（底层同步执行，microtask 调度保证公平性）。
+ */
+declare function connectInProcTransport(peer: InProcTransport, serverName: string): Promise<{
+  connection: McpConnection;
+  tools: ToolDescriptor[];
+}>;
+//#endregion
+//#region src/mcp/oauth.d.ts
+/** OAuth 2.0 token 响应。 */
+interface OAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  /** 过期时间（epoch 毫秒），undefined 表示永不过期。 */
+  expiresAt?: number;
+}
+/**
+ * 执行 OAuth 2.0 PKCE 授权码流程。
+ *
+ * 完整流程：
+ * 1. 生成 PKCE code_verifier（128 bytes，base64url）
+ * 2. 计算 code_challenge = SHA256(code_verifier)，base64url 编码
+ * 3. 在随机端口启动临时 HTTP 服务器接收回调
+ * 4. 打开浏览器到授权端点
+ * 5. 接收回调，用 code + code_verifier 交换 token
+ *
+ * 调用方负责用 {@link storeToken} 持久化返回的 token。
+ */
+declare function performPkceFlow(config: McpOAuthConfig): Promise<OAuthToken>;
+/**
+ * 用 refresh_token 刷新过期的 access token。
+ *
+ * 向 tokenEndpoint 发送 `grant_type=refresh_token` 请求。
+ * 如果刷新失败则抛出错误——调用方需自行调用 {@link deleteToken}
+ * 清除已存储的过期 token，并引导用户重新授权。
+ *
+ * 如果端点未返回新的 refresh_token，会保留旧的 refresh_token 继续使用。
+ */
+declare function refreshOAuthToken(config: McpOAuthConfig, refreshToken: string): Promise<OAuthToken>;
+/**
+ * 从 ~/.lynx/mcp-oauth.json 加载已存储的 token。
+ *
+ * @param serverName - MCP 服务器名称，对应配置文件中的 `name` 字段
+ * @returns 已存储的 token，文件不存在或数据损坏时返回 undefined
+ */
+declare function loadToken(serverName: string): OAuthToken | undefined;
+/**
+ * 将 token 原子写入 ~/.lynx/mcp-oauth.json。
+ *
+ * 按 serverName 为 key 分组存储，写入过程为原子操作
+ *（写临时文件 + rename），不会因进程崩溃而产生损坏文件。
+ *
+ * @param serverName - MCP 服务器名称
+ * @param token - 待持久化的 OAuth token
+ */
+declare function storeToken(serverName: string, token: OAuthToken): void;
+/**
+ * 删除指定 server 的已存储 token。
+ *
+ * @param serverName - MCP 服务器名称
+ */
+declare function deleteToken(serverName: string): void;
+//#endregion
+//#region src/mcp/xaa.d.ts
+/**
+ * XAA 身份认证结果。
+ *
+ * 包含 JWT access token、过期时间及 JWT claims，
+ * 认证成功后持久化到 ~/.lynx/mcp-xaa.json。
+ */
+interface XaaIdentity {
+  /** JWT access token。 */
+  token: string;
+  /** 过期时间（epoch ms）。 */
+  expiresAt: number;
+  /** JWT claims（iss, sub, aud 等）。 */
+  claims: Record<string, unknown>;
+}
+/**
+ * 执行 XAA (SEP-990) 企业身份认证流程。
+ *
+ * 完整步骤：
+ *   1. PRM 发现 — GET {config.idpUrl}/.well-known/oauth-protected-resource 获取 AS URL
+ *   2. AS 发现  — GET {asUrl}/.well-known/oauth-authorization-server 获取 token endpoint
+ *   3. JWT Bearer Grant — 生成 HS256 JWT assertion → POST {tokenEndpoint}
+ *   4. 本地持久化 — 写入 ~/.lynx/mcp-xaa.json
+ *
+ * @param config - XAA 认证配置
+ * @returns 认证身份（含 token、过期时间、claims）
+ * @throws 参数校验失败、发现失败、Token 交换失败 时抛出
+ */
+declare function performXaaLogin(config: McpXaaConfig): Promise<XaaIdentity>;
+/**
+ * 用已缓存的 identity 尝试静默刷新。
+ *
+ * - 如果 token 仍然有效（expiresAt > now + 5min），直接返回缓存的身份
+ * - 否则重新执行完整的 XAA 认证流程
+ *
+ * 刷新成功后自动更新持久化存储。
+ *
+ * @param config - XAA 认证配置（必须包含 serverName 或通过 loadIdentity/storeIdentity 使用）
+ * @returns 有效的认证身份
+ */
+declare function refreshXaaToken(config: McpXaaConfig): Promise<XaaIdentity>;
+/**
+ * 从 ~/.lynx/mcp-xaa.json 加载已存储的身份。
+ *
+ * @param serverName - MCP 服务器名称（用作存储键）
+ * @returns 有效的 XaaIdentity，或 undefined 如果文件不存在 / token 已过期 / 数据损坏
+ */
+declare function loadIdentity(serverName: string): XaaIdentity | undefined;
+/**
+ * 原子存储身份到 ~/.lynx/mcp-xaa.json。
+ *
+ * 读取现有缓存 → 更新目标 serverName 条目 → 原子写入。
+ * 多进程并发写入由 rename 的原子性保证：最后一次写入获胜。
+ *
+ * @param serverName - MCP 服务器名称（用作存储键）
+ * @param identity - 要存储的身份信息
+ */
+declare function storeIdentity(serverName: string, identity: XaaIdentity): void;
+//#endregion
+//#region src/memory/manager.d.ts
+/**
+ * Memory manager — persistent key‑value facts that survive
+ * across sessions.
+ *
+ * Memory entries are simple markdown files with frontmatter,
+ * stored in a configured directory. The agent can read/write
+ * memories via tools.
+ *
+ * Pattern: inspired by Claude Code's memory system —
+ *   ● Each fact is one file
+ *   ● Frontmatter contains metadata (type, tags, timestamp)
+ *   ● An index file (MEMORY.md) lists all entries for fast scanning
+ *   ● Loading reads the index first, then lazy‑loads individual files
+ */
+interface MemoryEntry {
+  /** File stem (slug). */
+  name: string;
+  /** Short description for relevance matching. */
+  description: string;
+  /** When the entry was last modified (Unix ms). */
+  updatedAt: number;
+  /** Full markdown content (lazy‑loaded). */
+  content?: string;
+  /** Metadata from frontmatter. */
+  type: "user" | "feedback" | "project" | "reference";
+  /** Absolute file path on disk. */
+  filePath: string;
+  /** Arbitrary extra metadata fields from frontmatter (e.g. tags, source). */
+  metadata?: Record<string, unknown>;
+}
+interface MemoryManager {
+  /** Load the index (all memory names + descriptions). */
+  list(): MemoryEntry[];
+  /** Load a single memory entry by name. */
+  get(name: string): MemoryEntry | undefined;
+  /** Write (create or update) a memory entry. */
+  put(entry: MemoryEntry): void;
+  /** Delete a memory entry by name. */
+  delete(name: string): boolean;
+  /** Reload the index from disk. */
+  reload(): void;
+  /** 全文搜索记忆 — 在名称、描述、内容中匹配关键词。按相关度排序。 */
+  search(query: string): MemoryEntry[];
+  /** 去重压缩 — 合并 Jaccard 相似度 > 0.8 的条目。返回合并后的条目列表。 */
+  compact(): MemoryEntry[];
+  /** 按 glob 模式批量删除匹配的记忆。返回删除的条目数。 */
+  forget(pattern: string): number;
+  /** 将所有记忆序列化为 JSON 字符串。 */
+  exportAll(): string;
+  /** 从 JSON 字符串批量导入记忆。跳过已存在的同名条目。返回导入数量。 */
+  importAll(data: string): number;
+  /** 合并另一个 memory 目录中的记忆文件。跳过冲突。返回合并的条目数。 */
+  merge(sourceDir: string): number;
+}
+/**
+ * Create a memory manager backed by a directory on disk.
+ *
+ * If the directory doesn't exist, it is created.
+ */
+declare function createMemoryManager(dir: string): MemoryManager;
+//#endregion
+//#region src/memory/semantic-search.d.ts
+/** 单条搜索结果 */
+interface SemanticSearchResult {
+  entry: MemoryEntry;
+  score: number;
+  /** 高亮片段 — 匹配词用 **...** 包裹 */
+  snippet: string;
+}
+/**
+ * 跨所有记忆执行语义搜索。
+ *
+ * 算法：
+ * 1. 将查询解析为词元，移除停用词
+ * 2. 对每条记忆计算：
+ *    - TF：词元在内容中出现的频率，按内容长度归一化
+ *    - 标题加权：匹配 entry.name 的词元权重 x3
+ *    - 描述加权：匹配 entry.description 的词元权重 x2
+ *    - 时间加权：越新的条目得分越高（1.0 ~ 0.5）
+ * 3. 返回 topK 个结果，按评分降序排列，
+ *    每条附带一个包含高亮标记的片段
+ */
+declare function searchMemorySemantic(manager: MemoryManager, query: string, topK?: number): SemanticSearchResult[];
+//#endregion
+//#region src/memory/expiry.d.ts
+/** 过期管理器接口 */
+interface ExpiryManager {
+  /** 检查所有记忆并归档过期条目。返回归档数量。 */
+  checkAndArchive(): number;
+  /** 获取条目的时间衰减权重（0.0-1.0）。越新越高。 */
+  getWeight(entry: MemoryEntry): number;
+  /** 为条目设置过期天数。day=0 表示永不过期。 */
+  setExpiry(name: string, days: number): void;
+  /** 按权重升序排列条目（最低——最接近过期——排在前面）。 */
+  listByExpiry(): Array<{
+    name: string;
+    weight: number;
+    daysRemaining: number;
+  }>;
+}
+/**
+ * 创建过期管理器。
+ *
+ * @param memoryDir - 记忆文件目录（如 ~/.lynx/memory/）
+ */
+declare function createExpiryManager(memoryDir: string): ExpiryManager;
+//#endregion
+//#region src/memory/active-refine.d.ts
+/** 单条精炼建议 */
+interface RefinementSuggestion {
+  entryName: string;
+  reason: "内容过长" | "可能重复" | "信息过时" | "格式不规范";
+  /** 面向人类可读的建议文本 */
+  suggestion: string;
+}
+/** 活跃精炼管理器接口 */
+interface ActiveRefinementManager {
+  /** 建议可以精炼的条目（过长、重复、过时、不规范）。 */
+  suggestRefinements(): RefinementSuggestion[];
+  /** 合并两条条目 — 将 source 的内容追加到 target 中，删除 source。 */
+  mergeEntries(target: string, source: string): MemoryEntry;
+  /** 摘要条目 — 将内容截断至 maxChars，添加摘要行。 */
+  summarizeEntry(name: string, maxChars?: number): MemoryEntry;
+  /** 检测并报告近似重复条目（内容 bigram Jaccard > 0.6）。 */
+  findDuplicates(): Array<{
+    entryA: string;
+    entryB: string;
+    similarity: number;
+  }>;
+}
+/**
+ * 创建活跃精炼管理器。
+ *
+ * 封装记忆精炼建议、合并、摘要和重复检测逻辑，
+ * 供 agent 引擎定期或按需调用。
+ */
+declare function createActiveRefinementManager(memoryManager: MemoryManager): ActiveRefinementManager;
+//#endregion
+//#region src/memory/team.d.ts
+/** 团队上下文 */
+interface TeamContext {
+  /** 团队 CLAUDE.md 文件内容 */
+  teamClaudeMd: string;
+  /** 团队规则列表（rules/ 目录下每个 .md 文件一条） */
+  teamRules: string[];
+  /** 团队事实（memory/ 目录中的记忆条目名） */
+  teamFacts: string[];
+}
+/** 团队记忆管理器接口 */
+interface TeamMemoryManager {
+  /** 从团队目录加载团队上下文。 */
+  loadTeamContext(): TeamContext;
+  /** 写入团队记忆条目（在 teamDir/memory/ 下创建/更新文件）。 */
+  write(name: string, content: string, author: string): void;
+  /** 列出所有团队记忆条目。 */
+  list(): MemoryEntry[];
+}
+/**
+ * 创建团队记忆管理器。
+ *
+ * @param teamDir - 团队目录路径（如 /workspace/.claude/team/ 或 ~/.lynx/team/）
+ */
+declare function createTeamMemoryManager(teamDir: string): TeamMemoryManager;
+//#endregion
+//#region src/tasks/manager.d.ts
+/**
+ * Background task manager — runs persistent tasks with lifecycle tracking.
+ *
+ * Tasks are long‑running operations (file watchers, MCP heartbeats,
+ * auto‑save timers) that outlive a single query turn. The manager
+ * provides start/stop/status for each task and graceful shutdown.
+ */
+interface TaskEntry {
+  id: string;
+  label: string;
+  status: "running" | "stopping" | "stopped" | "errored";
+  startedAt: number;
+  stoppedAt?: number;
+  error?: string;
+  /** Accumulated output text. */
+  output?: string;
+  /** Progress percentage 0-100. */
+  progress?: number;
+  /** Output chunks with timestamps for streaming. */
+  outputChunks?: Array<{
+    text: string;
+    timestamp: number;
+  }>;
+}
+interface TaskManager {
+  /** Register and start a background task. Returns a stop function. */
+  start(id: string, label: string, run: (signal: AbortSignal) => Promise<void>): Promise<void>;
+  /** Request graceful stop of a task. */
+  stop(id: string): Promise<void>;
+  /** Get a single task entry by id. Returns undefined if not found. */
+  get(id: string): TaskEntry | undefined;
+  /** Get status for all tasks. */
+  list(): TaskEntry[];
+  /** Get accumulated output for a task. */
+  getOutput(id: string): string;
+  /** Get all output chunks for a task since a given offset. */
+  getOutputSince(id: string, sinceIndex: number): {
+    output: string;
+    newIndex: number;
+  };
+  /** Update task metadata (label, status, etc.). */
+  update(id: string, patch: Partial<Pick<TaskEntry, "label" | "status">>): void;
+  /** Stop all tasks and wait for them to finish. */
+  destroy(): Promise<void>;
+}
+/**
+ * Create a background task manager.
+ *
+ * Each task receives an AbortSignal — when the manager calls stop(),
+ * the signal fires and the task should clean up and exit.
+ */
+declare function createTaskManager(): TaskManager;
+//#endregion
+export { type ActiveRefinementManager, type AgentConfig, type AgentSnapshot, type AgentState, type AgentStatus, type AssembleOptions, type BudgetTracker, type CallToolResult, type CompactionManager, type CompactionResult, type CompactionStrategy, type EngineDeps, type ExpiryManager, type HandoffContext, type InProcTransport, type LaneDispatcher, type LaneJob, type LaneResult, type LoopDeps, type McpConnection, type McpManager, type McpOAuthConfig, type McpResource, type McpServerConfig, type McpStatusEvent, type McpStatusListener, type McpTransportKind, type MemoryEntry, type MemoryManager, type OAuthToken, type ParallelResult, type ParallelTask, type PermissionBridge, type PermissionScope, type PrefixCacheManager, type PrefixStabilityReport, type QueryEngine, type RefinementSuggestion, SKILL_TOOL_NAME, type SemanticSearchResult, type SkillDefinition, type SkillEntry, type SkillLoadStatus, type SkillRegistry, type SkillState, type SkillWatcher, type CallToolResult$1 as SseCallToolResult, type SseMcpConnection, type SubAgentConfig, type SubAgentResult, type TaskEntry, type TaskManager, type TeamContext, type TeamMemoryManager, type TurnContext, type WebSocketConnection, type CallToolResult$2 as WsCallToolResult, type XaaIdentity, advanceTurn, assembleSystemPrompt, buildMessagesForTurn, callToolSse, callToolWs, captureSnapshot, computeFrozenHash, connectInProcTransport, connectSseTransport, connectStdioTransport, connectWsTransport, createActiveRefinementManager, createAgentState, createBudgetTracker, createCompactionManager, createExpiryManager, createInProcPair, createLaneDispatcher, createMcpManager, createMemoryManager, createPermissionBridge, createPrefixCacheManager, createQueryEngine, createSkillRegistry, createSkillState, createSkillToolHandler, createSkillWatcher, createTaskManager, createTeamMemoryManager, deleteToken, disconnectStdioTransport, estimateSnapshotTokens, extractFrozenZone, extractHotZone, extractMcpServerName, extractMcpToolName, extractWarmZone, generateHandoff, getBaseSystemPrompt, isCompactionCircuitOpen, isSnapshotValid, loadIdentity, loadProjectContext, loadToken, mergeSnapshot, needsHandoff, performPkceFlow, performXaaLogin, queryLoop, recordCompactionFailure, recordCompactionSuccess, recordError, refreshOAuthToken, refreshXaaToken, renderHandoffBlock, renderSkillBody, renderSkillCatalog, renderSkillSummary, runInParallel, sameFrozenPrefix, searchMemorySemantic, spawnSubAgent, storeIdentity, storeToken, transition };
+//# sourceMappingURL=index.d.mts.map