sorokin.oleg.edu/learnharness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Wave B: the native message record — input events, projection, adapter death

Browse Source 
The chat record is now pi-native agent history (LhMessage[]), the AI SDK's
UIMessage transcript contract is gone from the server, and every client turn
arrives as ONE explicit input event.

Core (new):
- src/core/native-messages.ts — the LhMessage taxonomy (user/assistant/
  toolResult + lhMarker customs: verdict, probe-handoff, subagent-steer,
  subagent-abort, plan-block), constructors, and toLlmMessages — the single
  model-facing seam (convertToLlm): strips ids, flattens markers to user
  text, drops UI-only plan-blocks, synthesizes INTERRUPTED results for
  dangling aborted calls, never throws.
- src/core/projection.ts — projectNative: the one-way native → UIMessage
  projection (consecutive assistant+toolResult runs group into one
  assistant view message; toolResults attach backward by toolCallId;
  markers project to data parts; plan-blocks splice after the last
  successful plan_init). Every existing consumer reads through it.
- src/core/input-events.ts — the ChatInput union (text/answer/verdict/
  continue), parseChatInput validation, and inputAppends (answer targets
  the dangling question call or 400s; verdict = optional note user
  message + native verdict marker).

Server:
- chat-handler.ts — the turn root takes {chatId, input}; write-ahead
  persists input appends + claimed steers before the turn; claimSteers
  coalesces the whole queue with the handler's steerDelivered filter as
  the dedupe seam; teacher-vs-prober branch on hasProbeDone.
- turn-service.ts — persistTurn stamps ids, drops clean question
  placeholder toolResults (the record ends at the unanswered call),
  emits plan-block markers idempotently (plan-blocks.ts rewrite), and
  persists abort partials.
- ui-stream.ts — PiTurnSpec takes the native base; the wire dialect is
  unchanged. jobs.ts steers are native markers (steer_<jobId> dedup ids);
  waitForIdle reads danglingQuestionOf. teacher-agent.ts wires
  convertToLlm: toLlmMessages. record-adapter.ts DELETED wholesale.
- GET /api/chats/[id] serves messages: projectNative(record.messages).

Client:
- chat-transport.ts — the 409 retry is IDENTITY (re-POST the same event
  body after the turn settles — the event was never persisted
  pre-acceptance; the merge logic is gone). The transport consumes the
  stashed input event via prepareSendMessagesRequest and throws loudly on
  a missing stash.
- chat.tsx — every send call site stashes exactly one ChatInput event
  (text, answer, verdict, continue) before invoking the SDK send.

Tests: full native migration (chat-flow rewritten to input events and
native record pins; jobs/extraction/demos/graph/usage/plan-blocks/
probe-done/reattach-transport converted; record-adapter.test.ts deleted;
chat-transport tests pin the identity retry). 982/982, typecheck, lint,
build all green.
This commit is contained in:
amosblomqvist
2026-09-26 00:37:46 +03:00
parent b87a6925af
commit 7ab47d4fcb
36 changed files with 2410 additions and 1447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/chat-transport.ts
+59 -63
View File
@@ -1,28 +1,31 @@
/**
* Chat transport with 409 merge-retry — the learner's send can race the
* server's wake pipeline (contracts/jobs.ts "THE ASYNC PROTOCOL"): the wake
* turn starts server-side and the client only notices via the /api/jobs poll
* up to a second later. A send in that window gets 409'd ("a turn is already
* running") and, before this file, surfaced as an error banner.
* Chat transport for the INPUT-EVENTS contract (Wave B, owner ruling
* 2026-09-26): the client never re-POSTs its transcript — every send
* carries ONE explicit input event ({text} | {answer} | {verdict} |
* {continue}) stashed by the call site (chat.tsx) before invoking the SDK
* send. The server owns the record; this transport's ONLY send-time job is
* to consume the stash and put it on the wire as {chatId, input}.
*
* Why NOT a bare retry: every 409 means the server record is AHEAD of the
* client — the wake turn persisted the steer message (and, once it finishes,
* its response) that the client hasn't seen. The chat handler's write-ahead
* persist makes the request body the canonical transcript, so re-POSTing the
* stale client list would clobber the steer + wake messages out of the
* record (and the job already flipped done — steerDelivered makes
* re-delivery impossible: permanent loss). The retry must therefore MERGE:
* wait for the in-flight turn to finish, refetch the record, append the
* client's unsent messages (by id) to the server's list, and re-POST the
* merged transcript.
* 409 retry (the wake-pipeline race, contracts/jobs.ts "THE ASYNC
* PROTOCOL"): a send can race the server's wake turn (the client only
* notices it via the /api/jobs poll up to a second later) and gets
* 409'd. Under input events the retry is IDENTITY: the event was never
* persisted (the write-ahead only happens once the turn is accepted), so
* waiting for the in-flight turn and re-POSTing the SAME body is safe —
* no merge, no stale-list clobber. The old UIMessage-era merge logic is
* deleted with the UIMessage record (the server now owns the
* record; a lost race means "try again later", not "merge transcripts").
*
* Client-side gap after a merged retry: useChat's local list still lacks the
* steer/wake messages until the next syncFromServer (job settle, remount, or
* a future "server-ahead" heal in the poller). Rare path; self-heals.
* The send path is LOUD about a missing stash: every SDK send must map to
* exactly one event — a send with nothing stashed is a call-site bug
* (it would otherwise silently re-send the previous event), so the
* transport throws instead of guessing.
*/
import { DefaultChatTransport } from "ai";
import type { UIMessageChunk } from "ai";
import type { ChatTransport } from "ai";
import type { ChatInput } from "@/src/core";
import type { TeacherUIMessage } from "@/src/core";
/** How often to poll turnInFlight while the racing turn runs. */
@@ -56,21 +59,10 @@ async function turnInFlight(chatId: string): Promise<boolean | null> {
}
}
async function serverMessages(chatId: string): Promise<TeacherUIMessage[] | null> {
try {
const res = await fetch(`/api/chats/${encodeURIComponent(chatId)}`);
if (!res.ok) return null;
const record = (await res.json()) as { messages?: TeacherUIMessage[] };
return Array.isArray(record.messages) ? record.messages : null;
} catch {
return null;
}
}
/**
* A fetch that turns a 409 on POST /api/chat into: wait for the running turn,
* merge the outgoing messages onto the fresh server record, re-POST. Non-409
* responses pass through untouched.
* A fetch that turns a 409 on POST /api/chat into: wait for the running
* turn, re-POST the SAME event body. Non-409 responses pass through
* untouched.
*/
/** Exported for tests. */
export function retryingFetch(chatId: string, opts: RetryFetchOptions = {}): typeof globalThis.fetch {
@@ -90,36 +82,15 @@ export function retryingFetch(chatId: string, opts: RetryFetchOptions = {}): typ
if (init?.signal?.aborted) return response;
if ((await turnInFlight(chatId)) !== false) continue;
// Turn finished: merge onto the fresh record, then re-POST.
const record = await serverMessages(chatId);
if (!record || typeof init?.body !== "string") return response;
const serverIds = new Set(record.map((m) => m.id));
const body = JSON.parse(init.body) as { messages?: TeacherUIMessage[] };
if (!Array.isArray(body.messages)) return response;
const outgoing = body.messages.filter((m) => m.id && !serverIds.has(m.id));
const merged = JSON.stringify({ ...body, messages: [...record, ...outgoing] });
response = await fetch(input, { ...init, body: merged }); // may 409 again → loop
// Turn finished: re-POST the same input event — nothing merged,
// nothing lost (the event was never persisted pre-acceptance).
response = await fetch(input, init); // may 409 again → loop
}
return response;
};
}
/**
* The plain transport (no reattach adapters): sends keep the 409
* merge-retry. chat.tsx uses createReattachingTransport below — a
* superset of this — but the plain form stays exported for surfaces
* that only ever send (never resume onto a running turn).
*/
export function createChatTransport(chatId: string): DefaultChatTransport<TeacherUIMessage> {
return new DefaultChatTransport<TeacherUIMessage>({
api: "/api/chat",
body: { chatId },
fetch: retryingFetch(chatId),
});
}
/* ────────────────────────────────────────────────────────────────────────
* THE REATTACH TRANSPORT (background-turn runner wave, owner ruling
* 2026-09-25): a turn runs server-side decoupled from every view, and a
@@ -166,6 +137,14 @@ export interface ReattachOptions {
lastMessageId?: () => string | undefined;
}
/** The input-events half (Wave B): consume the call site's stashed event.
* Exactly one event per SDK send — the ref is cleared on read, so a
* send with nothing stashed fails LOUDLY rather than re-sending the
* previous event. */
export interface InputEventOptions {
takeInput: () => ChatInput | undefined;
}
/** Concatenate byte payloads (the head stream's event + read-past remainder). */
function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
const out = new Uint8Array(a.length + b.length);
@@ -179,7 +158,7 @@ function freshMessageId(): string {
return `msg_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
}
/** One parsed SSE event off the wire (data: <json>\\n\\n framing). */
/** One parsed SSE event off the wire (data: <json>\n\n framing). */
interface SseEvent {
/** The raw bytes of this event, re-injectable into the head stream. */
raw: Uint8Array;
@@ -193,7 +172,7 @@ interface SseEvent {
/**
* Read the FIRST complete SSE event off a live body (the settled terminal
* and the start chunk are both single small events; a long-lived turn's
* log replays after). Resolves as soon as one \\n\\n boundary is seen — the
* log replays after). Resolves as soon as one \n\n boundary is seen — the
* caller re-injects the raw bytes (plus any read-past remainder) ahead of
* the unconsumed tail, so nothing is lost or reordered.
*/
@@ -217,16 +196,17 @@ async function readFirstEvent(reader: ReadableStreamDefaultReader<Uint8Array>):
}
}
/** The reattach transport: DefaultChatTransport for sends, our seam for resumes. */
/** The reattach transport: the input-event POST for sends, our seam for resumes. */
class ReattachingChatTransport extends DefaultChatTransport<TeacherUIMessage> {
constructor(
private readonly reattach: ReattachOptions,
private readonly inputEvent: InputEventOptions,
init: ConstructorParameters<typeof DefaultChatTransport<TeacherUIMessage>>[0],
) {
super(init);
}
override async reconnectToStream(
override async reconnectToStream(
options: Parameters<ChatTransport<TeacherUIMessage>["reconnectToStream"]>[0],
): Promise<ReadableStream<UIMessageChunk> | null> {
const res = await fetch(`/api/chats/${encodeURIComponent(options.chatId)}/stream`, {
@@ -300,15 +280,31 @@ class ReattachingChatTransport extends DefaultChatTransport<TeacherUIMessage> {
/**
* The chat.tsx wiring: `transport: createReattachingTransport(chatId, refs)`.
* Sends keep the 409 merge-retry fetch; resumes take the adapters above.
* Sends POST the stashed input event with the 409 identity-retry fetch;
* resumes take the adapters above.
*/
export function createReattachingTransport(
chatId: string,
reattach: ReattachOptions,
inputEvent: InputEventOptions,
): DefaultChatTransport<TeacherUIMessage> {
return new ReattachingChatTransport(reattach, {
return new ReattachingChatTransport(reattach, inputEvent, {
api: "/api/chat",
body: { chatId },
fetch: retryingFetch(chatId),
// THE INPUT-EVENTS CONTRACT (Wave B): replace the SDK's full-transcript
// body with {chatId, input}. The stash is consumed HERE — exactly once
// per SDK send (the 409 retry re-POSTs the built body, not the stash);
// a send with nothing stashed fails LOUDLY (a call-site bug — it must
// never silently re-send the previous event).
prepareSendMessagesRequest: () => {
const input = inputEvent.takeInput();
if (!input) {
throw new Error(
"Send without a stashed input event — every send call site must set pendingInput before invoking the SDK send (Wave B input-events contract).",
);
}
return { body: { chatId, input } };
},
});
}
}
components/chat.tsx
+40 -8
View File
@@ -26,7 +26,7 @@ import { DictationBar, useDictation } from "@/components/dictation";
import { JobsContext } from "@/components/jobs-context";
import { StatsBar } from "@/components/stats-bar";
import { useActivity } from "@/components/activity-dock";
import { isProviderKeyRefusal, mergeAdopted, type ChatSettings, type ModelSlotName } from "@/src/core";
import { isProviderKeyRefusal, mergeAdopted, type ChatInput, type ChatSettings, type ModelSlotName } from "@/src/core";
import { PlanBlock, PlanPopup, latestTree } from "@/components/plan-block";
import { PlanMarginalia } from "@/components/plan-window";
import { MermaidOverlay, SessionMermaidContext } from "@/components/session-overlay";
@@ -181,15 +181,35 @@ export function Chat({
// the per-render transport recreation can never capture a stale one.
const reattachSettledRef = useRef<() => void>(() => {});
const reattachLastIdRef = useRef<string | undefined>(undefined);
// THE INPUT STASH (Wave B input-events contract, owner ruling
// 2026-09-26): every SDK send maps to EXACTLY ONE explicit input event —
// the call site stashes the event here before invoking the SDK send, and
// the transport consumes it when building the POST body ({chatId, input};
// the client transcript never rides the wire). Consumed-on-read: a send
// with nothing stashed fails LOUDLY in the transport (a call-site bug —
// it must never silently re-send the previous event).
const pendingInputRef = useRef<ChatInput | null>(null);
const stashInput = (input: ChatInput) => {
pendingInputRef.current = input;
};
const takeInput = () => {
const input = pendingInputRef.current;
pendingInputRef.current = null;
return input ?? undefined;
};
const { messages, sendMessage, addToolOutput, setMessages, status, error, stop, clearError, resumeStream } =
useChat<TeacherUIMessage>({
id: chatId,
messages: initialMessages,
transport: createReattachingTransport(chatId, {
onSettled: () => reattachSettledRef.current(),
lastMessageId: () => reattachLastIdRef.current,
}),
transport: createReattachingTransport(
chatId,
{
onSettled: () => reattachSettledRef.current(),
lastMessageId: () => reattachLastIdRef.current,
},
{ takeInput },
),
// After the learner answers (addToolOutput), automatically send the
// continuation request so the teacher reacts to the answer.
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
@@ -200,6 +220,7 @@ export function Chat({
useEffect(() => {
if (!sentInitial.current && initialPrompt && initialMessages.length === 0) {
sentInitial.current = true;
stashInput({ type: "text", text: initialPrompt });
void sendMessage({ text: initialPrompt });
}
}, [initialPrompt, initialMessages.length, sendMessage]);
@@ -343,6 +364,7 @@ export function Chat({
messages.length > 0 &&
lastAssistantMessageIsCompleteWithToolCalls({ messages })
) {
stashInput({ type: "continue" });
void sendMessage();
}
// mount-only by design (turnInFlight read at initial value)
@@ -492,6 +514,7 @@ export function Chat({
status === "ready" &&
lastAssistantMessageIsCompleteWithToolCalls({ messages: record.messages })
) {
stashInput({ type: "continue" });
void sendMessage();
}
}, [chatId, setMessages, sendMessage, status]);
@@ -612,8 +635,8 @@ export function Chat({
// TWO REAL MESSAGES, ONE TURN (the custom-message scheme, user-decided
// 2026-09-12): a typed note is the learner's own user message, and the
// verdict is its own custom message — marker part ONLY, no human-
// authored text (the model-facing wording lives in the adapter:
// record-adapter flattens it; nothing fake is persisted as speech).
// authored text (the model-facing wording lives in toLlmMessages,
// the native convertToLlm seam; nothing fake is persisted as speech).
// setMessages + sendMessage() (no args) fires ONE request carrying
// both — the same single-turn mechanism syncFromServer already uses,
// so no 409 dance and no double teacher turn.
@@ -639,6 +662,10 @@ export function Chat({
],
});
setMessages([...messages, ...appended]);
// The event (Wave B): the server appends the note (its own user
// message) + the verdict marker natively — the optimistic ids above
// are local render only; the settle sync lands the canon.
stashInput({ type: "verdict", accepted, note: note || undefined });
void sendMessage();
},
[text, messages, setMessages, sendMessage],
@@ -964,6 +991,7 @@ export function Chat({
if (!t || busy || pending) return;
draftRef.current = t; // the refusal flow's preserve-and-replay seam
setText("");
stashInput({ type: "text", text: t });
void sendMessage({ text: t });
};
@@ -972,7 +1000,10 @@ export function Chat({
value={{
chatId,
syncFromServer,
sendText: (t: string) => void sendMessage({ text: t }),
sendText: (t: string) => {
stashInput({ type: "text", text: t });
void sendMessage({ text: t });
},
openSetup: () => setSetupOpen(true),
}}
>
@@ -1318,6 +1349,7 @@ export function Chat({
if (t) {
setText("");
draftRef.current = t;
stashInput({ type: "text", text: t });
void sendMessage({ text: t });
}
}}