codex-computer-use-mcp 0.3.4 → 0.5.0

package/ARCHITECTURE.md

@@ -1,162 +0,0 @@
-# Direct architecture and boundary inventory
-
-Code Mode remains outside this package. See [ADR 0001: Keep Code Mode in a standalone MCP process](docs/adr/0001-standalone-code-mode-mcp.md).
-
-## Design intent
-
-This package is a thin transport adapter to the official signed Computer Use tools. It has no independent policy or security role. Codex and macOS remain authoritative for tool behavior, access decisions, and platform controls.
-
-Preserve the official capability surface. Add adapter code only when the transport, zero-model-turn architecture, component compatibility, or process lifecycle requires it.
-
-Canonical app resolution, same-app locking, focus completion telemetry, and metadata-only audit came from the earlier background-computer-use wrapper. The current release retains them for compatibility. They do not provide extra authorization or sandbox boundaries. This inventory does not justify extending them. A maintainer must explicitly approve their removal or material simplification.
-
-## Official API evidence
-
-The architecture uses public source and the installed signed binaries; it does not speak a private Computer Use socket protocol.
-
-At OpenAI Codex source commit [`5c19155cbd93bfa099016e7487259f61669823ff`](https://github.com/openai/codex/tree/5c19155cbd93bfa099016e7487259f61669823ff):
-
-- the app-server documentation describes initialization, ephemeral threads, and the distinct `turn/start` operation that begins model work ([README lines 74–81](https://github.com/openai/codex/blob/5c19155cbd93bfa099016e7487259f61669823ff/codex-rs/app-server/README.md#L74-L81));
-- it documents `mcpServer/tool/call` as a direct call to a configured MCP tool ([README line 238](https://github.com/openai/codex/blob/5c19155cbd93bfa099016e7487259f61669823ff/codex-rs/app-server/README.md#L238));
-- the typed request contains `thread_id`, `server`, `tool`, and `arguments`—not a prompt or model request ([protocol lines 97–110](https://github.com/openai/codex/blob/5c19155cbd93bfa099016e7487259f61669823ff/codex-rs/app-server-protocol/src/protocol/v2/mcp.rs#L97-L110));
-- the implementation loads the thread runtime and invokes `thread.call_mcp_tool(...)` directly ([processor lines 455–474](https://github.com/openai/codex/blob/5c19155cbd93bfa099016e7487259f61669823ff/codex-rs/app-server/src/request_processors/mcp_processor.rs#L455-L474));
-- downstream structured elicitation is an explicit client capability rather than implicit approval ([README lines 89–94](https://github.com/openai/codex/blob/5c19155cbd93bfa099016e7487259f61669823ff/codex-rs/app-server/README.md#L89-L94)).
-
-The Full access behavior is also public in the pinned Codex `rust-v0.144.2` source at commit [`a6645b6b8a656360fa16fb7e1c6721d0697d3d6a`](https://github.com/openai/codex/tree/a6645b6b8a656360fa16fb7e1c6721d0697d3d6a):
-
-- legacy `danger-full-access` maps to `PermissionProfile::Disabled` ([models lines 289–297](https://github.com/openai/codex/blob/a6645b6b8a656360fa16fb7e1c6721d0697d3d6a/codex-rs/protocol/src/models.rs#L289-L297));
-- MCP permission prompts are auto-approved when the approval policy is `Never` and the permission profile is disabled ([MCP policy lines 76–99](https://github.com/openai/codex/blob/a6645b6b8a656360fa16fb7e1c6721d0697d3d6a/codex-rs/codex-mcp/src/mcp/mod.rs#L76-L99));
-- the elicitation manager applies that policy before client notification ([elicitation lines 196–221](https://github.com/openai/codex/blob/a6645b6b8a656360fa16fb7e1c6721d0697d3d6a/codex-rs/codex-mcp/src/elicitation.rs#L196-L221)), and limits the automatic response to empty-schema approval/confirmation forms ([lines 319–331](https://github.com/openai/codex/blob/a6645b6b8a656360fa16fb7e1c6721d0697d3d6a/codex-rs/codex-mcp/src/elicitation.rs#L319-L331)).
-
-The installed CLI labels app-server experimental. This project therefore verifies the current method and upstream schemas on every call and fails closed on drift.
-
-## Live architecture probe
-
-A raw stdio client can initialize the signed `SkyComputerUseClient` and list all ten tool schemas, but a real `list_apps` call from an ordinary Node parent returns:
-
-```text
-Computer Use server error -10000: Sender process is not authenticated
-```
-
-The same read-only call through signed app-server `mcpServer/tool/call` succeeded while app-server ran with an empty isolated `CODEX_HOME`:
-
-- all ten exact tools discovered;
-- one `mcpServer/tool/call`;
-- 39 apps returned;
-- ephemeral context explicitly attested `ephemeral: true`, `turns: []`, and `path: null`;
-- no `turn/start`, `turn/*`, or `item/*` model activity;
-- no account auth file or model API credential available to app-server;
-- a dummy provider with `supports_websockets = false` and unreachable loopback base URL;
-- plugin and remote-control features disabled;
-- trace/network sampling showed no app-server Responses API connection or model request after those controls (the separate official Computer Use service may use its own network transport).
-
-This is the narrow official boundary: direct calls require a loaded thread runtime ID in the current API, but do not require a conversation turn or model generation. Literal removal of the thread-shaped runtime object would require an upstream app-server API change.
-
-## Sender-authentication differential
-
-A supported fake stdio MCP server was substituted only to observe the app-server's public downstream envelope shape. App-server used:
-
-- MCP protocol `2025-06-18`;
-- `clientInfo` name/title/version identifying `codex-mcp-client` / Codex / the installed CLI;
-- standard `elicitation.form` and `elicitation.url` capability keys;
-- standard progress metadata on `tools/list`;
-- standard progress metadata plus public app-server-added `threadId` metadata on `tools/call`.
-
-An ordinary MCP SDK client then repeated a read-only raw-helper call with the same client identity, capability shape, protocol behavior, and public `progressToken`/random `threadId` metadata shape. The helper still returned `-10000 Sender process is not authenticated`. Changing documented handshake fields therefore does not repair raw dispatch.
-
-The relevant construction difference is the macOS responsible-process chain:
-
-- unsupported: ad-hoc/no-Team-ID Node parent → signed helper;
-- supported: Node/Pi → strict-valid OpenAI-signed app-bundled Codex (`2DC432GLL2`) → strict-valid OpenAI-signed helper (`2DC432GLL2`).
-
-Process sampling confirmed the helper children were direct descendants of signed app-server; helper processes may create their own process groups. App-server and helper therefore share one private broker-session cwd. One-shot MCP calls close that session after the call; Pi retains it only across the required `get_app_state` and following action. Cleanup preserves partial ancestry results, recovers any reparented process by that unique cwd, freezes the owned set to stability, then kills and verifies every process rather than assuming one PGID. Enumeration, freeze, or exit uncertainty fails cleanup closed. The app-server has the expected sandbox/application-group entitlement keys; the helper has OpenAI application/team identifiers, application groups, and keychain-access-group entitlements. Ordinary Node has no Team ID or entitlement set. The service's peer audit token is not exposed through the supported MCP layer. No private socket inspection, identity spoofing, copied signing material, re-signing, injection, or TCC change was attempted. The remaining enforcement boundary is therefore OS peer/responsible-process identity, not a missing public JSON field.
-
-Command, environment, cwd, and config differences were also isolated: both paths invoke the same signed helper with `mcp`; the accepted path gives it a signed parent plus a private fixed cwd/config environment. Matching public MCP fields did not alter the raw error, while the signed-parent path succeeds without model credentials.
-
-## Process path
-
-```text
-Pi model
-  └─ chooses computer_use_<method> and typed arguments
-      └─ local direct service
-          └─ signed app-bundled `codex app-server --stdio`
-              ├─ empty ephemeral runtime context (zero turns; no transcript)
-              └─ `mcpServer/tool/call`
-                  └─ signed SkyComputerUseClient `mcp`
-                      └─ official Computer Use service
-                          └─ target macOS app
-```
-
-Forbidden primary-path methods are enforced by code and tests:
-
-```text
-turn/start
-turn/steer
-turn/resume model work
-codex exec
-codex mcp-server model tools
-nested prompts or result summaries
-```
-
-## Current adapter inventory
-
-| Mechanism or former restriction | Role in the direct design | Current treatment |
-|---|---|---|
-| Reviewed ChatGPT/Codex/client paths | official transport compatibility | current per-user installed-component contract plus exact legacy plugin layout; canonicalized and verified |
-| Strict signatures and OpenAI Team ID | official component verification | retained to verify the selected signed transport components |
-| Signed-parent/responsible-process chain | official transport requirement | retained through signed app-server |
-| Private Sky socket/native-pipe access | unsupported/private route | prohibited |
-| Nested Codex model and prompt | former compatibility layer | removed |
-| Model selection and reasoning effort | former compatibility layer | removed; dummy unreachable provider prevents model transport |
-| Responses websocket prewarm on empty thread | accidental app-server behavior | disabled with non-websocket dummy provider |
-| Plugin/remote-control startup networking | accidental app-server behavior | corresponding features disabled |
-| Model-written multi-step task plan | former compatibility layer | removed |
-| Model result schema/summary | former compatibility layer | removed |
-| Streamed model-event target/method validation | former compatibility layer | replaced by pre-dispatch typed call validation |
-| Per-operation tool allowlists and call budgets | former wrapper policy | removed; one typed method per direct request |
-| Task text, cleanup instructions, required-capabilities fields | former compatibility layer | removed |
-| Dictionary-only special policy | former wrapper policy | removed |
-| Wrapper app/intent allowlists in full mode | former wrapper policy | absent |
-| Safe/full wrapper modes | former wrapper policy | removed; one durable no-permissions interface exposes all ten methods |
-| Wrapper approval prompts/configuration | former wrapper policy | removed; no command, config, environment, or per-call selector remains |
-| Official first-party app access | official Codex control | official Codex Full access auto-accepts normal empty-schema app approval elicitations; any elicitation app-server emits is forwarded unchanged |
-| macOS TCC | official platform control | retained; never modified |
-| Exact ten-tool inventory/schema | protocol compatibility check | retained and checked before each call |
-| Canonical bundle identity | legacy wrapper behavior | retained for the current release contract; not an independent authorization boundary |
-| Same-app kernel lock | legacy wrapper coordination | retained in one fixed per-user namespace shared across Pi/MCP state roots |
-| Automatic background app launch | accidental wrapper behavior | removed; the official tool owns app behavior |
-| Global focus watcher and final sample | legacy completion telemetry | retained for the current release contract; not a preventive sandbox |
-| Timeout/cancellation process-tree termination | operational lifecycle | retained with strict enumeration, freeze, kill, stdio-close, and exit verification |
-| Temporary broker-session cleanup | operational lifecycle | retained with isolated `CODEX_HOME`; Pi closes after the inspection-action pair, replacement inspection, or session shutdown |
-| Codex token usage accounting | former compatibility layer | removed; no model turn exists |
-| Content-safe private audit | legacy observability behavior | retained with direct-call fields; not an authorization mechanism |
-| Full-result spill files | output hygiene | prohibited; truncation is in-memory only |
-| Browser-host integration | out of scope | unchanged |
-
-These roles explain the current code. They do not authorize new safeguards. Only propose hardening for a concrete, realistically reachable failure in the supported path.
-
-## No-permissions and elicitation boundary
-
-No-permissions is the sole interface and means unrestricted wrapper dispatch with no wrapper approval prompt. All ten methods are registered. No config file, environment value, slash command, CLI mode switch, or tool argument selects another route.
-
-App-server is created with `approvalPolicy: "never"` and `sandbox: "danger-full-access"`. This is the official Codex Full access combination. The legacy sandbox field maps to `PermissionProfile::Disabled`; Codex then auto-accepts empty-schema MCP approval elicitations before client notification. Normal first-party Computer Use app approvals therefore do not prompt, and the bridge does not need to mutate the per-bundle approval store.
-
-The broker still handles any `mcpServer/elicitation/request` that app-server emits. Pi advertises OpenAI-form support and renders emitted form, OpenAI-form, and URL requests. Generic stdio MCP forwards supported standard modes as `elicitation/create`. The response path preserves `accept`, `decline`, `cancel`, structured content, and response metadata; no callback or compatible UI yields `cancel`, never an invented decision.
-
-## Pi tool and session boundary
-
-The Pi extension registers and activates all ten official definitions on `session_start`, additively preserving active tools owned by Pi and other extensions. Keeping inspection and interaction methods on the same direct surface avoids provider-bound tool discovery creating a second, incompatible client binding.
-
-For `get_app_state`, Pi starts one verified zero-turn app-server runtime and signed Computer Use client. The following direct interaction is serialized through that same runtime and thread, preserving the official active-app lease. The retained process tree is closed and verified after the action, before a replacement inspection, or during `session_shutdown`. One-shot MCP calls still start and close a broker session within the call. Exact inventory and schemas are revalidated before every dispatch in either path.
-
-This lifecycle changes neither the schemas nor the no-permissions policy. Interaction definitions omit extra `promptSnippet` and `promptGuidelines` metadata and rely on their official descriptions.
-
-## Output boundary
-
-Only official `text` and `image` MCP blocks are accepted. They are returned to the invoking client because app state and screenshots are the requested capability. They are never copied to audit, logs, temp files, or structured metadata. Text is truncated in memory at Pi's standard 50KB/2000-line bound; the full text is not persisted.
-
-## Package name
-
-Version 0.2.0 keeps the repository and npm package name `codex-computer-use-mcp` for continuity with version 0.1.0. Pi-owned typed tools are now the primary product path. OpenAI's signed Codex app-server remains an implementation boundary, not the planner.
-
-Any future package or repository rename would be a separate distribution change and would require maintainer approval.

package/CHANGELOG.md

@@ -1,19 +0,0 @@
-# Changelog
-
-This changelog records user-visible changes from version 0.3.2 onwards.
-
-## 0.3.4 - 2026-07-27
-
-### Fixed
-
-- Match native Computer Use focus behavior: already-frontmost targets, focus changes, and unavailable legacy focus telemetry no longer block or override official tool results. Focus observations remain available in metadata-only audit and response details.
-
-## 0.3.3 - 2026-07-27
-
-### Fixed
-
-- Support the macOS 27 `lsappinfo` `bundleID` output so frontmost-app detection can proceed to official Computer Use dispatch. [Brad Hallett](https://github.com/bradhallett) contributed this fix in [PR #6](https://github.com/tmustier/codex-computer-use-mcp/pull/6).
-
-### Documentation
-
-- Clarify that this package is a thin transport adapter and distinguish official transport requirements from retained legacy wrapper behavior in [PR #12](https://github.com/tmustier/codex-computer-use-mcp/pull/12).

package/CONTRIBUTING.md

@@ -1,33 +0,0 @@
-# Contributing
-
-Contributions are welcome, especially compatibility fixes, direct-protocol tests, realistic regression coverage, and clearer host diagnostics.
-
-## Setup
-
-```bash
-npm ci
-npm run check
-npm run check:pi
-npm test
-npm run build
-```
-
-Development and live acceptance require macOS and the official ChatGPT Computer Use component. Acceptance evidence must use benign real apps, not a disposable harness alone.
-
-## Pull requests
-
-- Keep Pi-owned typed methods as the primary path.
-- Do not add a nested model, action planner, prompt, subagent, or model-written result summary to direct dispatch.
-- Do not use private pipes/sockets, credential extraction, app injection, re-signing, sender impersonation, TCC automation, or automatic approval acceptance.
-- Keep app-server in a credential-free isolated `CODEX_HOME` with only official Computer Use configured.
-- Add a regression test for each concrete protocol, compatibility, lifecycle, or current-behavior fix.
-- Never log or persist arguments, typed values, screenshots, app-state/result content, elicitation contents, prompts, credentials, or tokens.
-- Do not add wrapper-side permission policy, risk classification, allowlists, gates, or speculative defence-in-depth on top of official Codex and macOS controls.
-- Treat current focus checks as legacy post-action completion telemetry, not preventive isolation or a precedent for further hardening.
-- Document reviewed ChatGPT component paths, launcher contracts, and upstream schema/API assumptions.
-- Include strict core/Pi type checks, tests, build, audit, package inspection, and real-app acceptance evidence.
-- Review material transport or published-behavior changes at the exact head, and keep findings tied to realistic supported paths.
-
-Repository/package renaming, merge, npm publication, and GitHub release require separate maintainer approval.
-
-See `ARCHITECTURE.md`, `SECURITY.md`, and `MIGRATION.md`.

package/MIGRATION.md

@@ -1,134 +0,0 @@
-# Migration and rollback
-
-Version 0.2.0 was the breaking direct-tool architecture change from version 0.1.0. Version 0.3.0 added Pi progressive disclosure, version 0.3.1 followed ChatGPT's current per-user Computer Use component layout, version 0.3.2 restored one complete direct Pi surface with shared inspection-action session continuity, version 0.3.3 added macOS 27 compatibility, and version 0.3.4 aligns focus behavior with native Computer Use. Use the relevant section below.
-
-## What changes
-
-| 0.1 released surface | 0.2 direct surface |
-|---|---|
-| `background_computer_use` aggregate task | ten `computer_use_<method>` Pi tools |
-| `background_computer_use_status` | `/computer-use-status` and MCP `computer_use_status` |
-| `/background-computer-use-mode` | removed; `/computer-use-status` is read-only |
-| safe/full wrapper modes | one durable no-permissions interface: all ten methods, no wrapper prompts |
-| nested model plans and summarizes | Pi calls one official typed method per tool call |
-| separate Codex model usage | no nested model/token usage |
-| state under wrapper-specific old path | isolated direct state under `~/.direct-computer-use` or Pi agent direct state |
-
-## Pre-migration checks
-
-1. Stop all current aggregate Computer Use calls.
-2. Record the installed package/extension version and permission mode.
-3. Back up the Pi package/config files without copying audit content into tickets or chat.
-4. Confirm no `pi-native-app-worker.*`, `SkyComputerUseClient mcp`, `codex app-server`, `lockf`, or focus-listener process from the old adapter is active. The direct adapter uses one fixed private `/tmp/codex-computer-use-mcp-<uid>` lock namespace across Pi and MCP state roots.
-5. Keep the old and new adapters from registering overlapping tools in one Pi process.
-
-## Source acceptance without installation
-
-Use a fresh Pi process and the source extension explicitly:
-
-```bash
-npm ci
-npm run build
-CODEX_COMPUTER_USE_HOME="$(mktemp -d)" \
-  pi -ne -e /absolute/path/to/integrations/pi/index.ts
-```
-
-`-ne` suppresses auto-discovered extensions so the live 0.1 adapter is not loaded. This does not change live Pi configuration.
-
-The source adapter starts only in no-permissions mode: all ten methods are available and the wrapper opens no permission UI of its own. The signed app-server runs with Codex Full access, so normal empty-schema app approval elicitations resolve without a prompt. Any elicitation app-server emits is still shown through Pi and answered only by the user. Use benign real apps for acceptance; do not use disposable harnesses as evidence.
-
-## Migrate to version 0.2.0
-
-1. Back up `~/.pi/agent/settings.json`, `~/.pi/agent/mcp.json`, and the installed 0.1 package or extension directory.
-2. Record the installed version and verify that npm resolves `codex-computer-use-mcp@0.2.0` exactly.
-3. Remove or disable the 0.1 aggregate adapter and generic MCP registration.
-4. Install `npm:codex-computer-use-mcp@0.2.0`.
-5. Remove any legacy direct `config.json`; the new build ignores it and has no mode selector.
-6. Start a fresh Pi process; do not rely on hot-reloading a security-boundary change.
-7. Verify `/computer-use-status` reports:
-   - `permissionMode: "no-permissions"`;
-   - `wrapperPermissionPrompts: false`;
-   - `officialApprovalPolicy: "full-access"`;
-   - `officialAppApprovalHandling: "auto-approved-by-codex-full-access"`;
-   - `officialElicitationHandling: "forwarded-if-emitted"`;
-   - all ten `availableMethods`;
-   - `brokerVerified: true`;
-   - `nestedModel: false`;
-   - `modelUsage: false`;
-   - `ephemeralZeroTurnRuntimeContextRequired: true`.
-8. Run `computer_use_list_apps` and `computer_use_get_app_state` against a benign real app with external focus sampling while the Mac is unlocked.
-9. Exercise mutating methods on benign disposable content, restore app state, then check audits and process cleanup.
-
-Do not copy old safe/full configuration into the new state root. No-permissions is compiled as the sole unrestricted, no-wrapper-prompt interface.
-
-Version 0.2.0 does not support targeted local Computer Use while the Mac is locked. OpenAI reserves locked use for active trusted turns started from a connected device. See the [locked-screen limitation](README.md#locked-screen-limitation).
-
-## Upgrade from version 0.2.0 to 0.3.0
-
-The MCP contract and signed execution path do not change. The native Pi extension now registers all ten definitions but initially activates only `computer_use_list_apps` and `computer_use_get_app_state`.
-
-1. Upgrade Pi to version 0.80.7 or newer.
-2. Back up `~/.pi/agent/settings.json` and the installed 0.2 package directory.
-3. Verify that npm resolves `codex-computer-use-mcp@0.3.0` exactly, then install that exact package.
-4. Start a fresh Pi process.
-5. Verify that the two inspection tools are initially active and the eight interaction tools remain registered but inactive.
-6. Call `computer_use_get_app_state` against a benign app while the Mac is unlocked. A successful result should add all eight interaction tools without removing any active tool.
-7. Exercise a benign interaction, inspect the private content-safe audit, and verify process cleanup.
-
-The change is context disclosure, not a permission mode. Codex Full access, emitted elicitation forwarding, schemas, and the no-permissions policy remain unchanged.
-
-## Upgrade from version 0.3.0 to 0.3.1
-
-ChatGPT 26.721 moved the signed Computer Use app out of the bundled plugin and into `~/.codex/computer-use/`. Version 0.3.1 follows the official launcher contract while retaining the exact former plugin layout as a compatibility candidate.
-
-1. Verify that npm resolves `codex-computer-use-mcp@0.3.1` exactly, then install that exact package.
-2. Start a fresh Pi process. A running Pi process retains the already-loaded extension code.
-3. Verify `/computer-use-status` reports `brokerVerified: true`.
-4. While the Mac is unlocked, run `computer_use_list_apps` and `computer_use_get_app_state` against a benign real app.
-
-The resolver does not read `HOME` or `CODEX_HOME` and has no arbitrary path override. Missing, symlinked, invalidly signed, or wrong-Team-ID clients fail closed.
-
-## Upgrade from version 0.3.1 to 0.3.2
-
-Version 0.3.2 activates all ten direct Pi tools at session start and retains one verified signed-client session across `get_app_state` and the following action.
-
-1. Verify that npm resolves `codex-computer-use-mcp@0.3.2` exactly, then install that exact package.
-2. Start a fresh Pi process; do not rely on hot reload for the retained process lifecycle.
-3. Verify all ten `computer_use_*` tools are active through the direct extension binding.
-4. With an unlocked Mac and a benign background app, call `computer_use_get_app_state`, then one harmless interaction against the same app.
-5. Verify the state and action used one app-server runtime/thread, the action did not report an inactive Computer Use session, focus remained preserved, and cleanup completed.
-
-The exact schemas, strict signature and OpenAI Team ID checks, canonical client and app resolution, Full access policy, zero-turn attestation, inventory validation, kernel lock, focus telemetry, process-tree cleanup, and content-safe audit remain mandatory.
-
-## Upgrade from version 0.3.2 to 0.3.3
-
-Version 0.3.3 accepts both the legacy `CFBundleIdentifier` key and the macOS 27 `bundleID` key from `lsappinfo`.
-
-1. Verify that npm resolves `codex-computer-use-mcp@0.3.3` exactly, then install that exact package.
-2. Start a fresh Pi process so it loads the updated extension code.
-3. On an unlocked Mac, run `computer_use_get_app_state` against a benign background app and verify that the result succeeds without moving focus.
-
-## Upgrade from version 0.3.3 to 0.3.4
-
-Version 0.3.4 removes the legacy background-only focus gate. Calls now match native Computer Use when a target is already frontmost, changes focus, or focus telemetry is unavailable. Focus observations remain metadata-only telemetry. No configuration migration is required.
-
-1. Verify that npm resolves `codex-computer-use-mcp@0.3.4` exactly, then install that exact package.
-2. Start a fresh Pi process so it loads the updated extension code.
-3. On an unlocked Mac, make a benign app frontmost, then run `computer_use_get_app_state` followed by `computer_use_press_key` with `ESC` against that same app.
-4. Verify both calls succeed, `backgroundPreserved` records `false`, the pair uses one zero-turn ephemeral session, and cleanup completes.
-
-## Rollback
-
-1. Stop the current Pi process.
-2. Confirm no direct app-server/client/focus/lock process remains.
-3. Remove or disable the current package registration.
-4. Restore the backed-up 0.1 package/config registration byte-for-byte.
-5. Start a fresh Pi process.
-6. Verify the old status command and installed hash.
-7. Preserve both private audit directories locally; never merge their content or publish it.
-
-Direct state can be removed only after rollback evidence is captured and no process references it. The fixed per-user lock directory can likewise be removed only when no direct call or `lockf` process exists. These paths contain configuration/content-safe metadata and hashed lock ownership—not credentials.
-
-## Generic MCP gateway
-
-If Pi uses `mcp.json`, retain `directTools: false`. Use the exact `0.3.4` package shown in `integrations/pi/mcp.json.example`. During source acceptance, use a distinct temporary server name and source path, then remove it. The direct Pi adapter is the primary live path; do not leave the version 0.1 aggregate server active after the switch.

package/PROOF.md

@@ -1,166 +0,0 @@
-# Direct architecture proof and acceptance record
-
-This file records evidence for the 0.2 direct-tool branch. It does not promise compatibility with future ChatGPT versions or authorize more wrapper safeguards. Historical proof for focus telemetry, locking, cleanup, and audit records released behavior. It does not give the wrapper an independent policy or security role.
-
-## Supported direct path
-
-```text
-Pi chooses typed method/arguments
-  → local direct service
-  → signed app-bundled Codex app-server
-  → mcpServer/tool/call
-  → signed SkyComputerUseClient
-  → official Computer Use service
-```
-
-No model turn, prompt, planner, result summarizer, subagent, shell, web tool, user plugin, or Codex auth credential exists on this path.
-
-## Architectural proof
-
-### Negative raw-helper probe
-
-The official helper's stdio MCP handshake succeeds and exposes all ten schemas. A real direct `list_apps` from an ordinary Node parent fails:
-
-```text
-Computer Use server error -10000: Sender process is not authenticated
-```
-
-Matching the app-server's observed public downstream MCP identity/capability/progress/`threadId` metadata shape in an ordinary raw MCP SDK client still produced the same sender-authentication rejection. Process and signing evidence identified the material difference as ad-hoc/no-Team-ID Node parent versus strict-valid OpenAI-signed app-server parent. The supported layer does not expose the service peer audit token. No attempt was made to forge sender identity, invoke a private pipe/socket, re-sign code, inject into a process, extract credentials, or alter TCC.
-
-### Positive official app-server probe
-
-The same signed helper through official app-server `mcpServer/tool/call` succeeds. Repeated read-only probes established:
-
-- exact ten-tool inventory;
-- one direct `list_apps` call;
-- empty ephemeral context explicitly attested `ephemeral: true`, `turns: []`, and `path: null`;
-- no `turn/start`, `turn/*`, or `item/*` model activity;
-- app-server `CODEX_HOME` isolated from the user's Codex home and containing no auth;
-- model provider replaced by a non-websocket dummy bound to unreachable loopback;
-- plugin and remote-control features disabled;
-- trace/network sampling showed no app-server Responses API connection or model request after those controls;
-- no nested model-token usage;
-- 39 apps returned.
-
-The public OpenAI source basis and permanent links are in `ARCHITECTURE.md`.
-
-## Automated evidence
-
-Current branch tests cover:
-
-- strict TypeScript for core and Pi adapter;
-- current ChatGPT per-user component resolution plus exact legacy-layout compatibility;
-- missing, symlinked-path, invalid-signature, and wrong-Team-ID resolution failures, including no fallback from a present invalid current client;
-- strict signature and Team ID checks;
-- exact official ten-tool inventory/schema drift rejection before dispatch;
-- direct JSONL request sequence with no `turn/start`;
-- isolated credential-free `CODEX_HOME` even when the parent environment contains a model API key;
-- production app-server arguments disable model transport, plugins, and remote control;
-- durable no-permissions as the sole policy, with no config/environment/command/tool override;
-- all ten methods available without wrapper prompts or mode gates;
-- exact `thread/start` Full access parameters (`approvalPolicy: "never"`, `sandbox: "danger-full-access"`);
-- fatal rejection of model-turn notifications, including a notification emitted during teardown;
-- strict `ephemeral: true` / `path: null` / `turns: []` response attestation before dispatch;
-- pre-buffer rejection of an oversized unterminated protocol line;
-- partial-preserving ancestry enumeration plus private-cwd recovery, stable freeze/termination of separately grouped or reparented helpers, and stdio closure;
-- unrestricted read and mutation dispatch under the single no-permissions policy;
-- absence of wrapper app/intent/action gates and permission prompts;
-- canonical bundle-ID dispatch;
-- native-compatible focus behavior for already-frontmost targets, focus changes, and unavailable legacy telemetry;
-- official error preservation;
-- private metadata-only audits with no arguments/results and truthful separate broker/lease cleanup evidence;
-- secure audit-directory/file no-follow and mode checks;
-- global per-user same-app exclusion across different supported state roots, race behavior, crash release, private lock roots, and bounded lock filenames;
-- focus-event ASN retry/drain behavior, including valid events at the start of a single large stdout chunk;
-- stdio MCP all-ten inventory/status with no alternate mode route;
-- signed app-server elicitation forwarding, exact user responses, headless cancellation, and cancellation while a UI callback is pending;
-- standard form/URL forwarding across a real MCP SDK client/server transport;
-- Pi source registration for every direct capability with no nested planner, permission command, or wrapper-generated approval UI;
-- Pi session-start registration and activation of all ten direct definitions while preserving unrelated active tools;
-- one retained broker/client session across `get_app_state` and the following action, with deterministic active-app lease continuity and verified close;
-- Pi form, opaque OpenAI-form, URL, decline, and headless-cancel elicitation handling.
-
-## Version 0.3.4 native focus compatibility
-
-Before the change, a live installed-path call targeting frontmost TextEdit was rejected with `Target app is already frontmost; direct background-only dispatch was refused`; the official broker was never called. The same signed official path accepted a state read when hosted by native ChatGPT, confirming the rejection was wrapper-only.
-
-After the change, a retained signed-client session targeted the app that was already frontmost and completed `get_app_state` followed by harmless `ESC`. Both audits recorded `outcome=ok`, `directCalls=1`, `modelTurnsStarted=0`, `ephemeralThread=true`, `backgroundPreserved=false`, and `appLeaseReleased=true`; cleanup was verified when the retained session closed after the action. No app-state text or screenshot was retained.
-
-## Official Full access approval probe
-
-A live differential used Chess (`com.apple.Chess`), which was absent from the signed service's persistent per-bundle approval file before and after both calls:
-
-1. `approvalPolicy: "never"` with `sandbox: "read-only"` returned `Computer Use approval denied`; app-server never emitted the service's empty-schema approval request to the bridge callback.
-2. Changing only the thread sandbox to `danger-full-access` made the same `get_app_state` call succeed. The bridge callback count and broker `elicitationRequests` were both zero, the runtime remained zero-turn and ephemeral, cleanup verified, and a before/after hash confirmed the persistent approval file was unchanged.
-
-This matches the pinned Codex source: `danger-full-access` maps to a disabled permission profile, and `Never` plus that profile auto-accepts empty-schema MCP confirmation elicitations inside the official host. It proves prompt-free request authorization without editing persistent app approvals or inventing a bridge response.
-
-## Fresh Pi unlocked real-app acceptance
-
-A fresh `pi -ne -e <source adapter> --no-session` process using the branch build exercised all ten tools sequentially in an unlocked macOS session. The target was a real background TextEdit document with disposable local content:
-
-1. `computer_use_list_apps`
-2. `computer_use_get_app_state`
-3. `computer_use_perform_secondary_action` (`Scroll Down`)
-4. `computer_use_scroll` (0.5 page)
-5. `computer_use_drag` (visible text selection)
-6. `computer_use_set_value`
-7. `computer_use_select_text`
-8. `computer_use_type_text`
-9. `computer_use_click`
-10. `computer_use_press_key` (`CMD+A` and `CMD+S`, normalized to official xdotool-style keys)
-
-Evidence:
-
-- 19 strictly sequential direct calls including eight state reads;
-- every call `outcome=ok`, `directCalls=1`, `modelTurnsStarted=0`, `ephemeralThread=true`, and `brokerCleanupVerified=true`;
-- every targeted call `backgroundPreserved=true`;
-- no first-party approval request appeared or was accepted;
-- final saved document content exactly `DIRECT COMPUTER USE ACCEPTANCE CLEANUP COMPLETE`;
-- 702 external 50ms frontmost samples, all Music, zero TextEdit samples;
-- 37 sampled direct app-server process observations, all `app-server --stdio` with the disabled provider; zero `codex exec`/`mcp-server` nested commands;
-- zero app-server TCP sockets observed after model/plugin/remote-control transport was disabled;
-- zero leaked direct app-server/client/focus/lock processes; zero owner files;
-- TextEdit was stopped and the disposable document removed after verification.
-
-Earlier exploratory attempts exposed and fixed two acceptance-quality issues rather than being counted as proof: common `CMD+A` needed normalization to the official `Meta_L+a` key form, and TextEdit state restoration had to be reset before a fresh run. The final evidence above is from the corrected direct path.
-
-## Historical Pi 0.80.7 progressive-disclosure measurement
-
-This measurement describes version 0.3.0 and 0.3.1. Version 0.3.2 intentionally supersedes progressive disclosure because it could leave direct interaction tools absent or make a provider-discovered interaction use a different client from direct `get_app_state`.
-
-
-A fresh Pi 0.80.7 process loaded only the source Computer Use extension plus a read-only observer. All ten definitions were registered. The initial active Computer Use set was exactly:
-
-- `computer_use_list_apps`
-- `computer_use_get_app_state`
-
-Serializing names, descriptions, schemas, and prompt guidelines measured 6,063 bytes for all ten definitions and 1,231 bytes for the initial two: 4,832 bytes removed from the initial request, a 79.7% reduction for this tool family.
-
-A second fresh process exercised the exported activation path from inside a tool execution. Pi's tool result recorded the exact eight interaction names in `addedToolNames`; the before/after active sets retained both inspection tools and removed zero tools. The lazily activated definitions had no `promptSnippet` or `promptGuidelines`.
-
-With `openai-codex/gpt-5.6-sol`, the first request reported 5,723 uncached input tokens. The immediately following request after additive activation reported 1,008 uncached input tokens and 5,632 cache-read tokens. This was live provider evidence that the initial prefix remained reusable while Pi inserted the eight definitions at the tool-result load point. Version 0.3.2 removes that activation path in favor of complete direct registration and signed-client session continuity.
-
-## Review and release status
-
-The direct implementation at commit `98d26f8040f8035a294caa8581d218a33c076990`, tree `01dd30c899863d182bcb0ac3256bd0cc11efc42b`, passed the immutable exact-head review and rollback-safe activation gates. It became the basis for the version 0.2.0 release.
-
-Validation recorded for the reviewed direct implementation:
-
-- `npm ci`: pass;
-- `npm run check`: pass;
-- `npm run check:pi`: pass;
-- `npm test`: 45/45 pass;
-- `npm run build`: pass;
-- `npm audit --omit=dev`: zero vulnerabilities;
-- `npm pack --dry-run`: 36 intended files, shrinkwrap present, no removed nested-runner artifact;
-- public-source scrub: no secrets, private absolute paths, or machine identifiers found;
-- fresh-Pi real-app acceptance: pass as above.
-
-Independent reviews of earlier revisions found cleanup and coordination gaps: fail-open or partial descendant enumeration, early-exit orphan recovery, state-root-scoped same-app locking, false-success lease-release audit, unverified focus-listener exit, pre-response direct-call accounting, and large-chunk focus-event loss. The reviewed implementation retains those fixes while removing wrapper-generated approval UI and safe or full configuration branches. The follow-up Full access change uses Codex's own policy to resolve normal empty-schema app approvals without prompts; any elicitation app-server emits remains a separate, faithfully forwarded user interaction.
-
-Version 0.2.0 supports direct local calls only in an unlocked macOS session. Targeted calls failed with official error `-10005` during genuine locked-session acceptance. OpenAI limits locked Computer Use to active trusted turns started from a connected device, so locked local use remains follow-up work and is not part of this release.
-
-## Non-goals
-
-No private Sky protocol clone, browser-host integration, credential extraction, TCC automation, app injection, re-signing, sender-auth bypass, wrapper-side approval fabrication, persistent approval-file mutation, nested model fallback, or tool-result persistence.

package/dist/config.d.ts

@@ -1,12 +0,0 @@
-export type PermissionMode = "no-permissions";
-export interface ExtensionConfig {
-    version: 2;
-    permissionMode: PermissionMode;
-}
-/**
- * The direct interface has one durable policy: no wrapper permission prompts and
- * no wrapper method restrictions. There is intentionally no file, environment,
- * command, tool argument, or per-call override that can select another mode.
- */
-export declare const DEFAULT_CONFIG: ExtensionConfig;
-export declare function loadConfig(): Promise<ExtensionConfig>;

package/dist/config.js

@@ -1,10 +0,0 @@
-/**
- * The direct interface has one durable policy: no wrapper permission prompts and
- * no wrapper method restrictions. There is intentionally no file, environment,
- * command, tool argument, or per-call override that can select another mode.
- */
-export const DEFAULT_CONFIG = { version: 2, permissionMode: "no-permissions" };
-export async function loadConfig() {
-    return { ...DEFAULT_CONFIG };
-}
-//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAEhG,MAAM,CAAC,KAAK,UAAU,UAAU;IAC/B,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;AAC9B,CAAC"}

package/dist/lock.d.ts

@@ -1,17 +0,0 @@
-export interface LockOwner {
-    runId: string;
-    pid: number;
-    app: string;
-    startedAt: string;
-}
-export declare class AppBusyError extends Error {
-    readonly owner?: Partial<LockOwner>;
-    constructor(app: string, owner?: Partial<LockOwner>);
-}
-export interface AppLock {
-    path: string;
-    owner: LockOwner;
-    release(): Promise<void>;
-}
-export declare function globalAppLockRoot(): string;
-export declare function acquireAppLock(stateDir: string, app: string, runId: string, _staleAfterMs?: number): Promise<AppLock>;