@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/tool-usage-projection.js

@@ -0,0 +1,1038 @@
+/**
+ * The `toolModeUsage` session projection (Tool Insights plan §3.1).
+ *
+ * A pure fold over DSH session events. The projection STATE is the host-only detail
+ * (exact per-tool matrix, 16-bucket duration histogram, error codes); the projection
+ * WIRE is the compact value that rides every `session.list` row. Splitting them this
+ * way keeps the session list small while the report channel can still answer exact
+ * range questions from the detail.
+ *
+ * Truthfulness rules the fold enforces:
+ *
+ * - A call is counted when it is DISPATCHED (`tool/call`, `tool/ptc-dispatch-start`),
+ *   and its duration is added only when a result settles it. A call whose result never
+ *   lands is `unsettled` — never a fabricated success, and never in a percentile.
+ * - `callId` is provider-minted, so pairing uses `Object.hasOwn`: a result naming
+ *   `constructor`/`toString` must read as unmatched, not as an inherited function.
+ * - Model attribution comes from the step's assistant message, then the request-header
+ *   route in force, then the explicit `unattributed` bucket. Code Mode sub-calls
+ *   inherit the parent program's model.
+ * - Every bound is explicit and loses information LOUDLY (`unsettled`, `toolsTruncated`
+ *   / `modelsTruncated`) rather than silently.
+ * - All state is plain JSON: the projection cache persists it.
+ *
+ * @module @try-works/dsh-tool-mode/tool-usage-projection
+ */
+import { staticToolOwner } from "./tool-sources.js";
+/** The projection key the client reads as `projectionValues.toolModeUsage`. */
+export const TOOL_USAGE_KEY = 'toolModeUsage';
+/** The persisted-state version; a stale cache row is re-folded instead of trusted. */
+export const TOOL_USAGE_STATE_VERSION = 1;
+/** The explicit bucket for calls with no readable model. */
+export const UNATTRIBUTED_MODEL = 'unattributed';
+/** The explicit per-tool bucket once the distinct-tool bound is reached. */
+export const TOOLS_OVERFLOW = '(overflow)';
+/**
+ * Duration histogram upper edges, in milliseconds (16 buckets).
+ *
+ * Log-scale because tool latencies span four orders of magnitude; the last bucket is
+ * open-ended. Percentiles are derived from this histogram, while `maxMs` stays exact.
+ */
+export const DURATION_BUCKETS_MS = Object.freeze([
+    10, 25, 50, 100, 200, 300, 500, 750, 1_000, 2_000, 3_000, 5_000, 10_000, 30_000, 60_000, 600_000,
+]);
+/** Hard bounds. The wire caps and the fold caps come from one table. */
+export const TOOL_USAGE_CAPS = Object.freeze({
+    /** In-flight (call dispatched, result not yet seen) records retained. */
+    pending: 100,
+    /** Recent calls retained in the detail state; the wire carries {@link TOOL_USAGE_CAPS.wireRecent}. */
+    recent: 200,
+    /** Recent calls the compact wire carries. */
+    wireRecent: 20,
+    /** Distinct tool performance rows per session. */
+    tools: 100,
+    /** Distinct models per session. */
+    models: 20,
+    /** Distinct tool names tracked per model. */
+    modelTools: 100,
+    /** Retained local-time days. */
+    days: 60,
+    /** Duration buckets per tool. */
+    buckets: 16,
+    /** Top tools the compact wire carries. */
+    topTools: 5,
+});
+/** A fresh empty state. */
+export function initToolUsageState() {
+    return {
+        stateVersion: TOOL_USAGE_STATE_VERSION,
+        calls: 0,
+        errors: 0,
+        unsettled: 0,
+        toolMs: 0,
+        uniqueTools: 0,
+        byTool: {},
+        byModel: {},
+        byOwner: {},
+        byDay: {},
+        byErrorCode: {},
+        recent: [],
+        pending: {},
+        route: null,
+        stepModel: null,
+        lastTurn: null,
+        toolsTruncated: 0,
+        modelsTruncated: 0,
+    };
+}
+/** The host-local `YYYY-MM-DD` day key for one timestamp (shared with the report). */
+export function toolUsageDayKey(time) {
+    return dayKeyOf(time);
+}
+/** One local-time day key (`YYYY-MM-DD`). */
+function dayKeyOf(time) {
+    const date = new Date(time);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** The histogram bucket for one settled duration. */
+function bucketOf(durationMs) {
+    for (let index = 0; index < DURATION_BUCKETS_MS.length - 1; index += 1) {
+        const edge = DURATION_BUCKETS_MS[index];
+        if (edge !== undefined && durationMs <= edge)
+            return index;
+    }
+    return DURATION_BUCKETS_MS.length - 1;
+}
+/** Serialized byte length, with `-1` for an unserializable value (never `0`). */
+function byteLengthOf(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? 0 : Buffer.byteLength(serialized, 'utf8');
+    }
+    catch {
+        return -1;
+    }
+}
+/** The model that emitted a call in `turn`/`step`, never a guess. */
+function modelFor(state, turn, step) {
+    if (state.stepModel !== null && state.stepModel.turn === turn && state.stepModel.step === step) {
+        return state.stepModel.model;
+    }
+    return state.route?.model ?? UNATTRIBUTED_MODEL;
+}
+/** The model for a Code Mode sub-call: the parent program's step model, then the route. */
+function codeModelFor(state) {
+    return state.stepModel?.model ?? state.route?.model ?? UNATTRIBUTED_MODEL;
+}
+/** A copy of `state` with the oldest tool/day keys pruned past the day bound. */
+function pruneDays(state) {
+    const days = Object.keys(state.byDay).sort();
+    if (days.length <= TOOL_USAGE_CAPS.days)
+        return state;
+    const keep = new Set(days.slice(days.length - TOOL_USAGE_CAPS.days));
+    const byDay = {};
+    for (const [day, usage] of Object.entries(state.byDay))
+        if (keep.has(day))
+            byDay[day] = usage;
+    const byTool = {};
+    for (const [name, bucket] of Object.entries(state.byTool)) {
+        const toolDays = {};
+        for (const [day, count] of Object.entries(bucket.byDay))
+            if (keep.has(day))
+                toolDays[day] = count;
+        byTool[name] = { ...bucket, byDay: toolDays };
+    }
+    const byModel = {};
+    for (const [model, usage] of Object.entries(state.byModel)) {
+        const modelDays = {};
+        for (const [day, count] of Object.entries(usage.byDay))
+            if (keep.has(day))
+                modelDays[day] = count;
+        byModel[model] = { ...usage, byDay: modelDays };
+    }
+    const byOwner = {};
+    for (const [owner, usage] of Object.entries(state.byOwner)) {
+        const ownerDays = {};
+        for (const [day, count] of Object.entries(usage.byDay))
+            if (keep.has(day))
+                ownerDays[day] = count;
+        byOwner[owner] = { ...usage, byDay: ownerDays };
+    }
+    return { ...state, byDay, byTool, byModel, byOwner };
+}
+/** A copy of `state` with one tool/day counter incremented. */
+function bumpToolDay(bucket, day, calls, errors, ms, unsettled, codeCalls) {
+    const current = bucket.byDay[day] ?? { calls: 0, errors: 0, ms: 0, maxMs: 0, unsettled: 0, codeCalls: 0 };
+    return {
+        ...bucket,
+        byDay: {
+            ...bucket.byDay,
+            [day]: {
+                calls: current.calls + calls,
+                errors: current.errors + errors,
+                ms: current.ms + ms,
+                maxMs: Math.max(current.maxMs, ms),
+                unsettled: current.unsettled + unsettled,
+                codeCalls: current.codeCalls + codeCalls,
+            },
+        },
+    };
+}
+/** A copy of `state` with one day counter incremented. */
+function bumpDay(state, day, calls, errors, ms, unsettled, code) {
+    const current = state.byDay[day] ?? { calls: 0, errors: 0, ms: 0, unsettled: 0, byCode: {} };
+    return {
+        ...state.byDay,
+        [day]: {
+            calls: current.calls + calls,
+            errors: current.errors + errors,
+            ms: current.ms + ms,
+            unsettled: current.unsettled + unsettled,
+            byCode: code === null ? current.byCode : { ...current.byCode, [code]: (current.byCode[code] ?? 0) + 1 },
+        },
+    };
+}
+/** A copy of one model's day counter with the given increments applied. */
+function bumpModelDay(usage, day, calls, errors, ms) {
+    const current = usage.byDay[day] ?? { calls: 0, errors: 0, ms: 0, maxMs: 0 };
+    return { ...usage.byDay, [day]: { calls: current.calls + calls, errors: current.errors + errors, ms: current.ms + ms, maxMs: Math.max(current.maxMs, ms) } };
+}
+/** A copy of one owner's day counter with the given increments applied. */
+function bumpOwnerDay(usage, day, calls, errors, ms) {
+    const current = usage?.byDay[day] ?? { calls: 0, errors: 0, ms: 0 };
+    return { ...usage?.byDay, [day]: { calls: current.calls + calls, errors: current.errors + errors, ms: current.ms + ms } };
+}
+/**
+ * The tool bucket for a name, honouring the distinct-tool bound.
+ *
+ * Past the bound the call is still counted in the totals but no 101st performance row
+ * is invented; `toolsTruncated` records how many calls lost their per-tool detail.
+ * @param state - the current state.
+ * @param name - the tool name.
+ * @returns the effective row key (`''` when untracked), its bucket and the new state.
+ */
+function toolBucket(state, name) {
+    const existing = state.byTool[name];
+    if (existing !== undefined)
+        return { key: name, bucket: existing, state };
+    if (Object.keys(state.byTool).length >= TOOL_USAGE_CAPS.tools) {
+        return {
+            key: '',
+            bucket: emptyToolBucket(),
+            state: { ...state, toolsTruncated: state.toolsTruncated + 1 },
+        };
+    }
+    return { key: name, bucket: emptyToolBucket(), state: { ...state, uniqueTools: state.uniqueTools + 1 } };
+}
+/** A copy of a histogram with one settled duration added. */
+function addToHistogram(histogram, ms) {
+    const next = [...histogram];
+    const index = bucketOf(ms);
+    next[index] = (next[index] ?? 0) + 1;
+    return next;
+}
+/** A zeroed 16-bucket histogram. */
+function emptyHistogram() {
+    return Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0);
+}
+/** A zeroed tool bucket. */
+function emptyToolBucket() {
+    return {
+        calls: 0,
+        errors: 0,
+        unsettled: 0,
+        codeCalls: 0,
+        directCalls: 0,
+        totalMs: 0,
+        maxMs: 0,
+        argsBytes: 0,
+        resultBytes: 0,
+        firstUsed: null,
+        lastUsed: null,
+        histogram: Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0),
+        byDay: {},
+    };
+}
+/** The model bucket for a name, honouring the distinct-model bound. */
+function modelBucket(state, model) {
+    const existing = state.byModel[model];
+    if (existing !== undefined)
+        return { bucket: existing, state };
+    if (Object.keys(state.byModel).length >= TOOL_USAGE_CAPS.models) {
+        // Past the bound, calls stay counted in the totals but attribution is explicit.
+        const unattributed = state.byModel[UNATTRIBUTED_MODEL] ?? { calls: 0, errors: 0, ms: 0, tools: [], histogram: emptyHistogram(), byDay: {} };
+        return {
+            bucket: unattributed,
+            state: {
+                ...state,
+                byModel: { ...state.byModel, [UNATTRIBUTED_MODEL]: unattributed },
+                modelsTruncated: state.modelsTruncated + 1,
+            },
+        };
+    }
+    return { bucket: { calls: 0, errors: 0, ms: 0, tools: [], histogram: emptyHistogram(), byDay: {} }, state };
+}
+/** Add a tool name to a model's bounded distinct-tool list. */
+function modelTools(usage, name) {
+    if (usage.tools.includes(name))
+        return usage.tools;
+    if (usage.tools.length >= TOOL_USAGE_CAPS.modelTools)
+        return usage.tools;
+    return [...usage.tools, name];
+}
+/** Append one recent entry, evicting the oldest past the bound. */
+function appendRecent(state, entry) {
+    const recent = [...state.recent, entry];
+    return recent.length > TOOL_USAGE_CAPS.recent ? recent.slice(recent.length - TOOL_USAGE_CAPS.recent) : recent;
+}
+/** Patch a recent entry when its call settles or becomes unsettled. */
+function patchRecent(recent, callId, kind, patch) {
+    for (let index = recent.length - 1; index >= 0; index -= 1) {
+        const entry = recent[index];
+        if (entry === undefined || entry.callId !== callId || entry.kind !== kind)
+            continue;
+        const next = [...recent];
+        next[index] = { ...entry, ...patch };
+        return next;
+    }
+    return [...recent];
+}
+/** Drop one pending call, counting it unsettled (the result never landed). */
+function dropUnsettled(state, key) {
+    const pending = state.pending[key];
+    if (pending === undefined)
+        return state;
+    const rest = { ...state.pending };
+    delete rest[key];
+    const day = dayKeyOf(pending.time);
+    const bucket = state.byTool[pending.name];
+    const byTool = bucket === undefined
+        ? state.byTool
+        : { ...state.byTool, [pending.name]: { ...bumpToolDay(bucket, day, 0, 0, 0, 1, 0), unsettled: bucket.unsettled + 1 } };
+    return {
+        ...state,
+        pending: rest,
+        byTool,
+        byDay: bumpDay(state, day, 0, 0, 0, 1, null),
+        unsettled: state.unsettled + 1,
+    };
+}
+/** Evict the oldest pending call when the bound is reached. */
+function evictOldestPending(state) {
+    let oldestKey;
+    let oldestTime = Number.POSITIVE_INFINITY;
+    for (const [key, pending] of Object.entries(state.pending)) {
+        if (pending.time < oldestTime) {
+            oldestTime = pending.time;
+            oldestKey = key;
+        }
+    }
+    return oldestKey === undefined ? state : dropUnsettled(state, oldestKey);
+}
+/** Fold one event into the state. Uninteresting events return the same reference. */
+export function foldToolUsageEvent(state, event) {
+    switch (event.type) {
+        case 'request/header': {
+            const provider = event.data.header.config.provider;
+            const model = event.data.header.config.model;
+            if (typeof model !== 'string' || model.length === 0)
+                return state;
+            return { ...state, route: { provider: typeof provider === 'string' ? provider : '', model } };
+        }
+        case 'assistant/message': {
+            const model = event.data.message.source.model;
+            if (typeof model !== 'string' || model.length === 0)
+                return state;
+            return { ...state, stepModel: { turn: event.data.turn, step: event.data.step, model } };
+        }
+        case 'tool/call': {
+            const day = dayKeyOf(event.time);
+            const model = modelFor(state, event.data.turn, event.data.step);
+            const owner = staticToolOwner(event.data.name).owner;
+            const { key: toolKey, bucket, state: withBucket } = toolBucket(state, event.data.name);
+            let next = {
+                ...withBucket,
+                calls: withBucket.calls + 1,
+                byDay: bumpDay(withBucket, day, 1, 0, 0, 0, null),
+                byOwner: { ...withBucket.byOwner, [owner]: bumpOwner(withBucket.byOwner[owner], day, 1, 0, 0) },
+                byTool: toolKey === '' ? withBucket.byTool : {
+                    ...withBucket.byTool,
+                    [toolKey]: bumpToolDay({
+                        ...bucket,
+                        calls: bucket.calls + 1,
+                        directCalls: bucket.directCalls + 1,
+                        argsBytes: bucket.argsBytes + Buffer.byteLength(event.data.arguments, 'utf8'),
+                        firstUsed: bucket.firstUsed === null ? event.time : Math.min(bucket.firstUsed, event.time),
+                        lastUsed: bucket.lastUsed === null ? event.time : Math.max(bucket.lastUsed, event.time),
+                    }, day, 1, 0, 0, 0, 0),
+                },
+            };
+            next = pruneDays(next);
+            const { bucket: modelUsage, state: withModel } = modelBucket(next, model);
+            next = {
+                ...withModel,
+                byModel: {
+                    ...withModel.byModel,
+                    [model]: {
+                        ...modelUsage,
+                        calls: modelUsage.calls + 1,
+                        tools: modelTools(modelUsage, event.data.name),
+                        byDay: bumpModelDay(modelUsage, day, 1, 0, 0),
+                    },
+                },
+            };
+            if (Object.keys(next.pending).length >= TOOL_USAGE_CAPS.pending)
+                next = evictOldestPending(next);
+            next = {
+                ...next,
+                pending: {
+                    ...next.pending,
+                    [event.data.callId]: { name: event.data.name, time: event.time, kind: 'direct', model },
+                },
+            };
+            return { ...next, recent: appendRecent(next, {
+                    time: event.time,
+                    name: event.data.name,
+                    model,
+                    kind: 'direct',
+                    callId: event.data.callId,
+                    ms: null,
+                    ok: null,
+                    code: null,
+                }) };
+        }
+        case 'tool/result': {
+            const callId = event.data.message.source.callId;
+            if (!Object.hasOwn(state.pending, callId))
+                return state;
+            const pending = state.pending[callId];
+            if (pending === undefined)
+                return state;
+            const ms = Math.max(0, event.time - pending.time);
+            const isError = event.data.message.isError === true || event.data.error !== undefined;
+            const code = typeof event.data.error?.code === 'string' ? event.data.error.code : null;
+            const day = dayKeyOf(pending.time);
+            const owner = staticToolOwner(pending.name).owner;
+            // A call past the distinct-tool bound has no per-tool row; its totals below are
+            // still updated, but no 101st row is invented.
+            const bucket = state.byTool[pending.name];
+            const errors = isError ? 1 : 0;
+            const histogram = bucket === undefined ? undefined : [...bucket.histogram];
+            if (histogram !== undefined)
+                histogram[bucketOf(ms)] = (histogram[bucketOf(ms)] ?? 0) + 1;
+            const pendingRest = { ...state.pending };
+            delete pendingRest[callId];
+            const modelUsage = state.byModel[pending.model];
+            return {
+                ...state,
+                errors: state.errors + errors,
+                toolMs: state.toolMs + ms,
+                byErrorCode: code === null ? state.byErrorCode : { ...state.byErrorCode, [code]: (state.byErrorCode[code] ?? 0) + 1 },
+                byDay: bumpDay(state, day, 0, errors, ms, 0, code),
+                byOwner: { ...state.byOwner, [owner]: bumpOwner(state.byOwner[owner], day, 0, errors, ms) },
+                byModel: modelUsage === undefined
+                    ? state.byModel
+                    : {
+                        ...state.byModel,
+                        [pending.model]: {
+                            ...modelUsage,
+                            errors: modelUsage.errors + errors,
+                            ms: modelUsage.ms + ms,
+                            histogram: addToHistogram(modelUsage.histogram, ms),
+                            byDay: bumpModelDay(modelUsage, day, 0, errors, ms),
+                        },
+                    },
+                byTool: bucket === undefined ? state.byTool : {
+                    ...state.byTool,
+                    [pending.name]: bumpToolDay({
+                        ...bucket,
+                        errors: bucket.errors + errors,
+                        totalMs: bucket.totalMs + ms,
+                        maxMs: Math.max(bucket.maxMs, ms),
+                        resultBytes: bucket.resultBytes + (event.data.message.content === undefined ? 0 : byteLengthOf(event.data.message.content)),
+                        histogram: histogram ?? bucket.histogram,
+                    }, day, 0, errors, ms, 0, 0),
+                },
+                pending: pendingRest,
+                recent: patchRecent(state.recent, callId, 'direct', { ms, ok: !isError, code }),
+            };
+        }
+        case 'tool/ptc-dispatch-start': {
+            const day = dayKeyOf(event.time);
+            const model = codeModelFor(state);
+            const owner = staticToolOwner(event.data.name).owner;
+            const { key: toolKey, bucket, state: withBucket } = toolBucket(state, event.data.name);
+            let next = {
+                ...withBucket,
+                calls: withBucket.calls + 1,
+                byDay: bumpDay(withBucket, day, 1, 0, 0, 0, null),
+                byOwner: { ...withBucket.byOwner, [owner]: bumpOwner(withBucket.byOwner[owner], day, 1, 0, 0) },
+                byTool: toolKey === '' ? withBucket.byTool : {
+                    ...withBucket.byTool,
+                    [toolKey]: bumpToolDay({
+                        ...bucket,
+                        calls: bucket.calls + 1,
+                        codeCalls: bucket.codeCalls + 1,
+                        argsBytes: bucket.argsBytes + byteLengthOf(event.data.arguments),
+                        firstUsed: bucket.firstUsed === null ? event.time : Math.min(bucket.firstUsed, event.time),
+                        lastUsed: bucket.lastUsed === null ? event.time : Math.max(bucket.lastUsed, event.time),
+                    }, day, 1, 0, 0, 0, 1),
+                },
+            };
+            next = pruneDays(next);
+            const { bucket: modelUsage, state: withModel } = modelBucket(next, model);
+            next = {
+                ...withModel,
+                byModel: {
+                    ...withModel.byModel,
+                    [model]: {
+                        ...modelUsage,
+                        calls: modelUsage.calls + 1,
+                        tools: modelTools(modelUsage, event.data.name),
+                        byDay: bumpModelDay(modelUsage, day, 1, 0, 0),
+                    },
+                },
+            };
+            const key = `code:${event.data.subCallId}`;
+            if (Object.keys(next.pending).length >= TOOL_USAGE_CAPS.pending)
+                next = evictOldestPending(next);
+            next = {
+                ...next,
+                pending: {
+                    ...next.pending,
+                    [key]: {
+                        name: event.data.name,
+                        time: event.time,
+                        kind: 'code',
+                        model,
+                        parentCallId: event.data.parentCallId,
+                        rootCallId: event.data.rootCallId,
+                    },
+                },
+            };
+            return {
+                ...next,
+                recent: appendRecent(next, {
+                    time: event.time,
+                    name: event.data.name,
+                    model,
+                    kind: 'code',
+                    callId: event.data.subCallId,
+                    parentCallId: event.data.parentCallId,
+                    rootCallId: event.data.rootCallId,
+                    ms: null,
+                    ok: null,
+                    code: null,
+                }),
+            };
+        }
+        case 'tool/ptc-dispatch': {
+            const key = `code:${event.data.subCallId}`;
+            if (!Object.hasOwn(state.pending, key))
+                return state;
+            const pending = state.pending[key];
+            if (pending === undefined)
+                return state;
+            const ms = Math.max(0, event.time - pending.time);
+            const isError = event.data.isError === true;
+            const code = typeof event.data.error?.code === 'string' ? event.data.error.code : null;
+            const day = dayKeyOf(pending.time);
+            const owner = staticToolOwner(pending.name).owner;
+            // Untracked past the tool bound: totals still settle, no 101st row is invented.
+            const bucket = state.byTool[pending.name];
+            const errors = isError ? 1 : 0;
+            const histogram = bucket === undefined ? undefined : [...bucket.histogram];
+            if (histogram !== undefined)
+                histogram[bucketOf(ms)] = (histogram[bucketOf(ms)] ?? 0) + 1;
+            const pendingRest = { ...state.pending };
+            delete pendingRest[key];
+            const modelUsage = state.byModel[pending.model];
+            return {
+                ...state,
+                errors: state.errors + errors,
+                toolMs: state.toolMs + ms,
+                byErrorCode: code === null ? state.byErrorCode : { ...state.byErrorCode, [code]: (state.byErrorCode[code] ?? 0) + 1 },
+                byDay: bumpDay(state, day, 0, errors, ms, 0, code),
+                byOwner: { ...state.byOwner, [owner]: bumpOwner(state.byOwner[owner], day, 0, errors, ms) },
+                byModel: modelUsage === undefined
+                    ? state.byModel
+                    : {
+                        ...state.byModel,
+                        [pending.model]: {
+                            ...modelUsage,
+                            errors: modelUsage.errors + errors,
+                            ms: modelUsage.ms + ms,
+                            histogram: addToHistogram(modelUsage.histogram, ms),
+                            byDay: bumpModelDay(modelUsage, day, 0, errors, ms),
+                        },
+                    },
+                byTool: bucket === undefined ? state.byTool : {
+                    ...state.byTool,
+                    [pending.name]: bumpToolDay({
+                        ...bucket,
+                        errors: bucket.errors + errors,
+                        totalMs: bucket.totalMs + ms,
+                        maxMs: Math.max(bucket.maxMs, ms),
+                        resultBytes: bucket.resultBytes + byteLengthOf(event.data.content),
+                        histogram: histogram ?? bucket.histogram,
+                    }, day, 0, errors, ms, 0, 0),
+                },
+                pending: pendingRest,
+                recent: patchRecent(state.recent, event.data.subCallId, 'code', { ms, ok: !isError, code }),
+            };
+        }
+        case 'turn/end': {
+            let next = state;
+            for (const key of Object.keys(next.pending))
+                next = dropUnsettled(next, key);
+            if (next.lastTurn === event.data.turn)
+                return next === state ? state : next;
+            return { ...next, lastTurn: event.data.turn };
+        }
+        default:
+            return state;
+    }
+}
+/** A copy of one owner counter with the given increments applied. */
+function bumpOwner(current, day, calls, errors, ms) {
+    return {
+        calls: (current?.calls ?? 0) + calls,
+        errors: (current?.errors ?? 0) + errors,
+        ms: (current?.ms ?? 0) + ms,
+        byDay: bumpOwnerDay(current, day, calls, errors, ms),
+    };
+}
+/** The compact wire value, derived only from the detail state. */
+export function toolUsageWire(state) {
+    const byModel = {};
+    for (const [model, usage] of Object.entries(state.byModel)) {
+        byModel[model] = { calls: usage.calls, errors: usage.errors, tools: usage.tools.length, ms: usage.ms };
+    }
+    const byOwner = {};
+    for (const [owner, usage] of Object.entries(state.byOwner)) {
+        byOwner[owner] = { calls: usage.calls, errors: usage.errors, ms: usage.ms };
+    }
+    const byDay = {};
+    for (const [day, usage] of Object.entries(state.byDay)) {
+        byDay[day] = { calls: usage.calls, errors: usage.errors, ms: usage.ms, unsettled: usage.unsettled };
+    }
+    const topTools = Object.entries(state.byTool)
+        .map(([name, bucket]) => ({ name, calls: bucket.calls, ms: bucket.totalMs }))
+        .sort((left, right) => right.calls - left.calls || left.name.localeCompare(right.name))
+        .slice(0, TOOL_USAGE_CAPS.topTools);
+    return {
+        stateVersion: TOOL_USAGE_STATE_VERSION,
+        calls: state.calls,
+        errors: state.errors,
+        unsettled: state.unsettled,
+        toolMs: state.toolMs,
+        uniqueTools: state.uniqueTools,
+        byOwner,
+        byModel,
+        byDay,
+        recent: state.recent.slice(-TOOL_USAGE_CAPS.wireRecent).map(entry => ({
+            time: entry.time,
+            name: entry.name,
+            model: entry.model,
+            ms: entry.ms,
+            ok: entry.ok,
+            kind: entry.kind,
+            code: entry.code,
+        })),
+        topTools,
+    };
+}
+/** One validation failure, named with the path that failed. */
+export class ToolUsageSchemaError extends Error {
+    name = 'ToolUsageSchemaError';
+}
+/** Describe a rejected value without echoing its content. */
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/** Refuse one value at a path. */
+function fail(path, expected, value) {
+    throw new ToolUsageSchemaError(`${path}: expected ${expected}, received ${describeValue(value)}`);
+}
+/** Validate an object with NO undeclared fields. */
+function objectAt(value, path, fields) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        fail(path, 'an object', value);
+    // SAFETY: the guard above proved a non-null, non-array object; the cast only restores
+    // the keyed view `Object.keys`/field reads require, and every field is validated below.
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!fields.includes(key))
+            fail(`${path}.${key}`, 'no such field', record[key]);
+    }
+    return record;
+}
+/** Validate a finite number (optionally an integer and/or non-negative). */
+function numberAt(value, path, options = {}) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        fail(path, 'a finite number', value);
+    if (options.int === true && !Number.isInteger(value))
+        fail(path, 'an integer', value);
+    if (options.min !== undefined && value < options.min)
+        fail(path, `a number >= ${options.min}`, value);
+    return value;
+}
+/** A non-negative integer counter. */
+function countAt(value, path) {
+    return numberAt(value, path, { int: true, min: 0 });
+}
+/** A number or null. */
+function nullableNumberAt(value, path) {
+    return value === null ? null : numberAt(value, path);
+}
+/** A string. */
+function stringAt(value, path) {
+    if (typeof value !== 'string')
+        fail(path, 'a string', value);
+    return value;
+}
+/** A string or null. */
+function nullableStringAt(value, path) {
+    return value === null ? null : stringAt(value, path);
+}
+/** A boolean. */
+function booleanAt(value, path) {
+    if (typeof value !== 'boolean')
+        fail(path, 'a boolean', value);
+    return value;
+}
+/** A boolean or null. */
+function nullableBooleanAt(value, path) {
+    return value === null ? null : booleanAt(value, path);
+}
+/** An array. */
+function arrayAt(value, path) {
+    if (!Array.isArray(value))
+        fail(path, 'an array', value);
+    return value;
+}
+/** The entries of a string-keyed record. */
+function recordAt(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        fail(path, 'a string-keyed record', value);
+    // SAFETY: the guard above proved a non-null, non-array object; `Object.entries` is the
+    // only operation, and every entry value is validated by the caller's value parser.
+    return Object.entries(value);
+}
+/** One call kind. */
+function kindAt(value, path) {
+    if (value !== 'direct' && value !== 'code')
+        fail(path, '"direct" or "code"', value);
+    return value;
+}
+const TOOL_DAY_FIELDS = ['calls', 'errors', 'ms', 'maxMs', 'unsettled', 'codeCalls'];
+const BUCKET_FIELDS = ['calls', 'errors', 'unsettled', 'codeCalls', 'directCalls', 'totalMs', 'maxMs', 'argsBytes', 'resultBytes', 'firstUsed', 'lastUsed', 'histogram', 'byDay'];
+const MODEL_FIELDS = ['calls', 'errors', 'ms', 'tools', 'histogram', 'byDay'];
+const OWNER_FIELDS = ['calls', 'errors', 'ms', 'byDay'];
+const DAY_FIELDS = ['calls', 'errors', 'ms', 'unsettled', 'byCode'];
+const RECENT_FIELDS = ['time', 'name', 'model', 'kind', 'callId', 'parentCallId', 'rootCallId', 'ms', 'ok', 'code'];
+const PENDING_FIELDS = ['name', 'time', 'kind', 'model', 'parentCallId', 'rootCallId'];
+/** Parse one tool/day counter. */
+function parseToolDay(value, path) {
+    const record = objectAt(value, path, TOOL_DAY_FIELDS);
+    return {
+        calls: countAt(record['calls'], `${path}.calls`),
+        errors: countAt(record['errors'], `${path}.errors`),
+        ms: numberAt(record['ms'], `${path}.ms`, { min: 0 }),
+        maxMs: numberAt(record['maxMs'], `${path}.maxMs`, { min: 0 }),
+        unsettled: countAt(record['unsettled'], `${path}.unsettled`),
+        codeCalls: countAt(record['codeCalls'], `${path}.codeCalls`),
+    };
+}
+/** Parse a record of tool/day counters. */
+function parseToolDayRecord(value, path) {
+    const out = {};
+    for (const [day, entry] of recordAt(value, path))
+        out[day] = parseToolDay(entry, `${path}.${day}`);
+    return out;
+}
+/** Parse one tool performance row. */
+function parseToolBucket(value, path) {
+    const record = objectAt(value, path, BUCKET_FIELDS);
+    const histogram = arrayAt(record['histogram'], `${path}.histogram`);
+    if (histogram.length !== TOOL_USAGE_CAPS.buckets)
+        fail(`${path}.histogram`, `${TOOL_USAGE_CAPS.buckets} entries`, histogram.length);
+    return {
+        calls: countAt(record['calls'], `${path}.calls`),
+        errors: countAt(record['errors'], `${path}.errors`),
+        unsettled: countAt(record['unsettled'], `${path}.unsettled`),
+        codeCalls: countAt(record['codeCalls'], `${path}.codeCalls`),
+        directCalls: countAt(record['directCalls'], `${path}.directCalls`),
+        totalMs: numberAt(record['totalMs'], `${path}.totalMs`, { min: 0 }),
+        maxMs: numberAt(record['maxMs'], `${path}.maxMs`, { min: 0 }),
+        argsBytes: numberAt(record['argsBytes'], `${path}.argsBytes`),
+        resultBytes: numberAt(record['resultBytes'], `${path}.resultBytes`),
+        firstUsed: nullableNumberAt(record['firstUsed'], `${path}.firstUsed`),
+        lastUsed: nullableNumberAt(record['lastUsed'], `${path}.lastUsed`),
+        histogram: histogram.map((entry, index) => countAt(entry, `${path}.histogram[${index}]`)),
+        byDay: parseToolDayRecord(record['byDay'], `${path}.byDay`),
+    };
+}
+/** Parse a model/day record. */
+function parseModelDayRecord(value, path) {
+    const out = {};
+    for (const [day, entry] of recordAt(value, path)) {
+        const record = objectAt(entry, `${path}.${day}`, ['calls', 'errors', 'ms', 'maxMs']);
+        out[day] = {
+            calls: countAt(record['calls'], `${path}.${day}.calls`),
+            errors: countAt(record['errors'], `${path}.${day}.errors`),
+            ms: numberAt(record['ms'], `${path}.${day}.ms`, { min: 0 }),
+            maxMs: numberAt(record['maxMs'], `${path}.${day}.maxMs`, { min: 0 }),
+        };
+    }
+    return out;
+}
+/** Parse an owner/day record (owners carry no durations-per-call bound). */
+function parseOwnerDayRecord(value, path) {
+    const out = {};
+    for (const [day, entry] of recordAt(value, path)) {
+        const record = objectAt(entry, `${path}.${day}`, ['calls', 'errors', 'ms']);
+        out[day] = {
+            calls: countAt(record['calls'], `${path}.${day}.calls`),
+            errors: countAt(record['errors'], `${path}.${day}.errors`),
+            ms: numberAt(record['ms'], `${path}.${day}.ms`, { min: 0 }),
+        };
+    }
+    return out;
+}
+/** Parse one model usage row. */
+function parseModelUsage(value, path) {
+    const record = objectAt(value, path, MODEL_FIELDS);
+    const histogram = arrayAt(record['histogram'], `${path}.histogram`);
+    if (histogram.length !== TOOL_USAGE_CAPS.buckets)
+        fail(`${path}.histogram`, `${TOOL_USAGE_CAPS.buckets} entries`, histogram.length);
+    return {
+        calls: countAt(record['calls'], `${path}.calls`),
+        errors: countAt(record['errors'], `${path}.errors`),
+        ms: numberAt(record['ms'], `${path}.ms`, { min: 0 }),
+        tools: arrayAt(record['tools'], `${path}.tools`).map((entry, index) => stringAt(entry, `${path}.tools[${index}]`)),
+        histogram: histogram.map((entry, index) => countAt(entry, `${path}.histogram[${index}]`)),
+        byDay: parseModelDayRecord(record['byDay'], `${path}.byDay`),
+    };
+}
+/** Parse one owner usage row. */
+function parseOwnerUsage(value, path) {
+    const record = objectAt(value, path, OWNER_FIELDS);
+    return {
+        calls: countAt(record['calls'], `${path}.calls`),
+        errors: countAt(record['errors'], `${path}.errors`),
+        ms: numberAt(record['ms'], `${path}.ms`, { min: 0 }),
+        byDay: parseOwnerDayRecord(record['byDay'], `${path}.byDay`),
+    };
+}
+/** Parse one day usage row. */
+function parseDayUsage(value, path) {
+    const record = objectAt(value, path, DAY_FIELDS);
+    const byCode = {};
+    for (const [code, entry] of recordAt(record['byCode'], `${path}.byCode`))
+        byCode[code] = countAt(entry, `${path}.byCode.${code}`);
+    return {
+        calls: countAt(record['calls'], `${path}.calls`),
+        errors: countAt(record['errors'], `${path}.errors`),
+        ms: numberAt(record['ms'], `${path}.ms`, { min: 0 }),
+        unsettled: countAt(record['unsettled'], `${path}.unsettled`),
+        byCode,
+    };
+}
+/** Parse one retained recent call. */
+function parseRecentCall(value, path) {
+    const record = objectAt(value, path, RECENT_FIELDS);
+    return {
+        time: numberAt(record['time'], `${path}.time`),
+        name: stringAt(record['name'], `${path}.name`),
+        model: stringAt(record['model'], `${path}.model`),
+        kind: kindAt(record['kind'], `${path}.kind`),
+        callId: stringAt(record['callId'], `${path}.callId`),
+        ...record['parentCallId'] === undefined ? {} : { parentCallId: stringAt(record['parentCallId'], `${path}.parentCallId`) },
+        ...record['rootCallId'] === undefined ? {} : { rootCallId: stringAt(record['rootCallId'], `${path}.rootCallId`) },
+        ms: nullableNumberAt(record['ms'], `${path}.ms`),
+        ok: nullableBooleanAt(record['ok'], `${path}.ok`),
+        code: nullableStringAt(record['code'], `${path}.code`),
+    };
+}
+/** Parse one in-flight call. */
+function parsePendingCall(value, path) {
+    const record = objectAt(value, path, PENDING_FIELDS);
+    return {
+        name: stringAt(record['name'], `${path}.name`),
+        time: numberAt(record['time'], `${path}.time`),
+        kind: kindAt(record['kind'], `${path}.kind`),
+        model: stringAt(record['model'], `${path}.model`),
+        ...record['parentCallId'] === undefined ? {} : { parentCallId: stringAt(record['parentCallId'], `${path}.parentCallId`) },
+        ...record['rootCallId'] === undefined ? {} : { rootCallId: stringAt(record['rootCallId'], `${path}.rootCallId`) },
+    };
+}
+const STATE_FIELDS = [
+    'stateVersion', 'calls', 'errors', 'unsettled', 'toolMs', 'uniqueTools', 'byTool', 'byModel',
+    'byOwner', 'byDay', 'byErrorCode', 'recent', 'pending', 'route', 'stepModel', 'lastTurn',
+    'toolsTruncated', 'modelsTruncated',
+];
+/** Parse the persisted fold state (the projection cache's input boundary). */
+function parseToolUsageState(value) {
+    const record = objectAt(value, 'state', STATE_FIELDS);
+    if (record['stateVersion'] !== TOOL_USAGE_STATE_VERSION)
+        fail('state.stateVersion', String(TOOL_USAGE_STATE_VERSION), record['stateVersion']);
+    const byTool = {};
+    for (const [name, entry] of recordAt(record['byTool'], 'state.byTool'))
+        byTool[name] = parseToolBucket(entry, `state.byTool.${name}`);
+    const byModel = {};
+    for (const [model, entry] of recordAt(record['byModel'], 'state.byModel'))
+        byModel[model] = parseModelUsage(entry, `state.byModel.${model}`);
+    const byOwner = {};
+    for (const [owner, entry] of recordAt(record['byOwner'], 'state.byOwner'))
+        byOwner[owner] = parseOwnerUsage(entry, `state.byOwner.${owner}`);
+    const byDay = {};
+    for (const [day, entry] of recordAt(record['byDay'], 'state.byDay'))
+        byDay[day] = parseDayUsage(entry, `state.byDay.${day}`);
+    const byErrorCode = {};
+    for (const [code, entry] of recordAt(record['byErrorCode'], 'state.byErrorCode'))
+        byErrorCode[code] = countAt(entry, `state.byErrorCode.${code}`);
+    const pending = {};
+    for (const [key, entry] of recordAt(record['pending'], 'state.pending'))
+        pending[key] = parsePendingCall(entry, `state.pending.${key}`);
+    const route = record['route'] === null ? null : (() => {
+        const parsed = objectAt(record['route'], 'state.route', ['provider', 'model']);
+        return { provider: stringAt(parsed['provider'], 'state.route.provider'), model: stringAt(parsed['model'], 'state.route.model') };
+    })();
+    const stepModel = record['stepModel'] === null ? null : (() => {
+        const parsed = objectAt(record['stepModel'], 'state.stepModel', ['turn', 'step', 'model']);
+        return {
+            turn: numberAt(parsed['turn'], 'state.stepModel.turn', { int: true }),
+            step: numberAt(parsed['step'], 'state.stepModel.step', { int: true }),
+            model: stringAt(parsed['model'], 'state.stepModel.model'),
+        };
+    })();
+    return {
+        stateVersion: TOOL_USAGE_STATE_VERSION,
+        calls: countAt(record['calls'], 'state.calls'),
+        errors: countAt(record['errors'], 'state.errors'),
+        unsettled: countAt(record['unsettled'], 'state.unsettled'),
+        toolMs: numberAt(record['toolMs'], 'state.toolMs', { min: 0 }),
+        uniqueTools: countAt(record['uniqueTools'], 'state.uniqueTools'),
+        byTool,
+        byModel,
+        byOwner,
+        byDay,
+        byErrorCode,
+        recent: arrayAt(record['recent'], 'state.recent').map((entry, index) => parseRecentCall(entry, `state.recent[${index}]`)),
+        pending,
+        route,
+        stepModel,
+        lastTurn: record['lastTurn'] === null ? null : numberAt(record['lastTurn'], 'state.lastTurn', { int: true }),
+        toolsTruncated: countAt(record['toolsTruncated'], 'state.toolsTruncated'),
+        modelsTruncated: countAt(record['modelsTruncated'], 'state.modelsTruncated'),
+    };
+}
+const WIRE_RECENT_FIELDS = ['time', 'name', 'model', 'ms', 'ok', 'kind', 'code'];
+const WIRE_FIELDS = ['stateVersion', 'calls', 'errors', 'unsettled', 'toolMs', 'uniqueTools', 'byOwner', 'byModel', 'byDay', 'recent', 'topTools'];
+/** Parse the compact wire value (the host's outbound boundary). */
+function parseToolUsageWire(value) {
+    const record = objectAt(value, 'wire', WIRE_FIELDS);
+    if (record['stateVersion'] !== TOOL_USAGE_STATE_VERSION)
+        fail('wire.stateVersion', String(TOOL_USAGE_STATE_VERSION), record['stateVersion']);
+    const byOwner = {};
+    for (const [owner, entry] of recordAt(record['byOwner'], 'wire.byOwner')) {
+        const parsed = objectAt(entry, `wire.byOwner.${owner}`, ['calls', 'errors', 'ms']);
+        byOwner[owner] = {
+            calls: countAt(parsed['calls'], `wire.byOwner.${owner}.calls`),
+            errors: countAt(parsed['errors'], `wire.byOwner.${owner}.errors`),
+            ms: numberAt(parsed['ms'], `wire.byOwner.${owner}.ms`, { min: 0 }),
+        };
+    }
+    const byModel = {};
+    for (const [model, entry] of recordAt(record['byModel'], 'wire.byModel')) {
+        const parsed = objectAt(entry, `wire.byModel.${model}`, ['calls', 'errors', 'tools', 'ms']);
+        byModel[model] = {
+            calls: countAt(parsed['calls'], `wire.byModel.${model}.calls`),
+            errors: countAt(parsed['errors'], `wire.byModel.${model}.errors`),
+            tools: countAt(parsed['tools'], `wire.byModel.${model}.tools`),
+            ms: numberAt(parsed['ms'], `wire.byModel.${model}.ms`, { min: 0 }),
+        };
+    }
+    const byDay = {};
+    for (const [day, entry] of recordAt(record['byDay'], 'wire.byDay')) {
+        const parsed = objectAt(entry, `wire.byDay.${day}`, ['calls', 'errors', 'ms', 'unsettled']);
+        byDay[day] = {
+            calls: countAt(parsed['calls'], `wire.byDay.${day}.calls`),
+            errors: countAt(parsed['errors'], `wire.byDay.${day}.errors`),
+            ms: numberAt(parsed['ms'], `wire.byDay.${day}.ms`, { min: 0 }),
+            unsettled: countAt(parsed['unsettled'], `wire.byDay.${day}.unsettled`),
+        };
+    }
+    return {
+        stateVersion: TOOL_USAGE_STATE_VERSION,
+        calls: countAt(record['calls'], 'wire.calls'),
+        errors: countAt(record['errors'], 'wire.errors'),
+        unsettled: countAt(record['unsettled'], 'wire.unsettled'),
+        toolMs: numberAt(record['toolMs'], 'wire.toolMs', { min: 0 }),
+        uniqueTools: countAt(record['uniqueTools'], 'wire.uniqueTools'),
+        byOwner,
+        byModel,
+        byDay,
+        recent: arrayAt(record['recent'], 'wire.recent').map((entry, index) => {
+            const parsed = objectAt(entry, `wire.recent[${index}]`, WIRE_RECENT_FIELDS);
+            return {
+                time: numberAt(parsed['time'], `wire.recent[${index}].time`),
+                name: stringAt(parsed['name'], `wire.recent[${index}].name`),
+                model: stringAt(parsed['model'], `wire.recent[${index}].model`),
+                ms: nullableNumberAt(parsed['ms'], `wire.recent[${index}].ms`),
+                ok: nullableBooleanAt(parsed['ok'], `wire.recent[${index}].ok`),
+                kind: kindAt(parsed['kind'], `wire.recent[${index}].kind`),
+                code: nullableStringAt(parsed['code'], `wire.recent[${index}].code`),
+            };
+        }),
+        topTools: arrayAt(record['topTools'], 'wire.topTools').map((entry, index) => {
+            const parsed = objectAt(entry, `wire.topTools[${index}]`, ['name', 'calls', 'ms']);
+            return {
+                name: stringAt(parsed['name'], `wire.topTools[${index}].name`),
+                calls: countAt(parsed['calls'], `wire.topTools[${index}].calls`),
+                ms: numberAt(parsed['ms'], `wire.topTools[${index}].ms`, { min: 0 }),
+            };
+        }),
+    };
+}
+/** Wrap one parser in the schema contract. */
+function schemaOf(parse) {
+    return {
+        parse,
+        safeParse: (value) => {
+            try {
+                return { success: true, data: parse(value) };
+            }
+            catch (error) {
+                return { success: false, error: error instanceof Error ? error : new Error(String(error)) };
+            }
+        },
+    };
+}
+/** The strict persisted-state schema (the projection cache's input boundary). */
+export const toolUsageStateSchema = schemaOf(parseToolUsageState);
+/** The compact wire's strict shape (the host's outbound boundary). */
+export const toolUsageWireSchema = schemaOf(parseToolUsageWire);
+/**
+ * The registered unit. Its STATE is the detail; its WIRE is the compact value.
+ *
+ * `apply` receives a full `SessionEvent`; the fold reads only the seven event types
+ * declared by {@link ToolUsageEvent} and returns the state unchanged otherwise.
+ */
+export const toolUsageProjectionDefinition = {
+    key: TOOL_USAGE_KEY,
+    stateVersion: TOOL_USAGE_STATE_VERSION,
+    stateSchema: toolUsageStateSchema,
+    init: () => initToolUsageState(),
+    // SAFETY: the projection registry passes the session's own `SessionEvent`; the fold
+    // reads only the seven event types declared by `ToolUsageEvent` and ignores the rest.
+    apply: (state, event) => foldToolUsageEvent(state, event),
+    wire: { viewSchema: toolUsageWireSchema, view: toolUsageWire },
+};
+//# sourceMappingURL=tool-usage-projection.js.map