@xcompiler/cli 0.2.2

package/dist/acp/index.d.ts

@@ -0,0 +1,1135 @@
+import { z } from 'zod';
+import { Readable, Writable } from 'node:stream';
+
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result: unknown;
+}
+interface JsonRpcFailure {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    error: JsonRpcErrorObject;
+}
+interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccess | JsonRpcFailure;
+declare const JsonRpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly SessionNotFound: -32001;
+    readonly TaskNotFound: -32002;
+    readonly PendingRequestNotFound: -32003;
+    readonly RuntimeError: -32010;
+    readonly CancellationUnsupported: -32020;
+};
+declare const AcpMethod: {
+    readonly Initialize: "initialize";
+    readonly Shutdown: "shutdown";
+    readonly SessionNew: "session/new";
+    readonly SessionPrompt: "session/prompt";
+    readonly SessionCancel: "session/cancel";
+    readonly SessionClose: "session/close";
+    readonly SessionSetMode: "session/set_mode";
+    readonly SessionUpdate: "session/update";
+    readonly SessionRequestPermission: "session/request_permission";
+    readonly LegacySessionCreate: "xcompiler/session/create";
+    readonly LegacySessionClose: "xcompiler/session/close";
+    readonly LegacyTaskStart: "xcompiler/task/start";
+    readonly LegacyTaskCancel: "xcompiler/task/cancel";
+    readonly LegacyConfirmationRespond: "xcompiler/confirmation/respond";
+    readonly LegacyPermissionRespond: "xcompiler/permission/respond";
+    readonly LegacyEvent: "xcompiler/event";
+};
+
+/** Supported target languages for generated projects. */
+declare const LANGUAGES: readonly ["python", "typescript"];
+type Language = (typeof LANGUAGES)[number];
+/** Plan intent: greenfield generation, incremental work, or isolated self-bootstrap. */
+declare const PLAN_INTENTS: readonly ["greenfield", "feature", "refactor", "self"];
+type PlanIntent = (typeof PLAN_INTENTS)[number];
+declare const ROLES: readonly ["Planner", "Architect", "Coder", "Tester", "Debugger"];
+type Role = (typeof ROLES)[number];
+interface StepSubtask {
+    id: string;
+    title: string;
+    description: string;
+    acceptance?: string;
+    outputs?: string[];
+    subTasks?: StepSubtask[];
+}
+declare const StepSchema: z.ZodObject<{
+    id: z.ZodString;
+    iterationId: z.ZodDefault<z.ZodString>;
+    phase: z.ZodEnum<{
+        REQUIREMENT_ANALYSIS: "REQUIREMENT_ANALYSIS";
+        HIGH_LEVEL_DESIGN: "HIGH_LEVEL_DESIGN";
+        DETAILED_DESIGN: "DETAILED_DESIGN";
+        CODE: "CODE";
+        UNIT_TEST: "UNIT_TEST";
+        INTEGRATION_TEST: "INTEGRATION_TEST";
+        MODULE_TEST: "MODULE_TEST";
+        FUNCTIONAL_TEST: "FUNCTIONAL_TEST";
+        DEBUG: "DEBUG";
+    }>;
+    title: z.ZodString;
+    description: z.ZodString;
+    systemPrompt: z.ZodString;
+    role: z.ZodEnum<{
+        Planner: "Planner";
+        Architect: "Architect";
+        Coder: "Coder";
+        Tester: "Tester";
+        Debugger: "Debugger";
+    }>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    outputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    subTasks: z.ZodOptional<z.ZodArray<z.ZodType<StepSubtask, unknown, z.core.$ZodTypeInternals<StepSubtask, unknown>>>>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        PENDING: "PENDING";
+        RUNNING: "RUNNING";
+        DONE: "DONE";
+        FAILED: "FAILED";
+        SKIPPED: "SKIPPED";
+    }>>;
+    retries: z.ZodDefault<z.ZodNumber>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type Step = z.infer<typeof StepSchema>;
+declare const PlanSchema: z.ZodPipe<z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    language: z.ZodDefault<z.ZodEnum<{
+        python: "python";
+        typescript: "typescript";
+    }>>;
+    intent: z.ZodDefault<z.ZodEnum<{
+        greenfield: "greenfield";
+        feature: "feature";
+        refactor: "refactor";
+        self: "self";
+    }>>;
+    projectType: z.ZodDefault<z.ZodEnum<{
+        application: "application";
+        library: "library";
+        mixed: "mixed";
+    }>>;
+    requirementDigest: z.ZodString;
+    complexityAssessment: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<{
+            simple: "simple";
+            moderate: "moderate";
+            complex: "complex";
+        }>;
+        rationale: z.ZodString;
+        splitRecommended: z.ZodDefault<z.ZodBoolean>;
+        userForcedPhaseSplit: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    implementationPhases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        objective: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            current: "current";
+            planned: "planned";
+            deferred: "deferred";
+        }>>;
+        scope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deliverables: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        verificationGate: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodString;
+            checks: z.ZodArray<z.ZodString>;
+            failurePolicy: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    architectureModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        responsibility: z.ZodString;
+        sourcePaths: z.ZodArray<z.ZodString>;
+        testPaths: z.ZodArray<z.ZodString>;
+        dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    globalPrompt: z.ZodDefault<z.ZodString>;
+    baselineSummary: z.ZodDefault<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pythonRequirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    userAddenda: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        iterationId: z.ZodDefault<z.ZodString>;
+        phase: z.ZodEnum<{
+            REQUIREMENT_ANALYSIS: "REQUIREMENT_ANALYSIS";
+            HIGH_LEVEL_DESIGN: "HIGH_LEVEL_DESIGN";
+            DETAILED_DESIGN: "DETAILED_DESIGN";
+            CODE: "CODE";
+            UNIT_TEST: "UNIT_TEST";
+            INTEGRATION_TEST: "INTEGRATION_TEST";
+            MODULE_TEST: "MODULE_TEST";
+            FUNCTIONAL_TEST: "FUNCTIONAL_TEST";
+            DEBUG: "DEBUG";
+        }>;
+        title: z.ZodString;
+        description: z.ZodString;
+        systemPrompt: z.ZodString;
+        role: z.ZodEnum<{
+            Planner: "Planner";
+            Architect: "Architect";
+            Coder: "Coder";
+            Tester: "Tester";
+            Debugger: "Debugger";
+        }>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        inputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        outputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        subTasks: z.ZodOptional<z.ZodArray<z.ZodType<StepSubtask, unknown, z.core.$ZodTypeInternals<StepSubtask, unknown>>>>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        acceptance: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            PENDING: "PENDING";
+            RUNNING: "RUNNING";
+            DONE: "DONE";
+            FAILED: "FAILED";
+            SKIPPED: "SKIPPED";
+        }>>;
+        retries: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodTransform<{
+    dependencies: string[];
+    version: "1";
+    language: "python" | "typescript";
+    intent: "greenfield" | "feature" | "refactor" | "self";
+    projectType: "application" | "library" | "mixed";
+    requirementDigest: string;
+    globalPrompt: string;
+    baselineSummary: string;
+    userAddenda: string;
+    createdAt: string;
+    steps: {
+        id: string;
+        iterationId: string;
+        phase: "REQUIREMENT_ANALYSIS" | "HIGH_LEVEL_DESIGN" | "DETAILED_DESIGN" | "CODE" | "UNIT_TEST" | "INTEGRATION_TEST" | "MODULE_TEST" | "FUNCTIONAL_TEST" | "DEBUG";
+        title: string;
+        description: string;
+        systemPrompt: string;
+        role: "Planner" | "Architect" | "Coder" | "Tester" | "Debugger";
+        tools: string[];
+        inputs: string[];
+        outputs: string[];
+        dependsOn: string[];
+        acceptance: string;
+        status: "PENDING" | "RUNNING" | "DONE" | "FAILED" | "SKIPPED";
+        retries: number;
+        maxRetries: number;
+        subTasks?: StepSubtask[] | undefined;
+    }[];
+    complexityAssessment?: {
+        level: "simple" | "moderate" | "complex";
+        rationale: string;
+        splitRecommended: boolean;
+        userForcedPhaseSplit: boolean;
+    } | undefined;
+    implementationPhases?: {
+        id: string;
+        title: string;
+        objective: string;
+        status: "current" | "planned" | "deferred";
+        scope: string[];
+        deliverables: string[];
+        dependsOn: string[];
+        verificationGate?: {
+            summary: string;
+            checks: string[];
+            failurePolicy: string;
+        } | undefined;
+    }[] | undefined;
+    architectureModules?: {
+        id: string;
+        name: string;
+        responsibility: string;
+        sourcePaths: string[];
+        testPaths: string[];
+        dependencies: string[];
+    }[] | undefined;
+}, {
+    version: "1";
+    language: "python" | "typescript";
+    intent: "greenfield" | "feature" | "refactor" | "self";
+    projectType: "application" | "library" | "mixed";
+    requirementDigest: string;
+    globalPrompt: string;
+    baselineSummary: string;
+    userAddenda: string;
+    createdAt: string;
+    steps: {
+        id: string;
+        iterationId: string;
+        phase: "REQUIREMENT_ANALYSIS" | "HIGH_LEVEL_DESIGN" | "DETAILED_DESIGN" | "CODE" | "UNIT_TEST" | "INTEGRATION_TEST" | "MODULE_TEST" | "FUNCTIONAL_TEST" | "DEBUG";
+        title: string;
+        description: string;
+        systemPrompt: string;
+        role: "Planner" | "Architect" | "Coder" | "Tester" | "Debugger";
+        tools: string[];
+        inputs: string[];
+        outputs: string[];
+        dependsOn: string[];
+        acceptance: string;
+        status: "PENDING" | "RUNNING" | "DONE" | "FAILED" | "SKIPPED";
+        retries: number;
+        maxRetries: number;
+        subTasks?: StepSubtask[] | undefined;
+    }[];
+    complexityAssessment?: {
+        level: "simple" | "moderate" | "complex";
+        rationale: string;
+        splitRecommended: boolean;
+        userForcedPhaseSplit: boolean;
+    } | undefined;
+    implementationPhases?: {
+        id: string;
+        title: string;
+        objective: string;
+        status: "current" | "planned" | "deferred";
+        scope: string[];
+        deliverables: string[];
+        dependsOn: string[];
+        verificationGate?: {
+            summary: string;
+            checks: string[];
+            failurePolicy: string;
+        } | undefined;
+    }[] | undefined;
+    architectureModules?: {
+        id: string;
+        name: string;
+        responsibility: string;
+        sourcePaths: string[];
+        testPaths: string[];
+        dependencies: string[];
+    }[] | undefined;
+    dependencies?: string[] | undefined;
+    pythonRequirements?: string[] | undefined;
+}>>;
+type Plan = z.infer<typeof PlanSchema>;
+
+type ChatRole = 'system' | 'user' | 'assistant';
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+interface ChatOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /** Force JSON-only response if provider supports it. */
+    responseFormat?: 'text' | 'json';
+    /**
+     * 流式 token 回调。设置后 provider 会以增量方式推送 token；
+     * provider 仍会聚合并返回完整文本作为最终结果。
+     */
+    onToken?: (chunk: string) => void;
+    /**
+     * 流式模式下的“可提前结束”判定。用于兼容一些 provider：
+     * 输出内容本身已经完整，但既不及时发送 [DONE]，也不主动断开连接。
+     * 返回 true 后 provider 应尽快结束本次流读取并返回当前 aggregate。
+     */
+    streamStopWhen?: (text: string) => boolean;
+    /**
+     * 可选验证钩子：provider 返回后调用。抛异常会被 FallbackClient
+     * 视为该 provider 失败，并切换到下一个。适用于：JSON 退化、
+     * 空输出、model token loop 等“表面成功但语义不可用”场景。
+     */
+    validate?: (text: string) => void;
+    /**
+     * 调用者可传入回调，与 LLM 输出一同拿到实际产出该响应的 provider 名。
+     * 主要用于追溯：在 FallbackClient 中服务于响应的是链中某一个后选 provider，
+     * 调用者（如 Executor）需要在审计 / Markdown 记录中为响应打上正确的“via 哪个模型”标签。
+     */
+    onProvider?: (name: string) => void;
+    /**
+     * 每次开始尝试候选 provider 时触发。用于 CLI 在等待首个 token 前显示
+     * 当前 provider 与模型；fallback 切换时会再次触发。
+     */
+    onProviderStart?: (name: string, model: string) => void;
+}
+
+/**
+ * AuditLogger 把开发流水线中的所有交互/执行动作记录到两份产物：
+ *
+ *  - `docs/process_log.md` —— 人类可读的过程记录，用于交付时汇总。
+ *  - `.xcompiler/audit.jsonl`   —— 机器可读的逐行 JSON，便于后续分析与回放。
+ *
+ * 设计原则：
+ *  - 追加写入，永不删除。
+ *  - 失败时不影响主流程（写盘异常仅打印 warning）。
+ *  - 每条事件都带 ts / kind / payload。
+ */
+type AuditKind = 'session.start' | 'session.end' | 'user.input' | 'user.decision' | 'llm.request' | 'llm.response' | 'llm.error' | 'llm.score' | 'fs.write' | 'plan.persist' | 'topic.persist' | 'phase.start' | 'phase.end' | 'tool.call' | 'tool.result' | 'sandbox.exec' | 'executor.turn' | 'planner.thought' | 'conftest.autogen' | 'issue.record' | 'issue.route' | 'issue.resolve' | 'note';
+interface AuditLoggerOptions {
+    /** workspace 根目录（绝对路径） */
+    root: string;
+    /** 命令名，例如 `xcompiler_build` / `xcompiler_run` */
+    command: string;
+    /** markdown 文件相对路径，默认 docs/process_log.md */
+    mdRelPath?: string;
+    /** jsonl 文件相对路径，默认 .xcompiler/audit.jsonl */
+    jsonlRelPath?: string;
+    /** full=完整内容；redacted=保留内容但遮蔽凭据（默认）；metadata=仅保留长度与摘要。 */
+    contentMode?: AuditContentMode;
+}
+type AuditContentMode = 'full' | 'redacted' | 'metadata';
+declare class AuditLogger {
+    private readonly mdAbs;
+    private readonly jsonlAbs;
+    private readonly command;
+    private readonly contentMode;
+    private startTs;
+    /** 串行化 markdown 追加，防止并发 appendFile 交错。 */
+    private mdQueue;
+    constructor(opts: AuditLoggerOptions);
+    start(meta?: Record<string, unknown>): Promise<void>;
+    end(summary?: Record<string, unknown>): Promise<void>;
+    /** 通用事件，jsonl + 简短 markdown 一行。 */
+    event(kind: AuditKind, message: string, data?: Record<string, unknown>): Promise<void>;
+    /** 用户输入 / 决策。会把内容以引用块写入 markdown。 */
+    userInput(label: string, content: string): Promise<void>;
+    userDecision(label: string, value: string): Promise<void>;
+    /** LLM 请求/响应：完整 prompt 与回包写入 markdown 折叠块。 */
+    llmRequest(role: string, model: string, messages: unknown, options?: unknown): Promise<void>;
+    llmResponse(role: string, model: string, content: string, meta?: Record<string, unknown>): Promise<void>;
+    llmError(role: string, model: string, err: unknown): Promise<void>;
+    /**
+     * 记录一轮 Executor 思考：thoughts 文本、计划调用的 actions、是否完成。
+     * 写入 jsonl + markdown 折叠块，交付时可作为"AI 思考过程完整记录"。
+     */
+    executorTurn(stepId: string, role: string, round: number, payload: {
+        thoughts?: string;
+        actions?: unknown[];
+        done?: boolean;
+        raw?: string;
+        provider?: string;
+    }): Promise<void>;
+    /** 记录 Planner 的思考阶段，比如 clarify / decompose 原始输出。 */
+    plannerThought(stage: string, content: string, meta?: Record<string, unknown> & {
+        provider?: string;
+    }): Promise<void>;
+    private ensureFiles;
+    private appendMd;
+    private appendJsonl;
+}
+
+declare const CLARIFICATION_CATEGORIES: readonly ["functionality", "data", "acceptance", "boundary", "quality", "extensibility"];
+type ClarificationCategory = (typeof CLARIFICATION_CATEGORIES)[number];
+declare const CLARIFICATION_OPTION_LABELS: readonly ["A", "B", "C", "D", "E"];
+type ClarificationOptionLabel = (typeof CLARIFICATION_OPTION_LABELS)[number];
+interface ClarifyOption {
+    label: ClarificationOptionLabel;
+    answer: string;
+}
+interface ClarifyQuestion {
+    id: string;
+    category: ClarificationCategory;
+    question: string;
+    why: string;
+    options: ClarifyOption[];
+}
+interface PlannerInput {
+    rawRequirement: string;
+    clarifications: Array<{
+        question: string;
+        answer: string;
+        category?: ClarificationCategory;
+        why?: string;
+        options?: ClarifyOption[];
+    }>;
+    /** 用户在澄清问答后补充的自定义需求（可为空）。 */
+    userAddenda?: string;
+    /** 增量开发时，现有工程基线摘要（文档 / 计划 / 源码树）。 */
+    baselineContext?: string;
+    /** 计划意图：greenfield / feature / refactor / self。 */
+    intent?: PlanIntent;
+}
+
+declare class Workspace {
+    readonly root: string;
+    constructor(root: string);
+    abs(...p: string[]): string;
+    ensure(dir: string): Promise<void>;
+    writeFile(rel: string, content: string): Promise<void>;
+    readFile(rel: string): Promise<string>;
+    exists(rel: string): Promise<boolean>;
+    remove(rel: string): Promise<void>;
+}
+
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+interface ExecExtra {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** 沙盒统一接口。任意 phase / tool 都通过此接口与运行时交互。 */
+interface Sandbox {
+    /** 实现标识，便于审计与日志区分。 */
+    readonly kind: 'subprocess' | 'docker';
+    /**
+     * 构建/复用环境。
+     *  - Python：`pip install -r requirements.txt` + venv。
+     *  - TypeScript：`npm install`（依据 package.json）。
+     * manifestFile 为依赖清单在 workspace 内的相对路径；不存在则跳过安装。
+     * 返回是否真正重建。
+     */
+    build(manifestFile?: string): Promise<{
+        rebuilt: boolean;
+        reason: string;
+    }>;
+    /** 执行任意命令；cmd 视实现可能是宿主路径或容器内路径。 */
+    exec(cmd: string, argv: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 运行工程入口程序。
+     *  - Python：`python <args>`（自动选用 venv 内解释器）。
+     *  - TypeScript：`npx tsx <args>`。
+     */
+    runProgram(args: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 运行测试套件。
+     *  - Python：`python -m pytest <args>`。
+     *  - TypeScript：`npm test`（Vitest）。
+     */
+    runTests(args?: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 安装额外依赖（不写入依赖清单）。
+     *  - Python：`pip install <packages>`。
+     *  - TypeScript：`npm install <packages>`。
+     */
+    installDeps(packages: string[]): Promise<ExecResult>;
+}
+
+type ToolPermissionOperation = 'shell_command' | 'file_write' | 'file_delete' | 'install_dependency' | 'config_change' | 'git_operation' | 'network_access' | 'test_command' | 'build_command' | 'external_read' | 'external_write';
+interface ToolPermissionRequest {
+    id?: string;
+    operationType: ToolPermissionOperation;
+    target: string;
+    reason: string;
+    risk: string;
+    scope: string;
+    skippable: boolean;
+    denyBehavior: string;
+    stepId?: string;
+    tool?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ToolPermissionDecision {
+    approved: boolean;
+    reason?: string;
+}
+type ToolPermissionRequester = (request: ToolPermissionRequest) => Promise<ToolPermissionDecision>;
+interface ToolExecutionEvent {
+    status: 'started' | 'completed';
+    stepId: string;
+    tool: string;
+    target?: string;
+    args?: Record<string, unknown>;
+    ok?: boolean;
+    summary?: string;
+    error?: string;
+    changedFiles?: string[];
+    patch?: string;
+}
+type ToolExecutionReporter = (event: ToolExecutionEvent) => void | Promise<void>;
+/** 工具调用的统一上下文。 */
+interface ToolContext {
+    ws: Workspace;
+    sandbox: Sandbox;
+    audit?: AuditLogger;
+    /** 当前 Step 的 outputs 白名单（写操作必须落在白名单内）。 */
+    allowedWrites: string[];
+    /** 当前 Step 的 id（仅用于审计）。 */
+    stepId: string;
+    /** 目标语言（决定依赖清单文件等）。默认 python。 */
+    language?: Language;
+    /** 当前 Step 的 write_file / append_file 单次 content 字节预算。 */
+    writeChunkBytes?: number;
+    /** Optional protocol/UI permission hook for sensitive tool operations. */
+    requestPermission?: ToolPermissionRequester;
+    /** Optional protocol/UI event hook for tool calls and file changes. */
+    onToolEvent?: ToolExecutionReporter;
+}
+/** 单次工具调用的结果统一结构。 */
+interface ToolResult<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    /** 用于摘要展示。 */
+    summary?: string;
+}
+interface Tool<A = unknown, R = unknown> {
+    readonly name: string;
+    readonly description: string;
+    /** 简要 JSON Schema 描述参数（仅用于 prompt，不强校验）。 */
+    readonly argsSchema: Record<string, unknown>;
+    run(args: A, ctx: ToolContext): Promise<ToolResult<R>>;
+}
+
+/**
+ * Skill：把一组原子工具组合为面向 LLM 的"高阶能力"。
+ *
+ * 在 M3 阶段 Skill 是一层"语义包装"——执行器仍然按 step.tools 中的工具名调用具体 Tool，
+ * 但 Step 可以声明 `tools: ["skill:patcher"]`，Skill Registry 会展开为底层工具集合，
+ * 并把 Skill 的 `prompt` 注入 system prompt，提示 LLM 该如何组合这些工具。
+ */
+interface Skill {
+    /** 形如 `patcher` / `tester` / `dep_resolver`。 */
+    readonly name: string;
+    /** 注入到 system prompt 的简短指引（中文一句话）。 */
+    readonly prompt: string;
+    /** 该 Skill 暴露给 LLM 的底层工具名集合。 */
+    readonly tools: string[];
+}
+
+interface EngineRunSummary {
+    totalSteps: number;
+    executedSteps: number;
+    failedStepId?: string;
+    failureLog?: string;
+    failureReason?: string;
+}
+interface StepAttemptOutcome {
+    ok: boolean;
+    failureLog: string;
+    reason?: string;
+}
+/**
+ * XCompiler 的公共生命周期 Hook。
+ *
+ * Context 对象会按顺序传给所有 handler；插件可以原位补充或调整字段，但不得替换
+ * workspace / audit 等核心服务。涉及文件写入时仍必须通过 Tool 与 EditGuard。
+ */
+interface HookContextMap {
+    'compile.start': {
+        workspace: string;
+        intent: PlanIntent;
+        topicMode: boolean;
+    };
+    'compile.afterClarify': {
+        rawRequirement: string;
+        questions: ClarifyQuestion[];
+        clarifications: PlannerInput['clarifications'];
+        userAddenda: string;
+    };
+    'compile.beforeDecompose': {
+        input: PlannerInput;
+    };
+    'compile.afterPlan': {
+        plan: Plan;
+    };
+    'compile.finish': {
+        plan: Plan;
+        planPath: string;
+    };
+    'run.before': {
+        plan: Plan;
+    };
+    'run.after': {
+        plan: Plan;
+        result: EngineRunSummary;
+    };
+    'run.error': {
+        plan: Plan;
+        error: unknown;
+    };
+    'step.before': {
+        plan: Plan;
+        step: Step;
+    };
+    'step.after': {
+        plan: Plan;
+        step: Step;
+        ok: boolean;
+    };
+    'step.error': {
+        plan: Plan;
+        step: Step;
+        error: unknown;
+    };
+    'step.attempt.before': {
+        plan: Plan;
+        step: Step;
+        role: Role;
+        debug: boolean;
+        retry: number;
+    };
+    'step.attempt.after': {
+        plan: Plan;
+        step: Step;
+        role: Role;
+        debug: boolean;
+        retry: number;
+        outcome: StepAttemptOutcome;
+    };
+    'tool.before': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+    };
+    'tool.after': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+        result: ToolResult;
+    };
+    'tool.error': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+        error: unknown;
+    };
+    'llm.before': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        options?: ChatOptions;
+    };
+    'llm.after': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        response: string;
+        durationMs: number;
+    };
+    'llm.error': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        error: unknown;
+        durationMs: number;
+    };
+}
+type HookName = keyof HookContextMap;
+type HookHandler<K extends HookName> = (context: HookContextMap[K]) => void | Promise<void>;
+interface HookRegistrationOptions {
+    /** 数值越大越先执行；相同优先级保持插件及注册顺序。 */
+    priority?: number;
+}
+interface PluginApi {
+    /** 当前 XCompiler 核心版本。 */
+    readonly xcompilerVersion: string;
+    /** 当前插件 API 主版本；仅同一主版本兼容。 */
+    readonly pluginApiVersion: number;
+    on<K extends HookName>(hook: K, handler: HookHandler<K>, options?: HookRegistrationOptions): () => void;
+    registerTool(tool: Tool): void;
+    registerSkill(skill: Skill): void;
+}
+/** 可序列化的插件清单；后续 registry / marketplace 不需要加载插件代码即可读取。 */
+interface XCompilerPluginManifest {
+    /** 全局唯一且稳定的插件 ID，例如 `company.policy-checker`。 */
+    id: string;
+    /** 插件自身版本，必须是完整 SemVer。 */
+    version: string;
+    /** 插件编译时面向的 XCompiler Plugin API 主版本。 */
+    apiVersion: number;
+    /** 插件可运行的最低 XCompiler 核心版本；必填完整 SemVer。 */
+    minXCompilerVersion: string;
+    /** 以下字段用于插件目录展示，不参与运行时兼容判定。 */
+    displayName?: string;
+    description?: string;
+    license?: string;
+    homepage?: string;
+    keywords?: string[];
+}
+interface XCompilerPlugin {
+    manifest: XCompilerPluginManifest;
+    /** 默认 continue：记录错误但不拖垮核心流程。 */
+    failureMode?: 'continue' | 'fail';
+    setup(api: PluginApi): void | Promise<void>;
+}
+
+type RuntimeLogLevel = 'success' | 'warning' | 'error' | 'info' | 'dim' | 'accent' | 'raw';
+
+interface RuntimeLogEvent {
+    type: 'log';
+    level: RuntimeLogLevel;
+    message: string;
+}
+interface RuntimeResultEvent {
+    type: 'result';
+    command: 'build' | 'run';
+    status: string;
+    data?: Record<string, unknown>;
+}
+interface RuntimeProgressEvent {
+    type: 'progress';
+    status: 'start' | 'succeed' | 'fail';
+    message: string;
+}
+interface RuntimeToolCallEvent {
+    type: 'tool_call';
+    status: ToolExecutionEvent['status'];
+    stepId: string;
+    tool: string;
+    target?: string;
+    ok?: boolean;
+    summary?: string;
+    error?: string;
+}
+interface RuntimeFileChangedEvent {
+    type: 'file_changed';
+    stepId: string;
+    tool: string;
+    path: string;
+}
+interface RuntimePatchProposedEvent {
+    type: 'patch_proposed';
+    stepId: string;
+    tool: string;
+    patch: string;
+}
+interface RuntimePermissionEvent {
+    type: 'permission';
+    status: 'requested' | 'approved' | 'denied';
+    request: ToolPermissionRequest;
+}
+type RuntimeEvent = RuntimeLogEvent | RuntimeProgressEvent | RuntimeResultEvent | RuntimeToolCallEvent | RuntimeFileChangedEvent | RuntimePatchProposedEvent | RuntimePermissionEvent;
+interface RuntimeProgress {
+    succeed(message: string): void | Promise<void>;
+    fail(message: string): void | Promise<void>;
+    stop?(): void | Promise<void>;
+}
+interface RuntimeSelectChoice<T extends string = string> {
+    name: string;
+    value: T;
+}
+interface RuntimeInteraction {
+    input(args: {
+        message: string;
+    }): Promise<string>;
+    confirm(args: {
+        message: string;
+        default?: boolean;
+    }): Promise<boolean>;
+    editor(args: {
+        message: string;
+        default?: string;
+        postfix?: string;
+    }): Promise<string>;
+    select<T extends string>(args: {
+        message: string;
+        choices: RuntimeSelectChoice<T>[];
+    }): Promise<T>;
+    readMultiline(args: {
+        message: string;
+    }): Promise<string>;
+    pauseStdin?(): void;
+}
+interface RuntimeIO {
+    emit(event: RuntimeEvent): void | Promise<void>;
+    progress(message: string, opts?: {
+        animate?: boolean;
+    }): RuntimeProgress;
+    interaction?: RuntimeInteraction;
+    requestPermission?: ToolPermissionRequester;
+}
+
+interface CompileOptions {
+    workspace: string;
+    configPath?: string;
+    inputFile?: string;
+    /**
+     * 已澄清的 topic.md 直接输入：跳过 intake / clarify / Addenda / Gate 1，把该文件
+     * 内容当作冻结后的项目选题书，直接进入 decompose。常用于：
+     *   - 用户上次已澄清并保留了 topic.md，重新跑 decompose 不想再问一遍
+     *   - 离线编辑了 topic.md 想直接拿来出 plan.json
+     * 与 --input 互斥；同时给则 --topic 优先并打印警告。
+     */
+    topicFile?: string;
+    outputFile?: string;
+    intent?: PlanIntent;
+    baselinePlanFile?: string;
+    yes?: boolean;
+    force?: boolean;
+    /** Optional XXX.xc project file to create/update with config, plan, and progress. */
+    projectFilePath?: string;
+    /** Project-file history command label; defaults to build. */
+    projectCommand?: string;
+    /** 程序化插件入口；动态插件加载将在后续版本基于它实现。 */
+    plugins?: XCompilerPlugin[];
+    pluginStrict?: boolean;
+    /** Runtime event and interaction adapter. CLI supplies a terminal implementation; SDKs may stay silent. */
+    io?: RuntimeIO;
+}
+
+interface ProjectAuditCheck {
+    name: string;
+    severity: 'error' | 'warn' | 'info';
+    ok: boolean;
+    summary: string;
+    detail?: string;
+}
+interface ProjectAuditResult {
+    ok: boolean;
+    warnings: number;
+    errors: number;
+    checks: ProjectAuditCheck[];
+    scope?: 'project' | 'iteration';
+    iterationId?: string;
+}
+
+interface EngineResult {
+    totalSteps: number;
+    executedSteps: number;
+    failedStepId?: string;
+    /** 失败 Step 的最终详细日志（reason + tool calls + 健康度）。 */
+    failureLog?: string;
+    failureReason?: string;
+}
+
+interface ExecuteOptions {
+    planPath: string;
+    workspace: string;
+    configPath?: string;
+    dryRun?: boolean;
+    fromStepId?: string;
+    onlyPhase?: string;
+    resetStatus?: boolean;
+    force?: boolean;
+    /** Optional XXX.xc project file to keep in sync with execution progress. */
+    projectFilePath?: string;
+    /** Project-file history command label; defaults to run. */
+    projectCommand?: string;
+    /** Whether to append a history row when execution starts; defaults to true. */
+    recordProjectHistory?: boolean;
+    /** @deprecated Runtime never mutates the host process. CLI adapters translate ExecuteResult to exit codes. */
+    setProcessExitCode?: boolean;
+    /** 程序化插件入口；CLI 文件加载器后续基于该入口实现。 */
+    plugins?: XCompilerPlugin[];
+    pluginStrict?: boolean;
+    /** Runtime event and interaction adapter. CLI supplies terminal rendering; SDKs may stay silent. */
+    io?: RuntimeIO;
+    /** Allow human terminal progress from lower-level engines. Defaults to true for CLI compatibility. */
+    terminalOutput?: boolean;
+}
+interface ExecuteResult {
+    status: 'ok' | 'failed' | 'error' | 'dry-run';
+    engine?: EngineResult;
+    audit?: ProjectAuditResult;
+    message?: string;
+    exitCode?: number;
+}
+
+interface WorkspaceOptions {
+    output?: string;
+    workspace?: string;
+    baseDir?: string;
+    name?: string;
+}
+
+type RuntimeBuildCommandOptions = Omit<CompileOptions, 'workspace'> & WorkspaceOptions;
+interface RuntimeBuildCommandResult {
+    workspace: string;
+    planPath?: string;
+}
+type RuntimeRunCommandOptions = Omit<ExecuteOptions, 'planPath' | 'workspace' | 'projectCommand'> & {
+    planArg?: string;
+    output?: string;
+    workspace?: string;
+    cwd?: string;
+};
+
+interface AcpInitializeResult {
+    protocolVersion: number;
+    agentInfo: {
+        name: 'xcompiler';
+        title: string;
+        version: string;
+    };
+    agentCapabilities: {
+        loadSession: boolean;
+        promptCapabilities: {
+            image: boolean;
+            audio: boolean;
+            embeddedContext: boolean;
+        };
+        mcpCapabilities: {
+            http: boolean;
+            sse: boolean;
+        };
+        sessionCapabilities: {
+            close: Record<string, never>;
+        };
+        auth: Record<string, never>;
+    };
+    authMethods: unknown[];
+}
+interface AcpSession {
+    id: string;
+    workspace?: string;
+    createdAt: string;
+    tasks: Map<string, AcpTask>;
+    pendingInteractions: Map<string, PendingInteraction>;
+    pendingPermissions: Map<string, PendingPermission>;
+}
+type AcpTaskStatus = 'running' | 'waiting_for_confirmation' | 'waiting_for_permission' | 'completed' | 'failed' | 'cancel_requested' | 'cancelled';
+interface AcpTask {
+    id: string;
+    sessionId: string;
+    status: AcpTaskStatus;
+    workspace: string;
+    userTask: string;
+    protocol: 'acp' | 'legacy';
+    phase: 'build' | 'run' | 'complete';
+    planPath?: string;
+    changedFiles: string[];
+    startedAt: string;
+    completedAt?: string;
+    cancellationRequested?: boolean;
+}
+interface PendingInteraction {
+    id: string;
+    taskId: string;
+    sessionId: string;
+    phase: 'build' | 'run';
+    kind: 'input' | 'confirm' | 'select' | 'editor' | 'multiline';
+    message: string;
+    choices?: Array<{
+        name: string;
+        value: string;
+    }>;
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+}
+interface PendingPermission {
+    id: string;
+    taskId: string;
+    sessionId: string;
+    request: unknown;
+    resolve: (approved: boolean, reason?: string) => void;
+    reject: (reason: Error) => void;
+}
+interface AcpCodeTaskParams {
+    sessionId: string;
+    workspace: string;
+    task: string;
+    configPath?: string;
+    intent?: RuntimeBuildCommandOptions['intent'];
+    requirePlanConfirmation?: boolean;
+    autoRunAfterBuild?: boolean;
+    force?: boolean;
+}
+interface AcpRuntimeFacade {
+    build(opts: RuntimeBuildCommandOptions): Promise<RuntimeBuildCommandResult>;
+    run(opts: RuntimeRunCommandOptions): Promise<ExecuteResult>;
+}
+interface AcpServerLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+interface AcpServerOptions {
+    runtime?: AcpRuntimeFacade;
+    logger?: AcpServerLogger;
+}
+
+declare class AcpSessionStore {
+    private readonly sessions;
+    create(workspace?: string): AcpSession;
+    get(sessionId: string): AcpSession;
+    close(sessionId: string): void;
+    closeAll(): void;
+    createTask(session: AcpSession, input: {
+        workspace: string;
+        userTask: string;
+        protocol: 'acp' | 'legacy';
+    }): AcpTask;
+    getTask(sessionId: string, taskId: string): AcpTask;
+    addInteraction(session: AcpSession, pending: PendingInteraction): void;
+    resolveInteraction(sessionId: string, requestId: string, value: unknown): void;
+    addPermission(session: AcpSession, pending: PendingPermission): void;
+    resolvePermission(sessionId: string, requestId: string, approved: boolean, reason?: string): void;
+}
+
+interface AcpTransport {
+    send(message: JsonRpcMessage): void;
+    onMessage(handler: (message: unknown) => void | Promise<void>): void;
+    onClose(handler: () => void | Promise<void>): void;
+    start(): Promise<void>;
+    close(): void;
+}
+declare class StdioTransport implements AcpTransport {
+    private readonly input;
+    private readonly output;
+    private messageHandler;
+    private closeHandler;
+    private closed;
+    private rl?;
+    constructor(input?: Readable, output?: Writable);
+    send(message: JsonRpcMessage): void;
+    onMessage(handler: (message: unknown) => void | Promise<void>): void;
+    onClose(handler: () => void | Promise<void>): void;
+    start(): Promise<void>;
+    close(): void;
+}
+
+declare class AcpServer {
+    readonly sessions: AcpSessionStore;
+    private readonly runtime;
+    private readonly logger;
+    private readonly pendingClientRequests;
+    private transport?;
+    constructor(opts?: AcpServerOptions);
+    start(transport: AcpTransport): Promise<void>;
+    handleMessage(message: unknown): Promise<JsonRpcMessage | undefined>;
+    private dispatchRequest;
+    private dispatchNotification;
+    private initialize;
+    private createSession;
+    private closeSession;
+    private prompt;
+    private startTask;
+    private cancelTask;
+    private respondConfirmation;
+    private respondPermission;
+    private runCodeTask;
+    private createRuntimeIO;
+    private createInteraction;
+    private requestInteraction;
+    private requestPermission;
+    private runtimeProgress;
+    private dispatchClientResponse;
+    private notifyTask;
+    private notifyUpdate;
+    private errorResponse;
+}
+
+declare function runAcpStdioServer(): Promise<void>;
+
+export { type AcpCodeTaskParams, type AcpInitializeResult, AcpMethod, type AcpRuntimeFacade, AcpServer, type AcpServerLogger, type AcpServerOptions, type AcpSession, type AcpTask, type AcpTransport, JsonRpcErrorCode, type JsonRpcFailure, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcSuccess, StdioTransport, runAcpStdioServer };