feat(cli/sdk/mcp): expose per-launch agent models

Merged
SH
2mo ago
+119-11

Summary

  • add --model <id> to superset agents create and superset workspaces create
  • forward per-launch model selection through the TypeScript SDK
  • expose the host's existing model and effort inputs in MCP agent and workspace launch tools
  • document the new CLI, SDK, and MCP surface

Why

The host service has supported per-launch model selection since #5248, using
the shared per-agent model registry to translate a model ID into the correct
flag or environment variable. Desktop can already use that path, but CLI, SDK,
and MCP callers cannot.

This change exposes the existing host behavior without duplicating model maps
or changing launch semantics. Omitting model still delegates to the agent's
configured default.

Since #6920, the host validates the id before launch: an unknown model fails
with a BAD_REQUEST naming every id the agent accepts, and an agent without a
model picker rejects the override. Nothing here re-implements that; the CLI,
SDK, and MCP surfaces just get the same error a desktop caller would.

This is a focused first slice of #5202. Agent-config CRUD and arbitrary
command/environment overrides remain out of scope.

CLI surface

$ superset agents create --help
  --model <string>  Model for this launch (agent-specific; omit to use the agent default)

$ superset workspaces create --help
  --model <string>  Model for the spawned agent (agent-specific; omit to use the agent default)

workspaces create --model requires --agent, matching the existing
--effort contract.

Testing

Rebased onto main on 2026-09-04 (conflicts with #6962 and #6990 were
additive neighbours). On the rebased branch:

  • bun test for agents create and workspaces create in packages/cli — 20 pass
  • tsc --noEmit clean for packages/cli, packages/mcp, packages/sdk
  • biome check clean on touched directories

Related issue

Progresses #5202.

Summary by cubic

Expose per-launch agent model selection in @superset/cli, @superset/sdk, and @superset/mcp so callers can choose a model per run. Previously only the host/Desktop path supported per-launch models; other surfaces always used the agent default. Omitting model still uses the agent’s default. Progresses #5202.

  • CLI: Add --model to superset agents create and superset workspaces create; require --agent when using --model; forward to host; tests and help updated.
  • SDK: Add optional model to agents.create and WorkspaceAgentLaunch; forward to host; api.md updated; no breaking changes.
  • MCP: Add optional model (and expose effort) in agents_create and workspaces_create tools; schema updated.
  • Docs: Document that model ids match the desktop picker, unknown ids are rejected before launch, and agents without a model picker reject explicit overrides.

Summary by CodeRabbit

  • New Features

    • Added optional per-launch model selection for agent sessions.
    • Added --model support to agent and workspace creation commands.
    • Added model override support to SDK and MCP interfaces.
    • Model values may use supported aliases or pinned IDs; omitted values use the agent default.
    • Added validation for unsupported models and overrides without an agent.

  • Documentation

    • Updated CLI, SDK, and MCP documentation with model and effort launch options, examples, and validation behavior.