@bastani/atomic 0.9.28-alpha.3 → 0.9.28-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/dist/builtin/intercom/package.json +2 -2
  3. package/dist/builtin/mcp/package.json +1 -1
  4. package/dist/builtin/subagents/CHANGELOG.md +6 -0
  5. package/dist/builtin/subagents/package.json +3 -3
  6. package/dist/builtin/subagents/skills/agent-browser/SKILL.md +1 -1
  7. package/dist/builtin/subagents/skills/cua-driver/BROWSER.md +60 -39
  8. package/dist/builtin/subagents/skills/cua-driver/EMBEDDING.md +119 -36
  9. package/dist/builtin/subagents/skills/cua-driver/LINUX.md +225 -183
  10. package/dist/builtin/subagents/skills/cua-driver/MACOS.md +120 -89
  11. package/dist/builtin/subagents/skills/cua-driver/README.md +16 -7
  12. package/dist/builtin/subagents/skills/cua-driver/RECORDING.md +85 -115
  13. package/dist/builtin/subagents/skills/cua-driver/RUNTIME.md +113 -0
  14. package/dist/builtin/subagents/skills/cua-driver/SKILL.md +55 -1071
  15. package/dist/builtin/subagents/skills/cua-driver/VISUAL.md +125 -0
  16. package/dist/builtin/subagents/skills/cua-driver/WINDOWS.md +145 -185
  17. package/dist/builtin/subagents/skills/cua-driver/WORKFLOW.md +173 -0
  18. package/dist/builtin/web-access/package.json +2 -2
  19. package/dist/builtin/workflows/CHANGELOG.md +10 -0
  20. package/dist/builtin/workflows/README.md +1 -1
  21. package/dist/builtin/workflows/package.json +2 -2
  22. package/dist/builtin/workflows/skills/impeccable/SKILL.md +8 -2
  23. package/dist/builtin/workflows/skills/impeccable/reference/adapt.md +6 -0
  24. package/dist/builtin/workflows/skills/impeccable/reference/audit.md +2 -1
  25. package/dist/builtin/workflows/skills/impeccable/reference/component-review.md +63 -0
  26. package/dist/builtin/workflows/skills/impeccable/reference/degraded/asset-producer.md +5 -0
  27. package/dist/builtin/workflows/skills/impeccable/reference/degraded/finish-reviewer.md +1 -1
  28. package/dist/builtin/workflows/skills/impeccable/reference/generate.md +101 -0
  29. package/dist/builtin/workflows/skills/impeccable/reference/harden.md +9 -0
  30. package/dist/builtin/workflows/skills/impeccable/reference/hooks.md +3 -1
  31. package/dist/builtin/workflows/skills/impeccable/reference/mode-operate.md +21 -0
  32. package/dist/builtin/workflows/skills/impeccable/reference/mode-persuade.md +19 -0
  33. package/dist/builtin/workflows/skills/impeccable/reference/mode-read.md +21 -0
  34. package/dist/builtin/workflows/skills/impeccable/reference/new-work.md +19 -12
  35. package/dist/builtin/workflows/skills/impeccable/reference/region-map.md +26 -0
  36. package/dist/builtin/workflows/skills/impeccable/reference/routing.md +1 -1
  37. package/dist/builtin/workflows/skills/impeccable/reference/visualize.md +5 -5
  38. package/dist/builtin/workflows/skills/impeccable/scripts/VERSION +1 -1
  39. package/dist/builtin/workflows/skills/impeccable/scripts/command-metadata.json +4 -0
  40. package/dist/builtin/workflows/skills/impeccable/scripts/impeccable.cmd +2 -2
  41. package/dist/builtin/workflows/skills/impeccable/scripts/live-browser-session.js +5 -1
  42. package/dist/builtin/workflows/skills/impeccable/scripts/live-browser.js +524 -4
  43. package/dist/builtin/workflows/skills/prompt-engineer/SKILL.md +1 -0
  44. package/dist/builtin/workflows/skills/prompt-engineer/references/claude_haiku_5_5.md +81 -0
  45. package/dist/codemode-worker.js +2 -2
  46. package/dist/core/agent-session-compaction.d.ts +3 -3
  47. package/dist/core/agent-session-compaction.d.ts.map +1 -1
  48. package/dist/core/agent-session-compaction.js +5 -1
  49. package/dist/core/agent-session-compaction.js.map +1 -1
  50. package/dist/core/agent-session-events.d.ts.map +1 -1
  51. package/dist/core/agent-session-events.js +1 -0
  52. package/dist/core/agent-session-events.js.map +1 -1
  53. package/dist/core/agent-session-extension-bindings.d.ts.map +1 -1
  54. package/dist/core/agent-session-extension-bindings.js +4 -0
  55. package/dist/core/agent-session-extension-bindings.js.map +1 -1
  56. package/dist/core/agent-session-methods.d.ts +6 -1
  57. package/dist/core/agent-session-methods.d.ts.map +1 -1
  58. package/dist/core/agent-session-methods.js.map +1 -1
  59. package/dist/core/agent-session-prompt.d.ts.map +1 -1
  60. package/dist/core/agent-session-prompt.js +3 -2
  61. package/dist/core/agent-session-prompt.js.map +1 -1
  62. package/dist/core/agent-session-types.d.ts +1 -0
  63. package/dist/core/agent-session-types.d.ts.map +1 -1
  64. package/dist/core/agent-session-types.js.map +1 -1
  65. package/dist/core/agent-session.d.ts +1 -0
  66. package/dist/core/agent-session.d.ts.map +1 -1
  67. package/dist/core/agent-session.js.map +1 -1
  68. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  69. package/dist/core/export-html/tool-renderer.js +2 -0
  70. package/dist/core/export-html/tool-renderer.js.map +1 -1
  71. package/dist/core/extensions/agent-events.d.ts +2 -0
  72. package/dist/core/extensions/agent-events.d.ts.map +1 -1
  73. package/dist/core/extensions/agent-events.js.map +1 -1
  74. package/dist/core/extensions/context-types.d.ts +2 -0
  75. package/dist/core/extensions/context-types.d.ts.map +1 -1
  76. package/dist/core/extensions/context-types.js.map +1 -1
  77. package/dist/core/extensions/mcp-server-registry.d.ts +4 -1
  78. package/dist/core/extensions/mcp-server-registry.d.ts.map +1 -1
  79. package/dist/core/extensions/mcp-server-registry.js +7 -4
  80. package/dist/core/extensions/mcp-server-registry.js.map +1 -1
  81. package/dist/core/extensions/runner.d.ts +3 -0
  82. package/dist/core/extensions/runner.d.ts.map +1 -1
  83. package/dist/core/extensions/runner.js +19 -0
  84. package/dist/core/extensions/runner.js.map +1 -1
  85. package/dist/core/extensions/tool-types.d.ts +2 -0
  86. package/dist/core/extensions/tool-types.d.ts.map +1 -1
  87. package/dist/core/extensions/tool-types.js.map +1 -1
  88. package/dist/core/fast-model-variants.d.ts.map +1 -1
  89. package/dist/core/fast-model-variants.js +3 -2
  90. package/dist/core/fast-model-variants.js.map +1 -1
  91. package/dist/core/model-resolver-defaults.d.ts.map +1 -1
  92. package/dist/core/model-resolver-defaults.js +2 -0
  93. package/dist/core/model-resolver-defaults.js.map +1 -1
  94. package/dist/core/nested-tool-calls.d.ts +1 -0
  95. package/dist/core/nested-tool-calls.d.ts.map +1 -1
  96. package/dist/core/nested-tool-calls.js +1 -0
  97. package/dist/core/nested-tool-calls.js.map +1 -1
  98. package/dist/core/settings-types.js.map +1 -1
  99. package/dist/core/tools/bash.d.ts.map +1 -1
  100. package/dist/core/tools/bash.js +7 -3
  101. package/dist/core/tools/bash.js.map +1 -1
  102. package/dist/core/tools/edit.js +1 -1
  103. package/dist/core/tools/edit.js.map +1 -1
  104. package/dist/extensions/codemode/execute.d.ts.map +1 -1
  105. package/dist/extensions/codemode/execute.js +55 -7
  106. package/dist/extensions/codemode/execute.js.map +1 -1
  107. package/dist/extensions/codemode/index.d.ts.map +1 -1
  108. package/dist/extensions/codemode/index.js +7 -0
  109. package/dist/extensions/codemode/index.js.map +1 -1
  110. package/dist/extensions/codemode/tool.d.ts +2 -0
  111. package/dist/extensions/codemode/tool.d.ts.map +1 -1
  112. package/dist/extensions/codemode/tool.js +2 -0
  113. package/dist/extensions/codemode/tool.js.map +1 -1
  114. package/dist/index.d.ts +1 -1
  115. package/dist/index.d.ts.map +1 -1
  116. package/dist/index.js.map +1 -1
  117. package/dist/modes/interactive/components/bash-execution.d.ts +5 -1
  118. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  119. package/dist/modes/interactive/components/bash-execution.js +17 -14
  120. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  121. package/dist/modes/interactive/components/branch-summary-message.d.ts +2 -1
  122. package/dist/modes/interactive/components/branch-summary-message.d.ts.map +1 -1
  123. package/dist/modes/interactive/components/branch-summary-message.js +5 -2
  124. package/dist/modes/interactive/components/branch-summary-message.js.map +1 -1
  125. package/dist/modes/interactive/components/chat-message-renderer.d.ts +1 -0
  126. package/dist/modes/interactive/components/chat-message-renderer.d.ts.map +1 -1
  127. package/dist/modes/interactive/components/chat-message-renderer.js +19 -8
  128. package/dist/modes/interactive/components/chat-message-renderer.js.map +1 -1
  129. package/dist/modes/interactive/components/compaction-boundary-message.d.ts +3 -2
  130. package/dist/modes/interactive/components/compaction-boundary-message.d.ts.map +1 -1
  131. package/dist/modes/interactive/components/compaction-boundary-message.js +7 -4
  132. package/dist/modes/interactive/components/compaction-boundary-message.js.map +1 -1
  133. package/dist/modes/interactive/components/custom-entry.d.ts +3 -1
  134. package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -1
  135. package/dist/modes/interactive/components/custom-entry.js +8 -2
  136. package/dist/modes/interactive/components/custom-entry.js.map +1 -1
  137. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  138. package/dist/modes/interactive/components/custom-message.js +1 -0
  139. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  140. package/dist/modes/interactive/components/settings-selector-items.js +1 -1
  141. package/dist/modes/interactive/components/settings-selector-items.js.map +1 -1
  142. package/dist/modes/interactive/components/skill-invocation-message.d.ts +2 -1
  143. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  144. package/dist/modes/interactive/components/skill-invocation-message.js +5 -2
  145. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  146. package/dist/modes/interactive/components/tool-execution.d.ts +4 -0
  147. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  148. package/dist/modes/interactive/components/tool-execution.js +10 -0
  149. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  150. package/dist/modes/interactive/interactive-agent-events.js +3 -1
  151. package/dist/modes/interactive/interactive-agent-events.js.map +1 -1
  152. package/dist/modes/interactive/interactive-auth-login.js +6 -0
  153. package/dist/modes/interactive/interactive-auth-login.js.map +1 -1
  154. package/dist/modes/interactive/interactive-bash-compact.js +2 -2
  155. package/dist/modes/interactive/interactive-bash-compact.js.map +1 -1
  156. package/dist/modes/interactive/interactive-extension-dialogs.js +11 -2
  157. package/dist/modes/interactive/interactive-extension-dialogs.js.map +1 -1
  158. package/dist/modes/interactive/interactive-mode-base.d.ts +3 -0
  159. package/dist/modes/interactive/interactive-mode-base.d.ts.map +1 -1
  160. package/dist/modes/interactive/interactive-mode-base.js +6 -0
  161. package/dist/modes/interactive/interactive-mode-base.js.map +1 -1
  162. package/dist/modes/interactive/interactive-mode-surface.d.ts +2 -1
  163. package/dist/modes/interactive/interactive-mode-surface.d.ts.map +1 -1
  164. package/dist/modes/interactive/interactive-mode-surface.js.map +1 -1
  165. package/dist/modes/interactive/interactive-render-chat.js +7 -5
  166. package/dist/modes/interactive/interactive-render-chat.js.map +1 -1
  167. package/dist/modes/interactive/interactive-selectors.js +8 -1
  168. package/dist/modes/interactive/interactive-selectors.js.map +1 -1
  169. package/dist/modes/interactive/interactive-session-runtime.js +1 -0
  170. package/dist/modes/interactive/interactive-session-runtime.js.map +1 -1
  171. package/dist/modes/interactive/interactive-startup.js +1 -0
  172. package/dist/modes/interactive/interactive-startup.js.map +1 -1
  173. package/dist/modes/interactive/program-status-reporter.d.ts +24 -0
  174. package/dist/modes/interactive/program-status-reporter.d.ts.map +1 -0
  175. package/dist/modes/interactive/program-status-reporter.js +96 -0
  176. package/dist/modes/interactive/program-status-reporter.js.map +1 -0
  177. package/dist/modes/interactive-engine/engine-custom-ui.d.ts.map +1 -1
  178. package/dist/modes/interactive-engine/engine-custom-ui.js +1 -0
  179. package/dist/modes/interactive-engine/engine-custom-ui.js.map +1 -1
  180. package/dist/modes/interactive-engine/engine-render-service.d.ts.map +1 -1
  181. package/dist/modes/interactive-engine/engine-render-service.js +3 -1
  182. package/dist/modes/interactive-engine/engine-render-service.js.map +1 -1
  183. package/dist/modes/interactive-engine/protocol.d.ts +1 -0
  184. package/dist/modes/interactive-engine/protocol.d.ts.map +1 -1
  185. package/dist/modes/interactive-engine/protocol.js +1 -0
  186. package/dist/modes/interactive-engine/protocol.js.map +1 -1
  187. package/dist/modes/interactive-engine/remote-renderer.d.ts +3 -0
  188. package/dist/modes/interactive-engine/remote-renderer.d.ts.map +1 -1
  189. package/dist/modes/interactive-engine/remote-renderer.js +7 -0
  190. package/dist/modes/interactive-engine/remote-renderer.js.map +1 -1
  191. package/docs/codemode.md +10 -6
  192. package/docs/compaction.md +1 -1
  193. package/docs/computer-use.md +9 -9
  194. package/docs/custom-provider/streaming.md +4 -0
  195. package/docs/environment-variables.md +2 -0
  196. package/docs/extensions/api-reference.md +1 -1
  197. package/docs/extensions/authoring.md +2 -0
  198. package/docs/extensions/events.md +5 -1
  199. package/docs/getting-started/first-session.md +1 -1
  200. package/docs/json.md +6 -1
  201. package/docs/models/evals.md +34 -3
  202. package/docs/models.md +1 -1
  203. package/docs/providers.md +8 -0
  204. package/docs/sdk.md +7 -1
  205. package/docs/settings.md +1 -1
  206. package/docs/skills.md +1 -1
  207. package/docs/terminal-setup.md +14 -0
  208. package/docs/workflows/authoring.md +3 -3
  209. package/examples/extensions/sandbox/package-lock.json +3 -3
  210. package/npm-shrinkwrap.json +67 -67
  211. package/package.json +8 -8
package/CHANGELOG.md CHANGED
@@ -2,6 +2,29 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.28-alpha.4] - 2026-10-07
6
+
7
+ ### Added
8
+
9
+ - Added the API-key-only providers `openai-api` and `anthropic-api`, so you can keep a ChatGPT or Claude subscription login on `openai`/`anthropic` and still use an API key for the same models. See [Subscription and API key at the same time](docs/providers.md#subscription-and-api-key-at-the-same-time).
10
+ - `session.compact()` and extension `ctx.compact()` accept `compactionModel` to pick the compaction model for one run without changing the `compactionModel` setting. An unknown ID rejects before the active run is interrupted. See [Compaction and tree navigation](docs/sdk.md#compaction-and-tree-navigation).
11
+ - Added terminal program-status reporting through OSC 7501 for runs, compaction, extension prompts, and sign-in. Compatible terminals can show when Atomic is working, waiting for input, done, or has failed.
12
+ - Added recorded response and tool execution durations. Bash tool results show their execution time, including after a session is resumed.
13
+
14
+ ### Changed
15
+
16
+ - Moved the GPT-6 Luna classifier from `openai/gpt-6-luna` to its own API-key-only provider, `openai-decisions/gpt-6-luna`, named "GPT-6 Luna Decisions". `openai/gpt-6-luna` now always means the chat model, and the classifier stays available while `openai` uses ChatGPT sign-in. Update `routerModel`, `compactionModel`, `structured_output` and codemode references that meant the classifier. See [Classifier models](docs/models.md#use-classifier-models).
17
+ - Codemode labels returned output items with numbered headers and places console output in a separate trailing block.
18
+ - Codemode now says that `ALL_TOOLS`, `searchTools()`, and `describeTool()` list only script-callable tools, and `searchTools()`/`describeTool()` answer an exact model-only tool name such as `subagent` with a hint to call it directly instead of returning nothing ([#3510](https://github.com/bastani-inc/atomic/issues/3510))
19
+
20
+ ### Fixed
21
+
22
+ - Updated the sandbox example extension's lockfile to `shell-quote` 1.12.0, resolving the `quote()` command-injection advisory [GHSA-pqg4-j6r4-53mv](https://github.com/advisories/GHSA-pqg4-j6r4-53mv) in its `@anthropic-ai/sandbox-runtime` dependency.
23
+ - Fixed hyperlinks being disabled in Herdr panes, while keeping image protocols off even when outer-terminal environment variables are inherited ([#10573](https://github.com/earendil-works/pi/issues/10573)).
24
+ - Fixed `outputPad` applying inconsistently to tool results, shell output, summaries, skill invocations, and custom transcript entries. Changing it in `/settings` now updates existing blocks without rebuilding the transcript.
25
+ - Fixed fullscreen text selections surviving a transcript rebuild and selecting unrelated replacement text.
26
+ - Fixed extension-registered MCP servers silently remaining unused when an SDK host has no MCP contribution consumer. Atomic now reports each unhandled server once.
27
+
5
28
  ## [0.9.28-alpha.3] - 2026-10-07
6
29
 
7
30
  ### Added
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/intercom",
3
- "version": "0.9.28-alpha.3",
3
+ "version": "0.9.28-alpha.4",
4
4
  "private": true,
5
5
  "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
6
6
  "contributors": [
@@ -44,7 +44,7 @@
44
44
  },
45
45
  "peerDependencies": {
46
46
  "@bastani/atomic": "*",
47
- "@earendil-works/pi-tui": "^1.0.4",
47
+ "@earendil-works/pi-tui": "^1.1.0",
48
48
  "typebox": "*"
49
49
  },
50
50
  "peerDependenciesMeta": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/mcp",
3
- "version": "0.9.28-alpha.3",
3
+ "version": "0.9.28-alpha.4",
4
4
  "private": true,
5
5
  "description": "Atomic's pi-compatible MCP integration for server connections, OAuth, tools, resources, and terminal management.",
6
6
  "contributors": [
@@ -2,6 +2,12 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.28-alpha.4] - 2026-10-07
6
+
7
+ ### Changed
8
+
9
+ - Updated the bundled Cua Driver skill to upstream `cua-driver-rs-v0.34.0`, with focused runtime, workflow, and visual guides covering authorization, exact targets, observation, and outcome verification.
10
+
5
11
  ## [0.9.27] - 2026-10-05
6
12
 
7
13
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/subagents",
3
- "version": "0.9.28-alpha.3",
3
+ "version": "0.9.28-alpha.4",
4
4
  "private": true,
5
5
  "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
6
6
  "contributors": [
@@ -35,8 +35,8 @@
35
35
  "peerDependencies": {
36
36
  "@bastani/atomic": "*",
37
37
  "@bastani/pi-ai": "*",
38
- "@earendil-works/pi-agent-core": "^1.0.4",
39
- "@earendil-works/pi-tui": "^1.0.4",
38
+ "@earendil-works/pi-agent-core": "^1.1.0",
39
+ "@earendil-works/pi-tui": "^1.1.0",
40
40
  "typebox": "*"
41
41
  },
42
42
  "peerDependenciesMeta": {
@@ -4,7 +4,7 @@ description: Browser automation CLI for AI agents. Use when the user needs to in
4
4
  hidden: true
5
5
  metadata:
6
6
  github-path: skills/agent-browser
7
- github-ref: refs/tags/v0.38.1
7
+ github-ref: refs/tags/v0.38.2
8
8
  github-repo: https://github.com/vercel-labs/agent-browser
9
9
  github-tree-sha: 82def67855a0d2aad7794207951820fa5422fdb0
10
10
  name: agent-browser
@@ -3,10 +3,14 @@
3
3
  Use this guide for page content in Chromium-family browsers and Electron.
4
4
  Browser chrome, permission prompts, downloads, file pickers, and unsupported
5
5
  engines remain native windows: inspect and operate them with
6
- `get_window_state` and the normal AX/PX action ladder in `SKILL.md`.
6
+ `get_window_state` and the native action loop in [WORKFLOW.md](WORKFLOW.md).
7
7
 
8
8
  ## Choose the page-aware route first
9
9
 
10
+ Use this route only when the user's requested interaction method permits
11
+ page-aware automation. GUI-only/native-input tasks stay on the native window
12
+ or authorized desktop loop, even for Electron applications.
13
+
10
14
  For supported page content, prefer the typed browser tools over the legacy
11
15
  `page` tool, accessibility guesses, omnibox shortcuts, or raw pixels. The
12
16
  typed route binds an exact native `(pid, window_id)` to a browser target and
@@ -32,14 +36,15 @@ same value on every call that accepts it. Passing it once is not sticky; a later
32
36
  omitted value uses the transport's implicit session. One long-lived MCP or SDK
33
37
  transport may omit `session` for one-off or deliberately unlabeled work; its
34
38
  first admitted call creates one implicit session and later unnamed calls reuse
35
- it. Direct one-shot CLI calls use disposable transports. Never substitute a raw
39
+ it. Use one persistent MCP connection for preparation, binding, actions, and
40
+ cleanup; see [RUNTIME.md](RUNTIME.md). Anonymous one-shot CLI calls use disposable transports. Never substitute a raw
36
41
  CDP target id, tab ordinal, URL match, or remembered ref for a capability
37
42
  returned by `get_browser_state`.
38
43
 
39
44
  ### Copy page content to the system clipboard
40
45
 
41
- If the requested outcome is exact page content on the system clipboard—not a
42
- literal text-selection gesture—read the content from a fresh semantic browser
46
+ If the requested outcome is exact page content on the system clipboard (not a
47
+ literal text-selection gesture), read the content from a fresh semantic browser
43
48
  snapshot, call `clipboard_write` with the exact observed value, and verify it
44
49
  with `clipboard_read`. This path is background-safe and does not require a
45
50
  clickable ref: passive headings and text nodes are evidence sources, not
@@ -48,7 +53,7 @@ controls that must be clicked before their value can be copied.
48
53
  Fall back to visual text selection and the platform copy hotkey only when the
49
54
  user explicitly requires that gesture or clipboard tools are unavailable.
50
55
  That fallback is native input, not a typed page mutation, and may require the
51
- foreground escalation rules in `SKILL.md`.
56
+ foreground escalation rules in [RUNTIME.md](RUNTIME.md#foreground-boundary).
52
57
 
53
58
  ### Browser recording feedback
54
59
 
@@ -74,13 +79,17 @@ recording overlay to explain navigation in a public demo.
74
79
 
75
80
  ## 1. Select an exact native window
76
81
 
82
+ The examples below show tool names and JSON arguments for calls on the same
83
+ persistent MCP connection. They are not separate shell commands. Replace all
84
+ sample PIDs, windows, target/tab IDs, and refs with returned values.
85
+
77
86
  Start or discover the app with the native tools and select one returned
78
87
  `window_id`:
79
88
 
80
- ```bash
81
- cua-driver start_session '{"session":"browser-run-1"}'
82
- cua-driver list_windows '{"pid":4242}'
83
- cua-driver get_browser_state \
89
+ ```text
90
+ start_session '{"session":"browser-run-1"}'
91
+ list_windows '{"pid":4242}'
92
+ get_browser_state
84
93
  '{"pid":4242,"window_id":991,"session":"browser-run-1"}'
85
94
  ```
86
95
 
@@ -108,8 +117,8 @@ a DevTools listener merely because the listener belongs to that process.
108
117
  Prefer an isolated profile when the task does not need the user's existing
109
118
  cookies or login state:
110
119
 
111
- ```bash
112
- cua-driver browser_prepare \
120
+ ```text
121
+ browser_prepare
113
122
  '{"session":"browser-run-1","allow_launch":true,
114
123
  "profile":{"mode":"isolated_new"}}'
115
124
  ```
@@ -126,6 +135,14 @@ order: Google Chrome, then Microsoft Edge. On Linux it accepts exact
126
135
  root-owned, non-group/world-writable package payloads in this order: Google
127
136
  Chrome, Chromium, then Microsoft Edge. User application directories, `PATH`
128
137
  entries, redirected paths, and unsigned or mismatched products fail closed.
138
+ On Windows, the installation must also be unmodifiable by the token that runs
139
+ the browser. A non-elevated Driver runs the browser with its own token. An
140
+ elevated Driver, including the built-in Administrator and administrators with
141
+ UAC off, runs it with a derived standard-user token (administrator rights
142
+ removed, Medium integrity) and proves the installation protected from that
143
+ token. If that token cannot be derived and verified, or can still modify the
144
+ installation, the refusal says so; the browser is not missing or unsigned, and
145
+ Driver never falls back to an elevated browser.
129
146
  Supply a Chromium-family browser pid when the isolated launch must use that
130
147
  process's exact executable, including Chromium on macOS or Windows. The pid
131
148
  remains required for existing-profile attachment.
@@ -151,8 +168,12 @@ satisfy the task.
151
168
  ```bash
152
169
  # Start the runtime with the trusted standard-mode launch grant.
153
170
  cua-driver mcp --grant existing-profile
171
+ ```
154
172
 
155
- cua-driver browser_prepare \
173
+ Then call on that connection:
174
+
175
+ ```text
176
+ browser_prepare
156
177
  '{"pid":4242,"window_id":991,"session":"browser-run-1",
157
178
  "strategy":{"kind":"existing_profile"}}'
158
179
  ```
@@ -228,8 +249,8 @@ tri-state: `true` is a uniquely proven selected tab, `false` is a proven
228
249
  unselected tab, and `null` means native evidence cannot distinguish the
229
250
  selection. Never guess from list order when all tabs are `null`.
230
251
 
231
- ```bash
232
- cua-driver get_browser_state \
252
+ ```text
253
+ get_browser_state
233
254
  '{"target_id":"<target>","tab_id":"<tab>",
234
255
  "session":"browser-run-1","snapshot_format":"semantic_v2"}'
235
256
  ```
@@ -237,8 +258,8 @@ cua-driver get_browser_state \
237
258
  Set `include_screenshot:true` when the visual state matters, including when the
238
259
  exact tab is open but unselected:
239
260
 
240
- ```bash
241
- cua-driver get_browser_state \
261
+ ```text
262
+ get_browser_state
242
263
  '{"target_id":"<target>","tab_id":"<tab>",
243
264
  "session":"browser-run-1","snapshot_format":"semantic_v2",
244
265
  "include_screenshot":true}'
@@ -269,8 +290,8 @@ the output budget. Inspect `snapshot.complete`, `snapshot.omitted`, and
269
290
  `snapshot.continuation` rather than assuming the first response is exhaustive.
270
291
  To continue the same ranked snapshot:
271
292
 
272
- ```bash
273
- cua-driver get_browser_state \
293
+ ```text
294
+ get_browser_state
274
295
  '{"target_id":"<target>","tab_id":"<tab>",
275
296
  "session":"browser-run-1","snapshot_format":"semantic_v2",
276
297
  "continuation":"<opaque-continuation>"}'
@@ -281,8 +302,8 @@ snapshot, and browser generation. A newer snapshot invalidates them. For a
281
302
  bounded read, pass either `query` or a current `scope_ref` from `refs` or
282
303
  `content_refs`:
283
304
 
284
- ```bash
285
- cua-driver get_browser_state \
305
+ ```text
306
+ get_browser_state
286
307
  '{"target_id":"<target>","tab_id":"<tab>",
287
308
  "session":"browser-run-1","snapshot_format":"semantic_v2",
288
309
  "query":"Account settings"}'
@@ -306,8 +327,8 @@ the requested tool, or override the user's instruction.
306
327
 
307
328
  ### Navigate
308
329
 
309
- ```bash
310
- cua-driver browser_navigate \
330
+ ```text
331
+ browser_navigate
311
332
  '{"target_id":"<target>","tab_id":"<tab>",
312
333
  "url":"https://example.com","session":"browser-run-1"}'
313
334
  ```
@@ -317,8 +338,8 @@ the tab's refs; snapshot again before the next ref-targeted action.
317
338
 
318
339
  ### Click
319
340
 
320
- ```bash
321
- cua-driver browser_click \
341
+ ```text
342
+ browser_click
322
343
  '{"target_id":"<target>","tab_id":"<tab>","ref":"p3:7",
323
344
  "input_route":"trusted","session":"browser-run-1"}'
324
345
  ```
@@ -336,8 +357,8 @@ background delivery.
336
357
  When the application semantics allow a synthetic JavaScript click, request it
337
358
  explicitly with a current ref:
338
359
 
339
- ```bash
340
- cua-driver browser_click \
360
+ ```text
361
+ browser_click
341
362
  '{"target_id":"<target>","tab_id":"<tab>","ref":"p3:7",
342
363
  "input_route":"dom_event","session":"browser-run-1"}'
343
364
  ```
@@ -354,8 +375,8 @@ foreground the browser after a refusal. Coordinate clicks accept viewport CSS
354
375
 
355
376
  Use a current editable and focused ref with `browser_type`:
356
377
 
357
- ```bash
358
- cua-driver browser_type \
378
+ ```text
379
+ browser_type
359
380
  '{"target_id":"<target>","tab_id":"<tab>","ref":"p4:2",
360
381
  "text":"hello","mode":"insert_text","session":"browser-run-1"}'
361
382
  ```
@@ -388,8 +409,8 @@ requires `destination_ref` in the same proven frame. Coordinate origins and
388
409
  destinations are available only where the trusted route can preserve the
389
410
  requested posture.
390
411
 
391
- ```bash
392
- cua-driver browser_pointer \
412
+ ```text
413
+ browser_pointer
393
414
  '{"target_id":"<target>","tab_id":"<tab>","ref":"p5:2",
394
415
  "action":"scroll","input_route":"dom_event","delta_y":240,
395
416
  "session":"browser-run-1"}'
@@ -455,15 +476,15 @@ capabilities, or existing-profile consent.
455
476
 
456
477
  ## Support boundaries
457
478
 
458
- | Surface | Typed state and mutation | Important boundary |
459
- | --- | --- | --- |
460
- | Chrome / Edge on Windows | Exact binding, refs, navigation, typing, trusted or explicit DOM click | Must run in an interactive user session, not Session 0 |
461
- | Chrome / Edge on macOS | Exact binding, refs, navigation, typing, explicit DOM click | Trusted standalone click refuses to preserve background posture |
462
- | Chrome / Chromium on Linux X11 | Exact binding, refs, navigation, typing, explicit DOM click | Trusted standalone click refuses to preserve background posture |
463
- | Chromium on validated Wayland setups | Exact binding only when compositor identity is provable | Generic/ambiguous compositor identity refuses mutation |
464
- | Electron | Exact single-page routes where endpoint and host relationship are proven | Do not infer support for arbitrary embedded webviews |
465
- | Safari / Firefox | Native window state only | Typed page mutation is not supported yet |
466
- | WebView2 / Tauri / other embedded webviews | Native AX/PX fallback unless an exact route is reported | Host/renderer correlation may refuse |
479
+ | Surface | Typed state and mutation | Important boundary |
480
+ | ------------------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------- |
481
+ | Chrome / Edge on Windows | Exact binding, refs, navigation, typing, trusted or explicit DOM click | Must run in an interactive user session, not Session 0 |
482
+ | Chrome / Edge on macOS | Exact binding, refs, navigation, typing, explicit DOM click | Trusted standalone click refuses to preserve background posture |
483
+ | Chrome / Chromium on Linux X11 | Exact binding, refs, navigation, typing, explicit DOM click | Trusted standalone click refuses to preserve background posture |
484
+ | Chromium on validated Wayland setups | Exact binding only when compositor identity is provable | Generic/ambiguous compositor identity refuses mutation |
485
+ | Electron | Exact single-page routes where endpoint and host relationship are proven | Do not infer support for arbitrary embedded webviews |
486
+ | Safari / Firefox | Native window state only | Typed page mutation is not supported yet |
487
+ | WebView2 / Tauri / other embedded webviews | Native AX/PX fallback unless an exact route is reported | Host/renderer correlation may refuse |
467
488
 
468
489
  Product classification alone is not a capability claim. Trust the structured
469
490
  result from the current host, process, window, session, and tab.