|
1 | | -# Patched opencode: TUI subagent indicator |
| 1 | +# Patched opencode: TUI subagent indicator (sidecar) |
| 2 | + |
| 3 | +Local build of opencode that shows running background subagents in the TUI |
| 4 | +footer (e.g. `⏳ 2 subagents`). |
| 5 | + |
| 6 | +## Why this is structured the way it is |
| 7 | + |
| 8 | +The whole point of this patch is to be **dead-code-friendly when upstream |
| 9 | +ships a fix**. If `anomalyco/opencode` (or anyone) eventually adds their |
| 10 | +own subagent indicator — whether a `waiting` SessionStatus variant, a new |
| 11 | +event, or a tree view — our local patch should become inert without |
| 12 | +fights, not a permanent fork. |
| 13 | + |
| 14 | +To achieve that, the patch follows three rules: |
| 15 | + |
| 16 | +1. **No modifications to existing upstream types or interfaces.** Nothing in |
| 17 | + `packages/schema/src/session-status-event.ts`, |
| 18 | + `packages/core/src/background-job.ts`, or any existing service |
| 19 | + interface is touched. The `BackgroundJob.subscribe()` method we |
| 20 | + prototyped in v1 was removed. |
| 21 | +2. **All new code lives in new files** under `packages/schema/src/local-*` |
| 22 | + and `packages/opencode/src/local/`. The `local.` prefix on the event |
| 23 | + type (`local.subagent.indicator`) is intentional — it cannot collide |
| 24 | + with anything upstream picks. |
| 25 | +3. **Everything is gated by `experimental.localSubagentIndicator`** in |
| 26 | + `RuntimeFlags`. Off → sidecar is a no-op, no events fire, the TUI |
| 27 | + shows nothing from us. On → the sidecar runs. |
| 28 | + |
| 29 | +The TUI checks both `session.status` (upstream's) and |
| 30 | +`local_subagent_indicator` (ours). If upstream ships a `waiting` variant |
| 31 | +with the same field, both indicators will agree. If upstream ships |
| 32 | +something with a different shape, our footer just keeps reading from the |
| 33 | +local channel; the user disables the flag and we're invisible. |
| 34 | + |
| 35 | +## Architecture |
2 | 36 |
|
3 | | -Local build of opencode with a small TUI patch that shows running background |
4 | | -subagents in the footer (e.g. `⏳ 2 subagents`). |
5 | | - |
6 | | -## What's different |
7 | | - |
8 | | -When the parent session is idle but has background subagents running, the TUI |
9 | | -footer now shows a `⏳ N subagent(s)` indicator. Without this, the parent |
10 | | -session looks "idle" and it's unclear whether the main agent is still working |
11 | | -or whether it's actually waiting for subagents to finish. |
12 | | - |
13 | | -When the parent is busy (running a model itself), the busy state wins. |
14 | | -When all subagents finish, the indicator disappears and the parent goes idle. |
15 | | - |
16 | | -## Files touched |
17 | | - |
18 | | -- `packages/schema/src/session-status-event.ts` — new `waiting` status variant |
19 | | - with `subagents: number` |
20 | | -- `packages/core/src/background-job.ts` — PubSub-based lifecycle event bus |
21 | | - (started / settled / cancelled) |
22 | | -- `packages/opencode/src/background/job.ts` — wire up the new `subscribe()` |
23 | | - method |
24 | | -- `packages/opencode/src/session/run-state.ts` — subscriber that maintains a |
25 | | - per-parent running count and transitions SessionStatus accordingly |
26 | | -- `packages/tui/src/routes/session/footer.tsx` — render the indicator |
27 | | - |
28 | | -## Install / reinstall |
| 37 | +``` |
| 38 | + BackgroundJob.list() ─── sidecar (polls every 1s) ──> EventV2.publish |
| 39 | + │ |
| 40 | + ▼ |
| 41 | + TUI event listener ◄──── EventV2 stream ◄──── "local.subagent.indicator" |
| 42 | + │ |
| 43 | + ▼ |
| 44 | + sync store: local_subagent_indicator[sessionID] = { count } |
| 45 | + │ |
| 46 | + ▼ |
| 47 | + Footer renders: "⏳ N subagent(s)" when count > 0 |
| 48 | +``` |
29 | 49 |
|
30 | | -The patched binary is at: |
| 50 | +**Polling at 1 second** instead of subscribing to BackgroundJob events. |
| 51 | +This is intentional: it requires zero changes to `core/background-job.ts`. |
| 52 | +The cost is up to 1 second of staleness on the indicator — acceptable |
| 53 | +for a footer counter. |
| 54 | + |
| 55 | +## Files |
| 56 | + |
| 57 | +- `packages/schema/src/local-subagent-indicator-event.ts` — new event |
| 58 | + def: `local.subagent.indicator` with `{ sessionID, info: { count } }` |
| 59 | +- `packages/schema/src/event-manifest.ts` — adds the new event to the |
| 60 | + inventory (additive — only a new line) |
| 61 | +- `packages/opencode/src/effect/runtime-flags.ts` — adds the |
| 62 | + `experimentalLocalSubagentIndicator` flag (additive — new line) |
| 63 | +- `packages/opencode/src/local/subagent-indicator.ts` — **new file**, |
| 64 | + the sidecar service |
| 65 | +- `packages/opencode/src/server/server.ts` — wires the sidecar into the |
| 66 | + server layer composition (one new `Layer.provideMerge` line) |
| 67 | +- `packages/tui/src/context/sync.tsx` — adds the |
| 68 | + `local_subagent_indicator` field to the sync store (additive — new |
| 69 | + field, new line in initial state, new `event.on` listener) |
| 70 | +- `packages/tui/src/routes/session/footer.tsx` — renders the indicator |
| 71 | + (additive — new `<Show>` block, no changes to existing code paths) |
| 72 | + |
| 73 | +## Install / rebuild |
| 74 | + |
| 75 | +The patched binary lives at: |
31 | 76 |
|
32 | 77 | ``` |
33 | 78 | /var/home/thegalkin/opencode-tui-subagent-indicator/packages/opencode/dist/opencode-linux-x64/bin/opencode |
34 | 79 | ``` |
35 | 80 |
|
36 | | -A symlink in `~/bin/opencode` already points at it and wins over the |
37 | | -linuxbrew one (verified with `which opencode`). |
| 81 | +A symlink at `~/bin/opencode` already points at it and wins over the |
| 82 | +linuxbrew version (`which opencode` confirms). To revert, just delete |
| 83 | +the symlink — the linuxbrew opencode stays untouched. |
38 | 84 |
|
39 | 85 | To rebuild after editing source: |
40 | 86 |
|
41 | 87 | ```sh |
42 | 88 | cd /var/home/thegalkin/opencode-tui-subagent-indicator |
| 89 | +bun script/generate.ts # regen SDK |
43 | 90 | bunx [email protected] --bun packages/opencode/script/build.ts --single --skip-install --skip-embed-web-ui |
44 | 91 | ``` |
45 | 92 |
|
46 | | -The homebrew `opencode` is left untouched. To revert, just delete the symlink: |
| 93 | +## Enabling the indicator |
47 | 94 |
|
48 | | -```sh |
49 | | -rm ~/bin/opencode |
50 | | -``` |
51 | | - |
52 | | -## Enable background subagents |
53 | | - |
54 | | -This is a `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` feature. Set the |
55 | | -env var (in your shell rc, or per-invocation) when you want agents to be able |
56 | | -to call `task(background=true)`. |
| 95 | +Set the env var before launching opencode: |
57 | 96 |
|
58 | | -## Try it |
59 | | - |
60 | | -1. Open the TUI on any project: `opencode .` |
61 | | -2. Ask the main agent to spawn background subagents (e.g. "run 3 explore tasks |
62 | | - in parallel in the background and tell me when each one finishes") |
63 | | -3. Watch the bottom-right of the TUI: you'll see `⏳ 3 subagents` and the |
64 | | - count will drop as each subagent finishes |
65 | | - |
66 | | -## Upstream |
| 97 | +```sh |
| 98 | +# Either: enable only this feature |
| 99 | +export OPENCODE_EXPERIMENTAL_LOCAL_SUBAGENT_INDICATOR=true |
67 | 100 |
|
68 | | -The feature is requested in `anomalyco/opencode#23784`. A broader proposal |
69 | | -(`#32167`) was closed as too large. The patch on branch |
70 | | -`feat/tui-subagent-indicator` in `thegalkin/opencode` is a minimal slice of |
71 | | -that — schema-level waiting status + footer indicator only. |
| 101 | +# Or: enable the umbrella that turns on all experiments |
| 102 | +export OPENCODE_EXPERIMENTAL=true |
| 103 | +``` |
72 | 104 |
|
73 | | -To send upstream: open a PR with the existing branch and reference |
74 | | -`#23784` in the description so maintainers can route it through design review. |
| 105 | +(These are read from `RuntimeFlags` via the standard `enabledByExperimental` |
| 106 | +helper — the same mechanism used by `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` |
| 107 | +and friends.) |
| 108 | + |
| 109 | +When the flag is off, the sidecar layer is a no-op: no fiber starts, no |
| 110 | +BackgroundJob polling, no events fire. The TUI sees an empty |
| 111 | +`local_subagent_indicator` map and renders nothing extra. |
| 112 | + |
| 113 | +## Upstream behavior |
| 114 | + |
| 115 | +If/when `anomalyco/opencode` ships its own fix: |
| 116 | + |
| 117 | +- They likely use a different flag name → our flag stays meaningful, no |
| 118 | + conflict, the user can keep using our local version |
| 119 | +- They use the same flag name (`experimentalLocalSubagentIndicator`) → user |
| 120 | + turns our flag off, upstream's solution takes over |
| 121 | +- They add a different mechanism entirely (a `waiting` SessionStatus |
| 122 | + variant, a tree view, etc.) → user can keep both: our footer indicator |
| 123 | + shows the count, upstream's view shows the tree |
| 124 | +- They add a `local.subagent.indicator` event with a different payload |
| 125 | + shape → TS compile error on the TUI's `event.on("local.subagent.indicator", ...)` |
| 126 | + call. Fix: remove that line (or just disable the flag) |
| 127 | + |
| 128 | +In the worst case, removing our patch is `git rm packages/opencode/src/local/ |
| 129 | +packages/schema/src/local-subagent-indicator-event.ts` and reverting the |
| 130 | +~5 additive lines in `event-manifest.ts`, `runtime-flags.ts`, `server.ts`, |
| 131 | +`sync.tsx`, `footer.tsx`. |
| 132 | + |
| 133 | +## How to test |
| 134 | + |
| 135 | +1. Set the env var: `export OPENCODE_EXPERIMENTAL_LOCAL_SUBAGENT_INDICATOR=true` |
| 136 | +2. Open the TUI on any project: `opencode .` |
| 137 | +3. Ask the main agent to spawn background subagents, e.g.: |
| 138 | + "Run 3 explore tasks in parallel in the background and tell me when each |
| 139 | + one finishes" |
| 140 | +4. Watch the bottom-right of the TUI: `⏳ 3 subagents` appears, count |
| 141 | + drops as each subagent finishes, indicator disappears when all done |
| 142 | + |
| 143 | +If nothing shows up, check: |
| 144 | +- `opencode --version` returns `0.0.0-feat/tui-subagent-indicator-...` |
| 145 | +- The env var is set in the same shell as `opencode` |
| 146 | +- The main agent actually called the `task` tool with `background=true` |
| 147 | + (and `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` or the umbrella |
| 148 | + is set) |
0 commit comments