@teaflask/assistant 0.0.0 → 0.6.0

package/dist/core/tool-view.js

@@ -0,0 +1,70 @@
+import { actionToolView } from "../components/tool-views/action-view.js";
+import { commandToolView } from "../components/tool-views/command-view.js";
+import { docsSearchToolView } from "../components/tool-views/docs-search-view.js";
+import { fileEditToolView } from "../components/tool-views/file-edit-view.js";
+import { questionsToolView } from "../components/tool-views/questions-view.js";
+const RESERVED_TOOL_VIEW_KEY_PREFIX = "teaflask.";
+export function isReservedToolViewKey(key) {
+    return key.startsWith(RESERVED_TOOL_VIEW_KEY_PREFIX);
+}
+export const PACKAGE_TOOL_VIEWS = Object.freeze({
+    "teaflask.questions": { version: 1, view: questionsToolView },
+    "teaflask.action": { version: 1, view: actionToolView },
+    "teaflask.command": { version: 1, view: commandToolView },
+    "teaflask.file-edit": { version: 1, view: fileEditToolView },
+    "teaflask.docs-search": { version: 1, view: docsSearchToolView },
+});
+export function actionToolName(slug) {
+    return `action__${slug}`;
+}
+export function actionToolViews(bySlug) {
+    const registry = {};
+    for (const [slug, registration] of Object.entries(bySlug)) {
+        registry[actionToolName(slug)] = registration;
+    }
+    return registry;
+}
+export function resolvedToolViewsOf(ref, toolName, registry, builtIns = PACKAGE_TOOL_VIEWS) {
+    const candidates = [];
+    if (ref !== undefined && !isReservedToolViewKey(ref.key)) {
+        const registration = _ownRegistrationOf(registry, ref.key);
+        if (registration !== undefined) {
+            if (registration.version === ref.version) {
+                candidates.push({ rung: 1, key: ref.key, registration });
+            }
+        }
+    }
+    if (!isReservedToolViewKey(toolName)) {
+        const registration = _ownRegistrationOf(registry, toolName);
+        if (registration !== undefined) {
+            candidates.push({ rung: 2, key: toolName, registration });
+        }
+    }
+    if (ref !== undefined && isReservedToolViewKey(ref.key)) {
+        const registration = _ownRegistrationOf(builtIns, ref.key);
+        if (registration !== undefined) {
+            if (registration.version === ref.version) {
+                candidates.push({ rung: 3, key: ref.key, registration });
+            }
+        }
+    }
+    const views = [];
+    const icons = [];
+    for (const { rung, key, registration } of candidates) {
+        if (registration.view !== undefined) {
+            views.push({ rung, key, adapter: registration.view });
+        }
+        if (registration.icon !== undefined) {
+            icons.push({ rung, key, adapter: registration.icon });
+        }
+    }
+    return { views, icons };
+}
+function _ownRegistrationOf(registry, key) {
+    if (registry === undefined) {
+        return undefined;
+    }
+    return Object.prototype.hasOwnProperty.call(registry, key)
+        ? registry[key]
+        : undefined;
+}

package/dist/core/transcript-lease.d.ts

@@ -0,0 +1,2 @@
+import type { AssistantConversationStore } from "./conversation-store.js";
+export declare function acquireTranscriptLeaseFromStore(store: AssistantConversationStore, surface: string): () => void;

package/dist/core/transcript-lease.js

@@ -0,0 +1,20 @@
+import { publishStore, scheduleConnectionSync, } from "./conversation-publish.js";
+import { syncIdleRecheck } from "./idle-recheck.js";
+export function acquireTranscriptLeaseFromStore(store, surface) {
+    store._leaseHolders.push(surface);
+    store._automaticReconnects = 0;
+    scheduleConnectionSync(store);
+    syncIdleRecheck(store);
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        const index = store._leaseHolders.indexOf(surface);
+        if (index !== -1) {
+            store._leaseHolders.splice(index, 1);
+        }
+        publishStore(store);
+    };
+}

package/dist/core/transcript-rows.d.ts

@@ -0,0 +1,83 @@
+import type { Message } from "@ag-ui/core";
+import type { TurnAttachment } from "../contract/threads.js";
+import type { UserTurnMeta } from "./user-turn-ledger.js";
+import type { MarkerAnchorsSnapshot } from "./connection-epoch.js";
+import { type MemoryUpdated } from "./memory-provenance-anchors.js";
+import type { BlockTiming } from "./segment-timing.js";
+import { type SubagentGroupRow } from "./subagent-rows.js";
+import type { DeliveredResult } from "./subagent-delivery-anchors.js";
+import type { AnchoredTurnFailReceipts } from "./turn-failed-anchors.js";
+import type { ToolCallDisplay, ToolCallState } from "./tool-call-display.js";
+import type { ToolCallSchemas } from "./tool-schema-anchors.js";
+export type MarkerPosition = "before" | "after";
+export interface UserMessageRow {
+    kind: "user";
+    key: string;
+    text: string;
+    attachments: TurnAttachment[];
+    createdAt?: string;
+    optimistic?: true;
+}
+export interface AssistantTextRow {
+    kind: "assistant-text";
+    key: string;
+    text: string;
+    streaming: boolean;
+    memoryUpdates?: MemoryUpdated[];
+}
+export interface ReasoningRow {
+    kind: "reasoning";
+    key: string;
+    text: string;
+    streaming: boolean;
+    timing?: BlockTiming;
+}
+export interface ToolCallRow {
+    kind: "tool-call";
+    key: string;
+    toolCallId: string;
+    toolName: string;
+    state: ToolCallState;
+    argsText: string;
+    result?: string;
+    offloaded: boolean;
+    errorText?: string;
+    refusalText?: string;
+    display?: ToolCallDisplay;
+    schemas?: ToolCallSchemas;
+    timing?: BlockTiming;
+    decisionBearing?: boolean;
+}
+export interface TurnFailedReceiptsRow {
+    kind: "turn-failed-receipts";
+    key: string;
+    receipts: AnchoredTurnFailReceipts[MarkerPosition];
+}
+export interface SubagentDeliveryRow {
+    kind: "subagent-delivery";
+    key: string;
+    results: DeliveredResult[];
+}
+export type TranscriptRow = UserMessageRow | AssistantTextRow | ReasoningRow | ToolCallRow | SubagentGroupRow | TurnFailedReceiptsRow | SubagentDeliveryRow;
+export interface PendingUserEcho {
+    messageId: string;
+    text: string;
+    attachments: TurnAttachment[];
+}
+export declare function transcriptRowsOf(messages: readonly Message[], anchors: MarkerAnchorsSnapshot, running: boolean, metaByMessageId?: ReadonlyMap<string, UserTurnMeta>): TranscriptRow[];
+export declare function withPendingUserEcho(rows: readonly TranscriptRow[], echo: PendingUserEcho | null): readonly TranscriptRow[];
+export declare function trailingRowIsStreaming(rows: readonly TranscriptRow[]): boolean;
+export declare function errorTextOf(recordedError: string | undefined, result: string | undefined): string | undefined;
+export interface MarkerBoundaries {
+    before: ReadonlySet<string>;
+    after: ReadonlySet<string>;
+}
+export declare const EMPTY_MARKER_BOUNDARIES: MarkerBoundaries;
+export interface TranscriptBlock {
+    messageId: string;
+    rows: TranscriptRow[];
+}
+export declare function transcriptBlocksOf(messages: readonly Message[], anchors: MarkerAnchorsSnapshot, running: boolean, metaByMessageId?: ReadonlyMap<string, UserTurnMeta>, options?: {
+    markerBoundaries?: MarkerBoundaries;
+    attachmentsByMessageId?: ReadonlyMap<string, TurnAttachment[]>;
+}): TranscriptBlock[];

package/dist/core/transcript-rows.js

@@ -0,0 +1,305 @@
+import { newestAssistantProseIdOf } from "./assistant-prose.js";
+import { memoryFootersOf, } from "./memory-provenance-anchors.js";
+import { DISPATCH_SUBAGENT_TOOL_NAME, withSubagentGroups, } from "./subagent-rows.js";
+import { EMPTY_TOOL_DECISION_ANCHORS } from "./tool-decision-anchors.js";
+import { EMPTY_TOOL_DENIAL_ANCHORS } from "./tool-denial-anchors.js";
+const NO_TURN_META = new Map();
+export function transcriptRowsOf(messages, anchors, running, metaByMessageId = NO_TURN_META) {
+    const results = _toolResultsOf(messages);
+    const rows = [];
+    const lastAssistantTextId = newestAssistantProseIdOf(messages);
+    const lastMessageId = messages.at(-1)?.id ?? null;
+    const memoryFooters = memoryFootersOf(anchors.memoryProvenanceAnchors, anchors.memoryAttributionAnchors);
+    const severed = _severedFlagsOf(messages, anchors);
+    for (const [index, message] of messages.entries()) {
+        _pushMarkersAt(rows, anchors, message.id, "before");
+        _pushMessageRows(rows, message, results, {
+            streamingMessageId: running ? lastAssistantTextId : null,
+            streamingReasoningId: running ? lastMessageId : null,
+            running,
+            superseded: severed[index],
+            errors: anchors.toolErrorAnchors,
+            refusals: anchors.toolRefusalAnchors,
+            cancels: anchors.toolCancelAnchors,
+            offloads: anchors.toolOffloadAnchors,
+            decisions: anchors.toolDecisionAnchors ?? EMPTY_TOOL_DECISION_ANCHORS,
+            denials: anchors.toolDenialAnchors ?? EMPTY_TOOL_DENIAL_ANCHORS,
+            displays: anchors.toolCallDisplayAnchors,
+            schemas: anchors.toolSchemaAnchors,
+            timings: anchors.blockTimingAnchors,
+            turnMeta: metaByMessageId,
+            memoryFooters,
+        });
+        _pushMarkersAt(rows, anchors, message.id, "after");
+    }
+    return withSubagentGroups(rows, _asDispatchCall, (row) => row.key);
+}
+export function withPendingUserEcho(rows, echo) {
+    if (echo === null ||
+        rows.some((row) => row.kind === "user" && row.key === echo.messageId)) {
+        return rows;
+    }
+    return [
+        ...rows,
+        {
+            kind: "user",
+            key: echo.messageId,
+            text: echo.text,
+            attachments: echo.attachments,
+            optimistic: true,
+        },
+    ];
+}
+export function trailingRowIsStreaming(rows) {
+    const last = rows.at(-1);
+    if (last === undefined) {
+        return false;
+    }
+    return ((last.kind === "assistant-text" || last.kind === "reasoning") &&
+        last.streaming);
+}
+function _pushMessageRows(rows, message, results, context) {
+    if (message.role === "user") {
+        const meta = context.turnMeta.get(message.id);
+        const attachments = meta?.attachments ?? context.sideAttachments?.get(message.id) ?? [];
+        if (typeof message.content === "string" &&
+            (message.content !== "" || attachments.length > 0)) {
+            rows.push({
+                kind: "user",
+                key: message.id,
+                text: message.content,
+                attachments,
+                ...(meta !== undefined ? { createdAt: meta.createdAt } : {}),
+            });
+        }
+        return;
+    }
+    if (message.role === "reasoning") {
+        if (message.content !== "") {
+            rows.push({
+                kind: "reasoning",
+                key: message.id,
+                text: message.content,
+                streaming: message.id === context.streamingReasoningId,
+                timing: context.timings.get(message.id),
+            });
+        }
+        return;
+    }
+    if (message.role !== "assistant") {
+        return;
+    }
+    if (typeof message.content === "string" && message.content !== "") {
+        const memoryUpdates = context.memoryFooters.get(message.id);
+        rows.push({
+            kind: "assistant-text",
+            key: message.id,
+            text: message.content,
+            streaming: message.id === context.streamingMessageId,
+            ...(memoryUpdates !== undefined ? { memoryUpdates } : {}),
+        });
+    }
+    for (const toolCall of message.toolCalls ?? []) {
+        const result = results.get(toolCall.id);
+        const recordedError = context.errors.get(toolCall.id);
+        const recordedRefusal = context.refusals.get(toolCall.id);
+        const state = _toolStateOf(result, recordedError !== undefined, context.denials.has(toolCall.id), context.cancels.has(toolCall.id), recordedRefusal !== undefined, context.superseded, context.running);
+        rows.push({
+            kind: "tool-call",
+            key: `${message.id}:${toolCall.id}`,
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            state,
+            argsText: toolCall.function.arguments,
+            result,
+            offloaded: context.offloads.has(toolCall.id),
+            errorText: errorTextOf(recordedError, result),
+            ...(state === "refused" ? { refusalText: recordedRefusal } : {}),
+            display: context.displays.get(toolCall.id),
+            schemas: context.schemas.get(toolCall.id),
+            timing: context.timings.get(toolCall.id),
+            ...(context.decisions.has(toolCall.id) ? { decisionBearing: true } : {}),
+        });
+    }
+}
+function _asDispatchCall(row) {
+    if (row.kind !== "tool-call" ||
+        row.toolName !== DISPATCH_SUBAGENT_TOOL_NAME ||
+        row.state === "refused" ||
+        row.state === "denied") {
+        return null;
+    }
+    return {
+        toolCallId: row.toolCallId,
+        settled: row.state === "output-available" ||
+            row.state === "output-error" ||
+            row.state === "cancelled" ||
+            row.state === "superseded",
+        failed: row.state === "output-error",
+        cancelled: row.state === "cancelled" || row.state === "superseded",
+        result: row.result,
+        errorText: row.errorText,
+        argsText: row.argsText,
+    };
+}
+export function errorTextOf(recordedError, result) {
+    if (recordedError === undefined) {
+        return undefined;
+    }
+    return recordedError !== "" ? recordedError : result;
+}
+function _toolResultsOf(messages) {
+    const results = new Map();
+    for (const message of messages) {
+        if (message.role === "tool" && typeof message.content === "string") {
+            results.set(message.toolCallId, message.content);
+        }
+    }
+    return results;
+}
+function _toolStateOf(result, errored, denied, cancelled, refused, superseded, running) {
+    if (errored) {
+        return "output-error";
+    }
+    if (denied) {
+        return "denied";
+    }
+    if (cancelled) {
+        return "cancelled";
+    }
+    if (refused) {
+        return "refused";
+    }
+    if (result !== undefined) {
+        return "output-available";
+    }
+    if (superseded) {
+        return "superseded";
+    }
+    return running ? "input-available" : "input-streaming";
+}
+function _severedFlagsOf(messages, anchors) {
+    const flags = messages.map(() => false);
+    let turnStart = 0;
+    for (const [index, message] of messages.entries()) {
+        if (message.role === "user") {
+            turnStart = index;
+            continue;
+        }
+        if (anchors.subagentDeliveryAnchors.has(message.id)) {
+            turnStart = index;
+        }
+        if (anchors.resumeAnchors.has(message.id)) {
+            for (let severed = turnStart; severed < index; severed += 1) {
+                flags[severed] = true;
+            }
+        }
+    }
+    return flags;
+}
+function _pushMarkersAt(rows, anchors, messageId, position) {
+    if (position === "before") {
+        const delivered = anchors.subagentDeliveryAnchors.get(messageId);
+        if (delivered !== undefined && delivered.length > 0) {
+            rows.push({
+                kind: "subagent-delivery",
+                key: `${messageId}:delivery`,
+                results: delivered,
+            });
+        }
+    }
+    const failed = anchors.turnFailedAnchors.get(messageId)?.[position];
+    if (failed !== undefined && failed.length > 0) {
+        rows.push({
+            kind: "turn-failed-receipts",
+            key: `${messageId}:${position}:failed`,
+            receipts: failed,
+        });
+    }
+}
+export const EMPTY_MARKER_BOUNDARIES = {
+    before: new Set(),
+    after: new Set(),
+};
+export function transcriptBlocksOf(messages, anchors, running, metaByMessageId = NO_TURN_META, options = {}) {
+    const deduped = _dedupedById(messages);
+    const results = _toolResultsOf(deduped);
+    const lastAssistantTextId = newestAssistantProseIdOf(deduped);
+    const lastMessageId = deduped.at(-1)?.id ?? null;
+    const memoryFooters = memoryFootersOf(anchors.memoryProvenanceAnchors, anchors.memoryAttributionAnchors);
+    const severed = _severedFlagsOf(deduped, anchors);
+    const blocks = deduped.map((message, index) => {
+        const rows = [];
+        _pushMarkersAt(rows, anchors, message.id, "before");
+        _pushMessageRows(rows, message, results, {
+            streamingMessageId: running ? lastAssistantTextId : null,
+            streamingReasoningId: running ? lastMessageId : null,
+            running,
+            superseded: severed[index],
+            errors: anchors.toolErrorAnchors,
+            refusals: anchors.toolRefusalAnchors,
+            cancels: anchors.toolCancelAnchors,
+            offloads: anchors.toolOffloadAnchors,
+            decisions: anchors.toolDecisionAnchors ?? EMPTY_TOOL_DECISION_ANCHORS,
+            denials: anchors.toolDenialAnchors ?? EMPTY_TOOL_DENIAL_ANCHORS,
+            displays: anchors.toolCallDisplayAnchors,
+            schemas: anchors.toolSchemaAnchors,
+            timings: anchors.blockTimingAnchors,
+            turnMeta: metaByMessageId,
+            memoryFooters,
+            sideAttachments: options.attachmentsByMessageId,
+        });
+        _pushMarkersAt(rows, anchors, message.id, "after");
+        return {
+            messageId: message.id,
+            rows: withSubagentGroups(rows, _asDispatchCall, (row) => row.key),
+        };
+    });
+    return _withCrossBlockGroups(blocks, options.markerBoundaries ?? EMPTY_MARKER_BOUNDARIES);
+}
+function _dedupedById(messages) {
+    const byId = new Map();
+    for (const message of messages) {
+        const existing = byId.get(message.id);
+        if (existing !== undefined &&
+            message.role === "assistant" &&
+            existing.role === "assistant") {
+            byId.set(message.id, {
+                ...existing,
+                ...message,
+                content: message.content || existing.content,
+                toolCalls: message.toolCalls ?? existing.toolCalls,
+            });
+        }
+        else {
+            byId.set(message.id, message);
+        }
+    }
+    return [...byId.values()];
+}
+function _withCrossBlockGroups(blocks, markerBoundaries) {
+    let standing = null;
+    return blocks.map((block) => {
+        if (markerBoundaries.before.has(block.messageId)) {
+            standing = null;
+        }
+        const rows = [];
+        for (const row of block.rows) {
+            if (row.kind !== "subagent-group") {
+                standing = null;
+                rows.push(row);
+                continue;
+            }
+            if (standing === null) {
+                standing = { ...row, entries: [...row.entries] };
+                rows.push(standing);
+                continue;
+            }
+            standing.entries.push(...row.entries);
+        }
+        if (markerBoundaries.after.has(block.messageId)) {
+            standing = null;
+        }
+        return { messageId: block.messageId, rows };
+    });
+}

package/dist/core/turn-failed-anchors.d.ts

@@ -0,0 +1,8 @@
+import { receiptOf, wellFormedReceiptAnchorsOf, withReceiptAnchored, type AnchoredReceipts } from "./receipt-anchors.js";
+import type { AgentSubscriber } from "@ag-ui/client";
+export type AnchoredTurnFailReceipts = AnchoredReceipts;
+export declare const EMPTY_TURN_FAILED_ANCHORS: ReadonlyMap<string, AnchoredTurnFailReceipts>;
+export declare const turnFailedReceiptOf: typeof receiptOf;
+export declare const withTurnFailedAnchored: typeof withReceiptAnchored;
+export declare const wellFormedFailAnchorsOf: typeof wellFormedReceiptAnchorsOf;
+export declare function turnFailedMarkerRecorder(onReceiptAnchored: (failedRunId: string, messageId: string, position: keyof AnchoredTurnFailReceipts, receipts: string[]) => void): AgentSubscriber;

package/dist/core/turn-failed-anchors.js

@@ -0,0 +1,9 @@
+import { receiptMarkerRecorder, receiptOf, wellFormedReceiptAnchorsOf, withReceiptAnchored, } from "./receipt-anchors.js";
+import { TURN_FAILED_EVENT_NAME } from "../contract/events.js";
+export const EMPTY_TURN_FAILED_ANCHORS = new Map();
+export const turnFailedReceiptOf = receiptOf;
+export const withTurnFailedAnchored = withReceiptAnchored;
+export const wellFormedFailAnchorsOf = wellFormedReceiptAnchorsOf;
+export function turnFailedMarkerRecorder(onReceiptAnchored) {
+    return receiptMarkerRecorder(TURN_FAILED_EVENT_NAME, onReceiptAnchored);
+}

package/dist/core/turn-failure-copy.d.ts

@@ -0,0 +1,4 @@
+import type { ServingAssistantTurn } from "../contract/threads.js";
+import type { AnchoredTurnFailReceipts } from "./turn-failed-anchors.js";
+export declare function failureSentenceOf(turns: ServingAssistantTurn[]): string | null;
+export declare function bannerFailureSentenceOf(sentence: string | null, failedReceiptAnchors: ReadonlyMap<string, AnchoredTurnFailReceipts> | undefined): string | null;

package/dist/core/turn-failure-copy.js

@@ -0,0 +1,19 @@
+export function failureSentenceOf(turns) {
+    const newestTurn = turns.at(-1);
+    if (newestTurn?.status === "failed" && newestTurn.kind == null) {
+        return newestTurn.error ?? "The last answer didn't finish.";
+    }
+    return null;
+}
+export function bannerFailureSentenceOf(sentence, failedReceiptAnchors) {
+    if (sentence === null || failedReceiptAnchors === undefined) {
+        return sentence;
+    }
+    for (const anchored of failedReceiptAnchors.values()) {
+        if (anchored.before.includes(sentence) ||
+            anchored.after.includes(sentence)) {
+            return null;
+        }
+    }
+    return sentence;
+}

package/dist/core/turn-usage-anchors.d.ts

@@ -0,0 +1,16 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+export interface TurnUsage {
+    turnId: string;
+    finality: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+}
+export declare const EMPTY_TURN_USAGE_ANCHORS: ReadonlyMap<string, TurnUsage>;
+export declare function usageIsFinal(usage: TurnUsage): boolean;
+export declare function turnUsageAnchorOf(value: unknown): TurnUsage | null;
+export declare function withTurnUsageAnchored(previous: ReadonlyMap<string, TurnUsage>, usage: TurnUsage): ReadonlyMap<string, TurnUsage>;
+export declare function wellFormedTurnUsageAnchorsOf(stored: ReadonlyMap<string, TurnUsage>): ReadonlyMap<string, TurnUsage>;
+export declare function turnUsageRecorder(onUsageAnchored: (usage: TurnUsage) => void): AgentSubscriber;

package/dist/core/turn-usage-anchors.js

@@ -0,0 +1,100 @@
+import { TURN_USAGE_RECORDED_EVENT_NAME } from "../contract/events.js";
+const TOKEN_MAX_CHARS = 64;
+const FINAL_FINALITY = "final";
+export const EMPTY_TURN_USAGE_ANCHORS = new Map();
+export function usageIsFinal(usage) {
+    return usage.finality === FINAL_FINALITY;
+}
+export function turnUsageAnchorOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const { turn_id: turnId, finality, input_tokens: inputTokens, output_tokens: outputTokens, cache_read_tokens: cacheReadTokens, cache_write_tokens: cacheWriteTokens, total_tokens: totalTokens, } = value;
+    if (typeof turnId !== "string" || turnId === "") {
+        return null;
+    }
+    const resolvedFinality = finality === undefined ? FINAL_FINALITY : finality;
+    if (typeof resolvedFinality !== "string" || resolvedFinality.trim() === "") {
+        return null;
+    }
+    if (!_isCount(inputTokens) ||
+        !_isCount(outputTokens) ||
+        !_isCount(cacheReadTokens) ||
+        !_isCount(cacheWriteTokens) ||
+        !_isCount(totalTokens)) {
+        return null;
+    }
+    return {
+        turnId,
+        finality: resolvedFinality.slice(0, TOKEN_MAX_CHARS),
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        totalTokens,
+    };
+}
+export function withTurnUsageAnchored(previous, usage) {
+    const existing = previous.get(usage.turnId);
+    if (existing !== undefined) {
+        if (usageIsFinal(existing) && !usageIsFinal(usage)) {
+            return previous;
+        }
+        if (_sameUsage(existing, usage)) {
+            return previous;
+        }
+    }
+    const next = new Map(previous);
+    next.set(usage.turnId, usage);
+    return next;
+}
+export function wellFormedTurnUsageAnchorsOf(stored) {
+    const seeded = new Map();
+    const entries = stored;
+    for (const [turnId, usage] of entries) {
+        if (typeof turnId !== "string" || !_isWellFormedUsage(usage)) {
+            continue;
+        }
+        seeded.set(turnId, usage);
+    }
+    return seeded;
+}
+export function turnUsageRecorder(onUsageAnchored) {
+    return {
+        onCustomEvent({ event }) {
+            if (event.name !== TURN_USAGE_RECORDED_EVENT_NAME) {
+                return;
+            }
+            const usage = turnUsageAnchorOf(event.value);
+            if (usage !== null) {
+                onUsageAnchored(usage);
+            }
+        },
+    };
+}
+function _isCount(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function _sameUsage(a, b) {
+    return (a.finality === b.finality &&
+        a.inputTokens === b.inputTokens &&
+        a.outputTokens === b.outputTokens &&
+        a.cacheReadTokens === b.cacheReadTokens &&
+        a.cacheWriteTokens === b.cacheWriteTokens &&
+        a.totalTokens === b.totalTokens);
+}
+function _isWellFormedUsage(usage) {
+    if (typeof usage !== "object" || usage === null) {
+        return false;
+    }
+    const { turnId, finality, inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens, } = usage;
+    return (typeof turnId === "string" &&
+        turnId !== "" &&
+        typeof finality === "string" &&
+        finality !== "" &&
+        _isCount(inputTokens) &&
+        _isCount(outputTokens) &&
+        _isCount(cacheReadTokens) &&
+        _isCount(cacheWriteTokens) &&
+        _isCount(totalTokens));
+}

package/dist/core/turns-backfill.d.ts

@@ -0,0 +1,14 @@
+export declare const TURNS_WINDOW = 200;
+export interface TurnsBackfillCursor {
+    before_created_at: string;
+    before_id: string;
+    limit: number;
+}
+export declare function backfilledTurnsOf<T extends {
+    id: string;
+    created_at: string;
+}>(newestWindow: readonly T[], fetchPage: (cursor: TurnsBackfillCursor) => Promise<{
+    turns: T[];
+}>, opts?: {
+    isStale?: () => boolean;
+}): Promise<T[] | null>;