Repository navigation
spec(issue): labs show a failed turn inline with its reason and Retry (FIX-2550) #4725
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
b2995e1
spec(issue): labs show a failed turn inline with its reason and Retry…
claude 8c1896f
spec(FIX-2550): E3 states what the no-key reason actually reads
claude f7757c5
spec(FIX-2550): one owner for the newest turn; review round 1
claude 12f81be
FIX-2550 spec: Retry only on turns the engine will retry; retried rep…
claude 577acca
Merge remote-tracking branch 'origin/main' into spec/FIX-2550
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # FIX-2550 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** | ||
|
|
||
| FIX-2370's decisions hold: one registry component with plain props and an `onRetry` callback | ||
| ([its D1](../FIX-2370/DECISIONS.md#d1)), sharing `error.tsx`'s body ([its D2](../FIX-2370/DECISIONS.md#d2)). | ||
| The two below are what the labs' code had to add. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · Retry is a new adapter verb | ||
|
|
||
| | | `adapter.retry(sessionId, requestId)` (chosen) | The screen calls the client | Retry through `send` with the old line | | ||
| |---|---|---|---| | ||
| | Keeps the lab rule "nothing in `src/` but the adapter touches a package" | yes | no | yes | | ||
| | Runs the same request again (same input, `retryOf` recorded) | yes | yes | no: a new turn with a copied line | | ||
| | The fakes can stand in for it | yes, one more verb | no | yes | | ||
|
|
||
| - **Instead of** the screen reaching the client: both labs route every package call through | ||
| their adapter, and the screen tests run on a fake of it. | ||
| - **Instead of** re-sending the user's line: that is a new turn, not a retry, and loses the | ||
| link the engine keeps between the two requests. | ||
| - **Locks in:** one more verb on each `LabAdapter`, and on each fake. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · "Newest turn" is read from the thread's items | ||
|
|
||
| - The adapter marks a failed entry `retryable` when it is the newest turn, the request of the | ||
| last entry the thread draws, and the engine will retry that request: one whose source is | ||
| `http`, `mcp` or `scheduled` (the engine's public re-entry sources; a record with no source | ||
| came in over `http`). The screen passes `onRetry` only for that entry, and only while no turn | ||
| runs. | ||
| - **Instead of** reading the newest request alone: the thread's entries already order the | ||
| turns, and a request that drew nothing (a board pass in Teammates) is not a turn the person | ||
| saw. The session's recent requests are read only for their source. | ||
| - **Why the source rule:** the engine refuses a retry of a request a task or the flow itself | ||
| started (`internal`, `task`). A worker answering another worker's message runs in its own | ||
| conversation with source `internal`, so without the rule its failed turn would offer a | ||
| Retry that can only fail. Each lab pins its list to the engine's in a test. | ||
| - **Who owns what:** `retryable` is the adapter's answer, and the only one; the screen never | ||
| recomputes it. The screen's own rule is only "no Retry while a turn runs". The adapter's | ||
| tests cover `retryable`; the screen's cover that `onRetry` follows it. | ||
| - **Not a bug:** Retry can show on the thread's newest turn while the session's newest request | ||
| is a board pass. That is the intended reading, and the retry still succeeds. | ||
| - **Locks in:** Retry follows what the person sees as the last turn. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **E1 · Who the line names.** Claude Code-style: *The main session*, the words the lab already | ||
| uses for it. Teammates: the worker's name. | ||
| - **E2 · Incomplete** is a small muted *Incomplete* under the half reply, in each lab's own entry | ||
| markup. It is a mark on an existing entry, not a second failure line. | ||
| - **E3 · No startup key warning.** FIX-2370's slice text also asked each lab's host to log one | ||
| when no model key is set. The failed-turn line now carries the provider's own reason at the | ||
| moment it matters (the AI Gateway's says "set the AI_GATEWAY_API_KEY environment variable"), | ||
| and FIX-2406 is moving the Claude Code-style host into `host.mts`. Left out to keep this one PR | ||
| off that file. That gateway message arrives with terminal colour codes in its text, which | ||
| every surface that shows an error would print; that is a package fix, filed on its own. | ||
| - **E4 · A task's own run** (the task view in Claude Code-style) shows its failure line too, with | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| no Retry: a failed task is retried from its row, which already has the button. | ||
| - **E5 · Wording.** The line's words are the component's; neither lab adds copy that names a role. | ||
|
|
||
| ## Notes from review | ||
|
|
||
| Round 1 (2026-11-04): Codex, no findings. Cursor (simplify): the one real point, that the spec | ||
| named two owners for "newest", is folded into D2 and the debt line. Recorded, not folded: | ||
| *failed* rather than FIX-2370's "error entry" is kept, since it matches the component's | ||
| `data-state="failed"` and the engine's request status, and Teammates' task `result.failed` is a | ||
| flag on another kind, not a kind; E4 stays, as one branch with no Retry wiring; FIX-2406's | ||
| matrix becomes the end-to-end spine when it lands, and these tests stay as the mapping's. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - Drafted 2026-11-04 from FIX-2550, FIX-2370's spec and decisions, both labs' `adapter.ts` and | ||
| `Entry.tsx`, and FIX-2406's spec PR #4719, which found the gap. | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # FIX-2550 · The labs show a failed turn inline, with its reason and Retry | ||
|
|
||
| **Spec** · [Decisions](DECISIONS.md) | ||
|
|
||
| Child of epic [FIX-2369](../../epics/FIX-2369/SPEC.md). This is the lab half of | ||
| [FIX-2370](../FIX-2370/SPEC.md), whose spec Jake approved on 2026-11-01. FIX-2370 shipped the | ||
| registry's `request-recovery` line; its two lab slices never landed, though the issue is Done. | ||
| The direction is FIX-2370's and is not reopened here. This spec settles only what the labs' | ||
| code adds to it. | ||
|
|
||
| ## Who feels it, before and after | ||
|
|
||
| | Someone who… | Today | After | | ||
| |---|---|---| | ||
| | **sends a turn that fails** (no API key, a provider error, max steps) in the Claude Code-style lab | The working line goes away and nothing else shows. A crash looks like a short answer | A red line in the thread: *The main session couldn't finish this turn*, the reason, and **Retry** | | ||
| | **sends a turn that fails** in the Teammates lab | The same: *… is answering* stops, and nothing says why | The same line under the worker's name: *Researcher couldn't finish this turn* | | ||
| | **presses Retry** | — | The button says *Retrying…*; the turn runs again as a new request, and its reply shows in the thread once stored (it does not stream; a streaming retry needs a client and engine change). A refused retry says so and Retry comes back | | ||
| | **reads an older failed turn** | — | The reason stays; Retry shows only on the newest turn, and not while one is running | | ||
| | **watches a reply fail half-way** | The half reply reads as a finished one | The half reply is marked *Incomplete*, with the failure line under it | | ||
|
|
||
| ## The goal, and how we'll know it's met | ||
|
|
||
| **In both labs, a failed turn reads as a failure, with its reason and a working Retry, drawn by | ||
| the registry's `request-recovery`.** | ||
|
|
||
| - **The real need:** FIX-2370's R-01, "a crash looks the same as a short answer". Both labs | ||
| still drop the engine's `error` item: Claude Code-style reads only `message` and | ||
| `tool_output`; Teammates reads every item and draws none of type `error`. | ||
| - **Smaller, and rejected:** a red text line in each lab's own markup. That is the third copy | ||
| FIX-2370's D1 and the epic's ER-4 rule out. | ||
| - **Not done if:** either lab still shows nothing for a failed turn; Retry is drawn and does not | ||
| start a new turn; or a lab draws its own failure line instead of `RequestRecovery`. | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| E["engine: error item<br/>(every failed request)"] --> A1["Claude Code-style adapter<br/>failed entry"] | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| E --> A2["Teammates adapter<br/>failed entry"] | ||
| A1 --> R["registry: request-recovery<br/>(installed copy in each lab)"] | ||
| A2 --> R | ||
| R -->|"onRetry, newest turn only"| C["adapter.retry →<br/>client request(id).retry()"] | ||
| ``` | ||
|
|
||
| **How we verify.** | ||
|
|
||
| - *Adapter cases, per lab:* built from an error item shaped the way `runAction.ts` writes one | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| (`type: "error"`, `status: "failed"`, `message`, `code`, `requestId`). It maps to one failed | ||
| entry carrying the reason; a message of the same request that never completed is marked | ||
| incomplete; only the newest turn's failed entry is retryable, and only when the engine will retry its request. | ||
| - *Retry, per lab:* the adapter's `retry` posts the client's retry for that request. | ||
| - *Screen, per lab:* the failed entry draws `request-recovery` with the reason; Retry is drawn on | ||
| the newest turn and calls the adapter; an older one draws no button. | ||
| - *A real failed turn:* each lab's host with no model key; a send fails, and the thread shows | ||
| the line with the engine's reason. | ||
|
|
||
| **Control that must fail:** dropping the `"error"` branch from each adapter fails its adapter | ||
| case; passing `onRetry` on every failed entry fails the newest-only case; dropping the source check fails the internal-source case. Each is run red in the | ||
| PR. | ||
|
|
||
| ## What changes | ||
|
|
||
| - **Each lab's adapter** maps an `error` item to a `failed` entry (reason, code, details, its | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| request, and whether Retry applies: the newest turn, from a source the engine retries), and marks an unfinished `message` of a failed | ||
| request incomplete. Claude Code-style adds `error` to the item types it reads. | ||
| - **Each lab's adapter gains `retry(sessionId, requestId)`**, the client's | ||
| `flow(f).request(id).retry()` on the session's flow ([D1](DECISIONS.md#d1)). Each lab's fake | ||
| gains the same verb. | ||
| - **Each lab installs `request-recovery`** in `src/components/flow-state/`, byte-identical to the | ||
| registry, and its `Entry` draws a `failed` entry with it. The screen passes `onRetry` only for | ||
| the newest turn while nothing runs ([D2](DECISIONS.md#d2)). | ||
| - **Docs:** each lab README's table of what it reads gains the failed-turn row. No `apps/docs` | ||
| change; the component's docs shipped with FIX-2370. | ||
|
|
||
| ## What stays as it is | ||
|
|
||
| The engine's error item and request record, the client's `retry()`, the registry component, | ||
| and Kitchen Sink. No package changes. | ||
|
|
||
| ## What's already here, and the debt | ||
|
|
||
| | Piece | What this does with it | | ||
| |---|---| | ||
| | `request-recovery` (`packages/ui/registry`) | **Installed as is** in both labs | | ||
| | `error.tsx` (`ErrorBody`), already installed in both labs | **Reused** through `request-recovery` | | ||
| | `RequestHandle.retry()` (client) | **Reused** as Retry | | ||
| | The labs' `interrupted` entry (Claude Code-style, after you stop a turn) | **Left alone**: a stop you made is not a failure | | ||
| | FIX-2406's contract matrix (spec [#4719](https://github.com/fixpoint-labs/flow-state-dev/pull/4719)) | Its failed-turn row is `it.fails` against this issue; whichever lands second removes the mark | | ||
|
|
||
| **Removes:** nothing. **Adds:** one adapter verb and one entry kind per lab. **Debt:** none new. | ||
| Newest-only Retry has one owner per layer: the adapter decides which turn is retryable (`retryable`, | ||
| [D2](DECISIONS.md#d2)), because only it sees every item; the screen passes `onRetry` for that | ||
| entry and adds only "not while a turn runs", as FIX-2370 has every caller do. | ||
|
|
||
| ## Sign off | ||
|
|
||
| **Approve by merging.** The direction is FIX-2370's, already approved; this signs the two calls | ||
| the labs' code needed. *If wrong:* the labs' line changes, the registry does not. | ||
|
|
||
| - [D1](DECISIONS.md#d1) · Retry is a new adapter verb, not the component reaching the client. | ||
| - [D2](DECISIONS.md#d2) · "Newest turn" is read from the thread's own items. | ||
|
|
||
| Improvement · Claude Code-style and Teammates labs · small · one PR · child of | ||
| [FIX-2369](https://linear.app/fixpoint-labs/issue/FIX-2369) | ||
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.