PR: #310: [Story-1223] Step-5 binds the live Atlas WS rail (ADR-110 T9)
by @ankitmaheshwari-com
View PR →
Story-1223 · pramaan-docs ADR-110 T9
Step-5 wizard binds the live WebSocket rail
What changed
| Piece | Role |
|---|
src/lib/agents/atlas-rail.ts | Pure, fully unit-tested core: v1 frame reducer (run.accepted → turn.delta → turn.completed → run.done/run.failed + disconnected state, unknown frames ignored forward-compatibly), wire→UI AtlasTurn/MatterFrameProposal mappers, wizard-draft → AtlasIntakeInput snapshot builder (minor-units conversion, party mapping), camelCase launch builder with history + counsel message. |
src/lib/agents/use-atlas-rail.ts | Transport-only hook: ONE WebSocket per wizard session, Clerk pramaan-api template token on connect, lazy first launch when Step 5 activates, follow-up sends as fresh launches carrying the thread as history, reconnect-with-fresh-token between turns, socket drop mid-run → status disconnected (the run survives server-side per ADR-110 §4.1). |
Wizard + Step5ReviewForm | The stub turn (buildStubAtlasTurn) is replaced by live rail state; the drawer's send box posts real counsel messages via the new optional onSendMessage prop (stories/mocks unaffected). The all-clear save gate now reflects Atlas's real verdict. |
| Backend sliver | pramaan-functions #321: history rides launch→queue→worker→agent_invoke.v1 so follow-up turns aren't amnesiac. |
Wire ↔ UI mapping (the one impedance point)
wire turn (snake_case) UI AtlasTurn
verdict / next_message_md / is_terminal → verdict / nextMessageMd / isTerminal
proposal.description → proposal.summary (+ first ¶ as understanding)
proposal.refined.core_dispute … → proposal.refined.coreDispute … (camelCase)
run.failed {user_visible_message} → verdict "error" turn (broker-filtered text only)
Verification
vitest: 476 passed (7 new rail tests: reducer sequence, failure mapping,
forward-compat, snapshot builder incl. minor-units, launch shape) · tsc clean
Tracked follow-ups: run-truth refetch endpoint for resuming a dropped mid-run view; findings (open_questions) card mapping once the agent-typed finding contract is generated into src/gen per HR-22.
Env: NEXT_PUBLIC_AGENTS_WS_URL → the Terraform-owned staging WS API. Drawer naming honors the freeze: “Atlas” + active dot, no role label.
Files changed
6 file(s), +581 / -11 lines
| Path |
Role |
+ |
- |
| src/components/add-matter/add-matter-wizard.tsx | Component | +9 | -10 |
| src/components/add-matter/step5-review/step5-review-form.tsx | Component | +8 | -1 |
| src/lib/agents/__tests__/atlas-rail.test.ts | Library | +141 | -0 |
| src/lib/agents/atlas-rail.ts | Library | +263 | -0 |
| src/lib/agents/use-atlas-rail.ts | Library | +146 | -0 |
| tests/unit/add-matter-wizard-label-gate.test.tsx | Test | +14 | -0 |