@anionex/dsh-computer-use 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# One aggregate row initializes the macOS Service provider before publishing
+# the model-facing Skill and Agent-scoped Tools.
+- insert:
+    - id: computer-use
+      name: '@anionex/dsh-computer-use'
+      config:
+        observationTtlMs: 0
+        interaction:
+          focusPolicy: preserve
+          keyboardPolicy: activate
+          pointerInputPolicy: targeted
+          cursorVisualization: visible
+          cursorAutoHideMs: 0

package/docs/interaction-policy.i18n.yaml

@@ -0,0 +1,4 @@
+# Bilingual-pair consistency record. Both languages carry equal authority.
+# Recompute these git blob hashes after confirming the two documents say the same thing.
+interaction-policy.md: 6f2e9620b76a5e523f037fbd5abb8604b61c7a49
+interaction-policy.zh.md: 7f00e6c0ea6d9e10687a11276f2ca2e7575e3503

package/docs/interaction-policy.md

@@ -0,0 +1,140 @@
+# Foreground-safe input policy
+
+## Requirement
+
+DSH Computer Use must let an Agent operate a native macOS application while the user continues working elsewhere. The default pointer path must not move the system cursor, post pointer events to the global HID stream, or activate the target application merely to make a pointer action work. Keyboard input is the one deliberate exception: the Bundle enables `keyboardPolicy: activate` so typing works reliably by bringing the target app to the foreground first, matching Codex Computer Use behavior. Pointer actions may show a separate Agent cursor, but that overlay must never become an input source or a window manager participant.
+
+The default Bundle configuration is:
+
+```yaml
+interaction:
+  focusPolicy: preserve
+  keyboardPolicy: activate
+  pointerInputPolicy: targeted
+  cursorVisualization: visible
+  cursorMotionMs: 180
+  cursorAutoHideMs: 0
+```
+
+`preserve` means pointer actions do not request foreground activation. `keyboardPolicy: activate` (the Bundle default) requests foreground activation before `type-text` keyboard fallback and `press-key`; `keyboardPolicy: preserve` keeps typing routed to the selected pid without activation and is reliable only for applications that accept background keyboard events. `targeted` means mouse, drag, and wheel events may be sent only to the exact observed process and window. `visible` enables the separate Agent cursor, whose motion and auto-hide timing are also host-owned. The model cannot change any interaction policy through Tool arguments.
+
+This is an input-routing property, not a consequence of Accessibility permission alone. Accessibility grants semantic UI access; foreground preservation comes from choosing semantic Accessibility operations first and using process/window-targeted fallback instead of the system cursor.
+
+## Overall design
+
+The action path has five ordered layers:
+
+1. The DSH Service binds the request to one unexpired observation, exact bundle id, pid, window, and element target handle, compatibility index, window-relative point, or screen-global point.
+2. For a handle action, the Service obtains fresh Accessibility state and resolves the target through the original locator, one unique provider-native identifier, or one unique semantic role/name/actions/ancestor match. Application, process, and selected-window identity remain exact; ambiguity and low confidence fail closed.
+3. The native helper observes the resolved target again and rejects any race that changed its locator, properties, process, or window before input.
+4. The helper prefers `AXPress`, Accessibility value assignment, selected-text assignment, or an action advertised by the element. When a `click` target advertises `AXPress` but macOS rejects the press, the helper retries `AXPress` on the element's pressable descendants within a bounded depth before considering the element-frame or coordinate pointer route.
+5. When semantic input is unavailable, keyboard events are posted to the selected pid and pointer events are posted to the selected pid and window. No pointer fallback uses a global event tap.
+
+Pointer delivery uses the observed window when it contains the point; otherwise it resolves the topmost on-screen window of the selected app that contains the screen point and posts through `SLEventPostToPid` with the pid/window fields and window-local coordinates. This is the same target-process shape Codex Computer Use uses (`SynthesizedEvent.send(to: pid)` with `CGWindow.window(at:)`), so `coordinateSpace: screen` supports arbitrary-coordinate clicks without a global HID event stream. Unavailable SkyLight symbols or a point outside every window of the selected app fails closed.
+
+Visual feedback uses a 28x28 `NSPanel` owned by a dedicated, persistent cursor process. The panel is borderless, nonactivating, click-through, and excluded from normal window cycling; it is not made visible on every Space. It draws the embedded transparent whole-image cursor (`assets/cursor.png`, Cursor arrow plus DeepSeek whale) with its top-left corner at the target point. Before input it animates to the same screen-global target point using an ease-out motion, briefly compresses the image for click, and keeps it pressed through a drag. By default it stays at the target point until the bound window changes or a hide command; set `cursorAutoHideMs` to a finite value for inactivity auto-hide. The overlay never posts input and never changes the system cursor position.
+
+Policy is enforced twice on the supported DSH Tool path. The Service rejects a known pointer or foreground requirement before obtaining a control lease or consuming a sensitive-action confirmation. The helper validates the same resolved policy immediately before input, including fallback decisions that can only be made at runtime. The helper also requires an isolated process group plus three standard pipe or Unix-socket transports whose peer endpoints belong to its direct parent process; ordinary shell redirection fails closed before any command is parsed. This transport check is defense in depth, not authentication against arbitrary code running as the same macOS user: a deliberately constructed detached parent can reproduce the topology, especially under `danger-full-access`. The registered Tool path remains the only supported route because it applies leases, confirmations, and host policy before invoking the helper.
+
+Every action result reports the route actually used:
+
+```ts
+activation: 'not-requested' | 'already-frontmost' | 'activated'
+pointerInput: boolean
+pointerRouting: 'none' | 'target-process'
+resolution?: {
+  mode: 'exact-locator' | 'native-identifier' | 'semantic-rebind'
+  confidence: number
+  candidateCount: number
+  targetChanged: boolean
+}
+```
+
+These fields do not claim that a target application can never change focus as its own side effect. They report only what the helper requested and emitted.
+
+## Action matrix
+
+| Action path | Default activation | Pointer route | Default result |
+|---|---|---|---|
+| `click` through `AXPress` | None | None | Allowed |
+| `set-value` through Accessibility | None | None | Allowed |
+| non-foreground `perform-action` advertised by the element | None | None | Allowed |
+| `AXRaise` | Denied | None | Requires explicit `focusPolicy: activate`, then re-observation/revalidation |
+| `type-text` through selected-text assignment | None | None | Allowed when the focused element accepts it |
+| `type-text` keyboard fallback | None with `keyboardPolicy: preserve`; `activated` with `keyboardPolicy: activate` | Target pid | Allowed; activation makes it reliable |
+| `press-key` | None with `keyboardPolicy: preserve`; `activated` with `keyboardPolicy: activate` | Target pid | Allowed; activation makes it reliable |
+| coordinate click or element-frame fallback | None | Target pid + window | Allowed when `pointerInputPolicy: targeted` |
+| scroll | None | Target pid + window | Allowed when `pointerInputPolicy: targeted` |
+| drag | None | Target pid + window | Allowed when `pointerInputPolicy: targeted` |
+
+`pointerInputPolicy: deny` disables coordinate click/fallback, scroll, and drag while leaving semantic Accessibility and process-targeted keyboard paths available. `coordinateSpace: window` (default) resolves coordinates inside the observed window frame; `coordinateSpace: screen` accepts Quartz screen-global points.
+
+## Critical decisions
+
+### Host policy is not a Tool argument
+
+The deployment owns `focusPolicy`, `keyboardPolicy`, and `pointerInputPolicy`. `allowCoordinateFallback` says only that `computer_click` may try the host-authorized pointer route after `AXPress` is unavailable. It cannot enable pointer delivery or foreground activation. `computer_perform_action` also treats `AXRaise` as foreground-affecting and rejects it under `preserve`.
+
+### Accessibility remains the primary route
+
+Semantic Accessibility operations are more stable than pixels and need no cursor emulation. They also work against many background applications. The helper revalidates the exact target before invoking them and reports `activation: not-requested`, `pointerInput: false`, and `pointerRouting: none`.
+
+### Stable handles rebind only with independent identity evidence
+
+The public `targetHandle` is opaque and observation-local; it does not expose an `AXUIElement`, locator, or `AXIdentifier`. The Service stores the normalized descriptor in Agent-owned memory and re-observes immediately before a handle action. Exact locator identity is preferred. Rebinding is opt-in through `allowRebind` and requires either one provider-native identifier whose stable semantics still match or one semantic candidate with the same role, normalized accessible name, advertised actions, and stable ancestor fingerprint. The resolver preserves the exact bundle id, pid, and selected-window identity. A truncated tree cannot authorize rebinding. Duplicate candidates return `COMPUTER_TARGET_AMBIGUOUS`; missing or insufficient evidence returns `COMPUTER_TARGET_LOW_CONFIDENCE`.
+
+Sensitive confirmation is bound to the exact handle action. Any native-identifier or semantic fallback marks the target changed, invalidates the prior token, and returns `COMPUTER_TARGET_REBIND_REQUIRES_CONFIRMATION` before input. Coordinates and screenshot-derived boxes cannot become handles, identity evidence, or authorization for a sensitive target. The caller must select the current handle and obtain a new one-use confirmation. Provider-native visual hit-testing remains a separate follow-up because the current visual workflow cannot independently validate a screenshot coordinate.
+
+### The default pointer route is virtual and target-specific
+
+The helper never moves the system cursor and then tries to restore it. That design would still interrupt the user, race with real input, and risk delivering an event to the wrong application.
+
+Instead, pointer fallback creates an event at the target screen point, binds it to the exact pid and `CGWindowID` (the observed window when it contains the point, otherwise the topmost app window under the point), supplies the window-local point expected by AppKit, and sends it through the per-process SkyLight route. Click, scroll, and drag share this route. The committed helper contains no `CGWarpMouseCursorPosition`, global `CGEventPost`, or `.post(tap: .cghidEventTap)` path.
+
+### Cursor visualization is presentation-only
+
+The visible Agent cursor is deliberately not the input source. It is a separate process with a strict JSON-lines protocol and a startup-ready handshake. Every show, press, and release is bound to the observed pid, `CGWindowID`, and expected frame; a closed, moved, resized, minimized, or off-screen window hides the overlay. Because presentation is separate from routing, disabling the cursor cannot change action semantics and overlay failure cannot redirect or globally emit input.
+
+### Activation is an explicit compatibility mode
+
+Some applications accept input only while active. A deployment may set `focusPolicy: activate` (all actions) or `keyboardPolicy: activate` (keyboard actions only), accepting that the target application can take the foreground. Before emitting input, the helper activates the exact process and observes it again. Element and window targets are revalidated; for keyboard actions the refreshed focused element is the target, because activation may move focus to the app's default control. Any element/window mismatch fails with `COMPUTER_STALE_OBSERVATION` instead of acting on the pre-activation target.
+
+With `focusPolicy: preserve` and `keyboardPolicy: preserve`, the helper never performs this activation step.
+
+### Pointer delivery fails closed
+
+Target-process pointer delivery resolves the window from the point itself: the observed window is used when its frame contains the point; otherwise the helper takes the topmost on-screen window of the selected app whose frame contains the point. Observation still captures `AXWindowNumber` when available and falls back to a unique frame/title match, but coordinate actions no longer require that match. A point outside every on-screen window of the selected app fails closed instead of falling back to the global cursor.
+
+### Private SPI is isolated and optional at runtime
+
+The per-process pointer route uses dynamically resolved SkyLight symbols. This keeps the failure explicit on an unsupported macOS build: semantic Accessibility and process-targeted keyboard input remain available, while pointer fallback returns `COMPUTER_ACTION_BLOCKED`. The helper never silently changes to global pointer injection.
+
+## Verified evidence
+
+The release evidence covers both implementation and observed behavior:
+
+- source and binary checks reject system-cursor warp symbols, the exact global `CGEventPost` symbol, and unknown dynamically resolved native symbols;
+- overlay checks require a nonactivating panel, click-through hit testing, prohibited application activation policy, and no cursor-warp primitive;
+- the overlay runtime rejects missing or malformed target identity, oversized or invalid JSON-lines commands, unsupported timing, and direct helpers that do not own a managed parent transport;
+- a real overlay process must emit its ready frame before commands, reuse one process across commands, and stop cleanly on disposal;
+- a native monitor requires the overlay to be the only 28x28 window owned by its process, not become frontmost, and produce no global pointer events from that process pid;
+- the helper must contain `SLEventPostToPid` and `CGEventSetWindowLocation`;
+- a coordinate click without an observed window id resolves the app window under the Quartz screen point and still reports `pointerRouting: target-process`;
+- `keyboardPolicy: activate` makes a background fixture become active and receive the key event, and the fixture transcript records the activation;
+- the fixture is started through `open -g` with `--background`, so LaunchServices does not request foreground activation;
+- the fixture records every `applicationDidBecomeActive` callback and the default path must not increase `activationCount`;
+- an independent native monitor samples cursor position and the frontmost pid every millisecond throughout click, scroll, and drag; every sample must remain unchanged;
+- background `AXPress`, Accessibility value/action, selected-text input, and pid-targeted key input change the fixture without activating it;
+- the native fixture inserts a harmless sibling and recreates a uniquely identified checkbox, proving the raw locator becomes stale while `AXIdentifier` resolution still finds exactly one target;
+- target-process click and scroll are each observed exactly once; drag has exactly one down/up gesture; the target remains non-frontmost;
+- `pointerInputPolicy: deny` rejects click fallback, scroll, and drag before any target pointer event is delivered;
+- clean Profile and real-model validation require the model-visible action result and fixture transcript to agree.
+
+## Known limitations
+
+- Target-process pointer delivery is less universal than semantic Accessibility. Custom canvases, games, hardened input surfaces, or future macOS changes may reject it.
+- The clicked point must fall inside an on-screen window of the selected app; minimized, fully hidden, or windowless targets fail closed.
+- `focusPolicy: activate` and `keyboardPolicy: activate` are intentionally disruptive and exist only as operator-selected compatibility modes.
+- A target application may change its own activation or focus as a side effect of an accepted action; the helper does not claim control over application-internal behavior.
+- The Agent cursor is scoped to one active Space and the exact observed window. `cursorAutoHideMs: 0` keeps it visible until the bound window changes, a new hide command arrives, or the helper is disposed.
+- Stable handles currently use exact locators, provider-native identifiers, and strict semantic identity. Semantic-spatial rebinding and provider-native visual hit-testing remain follow-up work; a vision-derived coordinate alone is never a verified target.

package/docs/interaction-policy.zh.md

@@ -0,0 +1,140 @@
+# 前台安全输入策略
+
+## 需求
+
+DSH Computer Use 应让 Agent 操作原生 macOS 应用时，用户仍能在其他应用中继续工作。默认指针路径不能移动系统光标、向全局 HID 事件流投递指针事件，也不能只为完成指针动作就激活目标应用。键盘输入是唯一刻意例外：Bundle 默认启用 `keyboardPolicy: activate`，通过先把目标应用带到前台来让输入可靠工作，这与 Codex Computer Use 的行为一致。指针动作可以显示独立 Agent 光标，但 overlay 绝不能成为输入源或窗口管理器参与者。
+
+Bundle 默认配置为：
+
+```yaml
+interaction:
+  focusPolicy: preserve
+  keyboardPolicy: activate
+  pointerInputPolicy: targeted
+  cursorVisualization: visible
+  cursorMotionMs: 180
+  cursorAutoHideMs: 1400
+```
+
+`preserve` 表示指针动作不请求前台激活。`keyboardPolicy: activate`（Bundle 默认）会在 `type-text` 键盘 fallback 与 `press-key` 前请求前台激活；`keyboardPolicy: preserve` 仍把键盘事件定向投递给选定 pid 而不激活，只有接受后台键盘事件的应用才可靠。`targeted` 表示鼠标、拖拽和滚轮事件只能投递给准确的已观察进程与窗口。`visible` 开启独立 Agent 光标，其移动与自动隐藏时长同样归宿主所有。模型不能通过 Tool 参数修改任何交互策略。
+
+这是一项输入路由属性，并不是只要拿到 Accessibility 权限就自然成立。Accessibility 授予语义化 UI 访问能力；真正避免抢前台的是优先使用语义化 Accessibility 操作，并用进程/窗口定向 fallback 代替系统光标。
+
+## 总体设计
+
+动作路径按以下五层执行：
+
+1. DSH Service 把请求绑定到一个未过期 observation、准确 bundle id、pid、窗口，以及 element target handle、兼容 index、窗口相对坐标或屏幕全局坐标。
+2. 对 handle 动作，Service 会获取新鲜 Accessibility 状态，并通过原 locator、唯一 provider-native identifier，或唯一 semantic role/name/actions/ancestor match 解析目标。应用、进程与选定窗口身份始终保持准确；歧义和低置信度都会 fail closed。
+3. Native helper 会再次观察已解析目标，并拒绝输入前发生的 locator、属性、进程或窗口竞态变化。
+4. Helper 优先使用 `AXPress`、Accessibility value 赋值、selected-text 赋值，或元素声明的 action。当 `click` 目标声明了 `AXPress` 但 macOS 拒绝执行时，helper 会在有界深度内重试该元素可点击子节点的 `AXPress`，之后才考虑元素 frame 或坐标指针路由。
+5. 语义输入不可用时，键盘事件定向投递到选定 pid；指针事件定向投递到选定 pid 和窗口。任何指针 fallback 都不使用全局 event tap。
+
+指针投递在点位于已观察窗口内时直接使用该窗口；否则解析选定应用在该屏幕点下最上层的屏幕内窗口，再通过 `SLEventPostToPid` 投递并附带 pid/window 字段与窗口本地坐标。这与 Codex Computer Use 的 target-process 形态一致（`SynthesizedEvent.send(to: pid)` 配合 `CGWindow.window(at:)`），因此 `coordinateSpace: screen` 无需全局 HID 事件流即可支持任意坐标点击。SkyLight symbol 不可用，或该点不在选定应用的任何屏幕内窗口中时都会 fail closed。
+
+视觉反馈由专用、常驻的光标进程创建 28x28 `NSPanel`。该 panel 无边框、不激活应用、点击穿透，并且不会进入普通窗口切换列表；它不会在全部 Space 上显示。它绘制嵌入的透明整图光标（`assets/cursor.png`，Cursor 箭头加 DeepSeek 鲸鱼），图片左上角对准目标点。输入前它会以 ease-out 动画移动到相同的屏幕全局目标点，click 时短暂压缩图片，drag 期间保持按压状态。默认它会停留在目标点，直到绑定窗口变化或收到 hide 命令；设置 `cursorAutoHideMs` 为有限值可以开启空闲自动隐藏。这个 overlay 不发出输入，也不会改变系统光标位置。
+
+受支持的 DSH Tool 路径会执行两层策略检查。Service 会在申请 control lease 或消费敏感动作 confirmation 之前拒绝已知需要指针或前台权限的动作；helper 会在真正发出输入前再次校验同一份已解析策略，包括只能在运行时确定的 fallback。Helper 还要求独立进程组，以及三条标准 pipe 或 Unix socket 传输的对端都属于它的直接父进程；普通 shell 重定向会在解析命令前 fail closed。这个传输检查只属于纵深防御，不会认证同一 macOS 用户下运行的任意代码：专门构造的 detached 父进程仍能复现这类拓扑，尤其是在 `danger-full-access` 下。注册 Tool 路径仍是唯一受支持的调用方式，因为它会在调用 helper 前执行 lease、confirmation 与宿主策略。
+
+每个动作结果都会报告实际使用的路由：
+
+```ts
+activation: 'not-requested' | 'already-frontmost' | 'activated'
+pointerInput: boolean
+pointerRouting: 'none' | 'target-process'
+resolution?: {
+  mode: 'exact-locator' | 'native-identifier' | 'semantic-rebind'
+  confidence: number
+  candidateCount: number
+  targetChanged: boolean
+}
+```
+
+这些字段不会声称目标应用绝不可能因自身副作用改变焦点，只报告 helper 实际请求和发出的行为。
+
+## 动作矩阵
+
+| 动作路径 | 默认激活行为 | 指针路由 | 默认结果 |
+|---|---|---|---|
+| 通过 `AXPress` 的 `click` | 不激活 | 无 | 允许 |
+| 通过 Accessibility 的 `set-value` | 不激活 | 无 | 允许 |
+| 元素声明且不影响前台的 `perform-action` | 不激活 | 无 | 允许 |
+| `AXRaise` | 拒绝 | 无 | 需要显式 `focusPolicy: activate`，随后重新观察/校验 |
+| 通过 selected-text 赋值的 `type-text` | 不激活 | 无 | 当前 focused element 接受时允许 |
+| `type-text` 键盘 fallback | `keyboardPolicy: preserve` 不激活；`keyboardPolicy: activate` 激活 | 目标 pid | 允许；激活后更可靠 |
+| `press-key` | `keyboardPolicy: preserve` 不激活；`keyboardPolicy: activate` 激活 | 目标 pid | 允许；激活后更可靠 |
+| 坐标点击或元素 frame fallback | 不激活 | 目标 pid + window | `pointerInputPolicy: targeted` 时允许 |
+| 滚动 | 不激活 | 目标 pid + window | `pointerInputPolicy: targeted` 时允许 |
+| 拖拽 | 不激活 | 目标 pid + window | `pointerInputPolicy: targeted` 时允许 |
+
+`pointerInputPolicy: deny` 会禁用坐标点击/fallback、滚动和拖拽，但保留语义化 Accessibility 与进程定向键盘路径。`coordinateSpace: window`（默认）在已观察窗口 frame 内解释坐标；`coordinateSpace: screen` 接受 Quartz 屏幕全局坐标。
+
+## 关键决策
+
+### 宿主策略不是 Tool 参数
+
+`focusPolicy`、`keyboardPolicy` 与 `pointerInputPolicy` 归部署方所有。`allowCoordinateFallback` 只表示 `computer_click` 在 `AXPress` 不可用后可以尝试宿主已授权的指针路由，不能自行开启指针投递或前台激活。`computer_perform_action` 也会把 `AXRaise` 视为影响前台的动作，并在 `preserve` 下拒绝。
+
+### Accessibility 始终是主路径
+
+语义化 Accessibility 操作比像素坐标更稳定，不需要模拟光标，并且能在许多后台应用上工作。Helper 会先重新校验准确目标，再调用这些操作，并返回 `activation: not-requested`、`pointerInput: false` 和 `pointerRouting: none`。
+
+### Stable handle 只在独立身份依据充分时 rebind
+
+公开的 `targetHandle` 是 opaque 且 observation-local 的；它不暴露 `AXUIElement`、locator 或 `AXIdentifier`。Service 把 normalized descriptor 保存在 Agent 自有内存中，并在 handle 动作前立即重新观察。系统优先使用准确 locator 身份。Rebind 必须通过 `allowRebind` 显式启用，并且只能依赖稳定语义仍一致的唯一 provider-native identifier，或 role、normalized accessible name、已声明 action 与稳定 ancestor fingerprint 全部一致的唯一 semantic candidate。Resolver 保留准确 bundle id、pid 与选定窗口身份。Truncated tree 不能授权 rebind。重复 candidate 返回 `COMPUTER_TARGET_AMBIGUOUS`；证据缺失或不足返回 `COMPUTER_TARGET_LOW_CONFIDENCE`。
+
+敏感 confirmation 绑定准确 handle action。任何 native-identifier 或 semantic fallback 都会把目标标记为 changed，在输入前使旧 token 失效，并返回 `COMPUTER_TARGET_REBIND_REQUIRES_CONFIRMATION`。坐标与截图-derived box 不能变成 handle、身份依据或敏感目标授权。调用方必须选择当前 handle，并获取新的单次 confirmation。Provider-native visual hit-test 被明确拆为后续能力，因为当前视觉流程无法独立校验截图坐标。
+
+### 默认指针路由是虚拟且目标定向的
+
+Helper 不会先移动系统光标再尝试恢复。那种设计仍会打断用户、与真实输入竞争，还可能把事件送错应用。
+
+指针 fallback 会在目标屏幕点创建事件，将其绑定到准确 pid 和 `CGWindowID`（点位于已观察窗口内时使用该窗口，否则使用该点下选定应用的最上层窗口），填入 AppKit 需要的窗口本地坐标，再通过 SkyLight 的进程定向路由发出。点击、滚动与拖拽共用这条路径。提交的 helper 不包含 `CGWarpMouseCursorPosition`、全局 `CGEventPost` 或 `.post(tap: .cghidEventTap)` 路径。
+
+### 光标可视化只负责展示
+
+可见 Agent 光标有意不作为输入源。它是独立进程，使用严格 JSON-lines 协议和启动就绪握手。每次 show、press 与 release 都绑定已观察的 pid、`CGWindowID` 和预期 frame；目标窗口关闭、移动、缩放、最小化或离开屏幕时，overlay 会隐藏。由于展示与输入路由彼此独立，关闭光标不会改变动作语义，overlay 失败也不能改道或全局发出输入。
+
+### 激活是显式兼容模式
+
+少数应用只有在 active 状态下才接受输入。部署方可以设置 `focusPolicy: activate`（全部动作）或 `keyboardPolicy: activate`（仅键盘动作），并明确接受目标应用可能抢到前台。Helper 会先激活准确进程并再次观察；元素与窗口目标会被重新校验，键盘动作则以刷新后的 focused element 为目标，因为激活可能把焦点移到应用默认控件。任何元素/窗口不匹配都会返回 `COMPUTER_STALE_OBSERVATION`，而不是继续操作激活前的目标。
+
+`focusPolicy: preserve` 且 `keyboardPolicy: preserve` 时，helper 不会执行这个激活步骤。
+
+### 指针投递必须 fail closed
+
+目标进程指针投递直接从点解析窗口：点位于已观察窗口 frame 内时使用该窗口；否则取选定应用在屏幕内且 frame 包含该点的最上层窗口。observation 仍会在可用时捕获 `AXWindowNumber`，并回退到唯一 frame/title 匹配，但坐标动作不再依赖该匹配。点不在选定应用任何屏幕内窗口时 fail closed，而不是退回全局光标。
+
+### Private SPI 被隔离并允许运行时缺失
+
+进程定向指针路由使用动态解析的 SkyLight symbol。这样在不支持的 macOS 版本上会明确失败：语义化 Accessibility 与进程定向键盘输入仍可用，指针 fallback 返回 `COMPUTER_ACTION_BLOCKED`。Helper 不会静默切换成全局指针注入。
+
+## 已验证证据
+
+发布证据同时覆盖实现与真实行为：
+
+- 源码与 binary 检查会拒绝系统光标 warp symbol、准确的全局 `CGEventPost` symbol，以及未知的动态解析 native symbol；
+- overlay 检查要求 nonactivating panel、点击穿透、prohibited 应用激活策略，并拒绝任何 cursor warp primitive；
+- overlay runtime 会拒绝缺失或格式错误的目标身份、超长或非法 JSON-lines 命令、不支持的时长，以及不拥有托管父进程传输的直接 helper 调用；
+- 真实 overlay 进程必须在执行命令前输出 ready frame，多条命令复用同一进程，并在释放时干净退出；
+- native monitor 要求 overlay 是该进程拥有的唯一 28x28 窗口、不会成为前台，且该进程 pid 不产生任何全局 pointer event；
+- helper 必须包含 `SLEventPostToPid` 与 `CGEventSetWindowLocation`；
+- 不携带已观察窗口 id 的坐标点击会按 Quartz 屏幕点解析应用窗口，结果仍报告 `pointerRouting: target-process`；
+- `keyboardPolicy: activate` 会让后台 fixture 变为前台并收到按键事件，fixture transcript 记录这次激活；
+- fixture 通过 `open -g` 与 `--background` 启动，LaunchServices 不会请求前台激活；
+- fixture 记录每次 `applicationDidBecomeActive` 回调，默认路径不得增加 `activationCount`；
+- 独立 native monitor 会在 click、scroll 与 drag 整个动作期间每毫秒采样系统光标和前台 pid，所有采样都必须保持不变；
+- 后台 `AXPress`、Accessibility value/action、selected-text 输入与 pid 定向按键都能修改 fixture 且不激活它；
+- native fixture 会插入无害 sibling 并重建一个带唯一 identifier 的 checkbox，证明原始 locator 已 stale，而 `AXIdentifier` resolution 仍只找到一个目标；
+- 目标进程 click 与 scroll 各只被观察到一次；drag 只产生一组 down/up gesture；目标始终不是前台应用；
+- `pointerInputPolicy: deny` 会在任何目标指针事件发出前拒绝 click fallback、scroll 与 drag；
+- 干净 Profile 与真实模型验证要求模型可见动作结果和 fixture transcript 相互一致。
+
+## 已知限制
+
+- 目标进程指针投递不如语义化 Accessibility 普适。自定义 canvas、游戏、强化输入 surface 或未来 macOS 变化可能拒绝该路由。
+- 点击点必须落在选定应用的某个屏幕内窗口里；最小化、完全隐藏或无窗口目标会 fail closed。
+- `focusPolicy: activate` 与 `keyboardPolicy: activate` 会有意打断前台工作，只作为操作方显式选择的兼容模式。
+- 目标应用可能因接受动作而自行改变 activation 或 focus；helper 不承诺控制应用内部副作用。
+- Agent 光标只属于当前 Space 和准确已观察窗口。`cursorAutoHideMs: 0` 会让它持续显示，直到绑定窗口变化、收到新的 hide 命令或 helper 被释放。
+- Stable handle 当前只使用准确 locator、provider-native identifier 与严格 semantic identity。Semantic-spatial rebind 和 provider-native visual hit-test 留作后续；仅凭 vision 得到的坐标永远不是已验证目标。

package/lib/approval-policy.js

@@ -0,0 +1,12 @@
+/** Shared DSH approval-policy read for Computer Use permission paths. */
+/**
+ * The session's effective DSH approval policy: a logged override, else the
+ * approval plugin's configured default.
+ * @param ctx - context with the approval service injected.
+ * @param agent - the agent whose session policy applies.
+ * @returns `'never'` when every approval ask would auto-reject without a prompt.
+ */
+export function approvalPolicy(ctx, agent) {
+    return ctx.approval.overrideOf(agent.session) ?? ctx.approval.config.policy ?? 'ask';
+}
+//# sourceMappingURL=approval-policy.js.map

package/lib/approval-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-policy.js","sourceRoot":"","sources":["../src/approval-policy.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAMzE;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,KAAY;IACvD,OAAO,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK,CAAA;AACtF,CAAC"}

package/lib/artifacts.js

@@ -0,0 +1,79 @@
+/** Workspace-fenced screenshot artifact allocation and validation. */
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, realpath, stat } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+import { ComputerUseError } from "./errors.js";
+/** Screenshot description that hands visual analysis to the sibling Vision Toolkit. */
+export const COMPUTER_SCREENSHOT_DESCRIPTION = [
+    'Current macOS application window observation.',
+    'For OCR, visual grounding, or pixel inspection, load the vision-tools Skill and pass this exact path to vision_glance, vision_ground, vision_detect, or vision_crop;',
+    'do not recreate OCR with bash, tesseract, or an ad hoc script.',
+].join(' ');
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+async function rejectSymlinkComponents(root, target) {
+    const rel = relative(root, target);
+    let current = root;
+    for (const part of rel.split(sep).filter(Boolean)) {
+        current = resolve(current, part);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink()) {
+                throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `artifact path component must not be a symbolic link: ${part}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof ComputerUseError)
+                throw error;
+            const code = error.code;
+            if (code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+/** Allocate a unique managed PNG path inside the current Session workspace. */
+export async function allocateScreenshotPath(workspace, artifactRoot, sessionId) {
+    const realWorkspace = await realpath(workspace);
+    const directory = resolve(realWorkspace, artifactRoot, String(sessionId));
+    if (!isWithin(realWorkspace, directory)) {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'artifactRoot escapes the Session workspace');
+    }
+    await rejectSymlinkComponents(realWorkspace, directory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const realDirectory = await realpath(directory);
+    if (!isWithin(realWorkspace, realDirectory)) {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'artifact directory escaped the Session workspace');
+    }
+    return resolve(realDirectory, `observation-${randomUUID()}.png`);
+}
+/** Validate a committed screenshot and return its stable model/client descriptor. */
+export async function describeScreenshot(path, width, height, maxBytes, sourceTool) {
+    const link = await lstat(path).catch((error) => {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'the screenshot artifact was not created', { cause: error });
+    });
+    if (link.isSymbolicLink() || !link.isFile()) {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'the screenshot artifact must be a regular non-symbolic-link file');
+    }
+    const info = await stat(path);
+    if (info.size > maxBytes) {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `screenshot exceeds maxScreenshotBytes (${info.size} > ${maxBytes})`);
+    }
+    if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) {
+        throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'provider returned invalid screenshot dimensions');
+    }
+    return {
+        path,
+        filename: basename(path),
+        mimeType: 'image/png',
+        kind: 'image',
+        description: COMPUTER_SCREENSHOT_DESCRIPTION,
+        sourceTool,
+        previewIntent: 'image',
+        bytes: info.size,
+        width,
+        height,
+    };
+}
+//# sourceMappingURL=artifacts.js.map

package/lib/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAG9C,uFAAuF;AACvF,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,+CAA+C;IAC/C,sKAAsK;IACtK,gEAAgE;CACjE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAEX,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAiB;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IACrC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AACxF,CAAC;AAED,KAAK,UAAU,uBAAuB,CAAC,IAAY,EAAE,MAAc;IACjE,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,IAAI,OAAO,GAAG,IAAI,CAAA;IAClB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAClD,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,CAAA;YACjC,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC1B,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,wDAAwD,IAAI,EAAE,CAAC,CAAA;YACzH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,gBAAgB;gBAAE,MAAM,KAAK,CAAA;YAClD,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAA;YAClD,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAA;QACpC,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAiB,EACjB,YAAoB,EACpB,SAAoB;IAEpB,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;IACzE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,4CAA4C,CAAC,CAAA;IACvG,CAAC;IACD,MAAM,uBAAuB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvD,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IACxD,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC/C,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,kDAAkD,CAAC,CAAA;IAC7G,CAAC;IACD,OAAO,OAAO,CAAC,aAAa,EAAE,eAAe,UAAU,EAAE,MAAM,CAAC,CAAA;AAClE,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,KAAa,EACb,MAAc,EACd,QAAgB,EAChB,UAA0C;IAE1C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACtD,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,yCAAyC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;IACtH,CAAC,CAAC,CAAA;IACF,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,kEAAkE,CAAC,CAAA;IAC7H,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,IAAI,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,0CAA0C,IAAI,CAAC,IAAI,MAAM,QAAQ,GAAG,CAAC,CAAA;IAC/H,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,iDAAiD,CAAC,CAAA;IAC5G,CAAC;IACD,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;QACxB,QAAQ,EAAE,WAAW;QACrB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,+BAA+B;QAC5C,UAAU;QACV,aAAa,EAAE,OAAO;QACtB,KAAK,EAAE,IAAI,CAAC,IAAI;QAChB,KAAK;QACL,MAAM;KACP,CAAA;AACH,CAAC"}

package/lib/backend.js

@@ -0,0 +1,3 @@
+/** Provider-facing backend protocol kept below the public Computer Use Service. */
+export {};
+//# sourceMappingURL=backend.js.map

package/lib/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,mFAAmF"}