codex-computer-use-mcp 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Contributions are welcome, especially compatibility fixes, adversarial policy tests, and clearer host diagnostics.
+
+## Setup
+
+```bash
+npm ci
+npm run check
+npm test
+npm run build
+```
+
+Development and live acceptance require macOS plus the official ChatGPT app. Tests that verify the bundled broker and compile disposable native harnesses are intentionally host integration tests.
+
+## Pull requests
+
+- Keep safe mode list-only; do not add targeted dispatch without a preventive mechanism that preserves official signed-parent authentication.
+- Do not add credential extraction, app injection, re-signing, private protocol bypasses, TCC automation, or automatic approval acceptance.
+- Add a regression test for every policy or cleanup fix.
+- Avoid logging task text, typed values, screenshots, app-state payloads, or model output.
+- Document any new fixed ChatGPT bundle path or CLI assumption.
+- Include `npm run check`, `npm test`, and `npm run build` results.
+- For targeted behavior changes, include a benign stopped-app acceptance and external focus evidence, and label post-dispatch checks honestly.
+
+Security-boundary changes should receive an independent exact-head review before merge. See `SECURITY.md` for private vulnerability reporting.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Mustier
+
+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/PROOF.md

@@ -0,0 +1,81 @@
+# Proof and acceptance record
+
+This records evidence for the standalone MCP extraction. It does not guarantee compatibility with future ChatGPT macOS versions.
+
+## Supported path
+
+```text
+MCP client → wrapper → app-bundled signed Codex CLI → signed SkyComputerUseClient → official Computer Use service
+```
+
+Direct unsigned access was rejected by sender authentication. The wrapper does not bypass that boundary. It verifies the fixed app-bundled Codex and Computer Use client with `codesign --verify --strict` and OpenAI Team ID `2DC432GLL2` before each run.
+
+## Preventive-boundary finding
+
+An independent `gpt-5.6-sol`/`xhigh` review of the first standalone candidate found that streamed target and argument checks occur after official-client dispatch. A model deviation could therefore reach a different already-approved app before the wrapper killed the worker.
+
+A local MCP proxy was prototyped and proved capable of rejecting a wrong target before forwarding. It was not adopted: making the unsigned proxy the official client's parent breaks the signed-parent sender-authentication chain and caused live Computer Use to fail. Injection, re-signing, credential extraction, and authentication bypass were rejected as out of bounds.
+
+The public authorization model was changed instead:
+
+- safe mode is list-only;
+- all targeted modes are rejected and audited before worker launch;
+- full-permissions mode is explicitly acknowledged broad authorization;
+- streamed target/method/argument/focus/cleanup checks are documented as post-dispatch detection and completion criteria, not a preventive sandbox.
+
+## Other review remediation
+
+The same review found and prompted fixes for:
+
+- incomplete operations returning a non-error tool status;
+- policy-validation failures missing audits;
+- lease-release failure suppressing the audit attempt;
+- cancellation losing available runner metadata;
+- ASN lookup failures being permanently deduplicated;
+- final focus sampling not draining an in-flight sample;
+- caret-ranged published dependencies without a shrinkwrap;
+- status claiming a healthy boundary without verifying the signed broker;
+- insufficient release provenance guidance.
+
+A second exact-tree review accepted the P1 architectural remediation and found two further P2 races: shutdown-only focus events could exhaust the single post-stop ASN lookup, and cancellation audits stored only a count rather than ordered methods. The watcher now performs a bounded awaited drain after listener closure and fails closed if any ASN remains unresolved. Cancellation now returns structured non-retryable error details and persists the ordered sanitized method list plus cleanup uncertainty. Combined regressions cover both cases.
+
+## Test and host evidence
+
+The original reviewed core demonstrated:
+
+- strict TypeScript compilation;
+- signed broker and ten-method schema verification;
+- crash-release and bounded hashed-lock tests;
+- streamed event, failed-status, call-budget, timeout, and cancellation tests;
+- focus watcher drain/final-query tests;
+- secure config/audit no-follow, mode, and fsync checks;
+- fresh stopped-Calculator background action with `2 + 2 = 4`, `AC → 0`, cleanup verified, and zero Calculator-frontmost samples;
+- all ten official methods, different-app concurrency, same-app exclusion, and cancellation cleanup in earlier benign harness acceptance.
+
+The standalone MCP server additionally demonstrated a real stdio client handshake and safe-mode `list` call:
+
+- result `ok`;
+- 39 apps;
+- one successful `list_apps` method;
+- background preserved;
+- separate Codex usage reported;
+- private sanitized audit written.
+
+After remediation, release validation must rerun the exact current test count, build, dependency audit, package inspection, read-only list acceptance, Pi adapter smoke, and independent exact-head review. The GitHub release should bind the final commit, tracked-tree aggregate hash, package integrity, host versions, and reviewer verdict.
+
+## Release gate
+
+Before publishing:
+
+1. Run `npm ci`, `npm run check`, `npm test`, `npm run build`, and `npm audit --omit=dev`.
+2. Inspect `npm pack --dry-run`; verify `npm-shrinkwrap.json` and exact runtime dependency versions are included.
+3. Verify ChatGPT/Codex/client signatures and Team ID on the acceptance host.
+4. Run fresh stdio MCP `list` acceptance in safe mode.
+5. Run one benign stopped-app action only after explicitly enabling full-permissions, with external focus sampling and cleanup verification.
+6. Check for leaked workers, listeners, lock holders, owner records, and harness apps.
+7. Independently review the exact release tree. Do not publish with unresolved P0/P1/P2 findings.
+8. Record commit, aggregate hash, package integrity, host versions, test count, and review verdict in the release.
+
+## Non-goals
+
+This project does not provide a Sky protocol clone, browser-host integration, credential extraction, TCC automation, app injection, re-signing, sender-authentication bypass, or automatic approval acceptance.

package/README.md

@@ -0,0 +1,195 @@
+# Codex Computer Use MCP
+
+A local MCP server that lets compatible agents use the official, signed Computer Use broker bundled with the OpenAI ChatGPT macOS app.
+
+It exposes all ten typed Computer Use methods while preserving:
+
+- official OpenAI code-signing checks;
+- first-party app approvals and sensitive-action prompts;
+- macOS Screen Recording and Accessibility permissions;
+- a deliberately list-only safe default;
+- explicit acknowledgement before broad full-permissions mode;
+- per-app kernel locks;
+- foreground/focus telemetry with fail-closed background guarantees;
+- output schemas, call budgets, timeout and process-group cleanup;
+- sanitized, mode-`0600` metadata audits.
+
+> **Independent project.** This is not an OpenAI product and is not endorsed by OpenAI. It depends on implementation details in the macOS ChatGPT app and may need updates when that app changes.
+
+## Important authorization model
+
+The official Computer Use client authenticates its signed parent process. Putting an unsigned local MCP proxy between app-bundled Codex and that client breaks the official sender-authentication boundary. Therefore wrapper checks of a nested model's target and arguments can only observe events **after** the signed client has dispatched them.
+
+This project does not pretend that post-dispatch observation is a preventive sandbox:
+
+- **Safe mode permits only `list`.** No target app or mutation is dispatched.
+- **Full-permissions mode broadly authorizes the wrapper to use official Computer Use.** It retains first-party OpenAI/macOS controls and detects target, method, argument, call-budget, focus, and cleanup drift, but detection cannot undo an action already dispatched.
+
+Do not enable full-permissions if you need the wrapper itself to provide a preventive per-app security boundary.
+
+## Requirements
+
+- macOS
+- Node.js 22 or newer
+- the official ChatGPT macOS app at `/Applications/ChatGPT.app`
+- a Codex account/session available to the app-bundled Codex CLI
+- required first-party OpenAI app approvals and macOS privacy permissions, completed in their official UI
+
+The server never extracts credentials, re-signs or injects into an app, changes TCC permissions, forges sender authentication, or self-accepts first-party approvals.
+
+## Install
+
+### From npm (after a release is published)
+
+```bash
+npm install -g codex-computer-use-mcp
+codex-computer-use-mcp --status
+```
+
+### From source
+
+```bash
+git clone https://github.com/tmustier/codex-computer-use-mcp.git
+cd codex-computer-use-mcp
+npm ci
+npm test
+npm run build
+node dist/mcp-server.js --status
+```
+
+Running `codex-computer-use-mcp` with no arguments starts the stdio MCP server.
+
+## Tools
+
+### `background_computer_use`
+
+| Mode | Purpose | Permission mode |
+|---|---|---|
+| `list` | List apps visible to official Computer Use | Safe or full |
+| `inspect` | Read one app | Full only |
+| `act` | Perform a concrete app task | Full only |
+| `dictionary_lookup` | Constrained local Apple Dictionary workflow | Full only |
+
+Optional fields include `cleanup`, `cleanup_instructions`, and `required_capabilities`. The latter can require observed successful use of official methods:
+
+`list_apps`, `get_app_state`, `click`, `perform_secondary_action`, `set_value`, `select_text`, `scroll`, `drag`, `press_key`, `type_text`.
+
+### `background_computer_use_status`
+
+Returns the permission mode, state/audit locations, broker verification and version, model, approval boundary, and supported methods.
+
+## Permission modes
+
+### Safe mode (default)
+
+Safe mode is intentionally list-only. Targeted requests are rejected and audited before a Codex worker starts.
+
+### Full-permissions mode
+
+This broadly authorizes targeted official Computer Use operations. It does **not** bypass official OpenAI approvals, sensitive-action prompts, macOS privacy controls, signing checks, focus monitoring, locks, call budgets, timeout cleanup, or audit logging.
+
+Enable it only with explicit acknowledgement:
+
+```bash
+codex-computer-use-mcp --configure full-permissions --acknowledge-full-permissions
+```
+
+Return to safe mode:
+
+```bash
+codex-computer-use-mcp --configure safe
+```
+
+State defaults to `~/.codex-computer-use-mcp`. Override it with `CODEX_COMPUTER_USE_HOME`. Configuration is mode `0600` and audited; an audit failure rolls a mode change back.
+
+## MCP client configuration
+
+### Pi native adapter
+
+```bash
+pi install npm:codex-computer-use-mcp@0.1.0
+```
+
+This registers `background_computer_use`, `/background-computer-use-status`, and `/background-computer-use-mode`.
+
+### Pi MCP gateway
+
+Alternatively add this to `~/.pi/agent/mcp.json`. `directTools: false` keeps the capability intentional instead of injecting it into every turn:
+
+```json
+{
+  "mcpServers": {
+    "codex-computer-use": {
+      "command": "npx",
+      "args": ["-y", "codex-computer-use-mcp@0.1.0"],
+      "lifecycle": "lazy",
+      "requestTimeoutMs": 360000,
+      "directTools": false
+    }
+  }
+}
+```
+
+See [`integrations/pi/`](integrations/pi/). Do not load both Pi adapters under the same tool name.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "codex-computer-use": {
+      "command": "npx",
+      "args": ["-y", "codex-computer-use-mcp@0.1.0"]
+    }
+  }
+}
+```
+
+For a source checkout, replace `npx` and its arguments with `node` and the absolute path to `dist/mcp-server.js`.
+
+## How it works
+
+```text
+MCP client
+  → this local server
+  → ChatGPT.app's signed app-bundled Codex CLI
+  → signed SkyComputerUseClient
+  → official Computer Use service
+  → target macOS app
+```
+
+The nested Codex turn is pinned to `gpt-5.6-sol`; reasoning is `low` for list, `high` for inspect/Dictionary, and `xhigh` for act. It receives a mode-specific tool allowlist, runs with shell/web/remote plugins disabled, and emits a constrained result schema. Streamed events are checked against the requested target, method set, argument constraints, and call budget. These checks are detection and fail-closed completion criteria, not pre-dispatch mediation.
+
+Target apps are background-launched with `open -g`. The server samples frontmost state and consumes global focus notifications. If the target becomes frontmost, completion fails. Unrelated user focus changes are recorded but do not invalidate the operation.
+
+## Usage, privacy, and audits
+
+Each operation starts a separate Codex turn and consumes separate Codex plan/API usage. Results report token usage.
+
+Audits include timestamps, operation/mode, canonical or hashed app identity, byte counts, outcome, methods, usage, and cleanup/focus results. They do **not** include task text, typed content, screenshots, app-state payloads, or model output. Policy-rejected requests are also audited once a secure state directory is available.
+
+## Known limitations
+
+- The integration targets fixed bundle paths inside the ChatGPT macOS app.
+- App updates may change bundled paths, CLI flags, plugin schemas, or signing layout.
+- First-party approvals may need completion in an official interactive OpenAI session.
+- Browser-host Computer Use is not exposed; this project targets native macOS apps.
+- In full-permissions mode, a target/method/focus/cleanup failure is detected after streamed events; mutations may already have occurred. Inspect and restore manually before retrying.
+- Secure config-path failures may prevent audit creation because the server refuses to write through an untrusted path.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm test
+npm run build
+```
+
+Runtime dependencies are exact-pinned and the published graph is bound by `npm-shrinkwrap.json`.
+
+See [`PROOF.md`](PROOF.md), [`SECURITY.md`](SECURITY.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Do not open a public issue for a vulnerability that could weaken code-signing checks, safe-mode dispatch restrictions, approval boundaries, focus guarantees, audit integrity, or cleanup behavior.
+
+Use GitHub's private vulnerability reporting. Include affected versions, the smallest non-sensitive reproduction, expected versus observed behavior, and whether app state changed or cleanup was unverified.
+
+Never include credentials, tokens, private/customer content, sensitive screenshots, raw app-state payloads, or private audit files.
+
+## Authorization model
+
+The signed official client authenticates its parent. An unsigned wrapper cannot synchronously proxy each Computer Use call without breaking that official sender-authentication chain. Streamed target, method, argument, call-budget, focus, and cleanup checks therefore occur after dispatch.
+
+For that reason:
+
+- safe mode is list-only and rejects targeted work before starting Codex;
+- full-permissions mode is broad wrapper authorization, not a preventive per-app sandbox;
+- post-dispatch validation can fail completion and surface cleanup risk, but cannot undo a mutation;
+- official OpenAI app approvals, sensitive-action prompts, and macOS privacy controls remain authoritative.
+
+## Security invariants
+
+1. Only the fixed OpenAI app-bundled Codex and Computer Use client paths may broker a run.
+2. Both binaries must pass strict code-signing verification and OpenAI Team ID checks.
+3. First-party OpenAI and macOS approvals are never self-accepted.
+4. Safe mode dispatches only `list_apps`; every targeted mode fails before worker launch.
+5. Full-permissions mode requires explicit acknowledgement and never claims preventive target isolation.
+6. The target app must not become frontmost; watcher health, queued events, in-flight samples, and final state are checked.
+7. Streamed calls must match the mode allowlist, requested target aliases, argument constraints, and call budget before completion is trusted.
+8. Same-app work remains kernel-excluded.
+9. Timeout and cancellation terminate the full worker process group and retain available partial metadata.
+10. Audits remain private and content-safe; policy rejections are audited, and audit failure is fatal once a secure state path exists.
+11. Runtime dependencies are exact-pinned and published with `npm-shrinkwrap.json`.
+
+## Supported versions
+
+Only the latest release is supported. Compatibility is evaluated against current ChatGPT macOS releases rather than guaranteed indefinitely.

package/dist/audit.d.ts

@@ -0,0 +1,25 @@
+export interface AuditRecord {
+    timestamp: string;
+    runId: string;
+    operation: string;
+    permissionMode: "safe" | "full-permissions";
+    app: string | null;
+    mutating: boolean;
+    cleanupRequested: boolean;
+    userConfirmed: boolean;
+    authorization: "none" | "full_permissions_config";
+    inputBytes: number;
+    outcome: string;
+    durationMs: number;
+    model: string;
+    usage: {
+        input: number;
+        cachedInput: number;
+        output: number;
+    };
+    computerUseCalls: number;
+    computerUseMethods: string[];
+    backgroundPreserved: boolean | null;
+    cleanupVerified: boolean | null;
+}
+export declare function appendAudit(stateDir: string, record: AuditRecord, fileName?: string): Promise<string>;

package/dist/audit.js

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import path from "node:path";
+async function ensurePrivateDirectory(directory) {
+    try {
+        const info = await lstat(directory);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error("Audit state path must be a non-symlink directory");
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error("Audit state path must be a non-symlink directory");
+    }
+    await chmod(directory, 0o700);
+}
+export async function appendAudit(stateDir, record, fileName = "background-computer-use.jsonl") {
+    if (path.basename(fileName) !== fileName)
+        throw new Error("Audit filename must not contain a path");
+    await ensurePrivateDirectory(stateDir);
+    const auditDir = path.join(stateDir, "audit");
+    await ensurePrivateDirectory(auditDir);
+    const auditPath = path.join(auditDir, fileName);
+    const flags = constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
+    const handle = await open(auditPath, flags, 0o600);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error("Audit target must be a regular file");
+        await handle.chmod(0o600);
+        await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return auditPath;
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,IAAI,MAAM,WAAW,CAAC;AAuB7B,KAAK,UAAU,sBAAsB,CAAC,SAAiB;IACtD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACvH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACrB,IAAI,KAAK,EAAE,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC1C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACvH,CAAC;IACD,MAAM,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,QAAgB,EAChB,MAAmB,EACnB,QAAQ,GAAG,+BAA+B;IAE1C,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACpG,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC;IACjG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAC3E,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9D,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+import type { PermissionMode } from "./policy.ts";
+export interface ExtensionConfig {
+    version: 1;
+    permissionMode: PermissionMode;
+}
+export declare const DEFAULT_CONFIG: ExtensionConfig;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function configPath(stateDir: string): string;
+export declare function loadConfig(stateDir: string): Promise<ExtensionConfig>;
+export declare function saveConfig(stateDir: string, config: ExtensionConfig): Promise<string>;

package/dist/config.js

@@ -0,0 +1,105 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_CONFIG = { version: 1, permissionMode: "safe" };
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export function configPath(stateDir) {
+    return path.join(stateDir, "config.json");
+}
+function parseConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ConfigError("Computer Use config must be an object");
+    const record = value;
+    if (Object.keys(record).some((key) => !["version", "permissionMode"].includes(key))) {
+        throw new ConfigError("Computer Use config contains unknown keys");
+    }
+    if (record.version !== 1)
+        throw new ConfigError("Unsupported Computer Use config version");
+    if (record.permissionMode !== "safe" && record.permissionMode !== "full-permissions") {
+        throw new ConfigError("permissionMode must be safe or full-permissions");
+    }
+    return { version: 1, permissionMode: record.permissionMode };
+}
+async function inspectStateDirectory(stateDir, create) {
+    try {
+        const info = await lstat(stateDir);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new ConfigError("Computer Use state must be a non-symlink directory");
+        if ((info.mode & 0o022) !== 0)
+            throw new ConfigError("Computer Use state directory must not be group/world writable");
+        return true;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+        if (!create)
+            return false;
+        await mkdir(stateDir, { recursive: true, mode: 0o700 });
+        const info = await lstat(stateDir);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new ConfigError("Computer Use state must be a non-symlink directory");
+        await chmod(stateDir, 0o700);
+        return true;
+    }
+}
+export async function loadConfig(stateDir) {
+    if (!(await inspectStateDirectory(stateDir, false)))
+        return { ...DEFAULT_CONFIG };
+    const file = configPath(stateDir);
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new ConfigError("Computer Use config must be a regular non-symlink file");
+        if ((info.mode & 0o777) !== 0o600)
+            throw new ConfigError("Computer Use config must have mode 0600");
+        return parseConfig(JSON.parse(await handle.readFile("utf8")));
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return { ...DEFAULT_CONFIG };
+        if (error instanceof ConfigError)
+            throw error;
+        throw new ConfigError("Could not read the Computer Use config");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export async function saveConfig(stateDir, config) {
+    const validated = parseConfig(config);
+    await inspectStateDirectory(stateDir, true);
+    await chmod(stateDir, 0o700);
+    const destination = configPath(stateDir);
+    const temporary = path.join(stateDir, `.config.${process.pid}.${Date.now()}.tmp`);
+    let handle;
+    try {
+        const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+        handle = await open(temporary, flags, 0o600);
+        await handle.chmod(0o600);
+        await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, destination);
+        const directory = await open(stateDir, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        return destination;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/lock.d.ts

@@ -0,0 +1,16 @@
+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 acquireAppLock(stateDir: string, app: string, runId: string, _staleAfterMs?: number): Promise<AppLock>;