rpc, computer, computerd, examples/mcp, docs: Add discovery commands to codemode

codemode gains subcommands: types prints every declaration, search and
describe reach the runtime's own discovery helpers so a script author
can find one method without reading everything, and pending lists what
a paused run is waiting on. CodemodeRPC carries the same five methods.
Approving or rejecting a paused run is deliberately not on the surface:
a run pauses because a connector asked for a human's decision, and the
process that wrote the script is not that human.

Two review findings are folded in. The proxy only ever forwarded the
literal /codemode, so a configured path could not be reached; the path
option is gone and one shared constant serves both sides. The CLI sets
process.exitCode instead of calling process.exit, so a large result
piped to another process drains before it ends.

Author: mattzcarey

.changeset/codemode-cli-binary.md

@@ -2,4 +2,4 @@
 "@cloudflare/computerd": minor
 ---
 
-Ships a second binary, codemode, next to computerd in the release artifacts and the computer-computerd-linux-x64 image. Run inside the container, it sends a script to the workspace's host and prints the result, or prints the host's TypeScript declarations with --types. It dials ws://computer.internal/codemode by default and needs no credentials.
+Ships a second binary, codemode, next to computerd in the release artifacts and the computer-computerd-linux-x64 image. Run inside the container, it sends a script to the workspace's host and prints the result, with subcommands to print the host's TypeScript declarations, search and describe one method at a time, and list what a paused run is waiting on. It dials ws://computer.internal/codemode by default and needs no credentials.

.changeset/codemode-rpc-interface.md

@@ -2,4 +2,4 @@
 "@cloudflare/computer-rpc": minor
 ---
 
-Adds the CodemodeRPC interface, the code surface a process inside the container reaches by opening a WebSocket to the host's egress endpoint at /codemode. It carries describe, which returns the TypeScript declarations of the globals a script may call, and execute, which runs a script body and reports completed, paused, or error rather than rejecting.
+Adds the CodemodeRPC interface, the code surface a process inside the container reaches by opening a WebSocket to the host's egress endpoint at /codemode. It carries types, search, and describe for discovering the globals a script may call, execute, which runs a script body and reports completed, paused, or error rather than rejecting, and pending, which lists what a paused run is waiting on. Approval is deliberately not on the surface.

docs/07_injected_service.md

@@ -68,8 +68,10 @@ back through, and the container backend answers it with a capnweb
 session whose bootstrap stub is `CodemodeRPC` (doc 08). The `codemode`
 binary that ships next to `computerd` is the client for it: a command
 the workspace runs can execute a script on the host with
-`codemode < script.js` and print the host's TypeScript declarations
-with `codemode --types`. The route answers `404` unless the backend was
+`codemode < script.js`, print the host's TypeScript declarations with
+`codemode types`, and find one method with `codemode search` or
+`codemode describe`. Approving a paused run is deliberately not on
+this surface. The route answers `404` unless the backend was
 constructed with the `codemode` option, and it needs no credential:
 reaching it at all means running inside this workspace's container.
 

docs/08_capnweb_interface.md

@@ -220,25 +220,33 @@ session whose bootstrap stub is:
 
 ```ts
 interface CodemodeRPC {
-  describe(): Promise<{ types: string; connectors: string[] }>;
+  types(): Promise<{ types: string; connectors: string[] }>;
+  search(query: string): Promise<CodemodeSearch>;
+  describe(target: string): Promise<CodemodeDescription>;
   execute(input: { code: string }): Promise<CodemodeResult>;
+  pending(executionId?: string): Promise<CodemodePendingAction[]>;
 }
 
 type CodemodeResult =
   | { status: "completed"; executionId: string; result?: unknown; logs?: string[] }
-  | { status: "paused"; executionId: string; pending: unknown[] }
+  | { status: "paused"; executionId: string; pending: CodemodePendingAction[] }
   | { status: "error"; executionId: string; error: string; logs?: string[] };
 ```
 
 `code` is the body of an async function. The host runs it through a
 codemode runtime in a dynamic worker, with the connectors the
 container backend was configured with as typed globals; `types` is
-the TypeScript declaration of those globals. `execute` never rejects:
-a script that throws comes back as an `error` result, and a run that
-stops for approval on the host comes back as `paused`. Each
-connection is its own session and is disposed when the client closes
-the socket. The `codemode` binary in the container image is the
-reference client.
+the TypeScript declaration of all of them, and `search` and
+`describe` are the runtime's own discovery helpers for one method at
+a time. `execute` never rejects: a script that throws comes back as
+an `error` result, and a run that stops for approval on the host
+comes back as `paused` with the actions it waits on, which `pending`
+also lists. Approving or rejecting is deliberately absent: a run
+pauses because a connector asked for a human's decision, and handing
+that decision to the process that wrote the script would make the
+gate meaningless. Each connection is its own session and
+is disposed when the client closes the socket. The `codemode` binary
+in the container image is the reference client.
 
 ## Push and fetch semantics
 

examples/mcp/README.md

@@ -128,13 +128,15 @@ a script back to the Durable Object, where it runs in a dynamic worker
 with the example's `notes` connector in scope:
 
 ```js
-const types = await codemode.exec({ command: "codemode --types", backend: "container-shell" });
+const types = await codemode.exec({ command: "codemode types", backend: "container-shell" });
 const added = await codemode.exec({
   command: `echo 'await notes.add({ text: "hello" }); return await notes.list({})' | codemode`,
   backend: "container-shell",
 });
 ```
 
+`codemode search <query>` and `codemode describe notes.add` find and
+document one method at a time instead of printing every declaration.
 `src/notes-connector.ts` is the whole connector. Swap it for connectors
 over whatever the workspace should reach.
 

examples/mcp/src/index.test.ts

@@ -163,10 +163,22 @@ describe("codemode from inside the container", () => {
   it("describes the notes connector and runs scripts against it", async () => {
     using api = await connect("codemode-run");
 
-    const description = await api.describe();
-    expect(description.connectors).toEqual(["notes"]);
-    expect(description.types).toContain("declare const notes:");
-    expect(description.types).toContain("add: (input: AddInput) => Promise<AddOutput>;");
+    const declared = await api.types();
+    expect(declared.connectors).toEqual(["notes"]);
+    expect(declared.types).toContain("declare const notes:");
+    expect(declared.types).toContain("add: (input: AddInput) => Promise<AddOutput>;");
+
+    const found = await api.search("append a note");
+    expect(found.results[0]?.path).toBe("notes.add");
+    const described = await api.describe("notes.add");
+    expect(described.kind).toBe("method");
+    expect(described.types).toContain("AddInput");
+
+    expect(await api.pending()).toEqual([]);
+    // A capnweb stub proxies any name, so the proof is that the host
+    // refuses the call: approving is not on the surface.
+    const offSurface = api as unknown as { approve(input: unknown): Promise<unknown> };
+    await expect(offSurface.approve({ executionId: "none" })).rejects.toThrow();
 
     const added = await api.execute({
       code: 'await notes.add({ text: "hello" }); console.log("added"); return await notes.list({});',

packages/computer/README.md

@@ -488,9 +488,12 @@ new CloudflareContainerBackend({
 Then forward `/codemode` to `backend.handleFetch` from the Durable
 Object's `fetch`, next to `/api`, and list `CodemodeRuntime` as a
 Durable Object binding so the runtime can find its facet class. Inside
-the container, `codemode --types` prints the declarations and
-`codemode < script.js` runs a script. `@cloudflare/codemode` is an
-optional peer dependency; install it when you use this option.
+the container, `codemode types` prints the declarations, `codemode
+search` and `codemode describe` find one method at a time, and
+`codemode < script.js` runs a script. A run that pauses for approval
+stays paused until the host decides; the container can list what it
+is waiting on but is never given a way to approve it. `@cloudflare/codemode` is an optional peer dependency;
+install it when you use this option.
 
 ### Constructing without the mixin
 

packages/computer/src/backends/container/cloudflare-container.test.ts

@@ -560,23 +560,6 @@ describe("CloudflareContainerBackend", () => {
     const res = await backend.handleFetch(new Request("http://computer.internal/codemode"));
     expect(res.status).toBe(400);
     expect(await res.text()).toMatch(/\/codemode requires a websocket upgrade/);
-
-    const custom = new CloudflareContainerBackend({
-      container: () => ({ getWorkspaceContainer: () => fake.host }),
-      workspace: fakeWorkspace,
-      codemode: {
-        ctx: {} as DurableObjectState,
-        loader: {} as WorkerLoader,
-        connectors: () => [],
-        path: "/scripts",
-      },
-    });
-    expect(
-      (await custom.handleFetch(new Request("http://computer.internal/codemode"))).status,
-    ).toBe(404);
-    expect((await custom.handleFetch(new Request("http://computer.internal/scripts"))).status).toBe(
-      400,
-    );
   });
 
   test("handleFetch refuses a dial-back that does not present the secret", async () => {

packages/computer/src/backends/container/cloudflare-container.ts

@@ -55,7 +55,11 @@ import {
   type WorkspaceEgressPolicy,
 } from "../../runtime/egress.js";
 import { WorkspaceTransportError } from "../../transport-failure.js";
-import { type CodemodeSessionOptions, createCodemodeSession } from "./codemode-session.js";
+import {
+  CODEMODE_PATH,
+  type CodemodeSessionOptions,
+  createCodemodeSession,
+} from "./codemode-session.js";
 import type { IWorkspaceContainerAPI, WorkspaceRef } from "./container-host.js";
 import { probeComputerdHealth } from "./health-probe.js";
 
@@ -137,10 +141,7 @@ export interface CloudflareContainerBackendOptions {
   // interception computerd dials back through, and runs in a dynamic
   // worker with the configured connectors as typed globals. Left unset,
   // the /codemode path answers 404.
-  codemode?: CodemodeSessionOptions & {
-    // Path on the egress host the CLI dials. Defaults to "/codemode".
-    path?: string;
-  };
+  codemode?: CodemodeSessionOptions;
 
   // Selector this backend is registered under in Workspace.
   // Defaults to "container-shell"; override when the
@@ -155,7 +156,6 @@ const DEFAULT_EGRESS_HOST = "computer.internal";
 // in step from one place.
 const EGRESS_HEALTH_PATH = "/health";
 const EGRESS_API_PATH = "/api";
-const EGRESS_CODEMODE_PATH = "/codemode";
 const DEFAULT_CONTAINER_PORT = 8080;
 const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 20_000;
@@ -414,7 +414,7 @@ export class CloudflareContainerBackend implements WorkspaceBackend {
       return this.#egress.gateway.fetch(new Request(parsedUrl, sanitized));
     }
     const url = new URL(req.url);
-    if (this.#codemode !== undefined && url.pathname === this.#codemodePath()) {
+    if (this.#codemode !== undefined && url.pathname === CODEMODE_PATH) {
       return this.#handleCodemodeFetch(req);
     }
     if (url.pathname !== EGRESS_API_PATH) {
@@ -458,10 +458,6 @@ export class CloudflareContainerBackend implements WorkspaceBackend {
 
   // --- internals --------------------------------------------------
 
-  #codemodePath(): string {
-    return this.#codemode?.path ?? EGRESS_CODEMODE_PATH;
-  }
-
   // Serves one codemode session per upgrade. No bearer check, unlike
   // /api: a request can only arrive here through the egress
   // interception bound to this workspace, and any process in the
@@ -472,9 +468,7 @@ export class CloudflareContainerBackend implements WorkspaceBackend {
     const codemode = this.#codemode;
     if (codemode === undefined) return new Response("not found", { status: 404 });
     if (req.headers.get("upgrade") !== "websocket") {
-      return new Response(`${this.#codemodePath()} requires a websocket upgrade`, {
-        status: 400,
-      });
+      return new Response(`${CODEMODE_PATH} requires a websocket upgrade`, { status: 400 });
     }
     const target = await createCodemodeSession(codemode);
     const pair = new WebSocketPair();

packages/computer/src/backends/container/codemode-session.test.ts

@@ -1,7 +1,8 @@
 // CodemodeRPCTarget is the bootstrap stub a container process talks to
 // over /codemode. It adapts a codemode runtime handle to the wire
 // contract and, because a rejection would surface on the host rather
-// than at the caller, folds every failure into an "error" result.
+// than at the caller, folds every run failure into an "error" result.
+// Approval is deliberately absent from the surface.
 
 import { describe, expect, test } from "vitest";
 
@@ -16,39 +17,64 @@ function connector(name: string, types: string): CodemodeConnectorLike {
   return { name: () => name, getTypeScriptTypes: async () => types };
 }
 
-function runtime(execute: CodemodeRuntimeLike["execute"]): CodemodeRuntimeLike {
-  return { execute };
+const pendingAction = { executionId: "p", seq: 1, connector: "kv", method: "put", args: {} };
+
+function runtime(overrides: Partial<CodemodeRuntimeLike> = {}): CodemodeRuntimeLike {
+  return {
+    execute: async () => completed(1),
+    search: async (query) => ({
+      results: [{ path: `kv.${query}`, connector: "kv", method: query, kind: "method", score: 1 }],
+      total: 1,
+      truncated: false,
+    }),
+    describe: async (target) => ({
+      path: target,
+      types: `declare const ${target}: {}`,
+      kind: "connector",
+    }),
+    pending: async () => [pendingAction],
+    ...overrides,
+  };
 }
 
 describe("CodemodeRPCTarget", () => {
-  test("describe joins each connector's declarations and lists their names", async () => {
-    const target = new CodemodeRPCTarget(
-      runtime(async () => completed(1)),
-      [connector("kv", "declare const kv: {}"), connector("github", "declare const github: {}")],
-    );
-    expect(await target.describe()).toEqual({
+  test("types joins each connector's declarations and lists their names", async () => {
+    const target = new CodemodeRPCTarget(runtime(), [
+      connector("kv", "declare const kv: {}"),
+      connector("github", "declare const github: {}"),
+    ]);
+    expect(await target.types()).toEqual({
       types: "declare const kv: {}\ndeclare const github: {}",
       connectors: ["kv", "github"],
     });
   });
 
-  test("describe with no connectors is empty rather than an error", async () => {
-    const target = new CodemodeRPCTarget(
-      runtime(async () => completed(1)),
-      [],
-    );
-    expect(await target.describe()).toEqual({ types: "", connectors: [] });
+  test("types with no connectors is empty rather than an error", async () => {
+    expect(await new CodemodeRPCTarget(runtime(), []).types()).toEqual({
+      types: "",
+      connectors: [],
+    });
+  });
+
+  test("search, describe, and pending pass straight through to the runtime", async () => {
+    const target = new CodemodeRPCTarget(runtime(), []);
+    expect((await target.search("get")).results[0]?.path).toBe("kv.get");
+    expect((await target.describe("kv")).types).toBe("declare const kv: {}");
+    expect(await target.pending("p")).toEqual([pendingAction]);
   });
 
   test("execute forwards the code and maps every runtime status", async () => {
     const seen: string[] = [];
     const target = new CodemodeRPCTarget(
-      runtime(async ({ code }) => {
-        seen.push(code);
-        if (code === "pause") return { status: "paused", executionId: "p", pending: [{ seq: 1 }] };
-        if (code === "fail")
-          return { status: "error", executionId: "e", error: "bad", logs: ["l"] };
-        return { status: "completed", executionId: "c", result: 42, logs: ["hi"] };
+      runtime({
+        execute: async ({ code }) => {
+          seen.push(code);
+          if (code === "pause")
+            return { status: "paused", executionId: "p", pending: [pendingAction] };
+          if (code === "fail")
+            return { status: "error", executionId: "e", error: "bad", logs: ["l"] };
+          return { status: "completed", executionId: "c", result: 42, logs: ["hi"] };
+        },
       }),
       [],
     );
@@ -62,7 +88,7 @@ describe("CodemodeRPCTarget", () => {
     expect(await target.execute({ code: "pause" })).toEqual({
       status: "paused",
       executionId: "p",
-      pending: [{ seq: 1 }],
+      pending: [pendingAction],
     });
     expect(await target.execute({ code: "fail" })).toEqual({
       status: "error",
@@ -74,8 +100,10 @@ describe("CodemodeRPCTarget", () => {
 
   test("execute never rejects: empty code and a throwing runtime become error results", async () => {
     const target = new CodemodeRPCTarget(
-      runtime(async () => {
-        throw new Error("boom");
+      runtime({
+        execute: async () => {
+          throw new Error("boom");
+        },
       }),
       [],
     );
@@ -85,6 +113,13 @@ describe("CodemodeRPCTarget", () => {
     });
     expect(await target.execute({ code: "x" })).toMatchObject({ status: "error", error: "boom" });
   });
+
+  test("the surface has no way to approve or reject", () => {
+    const target = new CodemodeRPCTarget(runtime(), []) as unknown as Record<string, unknown>;
+    expect(target.approve).toBeUndefined();
+    expect(target.reject).toBeUndefined();
+    expect(target.rollback).toBeUndefined();
+  });
 });
 
 function completed(result: unknown): CodemodeRuntimeOutput {