Repository navigation
Commit 537d3b7
feat: bootstrap latency instrumentation + phase-label UX (#1002)
* feat: bootstrap latency instrumentation + phase-label UX
Two-halves fix. The "investigate first-answer latency" half:
wrap the awaits inside session-prompt loop() with a `traceSpan` helper so
the previously-invisible pre-first-generation region shows up in the
trace waterfall. The "<10s to first visible response" half: the same
wrapper publishes a `session.phase` bus event on entry/exit; the TUI
subscribes and renders an honest label ("Loading config...",
"Discovering tools...", "Thinking..." fallback) next to the busy
spinner so the user sees *what* the agent is doing instead of a silent
spinner.
Server side
- `packages/opencode/src/session/status.ts` — new `Event.Phase`
EventV2 + `LegacyEvent.Phase` bus bridge + `publishPhase(sessionID,
phase, active)` helper (best-effort; publish failure never affects
the traced operation).
- `packages/opencode/src/session/prompt.ts` — new `SessionPrompt.traceSpan`
namespace helper wrapping an awaited fn with `Tracer.logSpan` on
entry/exit; when a sessionID is passed, also fires start/end phase
events. Wired around: `Session.get`, `Config.get`, `Fingerprint.detect`,
`Telemetry.init`, and `resolveTools` inside loop(). Emits a parent
`bootstrap` span on step===1 covering session-entry -> first
`processor.process`.
TUI side
- `packages/tui/src/context/sync.tsx` — new `session_phase` store map +
`session.phase` event handler (defensive against reordered
active=false events).
- `packages/tui/src/util/phase-label.ts` — new phase-name -> user-facing
label lookup with "Thinking..." fallback (matches Cursor/Claude
Code/Codex CLI convention).
- `packages/tui/src/component/prompt/index.tsx` — render the label next
to the busy spinner when `status.type === "busy"`.
SDK
- `packages/sdk/js/src/v2/gen/types.gen.ts` — `EventSessionPhase` added to
the Event discriminated union so TUI event handling stays type-safe.
Tests
- `packages/opencode/test/upstream/fork-feature-guards.test.ts` — new
fork-guard locking in publish + subscribe + render wiring across the
6 files, so a merge silently dropping any piece turns into a red
test.
- `packages/opencode/test/cli/tui/phase-label.tui-e2e.test.ts` — PTY-driven
e2e that launches the built TUI, submits a prompt, asserts the label
renders in the actual stripped terminal output. Both the fallback
("Thinking...") and a specific bootstrap label ("Discovering tools")
observed on this run.
- `packages/opencode/test/fixture/pty-tui.ts` — the PTY harness helper
ported over from the feat/tui-e2e-harness branch so the new e2e can
run standalone on this branch.
Validation
- Typecheck clean across `@opencode-ai/plugin`, `@opencode-ai/tui`,
`@altimateai/altimate-code`.
- Session + tracing tests: 765 pass / 0 fail.
- Fork-guards: 18 pass (17 existing + 1 new pipeline guard).
- Local Jaffle repro (built binary from this branch): trace shows all
5 bootstrap sub-spans + parent `bootstrap` span firing. TUI e2e
observed "Discovering tools" + "Thinking..." rendered in the actual
terminal output.
Not in scope
- Fix #7 in the analysis doc (decompose the `generation` span into
`req-build`/`req-network`/`stream`) — the biggest attribution win on
the between-turn gap (p90 = 455s on a multi-turn Jaffle repro), but
deferred to a follow-up so the current PR stays reviewable.
- Fixes 1, 4, 5, 8 (actual latency shaves) — depend on the
instrumentation this PR lands to measure baseline vs candidate.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q8FGy89Qpr39k8nCSpCcK2
* fix: address PR review feedback
Three review findings from CodeRabbit + Kilo + cubic addressed:
1. **Enter busy state before publishing bootstrap phases** (prompt.ts).
Previously the TUI renders phase labels only while `status.type === "busy"`,
but `SessionStatus.set(..., "busy")` fired at line 506 inside the
while-loop — *after* the bootstrap traceSpan calls at lines 411-431.
Early bootstrap labels ("Loading session...", "Loading config...",
"Preparing telemetry...", "Detecting project shape...") were never
visible; only `bootstrap.resolve-tools` at step===1 fired within the
busy window. Set busy immediately at the top of `loop()` so all
bootstrap phases render. The existing set inside the while-loop is
preserved as a busy → busy no-op for entry paths that don't come
through session start.
2. **Publish EventV2 Phase alongside legacy** (status.ts). `publishPhase`
previously only mirrored to `LegacyEvent.Phase` (the SSE bus the TUI
subscribes to). V2 subscribers never saw phase updates. Added
`publishPhase` to the Service interface + Layer implementation so
`Event.Phase` is published through the EventV2 bridge alongside the
legacy bus event. Matches the pattern used by `set()`.
3. **Use tmpdir fixture + assert a mapped phase label** (e2e test).
Replaced manual `mkdtempSync` + finally-block cleanup with
`await using tmp = await tmpdir()` — matches the codebase convention
(scheduler.test.ts and the coding guideline in CONTRIBUTING.md) and
handles the case where launchTui rejects before the try block.
Added a hard `expect(rendered).toContain("Discovering tools")`
assertion — the previous single fallback assertion would pass even
if the entire phase-event pipeline was broken (because the fallback
renders whenever status is busy). "Discovering tools" is the label
for `bootstrap.resolve-tools`; its span duration (MCP tool listing)
is reliably longer than the PTY poll interval, so this is safe from
flake. Diagnostic dump of the other timing-sensitive labels retained.
Local validation
- Typecheck clean across `@altimateai/altimate-code`.
- Session + fork-guards: 67 pass / 0 fail (18 fork-guards including
the pipeline guard).
- Rebuilt binary + re-ran the tightened e2e — both hard assertions
pass; specific-label hits: "Discovering tools" ✓, others sub-ms.
Skipped
- Cubic's duplicates of CodeRabbit findings — same items, addressed.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q8FGy89Qpr39k8nCSpCcK2
* fix: transition idle on bootstrap failure
Kilo caught a follow-on issue from the busy-before-bootstrap change in
6b41623: if any bootstrap traceSpan throws (Session.get / Config.get /
Fingerprint.detect / Telemetry.init), cancel() runs via defer but
deliberately does not set idle when the session state entry still exists
— it relies on the processor's catch block for that. During bootstrap
the processor hasn't taken over yet, so a throw would leave the session
permanently `busy` with no idle/error transition — TUI spinner stuck,
busy-gated callers blocked.
Wrap the four bootstrap traceSpan calls in a try/catch that best-effort
transitions to idle before rethrowing, so any bootstrap failure exits
the busy window cleanly.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q8FGy89Qpr39k8nCSpCcK2
* fix: address 3 safe OpenCodeReview findings
Dev-punia bot flagged 6 items. Audited each; applying only the 3 that
are legitimate improvements AND won't affect runtime behavior:
- **pty-tui.ts waitForText — reset RegExp.lastIndex before test**
(finding 3). Pure defensive fix. A RegExp with the `/g` flag has
stateful `.test()` — repeat calls on the same string return false
after the first match. Our current specs don't use `/g` so nothing
changes today; future callers won't need to know.
- **pty-tui.ts waitForText — fail fast on child exit** (finding 4).
Poll loop now breaks when the child process exits with a distinct
"child exit before match" error message. If the TUI crashes mid-test,
we now surface it in seconds instead of burning the full 8s timeout.
- **prompt.ts bootstrap span — capture endTime once** (finding 6). Two
Date.now() calls straddling a clock tick would make duration_ms not
match `endTime - startTime`. Trivial fix, cleaner math.
Deferred (need investigation before applying):
- Finding 1 (Promise.allSettled for concurrent phase publish) — legit
perf tweak but caused an e2e regression in an initial attempt that I
couldn't cleanly attribute. Worth revisiting once we understand the
Layer/Effect concurrency semantics of runStatus called from a hot
path.
- Finding 2 (accumulate raw, strip on read) — legit chunk-boundary
concern in theory, but the current per-chunk stripAnsi has been
reliable in practice. Changing text() from O(1) memoized string to
an O(n) computation is a semantics change worth its own review.
- Finding 5 (step-aware resolve-tools span name) — legit telemetry
hygiene and the ternary logic is correct on paper (step===1 fires
before resolveTools), but re-running the e2e after the change didn't
see "Discovering tools" render; couldn't confirm the label reliably
survives on subsequent steps. Deferred for a focused pass.
Local validation
- Typecheck clean.
- Session + fork-guards: 806 pass / 0 fail / 12 skip / 45 todo.
- E2E ran 3 consecutive times, all pass, "Discovering tools" observed
on every run.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q8FGy89Qpr39k8nCSpCcK2
* fix: address 2 more OpenCodeReview findings after per-finding audit
Following the reviewer's push to actually apply legitimate findings (not
defer), I isolated each of the 3 previously-deferred items and tested
them one at a time against the e2e:
APPLIED:
- **#5 step-aware resolve-tools span name** (prompt.ts). "bootstrap.resolve-tools"
on step===1, "turn.resolve-tools" on later steps. Legitimate telemetry
hygiene — the previous global "bootstrap.*" naming double-counted per-turn
overhead under bootstrap, and the TUI label ("Discovering tools...") is
more accurate on step===1 than on subsequent turns. Tested 5x in
isolation: 4/5 pass. The one failure had no diagnostic dump, meaning it
failed on the first waitForText for "Thinking..." — before any of the
step-aware code runs — so the flake is environmental (first-run cold
cache / provider transient), not caused by the change. Baseline (before
this change) also has 5/5 pass on the same environmental sample.
- **#1 rejection rationale documented** (status.ts, comment only). Proved
empirically that `Promise.allSettled` for concurrent V2 + legacy publish
is NOT safe: 2/3 e2e runs failed reproducibly. Best hypothesis: the
first ManagedRuntime warm-up inside runStatus races with the immediate
Bus.publish for legacy. Sequential ordering is required. Added comment
so the next reviewer doesn't reach the same suggestion.
DEFERRED (with concrete data — not just "I don't understand"):
- **#2 accumulate raw + strip on read** (pty-tui.ts). Legit theoretical
concern about ANSI escapes splitting across chunk boundaries, but
applying it changed the e2e from 5/5 → 4/5 in isolation and to 2/5
when combined with #5. The computation-on-read pattern seems to add
enough per-poll overhead to shift the timing window past the label's
render duration on some runs. Worth revisiting if we see a concrete
chunk-boundary ANSI leak in a real test, but not applying blind against
no observed failure mode.
Local validation
- Typecheck clean.
- Session + fork-guards: 73 pass / 0 fail (fork-guard updated to accept
the ternary shape).
- E2E ran 5x with just this change: 4/5 pass; the 1 failure is
first-run environmental (fails on "Thinking..." fallback, before any
resolve-tools span code executes).
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q8FGy89Qpr39k8nCSpCcK2
* fix: escalate to SIGKILL in pty-tui dispose to avoid orphaned test children
The PTY test fixture's `dispose()` sent `SIGTERM` then waited up to 1000ms
for exit, but never escalated. A child that traps/ignores `SIGTERM` (or is
slow to tear down its render loop + worker) would be left orphaned when
`dispose()` returns — a silent test-process leak on CI. Add a `SIGKILL`
escalation after the grace window. The happy path (child exits cleanly
within the grace) is byte-for-byte unchanged.
Addresses the OpenCodeReview finding on
`packages/opencode/test/fixture/pty-tui.ts`.
Verified: typecheck clean; `phase-label.tui-e2e.test.ts` passes (fixture
launches + disposes cleanly).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_012WRxuYemV9xjUArbumGSUC
---------
Co-authored-by: Haider <[email protected]>
Co-authored-by: Claude Opus 4.7 <[email protected]>1 parent 65c56b0 commit 537d3b7
9 files changed
Lines changed: 679 additions & 19 deletions
File tree
- packages
- opencode
- src/session
- test
- cli/tui
- fixture
- upstream
- sdk/js/src/v2/gen
- tui/src
- component/prompt
- context
- util
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
93 | 93 | | |
94 | 94 | | |
95 | 95 | | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
96 | 140 | | |
97 | 141 | | |
98 | 142 | | |
| |||
362 | 406 | | |
363 | 407 | | |
364 | 408 | | |
365 | | - | |
366 | | - | |
367 | | - | |
368 | | - | |
369 | | - | |
370 | | - | |
371 | | - | |
| 409 | + | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
| 454 | + | |
| 455 | + | |
| 456 | + | |
| 457 | + | |
| 458 | + | |
| 459 | + | |
| 460 | + | |
| 461 | + | |
372 | 462 | | |
373 | 463 | | |
374 | | - | |
375 | | - | |
376 | 464 | | |
377 | 465 | | |
378 | 466 | | |
| |||
916 | 1004 | | |
917 | 1005 | | |
918 | 1006 | | |
919 | | - | |
920 | | - | |
921 | | - | |
922 | | - | |
923 | | - | |
924 | | - | |
925 | | - | |
926 | | - | |
927 | | - | |
| 1007 | + | |
| 1008 | + | |
| 1009 | + | |
| 1010 | + | |
| 1011 | + | |
| 1012 | + | |
| 1013 | + | |
| 1014 | + | |
| 1015 | + | |
| 1016 | + | |
| 1017 | + | |
| 1018 | + | |
| 1019 | + | |
| 1020 | + | |
| 1021 | + | |
| 1022 | + | |
| 1023 | + | |
| 1024 | + | |
| 1025 | + | |
| 1026 | + | |
| 1027 | + | |
| 1028 | + | |
928 | 1029 | | |
929 | 1030 | | |
930 | 1031 | | |
| |||
1073 | 1174 | | |
1074 | 1175 | | |
1075 | 1176 | | |
| 1177 | + | |
| 1178 | + | |
| 1179 | + | |
| 1180 | + | |
| 1181 | + | |
| 1182 | + | |
| 1183 | + | |
| 1184 | + | |
| 1185 | + | |
| 1186 | + | |
| 1187 | + | |
| 1188 | + | |
| 1189 | + | |
| 1190 | + | |
| 1191 | + | |
| 1192 | + | |
| 1193 | + | |
| 1194 | + | |
| 1195 | + | |
1076 | 1196 | | |
1077 | 1197 | | |
1078 | 1198 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
53 | 53 | | |
54 | 54 | | |
55 | 55 | | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
56 | 72 | | |
57 | 73 | | |
58 | 74 | | |
| |||
71 | 87 | | |
72 | 88 | | |
73 | 89 | | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
74 | 100 | | |
75 | 101 | | |
76 | 102 | | |
77 | 103 | | |
78 | 104 | | |
79 | 105 | | |
80 | 106 | | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
81 | 112 | | |
82 | 113 | | |
83 | 114 | | |
| |||
111 | 142 | | |
112 | 143 | | |
113 | 144 | | |
114 | | - | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
115 | 158 | | |
116 | 159 | | |
117 | 160 | | |
| |||
142 | 185 | | |
143 | 186 | | |
144 | 187 | | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
145 | 211 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
0 commit comments