feat(cli): add per-launch agent reasoning effort

Merged
RO
3mo ago
+333-9

Summary

  • add --effort <level> to both superset agents create and superset workspaces create
  • carry the launch override through the TypeScript SDK and host service
  • validate agent-specific effort values before starting an agent or creating a worktree
  • document the supported levels and the default behavior across CLI and SDK
  • add focused CLI/host tests plus checked-in E2E evidence

UX contract

--effort is an explicit per-launch override. Omitting it passes no effort argument at all, so the underlying agent keeps its own configured default; Superset does not silently force medium.

The existing desktop New Workspace picker remains the visual launch control and continues to remember the last selection per agent. The CLI and SDK now expose the same underlying capability without introducing a second, potentially conflicting global default in Settings → Agents.

Invalid or unsupported values fail before side effects and report the choices for the selected agent.

End-to-end verification

Targeted the exact development instance for this worktree:

  • worktree: agent-thinking
  • desktop renderer: http://localhost:3105/#/workspaces
  • user journey: compiled CLI → local host service → new worktree → terminal agent → desktop workspace pane

Positive workspace lifecycle

Ran the compiled CLI with workspaces create --agent codex --effort high. It created a real worktree, launched Codex, and the desktop terminal showed both the high launch state and the E2E_WORKSPACE_EFFORT_OK response. The process argv independently contained -c model_reasoning_effort=high.

CLI-created Codex session showing high reasoning effort and the E2E marker

Desktop consistency

Opened the real New Workspace flow, selected Codex, and chose xHigh. This confirms the CLI addition uses the same agent-specific effort vocabulary already exposed by the installed desktop UI.

Desktop New Workspace flow with Codex and xHigh selected

Failure and default paths

  • agents create --agent codex --effort max failed with Unsupported reasoning effort and listed low, medium, high, xhigh.
  • workspaces create --agent codex --effort max failed before creating either the requested branch or workspace.
  • agents create --agent codex without --effort launched successfully; the observed process argv contained no model_reasoning_effort override.
  • workspaces create --agent codex --effort high returned a workspace and agent session, and the agent completed with the expected marker.

Automated gates

  • bun test packages/shared/src/agent-models.test.ts packages/host-service/src/trpc/router/agents/agents.test.ts packages/cli/src/commands/agents/create/command.test.ts packages/cli/src/commands/workspaces/create/command.test.ts — 42 passed
  • bun run lint — clean across 5,341 files
  • bun run typecheck — 35/35 tasks passed
  • bun run --filter @superset/cli build — passed
  • bun run --filter @superset/sdk build — ESM, CJS, and declaration build passed
  • GitHub CI — build, test, typecheck, lint, Sherif, version sync, and all three packaged CLI builds passed on this commit

Cleanup

After capture, the E2E workspace was deleted through the CLI, its test branch and empty worktree root were removed, all launched agents and dev servers were stopped, the disposable Docker stack and volume were deleted, the allocated port block was released, and generated auth/config/env files were removed.

Open in Stage

Summary by cubic

Adds a per-launch reasoning effort override to agent spawns across the CLI, SDK, and host. Users can set agent-specific levels or use the agent default; invalid values fail fast with clear choices, including during workspace creation.

  • New Features
    • CLI: superset agents create and superset workspaces create accept --effort <level>; on workspaces it requires --agent. Omitting --effort uses the agent’s default.
    • SDK: @superset/sdk adds optional effort to client.agents.create and to each agent entry in client.workspaces.create.
    • Host service: validates effort per agent (including rejecting overrides for agents that don’t support it), preflights effort during workspace creation to avoid side effects, and forwards valid values to the agent.
    • Docs: CLI and SDK refs updated with an “Agent effort levels” table per agent. Removed PR-evidence images.
    • Tests: added CLI and host tests for forwarding, omission, and validation paths.

Summary by CodeRabbit

  • New Features

    • Added an optional effort setting when launching agents through the CLI and SDK.
    • Workspace creation now supports configuring effort for spawned agents.
    • Supported effort levels vary by agent; omitted values use the agent default.
    • Invalid or unsupported effort settings are rejected with clear feedback.

  • Documentation

    • Updated CLI and SDK references with effort options, examples, supported levels, and usage requirements.
    • Added desktop product guidelines covering personas, design principles, branding, and accessibility.