@itookit/dsht 0.3.3 → 0.3.7

package/dist/controller/controller.d.ts

@@ -12,6 +12,8 @@ import { ConnectionController, type ConnectionListener } from './connection.ts';
 import { MemoryLog } from './memory-log.ts';
 import { type ControllerStore, type State } from '../state.ts';
 import type { HistorySearch, RemovalTarget } from '../session/types.ts';
+import type { ComposerState, InteractionState, ModelState, OptionState, PanelState, ReferenceState, ViewState } from '../session/info.ts';
+import type { Reasoning } from '../session/history.ts';
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
@@ -47,6 +49,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     snapshot: () => State;
     /** Current projection store; replaced at each connection generation. */
     get telemetry(): Telemetry;
+    /** Record of the selected session; the one strong owner lives in `State.session`. */
+    get record(): Transcript;
     /** @returns The current selector generation. */
     selection(): number;
     /** Advance the selector generation when the selected workspace or session changes. */
@@ -75,6 +79,10 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
      * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
      * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     *
+     * React's development build appends one performance-timeline entry per rendered component and Node
+     * never trims them, so the sample counts them and then bounds them; `perfMeasuresCleared` separates
+     * entries this sample released from entries the build created since the last one.
      */
     private memorySample;
     /** Collect before reading the heap when the runtime exposes a collection.
@@ -120,6 +128,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     get workingSince(): number | undefined;
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
     get visibleSessions(): ObjectValue[];
+    /** @returns Unanswered interactions by session, for the state each list row reports. */
+    pendingCounts(): ReadonlyMap<string, number>;
     /** Load the optional preset roster once per connection. */
     loadPresetNames(): void;
     /** @returns Host model routes and adapter-owned reasoning choices. */
@@ -135,10 +145,113 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @returns True when the caller may exit.
      */
     interrupt(force?: boolean): Promise<boolean>;
+    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
+    get sessionCostText(): string;
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
     pinHistory(pinned: boolean): void;
+    /** Recall one step through the selected session's prompt index; never touches the network.
+     * @param direction - Negative for older input, positive for newer input.
+     * @param current - Composer content before recall began, restored at the newest position.
+     * @returns The recalled prompt, or the unsent draft.
+     */
+    recall(direction: -1 | 1, current: string): string;
+    /** Remember a locally submitted command, which never becomes a durable session record.
+     * @param value - Submitted command text.
+     */
+    recordRecall(value: string): void;
+    /** Leave recall navigation because the composer was edited or replaced. */
+    resetRecall(): void;
+    /** Whether recall is parked on the oldest prompt the session retains. */
+    get recallAtOldest(): boolean;
+    /** How many prompts the selected session retains for recall. */
+    get recallLength(): number;
+    /** Whether an older prompt is reachable, in the loaded window or on the host. */
+    get recallHasOlder(): boolean;
+    /** Recover older prompts from the loaded window before spending a page request.
+     * @returns Whether any older prompt was recovered.
+     */
+    refillRecall(): boolean;
+    /** Composer draft, caret and parked draft of the selected session. */
+    get composer(): ComposerState;
+    /** Replace the composer text and caret.
+     * @param draft - New text.
+     * @param cursor - Caret column; defaults to the end of the text.
+     */
+    setComposer(draft: string, cursor?: number): void;
+    /** Move the caret without changing the text.
+     * @param cursor - Caret column.
+     */
+    setComposerCursor(cursor: number): void;
+    /** Move a non-empty draft aside while a dialog owns the keyboard. */
+    parkComposer(): void;
+    /** Give a parked draft back once no dialog needs the keyboard. */
+    restoreComposer(): void;
+    /** How the selected session's record is being read right now. */
+    get view(): ViewState;
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
+    setViewWindow(window?: Transcript): void;
+    /** Move the reader's position inside the displayed record.
+     * @param scroll - Rows scrolled back from the live end.
+     */
+    setScroll(scroll: number): void;
+    /** Replace the set of expanded reasoning blocks.
+     * @param folds - Sequences to expand beyond the default fold.
+     */
+    setFolds(folds: ReadonlySet<number>): void;
+    /** Set the fold mode of the live attempt's completed reasoning.
+     * @param reasoning - `row` to fold, `full` to keep the streamed text.
+     */
+    setLiveReasoning(reasoning: Reasoning): void;
+    /** Local answer state for the selected session's pending waterfalls. */
+    get interaction(): InteractionState;
+    /** Replace the partly collected answers, keyed by waterfall event id.
+     * @param answers - Answers collected so far, by event id.
+     */
+    setAnswers(answers: Record<string, ObjectValue[]>): void;
+    /** Replace the pending question's option keyboard state.
+     * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
+     */
+    setOption(option?: OptionState): void;
+    /** Replace the pending approval's selected row.
+     * @param approval - Selected approval row; undefined clears the highlight.
+     */
+    setApproval(approval?: InteractionState['approval']): void;
+    /** Composer-adjacent `@` reference menu state. */
+    get reference(): ReferenceState;
+    /** Highlight one row of the open reference menu.
+     * @param index - Row index into the current matches.
+     */
+    setReferenceIndex(index: number): void;
+    /** Remember the draft that dismissed the reference menu.
+     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
+     */
+    setReferenceDismissed(draft?: string): void;
+    /** Panels the selected session has open. */
+    get panels(): PanelState;
+    /** Show or hide the reasoning panel.
+     * @param open - Whether `/think` is open.
+     */
+    openThoughts(open: boolean): void;
+    /** Show or hide the pending-input panel.
+     * @param open - Whether `/queue` is open.
+     */
+    openQueue(open: boolean): void;
+    /** Show the model dialog at one step, or close it.
+     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
+     */
+    setModelPanel(model?: ModelState): void;
+    /** Show the history or content-search dialog, or close it.
+     * @param history - Query, content-search mode and matches; undefined closes the dialog.
+     */
+    setHistoryPanel(history?: PanelState['history']): void;
+    /** Show the host session-search results, or close them.
+     * @param search - Query, results and truncation flag; undefined closes the dialog.
+     */
+    setSearchPanel(search?: PanelState['search']): void;
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */
@@ -264,6 +377,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @param allowed - Whether the request is approved once.
      */
     approve(allowed: boolean): Promise<void>;
+    /** Dismiss the whole pending question set without answering it, as the Web close button does. */
+    dismissQuestion(): Promise<void>;
 }
 export type { HistorySearch, RemovalTarget } from '../session/types.ts';
 export type { State } from '../state.ts';

package/dist/controller/controller.js

@@ -8,8 +8,10 @@ import { markdownCacheStats } from "../session/markdown.js";
 import { SessionController } from "../session/controller.js";
 import { CatalogController } from "../catalog/controller.js";
 import { CostController } from "../cost/controller.js";
+import { costText } from "../cost/ledger.js";
 import { ConnectionController } from "./connection.js";
 import { MemoryLog } from "./memory-log.js";
+import { clearReactMeasures, measureCount } from "./perf-measures.js";
 import { initialState } from "../state.js";
 /** Application facade over the domain controllers; the UI owns only this object.
  *
@@ -55,6 +57,10 @@ export class Controller {
                 online: () => this.state.online,
                 signal: () => this.connection.signal(),
                 publish: () => this.update({}),
+                // The scan already reads every session's whole history; handing its pages to the session
+                // domain lets the prompt cache pick them up, so one open does not pay for a second walk.
+                scanPage: (sessionId, records) => this.session.rememberScanPage(sessionId, records),
+                scanDone: sessionId => this.session.rememberScanDone(sessionId),
             });
         if (memoryLogPath !== undefined)
             this.memoryLog = new MemoryLog(memoryLogPath, () => this.memorySample());
@@ -68,6 +74,8 @@ export class Controller {
     snapshot = () => this.state;
     /** Current projection store; replaced at each connection generation. */
     get telemetry() { return this.connection.telemetry; }
+    /** Record of the selected session; the one strong owner lives in `State.session`. */
+    get record() { return this.state.session.record; }
     /** @returns The current selector generation. */
     selection() { return this.selector; }
     /** Advance the selector generation when the selected workspace or session changes. */
@@ -129,18 +137,25 @@ export class Controller {
      * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
      * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
      * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     *
+     * React's development build appends one performance-timeline entry per rendered component and Node
+     * never trims them, so the sample counts them and then bounds them; `perfMeasuresCleared` separates
+     * entries this sample released from entries the build created since the last one.
      */
     memorySample() {
         const memory = process.memoryUsage();
-        const transcript = this.state.transcript;
+        const transcript = this.state.session.record;
         const ledger = this.costs?.summary();
         const layout = layoutStats(transcript);
         const markdown = markdownCacheStats();
+        const measuresCleared = clearReactMeasures();
+        const measures = measureCount();
         const gc = this.forcedGc();
         return {
             time: new Date().toISOString(),
             rss: memory.rss, heapTotal: memory.heapTotal, heapUsed: memory.heapUsed,
             external: memory.external, arrayBuffers: memory.arrayBuffers,
+            ...(measures === undefined ? {} : { perfMeasures: measures, perfMeasuresCleared: measuresCleared }),
             ...(gc === undefined ? {} : { heapUsedAfterGc: gc.used, gcMs: gc.ms }),
             online: this.state.online, screen: this.state.screen,
             session: this.state.sessionId ?? null,
@@ -224,6 +239,8 @@ export class Controller {
     get workingSince() { return this.session.workingSince; }
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
     get visibleSessions() { return this.session.visibleSessions; }
+    /** @returns Unanswered interactions by session, for the state each list row reports. */
+    pendingCounts() { return this.session.pendingCounts(); }
     /** Load the optional preset roster once per connection. */
     loadPresetNames() { this.catalog.loadPresetNames(); }
     /** @returns Host model routes and adapter-owned reasoning choices. */
@@ -241,10 +258,116 @@ export class Controller {
      * @returns True when the caller may exit.
      */
     interrupt(force = false) { return this.session.interrupt(force); }
+    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
+    get sessionCostText() {
+        const sessionId = this.state.sessionId;
+        return this.costs?.hasSession(sessionId) ? costText(this.costs.total(sessionId)) : '?';
+    }
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
     pinHistory(pinned) { this.session.pinHistory(pinned); }
+    /** Recall one step through the selected session's prompt index; never touches the network.
+     * @param direction - Negative for older input, positive for newer input.
+     * @param current - Composer content before recall began, restored at the newest position.
+     * @returns The recalled prompt, or the unsent draft.
+     */
+    recall(direction, current) { return this.session.recall(direction, current); }
+    /** Remember a locally submitted command, which never becomes a durable session record.
+     * @param value - Submitted command text.
+     */
+    recordRecall(value) { this.session.recordRecall(value); }
+    /** Leave recall navigation because the composer was edited or replaced. */
+    resetRecall() { this.session.resetRecall(); }
+    /** Whether recall is parked on the oldest prompt the session retains. */
+    get recallAtOldest() { return this.session.recallAtOldest; }
+    /** How many prompts the selected session retains for recall. */
+    get recallLength() { return this.session.recallLength; }
+    /** Whether an older prompt is reachable, in the loaded window or on the host. */
+    get recallHasOlder() { return this.session.recallHasOlder; }
+    /** Recover older prompts from the loaded window before spending a page request.
+     * @returns Whether any older prompt was recovered.
+     */
+    refillRecall() { return this.session.refillRecall(); }
+    /** Composer draft, caret and parked draft of the selected session. */
+    get composer() { return this.session.composer; }
+    /** Replace the composer text and caret.
+     * @param draft - New text.
+     * @param cursor - Caret column; defaults to the end of the text.
+     */
+    setComposer(draft, cursor) { this.session.setComposer(draft, cursor); }
+    /** Move the caret without changing the text.
+     * @param cursor - Caret column.
+     */
+    setComposerCursor(cursor) { this.session.setComposerCursor(cursor); }
+    /** Move a non-empty draft aside while a dialog owns the keyboard. */
+    parkComposer() { this.session.parkComposer(); }
+    /** Give a parked draft back once no dialog needs the keyboard. */
+    restoreComposer() { this.session.restoreComposer(); }
+    /** How the selected session's record is being read right now. */
+    get view() { return this.session.view; }
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
+    setViewWindow(window) { this.session.setViewWindow(window); }
+    /** Move the reader's position inside the displayed record.
+     * @param scroll - Rows scrolled back from the live end.
+     */
+    setScroll(scroll) { this.session.setScroll(scroll); }
+    /** Replace the set of expanded reasoning blocks.
+     * @param folds - Sequences to expand beyond the default fold.
+     */
+    setFolds(folds) { this.session.setFolds(folds); }
+    /** Set the fold mode of the live attempt's completed reasoning.
+     * @param reasoning - `row` to fold, `full` to keep the streamed text.
+     */
+    setLiveReasoning(reasoning) { this.session.setLiveReasoning(reasoning); }
+    /** Local answer state for the selected session's pending waterfalls. */
+    get interaction() { return this.session.interaction; }
+    /** Replace the partly collected answers, keyed by waterfall event id.
+     * @param answers - Answers collected so far, by event id.
+     */
+    setAnswers(answers) { this.session.setAnswers(answers); }
+    /** Replace the pending question's option keyboard state.
+     * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
+     */
+    setOption(option) { this.session.setOption(option); }
+    /** Replace the pending approval's selected row.
+     * @param approval - Selected approval row; undefined clears the highlight.
+     */
+    setApproval(approval) { this.session.setApproval(approval); }
+    /** Composer-adjacent `@` reference menu state. */
+    get reference() { return this.session.reference; }
+    /** Highlight one row of the open reference menu.
+     * @param index - Row index into the current matches.
+     */
+    setReferenceIndex(index) { this.session.setReferenceIndex(index); }
+    /** Remember the draft that dismissed the reference menu.
+     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
+     */
+    setReferenceDismissed(draft) { this.session.setReferenceDismissed(draft); }
+    /** Panels the selected session has open. */
+    get panels() { return this.session.panels; }
+    /** Show or hide the reasoning panel.
+     * @param open - Whether `/think` is open.
+     */
+    openThoughts(open) { this.session.openThoughts(open); }
+    /** Show or hide the pending-input panel.
+     * @param open - Whether `/queue` is open.
+     */
+    openQueue(open) { this.session.openQueue(open); }
+    /** Show the model dialog at one step, or close it.
+     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
+     */
+    setModelPanel(model) { this.session.setModelPanel(model); }
+    /** Show the history or content-search dialog, or close it.
+     * @param history - Query, content-search mode and matches; undefined closes the dialog.
+     */
+    setHistoryPanel(history) { this.session.setHistoryPanel(history); }
+    /** Show the host session-search results, or close them.
+     * @param search - Query, results and truncation flag; undefined closes the dialog.
+     */
+    setSearchPanel(search) { this.session.setSearchPanel(search); }
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */
@@ -369,4 +492,6 @@ export class Controller {
      * @param allowed - Whether the request is approved once.
      */
     async approve(allowed) { await this.session.approve(allowed); }
+    /** Dismiss the whole pending question set without answering it, as the Web close button does. */
+    async dismissQuestion() { await this.session.dismissQuestion(); }
 }

package/dist/controller/perf-measures.d.ts

@@ -0,0 +1,34 @@
+/** Drop the render measurements React's development build appends to the global performance timeline.
+ *
+ * `react-reconciler` emits one `performance.measure()` entry per rendered component when it resolves
+ * to its development build, and Node keeps every entry for the life of the process because
+ * `performance.clearMeasures()` is the only way to release them. Each entry also carries a
+ * `detail.devtools.properties` payload describing the component's props, which is where the memory
+ * actually goes: roughly 1.2 KB per render once the duplicated property names are counted.
+ *
+ * The production build emits no measurements at all, so `src/cli/index.ts` selects it and this
+ * module is a safety net for `DSHT_REACT_DEV=1`, where the development build is deliberate.
+ */
+/** Measure names the current timeline holds that React created.
+ *
+ * A name only counts when it is exactly one of `REACT_NAMES` or carries React's zero-width prefix,
+ * so entries an application or a library created under its own name are never selected.
+ * @param performance - Timeline to read.
+ * @returns Names React created, without duplicates.
+ */
+export declare function reactMeasureNames(performance: Performance): string[];
+/** Remove React's render measurements, and only those, from the global performance timeline.
+ *
+ * Intended to run on the memory-sampling interval: the development build keeps appending, so one
+ * pass only bounds the total instead of ending it. A failure is not worth propagating, because this
+ * is a bounded diagnostic and a measurement library that rejects input should not stop the client.
+ * @returns How many distinct measure names were cleared.
+ */
+export declare function clearReactMeasures(): number;
+/** How many measure entries the timeline currently holds.
+ *
+ * Recorded next to the heap counters so a memory log shows whether retained growth tracks the
+ * render count. Entries cleared by `clearReactMeasures` leave the count at zero.
+ * @returns Entry count, or undefined on a runtime without a readable timeline.
+ */
+export declare function measureCount(): number | undefined;

package/dist/controller/perf-measures.js

@@ -0,0 +1,78 @@
+/** Drop the render measurements React's development build appends to the global performance timeline.
+ *
+ * `react-reconciler` emits one `performance.measure()` entry per rendered component when it resolves
+ * to its development build, and Node keeps every entry for the life of the process because
+ * `performance.clearMeasures()` is the only way to release them. Each entry also carries a
+ * `detail.devtools.properties` payload describing the component's props, which is where the memory
+ * actually goes: roughly 1.2 KB per render once the duplicated property names are counted.
+ *
+ * The production build emits no measurements at all, so `src/cli/index.ts` selects it and this
+ * module is a safety net for `DSHT_REACT_DEV=1`, where the development build is deliberate.
+ */
+/** Zero-width space React prefixes to a component's own measure name; see `ReactFiberPerformanceTrack` in react-reconciler. */
+const COMPONENT_PREFIX = '\u200b';
+/** Measure names React passes as an explicit update trigger, or as the label for an errored or recovered boundary. */
+const REACT_NAMES = [
+    'Update', 'Cascading Update', 'Update Blocked', 'Update Suspended', 'Mount', 'Unmount',
+    'Reconnect', 'Disconnect', 'Recovered', 'Errored',
+];
+/** Constructors `performance` uses for invalid input, which a measurement library cannot survive. */
+const PROGRAMMING_ERRORS = ['TypeError', 'RangeError', 'SyntaxError'];
+/** The global performance timeline, when the runtime exposes one.
+ * @returns The timeline, or undefined on a runtime without `performance` or `getEntriesByType`.
+ */
+function timeline() {
+    const candidate = globalThis.performance;
+    return typeof candidate?.getEntriesByType === 'function' ? candidate : undefined;
+}
+/** Measure names the current timeline holds that React created.
+ *
+ * A name only counts when it is exactly one of `REACT_NAMES` or carries React's zero-width prefix,
+ * so entries an application or a library created under its own name are never selected.
+ * @param performance - Timeline to read.
+ * @returns Names React created, without duplicates.
+ */
+export function reactMeasureNames(performance) {
+    const names = new Set();
+    for (const entry of performance.getEntriesByType('measure')) {
+        const name = entry.name;
+        if (name.startsWith(COMPONENT_PREFIX))
+            names.add(name);
+        else if (REACT_NAMES.includes(name))
+            names.add(name);
+    }
+    return [...names];
+}
+/** Remove React's render measurements, and only those, from the global performance timeline.
+ *
+ * Intended to run on the memory-sampling interval: the development build keeps appending, so one
+ * pass only bounds the total instead of ending it. A failure is not worth propagating, because this
+ * is a bounded diagnostic and a measurement library that rejects input should not stop the client.
+ * @returns How many distinct measure names were cleared.
+ */
+export function clearReactMeasures() {
+    const performance = timeline();
+    if (performance === undefined)
+        return 0;
+    const names = reactMeasureNames(performance);
+    for (const name of names) {
+        try {
+            performance.clearMeasures(name);
+        }
+        catch (error) {
+            if (!PROGRAMMING_ERRORS.includes(error?.name ?? ''))
+                throw error;
+        }
+    }
+    return names.length;
+}
+/** How many measure entries the timeline currently holds.
+ *
+ * Recorded next to the heap counters so a memory log shows whether retained growth tracks the
+ * render count. Entries cleared by `clearReactMeasures` leave the count at zero.
+ * @returns Entry count, or undefined on a runtime without a readable timeline.
+ */
+export function measureCount() {
+    const performance = timeline();
+    return performance?.getEntriesByType('measure').length;
+}

package/dist/cost/controller.d.ts

@@ -1,5 +1,6 @@
 /** Periodic billing scans; the ledger outlives any single connection generation. */
 import type { Client } from '../transport/client.ts';
+import { type Json } from '../transport/wire.ts';
 import type { CostLedger } from './ledger.ts';
 /** Host access a scan needs; supplied by the controller facade. */
 export interface CostHost {
@@ -11,6 +12,10 @@ export interface CostHost {
     signal(): AbortSignal;
     /** Re-publish controller state after the ledger changes. */
     publish(): void;
+    /** Hand one already-read history page to another consumer, which owns what it does with it. */
+    scanPage?(sessionId: string, records: readonly Json[]): void;
+    /** Report that a session's history was read to its beginning. */
+    scanDone?(sessionId: string): void;
 }
 /** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
 export declare class CostController {

package/dist/cost/controller.js

@@ -77,7 +77,8 @@ export class CostController {
                     if (!session.running && typeof session.updatedAt === 'number' && this.updates.get(sessionId) === session.updatedAt)
                         continue;
                     try {
-                        const history = await sessionCostHistory(client, session, combined, () => { pages++; });
+                        const history = await sessionCostHistory(client, session, combined, () => { pages++; }, records => this.host.scanPage?.(sessionId, records));
+                        this.host.scanDone?.(sessionId);
                         scanned++;
                         events += history.events.length;
                         await ledger.replace(sessionId, history.cursor, history.events);

package/dist/cost/scanner.d.ts

@@ -1,6 +1,6 @@
 /** Address and page one session's complete billing history over the host connection. */
 import { type Client } from '../transport/client.ts';
-import { type ObjectValue } from '../transport/wire.ts';
+import { type Json, type ObjectValue } from '../transport/wire.ts';
 /** Wire addresses for one `session/list` row, in the order the cost scan should try them.
  *
  * A subagent child is reachable only under its durable parent, and the list row omits the delivery
@@ -14,9 +14,11 @@ export declare function costAddresses(session: ObjectValue): ObjectValue[];
  * @param session - One row from the host session list.
  * @param signal - Cancels paging without cancelling any agent work.
  * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @param onRecords - Hands each page's raw records to the caller, which owns any further reading of
+ *   them; the billing fold itself keeps only the minimal events below.
  * @returns Opening cursor and the minimal billing events behind it.
  */
-export declare function sessionCostHistory(client: Client, session: ObjectValue, signal: AbortSignal, onPage?: () => void): Promise<{
+export declare function sessionCostHistory(client: Client, session: ObjectValue, signal: AbortSignal, onPage?: () => void, onRecords?: (records: readonly Json[]) => void): Promise<{
     cursor: number;
     events: ObjectValue[];
 }>;

package/dist/cost/scanner.js

@@ -24,13 +24,15 @@ export function costAddresses(session) {
  * @param session - One row from the host session list.
  * @param signal - Cancels paging without cancelling any agent work.
  * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @param onRecords - Hands each page's raw records to the caller, which owns any further reading of
+ *   them; the billing fold itself keeps only the minimal events below.
  * @returns Opening cursor and the minimal billing events behind it.
  */
-export async function sessionCostHistory(client, session, signal, onPage) {
+export async function sessionCostHistory(client, session, signal, onPage, onRecords) {
     let lastError;
     for (const address of costAddresses(session)) {
         try {
-            return await readCostHistory(client, address, signal, onPage);
+            return await readCostHistory(client, address, signal, onPage, onRecords);
         }
         catch (error) {
             lastError = error;
@@ -42,7 +44,7 @@ export async function sessionCostHistory(client, session, signal, onPage) {
     throw lastError;
 }
 /** Page one addressed session's history into the billing events the ledger folds. */
-async function readCostHistory(client, address, signal, onPage) {
+async function readCostHistory(client, address, signal, onPage, onRecords) {
     onPage?.();
     const snapshot = await new Promise((resolve, reject) => {
         let sub;
@@ -77,6 +79,7 @@ async function readCostHistory(client, address, signal, onPage) {
     while (true) {
         signal.throwIfAborted();
         const records = array(page.records);
+        onRecords?.(records);
         events.push(...costRecords(records));
         if (!page.hasMore)
             break;