feat(cli/sdk/mcp): ws create --command, agents create rename, terminals create

Merged
SA
5mo ago
+439-1091

Brings the Superset command surface (CLI / SDK / MCP-v2 — the mirror-trio) into a consistent shape around launching work in a workspace.

1. ws create --command

New --command <cmd> flag on superset ws create that runs a shell command in the freshly-spawned workspace, parallel to the existing --agent/--prompt flow.

superset workspaces create --project <id> --local --name "..." --branch <b> --command "bun install && bun test"
  • After the worktree is materialized (gated on !alreadyExists, like the setup terminal), startCommandTerminal opens a terminal session in the worktree running the command.
  • Independent of --agent/--prompt — pass either or both. Singular flag (chain steps with &&/;).
  • Mirrored in SDK (workspaces.create({ command })) and MCP (workspaces_create).

2. Rename agents run → agents create

CRUD-consistent verb; reads as the standalone form of ws create --agent.

  • User-facing only: CLI command, SDK agents.create() (+ AgentCreateParams/AgentCreateResult), MCP agents_create. The host-service wire procedure stays agents.run, so the desktop renderer and cloud dispatch are untouched and there's no CLI↔host relay version-skew risk.
  • Hard rename — no alias / deprecated shim (very few consumers).

3. Add terminals create

Standalone counterpart of ws create --command — creates a terminal session in a workspace, wrapping the existing host terminal.createSession procedure.

superset terminals create --workspace <id> --command "bun test"   # run a command
superset terminals create --workspace <id>                        # interactive shell
  • --command optional (bare shell if omitted); --cwd overrides the working dir.
  • New SDK terminals resource (terminals.create()) and MCP terminals_create tool.

After this, the inline sugar maps cleanly: ws create --agent ≈ agents create, ws create --command ≈ terminals create.

Docs

skills/superset/SKILL.md (agents/terminals sections + inline-form framing), packages/cli/CLI_SPEC_CURRENT.md (command tree), packages/sdk/api.md + README.md. Also retires CLI_SPEC_TARGET.md — the CLI implementation is now the spec.

Testing

  • bun run lint clean; bun run typecheck 28/28 (typed clients catch any missed rename).
  • Built the CLI and confirmed the command tree: agents create + agents list register, agents run is now unknown, terminals create registers with --workspace/--command/--cwd.
  • --command verified end-to-end earlier with a throwaway PTY integration test (command written to a PTY spawned with cwd = the new worktree, standalone and alongside an agent). terminals create/agents create are thin pass-throughs to existing host procedures (terminal.createSession / agents.run) already covered by host-service integration tests.

Note: one pre-existing real-daemon process-group test (terminal.integration.test.ts) flakes (3s timeout) in the sandbox; it imports only host-service internals, none of which this PR touches.

Summary by CodeRabbit

  • New Features

    • Run a one‑off shell command in a new workspace with --command.
    • Create terminal sessions in workspaces (CLI command with --command and --cwd, SDK and tooling support); alias "term" added.
    • Agents launch action renamed from “run” to “create” across CLI, SDK, and tooling.

  • Documentation

    • Updated CLI, SDK, MCP, and examples to cover terminals, --command/--cwd, and agents create workflows.