opencode-codex-control 0.0.0-tegami-trusted-publish-setup → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saatvik Arya
+
+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/LICENSE-EXECUTOR

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rhys Sullivan
+
+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/NOTICE

@@ -0,0 +1,24 @@
+# NOTICE
+
+This project is licensed under the MIT License (see `LICENSE`). It includes
+code adapted from a third party, reproduced here with its license.
+
+## Executor
+
+Portions of this project are derived from **Executor**
+(<https://github.com/RhysSullivan/executor>), which is licensed under the MIT
+License, Copyright (c) 2026 Rhys Sullivan. The full license text is in
+`LICENSE-EXECUTOR`.
+
+Specifically, these files adapt Executor's MCP plugin SDK
+(`packages/plugins/mcp/src/sdk/`):
+
+| This project                    | Derived from Executor            |
+| ------------------------------- | -------------------------------- |
+| `src/tools/computer-use.ts`     | `codex-sky-tools.ts`             |
+| `src/tools/chrome.ts`           | `codex-browser-tools.ts`         |
+| `src/codex/repl.ts`             | `codex-repl.ts`                  |
+| `src/codex/permissions.ts`      | `codex-permissions.ts`           |
+
+The Chrome surface was retargeted to the current Chrome plugin API (the `ax`
+and `playwright` namespaces) rather than Executor's original `dom_cua` surface.

package/README.md

@@ -1,6 +1,132 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# opencode-codex-control
+
+An [OpenCode](https://opencode.ai) V2 plugin that exposes **Codex Computer Use**
+and **Codex Chrome** as native tools, by bridging Codex's `app-server` JSON-RPC.
+
+> [!IMPORTANT]
+> Unofficial. Not affiliated with OpenAI, the Codex team, or the OpenCode team.
+> It drives an existing Codex install on your machine and requires the same
+> plugins and macOS permissions Codex itself needs. Codex Computer Use is
+> macOS-only; Chrome control depends on Codex's bundled Chrome plugin.
+
+## Why a plugin and not an MCP server
+
+Codex's Computer Use and Chrome plugins are not MCP servers. Computer Use ships
+as a `node-repl` content variant, Chrome ships no server at all, and the
+Computer Use service only honours calls from a Codex-host session. The working
+path is `codex app-server` calling the bundled `node_repl` server's `js` tool,
+which imports `@oai/sky` or Chrome's `browser-client.mjs`.
+
+This plugin owns one `codex app-server` connection, compiles each typed tool
+call into the JavaScript program that performs it, and registers the results
+with OpenCode's tool registry. It has no runtime dependencies and spawns
+nothing until the first tool call.
+
+## Tools
+
+- `computer_use.*` — macOS desktop control: `list_apps`, `get_app_state`,
+  `click`, `type_text`, `press_key`, `paste`, `scroll`, `drag`, `select_text`,
+  `set_value`, `perform_secondary_action`.
+- `chrome.*` — the real Chrome: `list_tabs`, `new_tab`, `navigate`, `page_info`,
+  `read_page`, `read_dom`, `click`, `type_text`, `press_key`, `scroll`,
+  `set_value`, `select_text`, `perform_secondary_action`, `drag`,
+  `find_elements`, `go_back`, `go_forward`, `reload`, `close_tab`,
+  `export_content`.
+
+Interaction uses the accessibility (`ax`) API and `playwright` for reads; the
+`dom_cua`/`cua` namespaces are filtered out on Chrome's extension backend.
+
+## Requirements
+
+- OpenCode V2 (`opencode2`).
+- The `codex` CLI on `PATH` (or set `codexCli`).
+- Computer Use: the shared "Codex Computer Use" app under `$CODEX_HOME`.
+- Chrome: Codex's bundled Chrome plugin and the ChatGPT browser extension, used
+  once inside Codex.
+
+Each tool reports an ordered setup path when its surface is not installed.
+
+## Install
+
+From npm, in `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-codex-control"]
+}
+```
+
+From a local checkout (useful while developing):
+
+```jsonc
+{
+  "plugins": ["/absolute/path/to/opencode-codex-control"]
+}
+```
+
+## Options
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-codex-control",
+      "options": {
+        "codexHome": "~/.codex",
+        "codexCli": "codex",
+        "computerUse": true,
+        "chrome": true
+      }
+    }
+  ]
+}
+```
+
+## Permissions and approvals
+
+Every tool carries `options.permission` (`computer_use` or `chrome`), so the
+OpenCode permission layer is the consent boundary. To require a prompt for
+either surface:
+
+```jsonc
+{
+  "permissions": [{ "action": "chrome", "resource": "*", "effect": "ask" }]
+}
+```
+
+Codex's own approval prompts (for example Chrome's per-site access) arrive as
+`mcpServer/elicitation/request`. Because the OpenCode tool call has already been
+allowed, the plugin answers them automatically and logs the origin as
+`[codex-control] Codex approval accept (…)`. Treat this as coarse consent for
+now; finer-grained grants are a follow-up.
+
+## Development
+
+```sh
+bun install
+bun run typecheck
+bun test
+```
+
+`bun run smoke` exercises the real bridge end to end (it needs a working Codex
+install and will launch apps or open browser tabs), so it is not part of CI.
+
+## Layout
+
+```
+index.ts                    # entrypoint the OpenCode loader imports
+src/plugin.ts               # plugin definition + tool registration
+src/controller.ts           # connection lifecycle; call -> result
+src/codex/appserver.ts      # codex app-server child + JSON-RPC client
+src/codex/install.ts        # CLI/install discovery
+src/codex/permissions.ts    # macOS TCC denial -> setup instructions
+src/codex/repl.ts           # safe argument encoding + JSON result wrapper
+src/tools/computer-use.ts
+src/tools/chrome.ts
+```
+
+## License and attribution
+
+MIT. Portions are adapted from [Executor](https://github.com/RhysSullivan/executor)
+(MIT, Copyright (c) 2026 Rhys Sullivan) — see `NOTICE` and `LICENSE-EXECUTOR`.

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/plugin";

package/package.json

@@ -1,5 +1,57 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-codex-control",
-  "version": "0.0.0-tegami-trusted-publish-setup",
-  "description": "Placeholder published by Tegami for npm trusted publishing setup."
+  "version": "0.1.0",
+  "description": "OpenCode plugin that exposes Codex Computer Use and Chrome as native tools",
+  "type": "module",
+  "license": "MIT",
+  "author": "Saatvik Arya",
+  "homepage": "https://github.com/aryasaatvik/opencode-codex-control#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aryasaatvik/opencode-codex-control.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aryasaatvik/opencode-codex-control/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "codex",
+    "computer-use",
+    "chrome",
+    "desktop-automation",
+    "browser-automation"
+  ],
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "LICENSE-EXECUTOR",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "smoke": "bun scripts/smoke.ts",
+    "tegami": "bun scripts/tegami.mts",
+    "version:packages": "bun run tegami version",
+    "release:check": "bun run typecheck && bun test",
+    "release": "bun run release:check && bun run tegami publish"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "0.0.0-beta-19425",
+    "@types/bun": "1.3.9",
+    "@types/node": "24.12.2",
+    "tegami": "1.4.0",
+    "typescript": "5.8.2"
+  }
 }

package/src/codex/appserver.ts

@@ -0,0 +1,415 @@
+// Codex app-server bridge.
+//
+// Computer Use and Chrome are not MCP servers a client can spawn. Since the
+// 2026-08-28 Codex update the Computer Use service only honours calls from a
+// session registered by a Codex host process, and Chrome ships no server at
+// all. The supported path is `codex app-server` — Codex's own JSON-RPC front
+// end — whose `mcpServer/tool/call` invokes a plugin tool directly with no
+// model turn and no inference.
+//
+// Both surfaces are driven through the bundled `node_repl` server's `js`
+// tool: the program compiled by `tools/computer-use`/`tools/chrome` runs
+// inside it, imports `@oai/sky` or the Chrome browser client, and writes one
+// JSON value back. Chrome additionally refuses to run without Codex turn
+// metadata, which this bridge supplies because it starts no turns.
+//
+// The wire is newline-delimited JSON managed here. It is NOT MCP-shaped
+// (`_meta: null`, its own notification families), so it cannot go through a
+// generic MCP stdio transport.
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+import { permissionFailure, permissionFailureMessage } from "./permissions";
+
+export interface ElicitationRequest {
+  readonly message: string;
+  readonly mode?: string;
+  readonly url?: string;
+  readonly meta: Record<string, unknown>;
+  readonly requestedSchema?: unknown;
+}
+
+export type ElicitationAction = "accept" | "decline" | "cancel";
+
+export interface CodexAppServerConfig {
+  /** The `codex` CLI to spawn. */
+  readonly codexCli: string;
+  /** Value for the child's `CODEX_HOME`; omitted leaves the inherited one. */
+  readonly codexHome?: string;
+  /**
+   * How to answer a plugin approval prompt. Defaults to accepting: the
+   * OpenCode tool call the user already allowed is the consent boundary, so
+   * Codex's own prompt is redundant here.
+   */
+  readonly onElicitation?: (
+    request: ElicitationRequest,
+  ) => ElicitationAction | Promise<ElicitationAction>;
+  /** Diagnostics: startup transitions and other notifications. */
+  readonly onLog?: (message: string) => void;
+}
+
+export interface ToolCallResult {
+  /** The joined text content of the tool call. */
+  readonly text: string;
+  readonly isError: boolean;
+  readonly structuredContent?: unknown;
+  readonly meta?: unknown;
+}
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+interface RpcMessage {
+  id?: number | string;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: unknown;
+}
+
+const INITIALIZE_TIMEOUT_MS = 30_000;
+const DEFAULT_CALL_TIMEOUT_MS = 60_000;
+
+/** `mcpServer/startupStatus/updated` — Codex reports every server it runs. */
+const STARTUP_STATUS_METHOD = "mcpServer/startupStatus/updated";
+
+export class CodexAppServer {
+  readonly #config: CodexAppServerConfig;
+  #child: ReturnType<typeof spawn> | undefined;
+  #stdoutBuffer = "";
+  #stderrTail = "";
+  #nextId = 1;
+  #threadId: string | undefined;
+  #starting: Promise<void> | undefined;
+  #ready = false;
+  #closed = false;
+  #queue: Promise<unknown> = Promise.resolve();
+  readonly #pending = new Map<number, Pending>();
+
+  constructor(config: CodexAppServerConfig) {
+    this.#config = config;
+  }
+
+  get threadId(): string | undefined {
+    return this.#threadId;
+  }
+
+  /** Start and hand-shake on first use; a warm instance is a no-op. */
+  async ensureReady(): Promise<void> {
+    if (this.#closed) throw new Error("The Codex app-server connection has been closed.");
+    if (this.#ready) return;
+    this.#starting ??= this.#handshake();
+    await this.#starting;
+  }
+
+  async #handshake(): Promise<void> {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(this.#config.codexCli, ["app-server"], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          ...(this.#config.codexHome === undefined ? {} : { CODEX_HOME: this.#config.codexHome }),
+        },
+      });
+    } catch (error) {
+      throw new Error(
+        `Could not start the Codex app-server with "${this.#config.codexCli}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    this.#child = child;
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => this.#onStdout(chunk));
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      // Keep a short tail so a startup failure can explain itself.
+      this.#stderrTail = (this.#stderrTail + chunk).slice(-2000);
+    });
+    child.stdin?.on("error", () => undefined);
+    child.stdout?.on("error", () => undefined);
+    child.on("error", (error: Error) => this.#failAll(error));
+    child.on("exit", () => this.#failAll(new Error("Codex app-server exited.")));
+
+    await this.#request(
+      "initialize",
+      { clientInfo: { name: "opencode", title: "OpenCode", version: "0.1.0" } },
+      INITIALIZE_TIMEOUT_MS,
+    );
+    this.#notify("initialized", {});
+    const started = (await this.#request(
+      "thread/start",
+      // `approvalPolicy: "on-request"` is load-bearing: on a thread whose
+      // policy declines MCP elicitations, Codex answers every plugin prompt
+      // itself and never forwards it, surfacing as an unexplained denial on
+      // any tool that asks.
+      { sessionStartSource: "startup", approvalPolicy: "on-request" },
+      INITIALIZE_TIMEOUT_MS,
+    )) as { thread?: { id?: string } } | undefined;
+    const threadId = started?.thread?.id;
+    if (typeof threadId !== "string") {
+      throw new Error("Codex app-server returned no thread id from thread/start.");
+    }
+    this.#threadId = threadId;
+    this.#ready = true;
+  }
+
+  /** Call one tool on one Codex MCP server. */
+  async callTool(
+    server: string,
+    tool: string,
+    args: unknown,
+    options?: { readonly timeoutMs?: number },
+  ): Promise<ToolCallResult> {
+    await this.ensureReady();
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    return this.#serialize(async () => {
+      const reply = await this.#request(
+        "mcpServer/tool/call",
+        {
+          threadId: this.#threadId,
+          server,
+          tool,
+          arguments: args ?? {},
+          // Codex stamps a REPL call with the turn that issued it, and the
+          // Chrome client refuses to run without it. This bridge starts no
+          // turns, so it supplies the same shape: the pooled thread is the
+          // session, each call is its own turn.
+          _meta: {
+            "x-codex-turn-metadata": {
+              session_id: this.#threadId,
+              turn_id: randomUUID(),
+            },
+          },
+        },
+        timeoutMs,
+      );
+      return normalizeToolCall(reply);
+    });
+  }
+
+  /** Run one JavaScript program in Codex's `node_repl`. */
+  async callJs(program: {
+    readonly code: string;
+    readonly title: string;
+    readonly timeoutMs?: number;
+  }): Promise<ToolCallResult> {
+    const timeoutMs = program.timeoutMs ?? 30_000;
+    return this.callTool(
+      "node_repl",
+      "js",
+      {
+        code: program.code,
+        title: program.title,
+        ...(program.timeoutMs === undefined ? {} : { timeout_ms: program.timeoutMs }),
+      },
+      // Leave headroom under the caller so a slow page fails as a page error
+      // rather than an abandoned request.
+      { timeoutMs: timeoutMs + 20_000 },
+    );
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true;
+    const child = this.#child;
+    this.#child = undefined;
+    if (child === undefined) return;
+    child.stdin?.end();
+    child.kill("SIGTERM");
+    const escalate = setTimeout(() => child.kill("SIGKILL"), 3000);
+    escalate.unref?.();
+  }
+
+  /** Serialize calls: one real desktop and one real browser can only be
+   *  driven by one action at a time, however many OpenCode sessions exist. */
+  #serialize<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this.#queue.then(fn, fn);
+    this.#queue = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  }
+
+  #request(method: string, params: unknown, timeoutMs: number): Promise<unknown> {
+    const child = this.#child;
+    if (child === undefined || this.#closed) {
+      return Promise.reject(new Error("Codex app-server is not running."));
+    }
+    const id = this.#nextId++;
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        const tail = this.#stderrTail.trim();
+        reject(
+          new Error(
+            `Codex app-server did not answer ${method} within ${timeoutMs}ms.${
+              tail.length === 0 ? "" : `\n${tail}`
+            }`,
+          ),
+        );
+      }, timeoutMs);
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      this.#send({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  #notify(method: string, params: unknown): void {
+    this.#send({ jsonrpc: "2.0", method, params });
+  }
+
+  #send(message: unknown): void {
+    this.#child?.stdin?.write(`${JSON.stringify(message)}\n`, () => undefined);
+  }
+
+  #onStdout(chunk: string): void {
+    this.#stdoutBuffer += chunk;
+    const lines = this.#stdoutBuffer.split("\n");
+    this.#stdoutBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      let message: RpcMessage;
+      try {
+        message = JSON.parse(trimmed) as RpcMessage;
+      } catch {
+        continue;
+      }
+      this.#dispatch(message);
+    }
+  }
+
+  #dispatch(message: RpcMessage): void {
+    const isResponse =
+      message.method === undefined &&
+      typeof message.id === "number" &&
+      (message.result !== undefined || message.error !== undefined);
+    if (isResponse) {
+      const pending = this.#pending.get(message.id as number);
+      if (pending === undefined) return;
+      this.#pending.delete(message.id as number);
+      if (message.error === undefined) {
+        pending.resolve(message.result);
+      } else {
+        pending.reject(new Error(rpcErrorMessage(message.error)));
+      }
+      return;
+    }
+    if (message.method !== undefined && message.id !== undefined) {
+      void this.#handleServerRequest(message);
+      return;
+    }
+    if (message.method !== undefined) {
+      this.#handleNotification(message.method, message.params);
+    }
+  }
+
+  async #handleServerRequest(message: RpcMessage): Promise<void> {
+    if (message.method === "mcpServer/elicitation/request") {
+      const action = await this.#answerElicitation(message.params);
+      this.#send({ jsonrpc: "2.0", id: message.id, result: { action } });
+      return;
+    }
+    // The bridge starts no turns, so there is nothing else it can answer.
+    this.#send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32601, message: `OpenCode does not handle ${message.method}` },
+    });
+  }
+
+  async #answerElicitation(rawParams: unknown): Promise<ElicitationAction> {
+    const params = (rawParams ?? {}) as Record<string, unknown>;
+    const meta =
+      params["_meta"] !== null && typeof params["_meta"] === "object"
+        ? (params["_meta"] as Record<string, unknown>)
+        : {};
+    const connector =
+      typeof meta["connector_name"] === "string" ? (meta["connector_name"] as string) : undefined;
+    const message =
+      typeof params["message"] === "string"
+        ? (params["message"] as string)
+        : `Approve this ${connector ?? "Codex"} request?`;
+    const request: ElicitationRequest = {
+      message,
+      mode: typeof params["mode"] === "string" ? (params["mode"] as string) : undefined,
+      url: typeof params["url"] === "string" ? (params["url"] as string) : undefined,
+      meta,
+      requestedSchema: params["requestedSchema"],
+    };
+    const decided = await this.#config.onElicitation?.(request);
+    this.#config.onLog?.(
+      `Codex approval ${decided ?? "accept"}${connector === undefined ? "" : ` (${connector})`}: ${message}`,
+    );
+    return decided ?? "accept";
+  }
+
+  #handleNotification(method: string, params: unknown): void {
+    if (method !== STARTUP_STATUS_METHOD) return;
+    const entry = (params ?? {}) as { name?: unknown; status?: unknown };
+    if (typeof entry.name !== "string" || typeof entry.status !== "string") return;
+    this.#config.onLog?.(`Codex MCP server ${entry.name} is ${entry.status}`);
+  }
+
+  #failAll(error: Error): void {
+    this.#ready = false;
+    for (const pending of this.#pending.values()) pending.reject(error);
+    this.#pending.clear();
+  }
+}
+
+const normalizeToolCall = (raw: unknown): ToolCallResult => {
+  const result = (raw ?? {}) as {
+    content?: unknown;
+    structuredContent?: unknown;
+    isError?: unknown;
+    _meta?: unknown;
+  };
+  const content = Array.isArray(result.content) ? result.content : [];
+  const text = content
+    .map((block) => {
+      const b = block as { text?: unknown };
+      return typeof b.text === "string" ? b.text : "";
+    })
+    .filter((value) => value.length > 0)
+    .join("\n");
+  return {
+    text,
+    isError: result.isError === true,
+    ...(result.structuredContent === undefined
+      ? {}
+      : { structuredContent: result.structuredContent }),
+    ...(result._meta === undefined ? {} : { meta: result._meta }),
+  };
+};
+
+const rpcErrorMessage = (error: unknown): string => {
+  const e = (error ?? {}) as { message?: unknown; data?: unknown };
+  const message = typeof e.message === "string" ? e.message : JSON.stringify(error);
+  return typeof e.data === "string" && e.data.length > 0 ? `${message} (${e.data})` : message;
+};
+
+/** Throw an actionable error for a failed tool call, translating macOS
+ *  permission denials into the exact System Settings entry to enable. */
+export const toolCallError = (
+  result: ToolCallResult,
+  surface: string | undefined,
+): Error | undefined => {
+  if (!result.isError) return undefined;
+  const text = result.text.length > 0 ? result.text : "The Codex tool call failed.";
+  const permission = permissionFailure(text, surface);
+  return new Error(permission === null ? text : permissionFailureMessage(permission));
+};