Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions specs/issues/FIX-2550/DECISIONS.md
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
Comment thread
jhoffner marked this conversation as resolved.
Resolved

| | `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
Comment thread
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.
102 changes: 102 additions & 0 deletions specs/issues/FIX-2550/SPEC.md
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"]
Comment thread
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
Comment thread
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
Comment thread
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)
Loading