Add Chrome and OpenAI developer docs as Codex plugin presets

Author: RhysSullivan

e2e/local/codex-plugins.test.ts

@@ -34,6 +34,15 @@ import { withLocalServer } from "./local-server";
 const api = composePluginApi([mcpHttpPlugin()] as const);
 
 const FIXTURE = fileURLToPath(new URL("./fixtures/stdio-mcp-server.mjs", import.meta.url));
+const CHROME_CLIENT_RELATIVE = join(
+  "plugins",
+  "cache",
+  "openai-bundled",
+  "chrome",
+  "latest",
+  "scripts",
+  "browser-client.mjs",
+);
 const APP_SERVER_FIXTURE = fileURLToPath(
   new URL("./fixtures/codex-app-server.mjs", import.meta.url),
 );
@@ -67,6 +76,11 @@ const makeCodexHome = (): string => {
     mode: 0o755,
   });
 
+  // Chrome's bundled browser client, behind the `latest` symlink Codex keeps.
+  const chromeClient = join(home, CHROME_CLIENT_RELATIVE);
+  mkdirSync(join(chromeClient, ".."), { recursive: true });
+  writeFileSync(chromeClient, "export const setupBrowserRuntime = async () => ({});\n");
+
   const versionDir = join(home, "plugins", "cache", "personal", "echo-suite", "1.0.2");
   mkdirSync(join(versionDir, ".codex-plugin"), { recursive: true });
   mkdirSync(join(versionDir, "bin"), { recursive: true });
@@ -115,10 +129,12 @@ scenario(
           const { plugins } = yield* client.mcp.listCodexPlugins();
           const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
           expect([...byId.keys()].sort(), "curated + scanned entries are reported").toEqual([
+            "codex-chrome",
             "codex-computer-history",
             "codex-computer-use",
             "codex-echo-suite",
             "codex-messages",
+            "codex-openai-docs",
           ]);
           for (const plugin of plugins) {
             expect(plugin.available, `${plugin.id} is available`).toBe(true);
@@ -136,6 +152,18 @@ scenario(
           expect(messages?.appServer, "curated entries name their Codex server").toEqual({
             server: "messages",
           });
+          // Computer Use and Chrome have no server of their own: both are
+          // projected onto `node_repl`, and Chrome carries the client module
+          // its surface imports, resolved through the `latest` symlink.
+          expect(byId.get("codex-computer-use")?.appServer).toEqual({
+            server: "node_repl",
+            surface: "sky",
+          });
+          expect(byId.get("codex-chrome")?.appServer).toEqual({
+            server: "node_repl",
+            surface: "browser",
+            modulePath: join(codexHome, CHROME_CLIENT_RELATIVE),
+          });
 
           // Add two entries exactly as the add-form's Codex-plugins card does:
           // the reported recipe, verbatim.

packages/plugins/mcp/src/api/group.ts

@@ -66,7 +66,11 @@ const AddStdioServerPayload = Schema.Struct({
   /** Reach the server through the Codex app-server bridge: the command spawns
    *  `codex app-server` and `server` names the MCP server inside Codex. */
   appServer: Schema.optional(
-    Schema.Struct({ server: Schema.String, surface: Schema.optional(Schema.Literal("sky")) }),
+    Schema.Struct({
+      server: Schema.String,
+      surface: Schema.optional(Schema.Literals(["sky", "browser"])),
+      modulePath: Schema.optional(Schema.String),
+    }),
   ),
   slug: Schema.optional(Schema.String),
 });
@@ -152,7 +156,11 @@ const CodexPluginEntrySchema = Schema.Struct({
   /** Present on curated entries: add through the Codex app-server bridge,
    *  calling tools on this named server inside Codex. */
   appServer: Schema.optional(
-    Schema.Struct({ server: Schema.String, surface: Schema.optional(Schema.Literal("sky")) }),
+    Schema.Struct({
+      server: Schema.String,
+      surface: Schema.optional(Schema.Literals(["sky", "browser"])),
+      modulePath: Schema.optional(Schema.String),
+    }),
   ),
   setupHint: Schema.optional(Schema.String),
   /** The plugin's own icon from its local install, as a data URI. */

packages/plugins/mcp/src/api/handlers.ts

@@ -41,7 +41,7 @@ const toServerInput = (
       env?: Record<string, string>;
       cwd?: string;
       versionNegotiation?: "legacy" | "auto";
-      appServer?: { server: string; surface?: "sky" };
+      appServer?: { server: string; surface?: "sky" | "browser"; modulePath?: string };
       slug?: string;
     };
     return {

packages/plugins/mcp/src/sdk/appserver-connector.test.ts

@@ -15,12 +15,15 @@ import { createMcpConnector, type StdioConnectorInput } from "./connection";
 
 const fixture = fileURLToPath(new URL("./appserver-test-server.ts", import.meta.url));
 
-const appServerInput = (server: string, surface?: "sky"): StdioConnectorInput => ({
+const appServerInput = (
+  server: string,
+  appServer?: { readonly surface?: "sky" | "browser"; readonly modulePath?: string },
+): StdioConnectorInput => ({
   transport: "stdio",
   command: "bun",
   args: ["run", fixture],
   env: { CODEX_HOME: "/tmp/fixture-codex-home" },
-  appServer: { server, ...(surface === undefined ? {} : { surface }) },
+  appServer: { server, ...appServer },
 });
 
 const withConnection = (input: StdioConnectorInput) =>
@@ -126,7 +129,7 @@ describe("codex app-server bridge", () => {
   it.effect("the sky surface lists typed Computer Use tools, not the raw REPL", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const connection = yield* withConnection(appServerInput("node_repl", "sky"));
+        const connection = yield* withConnection(appServerInput("node_repl", { surface: "sky" }));
 
         const tools = yield* Effect.promise(() => connection.client.listTools());
         const names = tools.tools.map(({ name }) => name);
@@ -144,7 +147,7 @@ describe("codex app-server bridge", () => {
   it.effect("a sky tool call compiles to one node_repl program carrying its arguments", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const connection = yield* withConnection(appServerInput("node_repl", "sky"));
+        const connection = yield* withConnection(appServerInput("node_repl", { surface: "sky" }));
 
         // Quotes in the arguments matter: they are embedded into a JS source
         // text, so the encoding has to survive them exactly.
@@ -161,7 +164,10 @@ describe("codex app-server bridge", () => {
           `await sky.type_text(${JSON.stringify(args)})`,
         );
         expect(program, "returns the result as JSON through the REPL").toContain(
-          "nodeRepl.write(JSON.stringify(__result ?? null));",
+          "nodeRepl.write(JSON.stringify(result ?? null));",
+        );
+        expect(program, "runs in its own scope so a reused REPL session stays clean").toContain(
+          "await (async () => {",
         );
       }),
     ),
@@ -170,7 +176,7 @@ describe("codex app-server bridge", () => {
   it.effect("an argument-less sky tool calls its method with no argument object", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const connection = yield* withConnection(appServerInput("node_repl", "sky"));
+        const connection = yield* withConnection(appServerInput("node_repl", { surface: "sky" }));
 
         const result = yield* Effect.promise(() =>
           connection.client.callTool({ name: "list_apps", arguments: {} }),
@@ -184,7 +190,7 @@ describe("codex app-server bridge", () => {
   it.effect("a tool outside the sky surface is refused rather than sent to the REPL", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const connection = yield* withConnection(appServerInput("node_repl", "sky"));
+        const connection = yield* withConnection(appServerInput("node_repl", { surface: "sky" }));
 
         const outcome = yield* Effect.promise(() =>
           connection.client.callTool({ name: "js", arguments: { code: "process.exit(0)" } }).then(
@@ -197,6 +203,90 @@ describe("codex app-server bridge", () => {
     ),
   );
 
+  // -------------------------------------------------------------------------
+  // Chrome: also projected onto `node_repl`, but handle-based.
+  // -------------------------------------------------------------------------
+
+  const BROWSER_MODULE = "/codex/chrome/latest/scripts/browser-client.mjs";
+  const browserInput = () =>
+    appServerInput("node_repl", { surface: "browser", modulePath: BROWSER_MODULE });
+
+  it.effect("the browser surface lists typed Chrome tools, not the raw REPL", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const connection = yield* withConnection(browserInput());
+
+        const names = yield* Effect.promise(() =>
+          connection.client.listTools().then((result) => result.tools.map(({ name }) => name)),
+        );
+        expect(names, "the raw REPL is not exposed").not.toContain("js");
+        expect(names).toEqual(
+          expect.arrayContaining(["list_tabs", "new_tab", "navigate", "read_page", "click"]),
+        );
+      }),
+    ),
+  );
+
+  it.effect("a browser call imports the machine's own client and resolves a tab", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const connection = yield* withConnection(browserInput());
+
+        const result = yield* Effect.promise(() =>
+          connection.client.callTool({
+            name: "navigate",
+            arguments: { url: "https://example.com/" },
+          }),
+        );
+        const program = (result.content as readonly { readonly text: string }[])[0]!.text;
+        expect(program, "imports the scanner-resolved client path").toContain(
+          `await import(${JSON.stringify(BROWSER_MODULE)})`,
+        );
+        expect(program, "caches the runtime across calls in the pooled session").toContain(
+          "globalThis.__executorBrowser ??=",
+        );
+        expect(program, "falls back to the selected tab, opening one if needed").toContain(
+          "(await __browser.tabs.selected()) ?? (await __browser.tabs.new())",
+        );
+        expect(program).toContain("await __tab.goto(__args.url)");
+      }),
+    ),
+  );
+
+  it.effect("stamps REPL calls with the turn metadata the Chrome client requires", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        // Without this the real client refuses every call with "Missing
+        // required Codex turn metadata": Codex normally stamps a REPL call
+        // with its issuing turn, and this bridge runs no turns.
+        const connection = yield* withConnection(browserInput());
+
+        const result = yield* Effect.promise(() =>
+          connection.client.callTool({ name: "list_tabs", arguments: {} }),
+        );
+        const meta = (result.structuredContent as { readonly meta: Record<string, unknown> }).meta;
+        const turn = meta["x-codex-turn-metadata"] as Record<string, string>;
+        expect(typeof turn.session_id, "the pooled thread is the session").toBe("string");
+        expect(typeof turn.turn_id, "each call is its own turn").toBe("string");
+      }),
+    ),
+  );
+
+  it.effect("a tab-less browser tool skips tab resolution entirely", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const connection = yield* withConnection(browserInput());
+
+        const result = yield* Effect.promise(() =>
+          connection.client.callTool({ name: "list_tabs", arguments: {} }),
+        );
+        const program = (result.content as readonly { readonly text: string }[])[0]!.text;
+        expect(program).toContain("await __browser.tabs.list()");
+        expect(program, "no tab is resolved for a browser-level call").not.toContain("const __tab");
+      }),
+    ),
+  );
+
   it.effect("a server name Codex does not report fails the tools listing, not the connect", () =>
     Effect.scoped(
       Effect.gen(function* () {

packages/plugins/mcp/src/sdk/appserver-connector.ts

@@ -39,6 +39,7 @@
 import type { JSONRPCMessage, JSONRPCRequest, Transport } from "@modelcontextprotocol/client";
 import { Option, Schema } from "effect";
 
+import { browserCallProgram, browserToolList, findBrowserTool } from "./codex-browser-tools";
 import { findSkyTool, skyCallProgram, skyToolList } from "./codex-sky-tools";
 import { stdioSpawnEnv, type StdioTransportConfig } from "./stdio-connector";
 
@@ -78,10 +79,14 @@ export type AppServerTransportConfig = StdioTransportConfig & {
   /** The MCP server name inside Codex whose tools this transport exposes
    *  (e.g. `messages`) — the `server` of every `mcpServer/tool/call`. */
   readonly server: string;
-  /** `sky` projects the Codex Computer Use API over the `node_repl` server as
-   *  typed tools instead of exposing the REPL itself (see
-   *  `codex-sky-tools.ts`). Absent exposes the server's tools verbatim. */
-  readonly surface?: "sky";
+  /** A projected tool surface for a plugin driven through `node_repl` rather
+   *  than serving MCP itself: `sky` is Computer Use (`codex-sky-tools.ts`),
+   *  `browser` is Chrome (`codex-browser-tools.ts`). Absent exposes the
+   *  server's own tools verbatim. */
+  readonly surface?: "sky" | "browser";
+  /** Absolute path to the module a projected surface imports (Chrome's
+   *  `browser-client.mjs`); resolved per machine by the scanner. */
+  readonly modulePath?: string;
 };
 
 // ---------------------------------------------------------------------------
@@ -173,6 +178,9 @@ type AppServerReply =
 const INTERNAL_ERROR = -32603;
 const METHOD_NOT_FOUND = -32601;
 
+/** Ceiling for one browser action inside the REPL. */
+const BROWSER_TIMEOUT_MS = 120_000;
+
 const CHANNEL_CLOSED: AppServerReply = {
   ok: false,
   error: { code: INTERNAL_ERROR, message: "Codex app-server exited before replying" },
@@ -370,6 +378,10 @@ class AppServerClientTransport implements Transport {
       this.#emit({ jsonrpc: "2.0", id: message.id, result: { tools: skyToolList() } });
       return;
     }
+    if (this.#config.surface === "browser") {
+      this.#emit({ jsonrpc: "2.0", id: message.id, result: { tools: browserToolList() } });
+      return;
+    }
     const tools = await this.#collectServerTools(message.id);
     if (tools === undefined) return;
     this.#emit({ jsonrpc: "2.0", id: message.id, result: { tools } });
@@ -426,7 +438,7 @@ class AppServerClientTransport implements Transport {
     if (call === undefined) {
       this.#fail(message.id, {
         code: METHOD_NOT_FOUND,
-        message: `Unknown Computer Use tool "${params.value.name}"`,
+        message: `Unknown tool "${params.value.name}" for this Codex plugin`,
       });
       return;
     }
@@ -461,27 +473,70 @@ class AppServerClientTransport implements Transport {
    *  performs it; otherwise the tool is passed through by name. Undefined
    *  means the surface does not define that tool. */
   #toolCallParams(name: string, args: unknown): Record<string, unknown> | undefined {
-    if (this.#config.surface !== "sky") {
+    const program = this.#surfaceProgram(name, args);
+    if (program === "unknown-tool") return undefined;
+    if (program === undefined) {
       return {
         threadId: this.#threadId,
         server: this.#config.server,
         tool: name,
         arguments: args ?? {},
       };
     }
-    const tool = findSkyTool(name);
-    if (tool === undefined) return undefined;
     return {
       threadId: this.#threadId,
       server: this.#config.server,
       tool: "js",
       arguments: {
-        code: skyCallProgram(tool, args),
-        title: `Computer Use: ${tool.name}`,
+        code: program.code,
+        title: program.title,
+        ...(program.timeoutMs === undefined ? {} : { timeout_ms: program.timeoutMs }),
+      },
+      // Codex normally stamps a REPL call with the turn that issued it, and
+      // the Chrome client REFUSES to run without it ("Missing required Codex
+      // turn metadata"). This bridge starts no turns, so it supplies the same
+      // shape: the pooled thread is the session, and each tool call is its own
+      // turn. Computer Use does not check for it, but it is node_repl-backed
+      // too and Codex would stamp it, so both surfaces send it.
+      _meta: {
+        "x-codex-turn-metadata": {
+          session_id: this.#threadId,
+          turn_id: crypto.randomUUID(),
+        },
       },
     };
   }
 
+  /** The REPL program for a projected surface: `undefined` when this
+   *  connection exposes the server's own tools, `"unknown-tool"` when the
+   *  surface does not define `name`. */
+  #surfaceProgram(
+    name: string,
+    args: unknown,
+  ):
+    | { readonly code: string; readonly title: string; readonly timeoutMs?: number }
+    | undefined
+    | "unknown-tool" {
+    if (this.#config.surface === "sky") {
+      const tool = findSkyTool(name);
+      if (tool === undefined) return "unknown-tool";
+      return { code: skyCallProgram(tool, args), title: `Computer Use: ${tool.name}` };
+    }
+    if (this.#config.surface === "browser") {
+      const tool = findBrowserTool(name);
+      if (tool === undefined) return "unknown-tool";
+      return {
+        code: browserCallProgram(tool, args, this.#config.modulePath ?? ""),
+        title: `Chrome: ${tool.name}`,
+        // The REPL's own 30s default is too short for real navigation: a
+        // page load plus its accessibility pass routinely outruns it, and the
+        // failure surfaces as an opaque REPL timeout rather than a page error.
+        timeoutMs: BROWSER_TIMEOUT_MS,
+      };
+    }
+    return undefined;
+  }
+
   // -------------------------------------------------------------------------
   // Downstream traffic
   // -------------------------------------------------------------------------