feat(ai-chat): миграция run-lifecycle на FSM — reconnect/stalled/supersede (#488) #509
@@ -86,19 +86,11 @@ const MIN_HEIGHT = 400;
|
||||
// Margin kept between the window and the viewport edges while dragging.
|
||||
const EDGE_MARGIN = 8;
|
||||
|
||||
// #184 phase 1.5 / #430: backstop for the degraded-poll fallback. The poll is
|
||||
// armed when a resume attempt could not attach to the live run and disarmed by the
|
||||
// thread on settle / local stream; this cap is the ONLY backstop against an endless
|
||||
// tick (a stuck 'streaming' row before the boot-sweep, or a user-tail 204 with no
|
||||
// run).
|
||||
//
|
||||
// #430: measured from RUN ACTIVITY, not from arm-time. A real autonomous run takes
|
||||
// 11-25 min — longer than a fixed 10-min-from-start cap, which used to cut the poll
|
||||
// off mid-run. Instead we cap on INACTIVITY: keep polling as long as the run is
|
||||
// still making progress (its persisted rows keep changing), and only give up after
|
||||
// this long with NO new activity. A genuinely stuck run produces no row changes, so
|
||||
// the idle cap still bounds it; a long-but-progressing run polls to completion.
|
||||
const DEGRADED_POLL_IDLE_MAX_MS = 10 * 60_000;
|
||||
// #184 phase 1.5 / #430 / #488: the degraded-poll fallback. The window owns only
|
||||
// a DUMB 2.5s timer, gated by an armed flag; the THREAD's run-lifecycle FSM owns
|
||||
// arm/disarm AND the inactivity cap that turns a stuck run into a `stalled` banner
|
||||
// (#488 commit 4a — the cap moved into the thread so polling->stalled is a single
|
||||
// FSM transition; the window no longer silently stops polling at the cap).
|
||||
|
||||
/** Compact token formatter: 1.2M / 3.4k / 950. */
|
||||
function formatTokens(n: number): string {
|
||||
@@ -259,17 +251,13 @@ export default function AiChatWindow() {
|
||||
[roles],
|
||||
);
|
||||
|
||||
// #184 phase 1.5: degraded-poll fallback (replaces the F4/F5/F7 latches). When
|
||||
// ChatThread could not attach to a still-running run it arms this via
|
||||
// onResumeFallback(true); the thread disarms it on settle / local stream. The
|
||||
// window only OWNS the timer (armedAtRef stamps when it was armed for the cap).
|
||||
// #184 phase 1.5 / #488: degraded-poll fallback. ChatThread's FSM arms this via
|
||||
// onResumeFallback(true) when it enters a poll-bearing recovery (attach 204 /
|
||||
// starved finish / stop) and disarms it on settle / local stream / stalled. The
|
||||
// window owns ONLY the dumb 2.5s timer; the THREAD owns arm/disarm AND the
|
||||
// inactivity cap (a stuck run -> the thread's `stalled` banner disarms this).
|
||||
const [degradedPoll, setDegradedPoll] = useState(false);
|
||||
// #430: timestamp of the LAST run activity while the poll is armed — stamped on
|
||||
// arm and re-stamped whenever the polled rows change (see the effect below). The
|
||||
// idle cap is measured from this, so a long-but-progressing run keeps polling.
|
||||
const lastActivityAtRef = useRef(0);
|
||||
const onResumeFallback = useCallback((active: boolean): void => {
|
||||
if (active) lastActivityAtRef.current = Date.now();
|
||||
setDegradedPoll(active);
|
||||
}, []);
|
||||
// Reset the degraded poll whenever the open chat changes: it is scoped to the
|
||||
@@ -281,33 +269,17 @@ export default function AiChatWindow() {
|
||||
const { data: messageRows, isLoading: messagesLoading } =
|
||||
useAiChatMessagesQuery(
|
||||
activeChatId ?? undefined,
|
||||
// DELIBERATELY DUMB (invariant 8 / task 2.4): poll every 2.5s while armed
|
||||
// and while the run is still active (#430: under the INACTIVITY cap, not a
|
||||
// fixed-from-start cap); otherwise off. NO error checks (TanStack v5 resets
|
||||
// fetchFailureCount each fetch, so consecutive errors are not expressible —
|
||||
// and the poll must survive a server restart) and NO tail checks (the
|
||||
// settled/local-stream semantics live in ChatThread, which disarms via
|
||||
// onResumeFallback(false)). The idle cap is the only backstop.
|
||||
() =>
|
||||
degradedPoll === true &&
|
||||
Date.now() - lastActivityAtRef.current < DEGRADED_POLL_IDLE_MAX_MS
|
||||
? 2500
|
||||
: false,
|
||||
// DELIBERATELY DUMB: poll every 2.5s WHILE ARMED, otherwise off. NO error
|
||||
// checks (TanStack resets fetchFailureCount each fetch; the poll must survive
|
||||
// a server restart), NO tail checks, NO cap here — the settled/stalled/idle-cap
|
||||
// semantics all live in ChatThread's FSM, which disarms via onResumeFallback.
|
||||
() => (degradedPoll === true ? 2500 : false),
|
||||
// #344: gate on windowOpen too — no message history is fetched (and no
|
||||
// degraded poll runs) while the window is closed; it loads when the window
|
||||
// opens with an active chat.
|
||||
windowOpen,
|
||||
);
|
||||
|
||||
// #430: re-stamp the activity clock whenever the polled rows change while the
|
||||
// poll is armed. TanStack keeps the same `messageRows` reference across refetches
|
||||
// that return deep-equal data (structural sharing), so a new reference means the
|
||||
// run genuinely progressed — which extends the inactivity cap above. A stuck run
|
||||
// yields no reference change, so the cap eventually fires and stops the poll.
|
||||
useEffect(() => {
|
||||
if (degradedPoll) lastActivityAtRef.current = Date.now();
|
||||
}, [degradedPoll, messageRows]);
|
||||
|
||||
// #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
|
||||
// this workspace. When the feature is off no runs are ever created, so the
|
||||
// resume attempt would only ever 204; gating ChatThread's resume on it avoids a
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -57,6 +57,25 @@ export async function stopRun(
|
||||
return req.data;
|
||||
}
|
||||
|
||||
/**
|
||||
* #488: the run-fact — "is a run active on this chat?" — first-class from the
|
||||
* server (POST /ai-chat/run). Called on mount to seed the client FSM's run-fact
|
||||
* and to VERIFY after a supersede mismatch (an observer following a superseded
|
||||
* run asks for the latest run and follows it). Returns the latest run row (with
|
||||
* its `id` and `status`) and its projected assistant message, or `run: null` when
|
||||
* the chat has never had a run. Owner-gated server-side.
|
||||
*/
|
||||
export async function getRun(chatId: string): Promise<{
|
||||
run: { id: string; status: string } | null;
|
||||
message: IAiChatMessageRow | null;
|
||||
}> {
|
||||
const req = await api.post<{
|
||||
run: { id: string; status: string } | null;
|
||||
message: IAiChatMessageRow | null;
|
||||
}>("/ai-chat/run", { chatId });
|
||||
return req.data;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the chat bound to a document (the current user's most-recent chat
|
||||
* created on that page), or null when there is none. Drives auto-open-on-page.
|
||||
|
||||
@@ -0,0 +1,183 @@
|
||||
# AI-chat run-lifecycle FSM — design spec (#488)
|
||||
|
||||
This is the written design that `run-fsm.ts` implements. It ships in the PR (issue
|
||||
#488 commit 1: "the spec is written FIRST and enters the PR"). It has four parts:
|
||||
(1) the event × state transition table, (2) the map of every `chat-thread.tsx` ref
|
||||
to {FSM state | FSM context | stays data}, (3) the run-fact protocol, (4) the
|
||||
invariants.
|
||||
|
||||
The reducer is a **pure function** `reduce(machine, event) → machine`. The returned
|
||||
machine carries the **command effects** for that transition; a thin runtime in
|
||||
`chat-thread.tsx` dispatches events and executes effects. Because it is pure, the
|
||||
whole machine is enumerable and unit-tested directly (event × state → next state is
|
||||
the observable property) — see `run-fsm.test.ts`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Event × state transition table
|
||||
|
||||
Phases: `idle | sending | streaming | attaching | reconnecting(attempt,failed) |
|
||||
polling(reason) | stalled | stopping | superseding | error(kind)`.
|
||||
Context (orthogonal): `epoch`, `ownership: local|observer`, `runFact: {runId}|null`,
|
||||
`liveFollow` (are we following a live run we locally streamed — the reconnect
|
||||
ladder — vs a one-shot mount-attach resume? both are `observer`, but a live-follow
|
||||
drop RE-ENTERS the ladder (#488 commit 3) while a mount-resume drop polls).
|
||||
|
||||
Legend: **†** = command-transition (bumps `epoch`, I1). Effects in `[…]`.
|
||||
|
||||
| Event (source) | From phase(s) | → To phase | Effects / ctx |
|
||||
|---|---|---|---|
|
||||
| `SEND_LOCAL` (user send) | idle, error, polling, stalled, reconnecting | sending **†** | `[cancelReconnect, disarmPoll]`, ownership=local |
|
||||
| `STREAM_START{runId}` (SDK `start` metadata) | sending, attaching, reconnecting, superseding | streaming | `[cancelReconnect, disarmPoll]`, runFact←runId |
|
||||
| `FINISH_CLEAN` (onFinish clean) | streaming, … | idle | `[disarmPoll, cancelReconnect]`, runFact←null |
|
||||
| `FINISH_ABORT` (onFinish isAbort) | streaming, stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (I4 exits stopping by this DATA) |
|
||||
| `FINISH_DISCONNECT` (observer, NOT liveFollow) | streaming(observer) | polling(disconnect-visible) | `[armPoll]` (a mount-resume drop polls) |
|
||||
| `FINISH_DISCONNECT{hasVisibleContent}` (local drop OR liveFollow) | streaming | reconnecting(1) **†** *iff runFact\|liveFollow* | `[scheduleReconnect(1)]` (+`armPoll` if visible), ownership=observer, liveFollow=true (commit 3: repeatable) |
|
||||
| `FINISH_DISCONNECT` (no runFact, not liveFollow) | streaming | idle | runFact←null (plain terminal "connection lost") |
|
||||
| `STREAM_INCOMPLETE{reason}` (observer starved/torn clean finish) | streaming(observer) | polling(reason) | `[armPoll(reason)]` |
|
||||
| `FINISH_ERROR{kind}` (onFinish isError) | any | error(kind) | `[disarmPoll, cancelReconnect]`, runFact←null |
|
||||
| `STREAM_START{runId}` (first assistant frame of a local turn) | sending | streaming | runFact←runId, `[cancelReconnect, disarmPoll]` |
|
||||
| `ATTACH_START{runId}` (mount resume) | **idle only** (F2) | attaching **†** | `[resumeStream]`, ownership=observer, runFact←runId; ignored from any non-idle phase |
|
||||
| `ATTACH_LIVE` (attach GET 2xx) | attaching | streaming | — |
|
||||
| `ATTACH_NONE` (attach GET 204/err/throw) | attaching | polling(attach-none) | `[armPoll(attach-none)]` |
|
||||
| `RECONNECT_ATTEMPT{n}` (backoff timer) | reconnecting | reconnecting(n) **†** | `[resumeStream]` |
|
||||
| `RECONNECT_ATTACHED` (reconnect GET 2xx) | reconnecting | streaming | `[cancelReconnect, disarmPoll]` — **counter reset** (commit 3) |
|
||||
| `RECONNECT_NONE` (reconnect GET 204/err), attempt<MAX | reconnecting | reconnecting(n+1) **†** | `[armPoll(attach-none), scheduleReconnect(n+1)]` |
|
||||
| `RECONNECT_NONE`, attempt=MAX | reconnecting | reconnecting(MAX, failed) | `[armPoll(reconnect-exhausted)]` |
|
||||
| `RETRY` (manual, failed banner) | reconnecting(failed) | reconnecting(1) **†** | `[resumeStream]` |
|
||||
| `RETRY` (manual, stalled banner) | stalled | polling(attach-none) **†** | `[armPoll]` |
|
||||
| `POLL_TERMINAL` (settled tail merged) | polling, reconnecting, stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (I4) |
|
||||
| `POLL_IDLE_CAP` (inactivity cap) | polling, reconnecting | stalled | `[disarmPoll, cancelReconnect]` (commit 4a — no more silent) |
|
||||
| `RUN_FACT{null}` (POST /run → null/terminal, 204) | reconnecting/attaching/polling/stopping | idle | `[cancelReconnect, disarmPoll]`, runFact←null (I3 fresh-negative gate) |
|
||||
| `RUN_FACT{runId}` | any | (same) | runFact←runId (pessimism toward an attempt) |
|
||||
| `STOP_REQUESTED` (user Stop) | streaming, reconnecting, polling | stopping **†** | `[stopRun, abortAttach, cancelReconnect, armPoll]` (poll drives the terminal — I4 exit by data) |
|
||||
| `SUPERSEDE_REQUESTED{targetRunId}` (interrupt+send) | streaming, reconnecting, polling, error | superseding **†** | `[supersede(target), cancelReconnect, disarmPoll]` |
|
||||
| `SUPERSEDE_READY{runId}` (CAS ok) | superseding | streaming | ownership=local, runFact←runId |
|
||||
| `SUPERSEDE_MISMATCH{currentRunId}` (409 SUPERSEDE_TARGET_MISMATCH) | superseding | error(supersede-mismatch) | `[postRun(verify)]`, runFact←currentRunId |
|
||||
| `SUPERSEDE_TIMEOUT` (409 SUPERSEDE_TIMEOUT) | superseding | error(supersede-timeout) | — (composer keeps text; no auto-retry) |
|
||||
| `SUPERSEDE_INVALID` (409 SUPERSEDE_INVALID) | superseding | error(supersede-invalid) | — |
|
||||
| `RUN_ALREADY_ACTIVE` (409 A_RUN_ALREADY_ACTIVE, plain POST) | sending | error(run-already-active) | — (composer offers supersede; NO auto-retry) |
|
||||
| `DISPOSE` (unmount) | any | idle **†** | `[abortAttach, cancelReconnect, disarmPoll]` (I1/I5 — epoch++ kills late callbacks) |
|
||||
|
||||
**`stopping` honors any finish (re-review MEDIUM):** BEFORE the epoch filter, a
|
||||
stream finish (`FINISH_*`/`STREAM_INCOMPLETE`) arriving in phase `stopping` exits
|
||||
`stopping -> idle` regardless of generation. A plain Stop has no successor stream,
|
||||
so the aborted stream's finish IS the expected end (I4 exit by data) — and it
|
||||
carries the PRE-stop generation (STOP_REQUESTED bumped the epoch), so the filter
|
||||
would otherwise strand the machine in `stopping` (no idle-cap covers it). The filter
|
||||
stays in force for `superseding` (that is the F1 supersede drop).
|
||||
|
||||
**Epoch filter (I1):** the reducer then drops any event carrying an `epoch` that
|
||||
does not equal the current `ctx.epoch`. Outcome events (`STREAM_START`, `ATTACH_*`,
|
||||
`RECONNECT_*`, `SUPERSEDE_*`, **`FINISH_*`/`STREAM_INCOMPLETE`**, `RUN_FACT`) are
|
||||
stamped with the generation the corresponding STREAM started under (the runtime
|
||||
holds a per-owned-stream `turnEpoch`); trigger events (user actions, fresh
|
||||
disconnects) carry no epoch. **F1:** this is what makes a SUPERSEDED stream's late
|
||||
`onFinish` (a dead stream A closing after the CAS started stream B) get dropped, so
|
||||
A cannot drive the live new run into a false reconnect or reset its run-fact. The
|
||||
supersede path additionally ABORTS A and starts B only from A's onFinish (a
|
||||
microtask), because ai@6 `AbstractChat.makeRequest` corrupts overlapping streams
|
||||
(A's `finally` reads then nulls the shared `activeResponse`).
|
||||
|
||||
**Removed events (scope-cut, internal review):** `RUN_SUPERSEDED` (a ghost feature —
|
||||
never dispatched; the observer-superseded case is handled by the degraded poll,
|
||||
which follows the latest rows regardless of runId), `RECONNECT_BEGIN` (reconnect is
|
||||
entered by `FINISH_DISCONNECT`), and `POLL_ACTIVITY` (the window's activity clock was
|
||||
removed when the idle-cap moved into the thread). The reducer and this table now
|
||||
share exactly the dispatched event set.
|
||||
|
||||
### 409-code → event map (the real #487 contract consumed here)
|
||||
|
||||
| Server response | Event dispatched | error kind → banner |
|
||||
|---|---|---|
|
||||
| 409 `A_RUN_ALREADY_ACTIVE` (plain POST) | `RUN_ALREADY_ACTIVE` | run-already-active → "already answering / interrupt & send" |
|
||||
| 409 `SUPERSEDE_TARGET_MISMATCH` (+ body.runId) | `SUPERSEDE_MISMATCH{currentRunId}` | supersede-mismatch → verify via /run |
|
||||
| 409 `SUPERSEDE_TIMEOUT` | `SUPERSEDE_TIMEOUT` | supersede-timeout → "couldn't interrupt in time, resend" |
|
||||
| 409 `SUPERSEDE_INVALID` | `SUPERSEDE_INVALID` | supersede-invalid → "couldn't interrupt this run" |
|
||||
| 503 `A_RUN_BEGIN_FAILED` | `FINISH_ERROR{begin-failed}` | begin-failed → "could not start, temporary" |
|
||||
|
||||
---
|
||||
|
||||
## 2. Ref-map — every `chat-thread.tsx` ref → its new home (MIGRATION RESOLVED)
|
||||
|
||||
The migration is COMPLETE: the 13 run-lifecycle FLAGS below are GONE from
|
||||
`chat-thread.tsx` (collapsed into FSM phase/ctx/effects, or deleted). What remains
|
||||
are identity/data mirrors, effect-owned controllers/timers, and ONE React-liveness
|
||||
bit — none of which is a run-lifecycle flag, so the post-merge "no new flags" rule
|
||||
holds. **Pending column: empty.**
|
||||
|
||||
| # | Old ref | Resolved to | Where now |
|
||||
|---|---|---|---|
|
||||
| 1 | `reconcileTailRef` | **FSM phase** | reconcile-merge gated on `phase ∈ {polling, reconnecting, stopping}` |
|
||||
| 2 | `noStreamHandledRef` | **FSM epoch (I1)** | the attach outcome's epoch guard drops the stale/second outcome |
|
||||
| 3 | `onNoActiveStreamRef` | **FSM event** | transport → `handleAttachOutcome` dispatches `ATTACH_NONE`/`RECONNECT_NONE` |
|
||||
| 4 | `onReconnectAttachedRef` | **FSM event** | transport dispatches `ATTACH_LIVE` / `RECONNECT_ATTACHED` |
|
||||
| 5 | `resumedTurnRef` + `resumedTurn` state | **FSM ctx `ownership`** | `ownership==='observer'` ⇒ never flush; hides "Send now" |
|
||||
| 6 | `reconnectStateRef` + `reconnectState` state | **FSM phase** | `reconnecting(attempt,failed)` renders the banner |
|
||||
| 7 | `reconnectTimerRef` | **effect-owned timer** | owned by `scheduleReconnect`/`cancelReconnect` effects (not a flag) |
|
||||
| 8 | `flushOnAbortRef` | **DELETED** | the stop→flush dance is replaced by the CAS supersede (commit 5) |
|
||||
| 9 | `interruptNextSendRef` | **DELETED** | the server injects the interrupt note from the supersede itself |
|
||||
| 10 | `supersedeRetryRef` | **DELETED** (commit 5) | the client 409 retry ladder is gone; CAS supersede replaces it |
|
||||
| 11 | `stopPendingRef` | **FSM phase `stopping`** | the deferred stop fires from the chat-id adoption effect while `stopping` |
|
||||
| 12 | `mountedRef` | **retained (React liveness)** | orthogonal to run-lifecycle; gates imperative onFinish side-effects post-unmount. Epoch (I1) handles stale COMMAND-outcomes; DISPOSE bumps it |
|
||||
| 13 | `attemptResumeRef` | **FSM `ATTACH_START` + run-fact** | mount arms attach ONLY on a confirmed active run (commit 4b: streaming-tail status, or POST /run for a user tail) |
|
||||
| 14 | `stripRef` | **data** (attachStrategy) | strip+replay detail; the `resumeStream` effect reads it |
|
||||
| 15 | `strippedRowRef` | **data** (attachStrategy) | the anchor row |
|
||||
| 16 | `attachAbortRef` | **effect-owned controller** | aborted by the `abortAttach` effect in cleanup (I5) |
|
||||
| 17–25 | `chatIdRef`, `openPageRef`, `getEditorSelectionRef`, `roleIdRef`, `stableIdRef`, `queuedRef`, `sendMessageRef`, `statusRef`, `lastForwardedChatIdRef` | **data** (identity/send mirrors) | unchanged — not lifecycle flags |
|
||||
| NEW | `pendingSupersedeRef` | **data** (send-plumbing) | the runId injected into the next `POST /stream {supersede}`; the single replacement for the 3 DELETED one-shots (#8/#9/#10) — net −2 refs |
|
||||
| NEW | `idleCapTimerRef` | **effect-owned timer** | the stalled inactivity cap → `POLL_IDLE_CAP` (commit 4a); not a flag |
|
||||
|
||||
Net: the 13 lifecycle flags (#1–#13) are eliminated: **8** → FSM phase/ctx/epoch/event
|
||||
(#1–#6, #11, #13), **3** deleted (#8/#9/#10), **`reconnectTimerRef` (#7)** becomes an
|
||||
effect-owned controller, and **`mountedRef` (#12)** is retained as React liveness
|
||||
(8 + 3 + 1 + 1 = 13). (`attachAbortRef` (#16) is outside the #1–#13 set — it was
|
||||
already an effect-owned controller.) Two effect-owned timers + one send-plumbing data
|
||||
ref are added — none is a boolean lifecycle latch.
|
||||
|
||||
---
|
||||
|
||||
## 3. Run-fact protocol (`runFact: {runId} | null`) — I3
|
||||
|
||||
"A run is active" is first-class from the SERVER, not inferred from an assistant
|
||||
message. Sources, in the order they update `ctx.runFact`:
|
||||
|
||||
1. **Init (mount):** `POST /ai-chat/run { chatId }` → `{ run, message }`. A `run`
|
||||
with a non-terminal `status` seeds `runFact = { runId: run.id }`; a null/terminal
|
||||
run seeds `null`. This is what arms the resume attempt (`ATTACH_START`) — the
|
||||
attempt is armed ONLY on a positive fact (commit 4b: a user-tail with no active
|
||||
run no longer arms a pointless poll on every open).
|
||||
2. **Live update:** the `start` stream metadata carries `runId` → `STREAM_START{runId}`.
|
||||
3. **Attach outcomes:** `ATTACH_LIVE` (2xx) confirms active; a 204 on a non-stripped
|
||||
path is an authoritative NEGATIVE fact → the runtime dispatches `RUN_FACT{null}`,
|
||||
which cancels recovery (I3 fresh-negative gate).
|
||||
4. **Poll (future resume-stack iteration #491):** the delta will carry the run field;
|
||||
until then the poll drives to a terminal ROW, dispatched as `POLL_TERMINAL`.
|
||||
|
||||
Pessimism rule: a stale-but-positive fact PERMITS entering recovery (attach); the
|
||||
204 then cuts it. A fresh negative fact gates recovery OUT immediately.
|
||||
|
||||
---
|
||||
|
||||
## 4. Invariants
|
||||
|
||||
- **I1 — Epoch (generation counter).** Every command-emitting transition bumps
|
||||
`ctx.epoch`; every async outcome event carries its issuing epoch; the reducer
|
||||
drops stale-epoch outcomes. Replaces the one-shot-ref zoo (`noStreamHandledRef`,
|
||||
the flush/interrupt/supersede one-shots, the `mountedRef` late-callback gate).
|
||||
- **I2 — Ownership is context, not state.** `local | observer` is orthogonal to the
|
||||
transport phase. The queue flushes ONLY under local ownership; an observer
|
||||
following a detached run never flushes (was `resumedTurnRef`).
|
||||
- **I3 — Run-fact is first-class from the server.** Reconnect is entered by the
|
||||
run-fact, not by an assistant message (commit 2). A fresh negative fact cancels
|
||||
recovery.
|
||||
- **I4 — Exit `stopping` by DATA.** A terminal row / negative run-fact / terminal
|
||||
finish exits `stopping`, never the stopRun HTTP response (which returns after the
|
||||
abort but before finalization — keying off it would unlock the composer on a 409).
|
||||
- **I5 — Dispose protocol.** Command controllers (attach GET, POST /stream, POST
|
||||
/run) are effect-owned and aborted in cleanup (`abortAttach` on `DISPOSE`), not
|
||||
render-phase refs. A client abort of an already-sent POST does not cancel the
|
||||
server action, so disarming on unmount is safe.
|
||||
- **attachStrategy** (strip+replay today) is behind the `resumeStream` effect; the
|
||||
resume-stack iteration (#491) swaps it to tail-only WITHOUT touching the FSM.
|
||||
- **Queue** stays a data structure; flush/interrupt decisions are transitions.
|
||||
@@ -0,0 +1,461 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
reduce,
|
||||
initialMachine,
|
||||
reconnectDelayMs,
|
||||
RECONNECT_MAX_ATTEMPTS,
|
||||
type Machine,
|
||||
type Effect,
|
||||
type Event,
|
||||
} from "./run-fsm";
|
||||
|
||||
// Drive a sequence of events through the reducer, returning the final machine.
|
||||
function run(m: Machine, ...events: Event[]): Machine {
|
||||
return events.reduce(reduce, m);
|
||||
}
|
||||
function withRunFact(runId = "run-1"): Machine {
|
||||
return {
|
||||
...initialMachine(),
|
||||
ctx: { epoch: 0, ownership: "local", runFact: { runId }, liveFollow: false },
|
||||
};
|
||||
}
|
||||
function effectTypes(m: Machine): string[] {
|
||||
return m.effects.map((e) => e.type);
|
||||
}
|
||||
function hasEffect(m: Machine, type: Effect["type"]): boolean {
|
||||
return m.effects.some((e) => e.type === type);
|
||||
}
|
||||
|
||||
describe("run-fsm — epoch invariant (I1)", () => {
|
||||
it("drops an outcome carrying a stale epoch", () => {
|
||||
// A command bumps the epoch; an outcome stamped with the OLD epoch is dropped.
|
||||
const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" }); // epoch 0->1, attaching
|
||||
expect(m0.ctx.epoch).toBe(1);
|
||||
expect(m0.phase.name).toBe("attaching");
|
||||
// A late ATTACH_LIVE from a SUPERSEDED attempt (epoch 0) must NOT drive us.
|
||||
const stale = reduce(m0, { type: "ATTACH_LIVE", epoch: 0 });
|
||||
expect(stale.phase.name).toBe("attaching");
|
||||
expect(stale.effects).toEqual([]);
|
||||
});
|
||||
|
||||
it("applies an outcome carrying the current epoch", () => {
|
||||
const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
const live = reduce(m0, { type: "ATTACH_LIVE", epoch: m0.ctx.epoch });
|
||||
expect(live.phase.name).toBe("streaming");
|
||||
});
|
||||
|
||||
it("an outcome with no epoch is never dropped (trigger events)", () => {
|
||||
const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
const disposed = reduce(m0, { type: "DISPOSE" });
|
||||
expect(disposed.phase.name).toBe("idle");
|
||||
expect(hasEffect(disposed, "abortAttach")).toBe(true);
|
||||
});
|
||||
|
||||
it("every command-transition increments the epoch exactly once", () => {
|
||||
let m = initialMachine();
|
||||
const before = m.ctx.epoch;
|
||||
m = reduce(m, { type: "SEND_LOCAL" });
|
||||
expect(m.ctx.epoch).toBe(before + 1);
|
||||
m = reduce(m, { type: "STOP_REQUESTED" });
|
||||
expect(m.ctx.epoch).toBe(before + 2);
|
||||
});
|
||||
});
|
||||
|
||||
describe("run-fsm — local turn", () => {
|
||||
it("SEND_LOCAL → sending, local ownership, cancels recovery", () => {
|
||||
const m = reduce(withRunFact(), { type: "SEND_LOCAL" });
|
||||
expect(m.phase.name).toBe("sending");
|
||||
expect(m.ctx.ownership).toBe("local");
|
||||
expect(effectTypes(m)).toEqual(
|
||||
expect.arrayContaining(["cancelReconnect", "disarmPoll"]),
|
||||
);
|
||||
});
|
||||
|
||||
it("STREAM_START adopts the runId into the run-fact and goes streaming", () => {
|
||||
const m = run(initialMachine(), { type: "SEND_LOCAL" });
|
||||
const s = reduce(m, { type: "STREAM_START", runId: "run-9", epoch: m.ctx.epoch });
|
||||
expect(s.phase.name).toBe("streaming");
|
||||
expect(s.ctx.runFact).toEqual({ runId: "run-9" });
|
||||
});
|
||||
|
||||
it("FINISH_CLEAN → idle, run-fact cleared, poll/reconnect disarmed", () => {
|
||||
const streaming = run(initialMachine(), { type: "SEND_LOCAL" }, { type: "STREAM_START", runId: "r" });
|
||||
const done = reduce(streaming, { type: "FINISH_CLEAN" });
|
||||
expect(done.phase.name).toBe("idle");
|
||||
expect(done.ctx.runFact).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// #488 commit 2 — SSE break BEFORE the first assistant frame must still recover.
|
||||
describe("run-fsm — commit 2: reconnect by run-fact, not by assistant message", () => {
|
||||
it("FINISH_DISCONNECT with an active run-fact → reconnecting (even with no visible content)", () => {
|
||||
// Setup-phase break: no assistant frame yet, but a run-fact exists.
|
||||
const streaming = withRunFact("run-2");
|
||||
const m = reduce(streaming, {
|
||||
type: "FINISH_DISCONNECT",
|
||||
hasVisibleContent: false,
|
||||
epoch: streaming.ctx.epoch,
|
||||
});
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
if (m.phase.name === "reconnecting") expect(m.phase.attempt).toBe(1);
|
||||
expect(m.ctx.ownership).toBe("observer");
|
||||
expect(hasEffect(m, "scheduleReconnect")).toBe(true);
|
||||
// No visible content -> no poll arm yet (the reconnect ladder rebuilds it).
|
||||
expect(hasEffect(m, "armPoll")).toBe(false);
|
||||
});
|
||||
|
||||
it("FINISH_DISCONNECT WITH visible content also arms the poll", () => {
|
||||
const m = reduce(withRunFact("run-2"), {
|
||||
type: "FINISH_DISCONNECT",
|
||||
hasVisibleContent: true,
|
||||
epoch: 0,
|
||||
});
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("FINISH_DISCONNECT with NO run-fact → idle (plain connection-lost)", () => {
|
||||
const m = reduce(initialMachine(), {
|
||||
type: "FINISH_DISCONNECT",
|
||||
hasVisibleContent: true,
|
||||
epoch: 0,
|
||||
});
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
});
|
||||
|
||||
// #488 commit 3 — a SECOND break after a successful re-attach starts a NEW ladder.
|
||||
describe("run-fsm — commit 3: repeated reconnect cycles", () => {
|
||||
it("two breaks in a row produce two reconnect cycles (counter resets on attach)", () => {
|
||||
let m = withRunFact("run-3");
|
||||
// First break -> reconnecting(1).
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
// Attempt fires, re-attaches live.
|
||||
m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RECONNECT_ATTACHED", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("streaming");
|
||||
// SECOND break: the counter was reset, so a fresh ladder starts at attempt 1
|
||||
// (the old one-shot !wasResumed gate would have sent this to silent poll).
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
if (m.phase.name === "reconnecting") expect(m.phase.attempt).toBe(1);
|
||||
expect(hasEffect(m, "scheduleReconnect")).toBe(true);
|
||||
});
|
||||
|
||||
it("a MOUNT-attach observer drop falls to POLL, not the reconnect ladder", () => {
|
||||
// Distinguishes commit 3 from a one-shot resume: an observer that never
|
||||
// live-followed (liveFollow false) polls on a drop.
|
||||
let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
|
||||
expect(m.ctx.ownership).toBe("observer");
|
||||
expect(m.ctx.liveFollow).toBe(false);
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: true, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("polling");
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("STREAM_INCOMPLETE (observer starved/torn finish) → polling", () => {
|
||||
let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "STREAM_INCOMPLETE", reason: "starved", epoch: m.ctx.epoch });
|
||||
expect(m.phase).toEqual({ name: "polling", reason: "starved" });
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("liveFollow is set on the first local drop and kept across a re-attach", () => {
|
||||
let m = withRunFact("run-3");
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
|
||||
expect(m.ctx.liveFollow).toBe(true);
|
||||
m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RECONNECT_ATTACHED", epoch: m.ctx.epoch });
|
||||
expect(m.ctx.liveFollow).toBe(true); // kept — so a second drop reconnects
|
||||
// A clean finish clears it.
|
||||
m = reduce(m, { type: "FINISH_CLEAN", epoch: m.ctx.epoch });
|
||||
expect(m.ctx.liveFollow).toBe(false);
|
||||
});
|
||||
|
||||
it("RECONNECT_NONE backs off through the ladder, then fails at the cap", () => {
|
||||
let m = withRunFact("run-3");
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
|
||||
for (let n = 1; n < RECONNECT_MAX_ATTEMPTS; n++) {
|
||||
m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: n, epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RECONNECT_NONE", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
if (m.phase.name === "reconnecting") {
|
||||
expect(m.phase.attempt).toBe(n + 1);
|
||||
expect(m.phase.failed).toBe(false);
|
||||
}
|
||||
// The belt-and-suspenders poll is armed each failed attempt.
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
}
|
||||
// Final attempt fails -> failed banner (Retry), poll armed.
|
||||
m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: RECONNECT_MAX_ATTEMPTS, epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RECONNECT_NONE", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
if (m.phase.name === "reconnecting") expect(m.phase.failed).toBe(true);
|
||||
// RETRY restarts at attempt 1.
|
||||
m = reduce(m, { type: "RETRY" });
|
||||
expect(m.phase.name).toBe("reconnecting");
|
||||
if (m.phase.name === "reconnecting") {
|
||||
expect(m.phase.attempt).toBe(1);
|
||||
expect(m.phase.failed).toBe(false);
|
||||
}
|
||||
expect(hasEffect(m, "resumeStream")).toBe(true);
|
||||
});
|
||||
|
||||
it("reconnectDelayMs is the exponential backoff 1s,2s,4s,8s,16s", () => {
|
||||
expect([1, 2, 3, 4, 5].map(reconnectDelayMs)).toEqual([1000, 2000, 4000, 8000, 16000]);
|
||||
});
|
||||
});
|
||||
|
||||
// #488 commit 4 — polling stalled-state + user-tail gating.
|
||||
describe("run-fsm — commit 4: stalled + run-fact gating", () => {
|
||||
it("POLL_IDLE_CAP: polling → stalled with a banner (poll disarmed), not silent", () => {
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("polling");
|
||||
m = reduce(m, { type: "POLL_IDLE_CAP" });
|
||||
expect(m.phase.name).toBe("stalled");
|
||||
expect(hasEffect(m, "disarmPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("RETRY from stalled re-arms the poll", () => {
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "POLL_IDLE_CAP" });
|
||||
m = reduce(m, { type: "RETRY" });
|
||||
expect(m.phase.name).toBe("polling");
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("a fresh NEGATIVE run-fact while attaching cancels recovery (user-tail, no active run)", () => {
|
||||
// The mount POST /run returns no active run: attaching → idle, no poll armed.
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(m.ctx.runFact).toBeNull();
|
||||
expect(hasEffect(m, "disarmPoll")).toBe(true);
|
||||
});
|
||||
|
||||
it("a negative run-fact while polling stops the poll", () => {
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
|
||||
it("POLL_TERMINAL settles polling → idle (I4 data-driven exit)", () => {
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "POLL_TERMINAL" });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(m.ctx.runFact).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// #488 commit 5 — error classification + supersede CAS transitions.
|
||||
describe("run-fsm — commit 5: supersede CAS + error classification", () => {
|
||||
it("SUPERSEDE_REQUESTED → superseding, fires the CAS effect, bumps epoch", () => {
|
||||
const streaming = withRunFact("run-old");
|
||||
const m = reduce(streaming, { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
expect(m.phase.name).toBe("superseding");
|
||||
expect(m.ctx.epoch).toBe(streaming.ctx.epoch + 1);
|
||||
const sup = m.effects.find((e) => e.type === "supersede");
|
||||
expect(sup).toEqual({ type: "supersede", targetRunId: "run-old" });
|
||||
});
|
||||
|
||||
it("SUPERSEDE_READY → streaming as the new local owner", () => {
|
||||
let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
m = reduce(m, { type: "SUPERSEDE_READY", runId: "run-new", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("streaming");
|
||||
expect(m.ctx.ownership).toBe("local");
|
||||
expect(m.ctx.runFact).toEqual({ runId: "run-new" });
|
||||
});
|
||||
|
||||
it("SUPERSEDE_MISMATCH → error(supersede-mismatch) + verify via /run (no blind banner)", () => {
|
||||
let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
m = reduce(m, { type: "SUPERSEDE_MISMATCH", currentRunId: "run-x", epoch: m.ctx.epoch });
|
||||
expect(m.phase).toEqual({ name: "error", kind: "supersede-mismatch" });
|
||||
expect(hasEffect(m, "postRun")).toBe(true);
|
||||
expect(m.ctx.runFact).toEqual({ runId: "run-x" });
|
||||
});
|
||||
|
||||
it("SUPERSEDE_TIMEOUT → error(supersede-timeout), no auto-retry effect", () => {
|
||||
let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
m = reduce(m, { type: "SUPERSEDE_TIMEOUT", epoch: m.ctx.epoch });
|
||||
expect(m.phase).toEqual({ name: "error", kind: "supersede-timeout" });
|
||||
expect(m.effects).toEqual([]);
|
||||
});
|
||||
|
||||
it("SUPERSEDE_INVALID → error(supersede-invalid)", () => {
|
||||
let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
m = reduce(m, { type: "SUPERSEDE_INVALID", epoch: m.ctx.epoch });
|
||||
expect(m.phase).toEqual({ name: "error", kind: "supersede-invalid" });
|
||||
});
|
||||
|
||||
it("a stale SUPERSEDE outcome from a superseded epoch is dropped", () => {
|
||||
let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
const supersedingEpoch = m.ctx.epoch;
|
||||
// The user retriggers, bumping the epoch again.
|
||||
m = reduce(m, { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
|
||||
// The first CAS's late TIMEOUT (old epoch) must NOT knock us out of superseding.
|
||||
const late = reduce(m, { type: "SUPERSEDE_TIMEOUT", epoch: supersedingEpoch });
|
||||
expect(late.phase.name).toBe("superseding");
|
||||
});
|
||||
|
||||
it("RUN_ALREADY_ACTIVE (plain POST gate) → error(run-already-active), no retry effect", () => {
|
||||
const m = reduce(run(initialMachine(), { type: "SEND_LOCAL" }), { type: "RUN_ALREADY_ACTIVE" });
|
||||
expect(m.phase).toEqual({ name: "error", kind: "run-already-active" });
|
||||
expect(m.effects).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// #488 F2 — a late mount `getRun → ATTACH_START` must not hijack a local turn.
|
||||
describe("run-fsm — F2: ATTACH_START only from idle", () => {
|
||||
it("ATTACH_START from a local `sending` turn is ignored (no observer hijack)", () => {
|
||||
const sending = reduce(initialMachine(), { type: "SEND_LOCAL" }); // idle -> sending, local
|
||||
const m = reduce(sending, { type: "ATTACH_START", runId: "r" });
|
||||
expect(m.phase.name).toBe("sending");
|
||||
expect(m.ctx.ownership).toBe("local"); // NOT flipped to observer
|
||||
expect(m.effects).toEqual([]); // no resumeStream
|
||||
});
|
||||
|
||||
it("ATTACH_START from idle attaches as normal", () => {
|
||||
const m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
expect(m.phase.name).toBe("attaching");
|
||||
expect(m.ctx.ownership).toBe("observer");
|
||||
expect(hasEffect(m, "resumeStream")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("run-fsm — stop (I4: exit by data)", () => {
|
||||
it("STOP_REQUESTED → stopping, fires stopRun + abortAttach, no data-independent exit", () => {
|
||||
const m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
|
||||
expect(m.phase.name).toBe("stopping");
|
||||
expect(effectTypes(m)).toEqual(expect.arrayContaining(["stopRun", "abortAttach"]));
|
||||
});
|
||||
|
||||
it("stopping exits on the aborted stream's finish carrying the PRE-STOP epoch", () => {
|
||||
// MEDIUM (#488 re-review): STOP_REQUESTED is a command that BUMPS the epoch, but
|
||||
// the runtime stamps the aborted stream's onFinish with the stream's START (pre-
|
||||
// stop) generation — exactly what the component sends. `stopping` must HONOR
|
||||
// that finish regardless of generation (no idle-cap covers `stopping`).
|
||||
// MUTATION-VERIFY: remove the honor-in-`stopping` branch and this hangs in
|
||||
// `stopping` (the epoch filter drops the pre-stop finish) -> red.
|
||||
const preStopEpoch = withRunFact().ctx.epoch; // E1 (the stream's start epoch)
|
||||
let m = reduce(withRunFact(), { type: "STOP_REQUESTED" }); // E1 -> E2, stopping
|
||||
expect(m.ctx.epoch).toBe(preStopEpoch + 1);
|
||||
m = reduce(m, { type: "FINISH_ABORT", epoch: preStopEpoch }); // NOT the current epoch
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(m.ctx.runFact).toBeNull();
|
||||
});
|
||||
|
||||
it("stopping exits on a clean finish carrying the pre-stop epoch too", () => {
|
||||
const preStopEpoch = withRunFact().ctx.epoch;
|
||||
let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
|
||||
m = reduce(m, { type: "FINISH_CLEAN", epoch: preStopEpoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
|
||||
it("stopping exits on a negative run-fact (data)", () => {
|
||||
let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
|
||||
m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
|
||||
// Review #4: `stopping` arms the poll but had no inactivity backstop.
|
||||
it("review-4: POLL_IDLE_CAP in `stopping` exits to idle (bounded), NOT stalled", () => {
|
||||
let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
|
||||
expect(m.phase.name).toBe("stopping");
|
||||
expect(hasEffect(m, "armPoll")).toBe(true);
|
||||
// MUTATION-VERIFY: drop the `stopping` branch in POLL_IDLE_CAP and this hangs
|
||||
// in `stopping` (poll forever) -> red.
|
||||
m = reduce(m, { type: "POLL_IDLE_CAP" });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(hasEffect(m, "disarmPoll")).toBe(true);
|
||||
expect(m.ctx.ownership).toBe("local");
|
||||
});
|
||||
});
|
||||
|
||||
// Review #1: positive attach outcomes must be guarded by the SOURCE phase — the
|
||||
// epoch filter alone is insufficient because POLL_TERMINAL uses to() (no epoch
|
||||
// bump) and does not abort the in-flight GET.
|
||||
describe("run-fsm — review-1: attach outcomes guarded by source phase", () => {
|
||||
it("a late RECONNECT_ATTACHED after POLL_TERMINAL stays idle (no phantom streaming)", () => {
|
||||
let m = withRunFact("run-1");
|
||||
m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: true, epoch: m.ctx.epoch });
|
||||
m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch }); // attach GET
|
||||
const epoch = m.ctx.epoch;
|
||||
// The armed degraded poll reaches the terminal row FIRST (epoch unchanged).
|
||||
m = reduce(m, { type: "POLL_TERMINAL" });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(m.ctx.epoch).toBe(epoch); // POLL_TERMINAL did NOT bump the epoch
|
||||
// The slow GET returns live 2xx under the SAME epoch — must NOT resurrect.
|
||||
m = reduce(m, { type: "RECONNECT_ATTACHED", epoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
|
||||
it("a late ATTACH_LIVE / ATTACH_NONE after leaving `attaching` is ignored", () => {
|
||||
let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
const epoch = m.ctx.epoch;
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch }); // attaching -> polling
|
||||
m = reduce(m, { type: "POLL_TERMINAL" }); // -> idle (epoch unchanged)
|
||||
expect(m.phase.name).toBe("idle");
|
||||
m = reduce(m, { type: "ATTACH_LIVE", epoch }); // late 2xx, same epoch
|
||||
expect(m.phase.name).toBe("idle");
|
||||
// And a late ATTACH_NONE (not `attaching`) is a no-op too.
|
||||
m = reduce(m, { type: "ATTACH_NONE", epoch });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
});
|
||||
});
|
||||
|
||||
// Review #2: every terminal transition resets ownership to local.
|
||||
describe("run-fsm — review-2: terminal transitions reset ownership to local", () => {
|
||||
const observer = (): Machine => {
|
||||
let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
|
||||
expect(m.ctx.ownership).toBe("observer");
|
||||
return m;
|
||||
};
|
||||
it("FINISH_CLEAN resets ownership", () => {
|
||||
const m = reduce(observer(), { type: "FINISH_CLEAN", epoch: observer().ctx.epoch });
|
||||
expect(m.ctx.ownership).toBe("local");
|
||||
});
|
||||
it("FINISH_ERROR / POLL_TERMINAL / RUN_FACT(null) reset ownership", () => {
|
||||
let o = observer();
|
||||
expect(reduce(o, { type: "FINISH_ERROR", kind: "stream", epoch: o.ctx.epoch }).ctx.ownership).toBe("local");
|
||||
// POLL_TERMINAL from an observer polling phase
|
||||
let p = reduce(observer(), { type: "STREAM_INCOMPLETE", reason: "starved", epoch: observer().ctx.epoch });
|
||||
expect(reduce(p, { type: "POLL_TERMINAL" }).ctx.ownership).toBe("local");
|
||||
// RUN_FACT(null) from an observer attaching phase
|
||||
let a = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
expect(reduce(a, { type: "RUN_FACT", runFact: null, epoch: a.ctx.epoch }).ctx.ownership).toBe("local");
|
||||
});
|
||||
});
|
||||
|
||||
describe("run-fsm — ownership (I2) is context, orthogonal to phase", () => {
|
||||
it("attach/reconnect set observer; send/supersede-ready set local", () => {
|
||||
let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
|
||||
expect(m.ctx.ownership).toBe("observer");
|
||||
m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
|
||||
expect(m.phase.name).toBe("streaming");
|
||||
expect(m.ctx.ownership).toBe("observer"); // still observing a detached run
|
||||
// A local send flips ownership back to local.
|
||||
m = reduce(m, { type: "SEND_LOCAL" });
|
||||
expect(m.ctx.ownership).toBe("local");
|
||||
});
|
||||
});
|
||||
|
||||
describe("run-fsm — dispose (I5)", () => {
|
||||
it("DISPOSE from any phase aborts controllers and bumps epoch", () => {
|
||||
let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
|
||||
const before = m.ctx.epoch;
|
||||
m = reduce(m, { type: "DISPOSE" });
|
||||
expect(m.phase.name).toBe("idle");
|
||||
expect(m.ctx.epoch).toBe(before + 1);
|
||||
expect(effectTypes(m)).toEqual(
|
||||
expect.arrayContaining(["abortAttach", "cancelReconnect", "disarmPoll"]),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,595 @@
|
||||
/**
|
||||
* Run-lifecycle finite state machine for a single AI-chat thread (#488).
|
||||
*
|
||||
* ============================================================================
|
||||
* WHY THIS EXISTS
|
||||
* ----------------------------------------------------------------------------
|
||||
* The resume/reconnect/poll/stop/supersede lifecycle used to be spread across
|
||||
* ~26 `useRef` one-shot flags in `chat-thread.tsx`, each disarmed "on every
|
||||
* path". Ownerless flag combinations produced silent UI freezes, and every fix
|
||||
* added another ref (the #381 -> #432 -> #456 spiral). This module replaces that
|
||||
* ref-zoo with ONE pure reducer whose transitions are enumerable and unit-
|
||||
* testable in isolation (event x state -> next state is the observable property).
|
||||
*
|
||||
* The reducer is PURE: it owns no timers, no fetches, no React state. It maps
|
||||
* `(machine, event) -> machine`, where the returned machine carries the list of
|
||||
* COMMAND EFFECTS to run for that transition. A thin runtime in `chat-thread.tsx`
|
||||
* dispatches events (from SDK callbacks / HTTP outcomes) and executes the
|
||||
* effects (attach GET, POST /stream, POST /run, POST /stop, backoff timers,
|
||||
* poll arm/disarm). The runtime lives in a THREAD, not the window, so a late SDK
|
||||
* callback dies with the owner (kills the "event from a dead view" class, #161).
|
||||
*
|
||||
* ============================================================================
|
||||
* INVARIANTS (see run-fsm.spec.md for the full spec + tables)
|
||||
* ----------------------------------------------------------------------------
|
||||
* I1 EPOCH (generation counter). Commands (`resumeStream`, `postRun`, `stop`,
|
||||
* `supersede`, `scheduleReconnect`) are async; their outcomes arrive on the
|
||||
* SAME SDK/HTTP callbacks. Every command-emitting transition increments
|
||||
* `ctx.epoch`; every OUTCOME event carries the epoch it was issued under;
|
||||
* the reducer DROPS an outcome whose epoch != the current epoch. This is
|
||||
* what the one-shot-ref zoo used to approximate by hand.
|
||||
* I2 OWNERSHIP is a CONTEXT FIELD (`'local' | 'observer'`), not a state —
|
||||
* orthogonal to the transport phase. The queue is flushed ONLY by a local
|
||||
* owner (an observer following a detached run never flushes).
|
||||
* I3 RUN-FACT ("a run is active") is first-class from the server: `runFact`
|
||||
* holds the server-confirmed active run id (POST /run on mount, the `start`
|
||||
* metadata runId, attach outcomes). Reconnect is entered by the RUN-FACT,
|
||||
* not by the presence of an assistant message (#488 commit 2). A fresh
|
||||
* negative fact (null) cancels reconnect immediately.
|
||||
* I4 Exit `stopping` by DATA (a terminal row / negative run-fact), NEVER by the
|
||||
* stopRun HTTP response (which returns after abort, before finalization).
|
||||
* I5 Command controllers are effect-owned (abort in cleanup), NOT render-phase
|
||||
* refs — expressed here as the `abortAttach` effect on disposing transitions.
|
||||
* ============================================================================
|
||||
*/
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Phases (the transport lifecycle). Ownership / runFact are CONTEXT, not here.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Why the degraded poll is the active recovery. */
|
||||
export type PollReason =
|
||||
| "attach-none" // mount attach returned 204 / error — nothing live to attach
|
||||
| "starved" // a resumed finish carried no visible content
|
||||
| "disconnect-visible" // a live disconnect WITH on-screen content — poll to terminal
|
||||
| "reconnect-exhausted"; // the live re-attach ladder gave up
|
||||
|
||||
/** The classified error kind (drives the banner text + composer behavior). */
|
||||
export type ErrorKind =
|
||||
| "stream" // a generic provider/network stream error (useChat error)
|
||||
| "run-already-active" // 409 A_RUN_ALREADY_ACTIVE (a plain POST hit the gate)
|
||||
| "supersede-mismatch" // 409 SUPERSEDE_TARGET_MISMATCH (CAS target moved)
|
||||
| "supersede-timeout" // 409 SUPERSEDE_TIMEOUT (old run did not settle in W)
|
||||
| "supersede-invalid" // 409 SUPERSEDE_INVALID (bad supersede target)
|
||||
| "begin-failed"; // 503 A_RUN_BEGIN_FAILED (could not start the run)
|
||||
|
||||
export type Phase =
|
||||
| { name: "idle" }
|
||||
| { name: "sending" } // local POST in flight, before the first frame
|
||||
| { name: "streaming" } // receiving frames
|
||||
| { name: "attaching" } // mount-time attach GET in flight
|
||||
| { name: "reconnecting"; attempt: number; failed: boolean }
|
||||
| { name: "polling"; reason: PollReason }
|
||||
| { name: "stalled" } // poll hit the inactivity cap — banner + Retry
|
||||
| { name: "stopping" }
|
||||
| { name: "superseding" }
|
||||
| { name: "error"; kind: ErrorKind };
|
||||
|
||||
export type Ownership = "local" | "observer";
|
||||
|
||||
/** The server-confirmed active run, or null when no run is active. */
|
||||
export type RunFact = { runId: string } | null;
|
||||
|
||||
export interface Ctx {
|
||||
/** I1: generation counter — every command-transition increments it. */
|
||||
epoch: number;
|
||||
/** I2: does THIS client own the turn's writes (local streamer) or observe? */
|
||||
ownership: Ownership;
|
||||
/** I3: the server-confirmed active run. */
|
||||
runFact: RunFact;
|
||||
/**
|
||||
* Are we FOLLOWING a live run we were locally streaming (the reconnect ladder),
|
||||
* as opposed to a one-shot mount-attach resume? Both are `ownership: 'observer'`,
|
||||
* but they recover DIFFERENTLY on a drop: a live-follow drop RE-ENTERS the
|
||||
* reconnect ladder (#488 commit 3 — the second break after a successful re-attach
|
||||
* must reconnect again, not fall to silent poll), while a mount-resume drop falls
|
||||
* to the degraded poll. This is the ctx bit that separates the two WITHOUT a new
|
||||
* component ref (it is why commit 3 needs the FSM, not a surgical patch).
|
||||
*/
|
||||
liveFollow: boolean;
|
||||
}
|
||||
|
||||
export interface Machine {
|
||||
phase: Phase;
|
||||
ctx: Ctx;
|
||||
/** Command effects to run for the transition that produced THIS machine.
|
||||
* The runtime executes them and does not read them again. */
|
||||
effects: Effect[];
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Command effects (the reducer's only side-channel — executed by the runtime).
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type Effect =
|
||||
/** POST /run to (re)establish or verify the run-fact. `reason` is diagnostic. */
|
||||
| { type: "postRun"; reason: "mount" | "verify" }
|
||||
/** Trigger the SDK `resumeStream()` (attach GET via prepareReconnectToStream). */
|
||||
| { type: "resumeStream" }
|
||||
/** Schedule a reconnect attempt after a backoff, then dispatch RECONNECT_ATTEMPT. */
|
||||
| { type: "scheduleReconnect"; attempt: number; delayMs: number }
|
||||
/** Cancel any pending reconnect backoff timer. */
|
||||
| { type: "cancelReconnect" }
|
||||
/** Arm the degraded poll (the window's dumb timer follows the run in the DB). */
|
||||
| { type: "armPoll"; reason: PollReason }
|
||||
/** Disarm the degraded poll. */
|
||||
| { type: "disarmPoll" }
|
||||
/** POST /stop the chat's active run (authoritative detached-run stop). */
|
||||
| { type: "stopRun" }
|
||||
/** POST /stream { supersede: { runId } } — the CAS "interrupt and send now". */
|
||||
| { type: "supersede"; targetRunId: string }
|
||||
/** Abort the in-flight attach/reconnect GET controller (dispose / observer stop). */
|
||||
| { type: "abortAttach" };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Events. An OUTCOME event MAY carry `epoch`; if it does and it does not equal
|
||||
// the current epoch, the reducer drops it (I1). Trigger events (user actions,
|
||||
// fresh disconnects) carry no epoch and are never dropped.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type Event =
|
||||
// -- local turn --
|
||||
| { type: "SEND_LOCAL" }
|
||||
| { type: "STREAM_START"; runId?: string; epoch?: number }
|
||||
/** An OBSERVER's attached stream ended WITHOUT reaching terminal (a starved
|
||||
* clean replay, or a torn resume) — fall to the degraded poll to drive the row
|
||||
* to its real terminal state. (A live-follow drop uses FINISH_DISCONNECT.) */
|
||||
| { type: "STREAM_INCOMPLETE"; reason: PollReason; epoch?: number }
|
||||
| { type: "FINISH_CLEAN"; epoch?: number }
|
||||
| { type: "FINISH_ABORT"; epoch?: number }
|
||||
| { type: "FINISH_DISCONNECT"; hasVisibleContent: boolean; epoch?: number }
|
||||
| { type: "FINISH_ERROR"; kind: ErrorKind; epoch?: number }
|
||||
// -- mount attach (resume) --
|
||||
| { type: "ATTACH_START"; runId?: string }
|
||||
| { type: "ATTACH_LIVE"; epoch?: number }
|
||||
| { type: "ATTACH_NONE"; epoch?: number }
|
||||
// -- reconnect after a live disconnect (entered by FINISH_DISCONNECT, #488 c2) --
|
||||
| { type: "RECONNECT_ATTEMPT"; attempt: number; epoch?: number }
|
||||
| { type: "RECONNECT_ATTACHED"; epoch?: number }
|
||||
| { type: "RECONNECT_NONE"; epoch?: number }
|
||||
| { type: "RETRY" }
|
||||
// -- degraded poll --
|
||||
| { type: "POLL_TERMINAL" }
|
||||
| { type: "POLL_IDLE_CAP" }
|
||||
// -- run-fact (server-confirmed active run) --
|
||||
| { type: "RUN_FACT"; runFact: RunFact; epoch?: number }
|
||||
// -- stop --
|
||||
| { type: "STOP_REQUESTED" }
|
||||
// -- supersede (CAS) --
|
||||
| { type: "SUPERSEDE_REQUESTED"; targetRunId: string }
|
||||
| { type: "SUPERSEDE_READY"; runId?: string; epoch?: number }
|
||||
| { type: "SUPERSEDE_MISMATCH"; currentRunId?: string; epoch?: number }
|
||||
| { type: "SUPERSEDE_TIMEOUT"; epoch?: number }
|
||||
| { type: "SUPERSEDE_INVALID"; epoch?: number }
|
||||
| { type: "RUN_ALREADY_ACTIVE" }
|
||||
// -- lifecycle --
|
||||
| { type: "DISPOSE" };
|
||||
|
||||
export const RECONNECT_MAX_ATTEMPTS = 5;
|
||||
export const RECONNECT_BASE_DELAY_MS = 1000;
|
||||
/** Backoff before attempt N (1-based): 1s, 2s, 4s, 8s, 16s. */
|
||||
export function reconnectDelayMs(attempt: number): number {
|
||||
return RECONNECT_BASE_DELAY_MS * 2 ** (attempt - 1);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constructors / helpers.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function initialMachine(overrides?: Partial<Ctx>): Machine {
|
||||
return {
|
||||
phase: { name: "idle" },
|
||||
ctx: { epoch: 0, ownership: "local", runFact: null, liveFollow: false, ...overrides },
|
||||
effects: [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Build a machine result: a phase, optional ctx patch, and effects. Empty
|
||||
* effects by default. Never mutates the input. */
|
||||
function to(
|
||||
m: Machine,
|
||||
phase: Phase,
|
||||
opts?: { ctx?: Partial<Ctx>; effects?: Effect[] },
|
||||
): Machine {
|
||||
return {
|
||||
phase,
|
||||
ctx: { ...m.ctx, ...(opts?.ctx ?? {}) },
|
||||
effects: opts?.effects ?? [],
|
||||
};
|
||||
}
|
||||
|
||||
/** No transition: keep the phase, clear effects (so a re-run does not re-fire). */
|
||||
function stay(m: Machine): Machine {
|
||||
return { phase: m.phase, ctx: m.ctx, effects: [] };
|
||||
}
|
||||
|
||||
/** A command-transition: same as `to` but bumps the epoch (I1). Any outcome
|
||||
* event issued under the old epoch is dropped once this lands. */
|
||||
function command(
|
||||
m: Machine,
|
||||
phase: Phase,
|
||||
effects: Effect[],
|
||||
ctx?: Partial<Ctx>,
|
||||
): Machine {
|
||||
return {
|
||||
phase,
|
||||
ctx: { ...m.ctx, ...(ctx ?? {}), epoch: m.ctx.epoch + 1 },
|
||||
effects,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// The pure reducer.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** The terminal stream-finish events (one turn's stream ended). */
|
||||
function isFinishEvent(event: Event): boolean {
|
||||
return (
|
||||
event.type === "FINISH_ABORT" ||
|
||||
event.type === "FINISH_CLEAN" ||
|
||||
event.type === "FINISH_DISCONNECT" ||
|
||||
event.type === "FINISH_ERROR" ||
|
||||
event.type === "STREAM_INCOMPLETE"
|
||||
);
|
||||
}
|
||||
|
||||
export function reduce(m: Machine, event: Event): Machine {
|
||||
// MEDIUM (#488 re-review): honor ANY stream finish in `stopping` regardless of
|
||||
// generation. A plain user Stop has NO successor stream — the aborted stream's
|
||||
// finish IS the expected end of the stop, so exit `stopping -> idle` by that DATA
|
||||
// (I4). The epoch filter below must NOT drop it: STOP_REQUESTED bumped the epoch,
|
||||
// but the finish carries the PRE-stop generation (the runtime stamps it with the
|
||||
// stream's start epoch), so I1 would otherwise strand the machine in `stopping`
|
||||
// forever (no idle-cap covers `stopping`). The epoch filter stays in force for
|
||||
// `superseding` (a successor B owns) — that is the F1 supersede drop.
|
||||
if (m.phase.name === "stopping" && isFinishEvent(event)) {
|
||||
return to(m, { name: "idle" }, {
|
||||
// Reset ownership to local on this terminal transition (review #2): otherwise
|
||||
// an observer-stop leaves ownership 'observer' and hides "Send now" forever.
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
}
|
||||
|
||||
// I1: drop a stale outcome (an event issued under a superseded epoch).
|
||||
if ("epoch" in event && event.epoch !== undefined && event.epoch !== m.ctx.epoch) {
|
||||
return stay(m);
|
||||
}
|
||||
|
||||
switch (event.type) {
|
||||
// ---- local turn ----------------------------------------------------
|
||||
case "SEND_LOCAL":
|
||||
// A local send owns the view: leave any recovery, become the local
|
||||
// streamer, disarm poll/reconnect. epoch++ so a late recovery outcome
|
||||
// from the previous phase is dropped.
|
||||
return command(
|
||||
m,
|
||||
{ name: "sending" },
|
||||
[{ type: "cancelReconnect" }, { type: "disarmPoll" }],
|
||||
{ ownership: "local", liveFollow: false },
|
||||
);
|
||||
|
||||
case "STREAM_INCOMPLETE":
|
||||
// An OBSERVER's attached stream ended incomplete (starved / torn) — follow
|
||||
// the run to terminal via the degraded poll.
|
||||
return to(m, { name: "polling", reason: event.reason }, {
|
||||
effects: [{ type: "armPoll", reason: event.reason }],
|
||||
});
|
||||
|
||||
case "STREAM_START": {
|
||||
// First frame arrived. Adopt the run-fact runId if present. sending ->
|
||||
// streaming; a reconnect/attach that just went live also lands here.
|
||||
const runFact = event.runId ? { runId: event.runId } : m.ctx.runFact;
|
||||
return to(m, { name: "streaming" }, {
|
||||
ctx: { runFact },
|
||||
effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
|
||||
});
|
||||
}
|
||||
|
||||
case "FINISH_CLEAN":
|
||||
// A clean terminal outcome. The run is done — clear the run-fact and go
|
||||
// idle. (The queue flush is a component concern gated by ownership; the
|
||||
// FSM only models the phase.) Review #2: reset ownership to local so a
|
||||
// just-finished observer-attach turn re-exposes "Send now" for the queue.
|
||||
return to(m, { name: "idle" }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
|
||||
case "FINISH_ABORT":
|
||||
// A user Stop / intentional abort finished. If we were stopping, the
|
||||
// terminal data has now arrived (I4) — go idle. The run-fact is cleared.
|
||||
return to(m, { name: "idle" }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
|
||||
case "FINISH_DISCONNECT":
|
||||
// A LIVE SSE drop. Recovery depends on WHO we are (I2 + liveFollow):
|
||||
// - a mount-attach OBSERVER (a one-shot resume, NOT live-follow) that drops
|
||||
// -> the degraded poll drives the row to terminal from the DB.
|
||||
if (m.ctx.ownership === "observer" && !m.ctx.liveFollow) {
|
||||
return to(m, { name: "polling", reason: "disconnect-visible" }, {
|
||||
effects: [{ type: "armPoll", reason: "disconnect-visible" }],
|
||||
});
|
||||
}
|
||||
// - a LOCAL live turn (first drop) OR a live-follow re-attach (a SUBSEQUENT
|
||||
// drop) -> (re-)enter the reconnect ladder. #488 commit 3: allowed
|
||||
// REPEATEDLY — `liveFollow` is kept across a successful re-attach, so the
|
||||
// second break reconnects again instead of falling to silent poll.
|
||||
// #488 commit 2: gated on the RUN-FACT (or an existing live-follow), NOT on
|
||||
// the presence of an assistant message — a setup-phase break still recovers.
|
||||
// - visible content already on screen -> keep it, ALSO poll to terminal
|
||||
// (a full replay could clobber the fuller live tail);
|
||||
// - no visible content -> the reconnect ladder rebuilds it.
|
||||
if (m.ctx.runFact || m.ctx.liveFollow) {
|
||||
const effects: Effect[] = [
|
||||
{ type: "scheduleReconnect", attempt: 1, delayMs: reconnectDelayMs(1) },
|
||||
];
|
||||
if (event.hasVisibleContent) effects.push({ type: "armPoll", reason: "disconnect-visible" });
|
||||
return command(m, { name: "reconnecting", attempt: 1, failed: false }, effects, {
|
||||
ownership: "observer",
|
||||
liveFollow: true,
|
||||
});
|
||||
}
|
||||
// No run to recover: a plain disconnect. Surface the terminal notice.
|
||||
return to(m, { name: "idle" }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
});
|
||||
|
||||
case "FINISH_ERROR":
|
||||
return to(m, { name: "error", kind: event.kind }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
|
||||
// ---- mount attach (resume) ----------------------------------------
|
||||
case "ATTACH_START":
|
||||
// A reopened tab attaches to a still-running run: observer ownership.
|
||||
// #488 F2: ONLY from idle. The mount `getRun` round-trip resolves async, and
|
||||
// a local send may have started meanwhile (phase `sending`, ownership local);
|
||||
// a late ATTACH_START must NOT hijack that local turn into an observer-attach
|
||||
// (queue would stop flushing, "Send now" would hide). Guarding in the reducer
|
||||
// covers every dispatch source.
|
||||
if (m.phase.name !== "idle") return stay(m);
|
||||
return command(m, { name: "attaching" }, [{ type: "resumeStream" }], {
|
||||
ownership: "observer",
|
||||
runFact: event.runId ? { runId: event.runId } : m.ctx.runFact,
|
||||
});
|
||||
|
||||
case "ATTACH_LIVE":
|
||||
// The attach GET returned a live 2xx stream — follow it as an observer.
|
||||
// Review #1: guard by SOURCE phase. The epoch filter alone is not enough — a
|
||||
// POLL_TERMINAL uses to() (no epoch bump) and does not abort the in-flight
|
||||
// GET, so a slow 2xx landing after the machine already left `attaching` (e.g.
|
||||
// the armed poll saw the terminal row -> idle) would resurrect a settled run
|
||||
// into a phantom `streaming`. Only enter streaming FROM `attaching`.
|
||||
if (m.phase.name !== "attaching") return stay(m);
|
||||
return to(m, { name: "streaming" });
|
||||
|
||||
case "ATTACH_NONE":
|
||||
// 204 / non-2xx / throw: nothing live to attach. Arm the degraded poll to
|
||||
// follow the run to terminal from the DB. This is a soft-negative run-fact
|
||||
// (204 on a non-stripped path is authoritative-negative; the runtime may
|
||||
// pass a RUN_FACT null separately). Keep the run-fact as-is here.
|
||||
// Review #1: guard by source phase for consistency (a late outcome after the
|
||||
// machine already left `attaching` must not re-arm a poll).
|
||||
if (m.phase.name !== "attaching") return stay(m);
|
||||
return to(m, { name: "polling", reason: "attach-none" }, {
|
||||
effects: [{ type: "armPoll", reason: "attach-none" }],
|
||||
});
|
||||
|
||||
// ---- reconnect after a live disconnect ----------------------------
|
||||
case "RECONNECT_ATTEMPT":
|
||||
// A scheduled backoff fired — fire the attach GET. epoch++ so the previous
|
||||
// attempt's late outcome cannot drive this one.
|
||||
if (m.phase.name !== "reconnecting") return stay(m);
|
||||
return command(
|
||||
m,
|
||||
{ name: "reconnecting", attempt: event.attempt, failed: false },
|
||||
[{ type: "resumeStream" }],
|
||||
);
|
||||
|
||||
case "RECONNECT_ATTACHED":
|
||||
// #488 commit 3: a live re-attach succeeded. Reset to streaming — the
|
||||
// attempt counter is dropped, so a LATER disconnect can start a fresh
|
||||
// ladder from attempt 1 (the old one-shot `!wasResumed` gate forbade a
|
||||
// second cycle, sending the second break to silent poll).
|
||||
// Review #1: guard by SOURCE phase. The armed degraded poll can reach the
|
||||
// terminal row (POLL_TERMINAL -> idle, via to(), NO epoch bump, GET not
|
||||
// aborted) BEFORE a slow reconnect GET returns 2xx; without this guard that
|
||||
// late RECONNECT_ATTACHED (same epoch) would resurrect a settled run into a
|
||||
// phantom `streaming`. Only re-enter streaming FROM `reconnecting`.
|
||||
if (m.phase.name !== "reconnecting") return stay(m);
|
||||
return to(m, { name: "streaming" }, {
|
||||
effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
|
||||
});
|
||||
|
||||
case "RECONNECT_NONE": {
|
||||
// 204 / error during a reconnect attempt. Arm the degraded poll as the
|
||||
// belt-and-suspenders fallback, then either back off to the next attempt
|
||||
// or, at the cap, surface the manual Retry ("failed").
|
||||
if (m.phase.name !== "reconnecting") return stay(m);
|
||||
const attempt = m.phase.attempt;
|
||||
if (attempt < RECONNECT_MAX_ATTEMPTS) {
|
||||
return command(
|
||||
m,
|
||||
{ name: "reconnecting", attempt: attempt + 1, failed: false },
|
||||
[
|
||||
{ type: "armPoll", reason: "attach-none" },
|
||||
{ type: "scheduleReconnect", attempt: attempt + 1, delayMs: reconnectDelayMs(attempt + 1) },
|
||||
],
|
||||
);
|
||||
}
|
||||
return to(m, { name: "reconnecting", attempt, failed: true }, {
|
||||
effects: [{ type: "armPoll", reason: "reconnect-exhausted" }],
|
||||
});
|
||||
}
|
||||
|
||||
case "RETRY":
|
||||
// Manual Retry from the "failed" reconnect banner OR the stalled banner.
|
||||
if (m.phase.name === "reconnecting" && m.phase.failed) {
|
||||
return command(
|
||||
m,
|
||||
{ name: "reconnecting", attempt: 1, failed: false },
|
||||
[{ type: "resumeStream" }],
|
||||
);
|
||||
}
|
||||
if (m.phase.name === "stalled") {
|
||||
// Re-arm the poll to try to catch the run up again.
|
||||
return command(m, { name: "polling", reason: "attach-none" }, [
|
||||
{ type: "armPoll", reason: "attach-none" },
|
||||
]);
|
||||
}
|
||||
return stay(m);
|
||||
|
||||
// ---- degraded poll -------------------------------------------------
|
||||
case "POLL_TERMINAL":
|
||||
// The run reached a terminal row via the poll (or the reconcile merge). Go
|
||||
// idle and disarm everything (I4: this is a DATA-driven exit, incl. exit
|
||||
// from `stopping`). Review #2: reset ownership to local.
|
||||
return to(m, { name: "idle" }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
|
||||
case "POLL_IDLE_CAP":
|
||||
// Review #4: `stopping` also arms the poll (STOP_REQUESTED) but has NO other
|
||||
// backstop — an observer-stop with no SDK stream to fire onFinish, whose
|
||||
// server stop never drives the run terminal, would poll the DB forever. Give
|
||||
// it a bounded exit: cap -> idle + disarm (NOT `stalled`; Stop was already
|
||||
// pressed, so there is nothing for the user to retry).
|
||||
if (m.phase.name === "stopping") {
|
||||
return to(m, { name: "idle" }, {
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
}
|
||||
// #488 commit 4a: the poll hit the inactivity cap. Instead of going SILENT
|
||||
// (the old "forever half-done answer"), surface a stalled banner + Retry.
|
||||
if (m.phase.name !== "polling" && m.phase.name !== "reconnecting") return stay(m);
|
||||
return to(m, { name: "stalled" }, {
|
||||
effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
|
||||
});
|
||||
|
||||
// ---- run-fact ------------------------------------------------------
|
||||
case "RUN_FACT": {
|
||||
const runFact = event.runFact;
|
||||
// A fresh NEGATIVE fact (no active run) cancels recovery immediately (I3):
|
||||
// there is nothing to reconnect to / poll for.
|
||||
if (!runFact) {
|
||||
if (
|
||||
m.phase.name === "reconnecting" ||
|
||||
m.phase.name === "attaching" ||
|
||||
m.phase.name === "polling" ||
|
||||
m.phase.name === "stopping"
|
||||
) {
|
||||
return to(m, { name: "idle" }, {
|
||||
// Review #2: reset ownership to local on this terminal transition.
|
||||
ctx: { runFact: null, liveFollow: false, ownership: "local" },
|
||||
effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
|
||||
});
|
||||
}
|
||||
return to(m, m.phase, { ctx: { runFact: null } });
|
||||
}
|
||||
// A positive fact just updates the context (pessimism toward an attempt: a
|
||||
// stale-but-positive fact permits entering recovery; a 204 will cut it).
|
||||
return to(m, m.phase, { ctx: { runFact } });
|
||||
}
|
||||
|
||||
// ---- stop ----------------------------------------------------------
|
||||
case "STOP_REQUESTED":
|
||||
// Authoritative stop of a detached run. Enter `stopping` and fire stopRun +
|
||||
// abort the local/attach reader. ALSO arm the poll so the terminal row is
|
||||
// observed — the exit is by DATA (I4: a terminal row / negative run-fact),
|
||||
// never by the stopRun HTTP response (which returns after abort, before
|
||||
// finalization). For a local turn the aborted stream's onFinish (ANY finish)
|
||||
// is HONORED in `stopping` at the top of reduce() — regardless of generation
|
||||
// — and exits to idle; the armed poll is the fallback for an observer stop
|
||||
// with no local onFinish.
|
||||
return command(
|
||||
m,
|
||||
{ name: "stopping" },
|
||||
[
|
||||
{ type: "stopRun" },
|
||||
{ type: "abortAttach" },
|
||||
{ type: "cancelReconnect" },
|
||||
{ type: "armPoll", reason: "attach-none" },
|
||||
],
|
||||
);
|
||||
|
||||
// ---- supersede (CAS) ----------------------------------------------
|
||||
case "SUPERSEDE_REQUESTED":
|
||||
// "Interrupt and send now": CAS POST /stream { supersede }. epoch++ so a
|
||||
// late outcome of the interrupted run is dropped.
|
||||
return command(
|
||||
m,
|
||||
{ name: "superseding" },
|
||||
[{ type: "supersede", targetRunId: event.targetRunId }, { type: "cancelReconnect" }, { type: "disarmPoll" }],
|
||||
);
|
||||
|
||||
case "SUPERSEDE_READY": {
|
||||
// CAS succeeded (old run stopped/settled, slot taken, new run begun). We
|
||||
// are now the local streamer of the NEW run. Adopt its runId if provided.
|
||||
const runFact = event.runId ? { runId: event.runId } : m.ctx.runFact;
|
||||
return to(m, { name: "streaming" }, {
|
||||
ctx: { ownership: "local", runFact, liveFollow: false },
|
||||
});
|
||||
}
|
||||
|
||||
case "SUPERSEDE_MISMATCH":
|
||||
// The active run moved between the click and the CAS. Per the spec: verify
|
||||
// via /run rather than blindly banner — the mismatch may be our own already-
|
||||
// superseded run. Surface a classified error AND fire a run-fact verify.
|
||||
return to(m, { name: "error", kind: "supersede-mismatch" }, {
|
||||
ctx: { runFact: event.currentRunId ? { runId: event.currentRunId } : m.ctx.runFact },
|
||||
effects: [{ type: "postRun", reason: "verify" }],
|
||||
});
|
||||
|
||||
case "SUPERSEDE_TIMEOUT":
|
||||
// The old run did not settle within W. Nothing persisted; the composer keeps
|
||||
// its text. Classified error, NO auto-retry (the old client retry ladder is
|
||||
// removed in #488 commit 5).
|
||||
return to(m, { name: "error", kind: "supersede-timeout" });
|
||||
|
||||
case "SUPERSEDE_INVALID":
|
||||
return to(m, { name: "error", kind: "supersede-invalid" });
|
||||
|
||||
case "RUN_ALREADY_ACTIVE":
|
||||
// A plain POST hit the one-active-run gate. NO auto-retry — the composer
|
||||
// offers "interrupt and send" (supersede) instead.
|
||||
return to(m, { name: "error", kind: "run-already-active" });
|
||||
|
||||
// ---- lifecycle -----------------------------------------------------
|
||||
case "DISPOSE":
|
||||
// Unmount: abort in-flight controllers, drop timers, and bump the epoch so
|
||||
// NO late callback can drive this (now dead) machine (I5).
|
||||
return command(
|
||||
m,
|
||||
{ name: "idle" },
|
||||
[
|
||||
{ type: "abortAttach" },
|
||||
{ type: "cancelReconnect" },
|
||||
{ type: "disarmPoll" },
|
||||
],
|
||||
{ liveFollow: false },
|
||||
);
|
||||
|
||||
default: {
|
||||
// Exhaustiveness guard.
|
||||
const _never: never = event;
|
||||
void _never;
|
||||
return stay(m);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -3,6 +3,7 @@ import {
|
||||
resolveAdoptedChatId,
|
||||
newlyAddedChatIds,
|
||||
extractServerChatId,
|
||||
extractRunId,
|
||||
} from "./adopt-chat-id";
|
||||
|
||||
describe("resolveAdoptedChatId", () => {
|
||||
@@ -70,3 +71,17 @@ describe("extractServerChatId", () => {
|
||||
expect(extractServerChatId(undefined)).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("extractRunId", () => {
|
||||
it("reads a string runId from the start metadata", () => {
|
||||
expect(extractRunId({ metadata: { runId: "run-1" } })).toBe("run-1");
|
||||
});
|
||||
it("returns undefined when runId is absent", () => {
|
||||
expect(extractRunId({ metadata: { chatId: "c" } })).toBeUndefined();
|
||||
expect(extractRunId({})).toBeUndefined();
|
||||
expect(extractRunId(undefined)).toBeUndefined();
|
||||
});
|
||||
it("returns undefined for a non-string runId", () => {
|
||||
expect(extractRunId({ metadata: { runId: 7 } })).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -56,6 +56,20 @@ export function extractServerChatId(
|
||||
return typeof m?.chatId === "string" ? m.chatId : undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* #488: read the authoritative RUN id off a streaming assistant message. The
|
||||
* server attaches it as `message.metadata.runId` on the `start` part when a run
|
||||
* wraps the turn (see server `chatStreamMetadata`, #184/#487). This is the live
|
||||
* run-fact update the client FSM adopts (mirrors `extractServerChatId`). Returns
|
||||
* it only when it is a string; undefined otherwise.
|
||||
*/
|
||||
export function extractRunId(
|
||||
message: { metadata?: unknown } | undefined,
|
||||
): string | undefined {
|
||||
const m = message?.metadata as { runId?: string } | undefined;
|
||||
return typeof m?.runId === "string" ? m.runId : undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* The deduped set of ids present in `afterIds` but not in `beforeIds`. A
|
||||
* paginated/flatMapped list can repeat the same id, so dedupe: one genuinely-new
|
||||
|
||||
@@ -42,6 +42,51 @@ describe("describeChatError", () => {
|
||||
);
|
||||
});
|
||||
|
||||
// #488 commit 5: the #487 concurrency-gate / supersede 409s. FULL real bodies:
|
||||
// a ConflictException(object) whose response is serialized verbatim, carrying a
|
||||
// `code` and statusCode 409. Each must classify to a human text, not raw JSON.
|
||||
it("classifies A_RUN_ALREADY_ACTIVE (409) as already-answering, not raw JSON", () => {
|
||||
const body =
|
||||
'{"message":"A run is already active for this chat","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
|
||||
expect(describeChatError(body, t).title).toBe(
|
||||
"The agent is already answering",
|
||||
);
|
||||
// Never leaks the raw code as the detail.
|
||||
expect(describeChatError(body, t).detail).not.toContain("A_RUN_ALREADY_ACTIVE");
|
||||
});
|
||||
|
||||
it("classifies SUPERSEDE_TARGET_MISMATCH (409) as run-changed", () => {
|
||||
const body =
|
||||
'{"message":"active run does not match the supersede target","code":"SUPERSEDE_TARGET_MISMATCH","runId":"run-x","statusCode":409}';
|
||||
expect(describeChatError(body, t).title).toBe(
|
||||
"Couldn't interrupt — the run changed",
|
||||
);
|
||||
});
|
||||
|
||||
it("classifies SUPERSEDE_TIMEOUT (409) as couldn't-interrupt-in-time", () => {
|
||||
const body =
|
||||
'{"message":"the run did not settle within the supersede window","code":"SUPERSEDE_TIMEOUT","statusCode":409}';
|
||||
expect(describeChatError(body, t).title).toBe("Couldn't interrupt in time");
|
||||
});
|
||||
|
||||
it("classifies SUPERSEDE_INVALID (409) as couldn't-interrupt-that-run", () => {
|
||||
const body =
|
||||
'{"message":"supervise requires chatId","code":"SUPERSEDE_INVALID","statusCode":409}';
|
||||
expect(describeChatError(body, t).title).toBe(
|
||||
"Couldn't interrupt that run",
|
||||
);
|
||||
});
|
||||
|
||||
it("ORDER GUARD: A_RUN_ALREADY_ACTIVE wins over any generic status branch", () => {
|
||||
// Even though the body could superficially look 4xx-ish, the code branch runs
|
||||
// first, so it is never mislabeled by a generic status heading.
|
||||
const body =
|
||||
'{"message":"conflict","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
|
||||
const view = describeChatError(body, t);
|
||||
expect(view.title).not.toBe("Something went wrong");
|
||||
expect(view.title).not.toBe("AI provider not configured");
|
||||
});
|
||||
|
||||
it("classifies a dropped connection (ECONNRESET) as a lost-connection error", () => {
|
||||
expect(
|
||||
describeChatError("Cannot connect to API: read ECONNRESET", t).title,
|
||||
|
||||
@@ -39,6 +39,44 @@ export function describeChatError(
|
||||
};
|
||||
}
|
||||
|
||||
// #488 commit 5: the #487 concurrency-gate / supersede 409s. These arrive as a
|
||||
// ConflictException(object) body carrying a `code` (and statusCode 409). They
|
||||
// MUST be classified by `code` STRICTLY BEFORE any generic status branch, or the
|
||||
// user sees the raw JSON `{"code":"A_RUN_ALREADY_ACTIVE",…}`. The code strings
|
||||
// are the real #487 server contract (ai-chat.controller.ts) — do not invent.
|
||||
if (/"code"\s*:\s*"A_RUN_ALREADY_ACTIVE"/.test(msg)) {
|
||||
return {
|
||||
title: t("The agent is already answering"),
|
||||
detail: t(
|
||||
"This chat already has a run in progress. Wait for it to finish, or interrupt it and send now.",
|
||||
),
|
||||
};
|
||||
}
|
||||
if (/"code"\s*:\s*"SUPERSEDE_TARGET_MISMATCH"/.test(msg)) {
|
||||
return {
|
||||
title: t("Couldn't interrupt — the run changed"),
|
||||
detail: t(
|
||||
"The run you tried to interrupt is no longer the active one. Check the latest answer and try again.",
|
||||
),
|
||||
};
|
||||
}
|
||||
if (/"code"\s*:\s*"SUPERSEDE_TIMEOUT"/.test(msg)) {
|
||||
return {
|
||||
title: t("Couldn't interrupt in time"),
|
||||
detail: t(
|
||||
"The previous run didn't stop in time. Nothing was sent — try sending again.",
|
||||
),
|
||||
};
|
||||
}
|
||||
if (/"code"\s*:\s*"SUPERSEDE_INVALID"/.test(msg)) {
|
||||
return {
|
||||
title: t("Couldn't interrupt that run"),
|
||||
detail: t(
|
||||
"The run to interrupt doesn't belong to this chat. Reload and try again.",
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
if (/"statusCode"\s*:\s*403\b/.test(msg)) {
|
||||
return {
|
||||
title: t("AI chat is disabled"),
|
||||
|
||||
Reference in New Issue
Block a user