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

package/src/codex/install.ts

@@ -0,0 +1,122 @@
+// Locate the Codex install this plugin drives.
+//
+// Nothing here bundles or downloads anything: the `codex` CLI, the shared
+// "Codex Computer Use" app, and the Chrome plugin's bundled browser client are
+// all installed and licensed through the user's own Codex install. This module
+// only READS what is already on disk and reports whether each surface can run.
+
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+const isExecutable = (file: string): boolean => {
+  try {
+    accessSync(file, constants.X_OK);
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+const isReadable = (file: string): boolean => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+export const resolveCodexHome = (explicit?: string): string =>
+  explicit ?? process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
+
+/** The `codex` CLI the bridge spawns. PATH first, then the common install
+ *  locations for launch contexts that do not inherit the user's shell PATH. */
+export const resolveCodexCli = (explicit?: string): string | undefined => {
+  if (explicit !== undefined) return isExecutable(explicit) ? explicit : undefined;
+  const dirs = [
+    ...(process.env["PATH"] ?? "").split(delimiter),
+    join(homedir(), ".local", "bin"),
+    join(homedir(), ".bun", "bin"),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+  ];
+  for (const dir of dirs) {
+    if (dir.length === 0) continue;
+    const candidate = join(dir, "codex");
+    if (isExecutable(candidate)) return candidate;
+  }
+  return undefined;
+};
+
+/** The shared Codex Computer Use app: the install marker for Computer Use. */
+const computerUseClientPath = (codexHome: string): string =>
+  join(
+    codexHome,
+    "computer-use",
+    "Codex Computer Use.app",
+    "Contents",
+    "SharedSupport",
+    "SkyComputerUseClient.app",
+    "Contents",
+    "MacOS",
+    "SkyComputerUseClient",
+  );
+
+/** The Chrome plugin's bundled browser client, reached through the `latest`
+ *  symlink Codex maintains beside the versioned directories, so a plugin
+ *  update does not strand the stored path. */
+export const chromeClientPath = (codexHome: string): string =>
+  join(
+    codexHome,
+    "plugins",
+    "cache",
+    "openai-bundled",
+    "chrome",
+    "latest",
+    "scripts",
+    "browser-client.mjs",
+  );
+
+export interface CodexInstall {
+  /** Resolved `codex` CLI, or undefined when Codex is not installed. */
+  readonly cli?: string;
+  readonly codexHome: string;
+  readonly computerUse: boolean;
+  readonly chrome: boolean;
+  /** Absolute path the Chrome surface imports; always present, may not exist. */
+  readonly chromeModulePath: string;
+}
+
+export const detectInstall = (options?: {
+  readonly codexHome?: string;
+  readonly codexCli?: string;
+}): CodexInstall => {
+  const codexHome = resolveCodexHome(options?.codexHome);
+  const cli = resolveCodexCli(options?.codexCli);
+  const chromeModulePath = chromeClientPath(codexHome);
+  return {
+    ...(cli === undefined ? {} : { cli }),
+    codexHome,
+    computerUse: isExecutable(computerUseClientPath(codexHome)),
+    chrome: isReadable(chromeModulePath),
+    chromeModulePath,
+  };
+};
+
+/** The message shown when a surface cannot run yet. Written as ordered steps
+ *  because the person reading it has just been told they cannot proceed. */
+export const setupHint = (missing: "computer-use" | "chrome" | "codex"): string => {
+  if (missing === "codex") {
+    return "Codex is not installed. Install the Codex app from openai.com/codex and sign in.";
+  }
+  if (missing === "chrome") {
+    return [
+      "The Codex Chrome plugin is not installed.",
+      "In Codex, open Settings → Computer use and install the ChatGPT browser extension, then use Chrome once inside Codex so it can reach your browser.",
+    ].join(" ");
+  }
+  return [
+    "The Codex Computer Use app is not installed.",
+    "Install the Codex app from openai.com/codex, open Computer Use once inside Codex, and grant the macOS permissions it asks for.",
+  ].join(" ");
+};

package/src/codex/permissions.ts

@@ -0,0 +1,80 @@
+// Adapted from Executor (MIT, Copyright (c) 2026 Rhys Sullivan). See NOTICE.
+// macOS permission failures for the Codex surfaces.
+//
+// These tools drive the real machine, so macOS gates them behind TCC. The
+// plugin reports a bare Apple Event error code, which reaches a caller as an
+// opaque "Unknown error". Classifying it here turns the most common first-run
+// failure into something a person can act on: which System Settings pane, and
+// which exact entry, to enable.
+
+const settingsUrl = (pane: string): string =>
+  `x-apple.systempreferences:com.apple.preference.security?${pane}`;
+
+export interface CodexPermission {
+  readonly id: "automation" | "accessibility" | "screen-recording";
+  readonly label: string;
+  readonly entry: string;
+  readonly why: string;
+  readonly settingsUrl: string;
+}
+
+/**
+ * Automation is per-HOST: macOS attributes the Apple Event to the responsible
+ * process — the app that launched the chain, here OpenCode. Screen Recording
+ * and Accessibility attach to the Codex Computer Use app and are shared across
+ * every host, so granting them once in Codex covers this plugin too.
+ */
+export const CODEX_PERMISSIONS: Readonly<Record<string, readonly CodexPermission[]>> = {
+  "computer_use": [
+    {
+      id: "screen-recording",
+      label: "Screen Recording",
+      entry: "Codex Computer Use",
+      why: "so it can see the app it is operating",
+      settingsUrl: settingsUrl("Privacy_ScreenCapture"),
+    },
+    {
+      id: "accessibility",
+      label: "Accessibility",
+      entry: "Codex Computer Use",
+      why: "so it can click, type, and scroll",
+      settingsUrl: settingsUrl("Privacy_Accessibility"),
+    },
+  ],
+  "browser": [
+    {
+      id: "automation",
+      label: "Automation",
+      entry: "OpenCode → Google Chrome",
+      why: "so it can drive your browser",
+      settingsUrl: settingsUrl("Privacy_Automation"),
+    },
+  ],
+};
+
+/** Apple Event failures that mean "the user has not allowed this".
+ *  `-1743` is `errAEEventNotPermitted`; `-600`/`-609` are the connection
+ *  errors macOS returns when it refuses to hand the sender a port. */
+const deniedCodePattern = /(?:^|[^0-9-])(-1743|-609|-600)(?![0-9])/;
+
+/** A permission failure recognised in an upstream tool error, or null when
+ *  the error is about something else. Matching is on the numeric code, not on
+ *  wording: the plugin's own text is "Unknown error". */
+export const permissionFailure = (
+  message: string,
+  surface: string | undefined,
+): CodexPermission | null => {
+  if (!deniedCodePattern.test(message)) return null;
+  const permissions = surface === undefined ? [] : (CODEX_PERMISSIONS[surface] ?? []);
+  return permissions.find((p) => p.id === "automation") ?? permissions[0] ?? null;
+};
+
+/** The message a caller sees instead of "Unknown error". It names the block,
+ *  the exact entry to enable, and where, because macOS will not ask again on
+ *  its own after a denial. */
+export const permissionFailureMessage = (permission: CodexPermission): string =>
+  [
+    `macOS blocked this: ${permission.label} access has not been allowed.`,
+    `Open System Settings → Privacy & Security → ${permission.label}, find "${permission.entry}", and turn it on — ${permission.why}.`,
+    "macOS only asks once, so a prompt will not appear again until it is enabled there.",
+  ].join(" ");

package/src/codex/repl.ts

@@ -0,0 +1,50 @@
+// Adapted from Executor (MIT, Copyright (c) 2026 Rhys Sullivan). See NOTICE.
+// Shared helpers for projecting Codex's `node_repl` `js` tool as typed tools.
+//
+// Both surfaces (Computer Use via `@oai/sky`, Chrome via `browser-client.mjs`)
+// work the same way: a call is compiled into one JavaScript program, that
+// program is executed through Codex's `node_repl` server, and it reports a
+// single JSON value back through `nodeRepl.write`. The encoding that puts
+// caller arguments INTO that source text and reads one JSON value OUT is the
+// genuinely shared part, and the part that must be exactly right.
+
+/**
+ * An expression that evaluates to `value` inside the REPL.
+ *
+ * `JSON.parse` of a string, NOT a bare object literal. The two differ in
+ * exactly the way that matters here: `__proto__` as a key sets an object's
+ * PROTOTYPE in a literal, while being an ordinary own key under `JSON.parse`.
+ * Embedding caller arguments as a literal would let a caller move data onto
+ * the prototype chain; parsing keeps arguments data.
+ *
+ * U+2028/U+2029 are legal inside a JSON string but are literal line
+ * terminators in a JS source text, so they are escaped.
+ */
+export const jsString = (value: string): string =>
+  JSON.stringify(value).replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+
+export const jsLiteral = (value: unknown): string =>
+  `JSON.parse(${JSON.stringify(JSON.stringify(value ?? null))
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029")})`;
+
+/**
+ * Wrap a program body so it runs in its own scope and reports one JSON value.
+ *
+ * The scope matters: a REPL session is persistent, so a program that declared
+ * its working variables at top level would redeclare the same `const` on every
+ * call. Everything per-call lives inside the IIFE; only deliberate caches (the
+ * imported runtime) are left on `globalThis`.
+ *
+ * The REPL returns values only through `nodeRepl.write`, and only as text;
+ * `undefined` (every action method) becomes `null` so a caller always gets a
+ * well-formed JSON body rather than an empty string.
+ */
+export const writeJsonResult = (body: readonly string[], expression: string): string =>
+  [
+    "await (async () => {",
+    ...body.map((line) => `  ${line}`),
+    `  const result = ${expression};`,
+    "  nodeRepl.write(JSON.stringify(result ?? null));",
+    "})();",
+  ].join("\n");

package/src/controller.ts

@@ -0,0 +1,86 @@
+// Owns the Codex app-server connection and turns tool calls into results.
+//
+// One connection per plugin instance. `CodexAppServer` serializes calls inside
+// it, so concurrent OpenCode sessions cannot interleave desktop or browser
+// actions. The connection is created lazily on the first tool call and closed
+// when the plugin unloads.
+
+import { CodexAppServer, toolCallError } from "./codex/appserver";
+import { detectInstall, setupHint } from "./codex/install";
+import type { ComputerUseTool } from "./tools/computer-use";
+import { computerUseProgram } from "./tools/computer-use";
+import type { ChromeTool } from "./tools/chrome";
+import { chromeProgram } from "./tools/chrome";
+
+export const COMPUTER_USE_NAMESPACE = "computer_use";
+export const CHROME_NAMESPACE = "chrome";
+
+export interface PluginSettings {
+  readonly codexHome?: string;
+  readonly codexCli?: string;
+  readonly computerUse: boolean;
+  readonly chrome: boolean;
+}
+
+export class Controller {
+  readonly #settings: PluginSettings;
+  #server: CodexAppServer | undefined;
+
+  constructor(settings: PluginSettings) {
+    this.#settings = settings;
+  }
+
+  #bridge(): CodexAppServer {
+    this.#server ??= new CodexAppServer({
+      codexCli: this.#settings.codexCli ?? "codex",
+      ...(this.#settings.codexHome === undefined ? {} : { codexHome: this.#settings.codexHome }),
+      onLog: (message) => console.log(`[codex-control] ${message}`),
+    });
+    return this.#server;
+  }
+
+  async callComputerUse(tool: ComputerUseTool, input: unknown): Promise<string> {
+    const install = detectInstall(this.#settings);
+    if (install.cli === undefined) throw new Error(setupHint("codex"));
+    if (!install.computerUse) throw new Error(setupHint("computer-use"));
+    const result = await this.#bridge().callJs({
+      code: computerUseProgram(tool, input),
+      title: `Computer Use: ${tool.name}`,
+    });
+    const error = toolCallError(result, COMPUTER_USE_NAMESPACE);
+    if (error !== undefined) throw error;
+    return result.text;
+  }
+
+  async callChrome(tool: ChromeTool, input: unknown): Promise<string> {
+    const install = detectInstall(this.#settings);
+    if (install.cli === undefined) throw new Error(setupHint("codex"));
+    if (!install.chrome) throw new Error(setupHint("chrome"));
+    const result = await this.#bridge().callJs({
+      code: chromeProgram(tool, input, install.chromeModulePath),
+      title: `Chrome: ${tool.name}`,
+      // Real navigation routinely outruns the REPL's 30s default; a page load
+      // plus its DOM pass needs the longer budget.
+      timeoutMs: 55_000,
+    });
+    const error = toolCallError(result, CHROME_NAMESPACE);
+    if (error !== undefined) throw error;
+    return result.text;
+  }
+
+  async close(): Promise<void> {
+    const server = this.#server;
+    this.#server = undefined;
+    await server?.close();
+  }
+}
+
+export const readSettings = (options: unknown): PluginSettings => {
+  const o = (options ?? {}) as Record<string, unknown>;
+  return {
+    ...(typeof o["codexHome"] === "string" ? { codexHome: o["codexHome"] } : {}),
+    ...(typeof o["codexCli"] === "string" ? { codexCli: o["codexCli"] } : {}),
+    computerUse: o["computerUse"] !== false,
+    chrome: o["chrome"] !== false,
+  };
+};

package/src/plugin.ts

@@ -0,0 +1,90 @@
+// OpenCode plugin: Codex Computer Use and Chrome as native tools.
+//
+// Codex's Computer Use and Chrome plugins are driven entirely through
+// `codex app-server` (see `codex/appserver.ts`). This plugin owns one
+// app-server connection, projects each surface as typed tools, and lets
+// OpenCode's permission layer be the consent boundary: every tool carries a
+// `permission` action, and Codex's own approval prompts are answered
+// automatically once the user has allowed the call.
+//
+// Nothing is spawned until the first tool call, and each surface reports a
+// clear setup path when Codex or that surface is not installed.
+
+import type { Plugin as PluginNamespace } from "@opencode/plugin";
+
+import { resolveCodexHome } from "./codex/install";
+import {
+  CHROME_NAMESPACE,
+  COMPUTER_USE_NAMESPACE,
+  Controller,
+  readSettings,
+} from "./controller";
+import { CHROME_TOOLS } from "./tools/chrome";
+import { COMPUTER_USE_TOOLS } from "./tools/computer-use";
+
+type PluginContext = PluginNamespace.Context;
+
+// A plain object rather than `Plugin.define`: the helper is an identity
+// function, and importing it only for that would pull OpenCode's full server
+// dependency graph into every install. The `satisfies` keeps the type
+// contract without a runtime dependency.
+const plugin = {
+  id: "codex-control",
+  async setup(ctx: PluginContext) {
+    const settings = readSettings(ctx.options);
+    const controller = new Controller(settings);
+
+    await ctx.tool.transform((editor) => {
+      if (settings.computerUse) {
+        editor.namespace({
+          name: COMPUTER_USE_NAMESPACE,
+          description:
+            "Control macOS desktop apps through Codex Computer Use: read the accessibility tree and screenshots, click, type, and scroll.",
+        });
+        for (const tool of COMPUTER_USE_TOOLS) {
+          editor.add({
+            name: tool.name,
+            description: tool.description,
+            input: tool.inputSchema,
+            options: {
+              namespace: COMPUTER_USE_NAMESPACE,
+              permission: COMPUTER_USE_NAMESPACE,
+            },
+            execute: async (input: unknown) => ({
+              content: await controller.callComputerUse(tool, input),
+            }),
+          });
+        }
+      }
+
+      if (settings.chrome) {
+        editor.namespace({
+          name: CHROME_NAMESPACE,
+          description:
+            "Control the real Chrome browser through Codex: open tabs, navigate, read pages, click, and type, using the user's logged-in sessions.",
+        });
+        for (const tool of CHROME_TOOLS) {
+          editor.add({
+            name: tool.name,
+            description: tool.description,
+            input: tool.inputSchema,
+            options: { namespace: CHROME_NAMESPACE, permission: CHROME_NAMESPACE },
+            execute: async (input: unknown) => ({
+              content: await controller.callChrome(tool, input),
+            }),
+          });
+        }
+      }
+    });
+
+    console.log(
+      `[codex-control] loaded (codex home: ${resolveCodexHome(settings.codexHome)}, computer use: ${settings.computerUse}, chrome: ${settings.chrome})`,
+    );
+
+    return async () => {
+      await controller.close();
+    };
+  },
+} satisfies PluginNamespace.Plugin;
+
+export default plugin;