@autopilot-agent/cli 0.0.0-stage → 0.1.0

package/dist/design-tokens.d.ts

@@ -0,0 +1,34 @@
+/** CLI TUI 语义色 token；组件只引用 token，不直接写危险态颜色。 */
+export declare const CLI_TUI_COLORS: {
+    readonly accent: "ansi256(208)";
+    readonly permissionFullAccess: "#ff6b80";
+    readonly copilotBlue: "ansi256(33)";
+    readonly copilotBlueBright: "ansi256(39)";
+    readonly copilotPurple: "ansi256(99)";
+    readonly copilotGreen: "ansi256(77)";
+    readonly copilotInk: "ansi256(255)";
+    readonly copilotMuted: "ansi256(246)";
+    readonly copilotOutline: "ansi256(243)";
+};
+/** Design.md 中橙色强调色的 ANSI 256 语义映射；NO_COLOR 时完全不输出颜色。 */
+export declare const TUI_ACCENT_COLOR: "ansi256(208)";
+/** 工具徽标 chip 的强调背景色；与唯一强调色同源，只用于标注当前活动步骤。 */
+export declare const TUI_ACCENT_BG_COLOR: "ansi256(208)";
+/** 工具徽标 chip 上的深色粗体文字色；对应 Web 的 text-ink-on-dark 槽位语义。 */
+export declare const TUI_CHIP_TEXT_COLOR = "ansi256(16)";
+/** 工具成功 glyph 的辅助绿；状态永远带文字标签，不靠颜色传达。 */
+export declare const TUI_TOOL_SUCCESS_COLOR = "ansi256(46)";
+/** 工具失败文字的辅助红；状态永远带文字标签，不靠颜色传达。 */
+export declare const TUI_TOOL_ERROR_COLOR = "ansi256(196)";
+/** Skill 已启用开关的语义色。 */
+export declare const TUI_SKILL_ON_COLOR = "ansi256(46)";
+/** Skill 未启用开关的语义色。 */
+export declare const TUI_SKILL_OFF_COLOR = "ansi256(196)";
+/** 动态等待区（引导/排队输入）的背景色。 */
+export declare const TUI_WAITING_BACKGROUND_COLOR = "ansi256(236)";
+/** unified diff 新增行的语义色。 */
+export declare const TUI_DIFF_ADDED_COLOR = "ansi256(46)";
+/** unified diff 删除行的语义色。 */
+export declare const TUI_DIFF_REMOVED_COLOR = "ansi256(196)";
+/** 输入区（prompt）的背景色。 */
+export declare const TUI_PROMPT_BACKGROUND_COLOR = "ansi256(236)";

package/dist/design-tokens.js

@@ -0,0 +1,34 @@
+/** CLI TUI 语义色 token；组件只引用 token，不直接写危险态颜色。 */
+export const CLI_TUI_COLORS = {
+    accent: "ansi256(208)",
+    permissionFullAccess: "#ff6b80",
+    copilotBlue: "ansi256(33)",
+    copilotBlueBright: "ansi256(39)",
+    copilotPurple: "ansi256(99)",
+    copilotGreen: "ansi256(77)",
+    copilotInk: "ansi256(255)",
+    copilotMuted: "ansi256(246)",
+    copilotOutline: "ansi256(243)",
+};
+/** Design.md 中橙色强调色的 ANSI 256 语义映射；NO_COLOR 时完全不输出颜色。 */
+export const TUI_ACCENT_COLOR = CLI_TUI_COLORS.accent;
+/** 工具徽标 chip 的强调背景色；与唯一强调色同源，只用于标注当前活动步骤。 */
+export const TUI_ACCENT_BG_COLOR = CLI_TUI_COLORS.accent;
+/** 工具徽标 chip 上的深色粗体文字色；对应 Web 的 text-ink-on-dark 槽位语义。 */
+export const TUI_CHIP_TEXT_COLOR = "ansi256(16)";
+/** 工具成功 glyph 的辅助绿；状态永远带文字标签，不靠颜色传达。 */
+export const TUI_TOOL_SUCCESS_COLOR = "ansi256(46)";
+/** 工具失败文字的辅助红；状态永远带文字标签，不靠颜色传达。 */
+export const TUI_TOOL_ERROR_COLOR = "ansi256(196)";
+/** Skill 已启用开关的语义色。 */
+export const TUI_SKILL_ON_COLOR = "ansi256(46)";
+/** Skill 未启用开关的语义色。 */
+export const TUI_SKILL_OFF_COLOR = "ansi256(196)";
+/** 动态等待区（引导/排队输入）的背景色。 */
+export const TUI_WAITING_BACKGROUND_COLOR = "ansi256(236)";
+/** unified diff 新增行的语义色。 */
+export const TUI_DIFF_ADDED_COLOR = "ansi256(46)";
+/** unified diff 删除行的语义色。 */
+export const TUI_DIFF_REMOVED_COLOR = "ansi256(196)";
+/** 输入区（prompt）的背景色。 */
+export const TUI_PROMPT_BACKGROUND_COLOR = "ansi256(236)";

package/dist/error-diagnostics.d.ts

@@ -0,0 +1,8 @@
+/** CLI 内部错误的安全分类：只返回封闭类别与稳定错误码，不读取异常正文。 */
+export type CliErrorCategory = "config_directory" | "workspace_trust" | "agent_runtime" | "node_state" | "node_chat" | "unknown";
+export interface CliErrorClassification {
+    category: CliErrorCategory;
+    code: string;
+}
+/** 只从稳定异常类型与显式码白名单分类；未知或被篡改的码会回退到通用标记。 */
+export declare function classifyCliError(error: unknown): CliErrorClassification;

package/dist/error-diagnostics.js

@@ -0,0 +1,62 @@
+/** CLI 内部错误的安全分类：只返回封闭类别与稳定错误码，不读取异常正文。 */
+import { NodeChatError, NodeStateError } from "@autopilot-agent/adapters";
+import { AgentRuntimeError, WorkspaceTrustError } from "@autopilot-agent/core";
+const agentErrorCodes = new Set([
+    "SESSION_MODE_MISMATCH", "CHAT_RETRIEVAL_MODE_LOCKED", "CHAT_TOOL_FORBIDDEN", "CHAT_RAG_EVIDENCE_INSUFFICIENT",
+    "WORKSPACE_REQUIRED", "WORK_HISTORY_READ_ONLY", "SESSION_NOT_FOUND", "SESSION_TITLE_INVALID", "TURN_NOT_FOUND",
+    "TURN_NOT_RESUMABLE", "TURN_ALREADY_RUNNING", "CHECKPOINT_NOT_FOUND", "PROJECT_NOT_FOUND", "NOT_IMPLEMENTED",
+    "RUNTIME_ERROR", "INVALID_RUN_CONFIG", "PROVIDER_UNAUTHORIZED", "MODEL_NOT_FOUND", "MODEL_NOT_SUPPORTED",
+    "REASONING_EFFORT_NOT_SUPPORTED", "TURN_FROZEN_MISMATCH", "CREDENTIAL_REF_INVALID", "MISSING_CREDENTIAL",
+    "PROVIDER_PROTOCOL_REQUIRED", "UNSUPPORTED_API_PROTOCOL", "INVALID_PROTOCOL_PROFILE", "DUPLICATE_API_PROTOCOL_ADAPTER",
+    "CANONICAL_MESSAGE_INVALID", "APPROVAL_NOT_FOUND", "APPROVAL_MISMATCH", "APPROVAL_ALREADY_SUBMITTED",
+    "QUESTION_NOT_FOUND", "QUESTION_ALREADY_ANSWERED", "QUESTION_ANSWER_INVALID", "QUESTION_TURN_STATE_INVALID",
+    "JOB_NOT_FOUND", "JOB_INPUT_INVALID", "JOB_CURSOR_INVALID", "JOB_OWNER_UNAVAILABLE", "JOB_OWNER_UNKNOWN",
+    "JOB_STATE_CONFLICT", "JOB_STOP_TIMEOUT", "JOB_STOP_FAILED", "JOB_STORAGE_FAILED", "JOB_SPAWN_FAILED",
+    "JOB_STORE_CAPABILITY_UNSUPPORTED", "SESSION_HAS_ACTIVE_JOBS", "INTERACTIVE_TOOL_CONFLICT", "INBOX_INPUT_NOT_FOUND",
+    "INVALID_INPUT",
+]);
+const nodeStateErrorCodes = new Set([
+    "STATE_SESSION_CORRUPTED", "STATE_STORAGE_UNAVAILABLE", "STATE_STORAGE_UNSAFE_PATH", "STATE_SCHEMA_UNSAFE_PATH",
+    "STATE_SCHEMA_BUSY", "STATE_SCHEMA_RECOVERY_REQUIRED", "STATE_SCHEMA_MANIFEST_CORRUPTED", "STATE_SCHEMA_VERSION_INVALID",
+    "STATE_SCHEMA_VERSION_UNSUPPORTED", "STATE_SCHEMA_MIGRATION_MISSING", "STATE_SCHEMA_MIGRATION_FAILED",
+]);
+const nodeChatErrorCodes = new Set([
+    "CHAT_STATE_ROOT_INVALID", "CHAT_ATTACHMENT_UNAVAILABLE", "CHAT_ATTACHMENT_CANCELLED", "CHAT_ATTACHMENT_PARSER_UNAVAILABLE",
+    "CHAT_ATTACHMENT_CLEANUP_FAILED", "CHAT_SESSION_DELETING", "CHAT_UPLOAD_MODE_MISMATCH", "CHAT_ATTACHMENT_STORE_REQUIRED",
+    "CHAT_KNOWLEDGE_UNAVAILABLE",
+]);
+const configDirectoryErrorCodes = new Set([
+    "AUTOPILOT_HOME_UNRESOLVED", "AUTOPILOT_CONFIG_ROOT_NOT_DIRECTORY", "AUTOPILOT_CONFIG_ROOT_UNSAFE_LINK",
+    "AUTOPILOT_CONFIG_ROOT_UNAVAILABLE",
+]);
+/** 只从稳定异常类型与显式码白名单分类；未知或被篡改的码会回退到通用标记。 */
+export function classifyCliError(error) {
+    try {
+        if (hasStableConfigDirectoryErrorCode(error))
+            return { category: "config_directory", code: error.code };
+        if (error instanceof WorkspaceTrustError)
+            return { category: "workspace_trust", code: "WORKSPACE_TRUST_REQUIRED" };
+        if (error instanceof AgentRuntimeError) {
+            const code = agentErrorCodes.has(error.code) ? error.code : "AGENT_RUNTIME_ERROR";
+            return { category: "agent_runtime", code };
+        }
+        if (error instanceof NodeStateError) {
+            const code = nodeStateErrorCodes.has(error.code) ? error.code : "NODE_STATE_ERROR";
+            return { category: "node_state", code };
+        }
+        if (error instanceof NodeChatError) {
+            const code = nodeChatErrorCodes.has(error.code) ? error.code : "NODE_CHAT_ERROR";
+            return { category: "node_chat", code };
+        }
+    }
+    catch {
+        return { category: "unknown", code: "CLI_RUNTIME_ERROR" };
+    }
+    return { category: "unknown", code: "CLI_RUNTIME_ERROR" };
+}
+/** 只接受 CLI 已公开的配置目录错误码，不回显任意对象上的 code 字符串。 */
+function hasStableConfigDirectoryErrorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        && typeof error.code === "string"
+        && configDirectoryErrorCodes.has(error.code);
+}

package/dist/event-projector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI AgentEvent 安全投影器。
+ *
+ * 它在宿主边界补充本地 seq，并把 Core 事件归约为不包含 checkpoint、冻结
+ * 工具输入、raw reasoning 或绝对受控路径的公开 ViewModel。
+ */
+import { type AgentEvent, type RecoverableTurnView } from "@autopilot-agent/core";
+import type { CliEventEnvelope, CliProjection } from "./types.js";
+/** 创建空的 CLI 投影状态。 */
+export declare function createInitialCliProjection(): CliProjection;
+/** 归约单个本地事件信封；同一 turn/seq 重复信封不会再次产生公开事件。 */
+export declare function reduceCliEvent(previous: CliProjection, envelope: CliEventEnvelope): CliProjection;
+/** 生成本地单调 seq 的事件投影器；continue 阶段沿用同一实例，不重置 seq。 */
+export declare function createCliEventProjector(options?: {
+    now?: () => Date;
+    sessionId?: string;
+}): {
+    project(event: AgentEvent): {
+        envelope: CliEventEnvelope;
+        projection: CliProjection;
+        added: boolean;
+    };
+    getProjection(): CliProjection;
+    setSessionId(sessionId: string): void;
+    restore(view: RecoverableTurnView): CliProjection;
+};

package/dist/event-projector.js

@@ -0,0 +1,333 @@
+/**
+ * CLI AgentEvent 安全投影器。
+ *
+ * 它在宿主边界补充本地 seq，并把 Core 事件归约为不包含 checkpoint、冻结
+ * 工具输入、raw reasoning 或绝对受控路径的公开 ViewModel。
+ */
+import { sanitizeAgentTerminationView } from "@autopilot-agent/core";
+import { createPresentationState, getPresentationCopy, getToolPresentationProfile, reducePresentationInput } from "@autopilot-agent/presentation";
+/** 创建空的 CLI 投影状态。 */
+export function createInitialCliProjection() {
+    return {
+        status: "idle",
+        recoverable: false,
+        answer: "",
+        activeSkills: [],
+        events: [],
+        presentation: createPresentationState(),
+        seenKeys: new Set(),
+    };
+}
+/** 将内部 checkpoint 状态映射为 CLI 可见的生命周期状态。 */
+function mapCheckpointStatus(status) {
+    if (status === "awaiting_approval")
+        return "waiting_approval";
+    if (status === "awaiting_user_input")
+        return "waiting_user_input";
+    if (status === "interrupted_recoverable")
+        return "interrupted_recoverable";
+    if (status === "interrupted")
+        return "interrupted";
+    if (status === "limit_reached")
+        return "limit_reached";
+    if (status === "completed")
+        return "completed";
+    if (status === "failed")
+        return "failed";
+    return "running";
+}
+/** 对 CLI 可见的文本做长度、路径和常见凭据字段脱敏。 */
+function sanitizeText(value, maxLength = 4_000) {
+    const text = String(value ?? "").slice(0, maxLength);
+    return text
+        .replace(/(?:[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|private|tmp|var|mnt|workspace|Volumes)\/)[^\s"'`]+/gu, "[path]")
+        .replace(/\b(api[_-]?key|access[_-]?token|password|secret|dsn)\s*[:=]\s*[^\s,;]+/giu, function redactSensitiveField(_match, key) {
+        return `${key}=[redacted]`;
+    });
+}
+/** 只保留模型/工具边界允许公开的稳定错误码。 */
+function safeErrorCode(value) {
+    const text = String(value ?? "");
+    const knownCodes = [
+        "MODEL_OUTPUT_LIMIT",
+        "EMPTY_RESPONSE",
+        "STREAM_INCOMPLETE",
+        "TOOL_CALL_INVALID_JSON",
+        "TOOL_CALL_TRUNCATED",
+        "PROVIDER_UNAUTHORIZED",
+        "MODEL_NOT_FOUND",
+        "RUNTIME_ERROR",
+        "COMMAND_FAILED",
+        "TOOL_TIMEOUT",
+    ];
+    return knownCodes.find(function findKnownCode(code) { return text.includes(code); });
+}
+/** 仅透传 Core 固定的安全终态原因，避免暴露 Provider 原文、路径或凭据。 */
+function safeTurnFailureReason(value) {
+    const text = String(value ?? "");
+    const safeReasons = [
+        "修改任务未完成写后验证，不能标记为完成",
+        "修改任务未完成真实写入，不能标记为完成",
+        "模型连续返回空响应，未执行工具或产生可显示答复",
+        "供应商连接持续失败，已停止自动恢复",
+        "供应商请求持续超时，已停止自动恢复",
+        "供应商请求持续被限流，已停止自动恢复",
+        "供应商服务持续不可用，已停止自动恢复",
+        "供应商流式响应持续中断，已停止自动恢复",
+        "模型返回非法工具参数 JSON，格式修复后仍失败",
+        "模型输出连续截断，已达到最大恢复次数",
+        "上下文溢出后已完成一次压缩重试，compact 熔断器已阻止重复请求",
+        "reactive compact 失败，已熔断以避免重复请求",
+        "Agent Loop 执行失败",
+    ];
+    return safeReasons.find(function matchSafeReason(reason) { return text === reason; });
+}
+/** 复制投影状态，确保 reducer 不修改调用方持有的旧快照。 */
+function cloneProjection(previous, envelope) {
+    const seenKeys = new Set(previous.seenKeys);
+    seenKeys.add(`${envelope.turnId}:${envelope.seq}`);
+    return {
+        ...previous,
+        turnId: envelope.turnId,
+        lastSeq: Math.max(previous.lastSeq ?? 0, envelope.seq),
+        activeSkills: previous.activeSkills.map(function copySkill(skill) { return { ...skill }; }),
+        events: [...previous.events],
+        seenKeys,
+    };
+}
+/** 比较两份 activeSkills 身份，避免 checkpoint 事件重复渲染技能记录。 */
+function sameSkills(first, second) {
+    return first.length === second.length && first.every(function matchSkill(skill, index) {
+        const other = second[index];
+        return other?.skillId === skill.skillId && other.contentHash === skill.contentHash;
+    });
+}
+/** 从 checkpoint 提取只包含 Skill 身份的安全投影。 */
+function applyCheckpoint(projection, checkpoint, seq, turnId) {
+    projection.status = mapCheckpointStatus(checkpoint.status);
+    if (checkpoint.status !== "awaiting_approval")
+        projection.pendingApproval = undefined;
+    const activeSkills = (checkpoint.activeSkills ?? []).map(function copySkill(skill) {
+        return { skillId: skill.skillId, contentHash: skill.contentHash };
+    });
+    if (sameSkills(projection.activeSkills, activeSkills))
+        return;
+    projection.activeSkills = activeSkills;
+    projection.events.push({ type: "active_skills", seq, turnId, skills: activeSkills });
+}
+/** 将安全事件追加到投影事件列表。 */
+function appendEvent(projection, event) {
+    projection.events.push(event);
+}
+/** 将一个 Core AgentEvent 归约为兼容 Plain/JSONL 的安全 CLI 公开事件。 */
+function projectEvent(envelope, projection) {
+    const event = envelope.event;
+    const base = { seq: envelope.seq, turnId: envelope.turnId };
+    switch (event.type) {
+        case "turn_started":
+            projection.status = "running";
+            projection.recoverable = false;
+            return { ...base, type: "turn_started", stepCount: event.stepCount };
+        case "reasoning_summary":
+            return { ...base, type: "reasoning_summary", summary: sanitizeText(event.summary) };
+        case "reasoning_delta":
+            return { ...base, type: "reasoning_hidden" };
+        case "answer_delta":
+            {
+                const delta = sanitizeText(event.delta);
+                projection.answer += delta;
+                return { ...base, type: "answer_delta", delta };
+            }
+        case "answer_reset":
+        case "answer_discard":
+            projection.answer = "";
+            return { ...base, type: "answer_reset" };
+        case "tool_started":
+            {
+                const profile = getToolPresentationProfile(event.toolName);
+                return {
+                    ...base,
+                    type: "tool_started",
+                    callId: event.callId,
+                    toolName: sanitizeText(event.toolName, 160),
+                    summary: getPresentationCopy(profile.runningTitleKey),
+                };
+            }
+        case "tool_progress":
+            return { ...base, type: "tool_progress", callId: event.callId, toolName: sanitizeText(event.toolName, 160), tail: sanitizeText(event.tail, 160) };
+        case "tool_result":
+            {
+                const result = event.result;
+                const errorCode = "error" in result && result.error ? safeErrorCode(result.error.code) : undefined;
+                const profile = getToolPresentationProfile(event.toolName);
+                // 展示事实由 Core 在 schema 后生成；不回读旧 event.summary/diff 或 ToolExecutionResult.output。
+                const display = result.display;
+                const diff = display?.diff?.text;
+                return {
+                    ...base,
+                    type: "tool_result",
+                    callId: event.callId,
+                    toolName: sanitizeText(event.toolName, 160),
+                    status: result.status,
+                    summary: display?.summary ?? getPresentationCopy(profile.completedTitleKey),
+                    errorCode,
+                    diff,
+                    display,
+                };
+            }
+        case "approval_required":
+            {
+                const display = event.result.approval.display;
+                const reason = display?.actionPreview ?? display?.operation ?? "需要确认";
+                const allowedDecisions = display?.allowedDecisions ?? ["deny"];
+                projection.status = "waiting_approval";
+                projection.pendingApproval = {
+                    approvalId: event.result.approval.approvalId,
+                    callId: event.callId,
+                    toolName: sanitizeText(event.toolName, 160),
+                    reason,
+                    risk: display?.risk,
+                    allowedDecisions,
+                    display,
+                };
+                return {
+                    ...base,
+                    type: "approval_required",
+                    approvalId: event.result.approval.approvalId,
+                    callId: event.callId,
+                    toolName: sanitizeText(event.toolName, 160),
+                    reason,
+                    risk: display?.risk,
+                    allowedDecisions,
+                    display,
+                };
+            }
+        case "input_queued":
+            return { ...base, type: "input_queued", inputId: event.inputId, delivery: event.delivery };
+        case "todo_updated":
+            // Todo 字段已由 Core schema 限长并拒绝路径/凭据片段；宿主只做事件转发，不解析 raw Tool args。
+            return { ...base, type: "todo_updated", todos: event.todos, counts: event.counts };
+        case "input_joined":
+        case "input_consumed":
+            applyCheckpoint(projection, event.checkpoint, envelope.seq, envelope.turnId);
+            return { ...base, type: event.type, inputId: event.inputId };
+        case "model_recovery":
+            return {
+                ...base,
+                type: "model_recovery",
+                reason: safeErrorCode(event.reason) ?? "MODEL_RECOVERY",
+                attempt: event.attempt,
+                maxAttempts: event.maxAttempts,
+            };
+        case "context_overflow":
+            applyCheckpoint(projection, event.checkpoint, envelope.seq, envelope.turnId);
+            return { ...base, type: "context_overflow" };
+        case "context_compact_started":
+            return { ...base, type: "context_compact_started" };
+        case "context_compacted":
+            return { ...base, type: "context_compacted", preTokens: event.preTokens, postTokens: event.postTokens };
+        case "context_compact_failed":
+            return { ...base, type: "context_compact_failed" };
+        case "context_compact_circuit_open":
+            return { ...base, type: "context_compact_circuit_open" };
+        case "context_usage_updated":
+            // Core 出口已对 usage 做白名单投影；它只刷新状态栏事实，不进入 transcript 时间线。
+            projection.contextUsage = event.usage;
+            return { ...base, type: "context_usage", usage: event.usage };
+        case "turn_paused":
+        case "turn_completed":
+        case "turn_interrupted":
+        case "turn_failed":
+        case "turn_limit_reached":
+            applyCheckpoint(projection, event.checkpoint, envelope.seq, envelope.turnId);
+            {
+                const termination = sanitizeAgentTerminationView(event.termination);
+                projection.recoverable = termination?.recoverable === true;
+            }
+            if (event.type === "turn_failed") {
+                const failedStatus = projection.status === "idle" ? "failed" : projection.status;
+                const termination = sanitizeAgentTerminationView(event.termination);
+                return {
+                    ...base,
+                    type: "status",
+                    status: failedStatus,
+                    code: safeErrorCode(event.error) ?? "RUNTIME_ERROR",
+                    reason: termination?.reason ? undefined : safeTurnFailureReason(event.error),
+                    ...(termination ? { termination } : {}),
+                };
+            }
+            const status = projection.status === "idle" ? "running" : projection.status;
+            const termination = sanitizeAgentTerminationView(event.termination);
+            return { ...base, type: "status", status, ...(termination ? { termination } : {}) };
+    }
+}
+/** 归约单个本地事件信封；同一 turn/seq 重复信封不会再次产生公开事件。 */
+export function reduceCliEvent(previous, envelope) {
+    const key = `${envelope.turnId}:${envelope.seq}`;
+    if (previous.seenKeys.has(key))
+        return previous;
+    const next = cloneProjection(previous, envelope);
+    next.presentation = reducePresentationInput(previous.presentation, {
+        kind: "runtime_event",
+        envelope: {
+            seq: envelope.seq,
+            sessionId: envelope.sessionId ?? "cli-local-session",
+            turnId: envelope.turnId,
+            timestamp: envelope.timestamp,
+            event: envelope.event,
+        },
+    });
+    const projected = projectEvent(envelope, next);
+    if (projected)
+        appendEvent(next, projected);
+    return next;
+}
+/** 生成本地单调 seq 的事件投影器；continue 阶段沿用同一实例，不重置 seq。 */
+export function createCliEventProjector(options = {}) {
+    const now = options.now ?? function currentTime() { return new Date(); };
+    const nextSeqByTurn = new Map();
+    let sessionId = options.sessionId;
+    let projection = createInitialCliProjection();
+    return {
+        project(event) {
+            const currentSeq = nextSeqByTurn.get(event.turnId) ?? 0;
+            const envelope = {
+                seq: currentSeq + 1,
+                sessionId,
+                turnId: event.turnId,
+                timestamp: now().toISOString(),
+                event,
+            };
+            nextSeqByTurn.set(event.turnId, envelope.seq);
+            const previousLength = projection.events.length;
+            projection = reduceCliEvent(projection, envelope);
+            return { envelope, projection, added: projection.events.length > previousLength };
+        },
+        getProjection() {
+            return projection;
+        },
+        setSessionId(nextSessionId) {
+            sessionId = nextSessionId;
+        },
+        restore(view) {
+            const restored = createInitialCliProjection();
+            restored.turnId = view.turnId;
+            restored.lastSeq = view.lastSeq;
+            restored.status = view.status === "awaiting_approval"
+                ? "waiting_approval"
+                : view.status === "awaiting_user_input"
+                    ? "waiting_user_input"
+                    : view.status;
+            restored.recoverable = view.recoverable;
+            if (view.termination) {
+                restored.events.push({ type: "status", seq: view.lastSeq ?? 0, turnId: view.turnId, status: restored.status, termination: sanitizeAgentTerminationView(view.termination) });
+            }
+            restored.activeSkills = view.activeSkills.map(function copySkill(skill) { return { ...skill }; });
+            if (view.approval)
+                restored.pendingApproval = { ...view.approval };
+            projection = restored;
+            nextSeqByTurn.set(view.turnId, view.lastSeq ?? 0);
+            return projection;
+        },
+    };
+}

package/dist/file-mention-context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CLI 提交侧 @文件 mention 解析：从 prompt 原文提取 @ 引用，校验工作区边界后读取文件或
+ * 列目录一层，把有界内容以 `<system-reminder>` 附加块按出现顺序拼回 content；
+ * 失败路径（未找到/越界/过大/读取失败）降级为 notice，不阻断提交。
+ */
+/** resolveFileMentionContext 依赖的最小文件系统接缝；测试可注入受控实现。 */
+export interface FileMentionFs {
+    /** 返回目标的存在性形态与字节大小；目标不存在时抛错。 */
+    stat(absolutePath: string): Promise<{
+        isFile: boolean;
+        isDirectory: boolean;
+        size: number;
+    }>;
+    /** 以 UTF-8 读取目标文件全文。 */
+    readFile(absolutePath: string): Promise<string>;
+    /** 列出目录一层条目（不递归）。 */
+    listDirectory(absolutePath: string): Promise<Array<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+}
+/** resolveFileMentionContext 的返回契约；无有效 @ 引用时 content 保持原文。 */
+export interface ResolvedFileMentionContext {
+    /** 增强后的 prompt：原文 + `<system-reminder>` 附加块（至少一个 @ 引用成功时）。 */
+    content: string;
+    /** 面向用户的失败提示，按 mention 出现顺序。 */
+    notices: string[];
+}
+/** 从 prompt 原文提取 @ 引用的相对路径；`@` 必须位于行首或空白后，去重保序，`\` 归一为 `/`。 */
+export declare function extractFileMentions(content: string): string[];
+/** 解析 prompt 中的全部 @ 引用并构造增强 content；至少一个引用成功时在原文后追加附加块。 */
+export declare function resolveFileMentionContext(content: string, workspaceRoot: string, options?: {
+    fs?: FileMentionFs;
+}): Promise<ResolvedFileMentionContext>;