diff --git a/src/cache-ledger.ts b/src/cache-ledger.ts index abd5888910..3ad3b84114 100644 --- a/src/cache-ledger.ts +++ b/src/cache-ledger.ts @@ -138,7 +138,7 @@ interface LedgerLine { * of host churn). Sparse: omitted unless booked. The seam arm sets `seam` * above instead. Lets the web trajectory chart paint the same bucket * membership the economics card aggregates. */ - prov?: "ttl" | "side" | "rewind" | "client" | "orphan-sweep"; + prov?: "ttl" | "side" | "rewind" | "client" | "orphan-sweep" | "tools"; /** #1535: 1 iff `model` differs from the previous sample's KNOWN model * (unknown sides never flag); marks the re-billed stable prefix on the * first request after a model switch. Sparse: omitted unless set. */ @@ -312,6 +312,11 @@ interface CacheLedger { * the break — kept out of the unexplained seam tally. */ orphanSweepSeams: number; orphanSweepMissed: number; + /** #5466: mid-history breaks attributed to a mid-session change in the + * request's tools array (wire prefix = system + tools + messages) — kept + * out of the unexplained seam tally like the other host/provider buckets. */ + toolSeams: number; + toolSeamMissed: number; /** #2929: the provider-side arm split by idle gap — samples settled more * than PROVIDER_TTL_GAP_MS after the previous sample are normal TTL * expiry, not an abnormal provider failure. */ @@ -410,6 +415,12 @@ export interface SeamEvent { * rebuild artifact. Carries the divergent message's role/length/class * (never raw content). */ client?: { idx: number; role: string; len: number; cls: string }; + /** #5466: present iff booked as a TOOLS-array change — the request's tool table + * flipped between two turns ahead of the message prefix (the message-only view + * cannot see it), so the cached span broke at the tool boundary. Carries which + * entries appeared/disappeared/were redefined and how many reordered (names + * only, never schemas). */ + tools?: ToolsDelta; } const SEAM_BODY_CAP = 512 * 1024; @@ -463,6 +474,14 @@ export interface SeamSlot { * next loop round's continuity verdict reads them as entry-side ownership. * Preserved across byte-identical re-notes like keyFp. */ ownedSeparatorCores?: ReadonlySet; + /** #5466: per-entry fingerprints of the outbound body's `tools` array (order- + * sensitive), captured from the full parse at the send chokepoint. The wire + * prefix is system + tools + messages, so a mid-session tool-table change + * breaks the cached span without touching any message — detectSeam compares + * prev/cur to attribute that break to the tool table instead of the client. + * undefined = no tools array / unparseable body (unknown never flags); [] = + * present-but-empty. Preserved across byte-identical re-notes like effFp. */ + tools?: ToolEntry[]; } // #3023: message-count ceiling for the inbound pair. The per-message @@ -751,6 +770,97 @@ export function generationParamFp(body: Record | null | undefin return "sha256:" + createHash("sha256").update(canonicalJson(parts), "utf8").digest("hex").slice(0, 16); } +/** #5466: one entry of the outbound `tools` array, reduced to what the seam + * monitor needs — a display name (never the raw schema) and an order-sensitive + * fingerprint of the whole entry. */ +interface ToolEntry { + name: string; + fp: string; +} + +/** #5466: per-entry fingerprints of the outbound body's `tools` array, in order. + * The Anthropic wire prefix is system + tools + messages, so a mid-session change + * to the tool table invalidates the cached span WITHOUT touching any message — the + * message-only seam view cannot see it. Each entry is fingerprinted via + * canonicalJson (wire-agnostic: whole-entry, key-order-insensitive, so identical + * tools never flip while a real schema/description/rename flip is caught); the + * ORDER is preserved because a moved tool breaks the prefix exactly like an edited + * one. Returns undefined when the body has no `tools` array (unknown never flags); + * a present-but-empty array returns [] (distinct from undefined, so a real 0→N + * late registration is still caught by the length diff). */ +export function toolsArrayFps(body: Record | null | undefined): ToolEntry[] | undefined { + if (!body || typeof body !== "object") return undefined; + const t = body.tools; + if (!Array.isArray(t)) return undefined; + return t.map((entry) => { + const e = (entry ?? {}) as Record; + const fn = e.function; + const nested = fn !== null && typeof fn === "object" ? (fn as Record).name : undefined; + const rawName = typeof e.name === "string" ? e.name : typeof nested === "string" ? nested : undefined; + const name = rawName ?? "?"; + const fp = "sha256:" + createHash("sha256").update(canonicalJson(entry), "utf8").digest("hex").slice(0, 16); + return { name, fp }; + }); +} + +/** #5466: how two consecutive requests' tool tables differ, for the report. Names + * only (never schemas); `null` = identical (nothing to say). */ +interface ToolsDelta { + /** First divergent tool index (a positional mismatch, or the shorter array's + * length when the difference is purely a trailing add/remove). */ + idx: number; + /** Tool names present in the later request but not the earlier. */ + appeared: string[]; + /** Tool names present in the earlier request but not the later. */ + disappeared: string[]; + /** Same name in both, but its entry fingerprint differs (schema/description + * rewrite under an unchanged name). */ + edited: string[]; + /** Entries present in both (stable set) whose order shifted. Counted only when + * nothing appeared/disappeared/was redefined, so it reads as "reordered". */ + moved: number; + /** One-line human summary for the log/report. */ + summary: string; +} + +function describeToolsChange(prev: ToolEntry[], cur: ToolEntry[]): ToolsDelta | null { + const n = Math.min(prev.length, cur.length); + let identical = prev.length === cur.length; + if (identical) { + for (let i = 0; i < n; i++) { + if (prev[i].fp !== cur[i].fp) { identical = false; break; } + } + } + if (identical) return null; + let idx = n; + for (let i = 0; i < n; i++) { + if (prev[i].fp !== cur[i].fp) { idx = i; break; } + } + const prevByName = new Map(); + for (const e of prev) prevByName.set(e.name, e.fp); + const curByName = new Map(); + for (const e of cur) curByName.set(e.name, e.fp); + const appeared: string[] = []; + const disappeared: string[] = []; + const edited: string[] = []; + for (const [name, fp] of curByName) { + if (!prevByName.has(name)) appeared.push(name); + else if (prevByName.get(name) !== fp) edited.push(name); + } + for (const [name] of prevByName) if (!curByName.has(name)) disappeared.push(name); + let moved = 0; + if (appeared.length === 0 && disappeared.length === 0 && edited.length === 0) { + for (let i = 0; i < n; i++) if (prev[i].name !== cur[i].name) moved++; + } + const bits: string[] = []; + if (appeared.length) bits.push(`added ${appeared.join(", ")}`); + if (disappeared.length) bits.push(`removed ${disappeared.join(", ")}`); + if (edited.length) bits.push(`redefined ${edited.join(", ")}`); + if (moved > 0) bits.push(`${moved} reordered`); + const summary = bits.length > 0 ? bits.join("; ") : "tool table changed"; + return { idx, appeared, disappeared, edited, moved, summary }; +} + /** Record the body of the upstream round that is about to be sent. Called at * the single send chokepoints (loop fetchUpstream, non-streaming forward); * the next settleUsageReport pairs it with the usage report it produced. @@ -759,8 +869,9 @@ export function generationParamFp(body: Record | null | undefin * settle re-noting the same wireBody), the earlier count is kept. `keyFp` is * the outbound credential fingerprint (#2131) — likewise inherited from the * prior slot on a byte-identical re-note without a fresh capture. `effFp` is - * the generation-parameter fingerprint (#3803) — same inheritance rule. */ -export function noteForwardedBody(session: Session, body: string, msgs?: number | null, keyFp?: string, effFp?: string): void { + * the generation-parameter fingerprint (#3803) — same inheritance rule. + * `toolsFps` is the per-entry tools-array fingerprint (#5466) — same rule. */ +export function noteForwardedBody(session: Session, body: string, msgs?: number | null, keyFp?: string, effFp?: string, toolsFps?: ToolEntry[]): void { // #2868: encode to UTF-8 ONCE here — digest, capped head and retained full // body all consume this same buffer, so no later comparison re-encodes. // Caps are BYTES (the old code-unit caps overshot them up to 3× on CJK). @@ -796,6 +907,7 @@ export function noteForwardedBody(session: Session, body: string, msgs?: number keyFp: keyFp ?? (samePayload ? prior.keyFp : undefined), effFp: effFp ?? (samePayload ? prior.effFp : undefined), ownedSeparatorCores: samePayload ? prior.ownedSeparatorCores : undefined, + tools: toolsFps ?? (samePayload ? prior.tools : undefined), }; if ("round" in transient && transient.round > 1) { delete transient.imageFacts; @@ -1118,6 +1230,31 @@ function detectSeam(session: Session, led: CacheLedger): void { // means CLIPPED (bytes > cap) — an exactly-at-cap body is fully stored. const prevCapped = prev.bytes > SEAM_BODY_CAP; const curCapped = cur.bytes > SEAM_BODY_CAP; + // #5466: the tools table sits BEFORE messages in the Anthropic wire prefix + // (system + tools + messages), so a mid-session change to the request's + // tools array invalidates the cached span without touching any message — the + // message-only arms below cannot see it and would blame the first incidental + // divergence (client / seam-suspect / provider-side). Runs FIRST: a tools + // change is the earliest break in the prefix. Fail soft when either side + // lacks a captured tools array (no tools on the wire / unparseable body → + // undefined → legacy arms), mirroring the client arm's missing-capture rule. + const tPrev = prev.tools; + const tCur = cur.tools; + if (tPrev !== undefined && tCur !== undefined) { + const td = describeToolsChange(tPrev, tCur); + if (td !== null) { + line.prov = "tools"; + agg.toolSeams += 1; + agg.toolSeamMissed += line.tr; + if (led.seamEvents !== undefined && led.seamEvents.length >= SEAM_EVENTS_CAP) led.seamEvents.shift(); + const forensics = f ?? seamLcp(prev.head, cur.head); + (led.seamEvents ?? (led.seamEvents = [])).push({ seq: line.seq, at: line.at, input: line.input, hitPct: line.hitPct ?? 0, ...forensics, prevMsgs: prev.msgs ?? forensics.prevMsgs, curMsgs: cur.msgs ?? forensics.curMsgs, tools: td }); + if (agg.toolSeams === 1) { + loggerLog("warn", `[${session.id}] [cache-seam] tools-array change: hit ${line.hitPct}% (input=${line.input}, unexplained=${Math.round(line.tr)} tok) — the request's tools table changed (${td.summary}) ahead of the message prefix, so the cached span broke at the tool boundary, not from client history churn (#5466)`); + } + return; + } + } // Client reverted/trimmed history: the miss is the sanctioned // one-time re-bill of the retained prefix (or the gap's TTL). Only // trust the parsed counts when BOTH sides are fully stored — a side @@ -1256,6 +1393,7 @@ export function getCacheLedger(session: Session): CacheLedger { "nbSamples", "nbInput", "seamSuspects", "seamMissed", "providerSideMisses", "providerSideMissed", "providerTtlMisses", "providerTtlMissed", "rewinds", "rewindMissed", "abortCorrelated", "clientInserts", "clientInsertMissed", "orphanSweepSeams", "orphanSweepMissed", + "toolSeams", "toolSeamMissed", ] as const) { if (typeof g[key] !== "number") g[key] = 0; } @@ -1272,7 +1410,7 @@ export function getCacheLedger(session: Session): CacheLedger { foldSeqCounter: 0, folds: [], lines: [], - agg: { requests: 0, input: 0, cached: 0, output: 0, nc: 0, cr: 0, tr: 0, switches: 0, switchMissed: 0, effSwitches: 0, effSwitchMissed: 0, keySwitches: 0, keySwitchMissed: 0, promptSwitches: 0, promptSwitchMissed: 0, projSwitches: 0, projSwitchMissed: 0, wireSwitches: 0, wireSwitchMissed: 0, upstreamSwitches: 0, upstreamSwitchMissed: 0, restartDrops: 0, restartDropMissed: 0, attributedMissed: 0, unknownSamples: 0, unknownInput: 0, nbSamples: 0, nbInput: 0, seamSuspects: 0, seamMissed: 0, providerSideMisses: 0, providerSideMissed: 0, providerTtlMisses: 0, providerTtlMissed: 0, rewinds: 0, rewindMissed: 0, abortCorrelated: 0, clientInserts: 0, clientInsertMissed: 0, orphanSweepSeams: 0, orphanSweepMissed: 0 }, + agg: { requests: 0, input: 0, cached: 0, output: 0, nc: 0, cr: 0, tr: 0, switches: 0, switchMissed: 0, effSwitches: 0, effSwitchMissed: 0, keySwitches: 0, keySwitchMissed: 0, promptSwitches: 0, promptSwitchMissed: 0, projSwitches: 0, projSwitchMissed: 0, wireSwitches: 0, wireSwitchMissed: 0, upstreamSwitches: 0, upstreamSwitchMissed: 0, restartDrops: 0, restartDropMissed: 0, attributedMissed: 0, unknownSamples: 0, unknownInput: 0, nbSamples: 0, nbInput: 0, seamSuspects: 0, seamMissed: 0, providerSideMisses: 0, providerSideMissed: 0, providerTtlMisses: 0, providerTtlMissed: 0, rewinds: 0, rewindMissed: 0, abortCorrelated: 0, clientInserts: 0, clientInsertMissed: 0, orphanSweepSeams: 0, orphanSweepMissed: 0, toolSeams: 0, toolSeamMissed: 0 }, }; meta[LEDGER_KEY] = led; return led; @@ -2224,7 +2362,7 @@ interface BiliCacheReport extends CacheReport { recovery?: RecoveryReport; stability: BodyStability; /** #2131: line set widened with the per-call body-stability fields. */ - lines: Array; + lines: Array; modelSwitches: ModelSwitchStats; /** #3803: host generation-parameter switches (reasoning effort / thinking config) — a provider cache-namespace flip that re-bills the whole stable prefix once, distinct from any byte change. */ effSwitches: ModelSwitchStats; @@ -2248,7 +2386,7 @@ interface BiliCacheReport extends CacheReport { * is booked as new content, never as a prefix re-pay. */ initialBills: { samples: number; inputTokens: number }; invalidation: InvalidationTokenBreakdown; - seam: { suspects: number; missed: number; events: SeamEvent[]; providerSide: { count: number; missed: number }; providerTtl: { count: number; missed: number }; rewinds: { count: number; missed: number }; abortCorrelated: number; client: { count: number; missed: number }; orphanSweep: { count: number; missed: number } }; + seam: { suspects: number; missed: number; events: SeamEvent[]; providerSide: { count: number; missed: number }; providerTtl: { count: number; missed: number }; rewinds: { count: number; missed: number }; abortCorrelated: number; client: { count: number; missed: number }; orphanSweep: { count: number; missed: number }; tools: { count: number; missed: number } }; } export function buildSessionCacheReport(session: Session): BiliCacheReport { @@ -2541,7 +2679,7 @@ export function buildSessionCacheReport(session: Session): BiliCacheReport { invalidation, stability, recovery, - seam: { suspects: a.seamSuspects, missed: a.seamMissed, events: led.seamEvents ?? [], providerSide: { count: a.providerSideMisses, missed: a.providerSideMissed }, providerTtl: { count: a.providerTtlMisses, missed: a.providerTtlMissed }, rewinds: { count: a.rewinds, missed: a.rewindMissed }, abortCorrelated: a.abortCorrelated, client: { count: a.clientInserts, missed: a.clientInsertMissed }, orphanSweep: { count: a.orphanSweepSeams, missed: a.orphanSweepMissed } }, + seam: { suspects: a.seamSuspects, missed: a.seamMissed, events: led.seamEvents ?? [], providerSide: { count: a.providerSideMisses, missed: a.providerSideMissed }, providerTtl: { count: a.providerTtlMisses, missed: a.providerTtlMissed }, rewinds: { count: a.rewinds, missed: a.rewindMissed }, abortCorrelated: a.abortCorrelated, client: { count: a.clientInserts, missed: a.clientInsertMissed }, orphanSweep: { count: a.orphanSweepSeams, missed: a.orphanSweepMissed }, tools: { count: a.toolSeams, missed: a.toolSeamMissed } }, }; } @@ -2693,12 +2831,12 @@ function formatSeam(r: BiliCacheReport): string { if (r.seam.suspects > 0) { out.push("⚠ CACHE SEAM (suspected mid-history prefix breaks)"); out.push(` ${r.seam.suspects} sample(s) · ${fmtTok(r.seam.missed)} tok re-billed with no fold/switch/restart attribution`); - // #3307: seamEvents holds BOTH suspect and #3023 client-side events - // (one shared capped ring), so listing every event here echoed host-owned - // rewrites under the "suspected bili rebuild" header — the ✎ CLIENT - // section below already owns those. List only suspects here so the two - // sections stay disjoint and a client insert is never misread as a seam. - const suspectEvents = r.seam.events.filter((e) => !e.client); + // #3307: seamEvents holds suspect, #3023 client-side AND #5466 tools-array + // events (one shared capped ring), so listing every event here echoed + // host-owned breaks under the "suspected bili rebuild" header — the ✎ CLIENT + // and 🔧 TOOLS sections below already own those. List only true suspects so + // the sections stay disjoint and a host-side break is never misread as a seam. + const suspectEvents = r.seam.events.filter((e) => !e.client && !e.tools); for (const e of suspectEvents) { out.push(` #${e.seq} ${fmtTime(e.at)} hit ${e.hitPct.toFixed(1)}% · input ${fmtTok(e.input)} · divergence ≥${fmtTok(e.lcpBytes)}B at message[${e.msgIndex ?? "?"}] of ${e.prevMsgs}→${e.curMsgs}`); } @@ -2727,6 +2865,13 @@ function formatSeam(r: BiliCacheReport): string { if (e.client) out.push(` #${e.seq} ${fmtTime(e.at)} hit ${e.hitPct.toFixed(1)}% · input ${fmtTok(e.input)} · inbound message[${e.client.idx}] ${e.client.role}/${e.client.cls} ${e.client.len}B JSON · outbound ${fmtTok(e.lcpBytes)}B @ message[${e.msgIndex ?? "?"}] of ${e.prevMsgs}→${e.curMsgs}`); } } + if (r.seam.tools.count > 0) { + out.push("🔧 TOOLS-ARRAY CHANGE (host flipped the request's tool table — NOT a bili seam)"); + out.push(` ${r.seam.tools.count} sample(s) · ${fmtTok(r.seam.tools.missed)} tok re-billed when the request's tools array changed mid-session — the wire prefix is system + tools + messages, so the cached span broke at the tool boundary without any message changing. Host-owned re-bill (late plugin registration / dynamic tool enable), not a rebuild seam.`); + for (const e of r.seam.events) { + if (e.tools) out.push(` #${e.seq} ${fmtTime(e.at)} hit ${e.hitPct.toFixed(1)}% · input ${fmtTok(e.input)} · ${e.tools.summary} · outbound ${fmtTok(e.lcpBytes)}B @ message[${e.msgIndex ?? "?"}] of ${e.prevMsgs}→${e.curMsgs}`); + } + } if (r.seam.orphanSweep.count > 0) { out.push("🧹 ORPHAN CLEANUP SEAM (proactive failed-compress rotation — #3769)"); out.push(` ${r.seam.orphanSweep.count} sample(s) · ${fmtTok(r.seam.orphanSweep.missed)} tok re-billed when failed-compress records were rotated out of history without a fold claiming the break — bili's own cleanup, not an upstream or host rewrite`); diff --git a/src/loop/core.ts b/src/loop/core.ts index 269bb7a600..20454877b1 100644 --- a/src/loop/core.ts +++ b/src/loop/core.ts @@ -9,7 +9,7 @@ import { estimateCoreMessages } from "../preflight.js"; import { estimateWireOverhead } from "../server/budget.js"; import { handleAcpStatus } from "../acp-status.js"; import { STATUS_REPORT_CLOSE, STATUS_REPORT_OPEN } from "../acp-panel.js"; -import { credentialFingerprint, generationParamFp, handleAcpCache, lastForwardedBody, noteForwardedBody, noteForwardedImageFacts, settleUsageReport } from "../cache-ledger.js"; +import { credentialFingerprint, generationParamFp, handleAcpCache, lastForwardedBody, noteForwardedBody, noteForwardedImageFacts, settleUsageReport, toolsArrayFps } from "../cache-ledger.js"; import { billOutputUsage } from "../billing.js"; import { maybeJudgeContinuity } from "../invariant-judge.js"; import type { SeparatorSlot } from "../server/responses-ordering.js"; @@ -650,7 +650,7 @@ export async function* runCompressLoop( // noteForwardedBody is a string-only forensics sink; an opaque egress // envelope (Buffer) is lossy-converted — advisory pairing only, and the // provenance judge below already skips when the body was rewritten. - noteForwardedBody(ctx.session, typeof wireBodyStr === "string" ? wireBodyStr : wireBodyStr.toString("utf8"), wireArr !== undefined ? wireArr.length : null, credentialFingerprint(requestOptions.headers), generationParamFp(wireObj)); + noteForwardedBody(ctx.session, typeof wireBodyStr === "string" ? wireBodyStr : wireBodyStr.toString("utf8"), wireArr !== undefined ? wireArr.length : null, credentialFingerprint(requestOptions.headers), generationParamFp(wireObj), toolsArrayFps(wireObj)); // #564/#2627: provenance is resolved against the array that belongs to // `wireBodyStr`. Shedding rewrites the body wholesale, so the pre-shed // `wireArr` no longer describes it; rather than map stale indexes (which diff --git a/src/server/relay.ts b/src/server/relay.ts index 7ce093b91b..9a24052e3e 100644 --- a/src/server/relay.ts +++ b/src/server/relay.ts @@ -13,7 +13,7 @@ import { type BiliMessage } from "acp-kernel/wire"; import { absorbToolName, applyAbsorbView } from "../absorb.js"; import { APIG_RESIGN_SCHEME, resignApig } from "../apig-resign.js"; import { noteSuccessfulForward } from "../cache-keepalive.js"; -import { credentialFingerprint, generationParamFp, lastForwardedBody, noteClientAbort, noteForwardedBody, noteForwardedImageFacts, noteInboundMessages, noteOutboundContextEstimates, settleOverflowCalibration, settleUsageReport, withCacheCapture } from "../cache-ledger.js"; +import { credentialFingerprint, generationParamFp, lastForwardedBody, noteClientAbort, noteForwardedBody, noteForwardedImageFacts, noteInboundMessages, noteOutboundContextEstimates, settleOverflowCalibration, settleUsageReport, toolsArrayFps, withCacheCapture } from "../cache-ledger.js"; import { warnCacheCollapse } from "../cache-warn.js"; import { stampOutbound } from "../chain-checkpoint.js"; import { rewrapCommandcodeBody } from "../commandcode-wire.js"; @@ -1191,7 +1191,7 @@ const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepare // #3803: the generation-parameter fingerprint rides the SAME full parse as the message count — // it is extracted from sentParsed (the complete object), never from the capped body head, so a // trailing-field flip is seen even when the body exceeds SEAM_BODY_CAP. - noteForwardedBody(prepared.session, sentBody, Array.isArray(sentArr) ? (sentArr as unknown[]).length : null, credentialFingerprint(headers), generationParamFp(sentParsed)); + noteForwardedBody(prepared.session, sentBody, Array.isArray(sentArr) ? (sentArr as unknown[]).length : null, credentialFingerprint(headers), generationParamFp(sentParsed), toolsArrayFps(sentParsed)); // #3023: the client's own resent view — the protocol conversion of the // inbound bytes BEFORE processTurn folded/replaced anything, captured // with the exact same pairing semantics so detectSeam can attribute a diff --git a/src/web/client.ts b/src/web/client.ts index 5ca025d133..cef4402685 100644 --- a/src/web/client.ts +++ b/src/web/client.ts @@ -2539,11 +2539,12 @@ function changelogCatOf(rawLine) { providerTtl: { count: (raw.providerTtl && Number(raw.providerTtl.count)) || 0, missed: (raw.providerTtl && Number(raw.providerTtl.missed)) || 0 }, rewinds: { count: (raw.rewinds && Number(raw.rewinds.count)) || 0, missed: (raw.rewinds && Number(raw.rewinds.missed)) || 0 }, client: { count: (raw.client && Number(raw.client.count)) || 0, missed: (raw.client && Number(raw.client.missed)) || 0 }, + tools: { count: (raw.tools && Number(raw.tools.count)) || 0, missed: (raw.tools && Number(raw.tools.missed)) || 0 }, abortCorrelated: Number(raw.abortCorrelated) || 0, }; } function detailSeamActive(seam) { - return !!(seam && (seam.suspects > 0 || seam.missed > 0 || seam.events.length > 0 || seam.providerSide.count > 0 || seam.rewinds.count > 0 || seam.client.count > 0 || seam.abortCorrelated > 0)); + return !!(seam && (seam.suspects > 0 || seam.missed > 0 || seam.events.length > 0 || seam.providerSide.count > 0 || seam.rewinds.count > 0 || seam.client.count > 0 || seam.tools.count > 0 || seam.abortCorrelated > 0)); } // #2489/#3484: zoom-to-selection over the detail charts. The data is already // client-side, so zooming re-renders the SAME renderer over a filtered slice — no @@ -3492,6 +3493,7 @@ if (d.keepalive) kv(parts, t("det.keepalive"), d.keepalive.tierLabel + " · " + if (seam.providerSide.count > 0) sub.push(legendItem("background:#f0883e", t("det.leg_pside"))); if (seam.rewinds.count > 0) sub.push(legendItem("background:#57606a", t("det.leg_rewind"))); if (seam.client.count > 0) sub.push(legendItem("background:#0969da", t("det.leg_client"))); + if (seam.tools.count > 0) sub.push(legendItem("background:#0e7490", t("det.leg_tools"))); sub.push(legendItem("background:#9aa1a8", t("det.leg_rest"))); parts.push('' + legendItem("background:#8250df", t("det.cause_unattrib")) @@ -3655,15 +3657,16 @@ if (d.keepalive) kv(parts, t("det.keepalive"), d.keepalive.tierLabel + " · " + // tile (label · value · then the parts, top to bottom) — containment // rendered as layout, not as a caption floating beside the tiles. const plainUnattrib = () => '
' + t("det.ce_ttl") + '
' + fmtW(tot.ttlRepay || 0) + pctIn(tot.ttlRepay || 0) + "
"; - if (seam && (seam.missed > 0 || seam.providerTtl.count > 0 || seam.providerSide.count > 0 || seam.rewinds.count > 0 || seam.client.count > 0)) { + if (seam && (seam.missed > 0 || seam.providerTtl.count > 0 || seam.providerSide.count > 0 || seam.rewinds.count > 0 || seam.client.count > 0 || seam.tools.count > 0)) { var uChips = []; if (seam.missed > 0 || seam.suspects > 0) uChips.push('' + t("det.attr_seam") + " " + fmtW(seam.missed) + (seam.suspects > 0 ? " ×" + seam.suspects : "") + pctU(seam.missed) + ""); if (seam.providerTtl.missed > 0 || seam.providerTtl.count > 0) uChips.push('' + t("det.attr_ttl") + " " + fmtW(seam.providerTtl.missed) + (seam.providerTtl.count > 0 ? " ×" + seam.providerTtl.count : "") + pctU(seam.providerTtl.missed) + ""); if (seam.providerSide.missed > 0 || seam.providerSide.count > 0) uChips.push('' + t("det.attr_provider") + " " + fmtW(seam.providerSide.missed) + (seam.providerSide.count > 0 ? " ×" + seam.providerSide.count : "") + pctU(seam.providerSide.missed) + ""); if (seam.rewinds.missed > 0 || seam.rewinds.count > 0) uChips.push('' + t("det.attr_rewind") + " " + fmtW(seam.rewinds.missed) + (seam.rewinds.count > 0 ? " ×" + seam.rewinds.count : "") + pctU(seam.rewinds.missed) + ""); if (seam.client.missed > 0 || seam.client.count > 0) uChips.push('' + t("det.attr_client") + " " + fmtW(seam.client.missed) + (seam.client.count > 0 ? " ×" + seam.client.count : "") + pctU(seam.client.missed) + ""); + if (seam.tools.missed > 0 || seam.tools.count > 0) uChips.push('' + t("det.attr_tools") + " " + fmtW(seam.tools.missed) + (seam.tools.count > 0 ? " ×" + seam.tools.count : "") + pctU(seam.tools.missed) + ""); if (seam.abortCorrelated > 0) uChips.push('' + t("det.attr_abort") + " ×" + seam.abortCorrelated + ""); - var uRest = Math.max(0, (tot.ttlRepay || 0) - seam.missed - seam.providerTtl.missed - seam.providerSide.missed - seam.rewinds.missed - seam.client.missed); + var uRest = Math.max(0, (tot.ttlRepay || 0) - seam.missed - seam.providerTtl.missed - seam.providerSide.missed - seam.rewinds.missed - seam.client.missed - seam.tools.missed); if (uRest > 8192) uChips.push('' + t("det.attr_rest", { x: fmtW(uRest) }) + pctU(uRest) + ""); if (uChips.length) { parts.push('
' + t("det.ce_ttl") + '
' + fmtW(tot.ttlRepay || 0) + pctIn(tot.ttlRepay || 0) + '
' diff --git a/src/web/i18n.ts b/src/web/i18n.ts index 45d66a429b..18ac200c37 100644 --- a/src/web/i18n.ts +++ b/src/web/i18n.ts @@ -407,6 +407,7 @@ export const MESSAGES: Record> = { "det.leg_pside": "▲ 上游侧失效", "det.leg_rewind": "↩ 历史回退", "det.leg_client": "✎ 客户端中段改写", + "det.leg_tools": "🔧 工具表变更", "det.leg_rest": "其余", "det.fold_short": "折叠", "det.rec_title": "压缩回收(推荐 vs 实际折叠)", @@ -474,11 +475,13 @@ export const MESSAGES: Record> = { "det.attr_ttl_tip": "与上一请求间隔超过 10 分钟后,字节稳定/纯追加形态仍 miss——上游前缀缓存已正常过期,属预期损耗,无需处理", "det.attr_rewind": "↩ 历史回退", "det.attr_client": "✎ 客户端中段改写", + "det.attr_tools": "🔧 工具表变更", "det.attr_abort": "⏻ 中断相关", "det.attr_seam_tip": "出站请求体在历史中段出现字节分叉,且无 fold/模型切换/重启归因——疑似重建缝。数值为嫌疑样本重计费的 token。若此前几分钟内发生过折叠,多半是折叠后客户端回显的重付(#2929 后已归入折叠后重建)", "det.attr_provider_tip": "与上一请求间隔很短,且整条消息列表逐字节保留(整体一致,或前缀一致、仅尾部追加新消息;超过 512KiB 取证上限的请求以记录头稳定 + 精确消息数增长判定)却仍 miss——异常:上游淘汰/中继节点轮换,非 bili 重建缝;长间隔的同类样本归入「上游 TTL 过期」", "det.attr_rewind_tip": "客户端 revert/trim 使消息数下降——合法的一次性重计费(保留前缀),非缺陷", "det.attr_client_tip": "客户端自己重发的历史在中段分叉(插入/改写,如宿主其他插件注入、粘贴挂载、重渲染)——入站消息指纹对在该索引处失配,bili 的忠实重建把这个改动带到了线上。客户端自担的重计费,非 bili 重建缝(#3023)", + "det.attr_tools_tip": "请求的 tools 数组在中段变化(新增/移除/重定义/重排)——Anthropic 线上前缀是 system + tools + messages,工具表先于消息,故缓存缝断在工具边界而非消息。宿主自担的重计费(插件晚注册 / 动态开关工具),非 bili 重建缝(#5466)", "det.attr_abort_tip": "客户端流中 abort 后 30s 内结算的 miss 样本数——重试重写重发尾部;相关性而非因果,叠加标记不计入分桶", "det.attr_restart": "⟳ 重启丢窗", "det.attr_restart_tip": "bili 重启或会话恢复后,账本窗口断裂:重启后的首个请求无法与重启前样本配对,miss 按首账计费(初始内容)", @@ -1207,6 +1210,7 @@ export const MESSAGES: Record> = { "det.leg_pside": "▲ provider-side miss", "det.leg_rewind": "↩ rewind", "det.leg_client": "✎ client rewrite", + "det.leg_tools": "🔧 tools change", "det.leg_rest": "rest", "det.fold_short": "fold", "det.rec_title": "compression recovery (recommended vs folded)", @@ -1274,11 +1278,13 @@ export const MESSAGES: Record> = { "det.attr_ttl_tip": "byte-stable / append-shaped misses settled more than 10 minutes after the previous sample — the upstream prefix cache simply aged out; expected cost, no action needed", "det.attr_rewind": "↩ History rewound", "det.attr_client": "✎ Client mid-history rewrite", + "det.attr_tools": "🔧 Tools-array change", "det.attr_abort": "⏻ Abort-correlated", "det.attr_seam_tip": "Outbound bodies diverged mid-history with no fold/model-switch/restart attribution — suspected rebuild seam. Value = tokens re-billed on suspect samples. If a fold landed minutes earlier this is usually the post-fold client-echo re-bill (fold-owned since #2929)", "det.attr_provider_tip": "Arrived shortly after the previous request, whose entire message list came back byte-identical (whole body, or its prefix with only tail messages appended; above the 512 KiB forensics cap, proven by the stable recorded head plus exact message-count growth) yet the upstream did not serve its cache — abnormal: eviction / relay node rotation. Long-gap siblings are booked under upstream TTL expiry", "det.attr_rewind_tip": "Client revert/trim shrank the message count — sanctioned one-time re-bill of the retained prefix, not a defect", "det.attr_client_tip": "The client's own resent history diverged mid-list (insert/rewrite — another host plugin, paste hoisting, re-render): the inbound message-fingerprint pair mismatches at that index, and bili's faithful rebuild carried the change to the wire. Client-owned re-bill, not a bili rebuild seam (#3023)", + "det.attr_tools_tip": "The request's tools array changed mid-session (added / removed / redefined / reordered) — on the Anthropic wire the prefix is system + tools + messages, so the tool table precedes messages and the cached span breaks at the tool boundary, not a message. Host-owned re-bill (late plugin registration / dynamic tool toggle), not a bili rebuild seam (#5466)", "det.attr_abort_tip": "Missed samples settled within 30s of a client mid-stream abort — retry churn rewrites the resent tail; correlation, not causation (overlay marker, not a bucket)", "det.attr_restart": "⟳ restart drop", "det.attr_restart_tip": "After a bili restart or session restore the ledger window breaks: the first post-restart request cannot pair with pre-restart samples, so its miss is billed as a first bill (initial content)", diff --git a/tests/cache-seam-tools-change.test.ts b/tests/cache-seam-tools-change.test.ts new file mode 100644 index 0000000000..0ac073f40a --- /dev/null +++ b/tests/cache-seam-tools-change.test.ts @@ -0,0 +1,167 @@ +// #5466: tools-array-change attribution. The Anthropic wire prefix is +// system + tools + messages, so a mid-session change to the request's tools +// array invalidates the cached span WITHOUT touching any message. detectSeam +// was blind to it (message-only fingerprint) and blamed the first incidental +// divergence — the client (#3023) or an unexplained seam. toolsArrayFps +// captures per-entry tool fingerprints at the send chokepoint; when the prev/cur +// tool tables differ the residual books into the dedicated tools bucket +// (prov:"tools"), naming which entries appeared/disappeared/were redefined/ +// reordered. Stable tools, a missing capture on either side, and no-tools lanes +// keep the legacy arms untouched (fail soft, like the message ladder). +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { noteForwardedBody, noteInboundMessages, settleUsageReport, getCacheLedger, buildSessionCacheReport, handleAcpCache, toolsArrayFps } from "../src/cache-ledger.ts"; +import type { CoreMessage } from "acp-kernel"; +import type { Session } from "../src/session.ts"; + +let seq = 0; +function makeSession(): Session { + seq += 1; + return { + id: `tools-seam-${seq}`, + metadata: {}, + stats: {}, + state: { blocks: [], messageRefs: { byRaw: {}, byRef: {} }, tokenSnapshot: {} }, + } as unknown as Session; +} + +const T0 = Date.parse("2026-10-13T10:00:00Z"); +function settle(session: Session, at: number, input: number, cached: number): void { + settleUsageReport(session, { total: input, reportedCached: cached, output: 0, protocol: "openai", upstream: "http://u" }); +} +const inbound = (msgs: string[]): CoreMessage[] => msgs.map((c) => ({ role: "user", content: c })) as unknown as CoreMessage[]; + +type Tool = { name: string; description: string; input_schema: { type: string } }; +const A: Tool = { name: "read_file", description: "Read a file", input_schema: { type: "object" } }; +const B: Tool = { name: "write_file", description: "Write a file", input_schema: { type: "object" } }; +const C: Tool = { name: "bash", description: "Run a shell command", input_schema: { type: "object" } }; + +// Mirror the send chokepoint: note the FULL parsed body and derive the tools +// fingerprints from it exactly as src/server/relay.ts and src/loop/core.ts do. +function note(s: Session, msgs: string[], tools?: Tool[]): void { + const obj: Record = { model: "m", messages: msgs.map((c) => ({ role: "user", content: c })) }; + if (tools !== undefined) obj.tools = tools; + const str = JSON.stringify(obj); + noteForwardedBody(s, str, (obj.messages as unknown[]).length, undefined, undefined, toolsArrayFps(obj)); +} + +test("tools gained mid-session with stable messages books the tools bucket, not client/seam", () => { + const s = makeSession(); + note(s, ["a", "b", "c"], [A, B]); + settle(s, T0, 100_000, 99_000); + note(s, ["a", "b", "c"], [A, B, C]); + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + const line = led.lines[led.lines.length - 1]!; + assert.equal(line.prov, "tools"); + assert.equal(line.seam, undefined, "NOT a seam suspect"); + assert.equal(led.agg.toolSeams, 1); + assert.ok(led.agg.toolSeamMissed > 0); + assert.equal(led.agg.clientInserts, 0); + assert.equal(led.agg.seamSuspects, 0); + const ev = led.seamEvents?.[0]; + assert.ok(ev?.tools, "seam event carries tools forensics"); + assert.deepEqual(ev!.tools!.appeared, ["bash"]); + assert.equal(ev!.tools!.disappeared.length, 0); + assert.match(handleAcpCache(s).text, /TOOLS-ARRAY CHANGE/); + const report = buildSessionCacheReport(s); + assert.equal(report.seam.tools.count, 1); + assert.ok(report.seam.tools.missed > 0); +}); + +test("#5459 shape: tools gained AND a turn appended still attributes to tools, not provider-side/client", () => { + const s = makeSession(); + noteInboundMessages(s, inbound(["a", "b", "c"])); + note(s, ["a", "b", "c"], [A]); + settle(s, T0, 100_000, 99_000); + noteInboundMessages(s, inbound(["a", "b", "c", "d"])); + note(s, ["a", "b", "c", "d"], [A, B, C]); + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + const line = led.lines[led.lines.length - 1]!; + assert.equal(line.prov, "tools", "tools change precedes the appended turn in the prefix"); + assert.equal(led.agg.toolSeams, 1); + assert.equal(led.agg.clientInserts, 0); + assert.equal(led.agg.providerSideMisses, 0, "NOT booked provider-side"); + assert.deepEqual(led.seamEvents?.[0]?.tools?.appeared, ["write_file", "bash"]); +}); + +test("stable tools + genuine client mid-history rewrite stays prov=client (no regression)", () => { + const s = makeSession(); + noteInboundMessages(s, inbound(["a", "b", "c"])); + note(s, ["a", "b", "c"], [A, B]); + settle(s, T0, 100_000, 99_000); + noteInboundMessages(s, inbound(["a", "X", "b", "c"])); + note(s, ["a", "X", "b", "c"], [A, B]); + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + assert.equal(led.lines[led.lines.length - 1]!.prov, "client"); + assert.equal(led.agg.toolSeams, 0, "stable tools never flag"); + assert.equal(led.agg.clientInserts, 1); +}); + +test("stable tools + inbound-prefix-stable outbound break stays a seam suspect (no regression)", () => { + const s = makeSession(); + noteInboundMessages(s, inbound(["a", "b", "c"])); + note(s, ["a", "b", "c"], [A, B]); + settle(s, T0, 100_000, 99_000); + noteInboundMessages(s, inbound(["a", "b", "c", "d"])); + note(s, ["a", "B2", "c", "d"], [A, B]); + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + const line = led.lines[led.lines.length - 1]!; + assert.equal(line.seam, 1, "legacy seam bucket preserved"); + assert.equal(line.prov, undefined); + assert.equal(led.agg.toolSeams, 0); +}); + +test("no tools on either side keeps the legacy seam bucket (fail-soft)", () => { + const s = makeSession(); + note(s, ["a", "b", "c"]); + settle(s, T0, 100_000, 99_000); + note(s, ["a", "B2", "c"]); + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + assert.equal(led.agg.seamSuspects, 1); + assert.equal(led.agg.toolSeams, 0); +}); + +test("tools appearing where the earlier side had none fails soft to the legacy arms", () => { + const s = makeSession(); + note(s, ["a", "b", "c"]); // no tools array -> undefined capture + settle(s, T0, 100_000, 99_000); + note(s, ["a", "b", "c"], [A, B]); // tools present -> defined capture + settle(s, T0 + 1000, 100_000, 20_000); + const led = getCacheLedger(s); + assert.equal(led.agg.toolSeams, 0, "a missing-capture side declines to classify"); + assert.notEqual(led.lines[led.lines.length - 1]!.prov, "tools"); +}); + +test("delta classifies removed / redefined / reordered entries by name", () => { + const s1 = makeSession(); + note(s1, ["a"], [A, B]); + settle(s1, T0, 100_000, 99_000); + note(s1, ["a"], [A]); + settle(s1, T0 + 1000, 100_000, 20_000); + assert.deepEqual(getCacheLedger(s1).seamEvents?.[0]?.tools?.disappeared, ["write_file"]); + + const s2 = makeSession(); + note(s2, ["a"], [{ name: "x", description: "old", input_schema: { type: "object" } }]); + settle(s2, T0, 100_000, 99_000); + note(s2, ["a"], [{ name: "x", description: "new", input_schema: { type: "object" } }]); + settle(s2, T0 + 1000, 100_000, 20_000); + assert.deepEqual(getCacheLedger(s2).seamEvents?.[0]?.tools?.edited, ["x"]); + + const s3 = makeSession(); + note(s3, ["a"], [A, B]); + settle(s3, T0, 100_000, 99_000); + note(s3, ["a"], [B, A]); + settle(s3, T0 + 1000, 100_000, 20_000); + const d3 = getCacheLedger(s3).seamEvents?.[0]?.tools; + assert.ok(d3, "reorder produces a tools delta"); + assert.equal(d3.appeared.length, 0); + assert.equal(d3.disappeared.length, 0); + assert.equal(d3.edited.length, 0); + assert.equal(d3.moved, 2); + assert.match(d3.summary, /reordered/); +}); diff --git a/tests/golden/storage-render/anthropic.json b/tests/golden/storage-render/anthropic.json index 7c01ccf504..dbb9a1a312 100644 --- a/tests/golden/storage-render/anthropic.json +++ b/tests/golden/storage-render/anthropic.json @@ -95,13 +95,13 @@ "foldAt": 9, "editedAt": 12, "summaryFrom": 9, - "stateDigest": "ba0f75f6ddc882d00d5c456facd79166b62e3f2cacadd60744aa370d6b247105", + "stateDigest": "e468787d40bc943aedcd141e2dbf5d796e19ed0e3d013bae328389547aae8a93", "stateDigestAligned": "66991d5cb8864f3ca029914aa9afc20cc8b9687cfd4391ffe200017c68057946", "sectionDigests": { "state": "37b26b4f6898afff", "blockContents": "dc7d13d250c94bb4", "stats": "7caf981f99159be9", - "metadata": "ba51746c6749d0cf" + "metadata": "8892cff4bba24179" }, "stateKeyDigests": { "blocks": "3a454b9a16e4f0b9", diff --git a/tests/golden/storage-render/chat.json b/tests/golden/storage-render/chat.json index 5ecde5722b..3ce1118585 100644 --- a/tests/golden/storage-render/chat.json +++ b/tests/golden/storage-render/chat.json @@ -95,13 +95,13 @@ "foldAt": 9, "editedAt": 12, "summaryFrom": 9, - "stateDigest": "2c0b36206756617ae1e32cf0d221ddd8bf7f3e06994b49d11578bd1a35c90f26", + "stateDigest": "e91fb43346a4f47d052a8f348035f826edab556d9b722987cf82cd0148973584", "stateDigestAligned": "3011800706759958cfeab6520289f1ffe257cf4f7c3275d846c03a991f9ed6b8", "sectionDigests": { "state": "90857fbf82001a2b", "blockContents": "94a58f96d7c5cfc3", "stats": "7b6162aef3873d31", - "metadata": "7218c1e3430c3d21" + "metadata": "1c65db85f6a01255" }, "stateKeyDigests": { "blocks": "d9770feee91dafc6", diff --git a/tests/golden/storage-render/google.json b/tests/golden/storage-render/google.json index 26c5f73b94..f0e11c4088 100644 --- a/tests/golden/storage-render/google.json +++ b/tests/golden/storage-render/google.json @@ -95,13 +95,13 @@ "foldAt": 9, "editedAt": 12, "summaryFrom": 9, - "stateDigest": "c5eefef6525f180ab54a7ea57c4ddf004a568db0fc2d6d227ede31dc960706db", + "stateDigest": "9e2b7c9b356d65c3a51a40f7303dde61c7709bb877801ceba9b460ee8346be9f", "stateDigestAligned": "5217aa02331256a419837cd91105d3e3172f2ff38f0f3914c0e01128e221f012", "sectionDigests": { "state": "c5243ba17364d3ac", "blockContents": "473264d9df8ba338", "stats": "c90671e484dc5d37", - "metadata": "2980a8959aa0a39c" + "metadata": "3e019de20cdaae54" }, "stateKeyDigests": { "blocks": "0cfd0b9c0fc53073", diff --git a/tests/golden/storage-render/responses.json b/tests/golden/storage-render/responses.json index 8041cd5155..bcb4e3ea56 100644 --- a/tests/golden/storage-render/responses.json +++ b/tests/golden/storage-render/responses.json @@ -95,13 +95,13 @@ "foldAt": 9, "editedAt": 12, "summaryFrom": 9, - "stateDigest": "ff092bc66e11c35b15ad98acf6206629115825b62168da2e5542e06297f6d47a", + "stateDigest": "aabbb06d9699c7fe1128722e816d615e09bc070b6fbf8b31a373f97ebdf20cca", "stateDigestAligned": "db5f08a7d57c14952c31571e45b4dbc6c2ed35fe8a97c58cda6fa854d411eb25", "sectionDigests": { "state": "bee6e1ba0c6fba62", "blockContents": "b6701268a0bdcd8a", "stats": "1b56c993f03cd122", - "metadata": "77714417e484ba89" + "metadata": "7322d9965045401e" }, "stateKeyDigests": { "blocks": "34b0dc17f8c24595",