@animus-labs/cortex 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,881 @@
+/**
+ * Core types for the @animus-labs/cortex package.
+ *
+ * These types define the public API surface for CortexAgent configuration,
+ * context management, error classification, working tags, budget guards,
+ * compaction, events, and model tiers.
+ *
+ * References:
+ *   - cortex-architecture.md
+ *   - context-manager.md
+ *   - model-tiers.md
+ *   - error-recovery.md
+ *   - working-tags.md
+ */
+import type { CortexModel } from './model-wrapper.js';
+import type { ObservationalMemoryConfig, ObservationEvent, ReflectionEvent } from './compaction/observational/types.js';
+/**
+ * Pluggable logger interface for Cortex diagnostics.
+ *
+ * Cortex never decides where logs go. The consumer provides an implementation
+ * via CortexAgentConfig.logger. If omitted, all logging is silently discarded.
+ *
+ * All methods share the same signature for uniformity. The optional `data`
+ * parameter carries structured context (token counts, server names, error
+ * objects, etc.) that the consumer can serialize or inspect as needed.
+ *
+ * Compatible with `console` for quick development: `logger: console` works
+ * because console methods accept variadic args and ignore the extra object.
+ */
+export interface CortexLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Token usage and cost data from a single LLM call.
+ * Mirrors the pi-ai AssistantMessage.usage structure but is decoupled
+ * from pi-ai's types to avoid hard runtime dependencies.
+ */
+export interface CortexUsage {
+    /** Input (prompt) tokens. */
+    input: number;
+    /** Output (completion) tokens. */
+    output: number;
+    /** Cache-read tokens (tokens served from cache). */
+    cacheRead: number;
+    /** Cache-write tokens (tokens written to cache). */
+    cacheWrite: number;
+    /** Total tokens (input + output). */
+    totalTokens: number;
+    /** Cost breakdown in USD. */
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    /** Model identifier string (if available from the response). */
+    model?: string;
+}
+/**
+ * Accumulated usage data across the lifetime of a session.
+ *
+ * Unlike BudgetGuard (which resets per agentic loop for enforcement),
+ * SessionUsage accumulates across all loops for reporting and persistence.
+ * Cortex tracks this in memory; consumers persist and restore as needed.
+ */
+export interface SessionUsage {
+    /** Total cost in USD across all turns. */
+    totalCost: number;
+    /** Total number of LLM turns across all loops. */
+    totalTurns: number;
+    /** Accumulated token counts across all turns. */
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+}
+/**
+ * The lifecycle state of a CortexAgent instance.
+ *
+ * CREATED -> ACTIVE -> DESTROYED
+ *
+ * abort() returns the agent to ACTIVE (still usable).
+ * destroy() transitions to DESTROYED (all resources released).
+ */
+export type CortexLifecycleState = 'created' | 'active' | 'destroyed';
+/**
+ * Consumer-facing thinking/effort level.
+ *
+ * "max" maps to pi-ai/pi-agent-core's "xhigh" internally.
+ * "off" disables extended thinking entirely.
+ */
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max';
+/**
+ * Describes a model's thinking/reasoning capabilities.
+ * Returned by CortexAgent.getModelThinkingCapabilities().
+ */
+export interface ModelThinkingCapabilities {
+    /** Whether the model supports extended thinking at all. */
+    supportsThinking: boolean;
+    /** Whether the model supports the "max" (xhigh) thinking level. */
+    supportsMax: boolean;
+    /** Exact thinking levels this model accepts, using Cortex's public names. */
+    supportedLevels: ThinkingLevel[];
+}
+export type CortexToolPermissionDecision = 'allow' | 'block' | 'ask';
+export interface CortexToolPermissionResult {
+    decision: CortexToolPermissionDecision;
+    reason?: string;
+}
+/**
+ * Configuration for creating a CortexAgent instance.
+ *
+ * The `model` field uses CortexModel as the public boundary.
+ * Consumers obtain these handles from ProviderManager and pass them back to
+ * CortexAgent. Raw pi-ai model objects stay inside Cortex.
+ */
+export interface CortexAgentConfig {
+    /** Primary model for the agentic loop, THOUGHT, REFLECT, and all consumer-facing work. */
+    model: CortexModel;
+    /**
+     * Initial application/base prompt.
+     * Cortex composes its operational sections around this prompt.
+     */
+    initialBasePrompt?: string;
+    /**
+     * Utility model for internal operations (WebFetch summarization, safety classifier).
+     * - `'default'`: Cortex selects from a built-in mapping based on the primary model's provider.
+     * - A CortexModel: explicit utility model (must be same provider as primary).
+     * - `undefined`: same as `'default'`.
+     */
+    utilityModel?: CortexModel | 'default';
+    /** Working directory for file operations (Bash, Read, Write, Edit, Glob, Grep). */
+    workingDirectory: string;
+    /**
+     * Callback to resolve API keys by provider name.
+     * Throws on failure (classified as authentication error).
+     * Returns the API key string on success. Must never return empty string.
+     */
+    getApiKey?: (provider: string) => Promise<string>;
+    /** Ordered list of context slot names. Order defines position in the message array. */
+    slots?: string[];
+    /** Working tags configuration. */
+    workingTags?: {
+        /** Whether to enable working tags. Default: true. */
+        enabled?: boolean;
+    };
+    /** Budget guard configuration. */
+    budgetGuard?: {
+        /** Maximum number of LLM turns before force-stopping the loop. Default: Infinity. */
+        maxTurns?: number;
+        /** Maximum cost in USD before force-stopping the loop. Default: Infinity. */
+        maxCost?: number;
+    };
+    /** Maximum number of concurrent sub-agents. */
+    maxConcurrentSubAgents?: number;
+    /**
+     * Tool execution strategy for assistant messages with multiple tool calls.
+     * Defaults to sequential for deterministic permission, logging, and UI order.
+     */
+    toolExecution?: 'sequential' | 'parallel';
+    /** WebFetch tool configuration. */
+    webFetch?: {
+        /** Maximum number of web fetches per agentic loop. */
+        maxPerLoop?: number;
+    };
+    /** Bash tool configuration. */
+    bash?: {
+        /** Token threshold at which Bash auto-yields control back to the agent. */
+        autoYieldThreshold?: number;
+        /** Path to the shell executable. */
+        shellPath?: string;
+    };
+    /**
+     * Disable specific built-in tools by name.
+     * Built-in tools (Read, Write, Edit, Glob, Grep, Bash, WebFetch, TaskOutput)
+     * are registered automatically. Use this to exclude tools the agent should not have.
+     * SubAgent and load_skill are controlled separately via enableSubAgentTool/enableLoadSkillTool.
+     */
+    disableTools?: string[];
+    /**
+     * Structured permission result for a tool call.
+     * - `allow`: proceed immediately
+     * - `block`: deny the call
+     * - `ask`: consumer requires approval before the call can proceed
+     */
+    resolvePermission?: (toolName: string, toolArgs: unknown) => Promise<boolean | CortexToolPermissionResult>;
+    /**
+     * Initial thinking/effort level for the agentic loop.
+     * Omit to use the pi-agent-core default (medium).
+     * "max" maps to pi-ai/pi-agent-core's "xhigh" internally.
+     * Consumers can use getModelThinkingCapabilities() and clampThinkingLevel()
+     * to avoid exposing unsupported levels.
+     */
+    thinkingLevel?: ThinkingLevel;
+    /**
+     * Limit the effective context window for compaction calculations.
+     * Clamped to min(limit, model.contextWindow) with a floor of MINIMUM_CONTEXT_WINDOW (16K).
+     * null or undefined = use the model's full context window.
+     */
+    contextWindowLimit?: number | null;
+    /** Compaction configuration. All layers are always active. */
+    compaction?: Partial<CortexCompactionConfig>;
+    /**
+     * Deferred tool loading. When enabled, tools marked for deferral are NOT
+     * included in the `tools` array sent on every API turn. Instead, their
+     * names appear in an internally-managed `_available_tools` slot, and the
+     * agent uses the auto-registered `ToolSearch` tool to load specific tools
+     * on demand.
+     *
+     * Useful when consumers connect MCP servers with many tools: schemas are
+     * only paid for once a tool is actually needed, instead of every turn.
+     */
+    deferredTools?: DeferredToolsConfig;
+    /**
+     * Persists oversized tool results to disk and returns the file path.
+     *
+     * When configured, large tool results (>25K tokens by default) are
+     * replaced in the conversation with a bookend preview (head + tail)
+     * plus a file reference, so the model can use the Read tool to access
+     * the full content on demand.
+     *
+     * Used by both the proactive tool execution interceptor and the
+     * reactive compaction paths (microcompaction trim, aggregate budget
+     * enforcement). Consumer owns the storage location and cleanup.
+     *
+     * If both this and `compaction.microcompaction.persistResult` are set,
+     * this top-level setting wins (and is propagated to microcompaction).
+     */
+    persistResult?: PersistResultFn;
+    /**
+     * Per-tool token threshold overrides for the result-persistence interceptor.
+     *
+     * Tools not listed here use the built-in defaults (Bash: 7,500 to keep
+     * verbose command output tight; everything else: 25,000).
+     *
+     * Useful for tuning specific MCP tools or custom tools whose output has
+     * unusual size characteristics (e.g., a tool that returns large JSON payloads
+     * where you want a smaller cap, or a research tool whose output you want to
+     * keep more of in context).
+     */
+    toolResultThresholds?: Record<string, number>;
+    /**
+     * Consumer-set environment variables that propagate to ALL subprocesses
+     * (Bash tool, MCP stdio servers), bypassing the security blocklist.
+     *
+     * Use case: macOS dock icon suppression requires DYLD_INSERT_LIBRARIES
+     * and ANIMUS_DOCK_SUPPRESS_ADDON to propagate to child processes, but
+     * the safe-env blocklist strips DYLD_ prefixed variables by default.
+     * envOverrides are merged ON TOP of the sanitized environment, restoring
+     * these specific variables.
+     */
+    envOverrides?: Record<string, string>;
+    /**
+     * Optional logger for Cortex internal diagnostics.
+     * If omitted, all internal logging is silently discarded (no-op).
+     * The library never decides where logs go; only the consumer does.
+     *
+     * Compatible with `console` for quick development: `{ logger: console }`.
+     */
+    logger?: CortexLogger;
+    /**
+     * Optional diagnostics for investigating prompt or provider stalls.
+     * All diagnostics are opt-in and should remain disabled in normal use.
+     */
+    diagnostics?: CortexDiagnosticsConfig;
+}
+/**
+ * Prompt watchdog diagnostics configuration.
+ *
+ * Emits bounded lifecycle and heartbeat logs around prompt() and abort().
+ * Intended for investigating freezes or hung provider calls.
+ */
+export interface PromptWatchdogDiagnosticsConfig {
+    /** Whether prompt watchdog diagnostics are enabled. Default: false. */
+    enabled?: boolean;
+    /** Heartbeat interval while a prompt is in flight. Default: 1000ms. */
+    heartbeatIntervalMs?: number;
+    /** Warn if abort waits longer than this for idle. Default: 2000ms. */
+    abortWaitWarningMs?: number;
+}
+/**
+ * Optional diagnostics for Cortex internals.
+ *
+ * These are intentionally narrow and structured so consumers can opt into
+ * targeted investigations without turning normal debug logging into trace spam.
+ */
+export interface CortexDiagnosticsConfig {
+    /** Prompt and abort watchdog logs for freeze investigation. */
+    promptWatchdog?: PromptWatchdogDiagnosticsConfig;
+}
+/**
+ * Configuration for deferred tool loading.
+ *
+ * Reference: docs/cortex/tools/tool-search.md (TBD)
+ */
+export interface DeferredToolsConfig {
+    /**
+     * Master switch. When false (default), all tools are sent on every turn
+     * exactly as before. When true, tools marked for deferral are pulled out
+     * of the per-turn tools array and announced by name in the
+     * `_available_tools` slot instead.
+     */
+    enabled?: boolean;
+    /**
+     * When true (default), all MCP tools are deferred. When false, MCP tools
+     * are sent in full like built-ins. Has no effect when `enabled` is false.
+     */
+    deferMcp?: boolean;
+    /**
+     * Tool names that should never be deferred even if they match deferral
+     * criteria (overrides `shouldDefer` and `deferMcp` for the named tools).
+     * Use this to keep specific MCP tools always loaded.
+     */
+    alwaysLoad?: string[];
+}
+/**
+ * Configuration for the ContextManager.
+ *
+ * Slots define the ordered list of persistent content blocks at the start
+ * of the message array. Order determines position (first = most stable,
+ * best prefix cache hit rate).
+ */
+export interface ContextManagerConfig {
+    /** Ordered list of slot names. */
+    slots: string[];
+}
+/**
+ * Error categories for classifying LLM and network errors.
+ * Checked in priority order (first match wins).
+ */
+export type ErrorCategory = 'authentication' | 'rate_limit' | 'context_overflow' | 'server_error' | 'network' | 'cancelled' | 'unknown';
+/**
+ * Error severity levels.
+ * - fatal: unrecoverable, stop processing (e.g., invalid API key)
+ * - retry: transient, can be retried (e.g., rate limit, server error, network)
+ * - recoverable: can be handled without retry (e.g., context overflow triggers compaction)
+ */
+export type ErrorSeverity = 'fatal' | 'retry' | 'recoverable';
+/**
+ * A classified error with category, severity, original message, and suggested action.
+ */
+export interface ClassifiedError {
+    /** The error category determined by pattern matching. */
+    category: ErrorCategory;
+    /** The severity level for the category. */
+    severity: ErrorSeverity;
+    /** The original error message string. */
+    originalMessage: string;
+    /** Human-readable suggested action, or undefined if no action is needed. */
+    suggestedAction?: string;
+}
+/**
+ * Structured output from parsing working tags in agent text.
+ *
+ * Working tags separate internal reasoning (<working>...</working>) from
+ * user-facing communication. Both remain in conversation history; the
+ * difference is only in delivery.
+ */
+export interface AgentTextOutput {
+    /** Text intended for the user (working tag content stripped, whitespace normalized). */
+    userFacing: string;
+    /** Content from inside <working> tags, concatenated. Null if no working tags present. */
+    working: string | null;
+    /** The original unparsed text exactly as the agent produced it. */
+    raw: string;
+}
+/**
+ * Structured tool result with content array and typed details.
+ */
+export interface ToolContentDetails<T> {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    details: T;
+}
+/**
+ * Context passed to tool execute functions by the pi-agent-core adapter.
+ *
+ * Tools that want streaming support accept this as an optional second parameter.
+ * Tools that don't need it simply ignore it (backward compatible).
+ */
+export interface ToolExecuteContext {
+    /** Unique identifier for this tool call. */
+    toolCallId: string;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Callback for emitting incremental results during execution.
+     * Pi-agent-core emits these as tool_execution_update events.
+     * Useful for long-running tools (bash, sub-agents) that want to
+     * stream progress to the consumer's UI.
+     */
+    onUpdate?: (partialResult: ToolContentDetails<unknown>) => void;
+}
+/**
+ * Typed payload for tool_call_start events.
+ */
+export interface ToolCallStartPayload {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Typed payload for tool_call_update events.
+ */
+export interface ToolCallUpdatePayload {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    partialResult: ToolContentDetails<unknown>;
+}
+/**
+ * Typed payload for tool_call_end events.
+ */
+export interface ToolCallEndPayload {
+    toolCallId: string;
+    toolName: string;
+    result: ToolContentDetails<unknown>;
+    durationMs: number;
+    isError: boolean;
+    error?: string;
+}
+/**
+ * Budget guard configuration with explicit limits.
+ * Both default to Infinity (no enforcement).
+ */
+export interface BudgetGuardConfig {
+    /** Maximum number of LLM turns. Default: Infinity. */
+    maxTurns: number;
+    /** Maximum cost in USD. Default: Infinity. */
+    maxCost: number;
+}
+/**
+ * Tool category for microcompaction retention decisions.
+ * - rereadable: agent can re-read the source (files, directories)
+ * - non-reproducible: output may change or cost to re-fetch (web, APIs)
+ * - ephemeral: stale quickly, trivially re-runnable (ls, git status)
+ * - computational: small results from computations, non-reproducible without re-running
+ */
+export type ToolCategory = 'rereadable' | 'non-reproducible' | 'ephemeral' | 'computational';
+/**
+ * Microcompaction configuration: progressive tool result trimming.
+ */
+/**
+ * Callback invoked when microcompaction persists a cleared tool result to disk.
+ * The consumer implements the actual I/O and returns the file path.
+ *
+ * @param content - The full original tool result content
+ * @param metadata - Information about the result being persisted
+ * @returns The file path where the content was saved
+ */
+export type PersistResultFn = (content: string, metadata: {
+    toolName: string;
+    category: ToolCategory;
+    /** Present when called from the proactive tool execution interceptor. */
+    toolCallId?: string;
+    /** Present when called from compaction (reactive paths). */
+    messageIndex?: number;
+}) => Promise<string>;
+export interface MicrocompactionConfig {
+    /** Maximum tokens for a single tool result at insertion time. Default: 50000. */
+    maxResultTokens: number;
+    /**
+     * Minimum context utilization ratio below which L1 never trims, even when
+     * the cache is cold. Prevents pointless work on nearly empty contexts.
+     * Default: 0.25 (25%).
+     */
+    trimFloorRatio: number;
+    /**
+     * Absolute floor for the hot zone size (in tokens). Tool results within the
+     * hot zone of the most recent message are never trimmed. The effective hot
+     * zone is `max(hotZoneMinTokens, contextWindow * hotZoneRatio)`.
+     * Default: 16000.
+     */
+    hotZoneMinTokens: number;
+    /**
+     * Hot zone as a fraction of the context window. Wins over the floor on
+     * very large windows. Default: 0.05 (5%).
+     */
+    hotZoneRatio: number;
+    /**
+     * Multiplier applied to the hot zone for non-reproducible tools. When
+     * undefined, resolves to 1.0 if a persistResult callback is configured
+     * (full content recoverable from disk) or 1.5 if not (some buffer since
+     * content is lost on trim).
+     */
+    extendedRetentionMultiplier?: number;
+    /** Bookend size at the hot zone boundary (chars per side). Default: 2000. */
+    bookendMaxChars: number;
+    /** Bookend size at the far end of the degradation span (chars per side). Default: 256. */
+    bookendMinChars: number;
+    /**
+     * The degradation span as a fraction of the context window. Bookend size
+     * interpolates linearly from bookendMaxChars to bookendMinChars across this
+     * span. Beyond the span, results become placeholder or clear based on tool
+     * category. Default: 0.40 (40%).
+     */
+    degradationSpanRatio: number;
+    /** Tool name to category mapping. Unregistered tools default to standard retention. */
+    toolCategories?: Record<string, ToolCategory>;
+    /**
+     * Callback to persist tool results to disk before destructive trim actions
+     * (bookend, placeholder, clear). When set, the in-context replacement
+     * includes a file path reference the agent can Read to recover full content.
+     * Only fires for non-reproducible and computational tools.
+     *
+     * Typically set at the top-level CortexAgentConfig.persistResult and
+     * propagated here automatically.
+     */
+    persistResult?: PersistResultFn;
+    /** Maximum aggregate tokens for all tool results in a single turn. Default: 150000. */
+    maxAggregateTurnTokens?: number;
+}
+/**
+ * Conversation summarization (Layer 2) configuration.
+ */
+export interface CompactionConfig {
+    /** Context usage ratio that triggers summarization. Default: 0.70. */
+    threshold: number;
+    /** Number of recent turns preserved verbatim. Default: 6. */
+    preserveRecentTurns: number;
+    /** Custom summarization prompt. If provided, replaces the default prompt. */
+    customPrompt?: string;
+    /** Maximum Layer 2 retry attempts before falling through to Layer 3. Default: 3. */
+    maxRetries?: number;
+    /** Delay in ms between Layer 2 retry attempts. Default: 2000. */
+    retryDelayMs?: number;
+}
+/**
+ * Emergency truncation (Layer 3) configuration.
+ */
+export interface FailsafeConfig {
+    /** Context usage ratio that triggers emergency truncation. Default: 0.90. */
+    threshold: number;
+}
+/**
+ * Adaptive threshold configuration for Layer 2 compaction.
+ *
+ * Adjusts the compaction trigger point based on how recently the user last
+ * interacted. When the user is idle (no messages for a while), the threshold
+ * is lowered so compaction fires earlier, reducing token costs during interval
+ * ticks where the agent is thinking to itself.
+ *
+ * Three windows:
+ * - Recent (< recentWindowMs): no threshold reduction
+ * - Moderate (recentWindowMs .. idleWindowMs): moderateReduction applied
+ * - Idle (> idleWindowMs): idleReduction applied
+ *
+ * The effective threshold is: config.compaction.threshold - reduction
+ */
+export interface AdaptiveThresholdConfig {
+    /** Whether adaptive thresholds are enabled. Default: true. */
+    enabled: boolean;
+    /** Milliseconds within which interaction is considered "recent". Default: 300000 (5 min). */
+    recentWindowMs: number;
+    /** Milliseconds beyond which interaction is considered "idle". Default: 1800000 (30 min). */
+    idleWindowMs: number;
+    /** Threshold reduction when interaction is recent. Default: 0.0. */
+    recentReduction: number;
+    /** Threshold reduction when interaction is moderate. Default: 0.10. */
+    moderateReduction: number;
+    /** Threshold reduction when interaction is idle. Default: 0.20. */
+    idleReduction: number;
+}
+/**
+ * Full compaction configuration for CortexAgent.
+ *
+ * Supports two strategies:
+ * - `'observational'` (default): Observer/Reflector background compression
+ *   replaces L1 threshold trimming and L2 summarization. L3 emergency
+ *   truncation remains active as a safety valve.
+ * - `'classic'`: The existing L1 + L2 + L3 system operates unchanged.
+ *
+ * The failsafe (L3) is always active regardless of strategy.
+ */
+export interface CortexCompactionConfig {
+    /**
+     * Compaction strategy selection.
+     * - `'observational'`: Background observer/reflector compression (default).
+     * - `'classic'`: Traditional L1 microcompaction + L2 summarization.
+     * @default 'observational'
+     */
+    strategy?: 'observational' | 'classic';
+    /** Microcompaction (L1) configuration. Used when strategy is 'classic'. */
+    microcompaction: MicrocompactionConfig;
+    /** Conversation summarization (L2) configuration. Used when strategy is 'classic'. */
+    compaction: CompactionConfig;
+    /** Emergency truncation (L3) configuration. Always active regardless of strategy. */
+    failsafe: FailsafeConfig;
+    /** Adaptive threshold configuration. Adjusts Layer 2 trigger based on interaction recency. Used when strategy is 'classic'. */
+    adaptive: AdaptiveThresholdConfig;
+    /**
+     * Observational memory configuration. Used when strategy is 'observational'
+     * (or omitted, since observational is the default).
+     */
+    observational?: Partial<ObservationalMemoryConfig>;
+}
+/**
+ * Information about the compaction target passed to onBeforeCompaction.
+ */
+export interface CompactionTarget {
+    /** Number of turns that will be summarized. */
+    turnsToCompact: number;
+    /** Estimated tokens in the compaction target. */
+    estimatedTokens: number;
+}
+/**
+ * Result of a compaction operation.
+ */
+export interface CompactionResult {
+    /** Total tokens before compaction. */
+    tokensBefore: number;
+    /** Total tokens after compaction. */
+    tokensAfter: number;
+    /** Number of conversation turns that were compacted (summarized/removed). */
+    turnsCompacted: number;
+    /** Number of conversation turns preserved after compaction. */
+    turnsPreserved: number;
+    /** Token count of the generated summary. */
+    summaryTokens: number;
+    /**
+     * ISO timestamp of the oldest preserved turn, or null if no timestamp
+     * could be determined. The consumer (backend) should use
+     * `oldestPreservedIndex` to map back to a database timestamp when
+     * this is null.
+     */
+    oldestPreservedTimestamp: string | null;
+    /**
+     * Index of the oldest preserved turn in the original (pre-compaction)
+     * conversation history. The consumer can map this index back to a
+     * database timestamp via messages.db. Always present and accurate.
+     */
+    oldestPreservedIndex: number;
+    /** The generated summary text. */
+    summary: string;
+}
+/**
+ * Info passed to onCompactionDegraded when Layer 2 failed and Layer 3 was used.
+ */
+export interface CompactionDegradedInfo {
+    /** Number of consecutive Layer 2 failures (including this episode). */
+    layer2Failures: number;
+    /** Number of turns dropped by emergency truncation. */
+    turnsDropped: number;
+}
+/**
+ * Info passed to onCompactionExhausted when all compaction layers have failed.
+ */
+export interface CompactionExhaustedInfo {
+    /** The error from the last Layer 2 attempt. */
+    error: Error;
+    /** Number of consecutive Layer 2 failures. */
+    layer2Failures: number;
+}
+/**
+ * Event handlers emitted by CortexAgent during the agentic loop lifecycle.
+ */
+export interface CortexEvents {
+    /** Fired when the full agentic loop finishes (agent_end, not turn_end). */
+    onLoopComplete: () => void;
+    /** Fired before compaction starts. Awaited. Consumer should flush state. */
+    onBeforeCompaction: (target: CompactionTarget) => Promise<void>;
+    /** Fired after compaction completes. Consumer can re-seed messages, update state. */
+    onPostCompaction: (result: CompactionResult) => void;
+    /** Fired when context compaction fails. */
+    onCompactionError: (error: Error) => void;
+    /** Fired when Layer 2 compaction failed and Layer 3 (emergency truncation) was used as fallback. */
+    onCompactionDegraded: (info: CompactionDegradedInfo) => void;
+    /** Fired when all compaction layers have failed. Consumer should take recovery action. */
+    onCompactionExhausted: (info: CompactionExhaustedInfo) => void;
+    /** Fired when an error is classified during the agentic loop. */
+    onError: (error: ClassifiedError) => void;
+    /** Fired at the end of each turn with parsed working tag output. */
+    onTurnComplete: (output: AgentTextOutput) => void;
+    /** Fired when a sub-agent is spawned for delegated work. */
+    onSubAgentSpawned: (taskId: string, instructions: string, background: boolean) => void;
+    /** Fired when a sub-agent completes successfully. */
+    onSubAgentCompleted: (taskId: string, result: string, status: string, usage: unknown) => void;
+    /** Fired when a sub-agent fails. */
+    onSubAgentFailed: (taskId: string, error: string) => void;
+    /** Fired when observational memory activates (messages compressed and removed). Only fires when strategy is 'observational'. */
+    onObservation: (event: ObservationEvent) => void;
+    /** Fired when the reflector condenses observations. Only fires when strategy is 'observational'. */
+    onReflection: (event: ReflectionEvent) => void;
+}
+/**
+ * Transport configuration for connecting to an MCP server.
+ * Either stdio (spawn subprocess) or HTTP (connect to running server).
+ */
+export type McpTransportConfig = McpStdioConfig | McpHttpConfig;
+/**
+ * Stdio transport: spawn a subprocess and communicate via stdin/stdout.
+ */
+export interface McpStdioConfig {
+    transport: 'stdio';
+    /** The executable to run (e.g., 'node', '/path/to/tsx'). */
+    command: string;
+    /** Command line arguments. */
+    args?: string[];
+    /** Environment variables for the subprocess. */
+    env?: Record<string, string>;
+    /** Working directory for the subprocess. */
+    cwd?: string;
+}
+/**
+ * HTTP transport: connect to an already-running MCP server via Streamable HTTP.
+ */
+export interface McpHttpConfig {
+    transport: 'http';
+    /** The URL of the MCP server endpoint. */
+    url: string;
+    /** Optional HTTP headers (e.g., for authentication). */
+    headers?: Record<string, string>;
+}
+/**
+ * State of a single MCP server connection.
+ */
+export interface McpConnectionState {
+    /** The server name used for namespacing tools. */
+    serverName: string;
+    /** Transport configuration used for this connection. */
+    config: McpTransportConfig;
+    /** Whether the connection is currently active. */
+    connected: boolean;
+    /** Number of reconnect attempts since last successful connection. */
+    reconnectAttempts: number;
+    /** Names of tools discovered from this server (namespaced). */
+    toolNames: string[];
+}
+/**
+ * Default utility model mapping per provider.
+ * Keys are provider names, values are model IDs.
+ */
+export interface UtilityModelDefaults {
+    [provider: string]: string;
+}
+/**
+ * Configuration for registering a skill with the SkillRegistry.
+ * The consumer provides these at startup and dynamically as plugins install/uninstall.
+ */
+export interface SkillConfig {
+    /** Absolute path to the SKILL.md file. */
+    path: string;
+    /** Where this skill came from. Used for display and debugging. */
+    source: string;
+    /**
+     * Per-skill variables for ${VAR} substitution in the SKILL.md body.
+     * Merged into the preprocessor variables when getSkillBody() runs.
+     * Useful for plugin skills that reference ${PLUGIN_ROOT}.
+     */
+    variables?: Record<string, string>;
+}
+/**
+ * Internal skill index entry built from parsing a SKILL.md file.
+ */
+export interface SkillEntry {
+    /** Skill name from frontmatter (kebab-case). */
+    name: string;
+    /** Skill description from frontmatter (for agent activation). */
+    description: string;
+    /** Absolute path to the SKILL.md file. */
+    path: string;
+    /** Absolute path to the skill directory (parent of SKILL.md). */
+    dir: string;
+    /** Source identifier from SkillConfig. */
+    source: string;
+    /** Full parsed YAML frontmatter (preserved for forward compatibility). */
+    frontmatter: Record<string, unknown>;
+    /** Whether the agent can auto-load this skill. Derived from disable-model-invocation. */
+    modelInvocable: boolean;
+    /** Per-skill variables for ${VAR} substitution. */
+    variables?: Record<string, string>;
+}
+/**
+ * A loaded skill in the skill buffer (preprocessed body ready for injection).
+ */
+export interface LoadedSkill {
+    /** The skill name. */
+    name: string;
+    /** The preprocessed SKILL.md body content. */
+    content: string;
+}
+/**
+ * Context object passed to skill preprocessor scripts (!{script: path}).
+ * Cortex owns the built-in fields; the consumer provides everything else.
+ */
+export interface CortexScriptContext {
+    /** Absolute path to the skill's directory. */
+    skillDir: string;
+    /** Arguments passed to the skill (split by whitespace). */
+    args: string[];
+    /** Raw arguments string. */
+    rawArgs: string;
+    /** Additional key-value pairs from !{script: path, key: value} syntax. */
+    scriptArgs: Record<string, string>;
+    /** Consumer-provided context fields (Cortex does not inspect these). */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for spawning a sub-agent via the SubAgent tool.
+ */
+export interface SubAgentSpawnConfig {
+    /** What the sub-agent should do. Becomes the initial prompt. */
+    instructions: string;
+    /** Tool names to make available. Default: inherits parent's tools. */
+    tools?: string[];
+    /** Custom system prompt. Default: inherits parent's system prompt. */
+    systemPrompt?: string;
+    /** Maximum LLM turns. Default: inherits parent's budget guard config. */
+    maxTurns?: number;
+    /** Maximum cost in USD. Default: inherits parent's budget guard config. */
+    maxCost?: number;
+    /** Run asynchronously. Default: false (blocks until complete). */
+    background?: boolean;
+}
+/**
+ * Result returned by a completed sub-agent.
+ */
+export interface SubAgentResult {
+    /** The sub-agent's final text output. */
+    output: string;
+    /** Completion status. */
+    status: 'completed' | 'failed' | 'timed_out' | 'cancelled';
+    /** Usage summary. */
+    usage: {
+        turns: number;
+        cost: number;
+        durationMs: number;
+        contextTokens: number;
+    };
+    /** Summary of tool calls made by the sub-agent (extracted from conversation history on completion). */
+    toolCalls?: Array<{
+        name: string;
+        durationMs: number;
+        error?: string;
+    }>;
+}
+/**
+ * Tracked sub-agent record managed by SubAgentManager.
+ */
+export interface TrackedSubAgent {
+    /** Unique task identifier. */
+    taskId: string;
+    /** The sub-agent CortexAgent instance. */
+    agent: unknown;
+    /** The instructions the sub-agent was spawned with. */
+    instructions: string;
+    /** Whether this is a background sub-agent. */
+    background: boolean;
+    /** Spawn timestamp. */
+    spawnedAt: number;
+    /** Promise that resolves when the sub-agent completes. */
+    completion: Promise<SubAgentResult>;
+    /** Resolve function for the completion promise. */
+    resolve: (result: SubAgentResult) => void;
+    /** Number of tool calls executed so far. */
+    toolCount: number;
+    /** Name of the most recently started tool. */
+    lastToolName: string | null;
+    /** Summary/args of the most recently started tool. */
+    lastToolSummary: string | null;
+    /** Timestamp when the most recent tool started. */
+    lastToolStartedAt: number | null;
+    /** Set while the sub-agent is blocked awaiting a permission decision. */
+    pendingPermission: {
+        toolName: string;
+        args: unknown;
+    } | null;
+}
+//# sourceMappingURL=types.d.ts.map