sidekick-shared 0.25.0 → 0.26.0

package/dist/statusline/claudeStatuslinePayload.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Parser for the JSON Claude Code pipes to its status-line command.
+ *
+ * Claude Code runs the configured `statusLine.command` after every response
+ * (debounced at 300 ms) with a JSON document on stdin describing the session:
+ * model, workspace, context-window usage, estimated session cost, and — for
+ * Claude.ai Pro and Max subscribers — the *official* five-hour and seven-day
+ * rate-limit windows. That last block is the same data `/usage` shows and
+ * needs no network call, so Sidekick treats it as its most authoritative
+ * quota source whenever the status line is installed.
+ *
+ * Only the fields Sidekick reads are typed here; the raw document is kept on
+ * `raw` for callers that need more. Browser-safe: no Node imports.
+ *
+ * @module statusline/claudeStatuslinePayload
+ */
+import type { QuotaState } from '../quota';
+/** One official rate-limit window. */
+export interface ClaudeStatuslineRateLimitWindow {
+    /** Percentage of the window consumed, 0–100 (spend limits may exceed 100). */
+    usedPercentage: number;
+    /** Unix epoch seconds when the window resets. */
+    resetsAt: number;
+}
+export interface ClaudeStatuslinePayload {
+    sessionId?: string;
+    transcriptPath?: string;
+    cwd?: string;
+    model?: {
+        id?: string;
+        displayName?: string;
+    };
+    workspace?: {
+        currentDir?: string;
+        projectDir?: string;
+        gitWorktree?: string;
+    };
+    contextWindow?: {
+        usedPercentage?: number | null;
+        remainingPercentage?: number | null;
+        contextWindowSize?: number;
+        totalInputTokens?: number;
+        totalOutputTokens?: number;
+    };
+    cost?: {
+        totalCostUsd?: number;
+        totalDurationMs?: number;
+        totalApiDurationMs?: number;
+        totalLinesAdded?: number;
+        totalLinesRemoved?: number;
+    };
+    rateLimits?: {
+        fiveHour?: ClaudeStatuslineRateLimitWindow;
+        sevenDay?: ClaudeStatuslineRateLimitWindow;
+        spendLimit?: ClaudeStatuslineRateLimitWindow;
+    };
+    promptCache?: {
+        warm?: boolean;
+        cachingObserved?: boolean;
+        hitRatio?: number | null;
+        requests?: number;
+        misses?: number;
+        expectedRebuilds?: number;
+    };
+    /** The parsed document as received. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Parse a status-line document. Returns `null` for empty input, non-JSON, or
+ * JSON that is not an object; never throws.
+ */
+export declare function parseClaudeStatuslinePayload(text: string): ClaudeStatuslinePayload | null;
+export interface QuotaFromStatuslineOptions {
+    /** Capture time; defaults to now. */
+    now?: Date;
+    /**
+     * A previously known quota (typically the persisted snapshot). Windows the
+     * payload omits are carried over from it, since Claude Code drops a window
+     * from the document once its reset time has passed.
+     */
+    fallback?: QuotaState | null;
+}
+/**
+ * Build a `QuotaState` from the official rate-limit block. Returns `null`
+ * when the payload carries no rate limits at all (API-key users, or before
+ * the first response of a session), so callers fall back to their other
+ * sources.
+ */
+export declare function quotaFromStatuslinePayload(payload: ClaudeStatuslinePayload, options?: QuotaFromStatuslineOptions): QuotaState | null;

package/dist/statusline/claudeStatuslinePayload.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Parser for the JSON Claude Code pipes to its status-line command.
+ *
+ * Claude Code runs the configured `statusLine.command` after every response
+ * (debounced at 300 ms) with a JSON document on stdin describing the session:
+ * model, workspace, context-window usage, estimated session cost, and — for
+ * Claude.ai Pro and Max subscribers — the *official* five-hour and seven-day
+ * rate-limit windows. That last block is the same data `/usage` shows and
+ * needs no network call, so Sidekick treats it as its most authoritative
+ * quota source whenever the status line is installed.
+ *
+ * Only the fields Sidekick reads are typed here; the raw document is kept on
+ * `raw` for callers that need more. Browser-safe: no Node imports.
+ *
+ * @module statusline/claudeStatuslinePayload
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseClaudeStatuslinePayload = parseClaudeStatuslinePayload;
+exports.quotaFromStatuslinePayload = quotaFromStatuslinePayload;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableNum(value) {
+    if (value === null)
+        return null;
+    return num(value);
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function bool(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function window(value) {
+    if (!isRecord(value))
+        return undefined;
+    const usedPercentage = num(value.used_percentage);
+    const resetsAt = num(value.resets_at);
+    if (usedPercentage === undefined || resetsAt === undefined)
+        return undefined;
+    return { usedPercentage, resetsAt };
+}
+function defined(value) {
+    return Object.values(value).some((entry) => entry !== undefined) ? value : undefined;
+}
+/**
+ * Parse a status-line document. Returns `null` for empty input, non-JSON, or
+ * JSON that is not an object; never throws.
+ */
+function parseClaudeStatuslinePayload(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw))
+        return null;
+    const model = isRecord(raw.model) ? raw.model : undefined;
+    const workspace = isRecord(raw.workspace) ? raw.workspace : undefined;
+    const contextWindow = isRecord(raw.context_window) ? raw.context_window : undefined;
+    const cost = isRecord(raw.cost) ? raw.cost : undefined;
+    const rateLimits = isRecord(raw.rate_limits) ? raw.rate_limits : undefined;
+    const promptCache = isRecord(raw.prompt_cache) ? raw.prompt_cache : undefined;
+    return {
+        sessionId: str(raw.session_id),
+        transcriptPath: str(raw.transcript_path),
+        cwd: str(raw.cwd),
+        model: model ? defined({ id: str(model.id), displayName: str(model.display_name) }) : undefined,
+        workspace: workspace
+            ? defined({
+                currentDir: str(workspace.current_dir),
+                projectDir: str(workspace.project_dir),
+                gitWorktree: str(workspace.git_worktree),
+            })
+            : undefined,
+        contextWindow: contextWindow
+            ? defined({
+                usedPercentage: nullableNum(contextWindow.used_percentage),
+                remainingPercentage: nullableNum(contextWindow.remaining_percentage),
+                contextWindowSize: num(contextWindow.context_window_size),
+                totalInputTokens: num(contextWindow.total_input_tokens),
+                totalOutputTokens: num(contextWindow.total_output_tokens),
+            })
+            : undefined,
+        cost: cost
+            ? defined({
+                totalCostUsd: num(cost.total_cost_usd),
+                totalDurationMs: num(cost.total_duration_ms),
+                totalApiDurationMs: num(cost.total_api_duration_ms),
+                totalLinesAdded: num(cost.total_lines_added),
+                totalLinesRemoved: num(cost.total_lines_removed),
+            })
+            : undefined,
+        rateLimits: rateLimits
+            ? defined({
+                fiveHour: window(rateLimits.five_hour),
+                sevenDay: window(rateLimits.seven_day),
+                spendLimit: window(rateLimits.spend_limit),
+            })
+            : undefined,
+        promptCache: promptCache
+            ? defined({
+                warm: bool(promptCache.warm),
+                cachingObserved: bool(promptCache.caching_observed),
+                hitRatio: nullableNum(promptCache.hit_ratio),
+                requests: num(promptCache.requests),
+                misses: num(promptCache.misses),
+                expectedRebuilds: num(promptCache.expected_rebuilds),
+            })
+            : undefined,
+        raw,
+    };
+}
+function toWindow(live, fallback) {
+    if (live) {
+        return {
+            utilization: Math.max(0, live.usedPercentage),
+            resetsAt: new Date(live.resetsAt * 1000).toISOString(),
+        };
+    }
+    return fallback ?? { utilization: 0, resetsAt: '' };
+}
+/**
+ * Build a `QuotaState` from the official rate-limit block. Returns `null`
+ * when the payload carries no rate limits at all (API-key users, or before
+ * the first response of a session), so callers fall back to their other
+ * sources.
+ */
+function quotaFromStatuslinePayload(payload, options = {}) {
+    const limits = payload.rateLimits;
+    if (!limits?.fiveHour && !limits?.sevenDay)
+        return null;
+    const now = options.now ?? new Date();
+    const fallback = options.fallback ?? undefined;
+    return {
+        fiveHour: toWindow(limits.fiveHour, fallback?.fiveHour),
+        sevenDay: toWindow(limits.sevenDay, fallback?.sevenDay),
+        available: true,
+        providerId: 'claude-code',
+        source: 'statusline',
+        capturedAt: now.toISOString(),
+        stale: false,
+    };
+}

package/dist/statusline/formatter.d.ts

@@ -1,9 +1,15 @@
 import type { ActiveAccountStatus } from '../accountStatus';
 import type { QuotaState } from '../quota';
+import type { ClaudeStatuslinePayload } from './claudeStatuslinePayload';
 export interface StatuslineInput {
     accounts: ActiveAccountStatus;
     claudeQuota?: QuotaState | null;
     codexQuota?: QuotaState | null;
+    /**
+     * The document Claude Code piped to the status-line command, when running
+     * as one. Adds context usage, session cost, and prompt-cache hit rate.
+     */
+    live?: ClaudeStatuslinePayload | null;
     now?: Date;
 }
 export interface StatuslineSelection {
@@ -13,4 +19,11 @@ export interface StatuslineSelection {
     quota: QuotaState | null;
 }
 export declare function selectStatuslineAccount(input: StatuslineInput): StatuslineSelection | null;
+/**
+ * One-line status. Segments, in order, each omitted when unknown:
+ * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
+ *
+ * The age segment appears only for cached quota older than five minutes, so
+ * a snapshot from yesterday can no longer read like a live figure.
+ */
 export declare function formatStatusline(input: StatuslineInput): string;

package/dist/statusline/formatter.js

@@ -23,20 +23,62 @@ function selectStatuslineAccount(input) {
     }
     return null;
 }
+/**
+ * One-line status. Segments, in order, each omitted when unknown:
+ * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
+ *
+ * The age segment appears only for cached quota older than five minutes, so
+ * a snapshot from yesterday can no longer read like a live figure.
+ */
 function formatStatusline(input) {
     const selected = selectStatuslineAccount(input);
+    const now = input.now ?? new Date();
+    const liveSegments = formatLiveSegments(input.live);
     if (!selected)
-        return 'acct:none · quota unavailable';
+        return joinSegments(['acct:none', 'quota unavailable', ...liveSegments]);
     const account = compactLabel(selected.accountLabel);
     const quota = selected.quota;
-    if (!quota?.available)
-        return `acct:${account} · quota unavailable`;
-    const now = input.now ?? new Date();
+    if (!quota?.available) {
+        return joinSegments([`acct:${account}`, 'quota unavailable', ...liveSegments]);
+    }
     const utilization = clampPercent(quota.fiveHour.utilization);
     const reset = formatReset(quota.fiveHour.resetsAt, now);
     const eta = estimateWindowEta(quota, now);
-    const etaText = eta == null ? '' : ` · ~${formatMinutes(eta)} left`;
-    return `acct:${account} · 5h ${Math.round(utilization)}% resets ${reset}${etaText}`;
+    const segments = [`acct:${account}`, `5h ${Math.round(utilization)}% resets ${reset}`];
+    if (eta != null)
+        segments.push(`~${formatMinutes(eta)} left`);
+    if (quota.sevenDay.resetsAt && quota.sevenDay.utilization > 0) {
+        segments.push(`7d ${Math.round(clampPercent(quota.sevenDay.utilization))}%`);
+    }
+    if (quota.freshness && quota.freshness !== 'fresh') {
+        segments.push(`(${(0, quota_1.formatQuotaAge)(quota.ageMs)})`);
+    }
+    return joinSegments([...segments, ...liveSegments]);
+}
+function formatLiveSegments(live) {
+    if (!live)
+        return [];
+    const segments = [];
+    const context = live.contextWindow?.usedPercentage;
+    if (typeof context === 'number')
+        segments.push(`ctx ${Math.round(clampPercent(context))}%`);
+    const cost = live.cost?.totalCostUsd;
+    if (typeof cost === 'number' && cost > 0)
+        segments.push(`$${formatCost(cost)}`);
+    const hitRatio = live.promptCache?.hitRatio;
+    if (typeof hitRatio === 'number')
+        segments.push(`cache ${Math.round(clampPercent(hitRatio * 100))}%`);
+    return segments;
+}
+function joinSegments(segments) {
+    return segments.join(' · ');
+}
+function formatCost(value) {
+    if (value >= 100)
+        return value.toFixed(0);
+    if (value >= 10)
+        return value.toFixed(1);
+    return value.toFixed(2);
 }
 function estimateWindowEta(quota, now) {
     const resetAt = Date.parse(quota.fiveHour.resetsAt);

package/dist/statusline/index.d.ts

@@ -1,7 +1,15 @@
 export { getActiveAccountStatus } from '../accountStatus';
-export type { ActiveAccountStatus, ActiveProviderAccountStatus } from '../accountStatus';
-export { readQuotaSnapshot } from '../quotaSnapshots';
+export type { ActiveAccountStatus, ActiveAccountStatusOptions, ActiveProviderAccountStatus, } from '../accountStatus';
+export { readQuotaSnapshot, writeQuotaSnapshot } from '../quotaSnapshots';
 export type { QuotaSnapshotProviderId } from '../quotaSnapshots';
+export { appendQuotaHistorySample, getWorkspaceIdFromPath } from '../quotaHistory';
+export type { QuotaHistorySample } from '../quotaHistory';
+export { classifyQuotaFreshness, formatQuotaAge } from '../quota';
+export type { QuotaFreshness, QuotaState } from '../quota';
 export { BurnRateCalculator, estimateTimeToQuota } from './BurnRateCalculator';
 export { formatStatusline, selectStatuslineAccount } from './formatter';
 export type { StatuslineInput, StatuslineSelection } from './formatter';
+export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './claudeStatuslinePayload';
+export type { ClaudeStatuslinePayload, ClaudeStatuslineRateLimitWindow, QuotaFromStatuslineOptions, } from './claudeStatuslinePayload';
+export { STATE_FILE_NAME, STATE_FILE_SCHEMA_VERSION, billingBlockToStateFile, getStateFilePath, quotaToStateFile, readStateFile, writeStateFile, } from '../stateFile';
+export type { SidekickStateFile, SidekickStateInput, StateFileAccount, StateFileBillingBlock, StateFileContext, StateFileQuota, StateFileQuotaWindow, StateFileSession, StateFileWriter, WriteStateFileOptions, } from '../stateFile';

package/dist/statusline/index.js

@@ -1,13 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
+exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.formatQuotaAge = exports.classifyQuotaFreshness = exports.getWorkspaceIdFromPath = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
 var accountStatus_1 = require("../accountStatus");
 Object.defineProperty(exports, "getActiveAccountStatus", { enumerable: true, get: function () { return accountStatus_1.getActiveAccountStatus; } });
 var quotaSnapshots_1 = require("../quotaSnapshots");
 Object.defineProperty(exports, "readQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.readQuotaSnapshot; } });
+Object.defineProperty(exports, "writeQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.writeQuotaSnapshot; } });
+var quotaHistory_1 = require("../quotaHistory");
+Object.defineProperty(exports, "appendQuotaHistorySample", { enumerable: true, get: function () { return quotaHistory_1.appendQuotaHistorySample; } });
+Object.defineProperty(exports, "getWorkspaceIdFromPath", { enumerable: true, get: function () { return quotaHistory_1.getWorkspaceIdFromPath; } });
+var quota_1 = require("../quota");
+Object.defineProperty(exports, "classifyQuotaFreshness", { enumerable: true, get: function () { return quota_1.classifyQuotaFreshness; } });
+Object.defineProperty(exports, "formatQuotaAge", { enumerable: true, get: function () { return quota_1.formatQuotaAge; } });
 var BurnRateCalculator_1 = require("./BurnRateCalculator");
 Object.defineProperty(exports, "BurnRateCalculator", { enumerable: true, get: function () { return BurnRateCalculator_1.BurnRateCalculator; } });
 Object.defineProperty(exports, "estimateTimeToQuota", { enumerable: true, get: function () { return BurnRateCalculator_1.estimateTimeToQuota; } });
 var formatter_1 = require("./formatter");
 Object.defineProperty(exports, "formatStatusline", { enumerable: true, get: function () { return formatter_1.formatStatusline; } });
 Object.defineProperty(exports, "selectStatuslineAccount", { enumerable: true, get: function () { return formatter_1.selectStatuslineAccount; } });
+var claudeStatuslinePayload_1 = require("./claudeStatuslinePayload");
+Object.defineProperty(exports, "parseClaudeStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.parseClaudeStatuslinePayload; } });
+Object.defineProperty(exports, "quotaFromStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.quotaFromStatuslinePayload; } });
+var stateFile_1 = require("../stateFile");
+Object.defineProperty(exports, "STATE_FILE_NAME", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_NAME; } });
+Object.defineProperty(exports, "STATE_FILE_SCHEMA_VERSION", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "billingBlockToStateFile", { enumerable: true, get: function () { return stateFile_1.billingBlockToStateFile; } });
+Object.defineProperty(exports, "getStateFilePath", { enumerable: true, get: function () { return stateFile_1.getStateFilePath; } });
+Object.defineProperty(exports, "quotaToStateFile", { enumerable: true, get: function () { return stateFile_1.quotaToStateFile; } });
+Object.defineProperty(exports, "readStateFile", { enumerable: true, get: function () { return stateFile_1.readStateFile; } });
+Object.defineProperty(exports, "writeStateFile", { enumerable: true, get: function () { return stateFile_1.writeStateFile; } });

package/dist/tokenSummary.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One vocabulary for token totals across every Sidekick surface.
+ *
+ * Every report, dashboard, status bar, and export derives its headline token
+ * numbers from here so "Total" means the same thing everywhere:
+ *
+ * - `total`   — every token the provider billed: uncached input, cache writes,
+ *               cache reads, and output. Matches `NormalizedUsage.totalTokens`
+ *               and the per-model `tokens` the `EventAggregator` keeps.
+ * - `context` — tokens that occupied the context window on the last request:
+ *               uncached input, cache writes, and cache reads. Output is
+ *               excluded, matching the input-only formula Claude Code uses for
+ *               its status-line `used_percentage`.
+ * - `output`  — output tokens as billed.
+ *
+ * Cache reads are usually the majority of a coding-agent session's tokens, so
+ * an "input + output" total silently drops most of the work. Sidekick used to
+ * do that on some surfaces and not others; this helper is the single place the
+ * arithmetic lives.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module tokenSummary
+ */
+/** Any object carrying the four billable token buckets. */
+export interface TokenTotalsLike {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens?: number;
+    cacheReadTokens?: number;
+    /**
+     * A provider-semantics-aware total, when the source already computed one
+     * (for example `AggregatedTokens.totalTokens`). Preferred over the
+     * four-bucket sum because it already accounts for whether reasoning tokens
+     * were billed inside or outside `outputTokens`.
+     */
+    totalTokens?: number;
+}
+export interface TokenSummary {
+    /** Everything billed: uncached input + cache writes + cache reads + output. */
+    total: number;
+    /** Tokens occupying the context window: uncached input + cache writes + cache reads. */
+    context: number;
+    /** Uncached input tokens. */
+    input: number;
+    /** Output tokens as billed. */
+    output: number;
+    /** Tokens read from the prompt cache. */
+    cacheRead: number;
+    /** Tokens written to the prompt cache. */
+    cacheWrite: number;
+    /** Fraction of context tokens that came from cache reads (0..1), or null with no input. */
+    cacheHitRatio: number | null;
+}
+/** Column label for `TokenSummary.total` on any surface. */
+export declare const TOKEN_TOTAL_LABEL = "Total (incl. cache)";
+/** Column label for `TokenSummary.context` on any surface. */
+export declare const TOKEN_CONTEXT_LABEL = "Context";
+/** Derive the shared token vocabulary from any four-bucket token record. */
+export declare function summarizeTokens(totals: TokenTotalsLike): TokenSummary;
+/** Sum several token records bucket-by-bucket before summarizing. */
+export declare function sumTokenTotals(records: readonly TokenTotalsLike[]): TokenTotalsLike;

package/dist/tokenSummary.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * One vocabulary for token totals across every Sidekick surface.
+ *
+ * Every report, dashboard, status bar, and export derives its headline token
+ * numbers from here so "Total" means the same thing everywhere:
+ *
+ * - `total`   — every token the provider billed: uncached input, cache writes,
+ *               cache reads, and output. Matches `NormalizedUsage.totalTokens`
+ *               and the per-model `tokens` the `EventAggregator` keeps.
+ * - `context` — tokens that occupied the context window on the last request:
+ *               uncached input, cache writes, and cache reads. Output is
+ *               excluded, matching the input-only formula Claude Code uses for
+ *               its status-line `used_percentage`.
+ * - `output`  — output tokens as billed.
+ *
+ * Cache reads are usually the majority of a coding-agent session's tokens, so
+ * an "input + output" total silently drops most of the work. Sidekick used to
+ * do that on some surfaces and not others; this helper is the single place the
+ * arithmetic lives.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module tokenSummary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_CONTEXT_LABEL = exports.TOKEN_TOTAL_LABEL = void 0;
+exports.summarizeTokens = summarizeTokens;
+exports.sumTokenTotals = sumTokenTotals;
+/** Column label for `TokenSummary.total` on any surface. */
+exports.TOKEN_TOTAL_LABEL = 'Total (incl. cache)';
+/** Column label for `TokenSummary.context` on any surface. */
+exports.TOKEN_CONTEXT_LABEL = 'Context';
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/** Derive the shared token vocabulary from any four-bucket token record. */
+function summarizeTokens(totals) {
+    const input = count(totals.inputTokens);
+    const output = count(totals.outputTokens);
+    const cacheRead = count(totals.cacheReadTokens);
+    const cacheWrite = count(totals.cacheWriteTokens);
+    const context = input + cacheWrite + cacheRead;
+    const fourBucket = context + output;
+    const provided = totals.totalTokens;
+    const total = typeof provided === 'number' && Number.isFinite(provided) && provided >= 0
+        ? Math.floor(provided)
+        : fourBucket;
+    return {
+        total,
+        context,
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        cacheHitRatio: context > 0 ? cacheRead / context : null,
+    };
+}
+/** Sum several token records bucket-by-bucket before summarizing. */
+function sumTokenTotals(records) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheWriteTokens = 0;
+    let cacheReadTokens = 0;
+    for (const record of records) {
+        inputTokens += count(record.inputTokens);
+        outputTokens += count(record.outputTokens);
+        cacheWriteTokens += count(record.cacheWriteTokens);
+        cacheReadTokens += count(record.cacheReadTokens);
+    }
+    return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
+}

package/dist/transcript.d.ts

@@ -77,7 +77,12 @@ export interface CanonicalSessionTranscript {
         events: NormalizedUsage[];
         costs: NormalizedUsageCost[];
         totals: CanonicalTranscriptUsageTotals;
+        /** Strict total: `null` unless every usage event could be priced. */
         totalCostUsd: number | null;
+        /** Sum of the events that could be priced; pair with `unpricedEvents`. */
+        pricedCostUsd: number;
+        /** Usage events with neither a reported cost nor a catalog price. */
+        unpricedEvents: number;
     };
     provenance: {
         source: 'session-events';

package/dist/transcript.js

@@ -144,6 +144,8 @@ function projectSessionTranscript(events, options = {}) {
             totalCostUsd: usageCosts.length > 0 && usageCosts.every((cost) => cost.costUsd !== null)
                 ? usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0)
                 : null,
+            pricedCostUsd: usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0),
+            unpricedEvents: usageCosts.filter((cost) => cost.costUsd === null).length,
         },
         provenance: { source: 'session-events', fidelity, eventCount: events.length },
     };

package/dist/types/observedSessionV1.d.ts

@@ -69,6 +69,8 @@ export interface ProviderSessionAdapterV1 {
     dispose(): void;
 }
 export declare function derivePendingUserRequestV1(provider: ProviderId, sessionId: string, sourcePath: string, events: SessionEvent[]): PendingUserRequestV1 | null;
+/** The activity detector's reason for a session produced by this adapter, if known. */
+export declare function getObservedActivityReason(session: ObservedAgentSessionV1): string | undefined;
 export interface ProviderSessionAdapterV1Options {
     pollIntervalMs?: number;
     observationOnly?: boolean;