@basein/runner 0.3.25 → 0.3.27

package/dist/control/transcript.d.ts

@@ -34,6 +34,15 @@
  * birth time, mtime, and the bytes at its head and at the offset) and read
  * again from the start, which is exactly what the old code did every time.
  */
+import { type RateFlags } from "../replay/pricing.js";
+/**
+ * The session's own transcript for a path a hook handed over: a sub-agent's
+ * file (`<session>/subagents/…/agent-….jsonl`) names its session's, and any
+ * other path is itself. A session is measured from its own transcript, which
+ * adds its sub-agents' files up ({@link subagentUsage}): were a sub-agent's
+ * file taken for it, a turn's marks would be read from two different files.
+ */
+export declare function sessionTranscriptPath(path: string): string;
 /** The day the agent was told it is, and the words that told it (issue 1212). */
 export interface AgentDay {
     /** "Today's date is Thursday, 2023-11-30 and the current time is 00:00:00." */
@@ -151,17 +160,62 @@ export declare function settledLastAssistantText(transcriptPath: string | undefi
     confirmMs?: number;
     pollMs?: number;
 }): Promise<string>;
+/** How many prompts the transcript holds so far: user lines of the main conversation that carry text. */
+export declare function promptCount(transcriptPath: string | undefined): number;
+/**
+ * The assistant's last text of the turn that ended before prompt number
+ * `prompt` (the first prompt is 1): "" when that turn wrote none, and
+ * undefined while that prompt has not been written — or is long past.
+ *
+ * WHY. A turn's answer is read a moment after its `Stop`, once its last
+ * message is in the file. A prompt queued behind the turn can open the next
+ * turn inside that moment, and "the last assistant text" is then the next
+ * turn's: a recording was finished with the answer to another prompt. The
+ * answer of a turn is what stood when the next prompt was written.
+ */
+export declare function answerBeforePrompt(transcriptPath: string | undefined, prompt: number): string | undefined;
 /**
- * Per-model token usage, as it appears on one assistant message.
+ * Wait for the turn's last message to be in the transcript: until the
+ * conversation's newest line is an assistant message that calls no tool, or
+ * `timeoutMs` has passed. True when it is there.
+ *
+ * WHY. `Stop` fires before Claude Code has written the turn's last message (see
+ * {@link settledLastAssistantText}), and that message carries its own `usage`.
+ * A turn's cost read at `Stop` is therefore one model call short — and the
+ * call it lacks is counted in no turn at all, because the next turn's mark is
+ * taken after the line has landed. On a recording that is one call in many. On
+ * a replay it is most of the turn: the model's one call there is the one that
+ * reads the plan's results and answers. The console showed such turns as 93%
+ * and 97% saved where Claude Code's own bill said 42% (the service's
+ * improvelst.md, item 1).
+ *
+ * Returns at once when the message is already there, when the file cannot be
+ * read (there is no cost to wait for), and when its lines do not say how a
+ * message stopped and the newest one calls no tool (an older host, a fixture).
  */
-export interface ModelUsage {
+export declare function settledTurnEnd(transcriptPath: string | undefined, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<boolean>;
+/**
+ * Token usage of one model, summed over the requests that are priced alike:
+ * the flags of {@link RateFlags} say which (a long prompt, fast mode, US-only
+ * inference), and are absent for the ordinary ones.
+ */
+export interface ModelUsage extends RateFlags {
     model: string;
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens: number;
+    /** Every cache write, the 1-hour ones among them. */
     cacheCreationTokens: number;
+    /** Of those, the tokens written to the 1-hour cache. Absent for none. */
+    cacheCreation1hTokens?: number;
 }
-/** Cumulative per-model totals, captured when a run starts. */
+/**
+ * Cumulative totals, captured when a run starts: one entry per model and way
+ * of pricing, under the model's name with its rate key after it.
+ */
 export type UsageMark = Map<string, ModelUsage>;
 /**
  * Snapshot cumulative usage at the moment a run starts.
@@ -180,6 +234,13 @@ export declare function markTranscriptUsage(transcriptPath: string | undefined):
  * rotated transcript degrades to "no usage" rather than to a negative cost.
  */
 export declare function usageSince(transcriptPath: string | undefined, mark: UsageMark | undefined): ModelUsage[];
+/**
+ * The usage between two marks of one transcript, `from` the earlier: what
+ * {@link usageSince} gives, with `to` in the place of the transcript as it is
+ * now. A turn whose books are closed after the next turn has started ends at
+ * that turn's mark, not at whatever the file holds by then.
+ */
+export declare function usageBetween(mark: UsageMark | undefined, now: UsageMark): ModelUsage[];
 /** The first user prompt in the transcript — the run's `input` when a hook omits it. */
 export declare function firstUserPrompt(transcriptPath: string | undefined): string;
 //# sourceMappingURL=transcript.d.ts.map

package/dist/control/transcript.js

@@ -34,9 +34,11 @@
  * birth time, mtime, and the bytes at its head and at the offset) and read
  * again from the start, which is exactly what the old code did every time.
  */
-import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { redactText } from "../record/redact.js";
 import { truncateString } from "../record/truncate.js";
+import { rateKey, requestRates } from "../replay/pricing.js";
 function blocksOf(line) {
     const content = line.message?.content ?? line.content;
     if (Array.isArray(content))
@@ -116,8 +118,24 @@ function keepWithin(into, held, piece) {
     into.push(kept);
     return held + kept.length;
 }
+/** Turn answers kept per transcript: a turn's books close within seconds of its end. */
+const MAX_ANSWERS_KEPT = 8;
 const indexes = new Map();
-function freshIndex(st) {
+/**
+ * The files of a transcript's sub-agents, read for their tokens only
+ * ({@link subagentUsage}): transcript path → the main index they were read
+ * beside, one usage-only index per file, and `gone`: what the files whose
+ * index was let go of had used (one past {@link MAX_SUBAGENT_FILES}, one read
+ * again from its start after a rewrite). Dropped with the main index.
+ */
+const subagentIndexes = new Map();
+/** Sub-agent files read per transcript, at most. */
+const MAX_SUBAGENT_FILES = 256;
+/** How deep under `subagents/` their files are looked for (`workflows/wf_…/agent-….jsonl`). */
+const SUBAGENT_DEPTH = 3;
+/** What a line must hold to be worth parsing for its tokens. */
+const USAGE_KEY = Buffer.from('"usage"');
+function freshIndex(st, usageOnly) {
     return {
         ino: st.ino,
         birthtimeMs: st.birthtimeMs,
@@ -127,8 +145,11 @@ function freshIndex(st) {
         anchor: Buffer.alloc(0),
         skipping: false,
         lineNo: 0,
+        usageOnly: usageOnly !== undefined,
         usage: new Map(),
-        usageSeen: new Set(),
+        // A sub-agent's file shares its transcript's set: a message that a host
+        // writes into both files is counted once, whichever is read first.
+        usageSeen: usageOnly?.seen ?? new Set(),
         lastAssistantText: "",
         firstUserPrompt: "",
         sawPrompt: false,
@@ -137,6 +158,10 @@ function freshIndex(st) {
         toolUses: new Map(),
         systemDayLine: "",
         hostDay: "",
+        tail: "",
+        prompts: 0,
+        textSincePrompt: false,
+        answersBefore: new Map(),
     };
 }
 /** Whether `idx` can be continued for a file that now looks like `st`. */
@@ -168,41 +193,65 @@ function readAt(fd, position, length) {
  * an empty transcript, as the whole-file reader always did.
  */
 function indexFor(path) {
+    return indexIn(indexes, path, MAX_INDEXES, undefined, (dropped) => subagentIndexes.delete(dropped));
+}
+/**
+ * {@link indexFor} over a store of its own: `usageOnly` for the files of a
+ * transcript's sub-agents, which are read for their tokens and nothing else.
+ * `onDrop` hears of every path the store lets go of.
+ *
+ * A sub-agent's file that cannot be looked at for a moment keeps its index:
+ * its tokens were used. Let go of, an index was made again later beside the
+ * transcript's set of counted messages, which held every one of the file's —
+ * and the file counted $0 from then on. Every index such a store does let go
+ * of, or replaces, goes to `usageOnly.retire` with what it had counted.
+ */
+function indexIn(store, path, cap, usageOnly, onDrop) {
     let st;
     try {
         st = statSync(path);
     }
     catch {
-        indexes.delete(path);
+        if (usageOnly)
+            return store.get(path);
+        store.delete(path);
+        onDrop?.(path);
         return undefined;
     }
     if (!st.isFile())
-        return undefined;
-    let idx = indexes.get(path);
+        return usageOnly ? store.get(path) : undefined;
+    let idx = store.get(path);
     // Re-inserted on every use, so the Map's order is least-recently-used first.
     if (idx)
-        indexes.delete(path);
-    if (!idx || !continues(idx, st))
-        idx = freshIndex(st);
-    indexes.set(path, idx);
-    while (indexes.size > MAX_INDEXES) {
-        const oldest = indexes.keys().next().value;
+        store.delete(path);
+    if (!idx || !continues(idx, st)) {
+        if (idx)
+            usageOnly?.retire?.(idx);
+        idx = freshIndex(st, usageOnly);
+    }
+    store.set(path, idx);
+    while (store.size > cap) {
+        const oldest = store.keys().next().value;
         if (oldest === undefined)
             break;
-        indexes.delete(oldest);
+        const old = store.get(oldest);
+        store.delete(oldest);
+        if (old)
+            usageOnly?.retire?.(old);
+        onDrop?.(oldest);
     }
     if (st.size === idx.offset)
         return idx;
     try {
-        return catchUp(path, idx, st);
+        return catchUp(store, path, idx, st, usageOnly);
     }
     catch {
         // Unreadable mid-way (locked, deleted): what was folded in so far stands.
-        return indexes.get(path);
+        return store.get(path);
     }
 }
 /** Fold in what was appended; the index to use from now on (a fresh one after a rewrite). */
-function catchUp(path, stale, st) {
+function catchUp(store, path, stale, st, usageOnly) {
     const fd = openSync(path, "r");
     try {
         let idx = stale;
@@ -213,8 +262,9 @@ function catchUp(path, stale, st) {
             const anchorAt = idx.offset - idx.anchor.length;
             const anchor = readAt(fd, anchorAt, idx.anchor.length);
             if (!head.equals(idx.head) || !anchor.equals(idx.anchor)) {
-                idx = freshIndex(st);
-                indexes.set(path, idx);
+                usageOnly?.retire?.(idx);
+                idx = freshIndex(st, usageOnly);
+                store.set(path, idx);
             }
         }
         fold(idx, fd, st.size);
@@ -287,6 +337,104 @@ function fold(idx, fd, size) {
         }
     }
 }
+/**
+ * The files of `transcriptPath`'s sub-agents: every `agent-*.jsonl` under
+ * `<the transcript without .jsonl>/subagents/`, sub-folders included
+ * (a workflow's agents are in `workflows/wf_…/`). Links are not followed.
+ */
+function subagentFiles(transcriptPath) {
+    if (!transcriptPath.endsWith(".jsonl"))
+        return [];
+    const out = [];
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // no such folder: the session started no sub-agent
+        }
+        for (const entry of entries) {
+            if (out.length >= MAX_SUBAGENT_FILES)
+                return;
+            if (entry.isFile() && entry.name.startsWith("agent-") && entry.name.endsWith(".jsonl")) {
+                out.push(join(dir, entry.name));
+            }
+            else if (entry.isDirectory() && depth < SUBAGENT_DEPTH) {
+                walk(join(dir, entry.name), depth + 1);
+            }
+        }
+    };
+    walk(join(transcriptPath.slice(0, -".jsonl".length), "subagents"), 0);
+    return out;
+}
+/**
+ * The token usage in the files of a transcript's sub-agents, one total per
+ * file, each caught up with what was appended since the last call.
+ *
+ * WHY. Claude Code writes a sub-agent's conversation into a file of its own,
+ * and its tokens are on the session's bill. The transcript alone held 30,000
+ * tokens of a report whose two Explore agents used 400,000: the run was
+ * recorded at a tenth of its cost, and every saving against it measured far
+ * too small (the service's imp.md B5).
+ *
+ * `main` is the transcript's own index: a file read beside another one — the
+ * transcript was rewritten — is read again from its start.
+ *
+ * NEVER LESS THAN BEFORE. Every file read so far counts, listed this time or
+ * not — a folder that could not be listed for a moment, a file that could not
+ * be looked at, one past {@link MAX_SUBAGENT_FILES} — and so does what the
+ * files whose index was let go of had used (`gone`). A file read again is
+ * read beside the transcript's set of counted messages, so nothing counts
+ * twice. A total that fell made the turn across the fall cost $0 for that
+ * model, the main transcript's own tokens with it, and the file $0 for good.
+ */
+function subagentUsage(transcriptPath, main) {
+    const files = subagentFiles(transcriptPath);
+    let known = subagentIndexes.get(transcriptPath);
+    if (known && known.beside !== main) {
+        subagentIndexes.delete(transcriptPath);
+        known = undefined;
+    }
+    if (files.length === 0 && !known)
+        return [];
+    if (!known) {
+        known = { beside: main, files: new Map(), gone: new Map() };
+        subagentIndexes.set(transcriptPath, known);
+    }
+    const gone = known.gone;
+    const usageOnly = { seen: main.usageSeen, retire: (old) => addUsage(gone, old.usage) };
+    for (const file of files)
+        indexIn(known.files, file, MAX_SUBAGENT_FILES, usageOnly);
+    return [gone, ...[...known.files.values()].map((idx) => idx.usage)];
+}
+/** `from`'s tokens added into `into`, key by key. */
+function addUsage(into, from) {
+    for (const [key, u] of from) {
+        const sum = into.get(key);
+        if (!sum) {
+            into.set(key, { ...u });
+            continue;
+        }
+        sum.inputTokens += u.inputTokens;
+        sum.outputTokens += u.outputTokens;
+        sum.cacheReadTokens += u.cacheReadTokens;
+        sum.cacheCreationTokens += u.cacheCreationTokens;
+        if (u.cacheCreation1hTokens)
+            sum.cacheCreation1hTokens = (sum.cacheCreation1hTokens ?? 0) + u.cacheCreation1hTokens;
+    }
+}
+/**
+ * The session's own transcript for a path a hook handed over: a sub-agent's
+ * file (`<session>/subagents/…/agent-….jsonl`) names its session's, and any
+ * other path is itself. A session is measured from its own transcript, which
+ * adds its sub-agents' files up ({@link subagentUsage}): were a sub-agent's
+ * file taken for it, a turn's marks would be read from two different files.
+ */
+export function sessionTranscriptPath(path) {
+    const m = /^(.*)[\\/]subagents[\\/](?:.*[\\/])?agent-[^\\/]+\.jsonl$/.exec(path);
+    return m ? `${m[1]}.jsonl` : path;
+}
 function parse(bytes) {
     const text = bytes.toString("utf8").trim();
     if (!text)
@@ -300,6 +448,10 @@ function parse(bytes) {
     }
 }
 function ingest(idx, bytes) {
+    // A sub-agent's file is read for its tokens: most of its lines are tool
+    // results, some of them megabytes, and none of those is parsed.
+    if (idx.usageOnly && !bytes.includes(USAGE_KEY))
+        return;
     const line = parse(bytes);
     // A terminated line that does not parse is corrupt, not half-written: skip it.
     if (line)
@@ -316,9 +468,46 @@ function dayLineIn(text) {
     // The whole line, never cut at a full stop: "Nov. 30, 2023" has one inside.
     return redactText(DAY_LINE.exec(whole)?.[0] ?? "").slice(0, 200);
 }
+/** A message's `usage` into the index's totals, deduplicated by message id (see `totalUsage`'s note on why). */
+function foldUsage(idx, message) {
+    const usage = message?.usage;
+    if (!usage || typeof usage !== "object")
+        return;
+    const id = message?.id;
+    if (id && idx.usageSeen.has(id))
+        return;
+    if (id)
+        idx.usageSeen.add(id);
+    const model = message?.model ?? "unknown";
+    const input = count(usage.input_tokens);
+    const read = count(usage.cache_read_input_tokens);
+    const written = count(usage.cache_creation_input_tokens);
+    // A message is one request, and some of what sets its price is the
+    // request's own: its prompt length, its speed, where it ran. Requests
+    // priced differently are summed apart (replay/pricing.ts).
+    const rates = requestRates(model, {
+        promptTokens: input + read + written,
+        speed: usage.speed,
+        inferenceGeo: usage.inference_geo,
+    });
+    const key = model + rateKey(rates);
+    const acc = idx.usage.get(key) ?? { ...zeroUsage(model), ...rates };
+    acc.inputTokens += input;
+    acc.outputTokens += count(usage.output_tokens);
+    acc.cacheReadTokens += read;
+    acc.cacheCreationTokens += written;
+    const written1h = Math.min(written, count(usage.cache_creation?.ephemeral_1h_input_tokens));
+    if (written1h > 0)
+        acc.cacheCreation1hTokens = (acc.cacheCreation1hTokens ?? 0) + written1h;
+    idx.usage.set(key, acc);
+}
 /** What one line contributes to every answer this module gives. */
 function foldLine(idx, line) {
     idx.lineNo += 1;
+    if (idx.usageOnly) {
+        foldUsage(idx, line.message);
+        return;
+    }
     // The day the agent was told it is (issue 1212): a system prompt's
     // "Today's date is …", and the host's own date reminder beside it.
     if (line.type === "attachment" && line.attachment?.type === "prompt_snapshot") {
@@ -337,31 +526,43 @@ function foldLine(idx, line) {
     const message = line.message;
     const role = message?.role ?? line.type;
     const blocks = blocksOf(line);
-    // Usage, deduplicated by message id (see `totalUsage`'s note on why).
-    const usage = message?.usage;
-    if (usage && typeof usage === "object") {
-        const id = message?.id;
-        if (!id || !idx.usageSeen.has(id)) {
-            if (id)
-                idx.usageSeen.add(id);
-            const model = message?.model ?? "unknown";
-            const acc = idx.usage.get(model) ?? zeroUsage(model);
-            acc.inputTokens += usage.input_tokens ?? 0;
-            acc.outputTokens += usage.output_tokens ?? 0;
-            acc.cacheReadTokens += usage.cache_read_input_tokens ?? 0;
-            acc.cacheCreationTokens += usage.cache_creation_input_tokens ?? 0;
-            idx.usage.set(model, acc);
+    foldUsage(idx, message);
+    // Where the conversation stands ({@link settledTurnEnd}). A sub-agent's
+    // lines are another conversation: its last answer does not end this turn.
+    if (line.isSidechain !== true) {
+        if (role === "assistant") {
+            const stop = message?.stop_reason;
+            const calls = stop === "tool_use" || (stop == null && blocks.some((b) => b.type === "tool_use"));
+            idx.tail = calls ? "tool_call" : "answer";
+        }
+        else if (role === "user") {
+            idx.tail = "user";
         }
     }
     if (role === "assistant") {
         const text = textOf(blocks);
-        if (text)
+        if (text) {
             idx.lastAssistantText = text;
+            if (line.isSidechain !== true)
+                idx.textSincePrompt = true;
+        }
     }
     else if (role === "user") {
         // A user line carrying text is a prompt: "this prompt's results" start
         // again from it, its own tool results included.
         const text = textOf(blocks);
+        if (text && line.isSidechain !== true) {
+            // What the turn before this prompt answered, kept for a turn whose
+            // books close after the next one has begun ({@link answerBeforePrompt}).
+            idx.prompts += 1;
+            idx.answersBefore.set(idx.prompts, idx.textSincePrompt ? idx.lastAssistantText : "");
+            idx.textSincePrompt = false;
+            if (idx.answersBefore.size > MAX_ANSWERS_KEPT) {
+                const oldest = idx.answersBefore.keys().next().value;
+                if (oldest !== undefined)
+                    idx.answersBefore.delete(oldest);
+            }
+        }
         if (text) {
             if (!idx.sawPrompt)
                 idx.firstUserPrompt = text;
@@ -512,6 +713,7 @@ export async function settledTextAfterToolUse(transcriptPath, toolUseId, opts =
 /** Forget every cached index (tests; a caller that knows files were replaced). */
 export function forgetTranscripts() {
     indexes.clear();
+    subagentIndexes.clear();
 }
 // ── accessors ───────────────────────────────────────────────────────────────
 /**
@@ -645,6 +847,66 @@ export async function settledLastAssistantText(transcriptPath, opts = {}) {
     }
     return latest || before;
 }
+/** How many prompts the transcript holds so far: user lines of the main conversation that carry text. */
+export function promptCount(transcriptPath) {
+    if (!transcriptPath)
+        return 0;
+    return indexFor(transcriptPath)?.prompts ?? 0;
+}
+/**
+ * The assistant's last text of the turn that ended before prompt number
+ * `prompt` (the first prompt is 1): "" when that turn wrote none, and
+ * undefined while that prompt has not been written — or is long past.
+ *
+ * WHY. A turn's answer is read a moment after its `Stop`, once its last
+ * message is in the file. A prompt queued behind the turn can open the next
+ * turn inside that moment, and "the last assistant text" is then the next
+ * turn's: a recording was finished with the answer to another prompt. The
+ * answer of a turn is what stood when the next prompt was written.
+ */
+export function answerBeforePrompt(transcriptPath, prompt) {
+    if (!transcriptPath)
+        return undefined;
+    return indexFor(transcriptPath)?.answersBefore.get(prompt);
+}
+/**
+ * Wait for the turn's last message to be in the transcript: until the
+ * conversation's newest line is an assistant message that calls no tool, or
+ * `timeoutMs` has passed. True when it is there.
+ *
+ * WHY. `Stop` fires before Claude Code has written the turn's last message (see
+ * {@link settledLastAssistantText}), and that message carries its own `usage`.
+ * A turn's cost read at `Stop` is therefore one model call short — and the
+ * call it lacks is counted in no turn at all, because the next turn's mark is
+ * taken after the line has landed. On a recording that is one call in many. On
+ * a replay it is most of the turn: the model's one call there is the one that
+ * reads the plan's results and answers. The console showed such turns as 93%
+ * and 97% saved where Claude Code's own bill said 42% (the service's
+ * improvelst.md, item 1).
+ *
+ * Returns at once when the message is already there, when the file cannot be
+ * read (there is no cost to wait for), and when its lines do not say how a
+ * message stopped and the newest one calls no tool (an older host, a fixture).
+ */
+export async function settledTurnEnd(transcriptPath, opts = {}) {
+    if (!transcriptPath)
+        return false;
+    const pollMs = Math.max(10, opts.pollMs ?? 100);
+    const deadline = Date.now() + Math.max(0, opts.timeoutMs ?? 2_000);
+    for (;;) {
+        const tail = indexFor(transcriptPath)?.tail;
+        if (tail === undefined)
+            return false;
+        if (tail === "answer")
+            return true;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return false;
+        // Not unref'd: the turn's report waits on this, and a recorder asked to
+        // stop meanwhile stays for the moment it takes rather than lose it.
+        await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, left)));
+    }
+}
 const zeroUsage = (model) => ({
     model,
     inputTokens: 0,
@@ -652,6 +914,8 @@ const zeroUsage = (model) => ({
     cacheReadTokens: 0,
     cacheCreationTokens: 0,
 });
+/** A token count as a transcript line gives it: a missing or broken one is 0. */
+const count = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 /**
  * Sum every assistant message's `usage` in the whole file, keyed by model.
  *
@@ -682,6 +946,9 @@ function totalUsage(transcriptPath) {
         return totals;
     for (const [model, u] of idx.usage)
         totals.set(model, { ...u });
+    // And what the session's sub-agents used, each in a file of its own.
+    for (const usage of subagentUsage(transcriptPath, idx))
+        addUsage(totals, usage);
     return totals;
 }
 /**
@@ -718,17 +985,31 @@ export function markTranscriptUsage(transcriptPath) {
 export function usageSince(transcriptPath, mark) {
     if (!transcriptPath)
         return [];
-    const now = totalUsage(transcriptPath);
+    return usageBetween(mark, totalUsage(transcriptPath));
+}
+/**
+ * The usage between two marks of one transcript, `from` the earlier: what
+ * {@link usageSince} gives, with `to` in the place of the transcript as it is
+ * now. A turn whose books are closed after the next turn has started ends at
+ * that turn's mark, not at whatever the file holds by then.
+ */
+export function usageBetween(mark, now) {
     const out = [];
-    for (const [model, current] of now) {
-        const before = mark?.get(model);
+    for (const [key, current] of now) {
+        const before = mark?.get(key);
         const delta = {
-            model,
+            // The entry's own model and flags: its key carries the rate key too.
+            ...current,
             inputTokens: Math.max(0, current.inputTokens - (before?.inputTokens ?? 0)),
             outputTokens: Math.max(0, current.outputTokens - (before?.outputTokens ?? 0)),
             cacheReadTokens: Math.max(0, current.cacheReadTokens - (before?.cacheReadTokens ?? 0)),
             cacheCreationTokens: Math.max(0, current.cacheCreationTokens - (before?.cacheCreationTokens ?? 0)),
         };
+        const written1h = Math.max(0, (current.cacheCreation1hTokens ?? 0) - (before?.cacheCreation1hTokens ?? 0));
+        if (written1h > 0)
+            delta.cacheCreation1hTokens = Math.min(written1h, delta.cacheCreationTokens);
+        else
+            delete delta.cacheCreation1hTokens;
         if (delta.inputTokens ||
             delta.outputTokens ||
             delta.cacheReadTokens ||

package/dist/jsonrpc/framing.d.ts

@@ -59,15 +59,30 @@ export interface FrameHandlers {
 export interface FrameOptions {
     maxLineBytes?: number;
 }
+/** Note that `msg` was parsed from `text`, so it can be written again as that text. */
+export declare function rememberText(msg: object, text: string): void;
+/** Forget the text `msg` was parsed from: it is serialised again when written, with any change made to it. */
+export declare function forgetText(msg: unknown): void;
+/**
+ * The text `msg` was parsed from, when it can be sent again as one line;
+ * undefined for a message nobody read off the wire, and for one whose text
+ * holds a raw line break (a pretty-printed HTTP body: inside a JSON string a
+ * line break is always escaped, so a raw one is layout, and layout cannot
+ * cross a line-delimited stream). One trailing CR is a CRLF sender's line
+ * ending, not part of the message.
+ */
+export declare function receivedText(msg: unknown): string | undefined;
 /**
  * Read newline-delimited JSON messages off `input`.
  * Returns a detach function that stops the reader (it does not close `input`).
  */
 export declare function readFrames(input: Readable, handlers: FrameHandlers, opts?: FrameOptions): () => void;
 /**
- * Write one message as a single line. Serialization failure is swallowed after
- * being reported: a proxy that throws while answering the host takes the host's
- * session down with it, which rule 4 of §1 forbids.
+ * Write one message as a single line: the line it was read from when `msg` is
+ * the very object a reader produced ({@link receivedText}), its serialisation
+ * otherwise. Serialization failure is swallowed after being reported: a proxy
+ * that throws while answering the host takes the host's session down with it,
+ * which rule 4 of §1 forbids.
  */
 export declare function writeFrame(output: Writable, msg: unknown, onError?: (err: Error) => void): void;
 /**