sidekick-shared 0.27.5 → 0.28.0

package/dist/testing/sessionLogFixtures.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Claude Code and Codex session-log builders shared by the prompt-history
+ * tests, published through `sidekick-shared/testing`.
+ */
+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.ts = ts;
+exports.writeJsonl = writeJsonl;
+exports.appendJsonl = appendJsonl;
+exports.claudeFiller = claudeFiller;
+exports.codexFiller = codexFiller;
+exports.createSessionLogFixtures = createSessionLogFixtures;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const sessionPathResolver_1 = require("../parsers/sessionPathResolver");
+function ts(second) {
+    return new Date(Date.UTC(2026, 8, 1, 10, 0, second)).toISOString();
+}
+function writeJsonl(file, rows) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join('\n') + '\n');
+}
+function appendJsonl(file, rows) {
+    fs.appendFileSync(file, rows.map((row) => JSON.stringify(row)).join('\n') + '\n');
+}
+/** A Claude Code line with no message: read and ignored, like progress records. */
+function claudeFiller(bytes, second) {
+    return { type: 'system', subtype: 'filler', timestamp: ts(second), content: 'f'.repeat(bytes) };
+}
+/** A Codex line that is neither a prompt nor usage. */
+function codexFiller(bytes, second) {
+    return {
+        timestamp: ts(second),
+        type: 'event_msg',
+        payload: { type: 'agent_message', message: 'f'.repeat(bytes) },
+    };
+}
+/** Builders that read the per-test home and repo lazily from `context`. */
+function createSessionLogFixtures(context) {
+    let codexCounter = 0;
+    function claudeFile(workspace, sessionId) {
+        return path.join(context().home, '.claude', 'projects', (0, sessionPathResolver_1.encodeWorkspacePath)(workspace), `${sessionId}.jsonl`);
+    }
+    function claudeUser(content, second, extra = {}) {
+        return {
+            type: 'user',
+            entrypoint: 'cli',
+            cwd: context().repo,
+            gitBranch: 'main',
+            timestamp: ts(second),
+            message: { role: 'user', content },
+            ...extra,
+        };
+    }
+    /** One Claude Code assistant record; `message` fields are merged over the defaults. */
+    function claudeAssistant(id, second, extra = {}, message = {}) {
+        return {
+            type: 'assistant',
+            entrypoint: 'cli',
+            cwd: context().repo,
+            timestamp: ts(second),
+            message: {
+                id,
+                role: 'assistant',
+                model: 'claude-opus-5',
+                content: [{ type: 'text', text: 'ok' }],
+                stop_reason: 'end_turn',
+                usage: {
+                    input_tokens: 10,
+                    output_tokens: 20,
+                    cache_read_input_tokens: 30,
+                    cache_creation_input_tokens: 40,
+                },
+                ...message,
+            },
+            ...extra,
+        };
+    }
+    function codexFile() {
+        codexCounter++;
+        const id = `019d86b0-b20c-7b02-a3b2-${String(codexCounter).padStart(12, '0')}`;
+        return path.join(context().home, '.codex', 'sessions', '2026', '09', '01', `rollout-2026-09-01T10-00-${String(codexCounter).padStart(2, '0')}-${id}.jsonl`);
+    }
+    function codexMeta(cwd, source = 'cli', extra = {}) {
+        return {
+            timestamp: ts(0),
+            type: 'session_meta',
+            payload: {
+                id: 'meta',
+                timestamp: ts(0),
+                ...(cwd !== undefined ? { cwd } : {}),
+                originator: 'codex-tui',
+                source,
+                git: { branch: 'feature/x' },
+                ...extra,
+            },
+        };
+    }
+    function codexUser(texts, second) {
+        return {
+            timestamp: ts(second),
+            type: 'response_item',
+            payload: {
+                type: 'message',
+                role: 'user',
+                content: texts.map((text) => ({ type: 'input_text', text })),
+            },
+        };
+    }
+    function codexTokenCount(second) {
+        return {
+            timestamp: ts(second),
+            type: 'event_msg',
+            payload: {
+                type: 'token_count',
+                info: {
+                    last_token_usage: {
+                        input_tokens: 100,
+                        cached_input_tokens: 60,
+                        output_tokens: 7,
+                        cache_write_input_tokens: 5,
+                    },
+                },
+            },
+        };
+    }
+    return {
+        claudeFile,
+        claudeUser,
+        claudeAssistant,
+        codexFile,
+        codexMeta,
+        codexUser,
+        codexTokenCount,
+    };
+}

package/dist/tokenEstimation.d.ts

@@ -13,6 +13,8 @@ export interface TokenEstimate {
     confidence: TokenEstimationConfidence;
     provenance: string;
 }
+/** Latin/source-code characters per token in the fallback estimate. */
+export declare const ASCII_CHARS_PER_TOKEN = 3.5;
 /**
  * Estimate tokens without bundling a tokenizer.
  *

package/dist/tokenEstimation.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASCII_CHARS_PER_TOKEN = void 0;
 exports.estimateTextTokens = estimateTextTokens;
 exports.estimateSerializedTokens = estimateSerializedTokens;
+/** Latin/source-code characters per token in the fallback estimate. */
+exports.ASCII_CHARS_PER_TOKEN = 3.5;
 const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
 const EMOJI = /\p{Extended_Pictographic}/u;
 /**
@@ -30,19 +33,26 @@ function estimateTextTokens(text, options = {}) {
             provenance: options.model ?? 'injected-counter',
         };
     }
-    let asciiChars = 0;
+    // ASCII is never CJK or pictographic, so the leading ASCII run is counted
+    // without the per-code-point regex tests; most source text is all ASCII.
+    let firstNonAscii = 0;
+    while (firstNonAscii < text.length && text.charCodeAt(firstNonAscii) <= 127)
+        firstNonAscii++;
+    let asciiChars = firstNonAscii;
     let conservativeTokens = 0;
-    for (const codePoint of text) {
-        if (EMOJI.test(codePoint))
-            conservativeTokens += 2;
-        else if (CJK.test(codePoint))
-            conservativeTokens += 1;
-        else if ((codePoint.codePointAt(0) ?? 128) <= 127)
-            asciiChars += codePoint.length;
-        else
-            conservativeTokens += 1;
+    if (firstNonAscii < text.length) {
+        for (const codePoint of text.slice(firstNonAscii)) {
+            if (EMOJI.test(codePoint))
+                conservativeTokens += 2;
+            else if (CJK.test(codePoint))
+                conservativeTokens += 1;
+            else if ((codePoint.codePointAt(0) ?? 128) <= 127)
+                asciiChars += codePoint.length;
+            else
+                conservativeTokens += 1;
+        }
     }
-    const count = Math.ceil(asciiChars / 3.5) + conservativeTokens;
+    const count = Math.ceil(asciiChars / exports.ASCII_CHARS_PER_TOKEN) + conservativeTokens;
     return {
         count: Number.isFinite(count) && count >= 0 ? count : 0,
         method: 'sidekick-fallback-v1',

package/dist/toolCategory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * One vocabulary for what a tool call does, across Claude Code, Codex, and
+ * OpenCode tool names. Browser-safe: no Node imports.
+ *
+ * @module toolCategory
+ */
+export declare const TOOL_CATEGORIES: readonly ["shell", "file_read", "file_edit", "search", "web", "subagent", "planning", "mcp", "other"];
+export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
+export interface ClassifyToolOptions {
+    /** The MCP server the call went to, when the log records it separately (Codex). */
+    mcpServer?: string;
+}
+/**
+ * Classifies a tool name from any supported provider. `mcp__<server>__<tool>`
+ * names and calls with a known `mcpServer` are `mcp`; unknown names are
+ * `other`.
+ */
+export declare function classifyTool(name: string, options?: ClassifyToolOptions): ToolCategory;

package/dist/toolCategory.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * One vocabulary for what a tool call does, across Claude Code, Codex, and
+ * OpenCode tool names. Browser-safe: no Node imports.
+ *
+ * @module toolCategory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_CATEGORIES = void 0;
+exports.classifyTool = classifyTool;
+const mcpToolName_1 = require("./parsers/mcpToolName");
+exports.TOOL_CATEGORIES = [
+    'shell',
+    'file_read',
+    'file_edit',
+    'search',
+    'web',
+    'subagent',
+    'planning',
+    'mcp',
+    'other',
+];
+/** Lower-cased tool names of every provider, by category. */
+const CATEGORY_BY_NAME = new Map([
+    [
+        'shell',
+        [
+            'bash',
+            'bashoutput',
+            'killbash',
+            'killshell',
+            'exec_command',
+            'shell',
+            'local_shell',
+            'local_shell_call',
+            'container.exec',
+            'write_stdin',
+        ],
+    ],
+    ['file_read', ['read', 'notebookread', 'ls', 'list', 'view_image']],
+    [
+        'file_edit',
+        ['edit', 'multiedit', 'write', 'notebookedit', 'apply_patch', 'patch', 'patch_applied'],
+    ],
+    ['search', ['grep', 'glob', 'codesearch', 'toolsearch']],
+    ['web', ['webfetch', 'websearch', 'web_search', 'web_search_call', 'fetch']],
+    [
+        'subagent',
+        [
+            'task',
+            'agent',
+            'spawn_agent',
+            'wait_agent',
+            'send_message',
+            'followup_task',
+            'list_agents',
+            'wait',
+        ],
+    ],
+    [
+        'planning',
+        [
+            'todowrite',
+            'todoread',
+            'update_plan',
+            'updateplan',
+            'enterplanmode',
+            'exitplanmode',
+            'taskcreate',
+            'taskupdate',
+            'tasklist',
+            'askuserquestion',
+            'request_user_input',
+        ],
+    ],
+].flatMap(([category, names]) => names.map((name) => [name, category])));
+/**
+ * Classifies a tool name from any supported provider. `mcp__<server>__<tool>`
+ * names and calls with a known `mcpServer` are `mcp`; unknown names are
+ * `other`.
+ */
+function classifyTool(name, options = {}) {
+    if (options.mcpServer || (0, mcpToolName_1.parseMcpToolName)(name))
+        return 'mcp';
+    return CATEGORY_BY_NAME.get(name.trim().toLowerCase()) ?? 'other';
+}

package/dist/types/codex.d.ts

@@ -291,4 +291,8 @@ export interface CodexDbThread {
     source?: string;
     agent_nickname?: string | null;
     agent_role?: string | null;
+    /** 1 once the thread is archived; Codex then moves its rollout to `archived_sessions/`. */
+    archived?: number;
+    /** Unix seconds when the thread was archived. */
+    archived_at?: number | null;
 }

package/dist/usage/usageEvents.d.ts

@@ -50,6 +50,8 @@ export interface UsageEventRecord {
     };
     costUsd: number | null;
     costProvenance: PricingProvenance;
+    /** Session file the event came from; tells apart two files with one session id. */
+    filePath?: string;
 }
 /** One session that contributed events. */
 export interface UsageSessionRecord {
@@ -71,6 +73,18 @@ export interface CollectUsageEventsOptions {
     until?: Date | string;
     /** Restrict to one workspace's sessions. */
     workspacePath?: string;
+    /**
+     * Restrict to the sessions of several workspaces, listed once each and
+     * counted once even when roots overlap. Takes precedence over
+     * `workspacePath`. Roots that do not resolve are dropped; when none
+     * resolves, no session is read.
+     */
+    workspacePaths?: string[];
+    /**
+     * Also list each root's main checkout and git worktree siblings. Default
+     * true with `workspacePaths`, false with `workspacePath`.
+     */
+    includeWorktrees?: boolean;
     /** Preview-read concurrency (see `listSessionPreviewsAsync`). */
     concurrency?: number;
     /** Cache directory (default `<configDir>/usage-cache`). */
@@ -93,6 +107,8 @@ export interface CollectUsageEventsResult {
     diagnostics: SessionProviderDiagnostic[];
     cacheHits: number;
     cacheMisses: number;
+    /** Realpaths of the roots listed, after worktree expansion, when the call was scoped. */
+    roots?: string[];
 }
 export declare function getUsageCacheDir(): string;
 /** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */

package/dist/usage/usageEvents.js

@@ -64,6 +64,7 @@ const paths_1 = require("../paths");
 const sessionPreviews_1 = require("../sessionPreviews");
 const usageNormalization_1 = require("../usageNormalization");
 const atomic_1 = require("../writers/atomic");
+const workspaceRoots_1 = require("../workspaceRoots");
 /**
  * Bump when the cached record shape or the counting rules change; older files
  * are re-read. v2: Claude split lines and duplicate Codex `token_count` events
@@ -162,7 +163,7 @@ function cachedEventFromUsage(usage, timestamp, model) {
     return record;
 }
 /** Price a cached event with the current catalog (or its provider-reported cost). */
-function priceCachedEvent(cached, provider, sessionId, project) {
+function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
     const usage = {
         uncachedInputTokens: cached.i,
         cacheReadTokens: cached.cr,
@@ -195,6 +196,7 @@ function priceCachedEvent(cached, provider, sessionId, project) {
         },
         costUsd: priced.costUsd,
         costProvenance: priced.source,
+        filePath: sessionFile,
     };
 }
 const CLAUDE_AGENT_FILE = /^agent-.+\.jsonl$/;
@@ -292,12 +294,8 @@ async function collectUsageEvents(options) {
     const useCache = !options.noCache;
     const signal = options.signal;
     signal?.throwIfAborted();
-    const listed = await (0, sessionPreviews_1.listSessionPreviewsAsync)(options.providers, {
-        since: options.since,
-        workspacePath: options.workspacePath,
-        limit: Number.MAX_SAFE_INTEGER,
-        concurrency: options.concurrency,
-    });
+    const scope = usageScope(options);
+    const listed = await listScopedPreviews(options, scope?.listingRoots);
     signal?.throwIfAborted();
     const diagnostics = [...listed.diagnostics];
     for (const diagnostic of listed.diagnostics)
@@ -373,7 +371,7 @@ async function collectUsageEvents(options) {
                 continue;
             if (untilMs !== null && cached.t > untilMs)
                 continue;
-            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project));
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath));
             first = first === null ? cached.t : Math.min(first, cached.t);
             last = last === null ? cached.t : Math.max(last, cached.t);
             count += 1;
@@ -393,5 +391,51 @@ async function collectUsageEvents(options) {
     if (wroteCache)
         pruneUsageCache(exports.MAX_USAGE_CACHE_FILES, cacheDir);
     events.sort((a, b) => a.timestamp - b.timestamp);
-    return { events, sessions, diagnostics, cacheHits, cacheMisses };
+    return {
+        events,
+        sessions,
+        diagnostics,
+        cacheHits,
+        cacheMisses,
+        ...(scope ? { roots: scope.roots } : {}),
+    };
+}
+/** The roots to list, or undefined for an unscoped (or legacy single-root) call. */
+function usageScope(options) {
+    if (options.workspacePaths) {
+        return (0, workspaceRoots_1.resolveWorkspaceRoots)(options.workspacePaths, {
+            includeWorktrees: options.includeWorktrees !== false,
+        });
+    }
+    if (options.workspacePath && options.includeWorktrees === true) {
+        return (0, workspaceRoots_1.resolveWorkspaceRoots)([options.workspacePath], { includeWorktrees: true });
+    }
+    return undefined;
+}
+/** Lists previews once per root and keeps each session file once. */
+async function listScopedPreviews(options, listingRoots) {
+    const list = (workspacePath) => (0, sessionPreviews_1.listSessionPreviewsAsync)(options.providers, {
+        since: options.since,
+        workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+        concurrency: options.concurrency,
+    });
+    if (!listingRoots)
+        return list(options.workspacePath);
+    const byFile = new Map();
+    const diagnostics = new Map();
+    for (const root of listingRoots) {
+        options.signal?.throwIfAborted();
+        const listed = await list(root);
+        // Each root lists every provider again; report each problem once.
+        for (const diagnostic of listed.diagnostics) {
+            diagnostics.set(JSON.stringify(diagnostic), diagnostic);
+        }
+        for (const preview of listed.previews) {
+            if (!byFile.has(preview.filePath))
+                byFile.set(preview.filePath, preview);
+        }
+    }
+    const previews = [...byFile.values()].sort((left, right) => Date.parse(right.modifiedAt) - Date.parse(left.modifiedAt));
+    return { previews, diagnostics: [...diagnostics.values()] };
 }

package/dist/watchers/jsonlTail.d.ts

@@ -3,11 +3,30 @@
  * their own aggregation lifecycle.
  */
 import type { ZodType } from 'zod';
+/** Default bytes read from the file per chunk. */
+export declare const DEFAULT_JSONL_TAIL_READ_BYTES: number;
+/** Default longest line parsed; longer lines are skipped and reported. */
+export declare const DEFAULT_JSONL_TAIL_MAX_LINE_BYTES: number;
 export interface JsonlTailBatch {
     bytesRead: number;
     eventsRead: number;
     offset: number;
 }
+/** Where an event's line sits in the file. */
+export interface JsonlTailLine {
+    /** Byte offset where the line starts. */
+    offset: number;
+    /** Line length in bytes, without the newline. */
+    length: number;
+}
+export type JsonlTailResetReason = 'truncated' | 'rewritten' | 'replaced';
+/** The tail started over from the beginning of the file. */
+export interface JsonlTailReset {
+    /** `truncated`: the file shrank; `rewritten`: its first bytes or the resume point changed; `replaced`: another file now has the path. */
+    reason: JsonlTailResetReason;
+    /** The committed offset before the reset. */
+    previousOffset: number;
+}
 export interface JsonlTailOptions<T> {
     path: string;
     schema?: ZodType<T>;
@@ -15,9 +34,15 @@ export interface JsonlTailOptions<T> {
     startAtEnd?: boolean;
     debounceMs?: number;
     catchupIntervalMs?: number;
-    onEvent: (event: T) => void;
+    onEvent: (event: T, line: JsonlTailLine) => void;
     onBatchComplete?: (batch: JsonlTailBatch) => void;
     onError?: (error: Error, line?: string) => void;
+    /** Called after the tail resets to offset 0; events from the start follow. */
+    onReset?: (reset: JsonlTailReset) => void;
+    /** Bytes read per chunk (default 1 MiB); one poll reads chunk by chunk to the end. */
+    maxReadBytes?: number;
+    /** Longest line parsed (default 16 MiB); a longer line is skipped and reported to `onError`. */
+    maxLineBytes?: number;
 }
 export interface JsonlTail {
     readonly isActive: boolean;