|
| 1 | +# Plan: Fix Default Agent Not Applied in Shuvcode (Issue #255) |
| 2 | + |
| 3 | +**Issue:** [#255 - Default agent does not apply in shuvcode](https://github.com/Latitudes-Dev/shuvcode/issues/255) |
| 4 | +**Created:** 2026-01-03 |
| 5 | +**Author:** iamhenry |
| 6 | +**Priority:** High (Bug) |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Problem Statement |
| 11 | + |
| 12 | +The `default_agent` configuration option is not respected in the shuvcode TUI. When a user sets a custom default agent (e.g., `"orchestrator"`) in their config, the TUI always starts with the first agent in the list (typically `"build"`) instead of the configured default. |
| 13 | + |
| 14 | +### User Report |
| 15 | + |
| 16 | +> In my config I have the `orchestrator` custom agent set as my default and it works as expected in opencode. However in shuvcode it always starts with the `build` agent and doesnt respect the config. |
| 17 | +
|
| 18 | +```json |
| 19 | +"default_agent": "orchestrator" |
| 20 | +``` |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## Root Cause Analysis |
| 25 | + |
| 26 | +### The Bug |
| 27 | + |
| 28 | +The TUI's local context initializes the current agent using the first agent in the list rather than checking for the `default` property that's set by the Agent module based on the user's `default_agent` configuration. |
| 29 | + |
| 30 | +**Location:** `packages/opencode/src/cli/cmd/tui/context/local.tsx:42` |
| 31 | + |
| 32 | +**Current (Buggy) Code:** |
| 33 | +```typescript |
| 34 | +const [agentStore, setAgentStore] = createStore<{ |
| 35 | + current: string |
| 36 | +}>({ |
| 37 | + current: agents()[0].name, // <-- Always uses first agent |
| 38 | +}) |
| 39 | +``` |
| 40 | + |
| 41 | +### How It Should Work |
| 42 | + |
| 43 | +1. User sets `default_agent: "orchestrator"` in their `opencode.json` |
| 44 | +2. The `Agent.state()` function in `packages/opencode/src/agent/agent.ts:269-279` marks the configured agent with `default: true` |
| 45 | +3. The TUI should look for an agent with `default: true` and use that as the initial selection |
| 46 | +4. If no default is found, fall back to the first agent |
| 47 | + |
| 48 | +### Upstream Fix |
| 49 | + |
| 50 | +This issue was fixed in upstream opencode in commit `8f6c8844d` (PR #5843): |
| 51 | + |
| 52 | +**Fixed Code:** |
| 53 | +```typescript |
| 54 | +const [agentStore, setAgentStore] = createStore<{ |
| 55 | + current: string |
| 56 | +}>({ |
| 57 | + current: agents().find((x) => x.default)?.name ?? agents()[0].name, |
| 58 | +}) |
| 59 | +``` |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +## Technical Context |
| 64 | + |
| 65 | +### Agent Default Property Flow |
| 66 | + |
| 67 | +1. **Config Schema** (`packages/opencode/src/config/config.ts:722-727`): |
| 68 | + ```typescript |
| 69 | + default_agent: z |
| 70 | + .string() |
| 71 | + .optional() |
| 72 | + .describe( |
| 73 | + "Default agent to use when none is specified. Must be a primary agent. Falls back to 'build' if not set or if the specified agent is invalid.", |
| 74 | + ), |
| 75 | + ``` |
| 76 | + |
| 77 | +2. **Agent State Processing** (`packages/opencode/src/agent/agent.ts:269-279`): |
| 78 | + ```typescript |
| 79 | + // Mark the default agent |
| 80 | + const defaultName = cfg.default_agent ?? "build" |
| 81 | + const defaultCandidate = result[defaultName] |
| 82 | + if (defaultCandidate && defaultCandidate.mode !== "subagent") { |
| 83 | + defaultCandidate.default = true |
| 84 | + } else { |
| 85 | + // Fall back to "build" if configured default is invalid |
| 86 | + if (result["build"]) { |
| 87 | + result["build"].default = true |
| 88 | + } |
| 89 | + } |
| 90 | + ``` |
| 91 | + |
| 92 | +3. **Server-side Default Agent** (`packages/opencode/src/agent/agent.ts:300-304`): |
| 93 | + ```typescript |
| 94 | + export async function defaultAgent(): Promise<string> { |
| 95 | + const agents = await state() |
| 96 | + const defaultCandidate = Object.values(agents).find((a) => a.default) |
| 97 | + return defaultCandidate?.name ?? "build" |
| 98 | + } |
| 99 | + ``` |
| 100 | + |
| 101 | +### Agent Info Type |
| 102 | + |
| 103 | +The `Agent.Info` type includes a `default?: boolean` property that gets set when the agent matches the configured `default_agent`. |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## Implementation Plan |
| 108 | + |
| 109 | +### Task 1: Apply the TUI Fix |
| 110 | + |
| 111 | +- [ ] **1.1** Modify `packages/opencode/src/cli/cmd/tui/context/local.tsx` line 42 |
| 112 | + - Change: `current: agents()[0].name,` |
| 113 | + - To: `current: agents().find((x) => x.default)?.name ?? agents()[0].name,` |
| 114 | + |
| 115 | +### Task 2: Add Unit Tests |
| 116 | + |
| 117 | +- [ ] **2.1** Create new test file or extend `packages/opencode/test/agent/agent.test.ts` |
| 118 | + - Add test: "default_agent config sets default property on specified agent" |
| 119 | + - Add test: "default_agent falls back to build when invalid agent specified" |
| 120 | + - Add test: "defaultAgent() returns configured default agent name" |
| 121 | + |
| 122 | +- [ ] **2.2** Example test cases: |
| 123 | + ```typescript |
| 124 | + test("default_agent config sets default property on specified agent", async () => { |
| 125 | + await using tmp = await tmpdir({ |
| 126 | + init: async (dir) => { |
| 127 | + const opencodeDir = path.join(dir, ".opencode") |
| 128 | + await fs.mkdir(opencodeDir, { recursive: true }) |
| 129 | + const agentDir = path.join(opencodeDir, "agent") |
| 130 | + await fs.mkdir(agentDir, { recursive: true }) |
| 131 | + |
| 132 | + // Create custom agent |
| 133 | + await Bun.write( |
| 134 | + path.join(agentDir, "orchestrator.md"), |
| 135 | + `--- |
| 136 | + model: test/model |
| 137 | + mode: primary |
| 138 | + --- |
| 139 | + Orchestrator agent prompt`, |
| 140 | + ) |
| 141 | + |
| 142 | + // Set as default |
| 143 | + await Bun.write( |
| 144 | + path.join(dir, "opencode.json"), |
| 145 | + JSON.stringify({ |
| 146 | + $schema: "https://opencode.ai/config.json", |
| 147 | + default_agent: "orchestrator", |
| 148 | + }), |
| 149 | + ) |
| 150 | + }, |
| 151 | + }) |
| 152 | + await Instance.provide({ |
| 153 | + directory: tmp.path, |
| 154 | + fn: async () => { |
| 155 | + const agents = await Agent.list() |
| 156 | + const orchestrator = agents.find((a) => a.name === "orchestrator") |
| 157 | + expect(orchestrator?.default).toBe(true) |
| 158 | + |
| 159 | + const build = agents.find((a) => a.name === "build") |
| 160 | + expect(build?.default).toBeFalsy() |
| 161 | + |
| 162 | + const defaultName = await Agent.defaultAgent() |
| 163 | + expect(defaultName).toBe("orchestrator") |
| 164 | + }, |
| 165 | + }) |
| 166 | + }) |
| 167 | + ``` |
| 168 | + |
| 169 | +### Task 3: Verify Related Code Paths |
| 170 | + |
| 171 | +- [ ] **3.1** Review other locations where agent initialization happens: |
| 172 | + - `packages/opencode/src/cli/cmd/run.ts` - CLI run command |
| 173 | + - `packages/opencode/src/cli/cmd/github.ts` - GitHub integration |
| 174 | + - `packages/opencode/src/session/prompt.ts` - Session prompts |
| 175 | + - `packages/opencode/src/acp/agent.ts` - ACP agent handling |
| 176 | + |
| 177 | +- [ ] **3.2** Ensure all paths use `Agent.defaultAgent()` or check the `default` property |
| 178 | + |
| 179 | +### Task 4: Testing & Validation |
| 180 | + |
| 181 | +- [ ] **4.1** Run type checking: `bun turbo typecheck` |
| 182 | +- [ ] **4.2** Run test suite: `bun test` in `packages/opencode` |
| 183 | +- [ ] **4.3** Manual testing: |
| 184 | + - Create a custom agent file in `.opencode/agent/` |
| 185 | + - Set `default_agent` in `opencode.json` |
| 186 | + - Launch TUI with `bun dev` |
| 187 | + - Verify the configured agent is selected on startup |
| 188 | + - Verify agent cycling (`tab`/`shift+tab`) works correctly |
| 189 | + |
| 190 | +--- |
| 191 | + |
| 192 | +## File References |
| 193 | + |
| 194 | +### Internal Files to Modify |
| 195 | + |
| 196 | +| File | Line(s) | Change Description | |
| 197 | +|------|---------|-------------------| |
| 198 | +| `packages/opencode/src/cli/cmd/tui/context/local.tsx` | 42 | Fix initial agent selection | |
| 199 | +| `packages/opencode/test/agent/agent.test.ts` | New | Add default_agent tests | |
| 200 | + |
| 201 | +### Internal Files for Reference (No Changes) |
| 202 | + |
| 203 | +| File | Purpose | |
| 204 | +|------|---------| |
| 205 | +| `packages/opencode/src/agent/agent.ts:269-304` | Agent default marking & defaultAgent() function | |
| 206 | +| `packages/opencode/src/config/config.ts:722-727` | default_agent config schema | |
| 207 | +| `packages/opencode/src/session/prompt.ts:730,1374,1536` | Uses Agent.defaultAgent() | |
| 208 | +| `packages/opencode/src/server/server.ts:503-504,1154,1158` | Uses Agent.defaultAgent() | |
| 209 | +| `packages/opencode/src/acp/agent.ts:709-710,812` | Uses Agent.defaultAgent() | |
| 210 | + |
| 211 | +### External References |
| 212 | + |
| 213 | +| URL | Description | |
| 214 | +|-----|-------------| |
| 215 | +| https://github.com/sst/opencode/commit/8f6c8844d | Upstream fix commit | |
| 216 | +| https://github.com/sst/opencode/pull/5843 | Upstream PR with full context | |
| 217 | + |
| 218 | +--- |
| 219 | + |
| 220 | +## Validation Criteria |
| 221 | + |
| 222 | +### Definition of Done |
| 223 | + |
| 224 | +1. **TUI respects `default_agent` config** - When launching the TUI, the configured default agent should be selected |
| 225 | +2. **Fallback works** - If `default_agent` is not set or invalid, the first agent should be selected |
| 226 | +3. **Tests pass** - All existing tests continue to pass |
| 227 | +4. **New tests added** - Tests cover the default_agent configuration and TUI initialization |
| 228 | +5. **Type check passes** - No TypeScript errors introduced |
| 229 | + |
| 230 | +### Test Commands |
| 231 | + |
| 232 | +```bash |
| 233 | +# Type check |
| 234 | +cd packages/opencode && bun run typecheck |
| 235 | + |
| 236 | +# Unit tests |
| 237 | +cd packages/opencode && bun test |
| 238 | + |
| 239 | +# Full turbo test |
| 240 | +bun turbo test |
| 241 | + |
| 242 | +# Manual TUI test |
| 243 | +cd packages/opencode && bun dev |
| 244 | +``` |
| 245 | + |
| 246 | +--- |
| 247 | + |
| 248 | +## Rollback Plan |
| 249 | + |
| 250 | +If the fix introduces regressions: |
| 251 | + |
| 252 | +1. Revert the single line change in `local.tsx` |
| 253 | +2. Return to: `current: agents()[0].name,` |
| 254 | + |
| 255 | +--- |
| 256 | + |
| 257 | +## Notes |
| 258 | + |
| 259 | +- This is a straightforward one-line fix from upstream |
| 260 | +- The server-side `Agent.defaultAgent()` function already works correctly |
| 261 | +- The bug is specifically in the TUI's client-side agent initialization |
| 262 | +- The fix aligns with how other parts of the codebase respect the default agent setting |
0 commit comments