@rigkit/provider-cmux 0.2.3 → 0.2.5

package/README.md

@@ -52,11 +52,16 @@ export default workflow("site", {
           sshOptions: ["ServerAliveInterval=15"],
         },
         cwd: "/workspace/site",
-        command: "pnpm dev",
+        surfaceLayout: "tabs",
+        terminals: [{ command: "pnpm dev" }],
         url: "http://localhost:3000",
       });
     },
   });
 ```
 
+Set `surfaceLayout: "tabs"` to open terminals and the optional browser URL as
+tabs in the same cmux pane. Omit it, or set `"splits"`, to keep the default
+split-pane behavior.
+
 Local hosts can import `@rigkit/provider-cmux/host` to register the trusted `cmux.open` handler. The Rigkit CLI registers this handler automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/provider-cmux",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,8 +17,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@rigkit/sdk": "0.2.3",
-    "@rigkit/engine": "0.2.3"
+    "@rigkit/sdk": "0.2.5",
+    "@rigkit/engine": "0.2.5"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/capabilities.ts

@@ -1,7 +1,7 @@
 export const CMUX_OPEN_CAPABILITY_ID = "cmux.open";
 
 export const CMUX_OPEN_SCHEMA_HASH =
-  "sha256:671373232fc79a7f75dd01c8c83c0c350af62b349a89bb3cfcc96af2cd76c878";
+  "sha256:3a2975cfe53089c6a607da751b55575dc8806bd90132242d4b7e9065a26ae3af";
 
 export const CMUX_OPEN_CAPABILITY = {
   id: CMUX_OPEN_CAPABILITY_ID,
@@ -29,24 +29,40 @@ export type CmuxRemoteReadyOptions = {
   requireProxy?: boolean;
 };
 
+export type CmuxOpenTerminalDirection = "left" | "right" | "up" | "down";
+export type CmuxOpenSurfaceLayout = "splits" | "tabs";
+
+export type CmuxOpenTerminalInput = {
+  command: string;
+  cwd?: string;
+  direction?: CmuxOpenTerminalDirection;
+  focus?: boolean;
+};
+
 export type CmuxOpenInput = {
   name: string;
   ssh?: CmuxOpenSshInput;
   cwd?: string;
-  command?: string;
+  surfaceLayout?: CmuxOpenSurfaceLayout;
+  terminals?: readonly CmuxOpenTerminalInput[];
   url?: string;
   focus?: boolean;
   waitForRemoteReady?: boolean | CmuxRemoteReadyOptions;
 };
 
+export type CmuxOpenPaneResult = {
+  paneId?: string;
+  paneRef?: string;
+  surfaceId?: string;
+  surfaceRef?: string;
+};
+
 export type CmuxOpenResult = {
   sessionId: string;
   workspaceId: string;
   workspaceRef?: string;
-  terminalPaneId?: string;
-  terminalSurfaceId?: string;
-  browserPaneId?: string;
-  browserSurfaceId?: string;
+  terminalPanes: CmuxOpenPaneResult[];
+  browserPane?: CmuxOpenPaneResult;
 };
 
 export type CmuxOpenSession = CmuxOpenResult & {

package/src/host.ts

@@ -1,10 +1,8 @@
 import {
   createCmuxClient,
   formatShellCommand,
-  type CmuxBrowserOpenOptions,
   type CmuxClient,
   type CmuxClientOptions,
-  type CmuxNewPaneOptions,
   type CmuxNewWorkspaceOptions,
   type CmuxPane,
   type CmuxPortsKickOptions,
@@ -13,12 +11,19 @@ import {
   type CmuxWaitForRemoteOptions,
   type CmuxWorkspace,
 } from "./index.ts";
-import { defineHostCapability, type HostCapabilityHandler } from "@rigkit/sdk/host";
+import {
+  defineHostCapability,
+  type HostCapabilityContext,
+  type HostCapabilityHandler,
+} from "@rigkit/sdk/host";
 import {
   CMUX_OPEN_CAPABILITY,
   type CmuxOpenInput,
+  type CmuxOpenPaneResult,
   type CmuxOpenResult,
   type CmuxOpenSshInput,
+  type CmuxOpenTerminalDirection,
+  type CmuxOpenTerminalInput,
   type CmuxRemoteReadyOptions,
 } from "./capabilities.ts";
 
@@ -29,6 +34,7 @@ export type CmuxOpenClient = Pick<
   | "newWorkspace"
   | "ssh"
   | "newPane"
+  | "newSurface"
   | "send"
   | "portsKick"
   | "browserOpen"
@@ -39,6 +45,7 @@ export type CmuxOpenClient = Pick<
 export type CmuxOpenHostOptions = {
   client?: CmuxOpenClient;
   clientOptions?: CmuxClientOptions;
+  logger?: (message: string) => void;
 };
 
 export function createCmuxOpenHostCapability(
@@ -46,7 +53,11 @@ export function createCmuxOpenHostCapability(
 ): CmuxHostCapabilityHandler {
   return defineHostCapability(CMUX_OPEN_CAPABILITY.id, {
     schemaHash: CMUX_OPEN_CAPABILITY.schemaHash,
-    handle: async (params) => await openCmux(params, options),
+    handle: async (params, context) =>
+      await openCmux(params, {
+        ...options,
+        logger: options.logger ?? hostCapabilityLogger(context) ?? options.clientOptions?.logger,
+      }),
   });
 }
 
@@ -57,84 +68,120 @@ export async function openCmux(
   options: CmuxOpenHostOptions = {},
 ): Promise<CmuxOpenResult> {
   const input = parseCmuxOpenInput(params);
-  const cmux = options.client ?? createCmuxClient(options.clientOptions);
-  const command = commandForInput(input);
+  const logger = cmuxOpenLogger(options);
+  const cmux = options.client ?? createCmuxClient({
+    ...options.clientOptions,
+    ...(options.logger ? { logger: options.logger } : {}),
+    printCommands: options.clientOptions?.printCommands ?? false,
+  });
   let workspace: CmuxWorkspace;
-  let terminalPane: CmuxPane | undefined;
+  const terminalPanes: CmuxPane[] = [];
 
+  logger?.(`cmux: opening ${input.name}`);
   if (input.ssh) {
+    logger?.("cmux: connecting remote workspace");
     workspace = await cmux.ssh({
       ...cmuxSshOptionsForInput(input.ssh),
       name: input.name,
       noFocus: input.focus === false,
     });
   } else {
+    logger?.("cmux: creating workspace");
     const workspaceOptions: CmuxNewWorkspaceOptions = {
       name: input.name,
       cwd: input.cwd,
-      command: input.command,
       focus: input.focus,
     };
     workspace = await cmux.newWorkspace(workspaceOptions);
   }
 
   const workspaceId = workspace.id ?? workspace.handle;
+  const useTabLayout = input.surfaceLayout === "tabs";
 
-  if (input.ssh && command) {
-    const paneOptions: CmuxNewPaneOptions = {
-      workspace: workspaceId,
-      type: "terminal",
-      direction: "down",
-      focus: true,
-    };
-    terminalPane = await cmux.newPane(paneOptions);
+  for (const terminal of input.terminals ?? []) {
+    const cwd = terminal.cwd ?? input.cwd;
+    logger?.(cwd ? `cmux: starting terminal in ${cwd}` : "cmux: starting terminal");
+    const terminalPane = useTabLayout
+      ? await cmux.newSurface({
+          workspace: workspaceId,
+          type: "terminal",
+          focus: terminal.focus ?? true,
+        })
+      : await cmux.newPane({
+          workspace: workspaceId,
+          type: "terminal",
+          direction: terminal.direction ?? "down",
+          focus: terminal.focus ?? true,
+        });
+    terminalPanes.push(terminalPane);
     const sendOptions: CmuxSendOptions = {
       workspace: workspaceId,
       surface: terminalPane.surface,
-      text: command,
+      text: commandForTerminal(terminal, input),
     };
     await cmux.send(sendOptions);
   }
 
   const waitOptions = remoteReadyOptionsForInput(input);
   if (input.ssh && waitOptions) {
+    logger?.("cmux: waiting for remote ports");
     await cmux.waitForRemoteReady(workspaceId, waitOptions);
   }
 
-  if (input.ssh && terminalPane?.surface) {
-    const kickOptions: CmuxPortsKickOptions = {
-      workspace: workspaceId,
-      surface: terminalPane.surface,
-      reason: "command",
-    };
-    await cmux.portsKick(kickOptions);
+  if (input.ssh && terminalPanes.some((pane) => pane.surface)) {
+    logger?.("cmux: refreshing remote ports");
+    for (const pane of terminalPanes) {
+      if (!pane.surface) continue;
+      const kickOptions: CmuxPortsKickOptions = {
+        workspace: workspaceId,
+        surface: pane.surface,
+        reason: "command",
+      };
+      await cmux.portsKick(kickOptions);
+    }
   }
 
   let browserPane: CmuxPane | undefined;
   if (input.url) {
-    const browserOptions: CmuxBrowserOpenOptions = {
-      workspace: workspaceId,
-      url: input.url,
-      focus: input.focus !== false,
-    };
-    browserPane = await cmux.browserOpen(browserOptions);
+    logger?.(`cmux: opening ${input.url}`);
+    browserPane = useTabLayout
+      ? await cmux.newSurface({
+          workspace: workspaceId,
+          type: "browser",
+          url: input.url,
+          focus: input.focus !== false,
+        })
+      : await cmux.browserOpen({
+          workspace: workspaceId,
+          url: input.url,
+          focus: input.focus !== false,
+        });
   }
 
   if (input.focus !== false) {
+    logger?.("cmux: focusing workspace");
     await cmux.selectWorkspace(workspaceId);
   }
 
+  logger?.(`cmux: ready ${input.name}`);
   return {
     sessionId: workspaceId,
     workspaceId,
     ...(workspace.ref ? { workspaceRef: workspace.ref } : {}),
-    ...(terminalPane?.pane ? { terminalPaneId: terminalPane.pane } : {}),
-    ...(terminalPane?.surface ? { terminalSurfaceId: terminalPane.surface } : {}),
-    ...(browserPane?.pane ? { browserPaneId: browserPane.pane } : {}),
-    ...(browserPane?.surface ? { browserSurfaceId: browserPane.surface } : {}),
+    terminalPanes: terminalPanes.map(paneResultForCmuxPane),
+    ...(browserPane ? { browserPane: paneResultForCmuxPane(browserPane) } : {}),
   };
 }
 
+function cmuxOpenLogger(options: CmuxOpenHostOptions): ((message: string) => void) | undefined {
+  return options.logger ?? options.clientOptions?.logger;
+}
+
+function hostCapabilityLogger(context: HostCapabilityContext | undefined): ((message: string) => void) | undefined {
+  if (!context) return undefined;
+  return (message) => context.log(message, { label: "cmux" });
+}
+
 export function parseCmuxOpenInput(value: unknown): CmuxOpenInput {
   if (!isRecord(value)) throw new Error(`cmux.open requires an object input`);
   const name = requiredString(value, "name");
@@ -142,7 +189,8 @@ export function parseCmuxOpenInput(value: unknown): CmuxOpenInput {
     name,
     ...(value.ssh !== undefined ? { ssh: parseSshInput(value.ssh) } : {}),
     ...optionalStringField(value, "cwd"),
-    ...optionalStringField(value, "command"),
+    ...optionalSurfaceLayoutField(value, "surfaceLayout"),
+    ...(value.terminals !== undefined ? { terminals: parseTerminalInputs(value.terminals) } : {}),
     ...optionalStringField(value, "url"),
     ...optionalBooleanField(value, "focus"),
     ...(value.waitForRemoteReady !== undefined
@@ -205,10 +253,34 @@ function sshDestination(ssh: Extract<CmuxOpenSshInput, object>): string {
   return `${ssh.username}@${ssh.host}`;
 }
 
-function commandForInput(input: CmuxOpenInput): string | undefined {
-  if (!input.command) return undefined;
-  const prefix = input.cwd ? `${formatShellCommand(["cd", input.cwd])} && ` : "";
-  return `${prefix}${input.command}\n`;
+function parseTerminalInputs(value: unknown): CmuxOpenTerminalInput[] {
+  if (!Array.isArray(value)) throw new Error(`cmux.open terminals must be an array`);
+  return value.map((item, index) => parseTerminalInput(item, index));
+}
+
+function parseTerminalInput(value: unknown, index: number): CmuxOpenTerminalInput {
+  if (!isRecord(value)) throw new Error(`cmux.open terminals[${index}] must be an object`);
+  return {
+    command: requiredString(value, "command"),
+    ...optionalStringField(value, "cwd"),
+    ...optionalTerminalDirectionField(value, "direction"),
+    ...optionalBooleanField(value, "focus"),
+  };
+}
+
+function commandForTerminal(terminal: CmuxOpenTerminalInput, input: CmuxOpenInput): string {
+  const cwd = terminal.cwd ?? input.cwd;
+  const prefix = cwd ? `${formatShellCommand(["cd", cwd])} && ` : "";
+  return `${prefix}${terminal.command}\n`;
+}
+
+function paneResultForCmuxPane(pane: CmuxPane): CmuxOpenPaneResult {
+  return {
+    ...(pane.pane ? { paneId: pane.pane } : {}),
+    ...(pane.paneRef ? { paneRef: pane.paneRef } : {}),
+    ...(pane.surface ? { surfaceId: pane.surface } : {}),
+    ...(pane.surfaceRef ? { surfaceRef: pane.surfaceRef } : {}),
+  };
 }
 
 function remoteReadyOptionsForInput(input: CmuxOpenInput): CmuxWaitForRemoteOptions | false {
@@ -269,6 +341,30 @@ function optionalBooleanField(record: Record<string, unknown>, key: string): Rec
   return { [key]: value };
 }
 
+function optionalTerminalDirectionField(
+  record: Record<string, unknown>,
+  key: string,
+): Record<string, CmuxOpenTerminalDirection> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (value !== "left" && value !== "right" && value !== "up" && value !== "down") {
+    throw new Error(`cmux.open ${key} must be "left", "right", "up", or "down"`);
+  }
+  return { [key]: value };
+}
+
+function optionalSurfaceLayoutField(
+  record: Record<string, unknown>,
+  key: string,
+): Record<string, "splits" | "tabs"> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (value !== "splits" && value !== "tabs") {
+    throw new Error(`cmux.open ${key} must be "splits" or "tabs"`);
+  }
+  return { [key]: value };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/index.test.ts

@@ -135,7 +135,7 @@ describe("cmux sdk", () => {
     ]);
   });
 
-  test("creates panes, opens browsers, and sends terminal text", async () => {
+  test("creates panes, surfaces, opens browsers, and sends terminal text", async () => {
     const calls: Array<{ method: string; params: CmuxRpcParams }> = [];
     const cmux = createCmuxClient({
       printCommands: false,
@@ -161,6 +161,16 @@ describe("cmux sdk", () => {
             pane_ref: "pane:11",
           };
         }
+        if (method === "surface.create") {
+          return {
+            workspace_id: "00000000-0000-0000-0000-000000000009",
+            workspace_ref: "workspace:9",
+            surface_id: "00000000-0000-0000-0000-000000000012",
+            surface_ref: "surface:12",
+            pane_id: "00000000-0000-0000-0000-000000000008",
+            pane_ref: "pane:8",
+          };
+        }
         return {};
       },
     });
@@ -181,6 +191,17 @@ describe("cmux sdk", () => {
       surface: pane.surface,
       reason: "refresh",
     });
+    const surface = await cmux.newSurface({
+      workspace: "00000000-0000-0000-0000-000000000009",
+      pane: pane.pane,
+      type: "terminal",
+      focus: false,
+    });
+    await cmux.send({
+      workspace: "00000000-0000-0000-0000-000000000009",
+      surface: surface.surface,
+      text: "codex\\n",
+    });
     await cmux.browserOpen({
       workspace: "00000000-0000-0000-0000-000000000009",
       url: "http://localhost:3000",
@@ -188,6 +209,7 @@ describe("cmux sdk", () => {
     });
 
     expect(pane.surface).toBe("00000000-0000-0000-0000-000000000007");
+    expect(surface.surface).toBe("00000000-0000-0000-0000-000000000012");
     expect(calls).toEqual([
       {
         method: "pane.create",
@@ -214,6 +236,23 @@ describe("cmux sdk", () => {
           reason: "refresh",
         },
       },
+      {
+        method: "surface.create",
+        params: {
+          type: "terminal",
+          pane_id: "00000000-0000-0000-0000-000000000008",
+          workspace_id: "00000000-0000-0000-0000-000000000009",
+          focus: false,
+        },
+      },
+      {
+        method: "surface.send_text",
+        params: {
+          workspace_id: "00000000-0000-0000-0000-000000000009",
+          surface_id: "00000000-0000-0000-0000-000000000012",
+          text: "codex\\n",
+        },
+      },
       {
         method: "browser.open_split",
         params: {
@@ -400,8 +439,9 @@ describe("cmux sdk", () => {
     expect(() => cmux.run(["bad"])).toThrow(CmuxCommandError);
   });
 
-  test("handles cmux.open host capability for an ssh workspace", async () => {
+  test("handles cmux.open host capability for an ssh workspace with tabs", async () => {
     const calls: Array<{ method: string; params: unknown }> = [];
+    const logs: string[] = [];
     const client = fakeOpenClient(calls);
 
     const result = await openCmux({
@@ -412,18 +452,38 @@ describe("cmux sdk", () => {
         sshOptions: ["ServerAliveInterval=15"],
       },
       cwd: "/workspace/site",
-      command: "pnpm dev",
+      surfaceLayout: "tabs",
+      terminals: [
+        { command: "pnpm dev" },
+        { command: "codex", focus: false },
+      ],
       url: "http://localhost:4321",
-    }, { client });
+    }, { client, logger: (message) => logs.push(message) });
 
     expect(result).toEqual({
       sessionId: "workspace-1",
       workspaceId: "workspace-1",
       workspaceRef: "workspace:1",
-      terminalPaneId: "pane-1",
-      terminalSurfaceId: "surface-1",
-      browserPaneId: "pane-2",
-      browserSurfaceId: "surface-2",
+      terminalPanes: [
+        {
+          paneId: "pane-1",
+          paneRef: "pane:1",
+          surfaceId: "surface-1",
+          surfaceRef: "surface:1",
+        },
+        {
+          paneId: "pane-2",
+          paneRef: "pane:2",
+          surfaceId: "surface-2",
+          surfaceRef: "surface:2",
+        },
+      ],
+      browserPane: {
+        paneId: "pane-3",
+        paneRef: "pane:3",
+        surfaceId: "surface-3",
+        surfaceRef: "surface:3",
+      },
     });
     expect(calls).toEqual([
       {
@@ -435,11 +495,10 @@ describe("cmux sdk", () => {
         }),
       },
       {
-        method: "newPane",
+        method: "newSurface",
         params: {
           workspace: "workspace-1",
           type: "terminal",
-          direction: "down",
           focus: true,
         },
       },
@@ -451,6 +510,22 @@ describe("cmux sdk", () => {
           text: "cd /workspace/site && pnpm dev\n",
         },
       },
+      {
+        method: "newSurface",
+        params: {
+          workspace: "workspace-1",
+          type: "terminal",
+          focus: false,
+        },
+      },
+      {
+        method: "send",
+        params: {
+          workspace: "workspace-1",
+          surface: "surface-2",
+          text: "cd /workspace/site && codex\n",
+        },
+      },
       {
         method: "waitForRemoteReady",
         params: {
@@ -467,9 +542,18 @@ describe("cmux sdk", () => {
         },
       },
       {
-        method: "browserOpen",
+        method: "portsKick",
+        params: {
+          workspace: "workspace-1",
+          surface: "surface-2",
+          reason: "command",
+        },
+      },
+      {
+        method: "newSurface",
         params: {
           workspace: "workspace-1",
+          type: "browser",
           url: "http://localhost:4321",
           focus: true,
         },
@@ -480,6 +564,17 @@ describe("cmux sdk", () => {
       },
     ]);
     expect(calls[0]?.params).not.toHaveProperty("terminalStartupCommand");
+    expect(logs).toEqual([
+      "cmux: opening website",
+      "cmux: connecting remote workspace",
+      "cmux: starting terminal in /workspace/site",
+      "cmux: starting terminal in /workspace/site",
+      "cmux: waiting for remote ports",
+      "cmux: refreshing remote ports",
+      "cmux: opening http://localhost:4321",
+      "cmux: focusing workspace",
+      "cmux: ready website",
+    ]);
   });
 
   test("forwards an explicit cmux ssh terminal startup command", async () => {
@@ -513,8 +608,10 @@ describe("cmux sdk", () => {
     const controller = await cmuxProviderPlugin.createProvider({
       provider: { providerId: "cmux", config: {} },
       storage: memoryProviderStorage("cmux"),
+      hostStorage: memoryProviderStorage("cmux"),
+      local: { open: async () => {} },
     });
-    const requests: Array<{ capability: string; params: unknown }> = [];
+    const requests: Array<{ capability: string; params: unknown; options: unknown }> = [];
     const runtime = await controller.runtime({
       workflow: "test",
       nodePath: "operation.open",
@@ -525,8 +622,8 @@ describe("cmux sdk", () => {
       metadata: () => {},
       local: {
         open: async () => {},
-        requestCapability: async <Result,>(capability: string, params: unknown) => {
-          requests.push({ capability, params });
+        requestCapability: async <Result,>(capability: string, params: unknown, options: unknown) => {
+          requests.push({ capability, params, options });
           return { sessionId: "workspace-1", workspaceId: "workspace-1" } as Result;
         },
       },
@@ -538,6 +635,7 @@ describe("cmux sdk", () => {
       {
         capability: "cmux.open",
         params: { name: "workspace" },
+        options: { nodePath: "operation.open" },
       },
     ]);
     expect(session.sessionId).toBe("workspace-1");
@@ -554,6 +652,8 @@ describe("cmux sdk", () => {
     const controller = await cmuxProviderPlugin.createProvider({
       provider: { providerId: "cmux", config: {} },
       storage: memoryProviderStorage("cmux"),
+      hostStorage: memoryProviderStorage("cmux"),
+      local: { open: async () => {} },
     });
     let resolveClosed!: () => void;
     const runtime = await controller.runtime({
@@ -566,9 +666,10 @@ describe("cmux sdk", () => {
       metadata: () => {},
       local: {
         open: async () => {},
-        requestCapabilitySession: async <Result,>(capability: string, params: unknown) => {
+        requestCapabilitySession: async <Result,>(capability: string, params: unknown, options: unknown) => {
           expect(capability).toBe("cmux.open");
           expect(params).toEqual({ name: "workspace" });
+          expect(options).toEqual({ nodePath: "operation.open" });
           return {
             result: { sessionId: "workspace-1", workspaceId: "workspace-1" } as Result,
             closed: new Promise<void>((resolve) => {
@@ -594,6 +695,7 @@ describe("cmux sdk", () => {
 });
 
 function fakeOpenClient(calls: Array<{ method: string; params: unknown }>): CmuxOpenClient {
+  let terminalPaneIndex = 0;
   return {
     async newWorkspace(params) {
       calls.push({ method: "newWorkspace", params });
@@ -605,13 +707,26 @@ function fakeOpenClient(calls: Array<{ method: string; params: unknown }>): Cmux
     },
     async newPane(params) {
       calls.push({ method: "newPane", params });
+      terminalPaneIndex += 1;
+      return {
+        workspace: "workspace-1",
+        workspaceRef: "workspace:1",
+        pane: `pane-${terminalPaneIndex}`,
+        paneRef: `pane:${terminalPaneIndex}`,
+        surface: `surface-${terminalPaneIndex}`,
+        surfaceRef: `surface:${terminalPaneIndex}`,
+      };
+    },
+    async newSurface(params) {
+      calls.push({ method: "newSurface", params });
+      terminalPaneIndex += 1;
       return {
         workspace: "workspace-1",
         workspaceRef: "workspace:1",
-        pane: "pane-1",
-        paneRef: "pane:1",
-        surface: "surface-1",
-        surfaceRef: "surface:1",
+        pane: `pane-${terminalPaneIndex}`,
+        paneRef: `pane:${terminalPaneIndex}`,
+        surface: `surface-${terminalPaneIndex}`,
+        surfaceRef: `surface:${terminalPaneIndex}`,
       };
     },
     async send(params) {
@@ -627,10 +742,10 @@ function fakeOpenClient(calls: Array<{ method: string; params: unknown }>): Cmux
       return {
         workspace: "workspace-1",
         workspaceRef: "workspace:1",
-        pane: "pane-2",
-        paneRef: "pane:2",
-        surface: "surface-2",
-        surfaceRef: "surface:2",
+        pane: "browser-pane-1",
+        paneRef: "pane:browser-1",
+        surface: "browser-surface-1",
+        surfaceRef: "surface:browser-1",
       };
     },
     async selectWorkspace(workspace) {

package/src/index.ts

@@ -103,6 +103,14 @@ export type CmuxNewPaneOptions = {
   focus?: boolean;
 };
 
+export type CmuxNewSurfaceOptions = {
+  workspace?: string;
+  pane?: string;
+  type?: "terminal" | "browser";
+  url?: string;
+  focus?: boolean;
+};
+
 export type CmuxPane = {
   workspace?: string;
   workspaceRef?: string;
@@ -277,6 +285,17 @@ export class CmuxClient {
     return paneFromResult(await this.rpc("pane.create", params));
   }
 
+  async newSurface(options: CmuxNewSurfaceOptions = {}): Promise<CmuxPane> {
+    const params: CmuxRpcParams = {};
+    if (options.type) params.type = options.type;
+    if (options.pane) params.pane_id = options.pane;
+    if (options.workspace) params.workspace_id = options.workspace;
+    if (options.url) params.url = options.url;
+    if (options.focus !== undefined) params.focus = options.focus;
+
+    return paneFromResult(await this.rpc("surface.create", params));
+  }
+
   async listWorkspaces(): Promise<CmuxWorkspaceStatus[]> {
     const result = await this.rpc("workspace.list");
     const workspaces = Array.isArray(result.workspaces)
@@ -477,9 +496,13 @@ export {
   CMUX_OPEN_CAPABILITY_ID,
   CMUX_OPEN_SCHEMA_HASH,
   type CmuxOpenInput,
+  type CmuxOpenPaneResult,
   type CmuxOpenResult,
   type CmuxOpenSession,
+  type CmuxOpenSurfaceLayout,
   type CmuxOpenSshInput,
+  type CmuxOpenTerminalDirection,
+  type CmuxOpenTerminalInput,
   type CmuxRemoteReadyOptions,
 } from "./capabilities.ts";
 export {

package/src/provider.ts

@@ -7,6 +7,7 @@ import type { BaseProviderPlugin, WorkflowProviderController } from "@rigkit/eng
 import {
   CMUX_OPEN_CAPABILITY_ID,
   type CmuxOpenInput,
+  type CmuxOpenPaneResult,
   type CmuxOpenResult,
   type CmuxOpenSession,
 } from "./capabilities.ts";
@@ -37,24 +38,25 @@ export const cmuxProviderPlugin: BaseProviderPlugin = {
     return {
       providerId: CMUX_PROVIDER_ID,
       runtime(context) {
-        return createCmuxRuntime(context.local);
+        return createCmuxRuntime(context.local, context.nodePath);
       },
     };
   },
 };
 
-function createCmuxRuntime(local: LocalWorkspaceRuntime): CmuxRuntime {
+function createCmuxRuntime(local: LocalWorkspaceRuntime, nodePath: string): CmuxRuntime {
   return {
-    open: async (input) => await requestCmuxOpen(local, input),
+    open: async (input) => await requestCmuxOpen(local, input, { nodePath }),
   };
 }
 
 export async function requestCmuxOpen(
   local: LocalWorkspaceRuntime,
   input: CmuxOpenInput,
+  options: { nodePath?: string } = {},
 ): Promise<CmuxOpenSession> {
   if (local.requestCapabilitySession) {
-    const session = await local.requestCapabilitySession<CmuxOpenResult>(CMUX_OPEN_CAPABILITY_ID, input);
+    const session = await local.requestCapabilitySession<CmuxOpenResult>(CMUX_OPEN_CAPABILITY_ID, input, options);
     return {
       ...parseCmuxOpenResult(session.result),
       closed: session.closed,
@@ -64,7 +66,7 @@ export async function requestCmuxOpen(
     throw new Error(`Host capability ${CMUX_OPEN_CAPABILITY_ID} is unavailable in this runtime`);
   }
   const result = parseCmuxOpenResult(
-    await local.requestCapability(CMUX_OPEN_CAPABILITY_ID, input),
+    await local.requestCapability(CMUX_OPEN_CAPABILITY_ID, input, options),
   );
   return {
     ...result,
@@ -81,13 +83,32 @@ export function parseCmuxOpenResult(value: unknown): CmuxOpenResult {
     sessionId,
     workspaceId,
     ...optionalStringField(value, "workspaceRef"),
-    ...optionalStringField(value, "terminalPaneId"),
-    ...optionalStringField(value, "terminalSurfaceId"),
-    ...optionalStringField(value, "browserPaneId"),
-    ...optionalStringField(value, "browserSurfaceId"),
+    terminalPanes: arrayField(value, "terminalPanes", parseCmuxOpenPaneResult),
+    ...(value.browserPane !== undefined ? { browserPane: parseCmuxOpenPaneResult(value.browserPane) } : {}),
   };
 }
 
+function parseCmuxOpenPaneResult(value: unknown): CmuxOpenPaneResult {
+  if (!isRecord(value)) throw new Error(`cmux.open returned a non-object pane result`);
+  return {
+    ...optionalStringField(value, "paneId"),
+    ...optionalStringField(value, "paneRef"),
+    ...optionalStringField(value, "surfaceId"),
+    ...optionalStringField(value, "surfaceRef"),
+  };
+}
+
+function arrayField<Item>(
+  record: Record<string, unknown>,
+  key: string,
+  parseItem: (value: unknown) => Item,
+): Item[] {
+  const value = record[key];
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`cmux.open result ${key} must be an array`);
+  return value.map(parseItem);
+}
+
 function optionalStringField(record: Record<string, unknown>, key: string): Record<string, string> {
   const value = stringField(record, key);
   return value ? { [key]: value } : {};

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_PROVIDER_CMUX_VERSION = "0.2.3";
+export const RIGKIT_PROVIDER_CMUX_VERSION = "0.2.5";