Repository navigation
feat(cli): add per-launch agent reasoning effort - #5994
Merged
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughAdds optional agent reasoning-effort overrides across SDK and CLI APIs, validates supported values in the host service, checks workspace launches before dispatch, and updates related documentation. Also adds a desktop product specification. ChangesAgent effort override flow
Desktop product specification
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant CLI
participant SDK
participant HostService
participant AgentConfig
CLI->>SDK: create agent or workspace with effort
SDK->>HostService: send effort in launch payload
HostService->>AgentConfig: resolve supported effort levels
AgentConfig-->>HostService: return agent capability
HostService-->>CLI: accept launch or return validation error
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Ready to review this PR? Stage has broken it down into 5 individual chapters for you: 
Chapters generated by Stage for commit 25c72d5 on Jul 28, 2026 9:33pm UTC. |
Roshvan
marked this pull request as ready for review
July 27, 2026 19:41
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/cli/src/commands/workspaces/create/command.ts`:
- Around line 61-66: Update the validation around options.effort in the
workspace creation command to treat any value other than undefined, including an
explicitly empty string, as supplied; retain the !options.agent dependency check
and existing CLIError behavior.
In `@packages/host-service/src/trpc/router/agents/agents.ts`:
- Around line 177-225: Reject explicitly supplied empty effort values instead of
treating them as omitted: in validateAgentEffortSelection and
validateAgentLaunchEffort, return only when effort === undefined. Add a
regression assertion in
packages/host-service/src/trpc/router/agents/agents.test.ts lines 99-137 that
validateAgentEffortSelection("codex", "Codex", "") throws a BAD_REQUEST
TRPCError.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1ca16bbe-14e9-4bd6-af60-ae7f1ab181fb
⛔ Files ignored due to path filters (2)
apps/docs/public/images/cli/agent-reasoning-effort-cli-e2e.pngis excluded by!**/*.pngapps/docs/public/images/cli/agent-reasoning-effort-desktop.pngis excluded by!**/*.png
📒 Files selected for processing (15)
apps/desktop/PRODUCT.mdapps/docs/content/docs/cli/cli-reference.mdxapps/docs/content/docs/sdk/reference.mdxpackages/cli/src/commands/agents/create/command.test.tspackages/cli/src/commands/agents/create/command.tspackages/cli/src/commands/workspaces/create/command.test.tspackages/cli/src/commands/workspaces/create/command.tspackages/host-service/src/trpc/router/agents/agents.test.tspackages/host-service/src/trpc/router/agents/agents.tspackages/host-service/src/trpc/router/agents/index.tspackages/host-service/src/trpc/router/workspaces/workspaces.tspackages/sdk/api.mdpackages/sdk/src/resources/agents.tspackages/sdk/src/resources/workspaces.tspackages/sdk/tsconfig.json
Comment on lines
+61
to
+66
| if (options.effort && !options.agent) { | ||
| throw new CLIError( | ||
| "--effort requires --agent", | ||
| "Pass --agent <id> alongside --effort", | ||
| ); | ||
| } |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Treat an explicitly empty --effort as supplied.
--effort "" bypasses this truthiness check, so workspace creation proceeds without an agent instead of enforcing the documented dependency. Check for undefined and add an empty-value test.
Proposed fix
- if (options.effort && !options.agent) {
+ if (options.effort !== undefined && !options.agent) {📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| if (options.effort && !options.agent) { | |
| throw new CLIError( | |
| "--effort requires --agent", | |
| "Pass --agent <id> alongside --effort", | |
| ); | |
| } | |
| if (options.effort !== undefined && !options.agent) { | |
| throw new CLIError( | |
| "--effort requires --agent", | |
| "Pass --agent <id> alongside --effort", | |
| ); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/cli/src/commands/workspaces/create/command.ts` around lines 61 - 66,
Update the validation around options.effort in the workspace creation command to
treat any value other than undefined, including an explicitly empty string, as
supplied; retain the !options.agent dependency check and existing CLIError
behavior.
Comment on lines
+177
to
+225
| export function validateAgentEffortSelection( | ||
| presetId: string, | ||
| label: string, | ||
| effort: string | undefined, | ||
| ): void { | ||
| if (!effort) return; | ||
|
|
||
| const support = getAgentEffortSupport(presetId); | ||
| if (!support) { | ||
| throw new TRPCError({ | ||
| code: "BAD_REQUEST", | ||
| message: `${label} does not support a reasoning effort override. Omit effort to use the agent default.`, | ||
| }); | ||
| } | ||
|
|
||
| if (!support.efforts.some((option) => option.id === effort)) { | ||
| throw new TRPCError({ | ||
| code: "BAD_REQUEST", | ||
| message: `Unsupported reasoning effort "${effort}" for ${label}. Choose one of: ${support.efforts.map((option) => option.id).join(", ")}.`, | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Preflight a host-scoped launch before any larger workflow (such as | ||
| * workspace creation) performs side effects. | ||
| */ | ||
| export function validateAgentLaunchEffort( | ||
| db: HostDb, | ||
| input: Pick<AgentRunInput, "agent" | "effort">, | ||
| ): void { | ||
| if (!input.effort) return; | ||
| if (input.agent === SUPERSET_AGENT_ID) { | ||
| validateAgentEffortSelection( | ||
| SUPERSET_AGENT_ID, | ||
| SUPERSET_AGENT_LABEL, | ||
| input.effort, | ||
| ); | ||
| return; | ||
| } | ||
|
|
||
| const config = resolveHostAgentConfig(db, input.agent); | ||
| if (!config) { | ||
| throw new TRPCError({ | ||
| code: "NOT_FOUND", | ||
| message: `No host agent config matching '${input.agent}' (tried instance id then preset id).`, | ||
| }); | ||
| } | ||
| validateAgentEffortSelection(config.presetId, config.label, input.effort); |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Reject empty effort overrides rather than treating them as omitted.
Line 182 and Line 208 use if (!effort), so effort: "" bypasses validation. Treat only undefined as omission; then add a regression test for "".
packages/host-service/src/trpc/router/agents/agents.ts#L177-L225: replace both falsy guards withif (effort === undefined) return.packages/host-service/src/trpc/router/agents/agents.test.ts#L99-L137: assert thatvalidateAgentEffortSelection("codex", "Codex", "")throwsBAD_REQUEST.
Based on PR objectives: explicitly supplied effort values must be validated before side effects.
📍 Affects 2 files
packages/host-service/src/trpc/router/agents/agents.ts#L177-L225(this comment)packages/host-service/src/trpc/router/agents/agents.test.ts#L99-L137
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/host-service/src/trpc/router/agents/agents.ts` around lines 177 -
225, Reject explicitly supplied empty effort values instead of treating them as
omitted: in validateAgentEffortSelection and validateAgentLaunchEffort, return
only when effort === undefined. Add a regression assertion in
packages/host-service/src/trpc/router/agents/agents.test.ts lines 99-137 that
validateAgentEffortSelection("codex", "Codex", "") throws a BAD_REQUEST
TRPCError.
Contributor
Author
Kitenite
approved these changes
Jul 28, 2026
Kitenite
left a comment
Kitenite
left a comment
Member
There was a problem hiding this comment.
Reviewed and verified end to end:
- Unit tests: 42/42 pass across agent-models, host-service agents, and both CLI command test files.
- CLI smoke:
--effortpresent in help for both commands;--effortwithout--agentfails fast client-side with the hint, before any host call. - Live E2E against this branch's host-service (dev desktop + CDP): invalid effort (
bogus/turbo), effort on a non-supporting agent (Gemini), and effort on Superset chat all reject with the exact expected BAD_REQUEST messages — with zero side effects (no sessions, workspaces, or branches created).workspaces.createpreflight rejects before worktree creation. Positive path:agents.runwitheffort: lowspawned Claude with--effort lowin the real process argv. - Docs: effort table matches
AGENT_EFFORT_SUPPORTexactly. - sdk tsconfig
rootDir: verified load-bearing — declaration build fails with TS5011 without it.
Pushed a cleanup commit removing the unrelated apps/desktop/PRODUCT.md and the two PR-evidence PNGs (they were unreferenced by any docs page).
One deliberate behavior change worth noting for the record: an invalid persisted effort now hard-fails the launch instead of silently degrading to the agent default (buildAgentEffortArgs' degrade path is unreachable from these entry points). Acceptable — explicit is better here — but the degrade-to-default doc comment on buildAgentEffortArgs is now stale for these callers.
Neon deploy job failures are the standard fork-PR missing-secrets limitation, unrelated to this change.
2 tasks done
This branch had an error being deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--effort <level>to bothsuperset agents createandsuperset workspaces createUX contract
--effortis 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 forcemedium.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:
agent-thinkinghttp://localhost:3105/#/workspacesPositive 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 thehighlaunch state and theE2E_WORKSPACE_EFFORT_OKresponse. The process argv independently contained-c model_reasoning_effort=high.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.Failure and default paths
agents create --agent codex --effort maxfailed withUnsupported reasoning effortand listedlow, medium, high, xhigh.workspaces create --agent codex --effort maxfailed before creating either the requested branch or workspace.agents create --agent codexwithout--effortlaunched successfully; the observed process argv contained nomodel_reasoning_effortoverride.workspaces create --agent codex --effort highreturned 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 passedbun run lint— clean across 5,341 filesbun run typecheck— 35/35 tasks passedbun run --filter @superset/cli build— passedbun run --filter @superset/sdk build— ESM, CJS, and declaration build passedCleanup
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.
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.
superset agents createandsuperset workspaces createaccept--effort <level>; on workspaces it requires--agent. Omitting--effortuses the agent’s default.@superset/sdkadds optionalefforttoclient.agents.createand to each agent entry inclient.workspaces.create.Written for commit 25c72d5. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation