sidekick-shared 0.25.0 → 0.26.1

package/dist/providers/openCode.js

@@ -57,6 +57,7 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const sessionContext_1 = require("../context/sessionContext");
+const sessionStats_1 = require("../sessionStats");
 const openCodeParser_1 = require("../parsers/openCodeParser");
 const openCodeDatabase_1 = require("./openCodeDatabase");
 const zaiQuota_1 = require("../zaiQuota");
@@ -170,16 +171,24 @@ function makeDbSessionPath(dataDir, projectId, sessionId) {
 function isDbSessionPath(sessionPath) {
     return sessionPath.includes(path.sep + DB_SESSION_PREFIX + path.sep);
 }
-function workspaceMatches(left, right) {
-    const a = path
-        .resolve(left)
+/**
+ * Whether a session recorded in `sessionDirectory` belongs to `workspacePath`.
+ *
+ * A session started inside the workspace (the workspace itself or any
+ * subdirectory, e.g. a monorepo package) matches. A session started in a
+ * *parent* of the workspace does not: a sub-package workspace must not list
+ * every session of the enclosing repo as its own.
+ */
+function workspaceMatches(sessionDirectory, workspacePath) {
+    const session = path
+        .resolve(sessionDirectory)
         .replace(/[\\/]+$/, '')
         .toLowerCase();
-    const b = path
-        .resolve(right)
+    const workspace = path
+        .resolve(workspacePath)
         .replace(/[\\/]+$/, '')
         .toLowerCase();
-    return a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep);
+    return session === workspace || session.startsWith(workspace + path.sep);
 }
 /** Extract project ID from a synthetic DB session path. */
 function extractProjectIdFromDbPath(sessionPath) {
@@ -322,18 +331,15 @@ function normalizePath(input) {
         return path.resolve(input);
     }
 }
-// ---------------------------------------------------------------------------
-// File-based reader (legacy fallback)
-// ---------------------------------------------------------------------------
-/**
- * Incremental reader for file-based OpenCode sessions.
- *
- * Tracks which message IDs have been seen and reads new messages
- * plus their parts on each readNew() call.
- */
+function messageCreatedMs(message) {
+    const created = message.time?.created;
+    const ms = typeof created === 'number' ? created : Date.parse(String(created ?? ''));
+    return Number.isFinite(ms) ? ms : 0;
+}
 class OpenCodeFileReader {
     sessionId;
     seenMessages = new Map();
+    pendingSkip = 0;
     storageBase;
     constructor(sessionId) {
         this.sessionId = sessionId;
@@ -350,47 +356,47 @@ class OpenCodeFileReader {
         catch {
             return [];
         }
-        const newEvents = [];
+        const entries = [];
         for (const file of messageFiles) {
             const msgId = path.basename(file, '.json');
             const messagePath = path.join(messageDir, file);
             const message = readJsonSafe(messagePath);
             if (!message)
                 continue;
-            let messageMtimeMs = 0;
+            let mtimeMs = 0;
             try {
-                messageMtimeMs = fs.statSync(messagePath).mtimeMs;
+                mtimeMs = fs.statSync(messagePath).mtimeMs;
             }
             catch {
-                messageMtimeMs = 0;
+                mtimeMs = 0;
             }
-            const partDir = path.join(this.storageBase, 'part', msgId);
-            let parts = [];
-            if (fs.existsSync(partDir)) {
-                try {
-                    parts = fs
-                        .readdirSync(partDir)
-                        .filter((f) => f.endsWith('.json'))
-                        .map((f) => readJsonSafe(path.join(partDir, f)))
-                        .filter((p) => p !== null);
-                }
-                catch {
-                    // Skip unreadable part directories
-                }
+            const parts = this.readParts(msgId);
+            entries.push({ msgId, message, mtimeMs, parts, partIds: new Set(parts.map((p) => p.id)) });
+        }
+        if (this.pendingSkip > 0) {
+            // A position for this reader is a message count (see getPosition()), so a
+            // seek marks the oldest N messages as already seen without emitting them.
+            const ordered = [...entries].sort((a, b) => messageCreatedMs(a.message) - messageCreatedMs(b.message) ||
+                a.msgId.localeCompare(b.msgId));
+            for (const entry of ordered.slice(0, this.pendingSkip)) {
+                this.seenMessages.set(entry.msgId, { partIds: entry.partIds, mtimeMs: entry.mtimeMs });
             }
-            const partIds = new Set(parts.map((part) => part.id));
-            const previous = this.seenMessages.get(msgId);
+            this.pendingSkip = 0;
+        }
+        const newEvents = [];
+        for (const entry of entries) {
+            const previous = this.seenMessages.get(entry.msgId);
             const isNewMessage = !previous;
             let hasNewParts = false;
             if (previous) {
-                if (previous.mtimeMs !== messageMtimeMs) {
+                if (previous.mtimeMs !== entry.mtimeMs) {
                     hasNewParts = true;
                 }
-                else if (partIds.size !== previous.partIds.size) {
+                else if (entry.partIds.size !== previous.partIds.size) {
                     hasNewParts = true;
                 }
                 else {
-                    for (const partId of partIds) {
+                    for (const partId of entry.partIds) {
                         if (!previous.partIds.has(partId)) {
                             hasNewParts = true;
                             break;
@@ -399,19 +405,36 @@ class OpenCodeFileReader {
                 }
             }
             if (isNewMessage || hasNewParts) {
-                newEvents.push(...(0, openCodeParser_1.convertOpenCodeMessage)(message, parts));
-                this.seenMessages.set(msgId, { partIds, mtimeMs: messageMtimeMs });
+                newEvents.push(...(0, openCodeParser_1.convertOpenCodeMessage)(entry.message, entry.parts));
+                this.seenMessages.set(entry.msgId, { partIds: entry.partIds, mtimeMs: entry.mtimeMs });
             }
         }
         // Sort by timestamp
         return newEvents.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
     }
+    readParts(msgId) {
+        const partDir = path.join(this.storageBase, 'part', msgId);
+        if (!fs.existsSync(partDir))
+            return [];
+        try {
+            return fs
+                .readdirSync(partDir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => readJsonSafe(path.join(partDir, f)))
+                .filter((p) => p !== null);
+        }
+        catch {
+            // Skip unreadable part directories
+            return [];
+        }
+    }
     readAll() {
         this.reset();
         return this.readNew();
     }
     reset() {
         this.seenMessages.clear();
+        this.pendingSkip = 0;
     }
     exists() {
         return fs.existsSync(path.join(this.storageBase, 'message', this.sessionId));
@@ -422,8 +445,10 @@ class OpenCodeFileReader {
     getPosition() {
         return this.seenMessages.size;
     }
-    seekTo(_position) {
-        // File-backed reader does not support seeking — full replay required
+    seekTo(position) {
+        // Positions are message counts (getPosition()), so the next readNew() marks
+        // the oldest `position` messages as seen and emits only what follows.
+        this.pendingSkip = Number.isFinite(position) && position > 0 ? Math.floor(position) : 0;
     }
     wasTruncated() {
         return false; // JSON files don't truncate
@@ -438,11 +463,15 @@ class OpenCodeFileReader {
  * Uses time_updated timestamps to track which data has been seen,
  * querying only for newer messages/parts on each readNew() call.
  */
+/** How long a database-backed reader trusts its last session-row check. */
+const DB_EXISTS_MEMO_MS = 30_000;
 class OpenCodeDbReader {
     sessionId;
     db;
     lastTimeUpdated = 0;
     hasReadOnce = false;
+    existsCheckedAtMs = 0;
+    existsResult = true;
     constructor(sessionId, db) {
         this.sessionId = sessionId;
         this.db = db;
@@ -628,10 +657,22 @@ class OpenCodeDbReader {
         this.hasReadOnce = false;
     }
     exists() {
-        // DB-backed sessions are durable rows rather than ephemeral files.
-        // Treat transient sqlite timeout/read failures as "still exists" so
-        // SessionMonitor does not flap into discovery mode.
-        return true;
+        // DB-backed sessions are durable rows rather than ephemeral files. The row
+        // check costs a sqlite3 subprocess, so it is memoised, and a transient
+        // query failure still reports "exists" so SessionMonitor does not flap
+        // into discovery mode.
+        const now = Date.now();
+        if (now - this.existsCheckedAtMs < DB_EXISTS_MEMO_MS)
+            return this.existsResult;
+        this.existsCheckedAtMs = now;
+        try {
+            const row = this.db.getSession(this.sessionId);
+            this.existsResult = row !== null || this.db.getRuntimeStatus().kind === 'query_failed';
+        }
+        catch {
+            this.existsResult = true;
+        }
+        return this.existsResult;
     }
     flush() {
         // No-op for DB reading
@@ -1271,23 +1312,30 @@ class OpenCodeProvider {
         const db = this.ensureDb();
         return resolveProjectId(workspacePath, db, this.getRuntimeStatus()) || workspacePath;
     }
-    extractSessionLabel(sessionPath) {
-        const db = this.ensureDb();
-        const sessionId = this.getSessionId(sessionPath);
+    /** Session title from the metadata cache or the database; null without either. */
+    extractSessionLabelFromMetadata(sessionPath) {
         // Check metadata cache first
         const cached = this.sessionMetaCache.get(sessionPath);
         if (cached?.title) {
             return truncateTitle(cached.title);
         }
         // DB lookup
+        const db = this.ensureDb();
         if (db) {
-            const session = db.getSession(sessionId);
+            const session = db.getSession(this.getSessionId(sessionPath));
             if (session?.title) {
                 this.recordDatabaseStatus('extractSessionLabel', true);
                 return truncateTitle(session.title);
             }
         }
+        return null;
+    }
+    extractSessionLabel(sessionPath) {
+        const fromMetadata = this.extractSessionLabelFromMetadata(sessionPath);
+        if (fromMetadata)
+            return fromMetadata;
         // File fallback
+        const sessionId = this.getSessionId(sessionPath);
         const label = this.extractSessionLabelFromFiles(sessionPath, sessionId);
         this.recordDatabaseStatus('extractSessionLabel', label !== null || !isDbSessionPath(sessionPath));
         return label;
@@ -1649,78 +1697,13 @@ class OpenCodeProvider {
     }
     // --- Stats ---
     readSessionStats(sessionPath) {
-        const sessionId = path.basename(sessionPath, '.json');
-        const db = this.ensureDb();
-        let messageCount = 0;
-        let startTime = '';
-        let endTime = '';
-        const tokens = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0 };
-        const modelUsage = {};
-        const toolUsage = {};
-        let reportedCost = 0;
-        if (db) {
-            const messages = db.getMessagesForSession(sessionId);
-            const parts = db.getPartsForSession(sessionId);
-            for (const msg of messages) {
-                try {
-                    const data = JSON.parse(msg.data);
-                    const role = data.role;
-                    if (role === 'assistant' || role === 'user')
-                        messageCount++;
-                    const msgTokens = data.tokens;
-                    const cache = msgTokens?.cache;
-                    if (msgTokens) {
-                        tokens.input += msgTokens.input || 0;
-                        tokens.output += msgTokens.output || 0;
-                        tokens.cacheRead += cache?.read || 0;
-                        tokens.cacheWrite += cache?.write || 0;
-                    }
-                    if (data.cost)
-                        reportedCost += data.cost || 0;
-                    const modelId = data.modelID || 'unknown';
-                    if (role === 'assistant' && msgTokens) {
-                        if (!modelUsage[modelId])
-                            modelUsage[modelId] = { calls: 0, tokens: 0 };
-                        modelUsage[modelId].calls++;
-                        modelUsage[modelId].tokens +=
-                            (msgTokens.input || 0) + (msgTokens.output || 0);
-                    }
-                }
-                catch {
-                    /* skip */
-                }
-                if (!startTime)
-                    startTime = new Date(msg.time_created).toISOString();
-                endTime = new Date(msg.time_updated || msg.time_created).toISOString();
-            }
-            for (const part of parts) {
-                try {
-                    const data = JSON.parse(part.data);
-                    if (data.type === 'tool' || data.type === 'tool-invocation') {
-                        const toolName = data.tool || 'unknown';
-                        toolUsage[toolName] = (toolUsage[toolName] || 0) + 1;
-                    }
-                }
-                catch {
-                    /* skip */
-                }
-            }
-        }
-        return {
-            providerId: 'opencode',
-            sessionId,
-            filePath: sessionPath,
-            label: this.extractSessionLabel(sessionPath),
-            startTime,
-            endTime,
-            messageCount,
-            tokens,
-            modelUsage,
-            toolUsage,
-            compactionEstimate: 0,
-            truncationCount: 0,
-            reportedCost,
-        };
+        // One reader pass (database-backed or file-backed) feeds the shared
+        // aggregator, so compaction and truncation counts are real instead of the
+        // hardcoded zeros the direct SQLite read returned, and a session that
+        // cannot be read reports `availability: 'unavailable'` instead of zeros.
+        return (0, sessionStats_1.readSessionFileStats)(this, sessionPath, {
+            resolveLabel: () => this.extractSessionLabelFromMetadata(sessionPath),
+        });
     }
     readSessionContextSnapshot(sessionPath, options = {}) {
         return (0, sessionContext_1.readSessionContextSnapshot)(this, sessionPath, options);
@@ -1934,6 +1917,7 @@ class OpenCodeProvider {
         this.db?.close();
         this.db = null;
         this.dbInitialized = false;
+        this.dbStatus = { available: false, kind: 'db_missing' };
         this.sessionMetaCache.clear();
         this.dynamicContextWindowLimit = null;
     }

package/dist/providers/rolloutWalker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One capped walker for Codex rollout files.
+ *
+ * Codex writes `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`.
+ * Six recursive, uncapped walkers used to exist across the provider and the
+ * quota resolver; this module replaces them with a single walk that caps
+ * depth and file count, visits the newest-dated directories first so a
+ * `limit` can stop early, stats each file exactly once, and returns results
+ * newest first with the size and session id already attached.
+ *
+ * With `limit`, the early exit is by directory date: a rollout that was
+ * created days ago but is still being written lands in its creation day's
+ * directory, so a very small limit can miss it in favour of newer-dated,
+ * older-modified files. Callers that need exact mtime order over the whole
+ * history omit `limit` (the `maxFiles` cap still applies).
+ *
+ * @module providers/rolloutWalker
+ */
+export interface RolloutFileInfo {
+    path: string;
+    mtime: Date;
+    sizeBytes: number;
+    /** Session id parsed from the file name. */
+    sessionId: string;
+}
+export interface WalkRolloutFilesOptions {
+    /** Directory depth below each root to descend into (default 6; the dated tree is 3). */
+    maxDepth?: number;
+    /** Upper bound on files returned across all roots (default 20 000). */
+    maxFiles?: number;
+    /** Stop once this many files are collected, visiting newest-dated directories first. */
+    limit?: number;
+    /** Only files whose name carries this session id (case-insensitive). */
+    sessionId?: string;
+    /** Include zero-byte files (default false). */
+    includeEmpty?: boolean;
+}
+export declare const DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
+export declare const DEFAULT_ROLLOUT_WALK_MAX_FILES = 20000;
+/** Test if a filename is a Codex rollout file. */
+export declare function isRolloutFile(filename: string): boolean;
+/**
+ * Extract the session UUID from a rollout filename.
+ * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ */
+export declare function extractRolloutSessionId(filename: string): string;
+/**
+ * Walk one or more `sessions` roots for rollout files, newest first.
+ * Missing or unreadable directories are skipped; paths are deduplicated.
+ */
+export declare function walkRolloutFiles(roots: readonly string[], options?: WalkRolloutFilesOptions): RolloutFileInfo[];
+/** Async twin of {@link walkRolloutFiles} that yields between directories. */
+export declare function walkRolloutFilesAsync(roots: readonly string[], options?: WalkRolloutFilesOptions): Promise<RolloutFileInfo[]>;

package/dist/providers/rolloutWalker.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * One capped walker for Codex rollout files.
+ *
+ * Codex writes `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`.
+ * Six recursive, uncapped walkers used to exist across the provider and the
+ * quota resolver; this module replaces them with a single walk that caps
+ * depth and file count, visits the newest-dated directories first so a
+ * `limit` can stop early, stats each file exactly once, and returns results
+ * newest first with the size and session id already attached.
+ *
+ * With `limit`, the early exit is by directory date: a rollout that was
+ * created days ago but is still being written lands in its creation day's
+ * directory, so a very small limit can miss it in favour of newer-dated,
+ * older-modified files. Callers that need exact mtime order over the whole
+ * history omit `limit` (the `maxFiles` cap still applies).
+ *
+ * @module providers/rolloutWalker
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = void 0;
+exports.isRolloutFile = isRolloutFile;
+exports.extractRolloutSessionId = extractRolloutSessionId;
+exports.walkRolloutFiles = walkRolloutFiles;
+exports.walkRolloutFilesAsync = walkRolloutFilesAsync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = 20_000;
+/** Test if a filename is a Codex rollout file. */
+function isRolloutFile(filename) {
+    return filename.startsWith('rollout-') && filename.endsWith('.jsonl');
+}
+/**
+ * Extract the session UUID from a rollout filename.
+ * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ */
+function extractRolloutSessionId(filename) {
+    const base = path.basename(filename, '.jsonl');
+    // rollout-YYYYMMDD-HHMMSS-<uuid> or rollout-<timestamp>-<uuid>
+    const parts = base.split('-');
+    // The UUID is typically the last 5 segments (8-4-4-4-12)
+    if (parts.length >= 6) {
+        const possibleUuid = parts.slice(-5).join('-');
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(possibleUuid)) {
+            return possibleUuid;
+        }
+    }
+    // Fallback: use everything after "rollout-"
+    return base.replace(/^rollout-/, '');
+}
+function walkState(options) {
+    const maxFiles = Math.max(0, options.maxFiles ?? exports.DEFAULT_ROLLOUT_WALK_MAX_FILES);
+    const limit = options.limit === undefined ? Infinity : Math.max(0, options.limit);
+    return {
+        results: [],
+        seen: new Set(),
+        cap: Math.min(maxFiles, limit),
+        maxDepth: options.maxDepth ?? exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH,
+        sessionId: options.sessionId ? options.sessionId.trim().toLowerCase() : null,
+        includeEmpty: options.includeEmpty ?? false,
+    };
+}
+/** Newest-dated first: directory and file names sort descending. */
+function byNameDescending(a, b) {
+    return b.name.localeCompare(a.name);
+}
+function matchesFilter(state, name) {
+    if (!isRolloutFile(name))
+        return false;
+    return (state.sessionId === null || extractRolloutSessionId(name).toLowerCase() === state.sessionId);
+}
+function record(state, fullPath, name, stat) {
+    if (!state.includeEmpty && stat.size <= 0)
+        return;
+    if (state.seen.has(fullPath))
+        return;
+    state.seen.add(fullPath);
+    state.results.push({
+        path: fullPath,
+        mtime: stat.mtime,
+        sizeBytes: stat.size,
+        sessionId: extractRolloutSessionId(name),
+    });
+}
+function finish(state) {
+    return state.results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+}
+function visitSync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, fs.statSync(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+    }
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            visitSync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/**
+ * Walk one or more `sessions` roots for rollout files, newest first.
+ * Missing or unreadable directories are skipped; paths are deduplicated.
+ */
+function walkRolloutFiles(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        visitSync(state, root, 0);
+    return finish(state);
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+async function visitAsync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    let sinceYield = 0;
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, await fs.promises.stat(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+        if (++sinceYield >= 200) {
+            sinceYield = 0;
+            await yieldToEventLoop();
+        }
+    }
+    await yieldToEventLoop();
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            await visitAsync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/** Async twin of {@link walkRolloutFiles} that yields between directories. */
+async function walkRolloutFilesAsync(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        await visitAsync(state, root, 0);
+    return finish(state);
+}

package/dist/providers/types.d.ts

@@ -11,6 +11,7 @@
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
 import type { SessionEvent, SubagentStats, TokenUsage, ContextAttribution } from '../types/sessionEvent';
 import { SESSION_PROVIDER_IDS } from '../providerIds';
+import type { AggregatedCostProvenance } from '../aggregation/types';
 /** Stable runtime list for consumers that must enumerate session providers. */
 export { SESSION_PROVIDER_IDS } from '../providerIds';
 export type ProviderId = (typeof SESSION_PROVIDER_IDS)[number];
@@ -58,6 +59,12 @@ export interface SessionFileInfo {
     /** Optional provider-recorded creation timestamp. */
     createdAt?: Date;
 }
+/** How much of a session `readSessionStats()` could read. */
+export type SessionFileStatsAvailability = 'full' | 'partial' | 'unavailable';
+/**
+ * Aggregated stats for one session file, computed by `computeSessionFileStats()`
+ * over the shared `EventAggregator` for every provider.
+ */
 export interface SessionFileStats {
     providerId: ProviderId;
     sessionId: string;
@@ -66,19 +73,42 @@ export interface SessionFileStats {
     startTime: string;
     endTime: string;
     messageCount: number;
+    /** Token buckets; `summarizeTokens()` turns them into the cache-inclusive total. */
     tokens: {
         input: number;
         output: number;
         cacheWrite: number;
         cacheRead: number;
     };
+    /**
+     * Per-model calls, cache-inclusive token total (the `summarizeTokens().total`
+     * vocabulary), priced cost, and whether every call could be priced.
+     */
     modelUsage: Record<string, {
         calls: number;
         tokens: number;
+        costUsd: number;
+        priced: boolean;
     }>;
+    /** Calls per tool name: successful, failed, and still pending. */
     toolUsage: Record<string, number>;
+    /** Failed calls per tool name; a subset of `toolUsage`. */
+    toolFailures: Record<string, number>;
     compactionEstimate: number;
     truncationCount: number;
+    /** Cost of the priced portion of the session; read `costProvenance` before labelling it. */
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    /** Usage events with neither a provider-reported cost nor a catalog price. */
+    unpricedCalls: number;
+    /**
+     * `full` when every event was read, `partial` when the reader reported a
+     * truncated source, `unavailable` when the session could not be read at all
+     * (`unavailableReason` says why and every number is zero).
+     */
+    availability: SessionFileStatsAvailability;
+    unavailableReason?: string;
+    /** @deprecated Same value as `costUsd`; use it together with `costProvenance`. */
     reportedCost: number;
 }
 export interface ProjectFolderInfo {