@corbat-tech/coco 2.35.0 → 2.37.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { Server } from 'node:http';
 import { Logger, ILogObj } from 'tslog';
 
 declare const VERSION: string;
@@ -957,6 +958,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 +3141,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
  */
@@ -3253,6 +3327,382 @@ 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;
+
+/**
+ * Agent mode registry.
+ *
+ * Modes describe the intended control flow for a runtime turn without changing
+ * the provider interface. CLI, headless, and embedders share this registry.
+ */
+type AgentModeId = "ask" | "plan" | "build" | "debug" | "review" | "architect";
+interface AgentModeDefinition {
+    id: AgentModeId;
+    label: string;
+    description: string;
+    readOnly: boolean;
+    preferredTools: string[];
+    requiresVerification: boolean;
+}
+declare const AGENT_MODES: Record<AgentModeId, AgentModeDefinition>;
+declare function getAgentMode(mode: AgentModeId): AgentModeDefinition;
+declare function listAgentModes(): AgentModeDefinition[];
+declare function isAgentMode(value: string): value is AgentModeId;
+
+type ReasoningEffort = "auto" | "low" | "medium" | "high" | "max";
+type RuntimeMode = AgentModeId;
+interface AgentRuntimeOptions {
+    providerType: ProviderType;
+    model?: string;
+    providerConfig?: ProviderConfig;
+    provider?: LLMProvider;
+    toolRegistry?: ToolRegistry;
+    /** Legacy CLI session store passthrough. Runtime APIs use runtimeSessionStore. */
+    sessionStore?: unknown;
+    runtimeSessionStore?: RuntimeSessionStore;
+    workflowEngine?: WorkflowEngine;
+    permissionPolicy?: PermissionPolicy;
+    eventLog?: EventLog;
+    eventLogPath?: string;
+    turnRunner?: RuntimeTurnRunner;
+    /**
+     * 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.cancelled" | "turn.failed" | "tool.started" | "tool.completed" | "tool.allowed" | "tool.blocked" | "tool.skipped" | "workflow.planned" | "workflow.started" | "workflow.completed" | "workflow.failed" | "session.created" | "session.updated" | "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;
+    canExecuteToolInput?(mode: RuntimeMode, tool: ToolDefinition, input: Record<string, unknown>): PermissionDecision;
+}
+interface ProviderRuntimeSelection {
+    provider: ProviderType;
+    model: string;
+    thinking?: ThinkingMode;
+}
+interface RuntimeSession {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    mode: RuntimeMode;
+    messages: Message[];
+    instructions?: string;
+    metadata: Record<string, unknown>;
+}
+interface RuntimeSessionCreateOptions {
+    id?: string;
+    mode?: RuntimeMode;
+    instructions?: string;
+    metadata?: Record<string, unknown>;
+    messages?: Message[];
+}
+interface RuntimeSessionStore {
+    create(options?: RuntimeSessionCreateOptions): RuntimeSession;
+    get(id: string): RuntimeSession | undefined;
+    update(session: RuntimeSession): RuntimeSession;
+    list(): RuntimeSession[];
+    delete(id: string): boolean;
+}
+interface RuntimeTurnInput {
+    content: string;
+    sessionId?: string;
+    mode?: RuntimeMode;
+    options?: ChatOptions;
+    metadata?: Record<string, unknown>;
+}
+interface RuntimeTurnResult {
+    sessionId: string;
+    content: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        estimated?: boolean;
+    };
+    model: string;
+    mode: RuntimeMode;
+}
+type RuntimeTurnStreamEvent = {
+    type: "text";
+    sessionId: string;
+    text: string;
+} | {
+    type: "done";
+    sessionId: string;
+    result: RuntimeTurnResult;
+} | {
+    type: "error";
+    sessionId: string;
+    error: string;
+};
+interface RuntimeTurnContext {
+    runtime: unknown;
+    session: RuntimeSession;
+    provider: LLMProvider;
+    toolRegistry: ToolRegistry;
+    permissionPolicy: PermissionPolicy;
+    eventLog: EventLog;
+}
+interface RuntimeTurnRunner {
+    run(input: RuntimeTurnInput, context: RuntimeTurnContext): Promise<RuntimeTurnResult>;
+}
+interface RuntimeToolExecutionInput {
+    sessionId?: string;
+    mode?: RuntimeMode;
+    toolName: string;
+    input: Record<string, unknown>;
+    confirmed?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RuntimeToolExecutionResult {
+    toolName: string;
+    success: boolean;
+    output?: unknown;
+    error?: string;
+    duration: number;
+    decision: PermissionDecision;
+}
+
+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;
+
+type WorkflowRunStatus = "completed" | "failed";
+interface WorkflowRunInput {
+    workflowId: string;
+    input: Record<string, unknown>;
+    plan?: WorkflowPlan;
+}
+interface WorkflowRunResult {
+    id: string;
+    workflowId: string;
+    status: WorkflowRunStatus;
+    output: unknown;
+    startedAt: string;
+    completedAt: string;
+    error?: string;
+}
+interface WorkflowRunContext {
+    workflow: WorkflowDefinition;
+    plan: WorkflowPlan;
+    eventLog: EventLog;
+}
+type WorkflowHandler = (input: Record<string, unknown>, context: WorkflowRunContext) => Promise<unknown>;
+declare class WorkflowEngine {
+    private readonly catalog;
+    private readonly eventLog;
+    private handlers;
+    constructor(catalog?: WorkflowCatalog, eventLog?: EventLog);
+    registerHandler(workflowId: string, handler: WorkflowHandler): void;
+    createPlan(workflowId: string, input: Record<string, unknown>): WorkflowPlan;
+    run(request: WorkflowRunInput): Promise<WorkflowRunResult>;
+}
+declare function createWorkflowEngine(catalog?: WorkflowCatalog, eventLog?: EventLog): WorkflowEngine;
+
+/**
+ * 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: unknown;
+    readonly runtimeSessionStore: RuntimeSessionStore;
+    readonly workflowEngine: WorkflowEngine;
+    readonly permissionPolicy: PermissionPolicy;
+    readonly eventLog: EventLog;
+    readonly turnRunner: RuntimeTurnRunner;
+    private providerType;
+    private model;
+    private provider?;
+    constructor(options: AgentRuntimeOptions);
+    initialize(): Promise<void>;
+    getModel(): string;
+    updateProvider(providerType: ProviderType, model: string | undefined, provider: LLMProvider): void;
+    private publishToGlobalBridge;
+    snapshot(): AgentRuntimeSnapshot;
+    createSession(options?: RuntimeSessionCreateOptions): RuntimeSession;
+    getSession(sessionId: string): RuntimeSession | undefined;
+    listSessions(): RuntimeSession[];
+    runTurn(input: RuntimeTurnInput): Promise<RuntimeTurnResult>;
+    streamTurn(input: RuntimeTurnInput): AsyncIterable<RuntimeTurnStreamEvent>;
+    executeTool(input: RuntimeToolExecutionInput): Promise<RuntimeToolExecutionResult>;
+    assertToolAllowed(mode: RuntimeMode, toolName: string, input?: Record<string, unknown>): boolean;
+}
+declare function createAgentRuntime(options: AgentRuntimeOptions): Promise<AgentRuntime>;
+
+declare class DefaultRuntimeTurnRunner implements RuntimeTurnRunner {
+    run(input: RuntimeTurnInput, context: RuntimeTurnContext): Promise<RuntimeTurnResult>;
+}
+declare function createDefaultRuntimeTurnRunner(): RuntimeTurnRunner;
+
+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;
+
+interface RuntimeHttpServerOptions {
+    maxBodyBytes?: number;
+}
+declare function createRuntimeHttpServer(runtime: AgentRuntime, options?: RuntimeHttpServerOptions): Server;
+
+declare class DefaultPermissionPolicy implements PermissionPolicy {
+    canExecuteTool(mode: RuntimeMode, tool: ToolDefinition): PermissionDecision;
+    canExecuteToolInput(mode: RuntimeMode, tool: ToolDefinition, input: Record<string, unknown>): PermissionDecision;
+}
+declare function createPermissionPolicy(): PermissionPolicy;
+
+declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
+    private sessions;
+    create(options?: RuntimeSessionCreateOptions): RuntimeSession;
+    get(id: string): RuntimeSession | undefined;
+    update(session: RuntimeSession): RuntimeSession;
+    list(): RuntimeSession[];
+    delete(id: string): boolean;
+}
+declare class FileRuntimeSessionStore implements RuntimeSessionStore {
+    private readonly filePath;
+    private sessions;
+    constructor(filePath: string);
+    create(options?: RuntimeSessionCreateOptions): RuntimeSession;
+    get(id: string): RuntimeSession | undefined;
+    update(session: RuntimeSession): RuntimeSession;
+    list(): RuntimeSession[];
+    delete(id: string): boolean;
+    private readSessionsFromDisk;
+    private persist;
+}
+declare function createRuntimeSessionStore(): RuntimeSessionStore;
+declare function createFileRuntimeSessionStore(filePath: string): RuntimeSessionStore;
+
+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;
+
 /**
  * Tool exports for Corbat-Coco
  */
@@ -3300,4 +3750,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, AGENT_MODES, type AgentModeDefinition, type AgentModeId, 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, DefaultRuntimeTurnRunner, DiscoveryEngine, DockerGenerator, DocsGenerator, type Epic, type EventLog, type ExtensionRisk, FileEventLog, FileRuntimeSessionStore, InMemoryEventLog, InMemoryRuntimeSessionStore, 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 RuntimeHttpServerOptions, type RuntimeMode, type RuntimeSession, type RuntimeSessionCreateOptions, type RuntimeSessionStore, type RuntimeToolExecutionInput, type RuntimeToolExecutionResult, type RuntimeTurnContext, type RuntimeTurnInput, type RuntimeTurnResult, type RuntimeTurnRunner, type RuntimeTurnStreamEvent, SessionManager, type SkillManifest, SpecificationGenerator, type Sprint, type Story, type Task, TaskError, type TaskHistory, TaskIterator, type TaskVersion, ToolRegistry, VERSION, WorkflowCatalog, type WorkflowDefinition, WorkflowEngine, type WorkflowHandler, type WorkflowPlan, WorkflowRegistry, type WorkflowRisk, type WorkflowRunContext, type WorkflowRunInput, type WorkflowRunResult, type WorkflowRunStatus, type WorkflowStepDefinition, configExists, createADRGenerator, createAgentRuntime, createAnthropicProvider, createArchitectureGenerator, createBacklogGenerator, createCICDGenerator, createCodeGenerator, createCodeReviewer, createCompleteExecutor, createConvergeExecutor, createDefaultConfig, createDefaultRuntimeTurnRunner, createDiscoveryEngine, createDockerGenerator, createDocsGenerator, createEventLog, createFileEventLog, createFileRuntimeSessionStore, createFullToolRegistry, createLogger, createMcpToolPolicy, createOrchestrateExecutor, createOrchestrator, createOutputExecutor, createPermissionPolicy, createProvider, createProviderRegistry, createRuntimeHttpServer, createRuntimeSessionStore, createSessionManager, createSpecificationGenerator, createTaskIterator, createToolRegistry, createWorkflowCatalog, createWorkflowEngine, createWorkflowRegistry, getAgentMode, installProxyDispatcher, isAgentMode, listAgentModes, loadConfig, registerAllTools, saveConfig };