@rigkit/provider-cmux 0.2.13 → 0.2.14

package/README.md

@@ -1,67 +1,52 @@
 # @rigkit/provider-cmux
 
-Small SDK and Rigkit provider facade for opening workspaces in local `cmux`.
+Small SDK and Rigkit provider facade for driving local `cmux`.
 
 ```ts
 import { createCmuxClient } from "@rigkit/provider-cmux";
 
 const cmux = createCmuxClient();
 
-await cmux.newWorkspace({
+const workspace = await cmux.newWorkspace({
   name: "playground",
-  command: "echo hello world",
+  focus: true,
+});
+await cmux.newSurface({
+  workspace: workspace.id ?? workspace.handle,
+  type: "terminal",
   focus: true,
 });
 ```
 
-Commands are printed to stderr before execution:
-
-```text
-$ cmux new-workspace --name playground --command 'echo hello world' --focus true
-```
-
-`cmux new-workspace` and `cmux ssh` are socket commands. With cmux's default socket control mode (`cmuxOnly`), run rigkit from a terminal inside cmux so cmux sets `CMUX_SOCKET_PATH` and accepts the process.
-
-If you intentionally enable external socket control in cmux, opt in explicitly:
+Workflow operations use raw cmux actions through the provider facade:
 
 ```ts
-const cmux = createCmuxClient({ allowExternalAutomation: true });
-```
+const workspace = await providers.cmux.ssh({
+  destination: "root@devbox.example.com",
+  name: "site",
+});
 
-With `allowExternalAutomation`, the SDK can run `open -a cmux` and retry a workspace command while cmux starts.
+await providers.cmux.newSurface({
+  workspace: workspace.workspaceId,
+  type: "browser",
+  url: "http://localhost:3000",
+  focus: true,
+});
 
-Config-defined operations can request the typed `cmux.open` host capability through the provider facade:
+const terminal = await providers.cmux.newSurface({
+  workspace: workspace.workspaceId,
+  type: "terminal",
+  focus: false,
+});
 
-```ts
-import { workflow } from "@rigkit/sdk";
-import { cmux } from "@rigkit/provider-cmux";
+await providers.cmux.send({
+  workspace: workspace.workspaceId,
+  surface: terminal.surfaceId,
+  text: "pnpm dev\n",
+});
 
-export default workflow("site", {
-  providers: {
-    cmux: cmux.provider(),
-  },
-})
-  .sequence("site")
-  .operation("open", {
-    run: async ({ providers }) => {
-      await providers.cmux.open({
-        name: "site",
-        ssh: {
-          host: "devbox.example.com",
-          username: "root",
-          sshOptions: ["ServerAliveInterval=15"],
-        },
-        cwd: "/workspace/site",
-        surfaceLayout: "tabs",
-        terminals: [{ command: "pnpm dev" }],
-        url: "http://localhost:3000",
-      });
-    },
-  });
+await providers.cmux.selectWorkspace(workspace.workspaceId);
 ```
 
-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.
+Local hosts can import `@rigkit/provider-cmux/host` to register the trusted
+`cmux.call` handler. The Rigkit CLI registers this handler automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/provider-cmux",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -18,8 +18,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@rigkit/sdk": "0.2.13",
-    "@rigkit/engine": "0.2.13"
+    "@rigkit/sdk": "0.2.14",
+    "@rigkit/engine": "0.2.14"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/capabilities.ts

@@ -1,14 +1,30 @@
-export const CMUX_OPEN_CAPABILITY_ID = "cmux.open";
+export const CMUX_CALL_CAPABILITY_ID = "cmux.call";
 
-export const CMUX_OPEN_SCHEMA_HASH =
-  "sha256:3a2975cfe53089c6a607da751b55575dc8806bd90132242d4b7e9065a26ae3af";
+export const CMUX_CALL_SCHEMA_HASH =
+  "sha256:afcc8ef7251d854c80d1c04d9a98bc9afbd22d2ab15e1ce9fb880452ec17f6cf";
 
-export const CMUX_OPEN_CAPABILITY = {
-  id: CMUX_OPEN_CAPABILITY_ID,
-  schemaHash: CMUX_OPEN_SCHEMA_HASH,
+export const CMUX_CALL_CAPABILITY = {
+  id: CMUX_CALL_CAPABILITY_ID,
+  schemaHash: CMUX_CALL_SCHEMA_HASH,
 } as const;
 
-export type CmuxOpenSshInput = string | {
+export type CmuxCallMethod =
+  | "newWorkspace"
+  | "ssh"
+  | "newPane"
+  | "newSurface"
+  | "browserOpen"
+  | "send"
+  | "portsKick"
+  | "selectWorkspace"
+  | "waitForRemoteReady";
+
+export type CmuxCallInput = {
+  method: CmuxCallMethod;
+  params?: Record<string, unknown>;
+};
+
+export type CmuxSshInput = string | {
   kind?: "ssh";
   destination?: string;
   host?: string;
@@ -21,50 +37,72 @@ export type CmuxOpenSshInput = string | {
   terminalStartupCommand?: string;
   autoConnect?: boolean;
   skipDaemonBootstrap?: boolean;
+  name?: string;
+  noFocus?: boolean;
 };
 
-export type CmuxRemoteReadyOptions = {
-  timeoutMs?: number;
-  intervalMs?: number;
-  requireProxy?: boolean;
+export type CmuxWorkspaceInput = {
+  name?: string;
+  description?: string;
+  cwd?: string;
+  command?: string;
+  focus?: boolean;
 };
 
-export type CmuxOpenTerminalDirection = "left" | "right" | "up" | "down";
-export type CmuxOpenSurfaceLayout = "splits" | "tabs";
+export type CmuxPaneDirection = "left" | "right" | "up" | "down";
+export type CmuxSurfaceType = "terminal" | "browser";
 
-export type CmuxOpenTerminalInput = {
-  command: string;
-  cwd?: string;
-  direction?: CmuxOpenTerminalDirection;
+export type CmuxNewPaneInput = {
+  workspace?: string;
+  type?: CmuxSurfaceType;
+  direction?: CmuxPaneDirection;
+  url?: string;
   focus?: boolean;
 };
 
-export type CmuxOpenInput = {
-  name: string;
-  ssh?: CmuxOpenSshInput;
-  cwd?: string;
-  surfaceLayout?: CmuxOpenSurfaceLayout;
-  terminals?: readonly CmuxOpenTerminalInput[];
+export type CmuxNewSurfaceInput = {
+  workspace?: string;
+  pane?: string;
+  type?: CmuxSurfaceType;
   url?: string;
   focus?: boolean;
-  waitForRemoteReady?: boolean | CmuxRemoteReadyOptions;
 };
 
-export type CmuxOpenPaneResult = {
-  paneId?: string;
-  paneRef?: string;
-  surfaceId?: string;
-  surfaceRef?: string;
+export type CmuxBrowserOpenInput = {
+  workspace?: string;
+  window?: string;
+  url?: string;
+  focus?: boolean;
+};
+
+export type CmuxSendInput = {
+  workspace?: string;
+  surface?: string;
+  text: string;
 };
 
-export type CmuxOpenResult = {
+export type CmuxPortsKickInput = {
+  workspace: string;
+  surface?: string;
+  reason?: "command" | "refresh";
+};
+
+export type CmuxRemoteReadyInput = {
+  workspace: string;
+  timeoutMs?: number;
+  intervalMs?: number;
+  requireProxy?: boolean;
+};
+
+export type CmuxWorkspaceResult = {
   sessionId: string;
   workspaceId: string;
   workspaceRef?: string;
-  terminalPanes: CmuxOpenPaneResult[];
-  browserPane?: CmuxOpenPaneResult;
 };
 
-export type CmuxOpenSession = CmuxOpenResult & {
-  closed: Promise<void>;
+export type CmuxPaneResult = {
+  paneId?: string;
+  paneRef?: string;
+  surfaceId?: string;
+  surfaceRef?: string;
 };

package/src/host.ts

@@ -1,15 +1,15 @@
 import {
   createCmuxClient,
-  formatShellCommand,
+  type CmuxBrowserOpenOptions,
   type CmuxClient,
   type CmuxClientOptions,
+  type CmuxNewPaneOptions,
+  type CmuxNewSurfaceOptions,
   type CmuxNewWorkspaceOptions,
-  type CmuxPane,
   type CmuxPortsKickOptions,
   type CmuxSendOptions,
   type CmuxSshOptions,
   type CmuxWaitForRemoteOptions,
-  type CmuxWorkspace,
 } from "./index.ts";
 import {
   defineHostCapability,
@@ -17,19 +17,14 @@ import {
   type HostCapabilityHandler,
 } from "@rigkit/sdk/host";
 import {
-  CMUX_OPEN_CAPABILITY,
-  type CmuxOpenInput,
-  type CmuxOpenPaneResult,
-  type CmuxOpenResult,
-  type CmuxOpenSshInput,
-  type CmuxOpenTerminalDirection,
-  type CmuxOpenTerminalInput,
-  type CmuxRemoteReadyOptions,
+  CMUX_CALL_CAPABILITY,
+  type CmuxCallInput,
+  type CmuxSshInput,
 } from "./capabilities.ts";
 
 export type CmuxHostCapabilityHandler = HostCapabilityHandler;
 
-export type CmuxOpenClient = Pick<
+export type CmuxCallClient = Pick<
   CmuxClient,
   | "newWorkspace"
   | "ssh"
@@ -42,138 +37,69 @@ export type CmuxOpenClient = Pick<
   | "waitForRemoteReady"
 >;
 
-export type CmuxOpenHostOptions = {
-  client?: CmuxOpenClient;
+export type CmuxCallHostOptions = {
+  client?: CmuxCallClient;
   clientOptions?: CmuxClientOptions;
   logger?: (message: string) => void;
 };
 
-export function createCmuxOpenHostCapability(
-  options: CmuxOpenHostOptions = {},
+export function createCmuxCallHostCapability(
+  options: CmuxCallHostOptions = {},
 ): CmuxHostCapabilityHandler {
-  return defineHostCapability(CMUX_OPEN_CAPABILITY.id, {
-    schemaHash: CMUX_OPEN_CAPABILITY.schemaHash,
+  return defineHostCapability(CMUX_CALL_CAPABILITY.id, {
+    schemaHash: CMUX_CALL_CAPABILITY.schemaHash,
     handle: async (params, context) =>
-      await openCmux(params, {
+      await callCmux(params, {
         ...options,
         logger: options.logger ?? hostCapabilityLogger(context) ?? options.clientOptions?.logger,
       }),
   });
 }
 
-export const cmuxHostCapabilities = [createCmuxOpenHostCapability()] as const;
+export const cmuxHostCapabilities = [createCmuxCallHostCapability()] as const;
 
-export async function openCmux(
+export async function callCmux(
   params: unknown,
-  options: CmuxOpenHostOptions = {},
-): Promise<CmuxOpenResult> {
-  const input = parseCmuxOpenInput(params);
-  const logger = cmuxOpenLogger(options);
+  options: CmuxCallHostOptions = {},
+): Promise<unknown> {
+  const input = parseCmuxCallInput(params);
+  const logger = cmuxCallLogger(options);
   const cmux = options.client ?? createCmuxClient({
     ...options.clientOptions,
     ...(options.logger ? { logger: options.logger } : {}),
     printCommands: options.clientOptions?.printCommands ?? false,
   });
-  let workspace: CmuxWorkspace;
-  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,
-      focus: input.focus,
-    };
-    workspace = await cmux.newWorkspace(workspaceOptions);
-  }
-
-  const workspaceId = workspace.id ?? workspace.handle;
-  const useTabLayout = input.surfaceLayout === "tabs";
-
-  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: 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 && 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);
+  logger?.(`cmux: ${input.method}`);
+  switch (input.method) {
+    case "newWorkspace":
+      return await cmux.newWorkspace(input.params as CmuxNewWorkspaceOptions);
+    case "ssh":
+      return await cmux.ssh(cmuxSshOptionsForInput(input.params));
+    case "newPane":
+      return await cmux.newPane(input.params as CmuxNewPaneOptions);
+    case "newSurface":
+      return await cmux.newSurface(input.params as CmuxNewSurfaceOptions);
+    case "browserOpen":
+      return await cmux.browserOpen(input.params as CmuxBrowserOpenOptions);
+    case "send":
+      return await cmux.send(input.params as CmuxSendOptions);
+    case "portsKick":
+      return await cmux.portsKick(input.params as CmuxPortsKickOptions);
+    case "selectWorkspace":
+      await cmux.selectWorkspace(requiredString(input.params, "workspace"));
+      return "OK";
+    case "waitForRemoteReady": {
+      const { workspace, ...waitOptions } = input.params;
+      if (typeof workspace !== "string" || workspace.trim() === "") {
+        throw new Error(`cmux.call waitForRemoteReady requires params.workspace`);
+      }
+      return await cmux.waitForRemoteReady(workspace, waitOptions as CmuxWaitForRemoteOptions);
     }
   }
-
-  let browserPane: CmuxPane | undefined;
-  if (input.url) {
-    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 } : {}),
-    terminalPanes: terminalPanes.map(paneResultForCmuxPane),
-    ...(browserPane ? { browserPane: paneResultForCmuxPane(browserPane) } : {}),
-  };
 }
 
-function cmuxOpenLogger(options: CmuxOpenHostOptions): ((message: string) => void) | undefined {
+function cmuxCallLogger(options: CmuxCallHostOptions): ((message: string) => void) | undefined {
   return options.logger ?? options.clientOptions?.logger;
 }
 
@@ -182,28 +108,56 @@ function hostCapabilityLogger(context: HostCapabilityContext | undefined): ((mes
   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");
+export function parseCmuxCallInput(value: unknown): CmuxCallInput & { params: Record<string, unknown> } {
+  if (!isRecord(value)) throw new Error(`cmux.call requires an object input`);
+  const method = requiredString(value, "method");
+  if (!isCmuxCallMethod(method)) {
+    throw new Error(`cmux.call method is not supported: ${method}`);
+  }
+  const params = value.params === undefined ? {} : value.params;
+  if (!isRecord(params)) throw new Error(`cmux.call params must be an object`);
+  return { method, params };
+}
+
+function isCmuxCallMethod(value: string): value is CmuxCallInput["method"] {
+  return [
+    "newWorkspace",
+    "ssh",
+    "newPane",
+    "newSurface",
+    "browserOpen",
+    "send",
+    "portsKick",
+    "selectWorkspace",
+    "waitForRemoteReady",
+  ].includes(value);
+}
+
+function cmuxSshOptionsForInput(ssh: Record<string, unknown>): CmuxSshOptions {
+  const parsed = parseSshInput(ssh);
+  if (typeof parsed === "string") return { destination: parsed };
+
+  const destination = parsed.destination ?? sshDestination(parsed);
   return {
-    name,
-    ...(value.ssh !== undefined ? { ssh: parseSshInput(value.ssh) } : {}),
-    ...optionalStringField(value, "cwd"),
-    ...optionalSurfaceLayoutField(value, "surfaceLayout"),
-    ...(value.terminals !== undefined ? { terminals: parseTerminalInputs(value.terminals) } : {}),
-    ...optionalStringField(value, "url"),
-    ...optionalBooleanField(value, "focus"),
-    ...(value.waitForRemoteReady !== undefined
-      ? { waitForRemoteReady: parseRemoteReadyOptions(value.waitForRemoteReady) }
-      : {}),
+    destination,
+    ...(parsed.port !== undefined ? { port: parsed.port } : {}),
+    ...(parsed.identity !== undefined ? { identity: parsed.identity } : {}),
+    ...(parsed.sshOptions?.length ? { sshOptions: parsed.sshOptions } : {}),
+    ...(parsed.remoteCommandArgs !== undefined ? { remoteCommandArgs: parsed.remoteCommandArgs } : {}),
+    ...(parsed.initialCommand !== undefined ? { initialCommand: parsed.initialCommand } : {}),
+    ...(parsed.terminalStartupCommand !== undefined ? { terminalStartupCommand: parsed.terminalStartupCommand } : {}),
+    ...(parsed.autoConnect !== undefined ? { autoConnect: parsed.autoConnect } : {}),
+    ...(parsed.skipDaemonBootstrap !== undefined ? { skipDaemonBootstrap: parsed.skipDaemonBootstrap } : {}),
+    ...(parsed.name !== undefined ? { name: parsed.name } : {}),
+    ...(parsed.noFocus !== undefined ? { noFocus: parsed.noFocus } : {}),
   };
 }
 
-function parseSshInput(value: unknown): CmuxOpenSshInput {
+function parseSshInput(value: unknown): CmuxSshInput {
   if (typeof value === "string" && value.trim()) return value.trim();
-  if (!isRecord(value)) throw new Error(`cmux.open ssh must be a string or object`);
+  if (!isRecord(value)) throw new Error(`cmux.call ssh params must be an object`);
   if (value.kind !== undefined && value.kind !== "ssh") {
-    throw new Error(`cmux.open ssh.kind must be "ssh"`);
+    throw new Error(`cmux.call ssh.kind must be "ssh"`);
   }
   return {
     ...optionalStringField(value, "destination"),
@@ -217,84 +171,21 @@ function parseSshInput(value: unknown): CmuxOpenSshInput {
     ...optionalStringField(value, "terminalStartupCommand"),
     ...optionalBooleanField(value, "autoConnect"),
     ...optionalBooleanField(value, "skipDaemonBootstrap"),
+    ...optionalStringField(value, "name"),
+    ...optionalBooleanField(value, "noFocus"),
   };
 }
 
-function parseRemoteReadyOptions(value: unknown): boolean | CmuxRemoteReadyOptions {
-  if (typeof value === "boolean") return value;
-  if (!isRecord(value)) throw new Error(`cmux.open waitForRemoteReady must be a boolean or object`);
-  return {
-    ...optionalNumberField(value, "timeoutMs"),
-    ...optionalNumberField(value, "intervalMs"),
-    ...optionalBooleanField(value, "requireProxy"),
-  };
-}
-
-function cmuxSshOptionsForInput(ssh: CmuxOpenSshInput): CmuxSshOptions {
-  if (typeof ssh === "string") return { destination: ssh };
-
-  const destination = ssh.destination ?? sshDestination(ssh);
-  return {
-    destination,
-    ...(ssh.port !== undefined ? { port: ssh.port } : {}),
-    ...(ssh.identity !== undefined ? { identity: ssh.identity } : {}),
-    ...(ssh.sshOptions?.length ? { sshOptions: ssh.sshOptions } : {}),
-    ...(ssh.remoteCommandArgs !== undefined ? { remoteCommandArgs: ssh.remoteCommandArgs } : {}),
-    ...(ssh.initialCommand !== undefined ? { initialCommand: ssh.initialCommand } : {}),
-    ...(ssh.terminalStartupCommand !== undefined ? { terminalStartupCommand: ssh.terminalStartupCommand } : {}),
-    ...(ssh.autoConnect !== undefined ? { autoConnect: ssh.autoConnect } : {}),
-    ...(ssh.skipDaemonBootstrap !== undefined ? { skipDaemonBootstrap: ssh.skipDaemonBootstrap } : {}),
-  };
-}
-
-function sshDestination(ssh: Extract<CmuxOpenSshInput, object>): string {
-  if (!ssh.host) throw new Error(`cmux.open ssh.host is required when ssh.destination is omitted`);
-  if (!ssh.username) throw new Error(`cmux.open ssh.username is required when ssh.destination is omitted`);
+function sshDestination(ssh: Extract<CmuxSshInput, object>): string {
+  if (!ssh.host) throw new Error(`cmux.call ssh.host is required when ssh.destination is omitted`);
+  if (!ssh.username) throw new Error(`cmux.call ssh.username is required when ssh.destination is omitted`);
   return `${ssh.username}@${ssh.host}`;
 }
 
-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 {
-  if (input.waitForRemoteReady === false) return false;
-  if (input.waitForRemoteReady === true || input.waitForRemoteReady === undefined) {
-    return input.url ? {} : false;
-  }
-  return input.waitForRemoteReady;
-}
-
 function requiredString(record: Record<string, unknown>, key: string): string {
   const value = record[key];
   if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`cmux.open ${key} must be a non-empty string`);
+    throw new Error(`cmux.call ${key} must be a non-empty string`);
   }
   return value.trim();
 }
@@ -302,34 +193,32 @@ function requiredString(record: Record<string, unknown>, key: string): string {
 function optionalStringField(
   record: Record<string, unknown>,
   key: string,
-  expected?: string,
 ): Record<string, string> {
   const value = record[key];
   if (value === undefined) return {};
   if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`cmux.open ${key} must be a non-empty string`);
+    throw new Error(`cmux.call ${key} must be a non-empty string`);
   }
-  const normalized = value.trim();
-  if (expected !== undefined && normalized !== expected) {
-    throw new Error(`cmux.open ${key} must be "${expected}"`);
-  }
-  return { [key]: normalized };
+  return { [key]: value.trim() };
 }
 
-function optionalStringArrayField(record: Record<string, unknown>, key: string): Record<string, string[]> {
+function optionalStringArrayField(
+  record: Record<string, unknown>,
+  key: string,
+): Record<string, string[]> {
   const value = record[key];
   if (value === undefined) return {};
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`cmux.open ${key} must be an array of strings`);
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(`cmux.call ${key} must be an array of strings`);
   }
-  return { [key]: value };
+  return { [key]: value.map((item) => item.trim()) };
 }
 
 function optionalNumberField(record: Record<string, unknown>, key: string): Record<string, number> {
   const value = record[key];
   if (value === undefined) return {};
   if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`cmux.open ${key} must be a finite number`);
+    throw new Error(`cmux.call ${key} must be a finite number`);
   }
   return { [key]: value };
 }
@@ -337,31 +226,7 @@ function optionalNumberField(record: Record<string, unknown>, key: string): Reco
 function optionalBooleanField(record: Record<string, unknown>, key: string): Record<string, boolean> {
   const value = record[key];
   if (value === undefined) return {};
-  if (typeof value !== "boolean") throw new Error(`cmux.open ${key} must be a boolean`);
-  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"`);
-  }
+  if (typeof value !== "boolean") throw new Error(`cmux.call ${key} must be a boolean`);
   return { [key]: value };
 }
 

package/src/index.test.ts

@@ -18,7 +18,7 @@ import {
   type CmuxRpcResult,
   type CmuxRuntime,
 } from "./index.ts";
-import { openCmux, type CmuxOpenClient } from "./host.ts";
+import { callCmux, type CmuxCallClient } from "./host.ts";
 
 describe("cmux sdk", () => {
   test("parses workspace refs from cmux text output", () => {
@@ -439,52 +439,53 @@ describe("cmux sdk", () => {
     expect(() => cmux.run(["bad"])).toThrow(CmuxCommandError);
   });
 
-  test("handles cmux.open host capability for an ssh workspace with tabs", async () => {
+  test("handles raw cmux.call host capability requests", async () => {
     const calls: Array<{ method: string; params: unknown }> = [];
     const logs: string[] = [];
     const client = fakeOpenClient(calls);
 
-    const result = await openCmux({
-      name: "website",
-      ssh: {
+    const workspace = await callCmux({
+      method: "ssh",
+      params: {
         kind: "ssh",
         destination: "vm_123,token_123@vm-ssh.freestyle.sh",
+        name: "website",
         sshOptions: ["ServerAliveInterval=15"],
       },
-      cwd: "/workspace/site",
-      surfaceLayout: "tabs",
-      terminals: [
-        { command: "pnpm dev" },
-        { command: "codex", focus: false },
-      ],
-      url: "http://localhost:4321",
-    }, { client, logger: (message) => logs.push(message) });
-
-    expect(result).toEqual({
-      sessionId: "workspace-1",
-      workspaceId: "workspace-1",
-      workspaceRef: "workspace:1",
-      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",
+    }, { client, logger: (message: string) => logs.push(message) });
+    const browser = await callCmux({
+      method: "newSurface",
+      params: {
+        workspace: "workspace-1",
+        type: "browser",
+        url: "http://localhost:4321",
+        focus: true,
+      },
+    }, { client, logger: (message: string) => logs.push(message) });
+    const terminal = await callCmux({
+      method: "newSurface",
+      params: {
+        workspace: "workspace-1",
+        type: "terminal",
+        focus: false,
       },
-    });
+    }, { client, logger: (message: string) => logs.push(message) });
+    await callCmux({
+      method: "send",
+      params: {
+        workspace: "workspace-1",
+        surface: "surface-2",
+        text: "pnpm dev\n",
+      },
+    }, { client, logger: (message: string) => logs.push(message) });
+    await callCmux({
+      method: "selectWorkspace",
+      params: { workspace: "workspace-1" },
+    }, { client, logger: (message: string) => logs.push(message) });
+
+    expect(workspace).toEqual({ handle: "workspace-1", id: "workspace-1", ref: "workspace:1" });
+    expect(browser).toMatchObject({ surface: "surface-1" });
+    expect(terminal).toMatchObject({ surface: "surface-2" });
     expect(calls).toEqual([
       {
         method: "ssh",
@@ -498,18 +499,11 @@ describe("cmux sdk", () => {
         method: "newSurface",
         params: {
           workspace: "workspace-1",
-          type: "terminal",
+          type: "browser",
+          url: "http://localhost:4321",
           focus: true,
         },
       },
-      {
-        method: "send",
-        params: {
-          workspace: "workspace-1",
-          surface: "surface-1",
-          text: "cd /workspace/site && pnpm dev\n",
-        },
-      },
       {
         method: "newSurface",
         params: {
@@ -523,39 +517,7 @@ describe("cmux sdk", () => {
         params: {
           workspace: "workspace-1",
           surface: "surface-2",
-          text: "cd /workspace/site && codex\n",
-        },
-      },
-      {
-        method: "waitForRemoteReady",
-        params: {
-          workspace: "workspace-1",
-          options: {},
-        },
-      },
-      {
-        method: "portsKick",
-        params: {
-          workspace: "workspace-1",
-          surface: "surface-1",
-          reason: "command",
-        },
-      },
-      {
-        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,
+          text: "pnpm dev\n",
         },
       },
       {
@@ -563,17 +525,12 @@ describe("cmux sdk", () => {
         params: "workspace-1",
       },
     ]);
-    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",
+      "cmux: ssh",
+      "cmux: newSurface",
+      "cmux: newSurface",
+      "cmux: send",
+      "cmux: selectWorkspace",
     ]);
   });
 
@@ -581,11 +538,12 @@ describe("cmux sdk", () => {
     const calls: Array<{ method: string; params: unknown }> = [];
     const client = fakeOpenClient(calls);
 
-    await openCmux({
-      name: "website",
-      ssh: {
+    await callCmux({
+      method: "ssh",
+      params: {
         kind: "ssh",
         destination: "vm_123,token_123@vm-ssh.freestyle.sh",
+        name: "website",
         terminalStartupCommand: "ssh -tt vm_123:token_123@vm-ssh.freestyle.sh",
       },
     }, { client });
@@ -600,7 +558,7 @@ describe("cmux sdk", () => {
     });
   });
 
-  test("exposes a provider facade that requests cmux.open from the local host", async () => {
+  test("exposes a provider facade that requests raw cmux calls from the local host", async () => {
     const definition = cmux.provider();
     expect(definition.providerId).toBe("cmux");
     expect(definition.plugin).toBe(cmuxProviderPlugin);
@@ -624,77 +582,72 @@ describe("cmux sdk", () => {
         open: async () => {},
         requestCapability: async <Result,>(capability: string, params: unknown, options: unknown) => {
           requests.push({ capability, params, options });
+          const method = (params as { method?: string }).method;
+          if (method === "newSurface") {
+            return { surface: "surface-1", pane: "pane-1" } as Result;
+          }
+          if (method === "send") return "OK" as Result;
           return { sessionId: "workspace-1", workspaceId: "workspace-1" } as Result;
         },
       },
     }) as CmuxRuntime;
 
-    const session = await runtime.open({ name: "workspace" });
+    const workspace = await runtime.ssh({
+      destination: "vm_123,token_123@vm-ssh.freestyle.sh",
+      name: "workspace",
+    });
+    const terminal = await runtime.newSurface({
+      workspace: workspace.workspaceId,
+      type: "terminal",
+      focus: true,
+    });
+    await runtime.send({
+      workspace: workspace.workspaceId,
+      surface: terminal.surfaceId,
+      text: "git status\n",
+    });
 
     expect(requests).toEqual([
       {
-        capability: "cmux.open",
-        params: { name: "workspace" },
+        capability: "cmux.call",
+        params: {
+          method: "ssh",
+          params: {
+            destination: "vm_123,token_123@vm-ssh.freestyle.sh",
+            name: "workspace",
+          },
+        },
         options: { nodePath: "operation.open" },
       },
-    ]);
-    expect(session.sessionId).toBe("workspace-1");
-
-    let closed = false;
-    void session.closed.then(() => {
-      closed = true;
-    });
-    await Bun.sleep(5);
-    expect(closed).toBe(false);
-  });
-
-  test("uses host capability close reporting when the runtime provides it", async () => {
-    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({
-      workflow: "test",
-      nodePath: "operation.open",
-      emit: () => {},
-      interaction: {
-        present: async <Result,>() => undefined as Result,
+      {
+        capability: "cmux.call",
+        params: {
+          method: "newSurface",
+          params: {
+            workspace: "workspace-1",
+            type: "terminal",
+            focus: true,
+          },
+        },
+        options: { nodePath: "operation.open" },
       },
-      metadata: () => {},
-      local: {
-        open: async () => {},
-        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) => {
-              resolveClosed = resolve;
-            }),
-          };
+      {
+        capability: "cmux.call",
+        params: {
+          method: "send",
+          params: {
+            workspace: "workspace-1",
+            surface: "surface-1",
+            text: "git status\n",
+          },
         },
+        options: { nodePath: "operation.open" },
       },
-    }) as CmuxRuntime;
-
-    const session = await runtime.open({ name: "workspace" });
-    let closed = false;
-    void session.closed.then(() => {
-      closed = true;
-    });
-
-    await Bun.sleep(5);
-    expect(closed).toBe(false);
-    resolveClosed();
-    await session.closed;
-    expect(closed).toBe(true);
+    ]);
   });
 });
 
-function fakeOpenClient(calls: Array<{ method: string; params: unknown }>): CmuxOpenClient {
+function fakeOpenClient(calls: Array<{ method: string; params: unknown }>): CmuxCallClient {
   let terminalPaneIndex = 0;
   return {
     async newWorkspace(params) {

package/src/index.ts

@@ -492,26 +492,32 @@ export function formatShellCommand(args: readonly string[]): string {
 
 export { RIGKIT_PROVIDER_CMUX_VERSION } from "./version.ts";
 export {
-  CMUX_OPEN_CAPABILITY,
-  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,
+  CMUX_CALL_CAPABILITY,
+  CMUX_CALL_CAPABILITY_ID,
+  CMUX_CALL_SCHEMA_HASH,
+  type CmuxBrowserOpenInput,
+  type CmuxCallInput,
+  type CmuxCallMethod,
+  type CmuxNewPaneInput,
+  type CmuxNewSurfaceInput,
+  type CmuxPaneDirection,
+  type CmuxPaneResult,
+  type CmuxPortsKickInput,
+  type CmuxRemoteReadyInput,
+  type CmuxSendInput,
+  type CmuxSshInput,
+  type CmuxSurfaceType,
+  type CmuxWorkspaceInput,
+  type CmuxWorkspaceResult,
 } from "./capabilities.ts";
 export {
   CMUX_PROVIDER_ID,
   cmux,
   cmuxProviderPlugin,
   provider as defineCmuxProvider,
-  parseCmuxOpenResult,
-  requestCmuxOpen,
+  parseCmuxPaneResult,
+  parseCmuxWorkspaceResult,
+  requestCmuxCall,
   type CmuxProviderDefinition,
   type CmuxRuntime,
 } from "./provider.ts";

package/src/provider.ts

@@ -5,17 +5,33 @@ import {
 } from "@rigkit/sdk";
 import type { BaseProviderPlugin, WorkflowProviderController } from "@rigkit/engine";
 import {
-  CMUX_OPEN_CAPABILITY_ID,
-  type CmuxOpenInput,
-  type CmuxOpenPaneResult,
-  type CmuxOpenResult,
-  type CmuxOpenSession,
+  CMUX_CALL_CAPABILITY_ID,
+  type CmuxBrowserOpenInput,
+  type CmuxCallInput,
+  type CmuxNewPaneInput,
+  type CmuxNewSurfaceInput,
+  type CmuxPaneResult,
+  type CmuxPortsKickInput,
+  type CmuxRemoteReadyInput,
+  type CmuxSendInput,
+  type CmuxSshInput,
+  type CmuxWorkspaceInput,
+  type CmuxWorkspaceResult,
 } from "./capabilities.ts";
 
 export const CMUX_PROVIDER_ID = "cmux";
 
 export type CmuxRuntime = {
-  open(input: CmuxOpenInput): Promise<CmuxOpenSession>;
+  call(input: CmuxCallInput): Promise<unknown>;
+  newWorkspace(input?: CmuxWorkspaceInput): Promise<CmuxWorkspaceResult>;
+  ssh(input: CmuxSshInput): Promise<CmuxWorkspaceResult>;
+  newPane(input?: CmuxNewPaneInput): Promise<CmuxPaneResult>;
+  newSurface(input?: CmuxNewSurfaceInput): Promise<CmuxPaneResult>;
+  browserOpen(input?: CmuxBrowserOpenInput): Promise<CmuxPaneResult>;
+  send(input: CmuxSendInput): Promise<string>;
+  portsKick(input: CmuxPortsKickInput): Promise<string>;
+  selectWorkspace(workspace: string): Promise<void>;
+  waitForRemoteReady(input: CmuxRemoteReadyInput): Promise<unknown>;
 };
 
 export type CmuxProviderDefinition = WorkflowProviderDefinition<
@@ -45,75 +61,69 @@ export const cmuxProviderPlugin: BaseProviderPlugin = {
 };
 
 function createCmuxRuntime(local: LocalWorkspaceRuntime, nodePath: string): CmuxRuntime {
+  const request = (method: CmuxCallInput["method"], params?: Record<string, unknown>) =>
+    requestCmuxCall(local, { method, ...(params ? { params } : {}) }, { nodePath });
+
   return {
-    open: async (input) => await requestCmuxOpen(local, input, { nodePath }),
+    call: async (input) => await requestCmuxCall(local, input, { nodePath }),
+    newWorkspace: async (input = {}) =>
+      parseCmuxWorkspaceResult(await request("newWorkspace", input)),
+    ssh: async (input) =>
+      parseCmuxWorkspaceResult(await request("ssh", typeof input === "string" ? { destination: input } : input)),
+    newPane: async (input = {}) => parseCmuxPaneResult(await request("newPane", input)),
+    newSurface: async (input = {}) => parseCmuxPaneResult(await request("newSurface", input)),
+    browserOpen: async (input = {}) => parseCmuxPaneResult(await request("browserOpen", input)),
+    send: async (input) => String(await request("send", input)),
+    portsKick: async (input) => String(await request("portsKick", input)),
+    selectWorkspace: async (workspace) => {
+      await request("selectWorkspace", { workspace });
+    },
+    waitForRemoteReady: async (input) => await request("waitForRemoteReady", input),
   };
 }
 
-export async function requestCmuxOpen(
+export async function requestCmuxCall(
   local: LocalWorkspaceRuntime,
-  input: CmuxOpenInput,
+  input: CmuxCallInput,
   options: { nodePath?: string } = {},
-): Promise<CmuxOpenSession> {
-  if (local.requestCapabilitySession) {
-    const session = await local.requestCapabilitySession<CmuxOpenResult>(CMUX_OPEN_CAPABILITY_ID, input, options);
-    return {
-      ...parseCmuxOpenResult(session.result),
-      closed: session.closed,
-    };
-  }
+): Promise<unknown> {
   if (!local.requestCapability) {
-    throw new Error(`Host capability ${CMUX_OPEN_CAPABILITY_ID} is unavailable in this runtime`);
+    throw new Error(`Host capability ${CMUX_CALL_CAPABILITY_ID} is unavailable in this runtime`);
   }
-  const result = parseCmuxOpenResult(
-    await local.requestCapability(CMUX_OPEN_CAPABILITY_ID, input, options),
-  );
-  return {
-    ...result,
-    closed: new Promise<void>(() => {}),
-  };
+  return await local.requestCapability(CMUX_CALL_CAPABILITY_ID, input, options);
 }
 
-export function parseCmuxOpenResult(value: unknown): CmuxOpenResult {
-  if (!isRecord(value)) throw new Error(`cmux.open returned a non-object result`);
-  const sessionId = stringField(value, "sessionId");
-  if (!sessionId) throw new Error(`cmux.open result is missing sessionId`);
-  const workspaceId = stringField(value, "workspaceId") ?? sessionId;
+export function parseCmuxWorkspaceResult(value: unknown): CmuxWorkspaceResult {
+  if (!isRecord(value)) throw new Error(`cmux.call returned a non-object workspace result`);
+  const workspaceId = stringField(value, "workspaceId") ?? stringField(value, "id") ?? stringField(value, "handle");
+  if (!workspaceId) throw new Error(`cmux.call workspace result is missing workspace id`);
   return {
-    sessionId,
+    sessionId: stringField(value, "sessionId") ?? workspaceId,
     workspaceId,
-    ...optionalStringField(value, "workspaceRef"),
-    terminalPanes: arrayField(value, "terminalPanes", parseCmuxOpenPaneResult),
-    ...(value.browserPane !== undefined ? { browserPane: parseCmuxOpenPaneResult(value.browserPane) } : {}),
+    ...(stringField(value, "workspaceRef") ?? stringField(value, "ref")
+      ? { workspaceRef: stringField(value, "workspaceRef") ?? stringField(value, "ref") }
+      : {}),
   };
 }
 
-function parseCmuxOpenPaneResult(value: unknown): CmuxOpenPaneResult {
-  if (!isRecord(value)) throw new Error(`cmux.open returned a non-object pane result`);
+export function parseCmuxPaneResult(value: unknown): CmuxPaneResult {
+  if (!isRecord(value)) throw new Error(`cmux.call returned a non-object pane result`);
   return {
-    ...optionalStringField(value, "paneId"),
-    ...optionalStringField(value, "paneRef"),
-    ...optionalStringField(value, "surfaceId"),
-    ...optionalStringField(value, "surfaceRef"),
+    ...(stringField(value, "paneId") ?? stringField(value, "pane")
+      ? { paneId: stringField(value, "paneId") ?? stringField(value, "pane") }
+      : {}),
+    ...(stringField(value, "paneRef") ?? stringField(value, "paneRef")
+      ? { paneRef: stringField(value, "paneRef") ?? stringField(value, "paneRef") }
+      : {}),
+    ...(stringField(value, "surfaceId") ?? stringField(value, "surface")
+      ? { surfaceId: stringField(value, "surfaceId") ?? stringField(value, "surface") }
+      : {}),
+    ...(stringField(value, "surfaceRef") ?? stringField(value, "surfaceRef")
+      ? { surfaceRef: stringField(value, "surfaceRef") ?? stringField(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 } : {};
-}
-
 function stringField(record: Record<string, unknown>, key: string): string | undefined {
   const value = record[key];
   return typeof value === "string" && value.trim() !== "" ? value : undefined;

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_PROVIDER_CMUX_VERSION = "0.2.13";
+export const RIGKIT_PROVIDER_CMUX_VERSION = "0.2.14";