@corbat-tech/coco 2.34.0 → 2.36.0

package/dist/index.d.ts

@@ -503,6 +503,7 @@ declare const CocoConfigSchema: z.ZodObject<{
             "kimi-code": "kimi-code";
             lmstudio: "lmstudio";
             codex: "codex";
+            vertex: "vertex";
             copilot: "copilot";
             groq: "groq";
             openrouter: "openrouter";
@@ -511,7 +512,6 @@ declare const CocoConfigSchema: z.ZodObject<{
             together: "together";
             huggingface: "huggingface";
             qwen: "qwen";
-            vertex: "vertex";
             ollama: "ollama";
         }>>;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -957,6 +957,10 @@ type ProjectType = "cli" | "api" | "web_app" | "library" | "service" | "full_sta
 type ThinkingMode = "off" | "auto" | "low" | "medium" | "high" | {
     budget: number;
 };
+/**
+ * Whether this provider/model uses effort buckets (OpenAI) or token budgets (Anthropic, Gemini).
+ */
+type ThinkingKind = "effort" | "budget";
 
 /**
  * LLM Provider types for Corbat-Coco
@@ -3136,6 +3140,75 @@ declare class TaskError extends CocoError {
     });
 }
 
+/**
+ * Provider and model catalog.
+ *
+ * This is the source of truth for model IDs, defaults, context windows,
+ * pricing metadata, and provider capabilities. Endpoint adapters still own
+ * request/response conversion, but they should read model metadata from here.
+ */
+
+type ModelStatus = "current" | "legacy" | "deprecated" | "experimental";
+type ModelCapability = "streaming" | "tool-use" | "vision" | "reasoning-effort" | "adaptive-thinking" | "thinking-budget" | "openai-responses" | "openai-chat" | "anthropic-messages" | "gemini-generate-content";
+interface ProviderSource {
+    name: string;
+    url: string;
+    verifiedAt: string;
+}
+interface ModelPricing {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}
+interface ModelCatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    contextWindow: number;
+    maxOutputTokens?: number;
+    recommended?: boolean;
+    status: ModelStatus;
+    capabilities: ModelCapability[];
+    pricing?: ModelPricing;
+    source: ProviderSource;
+}
+interface ProviderCatalogEntry {
+    id: ProviderType;
+    defaultModel: string;
+    models: ModelCatalogEntry[];
+}
+
+/**
+ * Runtime compatibility view derived from the static provider catalog.
+ *
+ * The catalog records what a model is; this module records how Coco should use it
+ * safely at runtime, including endpoint selection and reasoning/tooling limits.
+ */
+
+type ProviderEndpointStrategy = "anthropic-messages" | "openai-responses" | "openai-chat" | "gemini-generate-content";
+type ModelCompatibilityStatus = ModelStatus | "unverified";
+interface ProviderRuntimeCapability {
+    provider: ProviderType;
+    model: string;
+    catalogModel?: ModelCatalogEntry;
+    status: ModelCompatibilityStatus;
+    endpoint: ProviderEndpointStrategy;
+    supportsStreaming: boolean;
+    supportsToolUse: boolean;
+    supportsVision: boolean;
+    supportsReasoning: boolean;
+    reasoningKinds: ThinkingKind[];
+    defaultReasoning: ThinkingMode;
+    contextWindow: number;
+    maxOutputTokens?: number;
+    sourceUrl?: string;
+    restrictions: string[];
+}
+interface ProviderProbeResult extends ProviderRuntimeCapability {
+    available: boolean | "not-checked";
+    checkedAt: string;
+    error?: string;
+}
+
 /**
  * Provider exports for Corbat-Coco
  */
@@ -3149,6 +3222,1006 @@ type ProviderType = "anthropic" | "openai" | "codex" | "copilot" | "gemini" | "v
  */
 declare function createProvider(type: ProviderType, config?: ProviderConfig): Promise<LLMProvider>;
 
+/**
+ * Agent mode registry.
+ *
+ * Modes describe the intended control flow for a turn without changing the
+ * provider interface. The REPL can route prompts, tools, and confirmations
+ * through these definitions while keeping compatibility with existing plan
+ * mode and quality loop behavior.
+ */
+type AgentModeId = "ask" | "plan" | "build" | "debug" | "review" | "architect";
+interface AgentModeDefinition {
+    id: AgentModeId;
+    label: string;
+    description: string;
+    readOnly: boolean;
+    preferredTools: string[];
+    requiresVerification: boolean;
+}
+
+/**
+ * Context window manager for automatic token tracking
+ * Monitors token usage and triggers compaction when threshold is exceeded
+ */
+/**
+ * Configuration for the context manager
+ */
+interface ContextManagerConfig {
+    /** Maximum tokens available (from provider.getContextWindow()) */
+    maxTokens: number;
+    /** Threshold percentage (0-1) at which to trigger compaction (default 0.8 = 80%) */
+    compactionThreshold: number;
+    /** Tokens reserved for response generation (default 4096) */
+    reservedTokens: number;
+}
+/**
+ * Context usage statistics
+ */
+interface ContextUsageStats {
+    /** Tokens currently used */
+    used: number;
+    /** Tokens available for use (excluding reserved) */
+    available: number;
+    /** Total capacity */
+    total: number;
+    /** Usage percentage (0-100) */
+    percentage: number;
+    /** Whether compaction is recommended */
+    shouldCompact: boolean;
+}
+/**
+ * Manages context window usage and determines when compaction is needed
+ */
+declare class ContextManager {
+    private usedTokens;
+    private config;
+    constructor(config?: Partial<ContextManagerConfig>);
+    /**
+     * Add tokens to the usage counter
+     */
+    addTokens(count: number): void;
+    /**
+     * Remove tokens from the usage counter
+     */
+    removeTokens(count: number): void;
+    /**
+     * Set the used token count directly
+     */
+    setUsedTokens(count: number): void;
+    /**
+     * Get the number of tokens currently used
+     */
+    getUsedTokens(): number;
+    /**
+     * Get the number of tokens available (excluding reserved)
+     */
+    getAvailableTokens(): number;
+    /**
+     * Get usage percentage (0-100)
+     */
+    getUsagePercent(): number;
+    /**
+     * Check if compaction should be triggered
+     */
+    shouldCompact(): boolean;
+    /**
+     * Get full usage statistics
+     */
+    getUsageStats(): ContextUsageStats;
+    /**
+     * Reset the token counter
+     */
+    reset(): void;
+    /**
+     * Update configuration (e.g., when switching providers/models)
+     */
+    updateConfig(config: Partial<ContextManagerConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): ContextManagerConfig;
+    /**
+     * Format usage for display
+     */
+    formatUsage(): string;
+}
+
+/**
+ * Progress Tracking Types
+ *
+ * Types for TodoWrite-like progress tracking in the REPL.
+ */
+/**
+ * Status of a todo item
+ */
+type TodoStatus = "pending" | "in_progress" | "completed" | "failed";
+/**
+ * A single todo item for tracking progress
+ */
+interface TodoItem {
+    /** Unique identifier for the todo */
+    id: string;
+    /** Description of what needs to be done (imperative form) */
+    content: string;
+    /** Present tense description shown during execution */
+    activeForm: string;
+    /** Current status of the todo */
+    status: TodoStatus;
+    /** ISO timestamp when the todo was created */
+    createdAt: string;
+    /** ISO timestamp when the todo was last updated */
+    updatedAt: string;
+    /** Parent todo ID for nested todos */
+    parentId?: string;
+}
+/**
+ * Serializable progress state
+ */
+interface ProgressState {
+    /** List of all todos */
+    todos: TodoItem[];
+    /** ID of the currently active task */
+    currentTask?: string;
+}
+/**
+ * Progress statistics
+ */
+interface ProgressStats {
+    /** Total number of todos */
+    total: number;
+    /** Number of pending todos */
+    pending: number;
+    /** Number of in-progress todos */
+    inProgress: number;
+    /** Number of completed todos */
+    completed: number;
+    /** Number of failed todos */
+    failed: number;
+    /** Completion percentage (0-100) */
+    completionPercent: number;
+}
+
+/**
+ * Progress Tracker
+ *
+ * Manages todo items for tracking task progress in the REPL.
+ */
+
+/**
+ * Tracks progress of tasks via a todo list
+ */
+declare class ProgressTracker {
+    private todos;
+    private currentTaskId?;
+    /**
+     * Create a new progress tracker
+     * @param initialState Optional initial state to restore from
+     */
+    constructor(initialState?: ProgressState);
+    /**
+     * Add a new todo item
+     * @param content Description of what needs to be done (imperative form)
+     * @param activeForm Present tense description shown during execution
+     * @param parentId Optional parent todo ID for nested todos
+     * @returns The created todo item
+     */
+    addTodo(content: string, activeForm: string, parentId?: string): TodoItem;
+    /**
+     * Add multiple todos at once
+     * @param items Array of { content, activeForm, parentId } objects
+     * @returns Array of created todo items
+     */
+    addTodos(items: Array<{
+        content: string;
+        activeForm: string;
+        parentId?: string;
+    }>): TodoItem[];
+    /**
+     * Update the status of a todo
+     * @param id Todo ID
+     * @param status New status
+     * @throws Error if todo not found
+     */
+    updateStatus(id: string, status: TodoStatus): void;
+    /**
+     * Start a todo (set to in_progress)
+     * @param id Todo ID
+     */
+    startTodo(id: string): void;
+    /**
+     * Complete a todo
+     * @param id Todo ID
+     */
+    completeTodo(id: string): void;
+    /**
+     * Mark a todo as failed
+     * @param id Todo ID
+     */
+    failTodo(id: string): void;
+    /**
+     * Get a todo by ID
+     * @param id Todo ID
+     * @returns The todo item or undefined
+     */
+    getTodo(id: string): TodoItem | undefined;
+    /**
+     * Get all todos
+     * @returns Array of all todo items
+     */
+    getTodos(): TodoItem[];
+    /**
+     * Get todos filtered by status
+     * @param status Status to filter by
+     * @returns Array of matching todo items
+     */
+    getTodosByStatus(status: TodoStatus): TodoItem[];
+    /**
+     * Get child todos of a parent
+     * @param parentId Parent todo ID
+     * @returns Array of child todo items
+     */
+    getChildTodos(parentId: string): TodoItem[];
+    /**
+     * Get the currently in-progress task
+     * @returns The current task or undefined
+     */
+    getCurrentTask(): TodoItem | undefined;
+    /**
+     * Get progress statistics
+     * @returns Progress stats object
+     */
+    getStats(): ProgressStats;
+    /**
+     * Remove a todo
+     * @param id Todo ID
+     * @returns true if removed, false if not found
+     */
+    removeTodo(id: string): boolean;
+    /**
+     * Clear all todos
+     */
+    clear(): void;
+    /**
+     * Check if there are any todos
+     * @returns true if there are todos
+     */
+    hasTodos(): boolean;
+    /**
+     * Check if all todos are completed
+     * @returns true if all todos are completed (or no todos exist)
+     */
+    isComplete(): boolean;
+    /**
+     * Format progress for display
+     * @returns Formatted progress string
+     */
+    formatProgress(): string;
+    /**
+     * Serialize to JSON
+     * @returns Serializable progress state
+     */
+    toJSON(): ProgressState;
+    /**
+     * Restore from JSON state
+     * @param state Progress state to restore
+     */
+    fromJSON(state: ProgressState): void;
+}
+
+/**
+ * Memory source level indicating where a memory file originates.
+ *
+ * The levels form a hierarchy with increasing specificity:
+ * - `user`: Global user preferences (~/.coco/COCO.md)
+ * - `project`: Project-specific instructions (./COCO.md, committed to repo)
+ * - `directory`: Subdirectory-specific instructions (e.g., src/api/COCO.md)
+ * - `local`: Personal overrides (./COCO.local.md, gitignored)
+ *
+ * Higher specificity levels override lower ones when conflicts occur.
+ * Directory-level files are collected from all directories between project root
+ * and the current working directory, with closer directories taking precedence.
+ */
+type MemoryLevel = "user" | "project" | "directory" | "local";
+/**
+ * Represents a parsed section within a memory file.
+ *
+ * Sections are delimited by markdown headings (## heading).
+ * Each section contains instructions or configuration for a specific topic.
+ *
+ * @example
+ * ```typescript
+ * const section: MemorySection = {
+ *   title: "Code Style",
+ *   content: "- Use 2-space indentation\n- Prefer const over let",
+ *   startLine: 10,
+ *   endLine: 15
+ * };
+ * ```
+ */
+interface MemorySection {
+    /**
+     * Section title extracted from the heading.
+     * The leading ## and any trailing whitespace are stripped.
+     */
+    title: string;
+    /**
+     * Raw markdown content of the section, excluding the heading line.
+     * Preserves original formatting including code blocks and lists.
+     */
+    content: string;
+    /**
+     * 1-based line number where the section heading appears.
+     */
+    startLine: number;
+    /**
+     * 1-based line number of the last line of the section content.
+     * This is the line before the next heading or end of file.
+     */
+    endLine: number;
+}
+/**
+ * Represents an import directive that references external content.
+ *
+ * Imports use the @path/to/file syntax to include content from other files.
+ * This allows modularizing memory across multiple files.
+ *
+ * @example
+ * ```typescript
+ * const memoryImport: MemoryImport = {
+ *   originalPath: "@./docs/style-guide.md",
+ *   resolvedPath: "/project/docs/style-guide.md",
+ *   resolved: true,
+ *   line: 5,
+ *   content: "# Style Guide\n..."
+ * };
+ * ```
+ */
+interface MemoryImport {
+    /**
+     * Original import path as written in the memory file.
+     * Includes the @ prefix.
+     *
+     * @example "@./docs/conventions.md"
+     */
+    originalPath: string;
+    /**
+     * Fully resolved absolute path to the imported file.
+     * Resolved relative to the containing memory file's directory.
+     */
+    resolvedPath: string;
+    /**
+     * Whether the import was successfully resolved and loaded.
+     * False if the file doesn't exist or couldn't be read.
+     */
+    resolved: boolean;
+    /**
+     * 1-based line number where the import directive appears.
+     */
+    line: number;
+    /**
+     * Content of the imported file, if successfully resolved.
+     * Undefined if the import failed.
+     */
+    content?: string;
+    /**
+     * Error message if the import failed to resolve.
+     * Provides details about why the import couldn't be loaded.
+     */
+    error?: string;
+}
+/**
+ * Represents a single memory file with its parsed content.
+ *
+ * Memory files are markdown documents containing instructions, preferences,
+ * and configuration for the AI assistant. They can include sections
+ * organized by headings and import other files.
+ *
+ * @example
+ * ```typescript
+ * const memoryFile: MemoryFile = {
+ *   path: "/project/COCO.md",
+ *   level: "project",
+ *   content: "# Project Memory\n\n## Code Style\n...",
+ *   sections: [...],
+ *   imports: [...],
+ *   modifiedAt: new Date("2024-01-15"),
+ *   exists: true
+ * };
+ * ```
+ */
+interface MemoryFile {
+    /**
+     * Absolute path to the memory file on the filesystem.
+     */
+    path: string;
+    /**
+     * Source level indicating the origin of this memory file.
+     * Determines precedence when merging multiple memory sources.
+     */
+    level: MemoryLevel;
+    /**
+     * Processed content of the memory file (after import resolution).
+     * Empty string if the file doesn't exist.
+     */
+    content: string;
+    /**
+     * Parsed sections extracted from the file content.
+     * Each section corresponds to a ## heading and its content.
+     */
+    sections: MemorySection[];
+    /**
+     * Import directives found in the file and their resolution status.
+     * Includes both successful and failed imports.
+     */
+    imports: MemoryImport[];
+    /**
+     * Timestamp when the file was last modified.
+     * Used for cache invalidation and change detection.
+     */
+    modifiedAt: Date;
+    /**
+     * Whether the memory file exists on disk.
+     * False for expected but missing memory files.
+     */
+    exists: boolean;
+}
+/**
+ * Represents an error that occurred while loading or parsing memory.
+ *
+ * Errors can be recoverable (warnings) or fatal (blocking).
+ * Recoverable errors allow the system to continue with partial memory.
+ *
+ * @example
+ * ```typescript
+ * const error: MemoryError = {
+ *   file: "/project/COCO.md",
+ *   level: "project",
+ *   error: "Circular import detected: ./a.md -> ./b.md -> ./a.md",
+ *   recoverable: true
+ * };
+ * ```
+ */
+interface MemoryError {
+    /**
+     * Path to the file where the error occurred.
+     * May be the memory file itself or an imported file.
+     */
+    file: string;
+    /**
+     * Memory level of the file that caused the error.
+     */
+    level: MemoryLevel;
+    /**
+     * Human-readable description of the error.
+     */
+    error: string;
+    /**
+     * Whether the system can continue despite this error.
+     *
+     * - `true`: Warning - the system can proceed with partial memory
+     * - `false`: Fatal - the memory loading process should abort
+     */
+    recoverable: boolean;
+}
+/**
+ * Combined memory context for a session, aggregating all memory sources.
+ *
+ * This is the primary interface used by the REPL and other components
+ * to access the merged memory from all levels.
+ *
+ * @example
+ * ```typescript
+ * const context: MemoryContext = {
+ *   files: [userMemory, projectMemory, localMemory],
+ *   combinedContent: "# User Memory\n...\n# Project Memory\n...",
+ *   totalSize: 15420,
+ *   errors: []
+ * };
+ * ```
+ */
+interface MemoryContext {
+    /**
+     * All loaded memory files, in order of precedence.
+     * Includes files that don't exist (with exists: false).
+     */
+    files: MemoryFile[];
+    /**
+     * Combined content from all memory files, ready for use in prompts.
+     *
+     * The content is merged with clear delimiters between sources.
+     * Later sources (higher precedence) appear after earlier ones.
+     */
+    combinedContent: string;
+    /**
+     * Total size of the combined content in characters.
+     * Used for enforcing size limits and estimating token usage.
+     */
+    totalSize: number;
+    /**
+     * All errors encountered during memory loading.
+     * Includes both recoverable warnings and fatal errors.
+     */
+    errors: MemoryError[];
+}
+
+/**
+ * Stack Detector for REPL Context Enrichment
+ *
+ * Detects project technology stack at REPL startup to enrich LLM context.
+ * Prevents COCO from suggesting incompatible technologies (e.g., npm in Java projects).
+ */
+type ProjectStack = "node" | "java" | "python" | "go" | "rust" | "unknown";
+interface ProjectStackContext {
+    /** Primary language/runtime */
+    stack: ProjectStack;
+    /** Package manager (npm, pnpm, yarn, maven, gradle, cargo, pip, go) */
+    packageManager: string | null;
+    /** Key dependencies (name → version) */
+    dependencies: Record<string, string>;
+    /** Inferred frameworks (e.g., ["Spring Boot", "React", "FastAPI"]) */
+    frameworks: string[];
+    /** Build tools detected (e.g., ["gradle", "webpack", "vite"]) */
+    buildTools: string[];
+    /** Testing frameworks (e.g., ["junit", "vitest", "pytest"]) */
+    testingFrameworks: string[];
+    /** Languages detected (e.g., ["TypeScript", "Java", "Python"]) */
+    languages: string[];
+}
+
+/**
+ * Unified Skill Types for Corbat-Coco
+ *
+ * Supports two kinds of skills:
+ * - Markdown (SKILL.md): Industry-standard format from skills.sh, injected into LLM system prompt
+ * - Native (TypeScript): Executable skills like /ship with deep runtime integration
+ */
+
+/** Where a skill was discovered */
+type SkillScope = "builtin" | "global" | "project";
+/** Two fundamental skill types */
+type SkillKind = "markdown" | "native";
+/** Extended categories (superset of existing REPL SkillCategory) */
+type SkillCategory = "general" | "git" | "model" | "coco" | "debug" | "custom" | "coding" | "testing" | "deployment" | "documentation" | "workflow";
+/** Skill execution risk level for routing and confirmation policy. */
+type SkillRisk = "read-only" | "write" | "network" | "destructive" | "secrets-sensitive";
+/** Agent surfaces a skill is known to support. */
+type SupportedAgentSurface = "coco" | "claude" | "codex" | "gemini" | "opencode";
+/** Lightweight skill descriptor (~50 tokens each, loaded at startup) */
+interface SkillMetadata {
+    /** Unique identifier (derived from name, kebab-case) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description -- used for semantic matching */
+    description: string;
+    /** Source repository or origin (e.g., "anthropics/skills", "local") */
+    source?: string;
+    /** Namespace prefix (derived from source directory structure) */
+    namespace?: string;
+    /** Version */
+    version: string;
+    /** Category for organization */
+    category: SkillCategory;
+    /** Kind of skill */
+    kind: SkillKind;
+    /** Where this skill was found */
+    scope: SkillScope;
+    /** Filesystem path to the skill root */
+    path: string;
+    /** Optional aliases for slash-command invocation */
+    aliases?: string[];
+    /** Optional glob patterns for auto-activation */
+    globs?: string[];
+    /** Tags for discovery */
+    tags?: string[];
+    /** Author information */
+    author?: string;
+    /** If true, this skill should NOT be auto-activated by the matcher */
+    disableModelInvocation?: boolean;
+    /** Tools this skill is allowed to use */
+    allowedTools?: string[];
+    /** Argument hint for CLI autocomplete */
+    argumentHint?: string;
+    /** Environment compatibility notes */
+    compatibility?: string;
+    /** Keyword triggers for explicit or automatic routing */
+    triggers?: string[];
+    /** Risk policy for confirmation/tool routing */
+    risk?: SkillRisk;
+    /** Agent surfaces this skill is intended to work with */
+    supportedAgents?: SupportedAgentSurface[];
+    /** Model override for this skill */
+    model?: string;
+    /** Execution context */
+    context?: "fork" | "agent" | "inline";
+}
+/** Fully loaded markdown skill content */
+interface MarkdownSkillContent {
+    /** The full markdown instructions */
+    instructions: string;
+    /** Paths to reference files, if any */
+    references: string[];
+    /** Paths to script files, if any */
+    scripts: string[];
+    /** Paths to template files, if any */
+    templates: string[];
+}
+/** Fully loaded native skill content */
+interface NativeSkillContent {
+    /** The execute function */
+    execute: (args: string, context: SkillExecutionContext) => Promise<SkillExecutionResult>;
+}
+/** Union of loaded skill content */
+type SkillContent = MarkdownSkillContent | NativeSkillContent;
+/** A skill with content loaded */
+interface LoadedSkill {
+    metadata: SkillMetadata;
+    content: SkillContent;
+}
+/** Context for skill execution */
+interface SkillExecutionContext {
+    cwd: string;
+    session?: unknown;
+    provider?: unknown;
+    config?: unknown;
+}
+/** Result of skill execution */
+interface SkillExecutionResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    shouldExit?: boolean;
+    /** If true, the output should be run as a subagent prompt (for context: fork/agent skills) */
+    shouldFork?: boolean;
+}
+/** Result of matching user input against available skills */
+interface SkillMatch {
+    skill: SkillMetadata;
+    /** Relevance score 0-1 */
+    score: number;
+    /** Why this skill matched */
+    reason: string;
+}
+
+/**
+ * TypeScript Native Skill Loader
+ *
+ * Adapts existing native Skill objects (from the REPL skills system)
+ * into the unified skill type system. This is a thin wrapper that
+ * converts existing skills without requiring changes to their code.
+ */
+
+/** The existing REPL Skill interface (duplicated here to avoid circular deps) */
+interface LegacySkill {
+    name: string;
+    description: string;
+    usage?: string;
+    aliases?: string[];
+    category?: string;
+    execute: (args: string, context: unknown) => Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+        shouldExit?: boolean;
+    }>;
+}
+
+/**
+ * Unified Skill Registry
+ *
+ * Central registry supporting both markdown (SKILL.md) and native (TypeScript) skills.
+ * Metadata is loaded eagerly at startup; full content is loaded lazily on demand.
+ */
+
+/** Skill lifecycle events */
+type SkillEvent = {
+    type: "activated";
+    skillId: string;
+} | {
+    type: "deactivated";
+    skillId: string;
+} | {
+    type: "executed";
+    skillId: string;
+    success: boolean;
+} | {
+    type: "discovered";
+    count: number;
+};
+type SkillEventListener = (event: SkillEvent) => void;
+/** Skills configuration (mirrors SkillsConfigSchema from config/schema.ts) */
+interface SkillsRuntimeConfig {
+    enabled?: boolean;
+    globalDir?: string;
+    globalDirs?: string[];
+    projectDir?: string;
+    projectDirs?: string[];
+    autoActivate?: boolean;
+    maxActiveSkills?: number;
+    disabled?: string[];
+}
+declare class UnifiedSkillRegistry {
+    /** Skill metadata indexed by ID (loaded eagerly) */
+    private metadata;
+    /** Alias -> skill ID mapping */
+    private aliases;
+    /** Cached loaded skills (loaded lazily) */
+    private loadedCache;
+    /** Currently active markdown skill IDs (injected into system prompt) */
+    private activeSkillIds;
+    /** Event listeners for skill lifecycle events */
+    private listeners;
+    /** Runtime configuration from CocoConfig.skills */
+    private _config;
+    /**
+     * Set runtime configuration for skills behavior
+     */
+    setConfig(config: SkillsRuntimeConfig): void;
+    /** Get current configuration (read-only) */
+    get config(): Readonly<SkillsRuntimeConfig>;
+    /** Subscribe to skill lifecycle events. Returns an unsubscribe function. */
+    on(listener: SkillEventListener): () => void;
+    private emit;
+    /**
+     * Discover and register all skills across all scopes
+     */
+    discoverAndRegister(projectPath: string, builtinSkills?: LegacySkill[], globalDir?: string): Promise<void>;
+    /**
+     * Register skill metadata (and its aliases)
+     */
+    registerMetadata(meta: SkillMetadata): void;
+    /** Get metadata by ID or alias */
+    getMetadata(idOrAlias: string): SkillMetadata | undefined;
+    /** Check if a skill exists */
+    has(idOrAlias: string): boolean;
+    /** Get all skill metadata */
+    getAllMetadata(): SkillMetadata[];
+    /** Get skills by category */
+    getByCategory(category: SkillCategory): SkillMetadata[];
+    /** Get skills by scope */
+    getByScope(scope: SkillScope): SkillMetadata[];
+    /** Get total skill count */
+    get size(): number;
+    /**
+     * Load full skill content by ID (cached)
+     */
+    loadSkill(id: string): Promise<LoadedSkill | null>;
+    /**
+     * Activate a markdown skill (loads content and marks as active)
+     *
+     * Respects maxActiveSkills config: if limit would be exceeded,
+     * the oldest active skill (FIFO) is deactivated to make room.
+     */
+    activateSkill(id: string): Promise<boolean>;
+    /** Deactivate a skill */
+    deactivateSkill(id: string): void;
+    /** Deactivate all skills */
+    deactivateAll(): void;
+    /** Get all currently active loaded skills */
+    getActiveSkills(): LoadedSkill[];
+    /** Get active skill IDs */
+    getActiveSkillIds(): string[];
+    /**
+     * Execute a skill by ID or alias
+     */
+    execute(idOrAlias: string, args: string, context: SkillExecutionContext): Promise<SkillExecutionResult>;
+    /**
+     * Find skills relevant to a user message
+     */
+    findRelevantSkills(userMessage: string, maxResults?: number, minScore?: number): SkillMatch[];
+}
+
+/**
+ * REPL types for Corbat-Coco
+ */
+
+/**
+ * REPL session state
+ */
+interface ReplSession {
+    id: string;
+    startedAt: Date;
+    messages: Message[];
+    projectPath: string;
+    config: ReplConfig;
+    /** Tools trusted for this session (skip confirmation) */
+    trustedTools: Set<string>;
+    /** Context window manager for tracking token usage */
+    contextManager?: ContextManager;
+    /** Progress tracker for todo-like task tracking */
+    progressTracker?: ProgressTracker;
+    /** Memory context from COCO.md/CLAUDE.md files */
+    memoryContext?: MemoryContext;
+    /** Project stack context (detected at startup) */
+    projectContext?: ProjectStackContext;
+    /** Unified skill registry (markdown + native skills) */
+    skillRegistry?: UnifiedSkillRegistry;
+    /** Last arguments passed to a skill (for $ARGUMENTS substitution) */
+    lastSkillArguments?: string;
+    /** Plan mode: restricts agent to read-only tools for planning */
+    planMode?: boolean;
+    /** Pending plan text awaiting user approval */
+    pendingPlan?: string | null;
+    /** Active workflow mode controlling prompts, tool access, and UX hints */
+    agentMode?: AgentModeId;
+    /** Reusable runtime facade for provider/tools/permissions/observability */
+    runtime?: AgentRuntime;
+}
+/**
+ * REPL configuration
+ */
+interface ReplConfig {
+    provider: {
+        type: ProviderType;
+        model: string;
+        maxTokens: number;
+        project?: string;
+        location?: string;
+        /** Active thinking/reasoning mode (undefined = not supported or use model default) */
+        thinking?: ThinkingMode;
+        /** Optional cheap model for background tasks (compaction, summarization) */
+        weakModel?: string;
+        /** Optional cheap model for file write/edit operations (architect/editor split) */
+        editorModel?: string;
+    };
+    ui: {
+        theme: "dark" | "light" | "auto";
+        showTimestamps: boolean;
+        maxHistorySize: number;
+        /** When to show diff after file modifications */
+        showDiff: "never" | "on_request" | "on_complete" | "always";
+    };
+    agent: {
+        systemPrompt: string;
+        maxToolIterations: number;
+        confirmDestructive: boolean;
+        /** If true, Coco may switch provider automatically after repeated provider failures */
+        enableAutoSwitchProvider?: boolean;
+        /** Enables bounded stream/provider recovery retries inside the agent loop */
+        recoveryV2?: boolean;
+        /** Enforces stricter read-only guarantees while plan mode is active */
+        planModeStrict?: boolean;
+        /** Enables the expanded read-only doctor diagnostics command */
+        doctorV2?: boolean;
+        /** Enables output offload instrumentation without changing context behavior */
+        outputOffload?: boolean;
+    };
+}
+
+/**
+ * Session persistence types for Corbat-Coco
+ *
+ * This module defines types for persisting and resuming REPL sessions,
+ * allowing users to continue work after restarts or interruptions.
+ */
+
+/**
+ * Session status indicating the state when the session was last saved
+ */
+type SessionStatus = "active" | "completed" | "interrupted" | "error";
+/**
+ * Persisted session metadata for quick listing and resumption
+ */
+interface PersistedSession {
+    /** Unique session identifier */
+    id: string;
+    /** Project path where session was created */
+    projectPath: string;
+    /** When the session started */
+    startedAt: Date;
+    /** When the session was last saved */
+    lastSavedAt: Date;
+    /** Session configuration */
+    config: ReplConfig;
+    /** Message count (for quick display without loading full conversation) */
+    messageCount: number;
+    /** Total tokens used during the session */
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    /** Human-readable title/summary of the session */
+    title?: string;
+    /** Whether session completed normally or was interrupted */
+    status: SessionStatus;
+}
+/**
+ * Session storage interface for persistence operations
+ */
+interface SessionStorage {
+    /**
+     * Save a session to disk
+     * @param session - The REPL session to persist
+     */
+    save(session: ReplSession): Promise<void>;
+    /**
+     * Load a session from disk
+     * @param sessionId - The unique session identifier
+     * @returns The loaded session or null if not found
+     */
+    load(sessionId: string): Promise<ReplSession | null>;
+    /**
+     * List all sessions, optionally filtered by project path
+     * @param projectPath - Optional project path to filter by
+     * @returns Array of persisted session metadata
+     */
+    listSessions(projectPath?: string): Promise<PersistedSession[]>;
+    /**
+     * Delete a session from disk
+     * @param sessionId - The unique session identifier
+     * @returns True if deleted, false if not found
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Get the most recent session for a project
+     * @param projectPath - The project path to search
+     * @returns The most recent session or null if none exist
+     */
+    getMostRecent(projectPath: string): Promise<PersistedSession | null>;
+}
+/**
+ * Configuration for session persistence behavior
+ */
+interface SessionPersistenceConfig {
+    /** Directory to store session files */
+    storageDir: string;
+    /** Auto-save interval in milliseconds (default: 30000 = 30 seconds) */
+    autoSaveInterval: number;
+    /** Maximum sessions to keep per project (default: 20) */
+    maxSessionsPerProject: number;
+    /** Whether to compress old sessions to save disk space */
+    compressOldSessions: boolean;
+}
+
+/**
+ * Session Storage Implementation
+ *
+ * Handles persisting and loading REPL sessions to disk.
+ * Uses a directory-per-session structure for efficient reads and writes.
+ *
+ * Storage Structure:
+ *   ~/.coco/sessions/
+ *     <session-id>/
+ *       metadata.json       - PersistedSession info
+ *       conversation.jsonl  - Messages, one per line
+ *       context.json        - Context manager state
+ */
+
+/**
+ * SessionStore class implementing SessionStorage interface
+ */
+declare class SessionStore implements SessionStorage {
+    private config;
+    private initialized;
+    constructor(config?: Partial<SessionPersistenceConfig>);
+    private ensureInitialized;
+    private getSessionFiles;
+    getSessionDir(sessionId: string): string;
+    exists(sessionId: string): Promise<boolean>;
+    save(session: ReplSession): Promise<void>;
+    load(sessionId: string): Promise<ReplSession | null>;
+    listSessions(projectPath?: string): Promise<PersistedSession[]>;
+    delete(sessionId: string): Promise<boolean>;
+    getMostRecent(projectPath: string): Promise<PersistedSession | null>;
+    /**
+     * Append messages to an existing session's conversation file
+     * Creates the file if it doesn't exist
+     * @param sessionId - The session ID
+     * @param messages - Messages to append
+     */
+    appendMessages(sessionId: string, messages: Message[]): Promise<void>;
+    /**
+     * Prune old sessions to keep storage manageable
+     * Keeps the most recent maxSessionsPerProject sessions per project
+     * @param projectPath - Optional project path to prune (prunes all if not specified)
+     * @returns Number of sessions deleted
+     */
+    pruneOldSessions(projectPath?: string): Promise<number>;
+    private calculateTokens;
+    private generateTitle;
+}
+
 /**
  * Tool Registry for Corbat-Coco
  * Central management of all available tools
@@ -3253,6 +4326,200 @@ declare class ToolRegistry {
  */
 declare function createToolRegistry(): ToolRegistry;
 
+/** Catalog-backed provider/model registry used by runtime consumers. */
+declare class ProviderRegistry {
+    listProviders(): ProviderCatalogEntry[];
+    getProvider(provider: ProviderType): ProviderCatalogEntry;
+    listModels(provider: ProviderType): ModelCatalogEntry[];
+    getModel(provider: ProviderType, model: string): ModelCatalogEntry | undefined;
+    getDefaultModel(provider: ProviderType): string;
+    getRecommendedModel(provider: ProviderType): ModelCatalogEntry;
+    getCapability(provider: ProviderType, model?: string): ProviderRuntimeCapability;
+    createProvider(provider: ProviderType, config?: ProviderConfig): Promise<LLMProvider>;
+    probe(provider: ProviderType, model: string | undefined, checkAvailability?: () => Promise<boolean>): Promise<ProviderProbeResult>;
+}
+declare function createProviderRegistry(): ProviderRegistry;
+
+type ReasoningEffort = "auto" | "low" | "medium" | "high" | "max";
+type RuntimeMode = AgentModeId;
+interface AgentRuntimeOptions {
+    providerType: ProviderType;
+    model?: string;
+    providerConfig?: ProviderConfig;
+    provider?: LLMProvider;
+    toolRegistry?: ToolRegistry;
+    sessionStore?: SessionStore;
+    permissionPolicy?: PermissionPolicy;
+    eventLog?: EventLog;
+    eventLogPath?: string;
+    /**
+     * Publish provider/tools into Coco's legacy process-global subagent bridge.
+     * CLI/headless use this for compatibility; embedders should leave it false.
+     */
+    publishToGlobalBridge?: boolean;
+}
+interface AgentRuntimeSnapshot {
+    provider: {
+        type: ProviderType;
+        model: string;
+        capability: ProviderRuntimeCapability;
+    };
+    tools: {
+        count: number;
+        names: string[];
+    };
+    modes: AgentModeDefinition[];
+}
+type RuntimeEventType = "runtime.initialized" | "provider.attached" | "provider.created" | "provider.updated" | "turn.started" | "turn.completed" | "turn.failed" | "tool.started" | "tool.completed" | "tool.allowed" | "tool.blocked" | "tool.skipped" | "workflow.planned" | "workflow.started" | "workflow.completed" | "workflow.failed" | "session.created" | "checkpoint.created" | "error";
+interface RuntimeEvent {
+    id: string;
+    type: RuntimeEventType;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+interface EventLog {
+    record(type: RuntimeEventType, data?: Record<string, unknown>): RuntimeEvent;
+    list(): RuntimeEvent[];
+    count(): number;
+    clear(): void;
+}
+interface PermissionDecision {
+    allowed: boolean;
+    reason?: string;
+    requiresConfirmation?: boolean;
+    risk: "read-only" | "write" | "network" | "destructive" | "secrets-sensitive";
+}
+interface PermissionPolicy {
+    canExecuteTool(mode: RuntimeMode, tool: ToolDefinition): PermissionDecision;
+}
+interface ProviderRuntimeSelection {
+    provider: ProviderType;
+    model: string;
+    thinking?: ThinkingMode;
+}
+
+/**
+ * Reusable runtime facade for wiring providers, tools, permissions, sessions,
+ * and observability. It does not own the CLI loop; CLI/headless are adapters on
+ * top of this boundary.
+ */
+declare class AgentRuntime {
+    private readonly options;
+    readonly providerRegistry: ProviderRegistry;
+    readonly toolRegistry: ToolRegistry;
+    readonly sessionStore: SessionStore;
+    readonly permissionPolicy: PermissionPolicy;
+    readonly eventLog: EventLog;
+    private providerType;
+    private model;
+    constructor(options: AgentRuntimeOptions);
+    initialize(): Promise<void>;
+    getModel(): string;
+    updateProvider(providerType: ProviderType, model: string | undefined, provider: LLMProvider): void;
+    private publishToGlobalBridge;
+    snapshot(): AgentRuntimeSnapshot;
+    assertToolAllowed(mode: RuntimeMode, toolName: string): boolean;
+}
+declare function createAgentRuntime(options: AgentRuntimeOptions): Promise<AgentRuntime>;
+
+declare class InMemoryEventLog implements EventLog {
+    private events;
+    record(type: RuntimeEventType, data?: Record<string, unknown>): RuntimeEvent;
+    list(): RuntimeEvent[];
+    count(): number;
+    clear(): void;
+}
+declare class FileEventLog implements EventLog {
+    private readonly filePath;
+    private memory;
+    private writable;
+    constructor(filePath: string);
+    record(type: RuntimeEventType, data?: Record<string, unknown>): RuntimeEvent;
+    list(): RuntimeEvent[];
+    count(): number;
+    clear(): void;
+}
+declare function createEventLog(): EventLog;
+declare function createFileEventLog(filePath: string): EventLog;
+
+declare class DefaultPermissionPolicy implements PermissionPolicy {
+    canExecuteTool(mode: RuntimeMode, tool: ToolDefinition): PermissionDecision;
+}
+declare function createPermissionPolicy(): PermissionPolicy;
+
+type ExtensionRisk = "read-only" | "write" | "network" | "destructive" | "secrets-sensitive";
+type AgentSurface = "coco" | "claude" | "codex" | "gemini" | "opencode";
+interface SkillManifest {
+    name: string;
+    description: string;
+    triggers: string[];
+    requiredTools: string[];
+    risk: ExtensionRisk;
+    compatibleAgents: AgentSurface[];
+    sourcePath?: string;
+}
+interface RecipeStep {
+    id: string;
+    description: string;
+    requiredTools?: string[];
+    check?: string;
+}
+interface RecipeManifest {
+    name: string;
+    description: string;
+    inputs: string[];
+    suggestedModels?: string[];
+    steps: RecipeStep[];
+    checks: string[];
+    risk: ExtensionRisk;
+}
+interface McpToolPolicy {
+    server: string;
+    tool: string;
+    risk: ExtensionRisk;
+    requiresConfirmation: boolean;
+    allowedModes: string[];
+}
+declare function createMcpToolPolicy(server: string, tool: string, risk: ExtensionRisk, allowedModes?: string[]): McpToolPolicy;
+
+type WorkflowRisk = "read-only" | "write" | "network" | "destructive" | "secrets-sensitive";
+interface WorkflowStepDefinition {
+    id: string;
+    description: string;
+    requiredTools: string[];
+    risk: WorkflowRisk;
+}
+interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    inputSchema: string;
+    steps: WorkflowStepDefinition[];
+    checks: string[];
+    outputKind: "markdown" | "json" | "patch" | "pull-request" | "release";
+    replayable: boolean;
+}
+interface WorkflowPlan {
+    id: string;
+    workflowId: string;
+    input: Record<string, unknown>;
+    status: "planned";
+    createdAt: string;
+}
+/** Descriptive catalog of reusable workflow definitions; it does not execute workflows. */
+declare class WorkflowCatalog {
+    private workflows;
+    constructor(workflows?: WorkflowDefinition[]);
+    register(workflow: WorkflowDefinition): void;
+    get(id: string): WorkflowDefinition | undefined;
+    list(): WorkflowDefinition[];
+    createPlan(workflowId: string, input: Record<string, unknown>, eventLog?: EventLog): WorkflowPlan;
+}
+declare const DEFAULT_WORKFLOWS: WorkflowDefinition[];
+declare const WorkflowRegistry: typeof WorkflowCatalog;
+declare function createWorkflowCatalog(workflows?: WorkflowDefinition[]): WorkflowCatalog;
+declare function createWorkflowRegistry(workflows?: WorkflowDefinition[]): WorkflowCatalog;
+
 /**
  * Tool exports for Corbat-Coco
  */
@@ -3300,4 +4567,4 @@ interface SystemProxyConfig {
  */
 declare function installProxyDispatcher(resolveSystem?: () => SystemProxyConfig | null): string | null;
 
-export { ADRGenerator, AnthropicProvider, ArchitectureGenerator, type Backlog, BacklogGenerator, CICDGenerator, type ChatOptions, type ChatResponse, type CocoConfig, CocoError, CodeGenerator, CodeReviewer, CompleteExecutor, ConfigError, ConvergeExecutor, DiscoveryEngine, DockerGenerator, DocsGenerator, type Epic, type LLMProvider, type Message, OrchestrateExecutor, type Orchestrator, type OrchestratorConfig, OutputExecutor, type Phase, type PhaseContext, PhaseError, type PhaseExecutor, type PhaseResult, type Progress, type ProjectState, type QualityDimensions, type QualityScores, type QualityThresholds, SessionManager, SpecificationGenerator, type Sprint, type Story, type Task, TaskError, type TaskHistory, TaskIterator, type TaskVersion, ToolRegistry, VERSION, configExists, createADRGenerator, createAnthropicProvider, createArchitectureGenerator, createBacklogGenerator, createCICDGenerator, createCodeGenerator, createCodeReviewer, createCompleteExecutor, createConvergeExecutor, createDefaultConfig, createDiscoveryEngine, createDockerGenerator, createDocsGenerator, createFullToolRegistry, createLogger, createOrchestrateExecutor, createOrchestrator, createOutputExecutor, createProvider, createSessionManager, createSpecificationGenerator, createTaskIterator, createToolRegistry, installProxyDispatcher, loadConfig, registerAllTools, saveConfig };
+export { ADRGenerator, AgentRuntime, type AgentRuntimeOptions, type AgentRuntimeSnapshot, type AgentSurface, AnthropicProvider, ArchitectureGenerator, type Backlog, BacklogGenerator, CICDGenerator, type ChatOptions, type ChatResponse, type CocoConfig, CocoError, CodeGenerator, CodeReviewer, CompleteExecutor, ConfigError, ConvergeExecutor, DEFAULT_WORKFLOWS, DefaultPermissionPolicy, DiscoveryEngine, DockerGenerator, DocsGenerator, type Epic, type EventLog, type ExtensionRisk, FileEventLog, InMemoryEventLog, type LLMProvider, type McpToolPolicy, type Message, OrchestrateExecutor, type Orchestrator, type OrchestratorConfig, OutputExecutor, type PermissionDecision, type PermissionPolicy, type Phase, type PhaseContext, PhaseError, type PhaseExecutor, type PhaseResult, type Progress, type ProjectState, ProviderRegistry, type ProviderRuntimeSelection, type QualityDimensions, type QualityScores, type QualityThresholds, type ReasoningEffort, type RecipeManifest, type RecipeStep, type RuntimeEvent, type RuntimeEventType, type RuntimeMode, SessionManager, type SkillManifest, SpecificationGenerator, type Sprint, type Story, type Task, TaskError, type TaskHistory, TaskIterator, type TaskVersion, ToolRegistry, VERSION, WorkflowCatalog, type WorkflowDefinition, type WorkflowPlan, WorkflowRegistry, type WorkflowRisk, type WorkflowStepDefinition, configExists, createADRGenerator, createAgentRuntime, createAnthropicProvider, createArchitectureGenerator, createBacklogGenerator, createCICDGenerator, createCodeGenerator, createCodeReviewer, createCompleteExecutor, createConvergeExecutor, createDefaultConfig, createDiscoveryEngine, createDockerGenerator, createDocsGenerator, createEventLog, createFileEventLog, createFullToolRegistry, createLogger, createMcpToolPolicy, createOrchestrateExecutor, createOrchestrator, createOutputExecutor, createPermissionPolicy, createProvider, createProviderRegistry, createSessionManager, createSpecificationGenerator, createTaskIterator, createToolRegistry, createWorkflowCatalog, createWorkflowRegistry, installProxyDispatcher, loadConfig, registerAllTools, saveConfig };