@rigkit/provider-cmux 0.2.4 → 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.4",
+  "version": "0.2.5",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,8 +17,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@rigkit/sdk": "0.2.4",
-    "@rigkit/engine": "0.2.4"
+    "@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,
@@ -21,8 +19,11 @@ import {
 import {
   CMUX_OPEN_CAPABILITY,
   type CmuxOpenInput,
+  type CmuxOpenPaneResult,
   type CmuxOpenResult,
   type CmuxOpenSshInput,
+  type CmuxOpenTerminalDirection,
+  type CmuxOpenTerminalInput,
   type CmuxRemoteReadyOptions,
 } from "./capabilities.ts";
 
@@ -33,6 +34,7 @@ export type CmuxOpenClient = Pick<
   | "newWorkspace"
   | "ssh"
   | "newPane"
+  | "newSurface"
   | "send"
   | "portsKick"
   | "browserOpen"
@@ -72,9 +74,8 @@ export async function openCmux(
     ...(options.logger ? { logger: options.logger } : {}),
     printCommands: options.clientOptions?.printCommands ?? false,
   });
-  const command = commandForInput(input);
   let workspace: CmuxWorkspace;
-  let terminalPane: CmuxPane | undefined;
+  const terminalPanes: CmuxPane[] = [];
 
   logger?.(`cmux: opening ${input.name}`);
   if (input.ssh) {
@@ -89,27 +90,34 @@ export async function openCmux(
     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) {
-    logger?.(input.cwd ? `cmux: starting command in ${input.cwd}` : "cmux: starting 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);
   }
@@ -120,25 +128,34 @@ export async function openCmux(
     await cmux.waitForRemoteReady(workspaceId, waitOptions);
   }
 
-  if (input.ssh && terminalPane?.surface) {
+  if (input.ssh && terminalPanes.some((pane) => pane.surface)) {
     logger?.("cmux: refreshing remote ports");
-    const kickOptions: CmuxPortsKickOptions = {
-      workspace: workspaceId,
-      surface: terminalPane.surface,
-      reason: "command",
-    };
-    await cmux.portsKick(kickOptions);
+    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) {
     logger?.(`cmux: opening ${input.url}`);
-    const browserOptions: CmuxBrowserOpenOptions = {
-      workspace: workspaceId,
-      url: input.url,
-      focus: input.focus !== false,
-    };
-    browserPane = await cmux.browserOpen(browserOptions);
+    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) {
@@ -151,10 +168,8 @@ export async function openCmux(
     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) } : {}),
   };
 }
 
@@ -174,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
@@ -237,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 {
@@ -301,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,7 +439,7 @@ 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);
@@ -413,7 +452,11 @@ 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, logger: (message) => logs.push(message) });
 
@@ -421,10 +464,26 @@ describe("cmux sdk", () => {
       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([
       {
@@ -436,11 +495,10 @@ describe("cmux sdk", () => {
         }),
       },
       {
-        method: "newPane",
+        method: "newSurface",
         params: {
           workspace: "workspace-1",
           type: "terminal",
-          direction: "down",
           focus: true,
         },
       },
@@ -452,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: {
@@ -468,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,
         },
@@ -484,7 +567,8 @@ describe("cmux sdk", () => {
     expect(logs).toEqual([
       "cmux: opening website",
       "cmux: connecting remote workspace",
-      "cmux: starting command in /workspace/site",
+      "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",
@@ -611,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 });
@@ -622,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) {
@@ -644,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";
@@ -82,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.4";
+export const RIGKIT_PROVIDER_CMUX_VERSION = "0.2.5";