c0de-agent 0.0.0 → 1.0.0

package/dist/shared/types/agent.d.ts

@@ -0,0 +1,202 @@
+import type { ChatTool } from './llm.js';
+import type { Message, Session } from './message.js';
+import type { ToolDef, ToolResult } from './tool.js';
+/** Agent error variants. Discriminated by `_tag`. */
+type AgentError = {
+    _tag: 'aborted';
+} | {
+    _tag: 'max_turns';
+    maxTurns: number;
+} | {
+    _tag: 'unexpected';
+    message: string;
+} | {
+    _tag: 'provider';
+    message: string;
+    retryable: boolean;
+} | {
+    _tag: 'tool';
+    toolName: string;
+    message: string;
+};
+/** A tool call awaiting user permission. */
+type PendingToolCall = {
+    id: string;
+    tool: string;
+    input: unknown;
+};
+/** Agent run-time status. Discriminated by `_tag`. */
+type AgentStatus = {
+    _tag: 'idle';
+} | {
+    _tag: 'running';
+    currentTool?: string;
+    turnCount: number;
+} | {
+    _tag: 'paused';
+    pauseReason: string;
+    pendingToolCall?: PendingToolCall;
+} | {
+    _tag: 'stopped';
+    reason: 'completed' | 'aborted' | 'error';
+    error?: AgentError;
+} | {
+    _tag: 'interrupted';
+};
+/** Configuration for creating an agent. */
+type AgentConfig = {
+    provider: string;
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    systemPrompt?: string;
+    tools: string[];
+    plugins: string[];
+    maxTurns?: number;
+    /** primary agent 名（段记录用，spec: agent-frontend-switching §4.2）。 */
+    agentName?: string;
+    /** primary agent 的 role prompt（仅覆盖 role section，保留动态上下文）。 */
+    agentRolePrompt?: string;
+};
+/**
+ * Token budget for context window management.
+ * 分配（spec §3.6 策略1）：reserved(system prompt+工具描述) 20%，
+ * historyBudget(历史消息) 60%，剩余 available-historyBudget 预留给当前轮次 20%。
+ */
+type TokenBudget = {
+    total: number;
+    reserved: number;
+    available: number;
+    historyBudget: number;
+    used: number;
+    keepRecent: number;
+};
+/** 段内单次 LLM 调用的轻量记录（不含 messages/systemPrompt/tools——那些是段级或派生数据）。 */
+type LLMCall = {
+    id: string;
+    timestamp: number;
+    usage: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+    };
+    latency: {
+        firstToken: number;
+        total: number;
+    };
+    cost: number;
+    thinking?: string;
+    /** 模型回复文本（替代完整 responseChunks；前端只用文本拼接）。 */
+    responseText: string;
+    /** 非正常停止原因（length/content_filter），正常完成为 undefined。 */
+    finishReason?: string;
+};
+/** 触发新段的原因。 */
+type SegmentTrigger = 'initial' | 'model_change' | 'tools_change' | 'system_prompt_change' | 'compaction' | 'user_confirmed';
+/**
+ * 一段共享相同前缀（systemPrompt + tools + provider + model）的连续 LLM 调用。
+ * 段首存一次前缀快照，段内 calls 只记轻量增量，消除每轮重复存储完整 messages 的 O(N²) 冗余。
+ */
+type LLMSegment = {
+    id: string;
+    /** hash(systemPrompt + 规格化 tools)。变化 = 前缀失效 = cache miss。 */
+    fingerprint: string;
+    provider: string;
+    model: string;
+    /** 段首快照：本段生命周期内恒定的系统提示词。 */
+    systemPrompt: string;
+    /** 段首快照：本段启用的工具规格。 */
+    tools: ChatTool[];
+    startedAt: number;
+    trigger: SegmentTrigger;
+    /** 段首 primary agent 名（段检测比较用，spec: agent-frontend-switching §4.3）。 */
+    agentName?: string;
+    /** 模型上下文窗口（来自 registry capabilities），用于总结面板使用率。段内恒定。 */
+    contextWindow?: number;
+    calls: LLMCall[];
+};
+/** Events emitted by the agent loop. Discriminated by `_tag`. */
+type AgentEvent = {
+    _tag: 'status_change';
+    status: AgentStatus;
+} | {
+    _tag: 'text_delta';
+    text: string;
+} | {
+    _tag: 'tool_call_start';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    _tag: 'tool_call_progress';
+    id: string;
+    progress: string;
+} | {
+    _tag: 'tool_call_end';
+    id: string;
+    result: ToolResult;
+} | {
+    _tag: 'thinking';
+    text: string;
+} | {
+    _tag: 'usage';
+    input: number;
+    output: number;
+    cacheRead?: number;
+} | {
+    _tag: 'permission_required';
+    toolCallId: string;
+    tool: string;
+    input: unknown;
+} | {
+    _tag: 'error';
+    error: AgentError;
+}
+/** 通知前端：本轮 LLM 调用详情已持久化，应刷新调用详情面板。轻量通知，不带 payload。 */
+ | {
+    _tag: 'llm_detail';
+} | {
+    _tag: 'subagent_start';
+    childId: string;
+    agentType: string;
+    description: string;
+    background: boolean;
+} | {
+    _tag: 'subagent_progress';
+    childId: string;
+    toolName?: string;
+    status: 'running' | 'completed' | 'failed';
+} | {
+    _tag: 'subagent_end';
+    childId: string;
+    agentType: string;
+    success: boolean;
+    output?: string;
+} | {
+    _tag: 'done';
+};
+/**
+ * Mutable agent state.
+ * Per the data+functions paradigm, the context object may be modified in place.
+ */
+type AgentState = {
+    id: string;
+    session: Session;
+    messages: Message[];
+    tools: ToolDef[];
+    config: AgentConfig;
+    status: AgentStatus;
+    abortController: AbortController;
+    steeringQueue: string[];
+    segments: LLMSegment[];
+    /** compaction 等事件要求下一轮强制开新段时设置；loop 消费后清除。 */
+    pendingSegmentTrigger?: SegmentTrigger;
+    tokenBudget: TokenBudget;
+    /** estimateTokens 的校准系数（由 calibrateEstimate 按真实 usage EMA 更新，默认 1.0）。 */
+    calibrationFactor: number;
+    compactionModel?: {
+        provider: string;
+        model: string;
+    };
+};
+export type { AgentConfig, AgentError, AgentEvent, AgentState, AgentStatus, LLMCall, LLMSegment, PendingToolCall, SegmentTrigger, TokenBudget, };

package/dist/shared/types/agent.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/base.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JSON Schema type (draft-07 compatible subset).
+ * Used for tool parameter schemas and config schemas.
+ */
+type JSONSchema = {
+    type?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema | JSONSchema[];
+    description?: string;
+    enum?: unknown[];
+    additionalProperties?: boolean | JSONSchema;
+    allOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    $ref?: string;
+    default?: unknown;
+    examples?: unknown[];
+    [key: string]: unknown;
+};
+/** Role of a message in a conversation. */
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * Lightweight session reference.
+ * Used by ToolContext and other cross-package types to avoid
+ * importing the full Session type from the session package.
+ */
+type SessionRef = {
+    id: string;
+    cwd: string;
+};
+export type { JSONSchema, MessageRole, SessionRef };

package/dist/shared/types/base.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/config.d.ts

@@ -0,0 +1,104 @@
+import type { ProviderConfig } from './llm.js';
+/** MCP server configuration. */
+type MCPServerConfig = {
+    name: string;
+    transport: 'stdio' | 'sse' | 'http';
+    command?: string;
+    args?: string[];
+    url?: string;
+};
+/** Context compaction configuration. */
+type CompactionConfig = {
+    enabled: boolean;
+    /** Token usage ratio that triggers compaction (e.g. 0.8 = 80%). */
+    threshold: number;
+    /** Token space to reserve after compaction. */
+    reserveTokens: number;
+    /** Token budget for retaining recent messages verbatim. */
+    keepRecentTokens: number;
+};
+/** Tool-mode auto-selection configuration (spec §16.5). */
+type ToolMetricsConfig = {
+    enabled: boolean;
+    /** Minimum success ratio to prefer a mode (e.g. 0.8 = 80%). */
+    threshold: number;
+    /** Minimum sample count before trusting a mode's success ratio. */
+    minSamples: number;
+};
+/** Web 搜索配置（见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md）。 */
+type WebSearchConfig = {
+    /** 后端选择。'auto'（默认）→ 按 key 可用性：tavily > brave > duckduckgo。 */
+    provider: 'auto' | 'duckduckgo' | 'tavily' | 'brave';
+    /** Tavily key；也可由环境变量 TAVILY_API_KEY 提供（环境变量优先）。 */
+    tavilyApiKey?: string;
+    /** Brave key；也可由环境变量 BRAVE_API_KEY 提供（环境变量优先）。 */
+    braveApiKey?: string;
+};
+/** 多 agent 配置（spec: multi-agent-design §4.12）。 */
+type AgentsConfig = {
+    /** agent markdown 目录（相对项目根），默认 '.c0de/agents'。 */
+    dir: string;
+    /** 并行子 agent 数上限，默认 3。 */
+    subagentConcurrency: number;
+};
+/** 权限配置：控制工具执行授权的默认行为。 */
+type PermissionConfig = {
+    /** 启动时的默认授权模式：'default' 逐个确认（默认）；'auto' 自动放行 ask 工具（YOLO 自动授权）。 */
+    defaultMode: 'default' | 'auto';
+};
+/** 自动升级配置（spec §18）。控制后台 npm registry 检查与无感知热更新行为。 */
+type UpdateConfig = {
+    /** 启用后台定期版本检查（默认 true）。 */
+    enabled: boolean;
+    /** 检查间隔（毫秒），默认 1 小时。 */
+    intervalMs: number;
+    /** 启动后首次检查的延迟（毫秒），默认 10 秒。 */
+    initialDelayMs: number;
+    /** 发现新版本后自动应用（无感知），false 则仅前端提示手动确认（默认 false）。 */
+    autoApply: boolean;
+};
+/** Server security configuration (spec §24.2). */
+type SecurityConfig = {
+    /** 启用 Bearer token 认证（远程访问场景）。本地开发默认关闭。 */
+    authEnabled: boolean;
+    /** Bearer token；authEnabled 为 true 时必填。 */
+    token?: string;
+    /** 额外允许的 CORS origin（本地回环始终允许）。 */
+    allowedOrigins: string[];
+};
+/** Global application configuration. */
+type Config = {
+    providers: ProviderConfig[];
+    defaultProvider: string;
+    defaultModel: string;
+    roleRouting: Record<string, {
+        provider: string;
+        model: string;
+    }>;
+    fallback: {
+        enabled: boolean;
+        maxRetries: number;
+        retryDelay: number;
+    };
+    compaction: CompactionConfig;
+    tools: {
+        enabled: string[];
+        disabled: string[];
+    };
+    plugins: {
+        enabled: string[];
+    };
+    mcpServers: MCPServerConfig[];
+    slashCommands: {
+        enabled: string[];
+    };
+    toolMetrics: ToolMetricsConfig;
+    security: SecurityConfig;
+    websearch: WebSearchConfig;
+    agents: AgentsConfig;
+    permission: PermissionConfig;
+    update: UpdateConfig;
+    theme: 'light' | 'dark' | 'system';
+    locale: string;
+};
+export type { AgentsConfig, CompactionConfig, Config, MCPServerConfig, PermissionConfig, SecurityConfig, ToolMetricsConfig, UpdateConfig, WebSearchConfig, };

package/dist/shared/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './agent.js';
+export type * from './base.js';
+export type * from './config.js';
+export type * from './llm.js';
+export type * from './message.js';
+export type * from './tool.js';

package/dist/shared/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/llm.d.ts

@@ -0,0 +1,122 @@
+import type { JSONSchema } from './base.js';
+/** Supported LLM provider protocols. */
+type ProviderProtocol = 'openai' | 'anthropic' | 'google' | 'openai-compat';
+/** Why a model response ended. Protocol-agnostic; mirrored by each provider. */
+type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'unknown';
+/** Provider configuration entry. */
+type ProviderConfig = {
+    name: string;
+    protocol: ProviderProtocol;
+    apiKey: string;
+    baseURL?: string;
+    models?: Record<string, ModelOverride>;
+};
+/** Per-model configuration overrides. */
+type ModelOverride = {
+    /** 是否在会话模型选择器中启用。省略或 true 为启用；false 为禁用（仍保留记录）。 */
+    enabled?: boolean;
+    contextWindow?: number;
+    maxOutput?: number;
+    supportsTools?: boolean;
+    supportsVision?: boolean;
+    supportsThinking?: boolean;
+    costPer1kInput?: number;
+    costPer1kOutput?: number;
+};
+/** Static model capability descriptor. */
+type ModelCapabilities = {
+    contextWindow: number;
+    maxOutput: number;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsThinking: boolean;
+    costPer1kInput: number;
+    costPer1kOutput: number;
+};
+/** Role tag for multi-model routing. */
+type ModelRole = {
+    readonly _tag: 'default';
+} | {
+    readonly _tag: 'smol';
+} | {
+    readonly _tag: 'slow';
+} | {
+    readonly _tag: 'plan';
+} | {
+    readonly _tag: 'commit';
+};
+/** Content part for multimodal messages (text or image). */
+type ContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
+/** Protocol-level chat message sent to the LLM provider. */
+type ChatMessage = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | ContentPart[];
+    toolCallId?: string;
+    toolCalls?: {
+        id: string;
+        name: string;
+        arguments: string;
+    }[];
+};
+/** Tool definition as sent to the LLM provider. */
+type ChatTool = {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+};
+/** Request to the LLM provider. */
+type ChatRequest = {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ChatTool[];
+    stream: true;
+    maxTokens?: number;
+    temperature?: number;
+    system?: string;
+};
+/**
+ * Streaming chunk from the LLM provider.
+ * Tool calls stream in three phases: start → delta(s) → end.
+ * The LLM package normalizes all provider formats to this union.
+ */
+type StreamChunk = {
+    _tag: 'text';
+    text: string;
+} | {
+    _tag: 'tool_call_start';
+    id: string;
+    name: string;
+} | {
+    _tag: 'tool_call_delta';
+    id: string;
+    argumentsDelta: string;
+} | {
+    _tag: 'tool_call_end';
+    id: string;
+    argumentsFinal?: string;
+} | {
+    _tag: 'thinking';
+    text: string;
+} | {
+    _tag: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead?: number;
+} | {
+    _tag: 'done';
+    finishReason?: FinishReason;
+} | {
+    _tag: 'error';
+    error: {
+        message: string;
+        retryable?: boolean;
+    };
+};
+export type { ChatMessage, ChatRequest, ChatTool, ContentPart, FinishReason, ModelCapabilities, ModelOverride, ModelRole, ProviderConfig, ProviderProtocol, StreamChunk, };

package/dist/shared/types/llm.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/message.d.ts

@@ -0,0 +1,71 @@
+import type { LLMSegment } from './agent.js';
+import type { MessageRole } from './base.js';
+import type { ToolResult } from './tool.js';
+/** Content variants within a single message. Discriminated by `_tag`. */
+type MessageContent = {
+    _tag: 'text';
+    text: string;
+} | {
+    _tag: 'tool_call';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    _tag: 'tool_result';
+    id: string;
+    tool: string;
+    output: ToolResult;
+} | {
+    _tag: 'thinking';
+    text: string;
+} | {
+    _tag: 'steering';
+    text: string;
+} | {
+    _tag: 'image';
+    mediaType: string;
+    data: string;
+};
+/** A single message in a session. Content is always an array of parts. */
+type Message = {
+    id: string;
+    sessionId: string;
+    role: MessageRole;
+    content: MessageContent[];
+    tokenCount: number;
+    createdAt: number;
+};
+/** 上次 agent run 的持久化状态（服务重启后检测中断用）。 */
+type LastRun = {
+    status: 'running' | 'completed';
+    agentName?: string;
+    provider?: string;
+    model?: string;
+    startedAt: number;
+};
+/** Session metadata for branching and compaction tracking. */
+type SessionMetadata = {
+    mainThreadId?: string;
+    squashCount?: number;
+    fileSnapshots?: string[];
+    /** 本会话分段增量 LLM 调用记录，用于调用详情面板展示。 */
+    segments?: LLMSegment[];
+    /** 上次 agent run 状态；status='running' 且进程无活跃 run → 被中断。 */
+    lastRun?: LastRun;
+};
+/** A conversation session (may have a parent for branching). */
+type Session = {
+    id: string;
+    title: string;
+    parentId: string | null;
+    projectId: string | null;
+    branchPoint: number | null;
+    metadata: SessionMetadata;
+    /** 子 session 用的 agent 类型名（null=主 session）。 */
+    agentType: string | null;
+    /** 隔离 worktree 路径（null=共享父 cwd）。 */
+    worktreePath: string | null;
+    createdAt: number;
+    updatedAt: number;
+};
+export type { LastRun, Message, MessageContent, Session, SessionMetadata };

package/dist/shared/types/message.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/tool.d.ts

@@ -0,0 +1,134 @@
+import type { JSONSchema, SessionRef } from './base.js';
+/** Permission level for tool execution. */
+type ToolPermission = 'auto' | 'ask' | 'deny';
+/** Result of a tool execution. Discriminated by `_tag`. */
+type ToolResult = {
+    _tag: 'success';
+    output: string;
+    metadata?: Record<string, unknown>;
+} | {
+    _tag: 'error';
+    error: string;
+} | {
+    _tag: 'permission_required';
+    reason: string;
+} | {
+    _tag: 'truncated';
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+};
+/** Context passed to a URL resolver (skill://, agent://, pr://, …). */
+type URLResolveContext = {
+    cwd: string;
+    session: SessionRef;
+};
+/** A resolver for one URL scheme (e.g. `skill`, `agent`, `pr`). */
+type URLResolver = {
+    scheme: string;
+    resolve: (url: string, ctx: URLResolveContext) => Promise<string>;
+};
+/** Mutable registry of URL resolvers, keyed by scheme. */
+type URLRegistry = {
+    resolvers: Map<string, URLResolver>;
+};
+/** Result of resolving a URL. */
+type ResolveResult = {
+    _tag: 'ok';
+    content: string;
+} | {
+    _tag: 'error';
+    error: string;
+};
+/** Transport shape for a debug adapter process stdio (DAP). Host-injected. */
+type DebugTransport = {
+    write: (chunk: string | Uint8Array) => void;
+    onData: (handler: (chunk: Uint8Array | string) => void) => void;
+    onClose: (handler: () => void) => void;
+    close: () => void;
+};
+/** Context passed to every tool executor. */
+type ToolContext = {
+    cwd: string;
+    session: SessionRef;
+    abort: AbortSignal;
+    mode?: string;
+    /** URL resolver registry; present when the host wires up internal URL schemes. */
+    urlRegistry?: URLRegistry;
+    /** Spawn a sub-agent and return its final text output (dependency-reversal hook
+     *  for the `task` tool; avoids tools→core circular import). */
+    runSubAgent?: (input: SubAgentRequest) => Promise<SubAgentResult>;
+    /** Spawn a debug adapter and return its stdio transport (dependency-reversal
+     *  hook for the `debug_*` tools; host wires real child_process spawn). */
+    debugSpawn?: (config: unknown) => DebugTransport;
+    /** 子 agent 专用：yield 工具调用时收集结构化结果（runSubAgent 注入）。 */
+    collectYield?: (data: unknown) => void;
+};
+/** 单个并行子任务项（批量模式）。 */
+type TaskItem = {
+    description?: string;
+    /** 角色细分（注入子 prompt）。 */
+    role?: string;
+    assignment: string;
+};
+/** Request to run a sub-agent (the `task` tool's payload to the host). */
+type SubAgentRequest = {
+    /** agent 类型名（必填）。 */
+    agentType: string;
+    prompt: string;
+    description?: string;
+    /** 批量模式的角色细分。 */
+    role?: string;
+    /** 批量模式的共享上下文。 */
+    context?: string;
+    model?: string;
+    /** 后台异步运行（默认 false）。 */
+    background?: boolean;
+};
+/** Result of a sub-agent run. */
+type SubAgentResult = {
+    _tag: 'success';
+    output: string;
+    sessionId: string;
+    data?: unknown;
+    patchPath?: string;
+} | {
+    _tag: 'error';
+    error: string;
+    sessionId?: string;
+} | {
+    _tag: 'running';
+    jobId: string;
+    sessionId: string;
+};
+/** Function signature for tool execution. */
+type ToolExecutor = (input: unknown, ctx: ToolContext) => Promise<ToolResult>;
+/** Optional execution mode for tools with multiple implementations. */
+type ToolMode = {
+    name: string;
+    description: string;
+    isAvailable: (ctx: ToolContext) => boolean;
+};
+/** Complete tool definition registered with the tool registry. */
+type ToolDef = {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+    permission: ToolPermission;
+    execute: ToolExecutor;
+    timeout?: number;
+    modes?: ToolMode[];
+};
+/** Per-(model, tool, mode) success/latency record used to auto-select the
+ *  best tool mode (spec §16.5). Persisted in the `tool_metrics` table. */
+type ModelToolMetrics = {
+    model: string;
+    tool: string;
+    mode: string;
+    attempts: number;
+    successes: number;
+    failures: number;
+    avgLatencyMs: number;
+    lastUsed: number;
+};
+export type { DebugTransport, ModelToolMetrics, ResolveResult, SubAgentRequest, SubAgentResult, TaskItem, ToolContext, ToolDef, ToolExecutor, ToolMode, ToolPermission, ToolResult, URLRegistry, URLResolveContext, URLResolver, };

package/dist/shared/types/tool.js

@@ -0,0 +1 @@
+export {};