@bingjiang0611/rotom 0.1.0-alpha.0

package/extensions/third-party/index.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import computerUse from "./node_modules/@injaneity/pi-computer-use/extensions/computer-use.ts";
+import askUserQuestion from "./node_modules/@juicesharp/rpiv-ask-user-question/index.ts";
+import goal from "./node_modules/@narumitw/pi-goal/src/index.ts";
+import subagents from "./node_modules/pi-subagents/index.ts";
+import { ASK_AUTO_CONTINUATION_MESSAGE, ASK_CONTINUATION_GUIDELINE, ASK_OPTION_CONTINUATION_DESCRIPTION, createAskContinuationController, selectedOptionsRequireContinuation, stripAskContinuationMetadata } from "./ask-continuation.ts";
+import { computerUseRecoveryApi } from "./computer-use-recovery.ts";
+import { registerDeferredTools } from "./deferred-tools.ts";
+import { subagentPolicyApi } from "./subagent-policy.ts";
+
+function sequentialAskCompatApi(pi: ExtensionAPI, askContinuation: ReturnType<typeof createAskContinuationController>): ExtensionAPI {
+	return new Proxy(pi, {
+		get(target, property, receiver) {
+			if (property === "registerTool") return (definition: Parameters<ExtensionAPI["registerTool"]>[0]) => {
+				const sequential = { ...definition, executionMode: "sequential" as const };
+				if (definition.name !== "ask_user_question") return target.registerTool(sequential);
+				const execute = definition.execute.bind(definition);
+				const baseParameters = definition.parameters as any;
+				const questionsSchema = baseParameters.properties?.questions ?? {};
+				const questionSchema = questionsSchema.items ?? {};
+				const optionsSchema = questionSchema.properties?.options ?? {};
+				const optionSchema = optionsSchema.items ?? {};
+				const parameters = {
+					...baseParameters,
+					properties: {
+						...(baseParameters.properties ?? {}),
+						questions: {
+							...questionsSchema,
+							items: {
+								...questionSchema,
+								properties: {
+									...(questionSchema.properties ?? {}),
+									options: { ...optionsSchema, items: { ...optionSchema, properties: { ...(optionSchema.properties ?? {}), continueExecution: { type: "boolean", description: ASK_OPTION_CONTINUATION_DESCRIPTION } } } },
+								},
+							},
+						},
+					},
+				};
+				return target.registerTool({
+					...sequential,
+					parameters,
+					promptGuidelines: [...(definition.promptGuidelines ?? []), ASK_CONTINUATION_GUIDELINE],
+					async execute(...args: Parameters<typeof definition.execute>) {
+						const rawParams = args[1];
+						const generation = askContinuation.beginAsk();
+						const forwarded = [...args] as unknown[]; forwarded[1] = stripAskContinuationMetadata(rawParams);
+						const result = await execute(...forwarded as Parameters<typeof definition.execute>);
+						return askContinuation.afterAskResult(result, selectedOptionsRequireContinuation(result, rawParams), generation, args[2]);
+					},
+				});
+			};
+			if (property === "on") return (event: Parameters<ExtensionAPI["on"]>[0], handler: (...args: any[]) => unknown) => target.on(event as any, ((...args: any[]) => {
+				const ctx = args[1];
+				if (!ctx || ctx.hasUI) return handler(...args);
+				const ui = new Proxy(ctx.ui, { get(uiTarget, uiProperty, uiReceiver) { if (uiProperty === "theme") return { fg: (_color: string, text: string) => text }; const uiValue = Reflect.get(uiTarget, uiProperty, uiReceiver); return typeof uiValue === "function" ? uiValue.bind(uiTarget) : uiValue; } });
+				return handler(args[0], new Proxy(ctx, { get(ctxTarget, ctxProperty, ctxReceiver) { if (ctxProperty === "ui") return ui; const ctxValue = Reflect.get(ctxTarget, ctxProperty, ctxReceiver); return typeof ctxValue === "function" ? ctxValue.bind(ctxTarget) : ctxValue; } }));
+			}) as any);
+			const value = Reflect.get(target, property, receiver);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
+/**
+ * One explicit composition root for the third-party runtime selected by the
+ * product. Package code remains unmodified and version-pinned by the launcher.
+ */
+export default function thirdPartyRuntime(pi: ExtensionAPI): void {
+	computerUse(computerUseRecoveryApi(pi));
+	subagents(subagentPolicyApi(pi));
+	goal(pi);
+	const askContinuation = createAskContinuationController();
+	const sequentialAskCompat = sequentialAskCompatApi(pi, askContinuation);
+	askUserQuestion(sequentialAskCompat);
+	registerDeferredTools(pi);
+	pi.on("tool_call", (event) => askContinuation.onToolCall(event.toolName));
+	pi.on("session_start", () => askContinuation.reset());
+	pi.on("session_shutdown", () => askContinuation.reset());
+	pi.on("session_tree", () => askContinuation.reset());
+	pi.on("agent_end", (event, ctx) => {
+		if (!askContinuation.onAgentEnd(event.messages, ctx.signal)) return;
+		pi.sendMessage({ customType: "ask-user-continuation", content: ASK_AUTO_CONTINUATION_MESSAGE, display: false }, { deliverAs: "followUp", triggerTurn: true });
+	});
+}

package/extensions/third-party/node_modules/.package-lock.json

@@ -0,0 +1,175 @@
+{
+  "name": "pi-agent-third-party-runtime",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "node_modules/@injaneity/pi-computer-use": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/@injaneity/pi-computer-use/-/pi-computer-use-0.5.0.tgz",
+      "integrity": "sha512-5uJ6TWnSkWBwRRGWGF1nMvyARlkJEDZsRkMmzTBOGQUNjulWMDztAv99OTdtWIGbSncRpYQQ15VGeFC/vq8hJQ==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.6.0"
+      },
+      "peerDependencies": {
+        "@earendil-works/pi-ai": "*",
+        "@earendil-works/pi-coding-agent": "*",
+        "typebox": "*"
+      }
+    },
+    "node_modules/@juicesharp/rpiv-ask-user-question": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@juicesharp/rpiv-ask-user-question/-/rpiv-ask-user-question-2.6.2.tgz",
+      "integrity": "sha512-DS9yZHcaPr+/nf0x2CCfiXBod/1aWjGyakGM3lZAObuGDhYI0nFRE5gxTcCOfQug6JtJXjt1GlzyX8Pljefdzg==",
+      "license": "MIT",
+      "dependencies": {
+        "@juicesharp/rpiv-config": "^2.6.2",
+        "typebox": "^1.1.24"
+      },
+      "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*",
+        "@juicesharp/rpiv-i18n": "*"
+      },
+      "peerDependenciesMeta": {
+        "@juicesharp/rpiv-i18n": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@juicesharp/rpiv-config": {
+      "version": "2.6.4",
+      "resolved": "https://registry.npmjs.org/@juicesharp/rpiv-config/-/rpiv-config-2.6.4.tgz",
+      "integrity": "sha512-nbY5W3kV7D0pVTbWKyi3C74H8QPTmJi4nNo5DelqR4rPOG26i02hqqAH+A3guTP86f/bbwFNUgJ3QQgLZnDoPg==",
+      "license": "MIT",
+      "dependencies": {
+        "typebox": "^1.1.24"
+      }
+    },
+    "node_modules/@narumitw/pi-goal": {
+      "version": "0.52.1",
+      "resolved": "https://registry.npmjs.org/@narumitw/pi-goal/-/pi-goal-0.52.1.tgz",
+      "integrity": "sha512-L4JDDn2JqRND9IWywJPr9XhkixO38yeL4CCCEAJoqG4++YpaKdywY32w71+rvD4UUOqCSRHwCyXd3CTEf1jw9w==",
+      "license": "MIT",
+      "dependencies": {
+        "@narumitw/pi-tui-kit": "^0.56.0"
+      },
+      "peerDependencies": {
+        "@earendil-works/pi-ai": "*",
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*",
+        "typebox": "*"
+      }
+    },
+    "node_modules/@narumitw/pi-tui-kit": {
+      "version": "0.56.1",
+      "resolved": "https://registry.npmjs.org/@narumitw/pi-tui-kit/-/pi-tui-kit-0.56.1.tgz",
+      "integrity": "sha512-FEviLa6FeiIQhYUhG2jmJ6DaXvI5xZ6Qxs+VUxqDJWtMx9MJpXm3/QAKGheuk25pmp4eW7Xmo3FDUAviuk7EKA==",
+      "license": "MIT",
+      "dependencies": {
+        "grok-mermaid": "0.2.3",
+        "highlight.js": "11.12.0"
+      },
+      "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*"
+      }
+    },
+    "node_modules/acorn": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz",
+      "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==",
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/grok-mermaid": {
+      "version": "0.2.3",
+      "resolved": "https://registry.npmjs.org/grok-mermaid/-/grok-mermaid-0.2.3.tgz",
+      "integrity": "sha512-/4KopAbsjvuRP9MdPtlDjOHUmUVEohOX73JNcsWpzAtFxh+bq5+Dhb6gzvRieLDwIPQIR3/vy8V1NNTuz4Zsmg==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/highlight.js": {
+      "version": "11.12.0",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.12.0.tgz",
+      "integrity": "sha512-nbfWpyRMcMrPMmDwJB+dhX/eiaPKtc2RB+0QZskqJ3WjRA/FDS0e9hZrx8EC/lbEv8gXy98FcDbNa/dspAaJMg==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/jiti": {
+      "version": "2.7.0",
+      "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz",
+      "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==",
+      "license": "MIT",
+      "bin": {
+        "jiti": "lib/jiti-cli.mjs"
+      }
+    },
+    "node_modules/pi-subagents": {
+      "version": "0.52.1-dev-agent-followthrough.2",
+      "resolved": "file:vendor/pi-subagents-0.52.1-dev-agent-followthrough.2.tgz",
+      "integrity": "sha512-HaLHkYtSIbiwnq6CkCAzPwVRDLswRw/WvbkrlR9/UM9TPYJFTQqsAtHgWsFi+syOI73fQ0ZZXV+WdphDmHqBIg==",
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "8.18.0",
+        "jiti": "2.7.0",
+        "typebox": "1.1.38",
+        "yaml": "2.8.3"
+      },
+      "bin": {
+        "pi-subagents": "install.mjs"
+      },
+      "peerDependencies": {
+        "@earendil-works/pi-agent-core": "*",
+        "@earendil-works/pi-ai": ">=0.80.0",
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*"
+      },
+      "peerDependenciesMeta": {
+        "@earendil-works/pi-agent-core": {
+          "optional": true
+        },
+        "@earendil-works/pi-ai": {
+          "optional": true
+        },
+        "@earendil-works/pi-coding-agent": {
+          "optional": true
+        },
+        "@earendil-works/pi-tui": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/typebox": {
+      "version": "1.1.38",
+      "resolved": "https://registry.npmjs.org/typebox/-/typebox-1.1.38.tgz",
+      "integrity": "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA==",
+      "license": "MIT"
+    },
+    "node_modules/yaml": {
+      "version": "2.8.3",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
+      "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}

package/extensions/third-party/node_modules/@injaneity/pi-computer-use/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zane Chee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/third-party/node_modules/@injaneity/pi-computer-use/README.md

@@ -0,0 +1,92 @@
+# pi-computer-use
+
+<p align="center">
+  <img src="./assets/logo/logo3.png" width="50%" alt="pi-computer-use">
+</p>
+
+`pi-computer-use` lets AI agents use desktop apps on macOS, Windows, and Linux.
+
+The macOS helper requires macOS 14 or newer.
+
+An agent can look at an app window, understand the buttons and text inside it, and perform actions like clicking, typing, scrolling, and waiting for something to change. This is useful when the agent needs to work with a normal desktop app instead of an API, a terminal command, or a file.
+
+New to computer use? Start with: [Wait, what exactly is Computer Use?](https://zanechee.dev/what-exactly-is-computer-use/)
+
+## What this package does
+
+This is a Pi extension. After installation, Pi agents get tools for:
+
+- finding open apps and windows
+- observing what is visible in a window
+- searching the visible interface for text, buttons, and controls
+- inspecting parts of the interface in more detail
+- clicking, typing, scrolling, and pressing UI controls
+- waiting for UI changes
+
+In short: it gives an agent a controlled way to operate desktop software.
+
+## What this package is not
+
+`pi-computer-use` is not a replacement for app APIs or MCP servers. If an app has a reliable direct integration, use that first.
+
+Computer use is most helpful when the only available interface is the app on screen.
+
+## Install
+
+```bash
+pi install npm:@injaneity/pi-computer-use
+```
+
+Start Pi and complete the platform setup flow.
+
+On macOS, the helper is installed per user by default. Grant permissions to:
+
+```text
+~/Applications/pi-computer-use.app
+```
+
+Existing writable system-wide installs remain at `/Applications/pi-computer-use.app`.
+
+Required macOS permissions:
+
+- Accessibility
+- Screen Recording, shown as Screen and System Audio Recording on newer macOS versions
+
+The macOS setup flow registers the helper first, so it should already appear in both Settings panes. Enable the toggles and choose Recheck.
+
+On Windows, use an interactive desktop session. Windows support uses the platform accessibility APIs and does not use the macOS helper app or TCC permission flow.
+
+On Linux, run Pi inside the target user's graphical session with a working AT-SPI2 accessibility bus. AT-SPI semantic operations remain background-first. X11 additionally supports EWMH window metadata/focus, window capture, and policy-gated XTEST physical input; strict headless/background policies never use focus or XTEST. Native Wayland remains semantic-only; diagnostics reads portal capability properties without creating a session, and interactive portal use is disabled. See [Linux support](./docs/linux.md) for the exact capability matrix and portal status.
+
+Use `/computer-use` inside Pi to show the active configuration and where it came from.
+
+## Main tools
+
+- `find_roots`
+- `observe_ui`
+- `search_ui`
+- `expand_ui`
+- `inspect_ui`
+- `act_ui`
+- `read_text`
+- `wait_for`
+
+See [docs/usage.md](./docs/usage.md) for the full tool reference.
+
+## Documentation
+
+- [Usage](./docs/usage.md)
+- [Architecture](./docs/architecture.md)
+- [Configuration](./docs/configuration.md)
+- [Development](./docs/development.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Linux support](./docs/linux.md)
+- [Contributing](./CONTRIBUTING.md)
+
+## Development status
+
+The architecture is centered on immutable, state-scoped observations. Desktop surfaces and CDP pages form one multi-root forest; progressive outline queries remain cached, while live work is ordered per physical resource so independent roots can run in parallel. `act_ui` accepts one or more intent steps, preserves focus across dependent input, verifies delivery, recovers safely, stores one complete successor state, and returns a compact diff when identity confidence allows. Older direct tools such as `screenshot`, `click`, `set_text`, and `computer_actions` are no longer part of the public extension surface.
+
+## License
+
+MIT

package/extensions/third-party/node_modules/@injaneity/pi-computer-use/docs/architecture.md

@@ -0,0 +1,158 @@
+# Architecture
+
+`pi-computer-use` exposes one state-scoped interface for desktop and browser UI:
+
+```text
+find roots → observe one root → search/expand/inspect its state → act from that state
+```
+
+The agent still sees a multi-root forest. `find_roots` returns stable root refs (`@rN`) for desktop windows, transient surfaces, and CDP pages. Observing one root produces an immutable element tree whose refs (`@eN`) belong only to that returned `stateId`. Progressive disclosure is unchanged: the first outline is folded, while `search_ui`, `expand_ui`, and `inspect_ui` query the full stored tree.
+
+## Runtime model
+
+Every live request follows one path:
+
+```text
+load saved state → prepare actions → run → observe → save → show changes
+```
+
+The implementation keeps that ownership explicit:
+
+| Module | Owns |
+|---|---|
+| `state.ts` | Saved UI states, request-local state, restoration, and serialization |
+| `actions.ts` | Validation, normalization, target resolution, dependent focus, and safe retry eligibility |
+| `bridge.ts` | Tool coordination and resource scheduling |
+| `view.ts` | Stable public refs and full-versus-changes rendering |
+| `outline.ts` | Parsing and querying complete UI trees |
+| `platform/*` | OS observation, input mechanics, and native protocol translation |
+
+```mermaid
+flowchart TB
+    A["Agent tool calls<br/>Pi may issue them concurrently"] --> C["State-scoped contract<br/>root @r / stateId / element @e"]
+    C --> Q{"Cached or live?"}
+    Q -->|"cached search / expand / inspect"| S["Bounded immutable state store"]
+    Q -->|"observe / act / live read"| R["Resource scheduler"]
+    R --> D1["desktop-pid:123 lane"]
+    R --> D2["desktop-pid:456 lane"]
+    R --> B1["cdp:page-A lane"]
+    D1 --> P["Platform-neutral backend"]
+    D2 --> P
+    B1 --> Cdp["Target-keyed CDP connections"]
+    P --> M["macOS AX/capture helper"]
+    P --> W["Windows UIA/input helper"]
+    P --> L["Linux AT-SPI2 helper"]
+    M --> O["OS UI resources"]
+    W --> O
+    L --> O
+    Cdp --> O
+```
+
+There is no session-wide current UI. Every call hydrates request-local state from `stateId`; unrelated calls cannot overwrite one another. Stored observations are immutable and bounded, so old refs either resolve to their exact observation or fail clearly after eviction.
+
+The scheduler serializes live operations only when they address the same physical resource. Different desktop processes and different CDP targets can run concurrently. Cached outline queries bypass it entirely. Every resource has a monotonically increasing epoch. A mutating call must present the epoch captured by its state; if another write won the race, the stale call is rejected before dispatch.
+
+Desktop scheduling is conservatively keyed by process rather than window because accessibility focus, menus, and physical input can cross window boundaries inside an app. CDP scheduling is keyed by page target. Global physical input remains mutex-protected in the native helper; semantic AX/UIA work can overlap where the platform permits it.
+
+## Observation and progressive disclosure
+
+`observe_ui` asks the selected backend for one look. A desktop look combines root identity, accessibility structure, optional image evidence, OCR boxes when required, and capture metadata. A browser look converts the CDP accessibility tree into the same serialized outline shape.
+
+The bridge stores the complete observation and returns a folded rendering. The state owns its refs:
+
+```text
+@r3 browser page
+  state A (epoch 4)
+    @e1 document
+    @e7 button
+
+@r8 desktop window
+  state B (epoch 2)
+    @e1 application
+    @e12 text field
+```
+
+`search_ui` and ordinary inspection are pure cached queries. A live escalation such as OCR or a refreshed truncated region is epoch-checked and resource-scheduled. It cannot silently graft data across a concurrent mutation.
+
+## Acting and batching
+
+`act_ui` runs one dependent action list:
+
+```ts
+act_ui({
+  stateId,
+  actions: [
+    { action: "setText", ref: "@e12", text: "hello" },
+    { action: "press", ref: "@e18" },
+  ],
+})
+```
+
+Transactions may include a semantic postcondition:
+
+```ts
+act_ui({
+  stateId,
+  actions: [{ action: "press", ref: "@e9" }],
+  expect: { text: "Saved", timeoutMs: 3000 }
+})
+```
+
+With a postcondition, the backend waits for the requested text or role to
+appear (or disappear with `gone: true`) before reporting success. It records
+whether the condition was newly verified, already present before delivery, or
+failed. A failed postcondition changes the execution outcome to `didnt`; event
+delivery alone is never treated as semantic success.
+
+One action is represented by an array of length one. A multi-action transaction is appropriate only when no intermediate observation is needed. The runtime validates one base state, acquires one resource lane, and sends the steps as one native helper transaction. The helper captures one pre-transaction root baseline, executes and verifies steps in order, and stops on the first failed or invalidated step. Partial results include `stoppedAt`, so callers know the exact checked boundary and must re-observe before continuing. The helper performs one final root-delta settle and the bridge produces one final observation. There is no alternate sequential protocol. This is not a mechanism for parallel actions within one UI resource.
+
+The bridge resolves model intent; the backend/helper owns grounding, preflight, delivery, and evidence. Accessibility capabilities choose an initial strategy but are not treated as proof that the intended result occurred. Editable-region clicks establish foreground focus for following unscoped keyboard steps in the same transaction. Raw coordinates are tied to the image-bearing state that produced them. Web-backed editable controls use atomic keyboard events and web-backed buttons use pointer events so application state receives normal input events rather than only a changed AX value. A helper result reports `worked`, `didnt`, or `unknown`, including evidence and shallow root changes where available.
+
+With `headless: true`, the background boundary is strict: Pi must never activate or raise an application, change the user's focused window, move the global cursor, post raw input, or display the agent cursor. With `headless: false` (the default), credible semantic activation may begin in the background, editable clicks preserve the focus they establish for following unscoped keyboard input, and keyboard input with a checked `didnt` result may retry in the foreground because the first attempt proved side-effect-free. Focus-preserving native keyboard requests must not raise or re-focus the window between semantic activation and HID delivery; canvas editors such as PowerPoint otherwise collapse an inner text editor back to placeholder selection. Ambiguous pointer outcomes are never replayed. With `cursor_overlay: true`, non-headless macOS background pointer actions enqueue a click-through agent cursor animation to the native grounded point without delaying delivery; foreground HID actions use only the physical cursor.
+
+The agent-facing `act_ui.headless` flag determines whether foreground execution is prohibited. Fallback-capable multi-action calls execute one checked action at a time, retain click-established focus, and stop on a checked `didnt`; strict-headless calls retain native transactional batching.
+
+## Successor diffs
+
+Complete observations remain immutable and bounded internally. The initial observation renders a folded full view. After a mutation, `view.ts` stabilizes public refs using confident native identities, saves the complete resulting state, and compares it with the base state. Small trustworthy results render `added`, `updated`, and `removed` nodes plus the next `stateId`. Root appearance, closure, and focus changes remain part of the run result.
+
+Diff rendering falls back to a full folded view when the root identity changes, too few successor nodes can be matched confidently, or the change budget would make a patch less useful than the full view. Cached queries always operate on the complete stored state, never on a partially applied model-side tree.
+
+## Browser support
+
+Browser pages are roots, not a second agent-facing context hierarchy. `launch_browser` returns browser-page `@r` refs; `observe_ui` returns their normal outline and `stateId`. `read_text`, `wait_for`, `act_ui`, `navigate_browser`, and `evaluate_browser` derive the CDP target from that state. Internal CDP target identifiers never need to be copied between public tools.
+
+## Native transports
+
+The macOS socket server and Windows line protocol accept multiple in-flight requests and correlate responses by request id. macOS protects shared AX ref/look stores and the root-event sequence; Windows uses a fixed worker pool and initializes UIA per worker thread. Both platforms keep eight immutable native look records and serialize global physical input. Target focus, bounded occlusion preflight, and HID delivery share that same critical section; another worker cannot change the foreground between validation and delivery. UIA-only Windows batches do not acquire the global physical-input lock, while any batch that may fall back to pointer or keyboard delivery holds it for the complete transaction.
+
+The Linux helper is a local JSON-lines child process with correlated concurrent requests. It snapshots roots over AT-SPI2 and attempts semantic `Action`/`EditableText` delivery first. On X11, EWMH enriches root identity/focus, XComposite (with `GetImage` fallback) supplies PNG capture, and non-headless policies may use serialized XTEST physical input. Strict headless/background policy blocks XTEST and focus. Wayland diagnostics only reads portal version and capability properties; no portal session, capture, or input path is implemented.
+
+Windows UIA extraction is bounded. When the native limit omits descendants, the nearest retained ancestors are marked `truncated`; `expand_ui` performs a scoped look and the helper carries forward the untouched refs into the new immutable look record. Windows root deltas combine an event journal with authoritative before/after snapshots. `SetWinEventHook` accelerates settling and retains short-lived root transitions, while snapshots remain the source of truth for persistent state.
+
+## Preventing platform drift
+
+Platform parity is defined by invariants, not matching source structure. Every helper reports an `architectureVersion` and the invariant set it implements. Startup fails closed if either helper omits a required invariant. The TypeScript backend interface and conformance check additionally require both platforms to expose the same observation, text ownership, batching, and lifecycle operations.
+
+Changes to a native backend should therefore include three layers of evidence:
+
+1. shared contract tests for request and response semantics;
+2. target-native compilation and deterministic native unit tests;
+3. the same black-box Cubench properties on an interactive host for that platform.
+
+OS-specific mechanisms can differ—AX, ScreenCaptureKit, and the AppKit agent-cursor overlay on macOS; UIA and Windows capture/input APIs on Windows; AT-SPI2 plus optional X11 EWMH/XComposite/XTEST on Linux—but state ownership, bounds, progressive disclosure, transaction boundaries, and honest outcomes may not. The overlay lives inside the existing helper because native action grounding owns the final screen point; keeping it there avoids a second coordinate transform or public cursor tool surface. The helper's socket server runs off the main thread while AppKit owns the main run loop, and the helper excludes its click-through overlay from root discovery. Cursor animation is observational: newer actions may supersede an in-flight path, but rendering never blocks action delivery or verification.
+
+## Design constraints
+
+- Preserve the multi-root forest and progressive disclosure.
+- Make state ownership explicit; never depend on a mutable session-wide current UI.
+- Reject stale writes before dispatch using resource epochs.
+- Serialize by physical resource, not by tool name or whole session.
+- Prefer platform semantics as the cheapest credible attempt, then trust verified outcomes over advertised capabilities.
+- Preserve focus established by one transaction step for dependent keyboard steps.
+- Store full immutable states and render the smallest trustworthy resulting view.
+- Keep observation compact and expand locally.
+- Let the backend/helper own action grounding and verification.
+- Keep platform mechanisms behind the platform-neutral seam.
+- Treat batching as one-resource transaction amortization, not a separate execution architecture.
+- Fail closed when an action outcome is uncertain; a later call must observe again.

package/extensions/third-party/node_modules/@injaneity/pi-computer-use/docs/configuration.md

@@ -0,0 +1,92 @@
+# Configuration
+
+Configuration controls browser access, strict accessibility execution, and the macOS agent cursor.
+
+## Files
+
+Global config:
+
+```text
+~/.pi/agent/extensions/pi-computer-use.json
+```
+
+Project config:
+
+```text
+.pi/computer-use.json
+```
+
+Project config overrides global config. Environment variables override both.
+
+Example:
+
+```json
+{
+  "browser_use": true,
+  "managed_browser": "chrome",
+  "headless": false,
+  "cursor_overlay": true
+}
+```
+
+Run `/computer-use` in Pi to show the active config and its source.
+
+## Options
+
+### `browser_use`
+
+Default: `true`
+
+When `false`, the extension refuses known browser windows. This is useful for projects that should not control browsers.
+
+Known browser families include Safari, Chrome and Chromium-family browsers, Firefox, Arc, Brave, Edge, Vivaldi, and Helium.
+
+### `managed_browser`
+
+Default: `"chrome"`
+
+Selects `"helium"` or `"chrome"` for `launch_browser`. The debugging port is always allocated internally and isn't part of the model-facing contract.
+
+### `headless`
+
+Default: `false`
+
+When `true`, actions must remain in the background. Raw pointer events, raw keyboard events, foreground focus fallback, cursor takeover, and the agent cursor overlay are blocked. When `false` (the default), Pi prefers verified semantic activation when it is credible, preserves the focus established by editable clicks for dependent keyboard input, and may retry keyboard input in the foreground when a background attempt conclusively produced no value change. Ambiguous pointer actions are never replayed blindly.
+
+### `cursor_overlay`
+
+Default: `true`
+
+When `true`, macOS pointer actions enqueue a click-through agent cursor animation to the native grounded point during non-headless background delivery. Foreground actions that control the physical cursor don't display the overlay. The overlay doesn't move the system pointer, accept input, or delay the action. Set it to `false` for invisible automation. `headless: true` always suppresses it regardless of this setting.
+
+## Environment variables
+
+```bash
+PI_COMPUTER_USE_BROWSER_USE=0
+PI_COMPUTER_USE_BROWSER_USE=1
+PI_COMPUTER_USE_MANAGED_BROWSER=helium
+PI_COMPUTER_USE_MANAGED_BROWSER=chrome
+PI_COMPUTER_USE_CHROME_EXECUTABLE=/absolute/path/to/chrome
+PI_COMPUTER_USE_HELIUM_EXECUTABLE=/absolute/path/to/helium
+PI_COMPUTER_USE_HEADLESS=0
+PI_COMPUTER_USE_HEADLESS=1
+PI_COMPUTER_USE_CURSOR_OVERLAY=0
+PI_COMPUTER_USE_CURSOR_OVERLAY=1
+PI_COMPUTER_USE_DELIVERY_POLICY=default
+PI_COMPUTER_USE_DELIVERY_POLICY=foreground
+PI_COMPUTER_USE_CDP_PORT=9222
+```
+
+`PI_COMPUTER_USE_HEADLESS=1` prohibits foreground fallback. `PI_COMPUTER_USE_DELIVERY_POLICY` is a debugging input; normal policy belongs in configuration rather than individual model calls.
+
+`launch_browser` searches common platform install locations and `PATH`. Use `PI_COMPUTER_USE_CHROME_EXECUTABLE` or `PI_COMPUTER_USE_HELIUM_EXECUTABLE` for an AppImage, portable install, or any non-standard location. An explicit override is authoritative and must name an executable file.
+
+## CDP browser support
+
+`PI_COMPUTER_USE_CDP_PORT` enables Chrome DevTools Protocol support for Chromium-family browsers. Launch the browser with `--remote-debugging-port=<port>` and set this variable to the same port.
+
+Use a dedicated, non-default profile with `--user-data-dir=<directory>`. Chrome 136 and later ignore remote-debugging switches for the default data directory as a security measure. `launch_browser` already creates a temporary, separate CDP profile and binds discovery to a randomly allocated loopback port.
+
+When CDP is active, discovered pages participate in the same root and state system as desktop UI. `launch_browser` configures CDP automatically and returns an observed page state. `navigate_browser` and `evaluate_browser` accept only CDP browser-page states; native browser windows continue to use the normal desktop observe/act tools.
+
+With the variable unset, CDP is inactive.