Web client's mirrored WebSocket frame types have drifted from the server union in both directions — 5 payloads, 5 inline casts hiding it (folds in #772)

[edspencer]

Summary

packages/web/src/lib/types.ts hand-mirrors the server's ServerMessage frames, and the mirror has drifted: three of the queue frames omit the fields #728 added, and chat:killed_task declares two fields the server never sends. The runtime handlers work around the gap with inline as {…} casts, so TypeScript is not checking the attachment plumbing at all.

Evidence

chat:queued_flushed — web (packages/web/src/lib/types.ts:1269):

payload: { projectSlug: string; sessionId: string };

server (packages/server/src/ws-protocol.ts:555-574) additionally sends text?: string and attachments?: Array<{ id; filename; kind? }>.

chat:queued_state — web (:1279-1286) has projectSlug, sessionId, text, qid?, reason? but no attachments; server (ws-protocol.ts:588-617) sends attachments?: Array<{ id; filename; kind? }>.

chat:queued_returned — web (:1296):

payload: { projectSlug: string; sessionId: string; text: string };

server (ws-protocol.ts:633-647) also sends attachments?.

The handlers then cast straight past the declared type:

• packages/web/src/lib/ws.ts:705-709 — const { sessionId, text, attachments } = msg.payload as { sessionId?; text?; attachments?: AttachmentRef[] }
• packages/web/src/lib/ws.ts:734-740 — same shape for chat:queued_state
• packages/web/src/lib/ws.ts:768-772 — same for chat:queued_returned

So the fields that carry a user's queued files across clients are read entirely through an assertion. If the server renamed attachments or changed the element shape, nothing in the web build would fail.

chat:killed_task — web (:1315) types the payload as Routing & { sessionId; summary; timestamp }. Routing (types.ts:1138-1148) contributes projectSlug, sessionId, jobId: string | null and seq?: number. The server's emit (packages/server/src/ws-turn.ts:848-856) sends only projectSlug, sessionId, summary, timestamp — no jobId (and it is an out-of-band hub.broadcast, so no per-turn seq either). The declared type claims a non-optional jobId that is always undefined at runtime.

Why it matters

The whole point of mirroring the frames client-side is to get a compile error when the wire contract moves. Here the mirror is stale on precisely the fields a recent feature (#728, queued attachments) added, and the casts mean the drift produced no signal. chat:killed_task fails in the other direction — the compiler will happily let code read payload.jobId as a string | null that is never present.

Suggested fix

1. Bring the three queue payloads in line with ws-protocol.ts (add text? / attachments?), then drop the inline as {…} casts in ws.ts:705-709, :734-740, :768-772 so the destructuring is type-checked.
2. Type chat:killed_task from what the server sends rather than Routing & — i.e. { projectSlug; sessionId; summary; timestamp }.
3. Worth considering as the durable fix: generate or share the client union from packages/server/src/ws-protocol.ts instead of maintaining a second hand-written copy. Related: the chat:injected gap filed separately.

[edspencer]

Folding #772 in here, and adding a frame this issue didn't know about

#772 (chat:injected is emitted but is not a member of the server ServerMessage union) is being closed in favour of this issue. Item 3 of this ticket's own fix plan already names it as the same gap: packages/web/src/lib/types.ts hand-mirrors ws-protocol.ts with nothing enforcing the correspondence, so frames drift in both directions. One fix — share or generate the union — closes both.

What #772 adds:

• Emitted at packages/server/src/ws-turn.ts:483-492.
• Declared and handled on the client (packages/web/src/lib/types.ts:1322, packages/web/src/lib/ws.ts).
• Absent from the server union: ws-protocol.ts:764-779 now lists 15 members (was 13 when chat:injected is emitted but is not a member of the server ServerMessage union — the emit seam is untyped #772 was filed — PR feat(server,web): show background work that is still running, pinned above the composer (#604) #807 added ChatBackgroundMessage). grep -n 'Injected' ws-protocol.ts returns nothing. It typechecks only because the emit seam is untyped.

New drift, added by PR #807 (#604) after this issue was filed — two items:

1. chat:background repeats the chat:killed_task defect exactly. Web types.ts:1342-1343 types the payload as Routing & { sessionId: string; tasks: LiveBackgroundTask[] }. The server sends only { projectSlug, sessionId, tasks } (ws-protocol.ts:738-745, emitted at ws.ts:319 and :1521). Routing therefore contributes a non-optional jobId: string | null plus seq? that never arrive — the same shape defect this issue already documents for chat:killed_task.
2. A fifth inline cast at packages/web/src/lib/ws.ts:761-766 (msg.payload as { sessionId?; tasks? }), continuing the pattern.

Not drift, for the record: turnRunning? on chat:active is correctly mirrored on both sides (ws-protocol.ts:562+, types.ts:1280), and web's LiveBackgroundTask matches server's LiveBackgroundTaskWire field-for-field.

Revised size: S — 5 payloads and 5 cast removals, up from 4 and 3.

⚠️ Two cautions for whoever takes this.

• The "close the seam" suggestion (make TurnHandle.emit / hub.broadcast take ServerMessage) is not part of the S. HubMessageInput is deliberately loose ({ type: string; payload: object }) because the typed payload interfaces have no string index signature. Tightening it touches every emit site in ws-turn.ts / ws.ts plus the hub's buffering — a separate M, and it should be filed as one rather than smuggled into this PR.
• Removing the as {…} casts may surface genuine type errors in the handlers (AttachmentRef versus the inline {id; filename; kind?} shape). Note also that packages/web/src/lib/types.ts is not covered by the server's typecheck config — verify with the web package's own build, not tsc -p packages/server.

Retitling to match the widened scope.

[edspencer]

Still valid, and it has grown by one. Re-verified against main at b2503ec (v0.69.0).

New since this was filed: a fifth inline cast

#807 (background work above the composer) added chat:background to the wire, and it took the same shortcut as the other four — packages/web/src/lib/ws.ts:763:

if (msg.type === "chat:background") {
  // App-level and LEVEL semantics: replace this session's set outright.
  const { sessionId, tasks } = msg.payload as {
    sessionId?: string;
    tasks?: LiveBackgroundTask[];
  };

Full current set of inline msg.payload as {…} casts in the frame dispatcher:

line	frame
:763	chat:background ← new, added by #807
:801	chat:queued_flushed
:830	chat:queued_state
:864	chat:queued_returned
:893	chat:killed_task

That the count went up rather than down between the filing and now is the argument for the issue: each new frame costs one more cast, because there is nothing in the type system pushing back. chat:background is a case where it bites — the payload is a LEVEL frame with REPLACE semantics carrying LiveBackgroundTaskWire[] (server-side truth: packages/server/src/ws-protocol.ts:705, packages/server/src/background-live.ts:50-78), and the client-side cast declares both fields optional, so a server-side shape change to tasks[] produces no type error here at all.

The four mirrored-type drifts originally cited are also unchanged in packages/web/src/lib/types.ts — :1286, :1296-1303, :1313 (all three missing attachments) and :1332 (chat:killed_task typed as Routing &, so a phantom jobId).

No action taken beyond recording this.

[edspencer]

Still valid, and it has grown — there is now a fifth inline cast. Re-verified from source on main @ b2503ec.

New since this issue was filed

#807 (background work above the composer, v0.69.0) added chat:background, and it landed with the same pattern this issue is about:

packages/web/src/lib/ws.ts:763

if (msg.type === "chat:background") {
  // App-level and LEVEL semantics: replace this session's set outright.
  const { sessionId, tasks } = msg.payload as {
    sessionId?: string;
    tasks?: LiveBackgroundTask[];
  };

So the full cast list is now five, not four:

ws.ts	frame
:763	chat:background ← new
:801	chat:queued_flushed
:830	chat:queued_state
:864	chat:queued_returned
:893	chat:killed_task

(:915 is a separate narrow (msg.payload as { seq?: number }) and is not one of these.)

Why this one is worth calling out specifically

The mirrored type at packages/web/src/lib/types.ts:1342-1343 is actually correct for this frame:

type: "chat:background";
payload: Routing & { sessionId: string; tasks: LiveBackgroundTask[] };

sessionId is non-optional and tasks is a required array — matching the server (packages/server/src/ws-protocol.ts:738). Yet the consumer re-declares both as optional and casts over the good type anyway. That makes this the clearest instance of the pattern: the cast is not working around a drifted type, it is discarding a correct one, and in doing so it re-introduces the optionality the server does not have.

It is also the newest, which is the substantive point: the pattern is still being copied into new code. Whatever the fix is here, it should be the kind that makes the next frame hard to add this way — a shared payloadOf<T>(msg) helper, or narrowing on the mirrored union directly — rather than a one-time cleanup of five call sites.

The rest of the issue is unchanged

The four payload drifts still reproduce verbatim on main: types.ts:1286 (chat:queued_flushed, no attachments), :1296-1303 (chat:queued_state, no attachments), :1313 (chat:queued_returned, no attachments), :1332 (chat:killed_task typed as Routing &, giving it a phantom jobId).

And the folded-in #772 defect is still live: grep 'chat:injected\|ChatInjectedMessage' packages/server/src/ws-protocol.ts returns zero hits, so the frame is still emitted without being a member of the server ServerMessage union. #772 was closed as a duplicate of this issue, not as fixed — worth stating explicitly so a reader of #772's NOT_PLANNED status does not conclude otherwise.