minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/protocol.js

@@ -0,0 +1,60 @@
+export const COMPUTER_USE_PROTOCOL_VERSION = 1;
+/**
+ * Actions that are both wired and implemented by the currently shipped native
+ * baseline. Keep this list conservative: exposing an action to the model is a
+ * product promise, not a placeholder for a future platform driver.
+ *
+ * Keep host-only control transitions (takeover/resume) and planned primitives
+ * out of the model schema until their native protocol exists. They remain in
+ * ComputerUseAction so callers receive an explicit `unsupported` response
+ * instead of being translated into a different, dangerous action.
+ */
+export const COMPUTER_USE_TOOL_ACTIONS = [
+    'status', 'permissions', 'observe', 'replay',
+    'click', 'double_click', 'right_click', 'middle_click', 'hover',
+    'pointer_down', 'pointer_move', 'pointer_up', 'drag', 'scroll',
+    'type', 'key', 'hotkey',
+    // ⚠️ 这里曾经还有 `press` / `release` / `call_user` 三个 —— 它们出现在给模型的
+    // 动作枚举和工具描述里，但 `nativeAction()` 没有对应 case、`waitFor` 也不接管，
+    // 模型一调就掉进 default 抛 `尚未映射到原生动作协议`；守护进程的 `capabilities()`
+    // 也**从来没有**宣传过它们。也就是说这是 TS 单方面多报。
+    //   · press/release（按住/松开某个键）：`hotkey` 已覆盖组合键；真要按住修饰键跨动作，
+    //     得先解决「run 中途中断时那个键永远卡在按下状态」，那是另一件事，不是补个 case。
+    //   · call_user：与 `AskUserQuestion` 工具重复，后者是已验证的通道。
+    // 三个都从模型可见面移除，`computerUseActionDispatch.test.ts` 锁住「列表里每个动作
+    // 都必须真的能被分派」。要加回来，先实现，再进这个列表。
+    // 闭环：动作后用像素判「界面稳了没」，比再看一张图便宜两个数量级。
+    'settle',
+    // 旁路通道：能不走像素就不走。
+    'clipboard_write', 'grab_region_to_clipboard', 'file_drop',
+    // 窗口控制：像素上根本表达不了「激活一个没在前台的应用」。
+    'activate_app', 'window',
+    // 语义等待：在此之前模型只能 observe→看→observe 地轮询，每轮烧一张图
+    // （约 1100 token）。这三个改用元数据观测轮询，一轮几乎不花 token。
+    // 实现是纯 TS 编排（waitFor.ts），不经守护进程动作通道。
+    'wait_for_element', 'wait_for_text', 'wait_for_window',
+    'wait',
+    'stop', 'emergency_stop',
+];
+export function requiredCapability(action, intent = 'normal') {
+    if (['status', 'permissions', 'list_apps', 'observe', 'replay', 'settle', 'wait_stable', 'wait_for_element', 'wait_for_text', 'wait_for_window'].includes(action))
+        return 'observe';
+    // 意图优先于动作种类：一次 click 与一次 key 都可能是「发送」。
+    if (intent === 'submit' && isMutatingComputerUseAction(action))
+        return 'submit';
+    // clipboard_read 不在模型可见动作里 —— 见 ComputerUseAction 的说明。
+    if (action === 'clipboard_read')
+        return 'clipboard-read';
+    if (['clipboard_write', 'grab_region_to_clipboard'].includes(action))
+        return 'clipboard-write';
+    if (action === 'file_drop')
+        return 'file-drop';
+    if (action === 'type' || action === 'key' || action === 'hotkey' || action === 'select_text')
+        return 'type';
+    return 'interact';
+}
+export function isMutatingComputerUseAction(action) {
+    return !['status', 'permissions', 'list_apps', 'observe', 'replay', 'settle', 'wait_stable', 'wait_for_element', 'wait_for_text', 'wait_for_window', 'wait'].includes(action);
+}
+const _computerStateContractOk = true;
+void _computerStateContractOk;

package/src/tools/computeruse/protocol.ts

@@ -0,0 +1,515 @@
+export const COMPUTER_USE_PROTOCOL_VERSION = 1;
+
+export type ComputerUseSurface = 'desktop' | 'tui' | 'cli' | 'workflow' | 'subagent';
+export type ComputerUseCapability =
+  | 'observe'
+  | 'interact'
+  | 'type'
+  | 'clipboard-read'
+  | 'clipboard-write'
+  | 'file-drop'
+  | 'submit';
+
+export interface ComputerUseRunContext {
+  ownerId: string;
+  conversationKey: string;
+  runId: string;
+  surface: ComputerUseSurface;
+  allowedApps: string[];
+  grantId?: string;
+  capabilities: ComputerUseCapability[];
+  allowedFileRoots?: string[];
+  supervised?: boolean;
+  /**
+   * 本回合已获人工批准的不可逆动作授权（见 ComputerUseIrreversibleGrant）。
+   *
+   * 由工具层在用户批准后就地 push。`run` 对象与两处 host gate 闭包持的是同一个
+   * 引用，所以一次赋值同时对工具和 gate 生效，不必两边各记一份状态。
+   */
+  irreversibleGrants?: ComputerUseIrreversibleGrant[];
+  /**
+   * 本回合用户的原话。**只用于把上下文摆给人看**，不参与任何授权判定。
+   *
+   * 唯一消费点是不可逆动作的确认弹窗：用户这一轮压根没提要做不可逆的事、
+   * 模型却要提交时，弹窗会额外提醒一句。判定权仍完全在用户手上——从措辞
+   * 推断授权是被明确否决过的做法（见 `grants.ts` 头注）。
+   */
+  userInput?: string;
+  /**
+   * Explicit, local-only diagnostic capture root. The native wire adapter strips
+   * this field; it is consumed by the TypeScript tool host to persist a
+   * chronological, privacy-aware trace for one CLI run.
+   */
+  diagnosticTraceDir?: string;
+}
+
+/**
+ * 一次人工批准的不可逆动作授权。**范围限定到「应用 + 动作类别」**。
+ *
+ * 早先的实现是批准后往 `capabilities` 里 push `'submit'`，于是「批准给张三发
+ * 这条消息」顺带放开了本回合内**任何**不可逆动作 —— 同一回合里再关个没保存的
+ * 窗口、再删点什么，都不会再问一句。用户点头的是一件事，拿到的是一类权力。
+ *
+ * 现在批准写的是这个结构：`appId` 是当时的前台应用，`actionClass` 是命中的
+ * 不可逆条目类别（`intent:submit` / `window:close` / `key:Enter` / `region:…`）。
+ * 批准发消息不再顺带批准关窗口，而同一 (应用, 类别) 的后续动作仍不重复打扰 ——
+ * 「尽量少问」和「批的是哪件事」这两件事可以同时成立。
+ *
+ * 生命周期跟着 `ComputerUseRunContext` 走：宿主每回合新建一个 run 对象
+ * （TUI `useChat.ts`、Desktop `localServer.ts`），所以「本回合有效」是天然边界。
+ */
+export interface ComputerUseIrreversibleGrant {
+  /** 批准时的前台应用标识；拿不到前台时为 `'*'`（仍受 supervised 那层约束）。 */
+  appId: string;
+  /** 命中的不可逆条目类别，如 `intent:submit`。 */
+  actionClass: string;
+  grantedAtMs: number;
+}
+
+export interface ComputerUseGrant {
+  id: string;
+  context: Omit<ComputerUseRunContext, 'grantId' | 'capabilities'>;
+  capabilities: ComputerUseCapability[];
+  expiresAt: number;
+}
+
+export interface ComputerUseRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ComputerUseDisplay {
+  id: string;
+  name?: string;
+  logicalBounds: ComputerUseRect;
+  /**
+   * 扣掉菜单栏与 Dock 之后**真正能放窗口、能点到**的矩形（与 logicalBounds 同坐标系）。
+   *
+   * 拿不到就是 undefined —— 说不出准确数字时保持沉默，好过给一个编的。
+   * ⚠️ 与 logicalBounds 的差别不是边角：本机 1920×1080 上菜单栏 30pt、Dock 94pt，
+   * 可用区只有 1920×956，**中心比屏幕中心高 32pt**。
+   */
+  visibleBounds?: ComputerUseRect;
+  physicalWidth: number;
+  physicalHeight: number;
+  scaleFactor: number;
+  primary: boolean;
+}
+
+export interface ComputerUseApp {
+  id: string;
+  name: string;
+  pid?: number;
+}
+
+export interface ComputerUseWindow {
+  id: string;
+  appId: string;
+  title?: string;
+  bounds: ComputerUseRect;
+  minimized?: boolean;
+}
+
+export interface AccessibilityNode {
+  elementId: string;
+  role: string;
+  /**
+   * Platform subrole (macOS `AXSubrole`). Several toolkits report a generic
+   * role and only mark secure entry here, so this is load-bearing for the
+   * human-handoff boundary rather than decoration.
+   */
+  subrole?: string;
+  name?: string;
+  value?: string;
+  /** True for password/secure-entry controls. The value must be omitted. */
+  protected?: boolean;
+  bounds?: ComputerUseRect;
+  enabled?: boolean;
+  focused?: boolean;
+  actions?: string[];
+  children?: AccessibilityNode[];
+}
+
+export interface ComputerUseImageReference {
+  path: string;
+  mime: 'image/png' | 'image/jpeg' | 'image/webp';
+  width: number;
+  height: number;
+  byteLength?: number;
+  sha256?: string;
+  displayId?: string;
+  revision?: string;
+  expiresAt: number;
+}
+
+export interface ComputerUseVerification {
+  status: 'passed' | 'inconclusive' | 'failed';
+  reason: string;
+  beforeRevision?: string;
+  afterRevision?: string;
+  changed?: boolean;
+}
+
+export interface ComputerUseActionMarker {
+  action: ComputerUseAction;
+  displayId?: string;
+  x?: number;
+  y?: number;
+  beforeRevision?: string;
+  afterRevision?: string;
+}
+
+// `OcrBlock` 与 `ComputerState.ocrBlocks` 已删除：本系统按 SPEC §8 不做本地 OCR
+// （文字识别由 VLM 直接完成），该字段自诞生起从未被任何 transport 填充过。
+// 留着一个恒空的协议字段，只会让人以为"换个 transport 就能有"。
+
+export interface ComputerState {
+  revision: string;
+  epoch: number;
+  displays: ComputerUseDisplay[];
+  activeApp?: ComputerUseApp;
+  windows: ComputerUseWindow[];
+  accessibility?: {
+    appId: string;
+    windowId?: string;
+    root: AccessibilityNode;
+    truncated?: boolean;
+  };
+  screenshot?: ComputerUseImageReference;
+  changedRegions: ComputerUseRect[];
+  /**
+   * 低频彩色帧序列，**按时间正序**（最早在前，最后一帧 = 当前状态）。
+   * 只有请求了多帧才非空；空数组表示只有上面那张 screenshot。
+   */
+  sequence?: ComputerUseSequenceFrame[];
+  backend: 'native' | 'degraded' | 'mock';
+}
+
+/** 原生侧低频环形缓冲里的一帧：裸 RGB，由宿主负责编码成 PNG。 */
+export interface ComputerUseSequenceFrame {
+  capturedAtMs: number;
+  width: number;
+  height: number;
+  /** 行主序 RGB，每像素 3 字节，base64。 */
+  rgbBase64: string;
+}
+
+export type ComputerUseAction =
+  | 'status'
+  | 'permissions'
+  | 'list_apps'
+  | 'observe'
+  | 'replay'
+  | 'click'
+  | 'double_click'
+  | 'right_click'
+  | 'middle_click'
+  | 'hover'
+  | 'pointer_down'
+  | 'pointer_move'
+  | 'pointer_up'
+  | 'drag'
+  | 'scroll'
+  | 'type'
+  | 'key'
+  | 'hotkey'
+  | 'press'
+  | 'release'
+  | 'call_user'
+  /**
+   * ⚠️ **保留但未实现**（`select_text` / `secondary_action` / `wait_stable`）。
+   *
+   * 留在类型里的唯一理由：让调用方收到明确的 `unsupported`，而不是被翻译成
+   * 另一个（可能危险的）动作 —— 「选中文本」被降级成「点一下再拖」是会真的
+   * 改坏文档的。
+   *
+   * **移除条件**：到 2026 年底仍无实现且无人请求，就把它们连同这段注释一起删。
+   * 保留一个永远不会实现的占位，等于让每个读代码的人重新判断一次「这是没做完
+   * 还是不打算做」。
+   */
+  | 'select_text'
+  | 'secondary_action'
+  /**
+   * ⚠️ **产品策略禁用，不是未实现。**
+   *
+   * 跨应用搬运内容只需 Cmd+C / Cmd+V，agent 根本不需要**看到**内容；
+   * 而需要看到的场景恰好是密码管理器把凭据放上去的那个场景。
+   * 它留在类型里是为了让调用方收到明确的 `unsupported` 而不是被翻译成
+   * 别的动作。要放开必须重新论证，不是删一行。
+   */
+  | 'clipboard_read'
+  | 'clipboard_write'
+  /**
+   * 走剪贴板把文本粘进焦点控件，**并把用户原来的剪贴板内容还原回去**。
+   *
+   * 不是 `clipboard_write` + `hotkey` 的语法糖，两点区别都是实质的：
+   * ① 还原必须先**读**剪贴板，而剪贴板读是被产品策略禁掉的（那里正是密码管理器
+   *    放凭据的地方）。禁的是**模型看见**，不是守护进程碰——所以存/还原整个收在
+   *    守护进程内部，旧内容不过线路、不进模型、不进审计。
+   * ② 两步版本中间有一段「剪贴板已被覆盖、但还没粘贴」的窗口，这期间中断就等于
+   *    把用户的剪贴板白白吃掉。
+   *
+   * 只对**模型显式要求**的 `clipboard_write` 保持不还原——那是有意要留在剪贴板上的。
+   */
+  | 'grab_region_to_clipboard'
+  | 'activate_app'
+  | 'window'
+  | 'file_drop'
+  | 'settle'
+  | 'wait_stable'
+  | 'wait_for_element'
+  | 'wait_for_text'
+  | 'wait_for_window'
+  | 'wait'
+  | 'takeover'
+  | 'resume'
+  | 'stop'
+  | 'emergency_stop';
+
+/**
+ * Actions that are both wired and implemented by the currently shipped native
+ * baseline. Keep this list conservative: exposing an action to the model is a
+ * product promise, not a placeholder for a future platform driver.
+ *
+ * Keep host-only control transitions (takeover/resume) and planned primitives
+ * out of the model schema until their native protocol exists. They remain in
+ * ComputerUseAction so callers receive an explicit `unsupported` response
+ * instead of being translated into a different, dangerous action.
+ */
+export const COMPUTER_USE_TOOL_ACTIONS = [
+  'status', 'permissions', 'observe', 'replay',
+  'click', 'double_click', 'right_click', 'middle_click', 'hover',
+  'pointer_down', 'pointer_move', 'pointer_up', 'drag', 'scroll',
+  'type', 'key', 'hotkey',
+  // ⚠️ 这里曾经还有 `press` / `release` / `call_user` 三个 —— 它们出现在给模型的
+  // 动作枚举和工具描述里，但 `nativeAction()` 没有对应 case、`waitFor` 也不接管，
+  // 模型一调就掉进 default 抛 `尚未映射到原生动作协议`；守护进程的 `capabilities()`
+  // 也**从来没有**宣传过它们。也就是说这是 TS 单方面多报。
+  //   · press/release（按住/松开某个键）：`hotkey` 已覆盖组合键；真要按住修饰键跨动作，
+  //     得先解决「run 中途中断时那个键永远卡在按下状态」，那是另一件事，不是补个 case。
+  //   · call_user：与 `AskUserQuestion` 工具重复，后者是已验证的通道。
+  // 三个都从模型可见面移除，`computerUseActionDispatch.test.ts` 锁住「列表里每个动作
+  // 都必须真的能被分派」。要加回来，先实现，再进这个列表。
+  // 闭环：动作后用像素判「界面稳了没」，比再看一张图便宜两个数量级。
+  'settle',
+  // 旁路通道：能不走像素就不走。
+  'clipboard_write', 'grab_region_to_clipboard', 'file_drop',
+  // 窗口控制：像素上根本表达不了「激活一个没在前台的应用」。
+  'activate_app', 'window',
+  // 语义等待：在此之前模型只能 observe→看→observe 地轮询，每轮烧一张图
+  // （约 1100 token）。这三个改用元数据观测轮询，一轮几乎不花 token。
+  // 实现是纯 TS 编排（waitFor.ts），不经守护进程动作通道。
+  'wait_for_element', 'wait_for_text', 'wait_for_window',
+  'wait',
+  'stop', 'emergency_stop',
+] as const satisfies readonly ComputerUseAction[];
+
+export type ComputerUseToolAction = (typeof COMPUTER_USE_TOOL_ACTIONS)[number];
+
+export interface ComputerUseRequest {
+  protocolVersion: number;
+  requestId: string;
+  context: ComputerUseRunContext;
+  action: ComputerUseAction;
+  appId?: string;
+  windowId?: string;
+  displayId?: string;
+  elementId?: string;
+  expectedRevision?: string;
+  expectedEpoch?: number;
+  x?: number;
+  y?: number;
+  /** ★ UI-TARS bbox 支持：框选右下角坐标（0-1000），系统自动取中心点点击 */
+  x2?: number;
+  y2?: number;
+  toX?: number;
+  toY?: number;
+  dx?: number;
+  dy?: number;
+  button?: 'left' | 'right' | 'middle';
+  clickCount?: number;
+  text?: string;
+  key?: string;
+  /** 修饰键，如 ['command', 'shift']，用于 hotkey 动作 */
+  modifiers?: string[];
+  secondaryAction?: string;
+  direction?: 'up' | 'down' | 'left' | 'right';
+  pages?: number;
+  filePaths?: string[];
+  rect?: ComputerUseRect;
+  timeoutMs?: number;
+  quietMs?: number;
+  /** Internal host instruction: keep the native input lease through settle and post-observe. */
+  _verifiedAction?: {
+    quietMs: number;
+    timeoutMs: number;
+    region?: ComputerUseRect;
+  };
+  /** observe 时要附带多少帧连续画面。0/1 = 只给当前截图。 */
+  frames?: number;
+  /**
+   * 让守护进程在动作落地后顺手测一次界面变化率（填回 `changeRatio`）。
+   *
+   * **模型不设这个字段**（工具 schema 里没有它）。它由
+   * `computerUseService::shouldProbeChange` 按「输入类动作 + 上次观测的 AX 树
+   * 不可用」自动置上 —— 这是一条安全兜底的输入，不是模型可以调的旋钮。
+   */
+  probeChange?: boolean;
+  /**
+   * 变化率探测的 ROI，**逻辑点**（不是 0–1000 相对坐标）。
+   *
+   * 取自上一次观测的焦点控件矩形。它和 `rect` 不同：`rect` 是模型给的相对
+   * 坐标、要经换算；这个是从 AX 拿到的、本来就是逻辑点，**不能**再走一次
+   * 相对坐标映射，否则会被二次换算成一块完全不相干的区域。
+   */
+  probeRegion?: ComputerUseRect;
+  /** window 动作要做什么。缺省 focus。 */
+  windowOperation?: ComputerUseWindowOperation;
+  /**
+   * window `center` 用：true = 无条件摆到可用区正中。
+   *
+   * 缺省（false）只在窗口被裁切或被 Dock/菜单栏压住时才动它 —— 已经摆好的布局
+   * 不折腾，给「同屏多应用」留空间。
+   */
+  force?: boolean;
+  /** file_drop 用哪条路径把文件送进去。缺省 paste。 */
+  dropMethod?: ComputerUseDropMethod;
+  /** call_user 动作的消息内容 */
+  message?: string;
+}
+
+export type ComputerUseWindowOperation =
+  | 'focus'
+  | 'minimize'
+  | 'restore'
+  | 'close'
+  | 'move_resize'
+  | 'center';
+
+/**
+ * 文件投放的机制。
+ *
+ * **两种都不是真拖拽** —— macOS 的拖拽必须由**源应用**发起
+ * `NSDraggingSession`，第三方进程合成不出 AppKit 认账的那一套。名字保留
+ * `file_drop` 是为了协议稳定，但调用方必须知道实际发生的是什么。
+ *
+ *   paste       把文件引用放进剪贴板再 Cmd+V。覆盖面最广（访达/微信/邮件）
+ *   open_panel  驱动**已经打开的**文件面板：Cmd+Shift+G → 输入路径 → 确认。
+ *               对有明确「附件/导入」按钮的应用更稳，但它打不开那个面板
+ */
+export type ComputerUseDropMethod = 'paste' | 'open_panel';
+
+export type ComputerUseErrorCode =
+  | 'unavailable'
+  | 'unsupported'
+  | 'permission_denied'
+  | 'permission_required'
+  | 'invalid_request'
+  | 'invalid_coordinates'
+  | 'capture_transient'
+  | 'invalid_image'
+  | 'verification_failed'
+  | 'protocol_mismatch'
+  | 'stale_state'
+  | 'target_not_found'
+  | 'target_out_of_scope'
+  | 'grant_required'
+  | 'lease_conflict'
+  | 'human_input_detected'
+  | 'cancelled'
+  | 'timeout'
+  | 'app_unresponsive'
+  | 'human_intervention_required'
+  | 'internal';
+
+export interface ComputerUseResponse {
+  protocolVersion: number;
+  requestId: string;
+  ok: boolean;
+  state?: ComputerState;
+  content?: string;
+  images?: ComputerUseImageReference[];
+  data?: unknown;
+  postState?: ComputerState;
+  beforeState?: ComputerState;
+  verification?: ComputerUseVerification;
+  actionMarker?: ComputerUseActionMarker;
+  settle?: {
+    settled: boolean;
+    stableMs: number;
+    observedEpoch: number;
+    reason?: string;
+  };
+  error?: {
+    code: ComputerUseErrorCode;
+    message: string;
+    hint?: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+  };
+  /**
+   * 本次观测相对**上一次观测**的焦点变化语义（仅 observe 类请求会带）。
+   *
+   * `other-process` 是这里最要紧的一个值：前台窗口归 OS 管、应用拦不住，
+   * 所以「别的进程/用户把前台抢走了」是**唯一不会被自绘应用堵掉的信号**。
+   * 用户自己切了窗口、或弹了个系统对话框，agent 若继续按旧坐标点下去，
+   * 就是在别人的窗口上闭眼操作 —— 这类失败最危险且完全可检出。
+   */
+  focusChange?: import('./vision/focus.js').FocusChange;
+  /** 本次观测派生出的焦点快照（level 如实反映实际拿到哪一层）。 */
+  focus?: import('./vision/focus.js').FocusSnapshot;
+}
+
+export interface ComputerUseInputStatus {
+  context: Pick<ComputerUseRunContext, 'ownerId' | 'conversationKey' | 'runId'>;
+  detected: boolean;
+  inputType?: 'pointer' | 'keyboard' | 'scroll';
+  detectedAtMs?: number;
+}
+
+/**
+ * 动作意图。模型**自报**，与 WebBrowser 的 `intent` 同构。
+ *
+ * `submit` 声明「这一步会造成外部可见的、不可撤销的后果」——发消息、下单、
+ * 永久删除。它把所需能力从 interact/type 提升到 `submit`，从而触发额外的
+ * 人工确认。自报当然可能漏报，所以它不是唯一防线：`apps/<app>.md` 的
+ * `irreversible:` 声明能在模型没自报时独立命中（见 vision/appGuide.ts）。
+ */
+export type ComputerUseIntent = 'normal' | 'submit';
+
+export function requiredCapability(
+  action: ComputerUseAction,
+  intent: ComputerUseIntent = 'normal',
+): ComputerUseCapability {
+  if (['status', 'permissions', 'list_apps', 'observe', 'replay', 'settle', 'wait_stable', 'wait_for_element', 'wait_for_text', 'wait_for_window'].includes(action)) return 'observe';
+  // 意图优先于动作种类：一次 click 与一次 key 都可能是「发送」。
+  if (intent === 'submit' && isMutatingComputerUseAction(action)) return 'submit';
+  // clipboard_read 不在模型可见动作里 —— 见 ComputerUseAction 的说明。
+  if (action === 'clipboard_read') return 'clipboard-read';
+  if (['clipboard_write', 'grab_region_to_clipboard'].includes(action)) return 'clipboard-write';
+  if (action === 'file_drop') return 'file-drop';
+  if (action === 'type' || action === 'key' || action === 'hotkey' || action === 'select_text') return 'type';
+  return 'interact';
+}
+
+export function isMutatingComputerUseAction(action: ComputerUseAction): boolean {
+  return !['status', 'permissions', 'list_apps', 'observe', 'replay', 'settle', 'wait_stable', 'wait_for_element', 'wait_for_text', 'wait_for_window', 'wait'].includes(action);
+}
+
+/**
+ * 编译期契约断言：本工具的 `ComputerState` 必须满足线路协议承诺的
+ * `ComputerObservation` 结构子集。
+ *
+ * 方向是**工具依赖协议**：协议（`src/web/protocol.ts`）是 desktop / server 共享的
+ * 类型真值，它不该反过来 import 某个工具的内部模块。这行断言就是两者之间的接缝 ——
+ * 谁改窄了这几个字段（比如把 `screenshot.path` 改成可选、把 `windows` 删掉），
+ * 编译立刻红，而不是等到 desktop 面板运行时才发现读不到东西。
+ *
+ * 纯类型断言，不产生任何运行时代码。
+ */
+type _ComputerStateSatisfiesWireContract =
+  ComputerState extends import('../../web/protocol.js').ComputerObservation ? true : never;
+const _computerStateContractOk: _ComputerStateSatisfiesWireContract = true;
+void _computerStateContractOk;

package/src/tools/computeruse/telemetryLog.js

@@ -0,0 +1,57 @@
+/**
+ * ============================================================
+ *  telemetryLog.ts —— Computer Use 遥测的落地点
+ * ------------------------------------------------------------
+ *  `vision/telemetry.ts` 是**纯逻辑**（白名单过滤、连续失败计数、汇总）；
+ *  本模块是它与真实文件系统之间那一层：决定写哪个文件、失败怎么办、
+ *  以及从多少条记录里做判断。
+ *
+ *  为什么要分两层：纯逻辑那层要能在单测里对着内存数组跑，不该知道
+ *  `~/Library/Application Support` 存在；而路径与容量策略是部署问题，
+ *  不该混进算法里。
+ *
+ *  ★ 遥测的职责是**观测**：验证两个假设（见 vision/telemetry.ts 头注）。
+ *    它**不承担运行时安全职责** —— 连续失败熔断曾经建在这个文件上，那是
+ *    个错误：全机唯一的日志没有会话隔离（A 的失败熔断 B）、读改写有竞态、
+ *    而且计数不分动作（一次成功 observe 就清零，于是「失败→观察→失败」
+ *    这个最常见的打转模式可以无限绕过熔断）。熔断现在住在
+ *    `ComputerUseService`，按运行 + 动作指纹分桶，同步无 IO。
+ *
+ *  隐私：写盘前必经 `sanitizeRecord` 白名单，只留命令名、耗时、枚举值、
+ *  比例。屏幕内容、窗口标题、输入文本一律进不来 —— 那是白名单的实现保证，
+ *  不是调用方的自觉。
+ * ============================================================
+ */
+import { join } from 'node:path';
+import { computerUseStateDir } from './computerUseService.js';
+import { CONSECUTIVE_FAILURE_LIMIT, readRecords, record, renderReport, summarize, } from './vision/telemetry.js';
+function logPath() {
+    return join(computerUseStateDir(), 'telemetry.jsonl');
+}
+/**
+ * 记一条调用元数据。
+ *
+ * **永不抛异常、永不阻断主流程**：遥测是观测手段，不是功能。日志写不进去
+ * （磁盘满、目录只读）时宁可少一条记录，也不能让一次正常的桌面操作失败。
+ */
+export async function recordComputerUseCall(raw) {
+    try {
+        await record(logPath(), raw);
+    }
+    catch {
+        /* 观测失败不影响功能 */
+    }
+}
+export { CONSECUTIVE_FAILURE_LIMIT };
+/**
+ * 人类可读的遥测汇总，给 CLI/诊断用。
+ *
+ * 这是 SPEC §9 声称的「验证两个假设」真正的出口 —— 在此之前遥测模块整个
+ * 没有生产调用方，汇总函数写了却没人能看到结果。
+ */
+export async function readComputerUseTelemetryReport() {
+    const records = await readRecords(logPath()).catch(() => []);
+    if (records.length === 0)
+        return '还没有 Computer Use 遥测记录。';
+    return renderReport(summarize(records));
+}