minimal-agent 0.10.0 → 0.12.0

package/src/types.ts

@@ -0,0 +1,960 @@
+/**
+ * ============================================================
+ *  src/types.ts —— 全局核心类型定义
+ * ------------------------------------------------------------
+ *  这个文件是项目的"类型字典"，所有模块都从这里 import 类型。
+ *  新手阅读建议：从上往下，每个类型上方有"何时用 / 为何这么设计"的注释。
+ *
+ *  设计原则：
+ *  - 形状跟 OpenAI Chat Completions API 对齐（多 provider 兼容性最好）
+ *  - 不用 class，全用 interface / type alias（更轻、更易读）
+ *  - 一切尽量简单：能用基本类型就不引第三方
+ * ============================================================
+ */
+
+import type { z } from 'zod';
+import type { AskQuestionSpec, AskQueueState, AskSource } from './askBridge.js';
+import type { ToolGate } from './toolGate.js';
+
+// ---------------- 1. 消息 (Message) ----------------
+//
+// Message 是 LLM 对话历史的最小单元，会被原样发到 LLM，也会被压缩、保存、回放。
+// 我们采用 OpenAI Chat Completions 的形态（role + content + tool_calls/tool_call_id），
+// 因为 DeepSeek、月之暗面、智谱、火山、OpenRouter 等绝大多数中国 / 国际 provider
+// 都按此协议兼容。
+//
+// 四种 role：
+//   system    —— 系统提示词，固定放在最前面
+//   user      —— 用户输入
+//   assistant —— 模型回答（可能含 tool_calls 表示要调工具）
+//   tool      —— 工具执行结果，必须配对一个 tool_call_id
+
+/** 助手要调用的"一次工具调用"；arguments 是 JSON 字符串（OpenAI 协议如此规定）。 */
+export interface ToolCall {
+  /** 这次调用的唯一 id（OpenAI 返回的，要原样回传到 tool 消息的 tool_call_id） */
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    /** JSON 字符串！不是对象。需要 JSON.parse 后再交给 Zod 校验 */
+    arguments: string;
+  };
+}
+
+// ---------------- 1.1 多模态内容块 ----------------
+//
+// OpenAI Chat Completions 兼容的多模态输入使用 content 数组：
+//   [{ type: 'text', text: '...' }, { type: 'image_url', image_url: { url } }]
+// 这里保持协议字段名，不做自定义抽象，方便 MiniMax / 火山 / Kimi 直接消费。
+
+export type ImageDetail = 'low' | 'default' | 'high';
+
+export interface ChatImageUrl {
+  url: string;
+  detail?: ImageDetail;
+  max_long_side_pixel?: number;
+}
+
+export interface ChatVideoUrl {
+  url: string;
+  detail?: ImageDetail;
+  fps?: number;
+}
+
+export type ChatContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: ChatImageUrl }
+  // v1 只正式暴露图片入口；视频先保留协议类型，后续接 Files API / fps 等策略。
+  | { type: 'video_url'; video_url: ChatVideoUrl };
+
+export interface ImageInputSpec {
+  source: string;
+  detail?: ImageDetail;
+  maxLongSidePixel?: number;
+}
+
+/**
+ * 用户消息关联的附件展示元数据。
+ *
+ * content bytes、绝对路径和访问令牌不属于会话历史；宿主打开历史时可按 id
+ * 临时补充 previewUrl。LLM client 会在序列化请求前剥离整个 attachments 字段。
+ */
+export interface MessageAttachmentRef {
+  id: string;
+  name: string;
+  mime: string;
+  size: number;
+  sha256?: string;
+  previewUrl?: string;
+}
+
+/** Stable, credential-free reference to an element selected in the browser. */
+export interface MessageBrowserReference {
+  id: string;
+  url: string;
+  tabId: string;
+  selector: string;
+  snapshotRef?: string;
+  tag?: string;
+  role?: string;
+  accessibleName?: string;
+  text?: string;
+  attributes: Record<string, string>;
+  boundingBox?: { x: number; y: number; width: number; height: number };
+  pageRevision: string;
+  capturedAt: number;
+}
+
+/**
+ * 所有 Message variant 共享的可选字段。
+ *
+ * timestamp（v2 新增）：本地 unix millis（Date.now()）。
+ *   - 用途：UI 渲染 turn 边界横线（duration / 时间显示）
+ *   - 由 loop.ts 在 push 进 history 时填充
+ *   - **不发给 LLM**：client.ts 在序列化 messages 时剥掉此字段（避免破坏 OpenAI 协议合规）
+ *   - 旧 last-context.json 不带此字段时 fallback Date.now()
+ */
+export type Message = (
+  | {
+      role: 'system';
+      content: string;
+      timestamp?: number;
+      /**
+       * v2.x 新增：UI 临时提示（slash 命令输出等），不持久化、不算作真正的 system prompt。
+       *
+       *  - saveContext（persistContext.ts）写盘前过滤掉 _ephemeral=true 的 system 消息
+       *  - MessageList 识别此标记走暗灰单行样式（其他 system 消息保持 hide）
+       *  - 其他场景（LLM 调用等）暂时不过滤；短消息无害，下个版本再做 runQuery 入参过滤
+       *  - 已知限制：本期 LLM 收到 ephemeral 消息（不影响功能，仅噪声）
+       */
+      _ephemeral?: true;
+    }
+  | {
+      role: 'user';
+      content: string | ChatContentPart[];
+      attachments?: MessageAttachmentRef[];
+      browserReferences?: MessageBrowserReference[];
+      timestamp?: number;
+    }
+  | {
+      role: 'assistant';
+      /** 当 tool_calls 非空时 content 通常为 null（OpenAI 协议） */
+      content: string | null;
+      tool_calls?: ToolCall[];
+      /**
+       * 思维链字段：DeepSeek-R1 / MiniMax 推理拆分模式（reasoning_split=True）/
+       * OpenRouter 等会把模型的"思考"内容放在这里。
+       *
+       * 必须在多轮工具调用中把上一轮的 reasoning 原样回传，否则模型会"失忆"
+       * （断了思维链）。我们的策略是把流式收到的 reasoning 累积后挂在 assistant
+       * 消息上，下一轮请求时连同 messages 整个 JSON.stringify 发回去，未知字段
+       * 普通 OpenAI 兼容 provider 会忽略，需要它的 provider 会用上。
+       *
+       * 字段命名兼容多 provider：
+       *  - reasoning_content: DeepSeek-R1 风格（字符串）
+       *  - reasoning_details: MiniMax / OpenRouter 风格（结构化数组）
+       *  - reasoning:         少数 fork 的字符串别名
+       */
+      reasoning_content?: string;
+      reasoning_details?: unknown[];
+      reasoning?: string;
+      timestamp?: number;
+    }
+  | {
+      role: 'tool';
+      /** 工具的输出文本（成功时是结果，失败时是 error 字符串） */
+      content: string;
+      /** 必须对应上面 assistant 消息里某个 ToolCall 的 id */
+      tool_call_id: string;
+      /** 本地展示元数据；发送 Provider 前会剥离。 */
+      display_metadata?: ToolResultMetadata;
+      timestamp?: number;
+    }
+) & {
+  /**
+   * id（v2.x 终极重构新增）：本地唯一的、永不改变的身份标识（通常是 UUID）。
+   *   - 用途：React TUI 列表 commit 阶段，作为 <Static> 稳定不动的 Key 彻底拦截重绘。
+   *   - 不发给 LLM：client.ts 在发送给 LLM 序列化消息前自动剔除。
+   */
+  id?: string;
+};
+
+// ---------------- 2. 工具 (Tool) ----------------
+//
+// 这是 minimal-agent 对 kakadeai Tool 接口的极简化版本。
+// kakadeai 原版有 ~30 个字段（UI 渲染、权限、telemetry...），我们只保留 7 个核心字段。
+// 凡是模型能"看到"的部分（name / description / inputSchema），都和 kakadeai 一字不差，
+// 这样 prompt 工程的成果可以复用。
+
+/** 工具执行结果：要么成功（输出字符串），要么失败（错误描述）。 */
+export interface AgentResultMetadata {
+  kind: 'agent';
+  agentType: 'explore' | 'general';
+  description: string;
+  agentId?: string;
+  status?: 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+  isolation: 'none' | 'worktree';
+  turns: number;
+  toolCalls: number;
+  failedToolCalls: number;
+  /** 子任务从进入协调器到结束的总耗时。 */
+  durationMs: number;
+  changedFiles: string[];
+  /**
+   * 代码调研类子任务的「实际覆盖文件」清单（从 tool call 历史提取）。
+   * 用于父 agent / 宿主做覆盖度自检；非调研类可能为空。
+   */
+  coveredFiles?: string[];
+  worktree?: {
+    id: string;
+    branch: string;
+    baseSha: string;
+    status: 'ready' | 'applied' | 'discarded' | 'needs_attention';
+  };
+}
+
+export type FileActivityKind = 'read' | 'created' | 'modified' | 'generated' | 'deleted';
+export type FileVerification = 'passed' | 'failed' | 'not_run';
+export type ConversationFilePurpose = 'source' | 'deliverable' | 'support';
+export interface FilePatchSummary {
+  unifiedDiff?: string;
+  beforeHash?: string;
+  afterHash: string;
+  additions: number;
+  deletions: number;
+  truncated: boolean;
+  omittedReason?: 'too_large';
+}
+
+/** Structured local file output. Paths are always workspace-relative. */
+export interface FileActivityMetadata {
+  kind: 'file_activity';
+  files: Array<{
+    relativePath: string;
+    activity: FileActivityKind;
+    sha256?: string;
+    mime?: string;
+    verification: FileVerification;
+    purpose: ConversationFilePurpose;
+    patch?: FilePatchSummary;
+  }>;
+}
+
+export interface DeliverableManifest {
+  runId?: string;
+  conversationKey?: string;
+  status: 'draft' | 'verified' | 'final';
+  summary: string;
+  files: Array<{
+    relativePath: string;
+    sha256?: string;
+    mime?: string;
+    label?: string;
+    size?: number;
+    modifiedAt?: number;
+    sourceToolCallId?: string;
+    verification: FileVerification;
+    purpose: 'deliverable';
+  }>;
+  links?: Array<{ url: string; title?: string }>;
+  browserEvidence?: Array<{ tabId: string; url: string; screenshotId?: string }>;
+  warnings: string[];
+}
+
+/** File-search candidates. Discovery alone never makes a file important to a conversation. */
+export interface FileDiscoveryMetadata {
+  kind: 'file_discovery';
+  files: Array<{
+    relativePath: string;
+    size: number;
+    modifiedAt: number;
+  }>;
+}
+
+/** A formal result published to the user by PresentResult. */
+export interface ResultManifestMetadata {
+  kind: 'result_manifest';
+  manifest: DeliverableManifest;
+}
+
+export type ProcessCommandKind = 'test' | 'typecheck' | 'build' | 'check' | 'other';
+export type ProcessExecutionStatus = 'started' | 'running' | 'completed' | 'failed' | 'stopped';
+
+/** Structured process state shared by Bash, PowerShell, TaskOutput and the evidence ledger. */
+export interface ProcessExecutionMetadata {
+  kind: 'process_execution';
+  shell: 'bash' | 'powershell';
+  mode: 'foreground' | 'background';
+  taskId?: string;
+  commandKind: ProcessCommandKind;
+  status: ProcessExecutionStatus;
+  exitCode?: number | null;
+}
+
+/** Agent 子任务的结构化阶段进度；仅供宿主展示，不写入会话历史或发送给 LLM。 */
+export interface SubagentProgress {
+  kind: 'subagent';
+  phase: 'queued' | 'preparing' | 'analyzing' | 'using_tool' | 'drafting' | 'waiting_owner';
+  queuePosition?: number;
+  activeCount?: number;
+  maxConcurrent?: number;
+  turn?: number;
+  toolName?: string;
+  toolDescription?: string;
+  outputChars?: number;
+}
+
+export type ToolProgressDetail = SubagentProgress;
+
+export type ToolResultMetadata =
+  | AgentResultMetadata
+  | FileActivityMetadata
+  | FileDiscoveryMetadata
+  | ResultManifestMetadata
+  | ProcessExecutionMetadata;
+
+export type ToolResult =
+  | {
+    ok: true;
+    content: string;
+    metadata?: ToolResultMetadata;
+    recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
+    sensitivity?: 'public' | 'local' | 'sensitive';
+    visionImages?: ImageInputSpec[];
+    visionNote?: string;
+  }
+  | {
+    ok: false;
+    error: string;
+    metadata?: ToolResultMetadata;
+    recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
+    sensitivity?: 'public' | 'local' | 'sensitive';
+    visionImages?: ImageInputSpec[];
+    visionNote?: string;
+  };
+
+// visionImages：工具想让（视觉）模型「亲眼看一下」的图像（如浏览器关键节点实况截图）。
+// 主循环在回填工具结果后，把它们组装成一条带图的 user 消息喂给模型自我核验（见 loop.ts）。
+// 通用能力，不绑任何具体工具；模型不支持识图时主循环丢弃、优雅降级。
+//
+// ★ 成功和失败**两个分支都能带图**，因为「这步成不成」与「要不要看图」是两个正交
+// 维度——而出错时那张截图恰恰最该看（权限弹窗、验证拦截、意外的前台窗口，全靠
+// 它才看得见）。历史坑：失败分支曾经不带图，于是 ComputerUse 为了附上错误现场
+// 把失败**返回成 ok:true**。后果远超「注释不准」：前端显示成功、失败计数永远归零、
+// 连续失败熔断因此从未触发过一次（那时它还建在遥测日志上；现已内移到
+// ComputerUseService，按运行 + 动作指纹隔离）。
+// 让类型能表达真话，工具才不必撒谎。
+//
+// visionNote：跟这批图一起给模型的一句说明，拼在通用核验提示之后。
+// 内核不需要（也不应该）知道图是什么——「这几张是 1 秒间隔的连续帧」「淡化区只是
+// 没变化、不是被禁用」这类语义只有工具自己清楚，而看图的人不知道就会误读。
+// 与 Tool.gateRequest 同构：机制在内核，语义在工具。
+
+/**
+ * 工具调用时的环境态透传。与结构化输入分开，不会暴露给模型。
+ * 需要这些上下文的工具实现 `callWithContext()`，executeTool 统一调度，
+ * 避免按工具名写特判分支。
+ */
+export interface ToolCallContext {
+  /** 当前 runQuery() 主循环的运行时历史（含 system/user/assistant/tool 消息）。 */
+  history?: readonly Message[];
+  /** Per-conversation mutable state; file freshness and background tasks must not leak across sessions. */
+  sessionState?: import('./session/sessionState.js').SessionState;
+  /** 同一用户回合内共享的 Advisor 调用计数，防止模型循环咨询。 */
+  advisorCalls?: { used: number; max: number };
+  /** 区分主模型自动咨询与用户显式 /advisor ask。 */
+  advisorInvocation?: 'agent' | 'manual';
+  /**
+   * 主循环使用的 provider —— Agent 等「工具内部再起子查询」的派生工具用它
+   * 跑嵌套 runQuery（子 agent 与主 agent 同一模型，不另配凭据）。
+   */
+  provider?: Provider;
+  /**
+   * 主循环的工具执行闸门 —— 子 agent 继承同一审批策略（否则可写子 agent
+   * 就成了绕过宿主审批的后门）。type-only import，toolGate.ts 零依赖无环。
+   */
+  toolGate?: ToolGate;
+  /**
+   * 本次调用的 tool_call id，供调用级进度事件精确关联 UI 卡片。
+   */
+  toolCallId?: string;
+  /** 同一用户回合内共享的 Agent 子任务派生计数，防失控 fan-out（仿 advisorCalls）。 */
+  agentCalls?: { used: number; max: number };
+  subagentConfig?: {
+    maxConcurrent: number;
+    timeoutMs: number;
+    exploreMaxTurns: number;
+    generalMaxTurns: number;
+    defaultWriteIsolation: 'none' | 'worktree';
+  };
+  /** 上报长时工具的最新进度；宿主缺席时由 loop 提供的实现安全降级。 */
+  reportProgress?: (message: string, detail?: ToolProgressDetail) => void;
+  /** 当前用户原始输入及其稳定身份，供需要证据校验的受控工具使用。 */
+  currentUserInput?: string;
+  userMessageId?: string;
+  promptCache?: PromptCacheContext;
+  sessionId?: string;
+  workspaceId?: string;
+  /** Trusted working directory for this run; avoids process-global cwd leakage across Desktop sessions. */
+  cwd?: string;
+  /** 本机记忆权限由宿主明确声明；不可信宿主必须为 denied。 */
+  memoryAccess?: import('./runtime/agentRuntimeContext.js').MemoryAccessInput;
+  /**
+   * Browser actions are scoped to the owning conversation/run by the host.
+   * `supervised` 由宿主声明「存在可见浏览器 + 真人可接管/resume」（仅 Desktop 置 true）：
+   * 内核据此决定遇到 CAPTCHA/登录等关卡时能否交人处理；缺省/未监督（CLI -p、TUI、gateway）
+   * 绝不阻塞等人，改为据实非阻塞返回。
+   */
+  browserRun?: {
+    conversationKey: string;
+    runId: string;
+    profileId?: string;
+    supervised?: boolean;
+    /**
+     * Host-issued grants for this user turn. Page content can never add grants.
+     * Observe/interact are the normal supervised-browser baseline; upload and
+     * final submit must originate from the user's task.
+     */
+    grants?: import('./tools/webbrowser/browserRunRegistry.js').BrowserActionGrant[];
+    taskGrantId?: string;
+    /** Canonical roots from which this browser run may upload files. */
+    allowedUploadRoots?: string[];
+  };
+  /**
+   * Host-issued native desktop-control scope. Never derived from model arguments.
+   *
+   * ⚠️ **有意的例外，别当成漏网之鱼**：这里（以及上面 `browserRun.grants`）确实
+   * `import` 了具体工具的类型。内核对它**一个字段都不读**，纯透传给工具，
+   * 之所以不换成结构子集或 `unknown`：那会逼工具侧在几十处 narrow/cast，
+   * 把类型安全从"编译器保证"降级成"人记得写对"，代价远大于收益。
+   *
+   * 真正必须守住的那条线是 **`src/web/protocol.ts` 零工具依赖** —— 它是
+   * desktop 与 server 两个外部消费方的类型真值，一个工具的内部重构不该顺着
+   * 协议波及它们。那条线已改为「协议声明 `ComputerObservation` 结构契约、
+   * 工具编译期断言兼容」，并由 `test/kernelPurity.test.ts` 守着。
+   */
+  computerRun?: import('./tools/computeruse/protocol.js').ComputerUseRunContext;
+  /**
+   * Trusted host bridge for pausing a native Computer Use action while the
+   * owner handles credentials, OTP, CAPTCHA, permissions, or a manual
+   * takeover. It is never serialized to the native helper or exposed to the
+   * model.
+   */
+  computerIntervention?: {
+    inspect(
+      state: import('./tools/computeruse/protocol.js').ComputerState,
+      signal?: AbortSignal,
+    ): Promise<{
+      resolution: 'none' | 'resumed' | 'cancelled';
+      state?: import('./tools/computeruse/protocol.js').ComputerState;
+    }>;
+    pause(
+      reason: import('./humanIntervention.js').HumanInterventionReason,
+      summary: string,
+      signal?: AbortSignal,
+    ): Promise<{
+      resolution: 'resumed' | 'cancelled';
+      state?: import('./tools/computeruse/protocol.js').ComputerState;
+    }>;
+  };
+}
+
+export interface Tool<TInput = unknown> {
+  /** 工具名，必须和 kakadeai 一致：'Read' / 'Edit' / 'Write' / 'Glob' / 'Grep' */
+  name: string;
+
+  /**
+   * 给模型看的描述（会出现在 LLM 的 tools 字段里）。
+   * 可以是静态字符串，也可以是函数（函数版本方便注入运行时信息，如 cwd）。
+   */
+  description: string | (() => string);
+
+  /** Zod schema：模型返回的 arguments JSON 会用它校验和解析 */
+  inputSchema: z.ZodType<TInput>;
+
+  /**
+   * JSON Schema 形式的参数描述，会原样塞进 LLM 请求的 tools 字段。
+   * 我们手写而不是从 Zod 自动转换，原因：
+   *   - 零依赖（不用引 zod-to-json-schema）
+   *   - 教学清晰：学生能直接看到"模型看到的是什么"
+   * 与 Zod schema 保持一致是开发者的责任（可在测试里断言）。
+   */
+  parameters: object;
+
+  /** 是否只读？（read/glob/grep = true；edit/write = false）—— 仅用于元信息 */
+  isReadOnly?: boolean;
+
+  /** 多个调用是否能并发执行？（read/glob/grep = true；edit/write = false） */
+  isConcurrencySafe?: boolean;
+
+  /** 输出超过这个字符数会被截断（防止把巨大文件灌进上下文） */
+  maxResultSizeChars?: number;
+
+  /** Synchronous host/runtime probe used before the tool is shown to the model. */
+  resolveAvailability?(
+    runtime: import('./runtime/agentRuntimeContext.js').AgentRuntimeContext,
+  ): ToolAvailability;
+
+  /**
+   * 中断行为（方法，支持动态判断）：
+   * - 'cancel': 可以安全取消该工具执行，丢弃结果
+   * - 'block':  必须执行完该工具，新输入排队等待
+   * 缺省/未实现 = 'block'（安全默认）
+   */
+  interruptBehavior?(): 'cancel' | 'block';
+
+  /**
+   * 给宿主的 ToolGate 决策补充工具侧语义。
+   *
+   * ⚠️ `input` 可能是 `undefined` —— **参数没通过 zod 校验时也会调它**。
+   * 因为「参数烂掉」不等于「身份不明」：运行身份来自宿主注入的 context，
+   * 与模型给的参数无关。这种情况下工具应当**照常给出身份**（runContext），
+   * 只省略依赖参数的部分（action / isReadOnly），让参数错误由工具层如实报出来。
+   *
+   * 实测代价：此前参数校验失败时整个 gateRequest 被跳过 → 闸门请求里没有
+   * runContext → 桌面端报「运行身份与当前宿主会话不匹配」，把参数格式问题
+   * 讲成权限问题，照那个方向根本查不下去。
+   */
+  gateRequest?(
+    input: TInput | undefined,
+    context: ToolCallContext,
+  ): Partial<Pick<import('./toolGate.js').ToolGateRequest, 'isReadOnly' | 'runContext' | 'action'>>;
+
+  /**
+   * 真正干活的函数。
+   * @param input  已被 Zod 校验通过的参数
+   * @param signal 用于响应 Ctrl+C 等中断
+   */
+  call(input: TInput, signal?: AbortSignal): Promise<ToolResult>;
+
+  /** 仅需要会话运行态的工具实现；普通工具继续使用 call。 */
+  callWithContext?(
+    input: TInput,
+    signal: AbortSignal | undefined,
+    context: ToolCallContext,
+  ): Promise<ToolResult>;
+}
+
+export interface ToolAvailability {
+  available: boolean;
+  /** Must change when config, executable resolution, or another availability input changes. */
+  signature: string;
+}
+
+// ---------------- 3. Provider 配置 ----------------
+//
+// minimal-agent 从 .env 环境变量读取配置：
+//   MINIMAL_AGENT_BASE_URL   - API 地址
+//   MINIMAL_AGENT_API_KEY    - API key
+//   MINIMAL_AGENT_MODEL      - 模型名
+//   MINIMAL_AGENT_PROVIDER   - 友好名称（可选，默认 "env"）
+//   MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口（可选，默认 128000）
+
+export interface Provider {
+  /** 友好名（仅展示用），如 "deepseek" */
+  name: string;
+
+  /** API 完整端点 URL，如 "https://api.deepseek.com/v1/chat/completions" */
+  baseURL: string;
+
+  /** API key（敏感信息，用户自己填） */
+  apiKey: string;
+
+  /** 模型 id，如 "deepseek-chat" */
+  model: string;
+
+  /** 该模型的上下文窗口（token 数）；用于压缩阈值计算 */
+  contextWindow: number;
+
+  /**
+   * 自动压缩触发阈值占 contextWindow 的比例（0~1，默认 0.85）。
+   *
+   * 阈值 = min(contextWindow × compactRatio, contextWindow − 输出 buffer)，**provider 无关**：
+   * 纯按 contextWindow 缩放，适配所有模型，不绑任何 provider。
+   *
+   * 可经 .env `MINIMAL_AGENT_COMPACT_RATIO` 或 webchat 设置页配置；缺省时 fallback
+   * DEFAULT_COMPACT_RATIO（0.85）。**测试时临时调小（如 0.2）即可轻松触发自动压缩验证。**
+   */
+  compactRatio?: number;
+
+  /**
+   * 单次 LLM 响应的输出 token 上限（OpenAI `max_tokens`）。
+   *
+   * **为什么必须显式发**：很多 OpenAI 兼容 provider 的默认输出上限很小——实测火山
+   * `doubao-seed-2.0-pro` 默认就 4096，不发 max_tokens 时长输出（如一次性写整篇 PLAN.md）
+   * 会在 4096 处被 `finish_reason=length` 硬截断，被引擎判为「截断不可信」而 halt。
+   * 它是**上限不是预订**：设大不额外花钱（实测豆包接受到 ≥131072 仍按需返回），只是兜住
+   * 小默认值的 provider。可经 .env `MINIMAL_AGENT_MAX_TOKENS` 或 saved config 配置；
+   * 缺省时由 config 层给 DEFAULT_MAX_TOKENS。个别 provider 若拒绝过大的值，client 会
+   * 自动去掉 max_tokens 重发降级（见 client.ts）。
+   */
+  maxTokens?: number;
+
+  /**
+   * 请求协议格式：'openai'（Chat Completions，默认）| 'anthropic'（Messages API）。
+   * 缺省当 'openai'——兼容旧版只产出 OpenAI 格式对象的 env 自举路径。见 client.ts。
+   */
+  apiFormat?: 'openai' | 'anthropic';
+
+  /**
+   * 该模型是否支持识图（多模态视觉）。resolveProvider 从所选 ModelConfig 归一成真布尔
+   * （条目未显式设则为 true）。发图类消费方（浏览器截图核验等）严格按 `=== true` 判定：
+   * 故未经 resolveProvider 的 provider（如纯 env 自举，此处为 undefined）会被当作「不支持」——
+   * 保守地不给可能非视觉的端点发图（免触发 400），并优雅降级（不截、不假装核验）。
+   */
+  supportsVision?: boolean;
+  promptCache?: PromptCacheConfig;
+}
+
+export type PromptCacheMode = 'auto' | 'session-key' | 'disabled';
+
+export interface PromptCacheConfig {
+  mode: PromptCacheMode;
+}
+
+export interface PromptCacheContext {
+  /** Opaque SHA-256 routing key safe to send to a provider. */
+  scopeKey: string;
+  /** Local-only identity used to derive child scopes; never serialized. */
+  conversationKey: string;
+}
+
+export interface PromptCacheUsage {
+  reported: boolean;
+  promptTokens?: number;
+  cacheReadTokens?: number;
+  cacheMissTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+export interface RunEvidenceEntry {
+  toolName: string;
+  callHash: string;
+  ok: boolean;
+  resultHash: string;
+  kind: 'tool' | 'file' | 'delivery' | 'verification' | 'web';
+  paths?: string[];
+  urls?: string[];
+  verification?: FileVerification;
+}
+
+export interface RunEvidenceLedger {
+  toolCalls: number;
+  failedToolCalls: number;
+  entries: RunEvidenceEntry[];
+}
+
+export interface HarnessDiagnostics {
+  promptVersion: 'minimal-agent:prompt:v2';
+  basePromptHash: string;
+  enabledPolicyIds?: string[];
+  enabledCapabilities: string[];
+  effectiveToolSetSignature?: string;
+  tokenBudget?: {
+    contextWindow: number;
+    inputLimit: number;
+    reservedOutput: number;
+    historyTokens: number;
+    toolTokens: number;
+    transientTokens: number;
+    totalInputTokens: number;
+    overBudget: boolean;
+  };
+  stopReason?: 'complete' | 'max_turns' | 'stalled' | 'aborted' | 'error';
+  evidence?: RunEvidenceLedger;
+}
+
+// ---------------- 4. LLM 流式事件 ----------------
+//
+// LLM 客户端是 AsyncGenerator，逐 chunk yield 这些事件。
+// 上层（loop.ts）按事件类型组装最终的 assistant 消息。
+
+export type LlmStreamEvent =
+  /** 文本增量（assistant 在打字） */
+  | { type: 'text_delta'; delta: string }
+  /** 工具调用增量（OpenAI 协议下 tool_calls 也是分片返回的） */
+  | {
+      type: 'tool_call_delta';
+      /** 这是当前 tool_calls 数组里的第几个？（多工具并行调用时） */
+      index: number;
+      id?: string;
+      name?: string;
+      argumentsDelta?: string;
+    }
+  /**
+   * 思维链增量（DeepSeek-R1 / MiniMax / OpenRouter）。
+   * field 表示 provider 用的是哪个字段名（决定累积时往哪个 key 上拼）。
+   * `reasoning_details` 是结构化数组，按片追加；其它两个是字符串增量。
+   */
+  | {
+      type: 'reasoning_delta';
+      field: 'reasoning_content' | 'reasoning' | 'reasoning_details';
+      /** 字符串增量（reasoning_content / reasoning） */
+      delta?: string;
+      /** 数组增量（reasoning_details） */
+      items?: unknown[];
+    }
+  /**
+   * 流结束。
+   *
+   * promptTokens（v2.x 新增，可选）：本轮请求的**真实** prompt token 数。
+   *   - 仅当 provider 支持并返回 usage（client 开 `stream_options.include_usage`）时才有；
+   *     拿不到（老 provider / 关闭逃生开关）时为 undefined。
+   *   - 用途：loop 把它接住作为自动压缩的「真实 usage 闭环」权威判据，
+   *     校正本地估算对工具 schema / 中文的系统性低估；无此值时调用方 fallback 估算。
+   *   - ⚠️ 语义是「本轮 prompt 的**总** token 数，含命中缓存的部分」。OpenAI 协议天然如此
+   *     （cached_tokens 是 prompt_tokens 的子集明细）；Anthropic 协议的 input_tokens **不含**
+   *     缓存部分，故其解析器必须自行把三段相加后再填进来，否则开启缓存后自动压缩会严重低估。
+   *
+   * cachedPromptTokens / cacheWriteTokens（可选，纯观测）：
+   *   - cachedPromptTokens = promptTokens 中**命中缓存**的部分（读缓存，计费打折）
+   *   - cacheWriteTokens   = 本轮**写入**缓存的部分（Anthropic 显式打点才有；OpenAI 自动
+   *     缓存不单独报告写入量，恒为 undefined）
+   *   - 只用于展示命中率与验证缓存是否真的生效，不参与任何控制流决策。
+   */
+  | {
+      type: 'done';
+      stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted';
+      promptTokens?: number;
+      cachedPromptTokens?: number;
+      cacheMissTokens?: number;
+      cacheWriteTokens?: number;
+      promptCacheUsage?: PromptCacheUsage;
+    }
+  /** 用户主动中断（ESC/Ctrl+C）；不显示红色错误，只显示一行提示 */
+  | { type: 'interrupted' };
+
+// ---------------- 5. Loop 对外的事件 ----------------
+//
+// loop.runQuery() 是 AsyncGenerator，UI 通过 for await 拿这些事件并把它们映射到 React state。
+
+/**
+ * 工作过程显示阶段标签（UI 的 LiveArea 据此选择文字 / 决定是否隐藏整面板）。
+ *
+ *   idle           —— 当前没有任何工作（隐藏 LiveArea）
+ *   thinking       —— 已发请求，等首个 token（reasoning 或 text 或 tool_call）
+ *   streaming      —— 模型在流式输出最终回答文本
+ *   tool_executing —— 至少一个工具在跑（并行时栈式显示多个）
+ *   compacting     —— 正在跑自动 / reactive / 手动压缩
+ */
+export type ProgressStage =
+  | 'idle'
+  | 'thinking'
+  | 'streaming'
+  | 'tool_executing'
+  | 'compacting';
+
+export type CompactionMode = 'llm-summary' | 'snip-fallback';
+export type CompactionTrigger =
+  | 'threshold'
+  | 'post-budget'
+  | 'provider-overflow'
+  | 'manual';
+export type CompactionFallbackReason =
+  | 'llm-error'
+  | 'invalid-summary'
+  | 'still-over-budget';
+
+/**
+ * LiveArea 显示一行工具调用用的快照。
+ *
+ * 之前定义在 ui/hooks/useChat.ts 中（仅 UI 内部）；
+ * 工具并行后 loop.ts 和 UI 都要引用这个形状，统一上移到 types.ts。
+ */
+export interface ToolStatusState {
+  toolName: string;
+  argsPreview: string;
+  status: 'running';
+  /**
+   * v2 新增：人话版工具描述（如 "Reading src/foo.ts" 而非 "Read(file_path=...)").
+   * 由 loop.ts 的 friendlyToolDescription() 生成；UI 优先用它显示在 spinner 行。
+   * 缺省时 UI fallback 到 `${toolName}(${argsPreview})`。
+   */
+  argsFriendly?: string;
+  /**
+   * 长时工具的步内实时进度行（如生图 "[ai-image-plan] round 1/1 15/31 t2i → ai_p11.png"）。
+   * 由调用级 tool_progress 事件更新；LiveArea 有则追加显示——
+   * 治「单步十几分钟静态无变化被误判死机」（2026-07-02 生图假卡死事故）。缺省 = 无进度可示。
+   */
+  progress?: string;
+  progressDetail?: ToolProgressDetail;
+}
+
+export type LoopEvent =
+  /** 文本流（同 LlmStreamEvent.text_delta） */
+  | { type: 'text'; delta: string }
+  /**
+   * 用户消息刚 push 进 history（loop 入口）。
+   *
+   * 为什么需要这条 event：loop.ts push 用户消息后，到 assistant_message 之前，
+   * UI 端 handleEvent 不会触发 bump（stage_change/text/reasoning 都不 bump），
+   * 而 useChat 的 history 是 useMemo(..., [version])，version 不变就不重算 →
+   * <Static> 直到整轮落定才一次性 commit「用户消息+reasoning+答案」，用户输入无法第一时间置顶。
+   * UI 收到此事件立即 bump，让 <Static> 马上把用户消息 commit 进 scrollback（符合 T-A-O-R 顺序）。
+   */
+  | { type: 'user_message_committed'; message?: Extract<Message, { role: 'user' }> }
+  /** 一轮 assistant 消息已完整组装（含可能的 tool_calls） */
+  | { type: 'assistant_message'; message: Extract<Message, { role: 'assistant' }> }
+  /**
+   * 主循环在工具结果之后注入的「带外上下文消息」（当前用于浏览器关键节点实况截图回填）。
+   * 宿主收到后应把它当作一条消息追加进对话展示；模型也会在下一轮看到它（已 push 进 history）。
+   * 内核为节省上下文会把历史里旧的同类图片消息降级为文字，但宿主展示层可自行保留全部，互不影响。
+   */
+  | { type: 'injected_message'; message: Message }
+  /**
+   * 工具开始执行。
+   *
+   * v2 新增 argsFriendly：人话版工具描述（如 "Reading src/foo.ts"），由 loop.ts 的
+   * friendlyToolDescription() 在 yield 此事件时生成。UI 端 useChat handleEvent 接收
+   * 后存入 ToolStatusState.argsFriendly 给 LiveArea spinner 行用。
+   */
+  | {
+      type: 'tool_start';
+      toolName: string;
+      toolCallId: string;
+      argsPreview: string;
+      argsFriendly?: string;
+    }
+  /** 长时工具执行中的调用级进度，不写入会话历史。 */
+  | {
+      type: 'tool_progress';
+      toolName: string;
+      toolCallId: string;
+      message: string;
+      detail?: ToolProgressDetail;
+    }
+  /** 工具结束（成功或失败） */
+  | {
+      type: 'tool_end';
+      toolName: string;
+      toolCallId: string;
+      ok: boolean;
+      content: string;
+      metadata?: ToolResultMetadata;
+    }
+  | { type: 'tool_messages_committed' }
+  /** Local-safe harness observability; never contains prompt, memory, arguments, or reasoning text. */
+  | { type: 'harness_diagnostics'; diagnostics: HarnessDiagnostics }
+  /** 触发了自动压缩 */
+  | { type: 'compact_start' }
+  | {
+      type: 'compact_done';
+      before: number;
+      after: number;
+      /** Optional for wire compatibility with older hosts. */
+      trigger?: CompactionTrigger;
+      mode?: CompactionMode;
+      degraded?: boolean;
+      fallbackReason?: CompactionFallbackReason;
+      messagesRemoved?: number;
+      tokensFreed?: number;
+    }
+  /**
+   * 当前会话上下文用量。真实 usage 不可用时由内核统一估算。
+   *
+   * cachedPromptTokens / cacheWriteTokens：提示词缓存观测位（纯展示，不参与决策）。
+   * 只有 provider 真实报告时才有值；`source:'estimated'` 时恒为 undefined
+   * （估算路径没有缓存信息，不能拿估算值冒充命中率）。
+   */
+  | {
+      type: 'context_usage';
+      usedTokens: number;
+      contextWindow: number;
+      remainingTokens: number;
+      compactThreshold: number;
+      source: 'actual' | 'estimated';
+      cachedPromptTokens?: number;
+      cacheMissTokens?: number;
+      cacheWriteTokens?: number;
+      promptCacheUsage?: PromptCacheUsage;
+    }
+  /** 整轮交互结束（模型不再调工具） */
+  | {
+      type: 'turn_done';
+      completionStatus?: 'completed' | 'delivery_incomplete' | 'delivery_unverified' | 'claims_unverified';
+      warning?: string;
+    }
+  /**
+   * 中断事件
+   * - reason: 'manual' 用户按ESC/Ctrl+C手动中断
+   * - reason: 'queued_input' 有新的排队输入需要在安全点处理
+   */
+  | { type: 'interrupted'; reason?: 'manual' | 'queued_input' }
+  /**
+   * 出错（API 报错 / 网络异常等）。
+   *
+   * code（v2.x 新增，可选）：让 `-p --output-format json` 把终结原因映射成稳定的
+   * stop_reason，也让 print.ts 区分"致命错误（退出）"与"非致命警告（继续）"：
+   *   - 'llm_error'      LLM 调用失败 → 终结，stop_reason='error'
+   *   - 'max_turns'      撞最大轮数上限 → 终结，stop_reason='max_turns'
+   *   - 'compact_failed' 自动压缩失败但 loop 想继续 → 非致命，print.ts 只 stderr 警告不退出
+   *   - 'aborted'        被中断（signal.aborted）
+   * 缺省（旧调用方 / 未分类错误）按致命、stop_reason='error' 处理。
+   */
+  | {
+      type: 'error';
+      error: string;
+      code?: 'llm_error' | 'max_turns' | 'compact_failed' | 'aborted' | 'stalled' | 'context_overflow';
+    }
+  /**
+   * 非致命警告：需冒泡给用户但不终止执行。
+   *
+   * 通用框架事件（不绑定任何插件）。插件 / 工作流遇到"该提醒但不该报错"的情况
+   * （如多余参数被忽略、审批闸门在非交互模式被自动跳过）应 yield 此事件，
+   * 而非自定义私有事件 —— 框架 UI 不认插件私有词表。
+   *   - `-p` 模式：print.ts 落 stderr（权威通道，不受 verbose 控制）
+   *   - TUI：不渲染成红色 error；插件可另发 plugin_progress 把同文案镜像到状态行
+   */
+  | { type: 'warning'; message: string }
+  /**
+   * 插件循环进度（通用化事件，替代旧的 plugin_start / plugin_iteration）。
+   *
+   * 约定：
+   *   - 进入循环时 yield 一次 { current: 0, max, message: <说明> }
+   *   - 每轮迭代 yield 一次 { current: N, max }
+   *   - UI 把 current/max 渲染为进度数字，message 用于状态描述
+   *   - current/max 都可省略 = 纯文案进度（如工作流步骤的人话 title——
+   *     嵌套块的块内序号对用户是噪声时，插件只发 message，UI 不渲染数字）
+   */
+  | {
+      type: 'plugin_progress';
+      pluginId: string;
+      current?: number;
+      max?: number;
+      message?: string;
+    }
+  /**
+   * 思维链流式片段。
+   *
+   * 来源：DeepSeek-R1 / MiniMax reasoning_split / OpenRouter 等 provider 的 reasoning_delta。
+   * loop.ts 同时把它累积成字符串挂在 assistant 消息上回传（保持思维链连续）。
+   * UI 端 useChat 把它累积进 reasoningPreview（100ms 节流 + 环形截断），由 LiveArea
+   * 在 thinking 阶段短尾部显示；assistant_message 落定后
+   * 整段思维链随消息进 history，由 MessageList 提交进 scrollback（💭 块），live 预览清空。
+   */
+  | { type: 'reasoning'; delta: string }
+  /**
+   * Progress 阶段切换。
+   *
+   * loop.ts 在以下时机 yield：
+   *   - 进入新一轮 LLM 调用前 → 'thinking'
+   *   - 首个 text_delta 到来时 → 'streaming'（用布尔 flag 防重复）
+   *   - 进入工具并行执行段前 → 'tool_executing'
+   *   - 进入自动/reactive 压缩前 → 'compacting'
+   *
+   * turn_done / interrupted / error 后 UI 端自行 reset 到 'idle'（loop 不再额外 yield）。
+   */
+  | { type: 'stage_change'; stage: ProgressStage }
+  /**
+   * 执行中向用户提问（AskUserQuestion 工具触发，经 askBridge）。
+   *
+   * 这是「问答 over wire」的出站事件：TUI 不靠它（TUI 走 askBridge 内存 handler 直接弹界面），
+   * 但 `-p --output-format stream-json` 子进程的 askBridge handler 会 emit 本事件到 stdout，
+   * 让远程通道（webchat / 网关）收到问题、渲染选择、把答案经 stdin 的 `ask_answer` 回灌。
+   * requestId 用于关联问题与答案（一轮内可多次提问）。
+   */
+  | { type: 'ask'; requestId: string; questions: AskQuestionSpec[]; source?: AskSource }
+  /** 问题在本回合所有者队列中的状态；不写入 Session 历史。 */
+  | { type: 'ask_status'; source: AskSource; state: AskQueueState; queuePosition?: number; queuedCount?: number };
+// 注：插件私有事件（如 workflow-runner 的 workflow_*）不再写在这里。
+// 插件通过 PluginEvent 开放契约 yield 任意 type 字符串的事件，UI 静默忽略未识别项。