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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion reference/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ billion-context/
│ │ ├── context-window.ts # Context-window resolution (launcher model channel, beta headers)
│ │ ├── dsh-compaction-guard.ts # Rejects dsh whole-prefix compaction replays (#1729)
│ │ ├── handle.ts # Proxy request pipeline (route triage, compat relay, compress orchestration) (#1440 P2 cut 3)
│ │ ├── handoff-response.ts # Retains parsed assistant output for handoff export without changing request snapshots
│ │ ├── handoff-response.ts # Retains parsed assistant output for handoff export without changing request snapshots; turn-final reply stashed in metadata.handoffReply for durable DB persistence (never lastMessages/messages table — the view is the ref-ledger's territory, #6947)
│ │ ├── headers.ts # Client-provided id sanitization for dump filenames (#286)
│ │ ├── inject.ts # Per-wire tool-injection wrappers + FORCE_TEXT_PROTOCOL switch (#1440)
│ │ ├── observability.ts # Body dumps (dumps/req-*.json, raw/*), unrecognized-path stats
Expand Down Expand Up @@ -304,6 +304,7 @@ billion-context/
│ ├── remote-notices.ts # Remote announcement feed watcher: fail-open polling, last-known-good snapshot (#5548)
│ ├── request-membership.ts # Settle-side membership probe: is this usage report ours (#4805)
│ ├── resolver-wedge.ts # Persistent local DNS resolver wedge detector + alarm (#5221)
│ ├── responses-system-sections.ts # Single source of truth for the Responses-wire developer-section join: steady prepare + round-2 rebuild share one separator (#6922)
│ ├── responses-tool-output.ts # Responses tool-output image parts: projection + patch helpers
│ ├── rollout.ts # Feature rollout: per-install uuid, basis-point buckets, nested cohorts (#3062)
│ ├── runaway-guard.ts # Intrinsic stream terminator for runaway tag/codepoint enumeration (#2346)
Expand Down
130 changes: 128 additions & 2 deletions src/server/handoff-response.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,82 @@
import type { CoreMessage } from "acp-kernel";
import { anthropicToCore, googleToCore, openaiToCore, responsesToCore } from "acp-kernel/wire";
import type { BiliMessage } from "acp-kernel/wire";
import { anthropicToCore, canonicalToolArgs, ClusterCounter, deriveCanonicalMessageId, googleToCore, openaiToCore, responsesToCore } from "acp-kernel/wire";
import { markDirty, type Session } from "../session.js";
import { log as loggerLog } from "../logger.js";
import { planStoredMessageRow, type HandoffReplyStashRow } from "../storage/ingest.js";

export const HANDOFF_REPLY_MAX_BYTES = 1_500_000;

export type HandoffReply = ReturnType<typeof createHandoffReply>;

export function createHandoffReply(session: Session, canSave: () => boolean = () => true) {
/**
* #6947: canonical base id (WITHOUT the ClusterCounter `_N` suffix) re-derived
* from a core message's OWN fields — the inverse of what each protocol codec
* feeds deriveCanonicalMessageId (#3642). Lets the write-back pre-seed a
* ClusterCounter from the cores already stored, so appended reply ids number
* exactly as the next full codec pass over [stored…, reply…] would (the
* re-send then joins by (msg_id, identity) onto the SAME rows instead of
* retiring + re-ingesting). Host-side on purpose: the kernel boundary (#2092)
* is human-gated and the kernel already exports both seed helpers.
*
* Returns null when the base cannot be derived from core fields alone: image
* parts (the #3751 payload fingerprint lives in sidecars the handoff capture
* never sets — unreachable here, null is the honest answer) and unknown
* content types. Callers skip nulls: an under-count can only shift a cluster
* SUFFIX for an identical repeated identity, never mint a wrong bare id.
*/
function baseIdOfCore(m: BiliMessage): string | null {
const text = m.text ?? "";
switch (m.contentType) {
case "text":
if (m.imagePart) return null;
return deriveCanonicalMessageId(m.originalRole ?? m.role, "text", text);
case "reasoning":
return deriveCanonicalMessageId("assistant", "reasoning", text);
case "tool-call":
return deriveCanonicalMessageId("assistant", "tool-call", canonicalToolArgs(text), { toolName: m.toolName });
case "tool-result":
return deriveCanonicalMessageId("tool", "tool-result", text, { toolName: m.toolName });
default:
return null;
}
}

/**
* #6947 join polish: re-stamp the sidecars each protocol codec would add on
* the NEXT re-send, so the write-back row's stored bytes join the re-send
* row's by identity (identityOfStoredContent strips only id/wireIndex —
* every other field counts). Without this, the re-send ingest lands a
* second row for the same logical message (tombstone churn + the content
* CAS storing the reply bytes twice) on long sessions:
* - openai reasoning cores carry `reasoningContent` (the codec stamps the
* reasoning text a second time — kernel/src/wire/openai.ts);
* - openai clients (pi) re-serialize tool-call args with parse +
* JSON.stringify (compact, key order preserved) and the anthropic codec
* stores safeStringify(input) — both reduce to the same normalization
* of the verbatim streamed args.
* Lanes whose codecs attach payload sidecars the text capture cannot
* reproduce (google rawGoogleParts / responses rawResponsesItem /
* anthropic thinkingSignature) keep the write-back row byte-distinct —
* accepted residual, same class as client round-trip drift.
*/
function restampForJoin(protocol: string | undefined, m: CoreMessage): CoreMessage {
const b = m as BiliMessage;
const text = b.text ?? "";
if (b.contentType === "reasoning" && protocol === "openai") {
const stamped: BiliMessage = { ...b, reasoningContent: text };
return stamped as CoreMessage;
}
if (b.contentType === "tool-call" && (protocol === "openai" || protocol === "anthropic")) {
try {
const parsed: unknown = JSON.parse(text);
if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return { ...m, text: JSON.stringify(parsed) };
} catch { /* non-JSON args: keep the verbatim bytes */ }
}
return m;
}

export function createHandoffReply(session: Session, canSave: () => boolean = () => true, protocol?: string) {
const request = session.stats.requests;
const snapshot = session.lastMessages;
const messages = new Map<string, { message: CoreMessage; bytes: number; textBytes: number; lastCodeUnit: number }>();
Expand Down Expand Up @@ -48,6 +117,62 @@ export function createHandoffReply(session: Session, canSave: () => boolean = ()
discard,
save() {
if (discarded || !messages.size || session.stats.requests !== request || session.lastMessages !== snapshot || !canSave()) return;
// #6947 turn-final write-back (direction C — persistence is
// separated from the session identity ledger): the reply rows
// historically only persisted when a LATER request re-sent them
// (snapshotMessages replaces lastMessages from the request
// array), so an idle session's last turn never reached the store
// — the web UI kept showing the previous (stale) reply forever.
// We must NOT append the reply to the snapshot: lastMessages is
// the single source of truth for the resident window (digest
// parity, web view, fork refs), and the reply's REF is minted by
// the kernel only when a request presents it — pushing it here
// created a window where fork/snapshot saw a message with no
// ref and 409'd (review regression, #6953).
// Instead the captured reply is stashed as plan-ready rows in
// metadata.handoffReply (persisted → both views digest-equal).
// Ids are derived EXACTLY as the next codec pass will derive
// them: the SAME canonical seed the codecs feed
// deriveCanonicalMessageId (#3642 — role|contentType with the
// toolCallId slot pinned empty, toolName, and canonicalToolArgs
// for tool calls; wire toolCallIds are transport plumbing, never
// content identity) and the same cluster numbering (Nth
// occurrence of the same base, counted in arrival order over the
// snapshot). The planners turn the stash into trailing
// NON-TAIL log rows (never tailSeqs), and the re-send — full or
// delta path — JOINs them in place by msg_id+identity (#4390)
// on EVERY content type, so the #3133 fast path stays green.
// Worst case (client round-trip drift): one refused delta + one
// redundant full re-ingest — never wrong rows.
// Skipped when the snapshot is a bounded folded re-render: its
// array is a pruned view, not the raw tail the store appends to.
if (session.lastMessagesFolded !== true && Array.isArray(snapshot)) {
const clusters = new ClusterCounter();
for (const m of snapshot) {
const b = baseIdOfCore(m);
if (b !== null) clusters.next(b);
}
const rows: HandoffReplyStashRow[] = [];
for (const entry of messages.values()) {
const m = restampForJoin(protocol, entry.message);
const b = baseIdOfCore(m);
// b is null only for image-part cores (the #3751 payload
// fingerprint lives in sidecars the capture never sets —
// it has no imagePart). Skip the row in that unreachable
// case: without a content-derived id the row could never
// join the re-send and would only ever be a duplicate —
// the reply then persists on re-send, as pre-#6947.
if (b === null) continue;
rows.push(planStoredMessageRow({ ...m, id: clusters.next(b) }));
}
// Each turn's save() overwrites the stash; after the re-send
// presents the reply as a view row the planner gates it out
// by msgId — no explicit consumption needed. The row bytes
// duplicate metadata.handoffResponse for one turn (both
// bounded by the HANDOFF_REPLY_MAX_BYTES cap) — accepted to
// close the idle-persistence gap without touching the view.
if (rows.length > 0) session.metadata["handoffReply"] = { request, rows };
}
session.metadata.handoffResponse = { request, messages: [...messages.values()].map((entry) => entry.message) };
markDirty(session);
},
Expand Down Expand Up @@ -76,3 +201,4 @@ export function captureHandoffJson(reply: HandoffReply | undefined, protocol: st
reply.discard();
}
}

2 changes: 1 addition & 1 deletion src/server/relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,7 @@ async function forwardCaptured(
// client socket still open?" — a client that hangs up on the terminal frame
// (pi's shape) must not lose the finished reply. Partial turns (no terminal)
// are still never captured.
const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepared.session) : undefined;
const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepared.session, () => true, prepared.protocol) : undefined;
// E2: a codex native-compaction request intercepted in prepare() carries a
// forged success response — serve it without contacting upstream.
if (prepared?.codexForge) {
Expand Down
43 changes: 43 additions & 0 deletions src/storage/ingest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,49 @@ function stringifyForStore(m: CoreMessage): string {
}
}

/** A persisted turn-final reply row. Stored under the session's
* `metadata.handoffReply` (see src/server/handoff-response.ts) — OUTSIDE the
* messages table on purpose: the table's seq space is the ref-ledger
* substrate (persist.maybeRestampToLedger aligns live refs onto row seq+1,
* #4316), so non-view rows would desync every post-fold ref. metadata_json
* is persisted in both the legacy file and the unified DB (identical in
* both views ⇒ digest-equal), so the reply still lands durably in the DB —
* #6947 — without touching the view, the ledger, or any wire. */
export interface HandoffReplyStashRow {
msgId: string;
content: string;
hash: string;
identity: string;
role: string;
kind: string;
media?: { hash: string; bytes: string }[];
ts?: number;
}

/** Plan-ready representation of a core the store has never seen through a
* request — the turn-final handoff reply. Runs the EXACT serialization
* chain the planners use (serializeForStore → splitMediaContent →
* identityOfStoredContent), so the row's identity equals the one a client
* re-send of the same reply would derive — DB readers can dedup the stash
* against view rows by (msgId, identity) if they ever join. Exported so the
* host capture (handoff-response.ts) and this module cannot drift apart. */
export function planStoredMessageRow(m: CoreMessage): HandoffReplyStashRow {
const raw = serializeForStore(m);
ingestSerializations.count++;
const parsed = JSON.parse(raw) as { role?: unknown; contentType?: unknown };
const split = splitMediaContent(raw);
return {
msgId: m.id,
content: split.content,
hash: split.hash,
identity: identityOfStoredContent(split.content),
role: typeof parsed.role === "string" ? parsed.role : "assistant",
kind: typeof parsed.contentType === "string" ? parsed.contentType : "message",
...(split.media.length > 0 ? { media: split.media } : {}),
...(typeof m.ts === "number" ? { ts: m.ts } : {}),
};
}

/** Builds rows + pointer sequences. Pure: no database touched, so tests can
* assert the mapping itself. seq assignment: first-seen over the ordered
* union (pluginSnapshot first — frozen raw prefix — then fresh tail ids). */
Expand Down
23 changes: 21 additions & 2 deletions src/storage/store.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1579,10 +1579,11 @@ export class UnifiedStore {
// stable absolute seqs: same identity (msgId + content hash)
// keeps its old seq; new identities continue after max(seq).
const existing = this.db
.prepare("SELECT seq, msg_id, identity, content_hash, retired_at FROM messages WHERE session_id = ?")
.all(s.sessionId) as { seq: number; msg_id: string; identity: string; content_hash: string; retired_at: number | null }[];
.prepare("SELECT seq, msg_id, identity, content_hash, retired_at, ref FROM messages WHERE session_id = ?")
.all(s.sessionId) as { seq: number; msg_id: string; identity: string; content_hash: string; retired_at: number | null; ref: string | null }[];
const seqByIdentity = new Map<string, number>();
const hashBySeq = new Map<number, string>();
const storedRefBySeq = new Map<number, string | null>();
const retiredSeqs: number[] = [];
let nextSeq = 0;
for (const row of existing) {
Expand All @@ -1594,6 +1595,7 @@ export class UnifiedStore {
if (row.retired_at !== null) retiredSeqs.push(row.seq);
seqByIdentity.set(`${row.msg_id}\u0000${row.identity}`, row.seq);
hashBySeq.set(row.seq, row.content_hash);
storedRefBySeq.set(row.seq, row.ref);
if (row.seq + 1 > nextSeq) nextSeq = row.seq + 1;
}
// #3133 watermark gate (full path): the watermark names the abs seq
Expand All @@ -1604,6 +1606,12 @@ export class UnifiedStore {
// save runs the full ingest.
const planToAbs = new Map<number, number>();
const repairs: { seq: number; msgId: string; from: string; to: string; content: string }[] = [];
// #6947: rows written by the turn-final handoff write-back carry
// ref=NULL — their ref is minted only when a LATER request re-sends
// the message. This join hit is the first moment the minted ref can
// reach the stored row; backfill NULL only (a non-null stored ref is
// the frozen index-time projection and must never be rewritten).
const refBackfills: { seq: number; ref: string; refNum: number }[] = [];
const messages = input.messages.map((m) => {
// #3133: plan rows carry the intern-pass hash; only direct
// callers without a planner pay the sha256 here.
Expand All @@ -1625,10 +1633,21 @@ export class UnifiedStore {
const fresh = m.contentHash ?? sha256Hex(m.content);
const stored = hashBySeq.get(abs);
if (stored !== undefined && stored !== fresh) repairs.push({ seq: abs, msgId: m.msgId, from: stored, to: fresh, content: m.content });
// #6947: minted-ref backfill for turn-final write-back rows.
// Never "BLOCKED" (a byRaw-only token, #ingest note) and never
// over an already-stored ref.
if (m.ref !== null && m.ref !== "BLOCKED" && m.refNum !== null && storedRefBySeq.get(abs) === null) {
refBackfills.push({ seq: abs, ref: m.ref, refNum: m.refNum });
}
}
planToAbs.set(m.seq, abs);
return { ...m, seq: abs };
});
for (const b of refBackfills) {
// The ref IS NULL re-check inside the statement keeps the update
// idempotent if two plan rows join the same stored row.
this.db.prepare("UPDATE messages SET ref = ?, ref_num = ? WHERE session_id = ? AND seq = ? AND ref IS NULL").run(b.ref, b.refNum, s.sessionId, b.seq);
}
for (const r of repairs) {
// #4793: a sibling row may already hold the target bytes for this
// msg_id — e.g. an old generation stamped with an EMPTY identity
Expand Down
6 changes: 3 additions & 3 deletions tests/golden/storage-render/anthropic.json
Original file line number Diff line number Diff line change
Expand Up @@ -95,13 +95,13 @@
"foldAt": 9,
"editedAt": 12,
"summaryFrom": 9,
"stateDigest": "1f528f4fee4f59026d3b005f99a0489cadc139e54698896b2e5a0dadbc95ee2b",
"stateDigestAligned": "a796f61ccd006f5fa1573e1ef33bf756dc24bf017154fab8bde4c0b369516537",
"stateDigest": "97c49de03bb6c42c99a9d0f03ce7cef247b4cb034ee1da24d5954207225bb341",
"stateDigestAligned": "2f913ebef14626bd7923a11fffc9676e2919664f2a5e1649b456bf03ec09cb29",
"sectionDigests": {
"state": "56e66f6b72c7f0dd",
"blockContents": "dc7d13d250c94bb4",
"stats": "e83198a55e6b2c29",
"metadata": "65894bb8839e9947"
"metadata": "5d34f4fe94270d09"
},
"stateKeyDigests": {
"blocks": "3a454b9a16e4f0b9",
Expand Down
6 changes: 3 additions & 3 deletions tests/golden/storage-render/chat.json
Original file line number Diff line number Diff line change
Expand Up @@ -95,13 +95,13 @@
"foldAt": 9,
"editedAt": 12,
"summaryFrom": 9,
"stateDigest": "a7b5a67f54a2cbd7978e2a57ad78f522f7af8f94a4e2402898aee4d93479541a",
"stateDigestAligned": "76f701f5ab1631fe1615a3f1cd8fa0fcd0a3fa19c02658cc5d077ae565f4897a",
"stateDigest": "accd7fe100acd1e3adf3b6186b4c709085f4e229ea2d8d553f903cf30f97b42c",
"stateDigestAligned": "4d6b17bddffef0fbaf73bd585a8a702c34a866c105719da5fa16bc90da1be38b",
"sectionDigests": {
"state": "90857fbf82001a2b",
"blockContents": "94a58f96d7c5cfc3",
"stats": "5c2f0fe203d710e8",
"metadata": "0c7d1819e0d4c0f6"
"metadata": "5e869987612d599b"
},
"stateKeyDigests": {
"blocks": "d9770feee91dafc6",
Expand Down
6 changes: 3 additions & 3 deletions tests/golden/storage-render/google.json
Original file line number Diff line number Diff line change
Expand Up @@ -95,13 +95,13 @@
"foldAt": 9,
"editedAt": 12,
"summaryFrom": 9,
"stateDigest": "f8d07462fd8881896c5b52864e84ff9a1a79b0cdb73cd2ef87e16d361b5a07d3",
"stateDigestAligned": "219c42a0f17ed7c9061174627ca56e5b6733e7413d8af98953105bf5d60a40b7",
"stateDigest": "a9769a0169874c9b501b27a73cf721dcb57097969e974f050a3fa68a741b17fd",
"stateDigestAligned": "3db9797c6435542e793cfd27d4d5d9a76d49474289601d07c90d65fa9d567112",
"sectionDigests": {
"state": "c5243ba17364d3ac",
"blockContents": "473264d9df8ba338",
"stats": "a3c84817f1d0c3dd",
"metadata": "615f125909ed135d"
"metadata": "631282b79ac9672c"
},
"stateKeyDigests": {
"blocks": "0cfd0b9c0fc53073",
Expand Down
Loading
Loading