sidekick-shared 0.28.2 → 0.29.0

package/dist/toolCallOrigins.js

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * Locates the session record that issued each of a set of tool calls, by id.
+ *
+ * Given Claude Code `tool_use` ids (`toolu_…`) and/or Codex `call_id`s, finds
+ * the session file, session id and time of each call, plus the ordinal of the
+ * human prompt the call answered, so a downstream record (an edit, a commit)
+ * can be tied back to the prompt that caused it. Scope, listing, session keys
+ * and ordinals are the ones `collectPromptHistory()` uses, so results join
+ * directly with prompt-history entries.
+ *
+ * Cost: one listing of the workspace-scoped session files (`since` prunes by
+ * modification time), then a streaming pass over each candidate file in which
+ * a line is only parsed when it contains one of the wanted ids. Claude Code
+ * subagent transcripts of each session are searched too. Stops as soon as
+ * every id is found. Prompt ordinals are read only for files that matched.
+ *
+ * Node-only: reads session files.
+ *
+ * @module toolCallOrigins
+ */
+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.findToolCallOrigins = findToolCallOrigins;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const promptHistory_1 = require("./promptHistory");
+const codexRolloutOrigin_1 = require("./parsers/codexRolloutOrigin");
+const workspaceRoots_1 = require("./workspaceRoots");
+/**
+ * Finds where each tool call was issued. Ids that are not found are absent
+ * from the result. When an id appears more than once (a forked or resumed
+ * session can replay history), the earliest record wins, and a session's own
+ * record wins over a fork's copy at the same instant.
+ */
+async function findToolCallOrigins(options) {
+    const wanted = new Set([...options.ids].filter((id) => typeof id === 'string' && id.length > 0));
+    const found = new Map();
+    if (wanted.size === 0)
+        return found;
+    throwIfAborted(options.signal);
+    const realpaths = new Map();
+    const { roots, listingRoots } = (0, promptHistory_1.resolveRoots)(options.workspacePaths, options.includeWorktrees !== false, realpaths);
+    if (roots.length === 0)
+        return found;
+    const providers = options.providers ?? ['claude-code', 'codex'];
+    const sinceMs = options.since ? options.since.getTime() : null;
+    const candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs);
+    const byProviderSession = new Map();
+    for (const candidate of candidates) {
+        byProviderSession.set(`${candidate.provider}:${candidate.sessionId}`, candidate);
+    }
+    const marksCache = new Map();
+    const marksFor = (candidate) => {
+        let marks = marksCache.get(candidate.key);
+        if (!marks) {
+            marks = (0, promptHistory_1.readPromptOrdinalMarks)(candidate.provider, candidate.sessionId, candidate.filePath).catch(() => []);
+            marksCache.set(candidate.key, marks);
+        }
+        return marks;
+    };
+    const remaining = new Set(wanted);
+    // Best timestamp seen per id, to prefer the earliest record across files.
+    const bestMs = new Map();
+    for (const candidate of candidates) {
+        if (remaining.size === 0)
+            break;
+        throwIfAborted(options.signal);
+        const targets = [{ candidate, filePath: candidate.filePath }];
+        if (candidate.provider === 'claude-code') {
+            for (const sub of claudeSubagentTranscripts(candidate.filePath, candidate.sessionId)) {
+                targets.push({ candidate, filePath: sub.filePath, agentId: sub.agentId });
+            }
+        }
+        // A Codex fork or spawned subagent answers its parent's prompts.
+        let codexParent;
+        if (candidate.provider === 'codex') {
+            const origin = (0, codexRolloutOrigin_1.codexRolloutOrigin)(await readFirstRecord(candidate.filePath));
+            if (origin.parentId)
+                codexParent = { id: origin.parentId, fork: !origin.isSubagent };
+        }
+        for (const target of targets) {
+            const hits = await scanForIds(target.filePath, candidate.provider, remaining, roots, realpaths, options.signal);
+            for (const hit of hits) {
+                const isFork = codexParent?.fork === true;
+                const previous = bestMs.get(hit.id);
+                if (previous &&
+                    (previous.ms < hit.timestampMs ||
+                        (previous.ms === hit.timestampMs && (!previous.fork || isFork)))) {
+                    continue;
+                }
+                bestMs.set(hit.id, { ms: hit.timestampMs, fork: isFork });
+                let subagent;
+                if (target.agentId) {
+                    subagent = { agentId: target.agentId, parentSessionId: candidate.sessionId };
+                }
+                else if (codexParent && !codexParent.fork) {
+                    subagent = { agentId: candidate.sessionId, parentSessionId: codexParent.id };
+                }
+                // Ordinals come from the session whose prompts the call answered: a
+                // Codex fork or subagent has none of its own, so its parent's count.
+                const parentSession = codexParent
+                    ? byProviderSession.get(`codex:${codexParent.id}`)
+                    : undefined;
+                const session = parentSession ?? candidate;
+                const afterOrdinal = !codexParent || parentSession
+                    ? ordinalAt(await marksFor(session), hit.timestampMs)
+                    : null;
+                found.set(hit.id, {
+                    provider: candidate.provider,
+                    sessionId: session.sessionId,
+                    sessionKey: session.key,
+                    filePath: target.filePath,
+                    timestamp: hit.timestamp,
+                    afterOrdinal,
+                    ...(hit.toolName ? { toolName: hit.toolName } : {}),
+                    ...(subagent ? { subagent } : {}),
+                });
+                // A fork's copy might be replaced by the original later; keep looking.
+                if (!isFork)
+                    remaining.delete(hit.id);
+            }
+            if (remaining.size === 0)
+                break;
+        }
+    }
+    return found;
+}
+/** Highest ordinal among prompts at or before `ms`; marks are in file order. */
+function ordinalAt(marks, ms) {
+    let best = null;
+    for (const mark of marks) {
+        if (Number.isFinite(mark.timestampMs) && mark.timestampMs <= ms) {
+            if (best === null || mark.ordinal > best)
+                best = mark.ordinal;
+        }
+    }
+    return best;
+}
+function claudeSubagentTranscripts(sessionFile, sessionId) {
+    const dir = path.join(path.dirname(sessionFile), sessionId, 'subagents');
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith('.jsonl'))
+        .sort()
+        .map((name) => ({
+        filePath: path.join(dir, name),
+        agentId: path.basename(name, '.jsonl').replace(/^agent-/, ''),
+    }));
+}
+async function readFirstRecord(filePath) {
+    let handle;
+    try {
+        handle = await fs.promises.open(filePath, 'r');
+        const buffer = Buffer.alloc(256 * 1024);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const text = buffer.subarray(0, bytesRead).toString('utf8');
+        const newline = text.indexOf('\n');
+        return JSON.parse(newline === -1 ? text : text.slice(0, newline));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** Fail-closed scope check on a recorded working directory. */
+function inScope(cwd, roots, realpaths) {
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        return false;
+    const real = (0, workspaceRoots_1.realpathOrNull)(cwd, realpaths);
+    if (!real)
+        return false;
+    return roots.some((root) => {
+        if (real === root)
+            return true;
+        const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+        return real.startsWith(prefix);
+    });
+}
+const ID_PATTERN = /"(?:id|call_id)"\s*:\s*"([^"\\]{1,256})"/g;
+async function scanForIds(filePath, provider, wanted, roots, realpaths, signal) {
+    const hits = [];
+    let stream;
+    try {
+        stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+    }
+    catch {
+        return hits;
+    }
+    const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    // Codex records a working directory per session/turn, not per line.
+    let codexCwd;
+    try {
+        for await (const line of lines) {
+            throwIfAborted(signal);
+            if (provider === 'codex' && line.includes('"cwd"')) {
+                const cwd = codexCwdOf(line);
+                if (cwd !== undefined)
+                    codexCwd = cwd;
+            }
+            let match = false;
+            for (const found of line.matchAll(ID_PATTERN)) {
+                if (wanted.has(found[1])) {
+                    match = true;
+                    break;
+                }
+            }
+            if (!match)
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const lineHits = provider === 'claude-code' ? claudeToolUses(record, wanted) : codexToolCall(record, wanted);
+            if (lineHits.length === 0)
+                continue;
+            const cwd = provider === 'claude-code' ? record.cwd : codexCwd;
+            if (!inScope(cwd, roots, realpaths))
+                continue;
+            hits.push(...lineHits);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        // Unreadable or vanished file: keep what was found.
+    }
+    finally {
+        lines.close();
+        stream.destroy();
+    }
+    return hits;
+}
+function codexCwdOf(line) {
+    try {
+        const record = JSON.parse(line);
+        if (record.type === 'session_meta' || record.type === 'turn_context') {
+            return record.payload?.cwd;
+        }
+    }
+    catch {
+        // Not a complete record.
+    }
+    return undefined;
+}
+function timeOf(record) {
+    const timestamp = record.timestamp;
+    if (typeof timestamp !== 'string')
+        return null;
+    const timestampMs = Date.parse(timestamp);
+    return Number.isFinite(timestampMs) ? { timestamp, timestampMs } : null;
+}
+function claudeToolUses(record, wanted) {
+    const row = record;
+    if (row?.type !== 'assistant' || !Array.isArray(row.message?.content))
+        return [];
+    const time = timeOf(record);
+    if (!time)
+        return [];
+    const hits = [];
+    for (const block of row.message.content) {
+        const item = block;
+        if ((item?.type === 'tool_use' || item?.type === 'server_tool_use') &&
+            typeof item.id === 'string' &&
+            wanted.has(item.id)) {
+            hits.push({
+                id: item.id,
+                ...time,
+                ...(typeof item.name === 'string' ? { toolName: item.name } : {}),
+            });
+        }
+    }
+    return hits;
+}
+function codexToolCall(record, wanted) {
+    const row = record;
+    const payloadType = row?.payload?.type;
+    if (row?.type !== 'response_item' ||
+        typeof payloadType !== 'string' ||
+        !payloadType.endsWith('_call')) {
+        return [];
+    }
+    const callId = row.payload?.call_id;
+    if (typeof callId !== 'string' || !wanted.has(callId))
+        return [];
+    const time = timeOf(record);
+    if (!time)
+        return [];
+    const name = row.payload?.name;
+    return [
+        {
+            id: callId,
+            ...time,
+            toolName: typeof name === 'string' ? name : payloadType.replace(/_call$/, ''),
+        },
+    ];
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw (signal.reason ?? Object.assign(new Error('The operation was aborted'), { name: 'AbortError' }));
+    }
+}

package/dist/transcript.d.ts

@@ -32,6 +32,13 @@ export interface CanonicalTranscriptBlock {
     command?: string;
     truncated?: boolean;
     raw?: unknown;
+    /**
+     * The provider's own tool name before normalization (for example Codex
+     * `exec_command` behind `Bash`), when the parser recorded one.
+     */
+    rawToolName?: string;
+    /** The MCP server that served this tool call, when the parser recorded one. */
+    mcpServerName?: string;
 }
 export interface CanonicalTranscriptMessage {
     id?: string;
@@ -51,10 +58,15 @@ export interface CanonicalToolCall {
     id?: string;
     name: string;
     timestamp: string;
+    /** Tool input without the parsers' internal `_sidekick*` bookkeeping keys. */
     input?: unknown;
     output?: unknown;
     isError?: boolean;
     command?: string;
+    /** The provider's own tool name before normalization, when recorded. */
+    rawToolName?: string;
+    /** The MCP server that served this tool call, when recorded. */
+    mcpServerName?: string;
     source: TranscriptSourceProvenance;
 }
 export interface CanonicalTranscriptUsageTotals {

package/dist/transcript.js

@@ -66,10 +66,12 @@ function projectSessionTranscript(events, options = {}) {
             blocks.push({ type: 'text', ...boundedText(event.summary, fidelity, maxContentChars) });
         }
         if (event.type === 'tool_use') {
+            const projected = projectToolInput(event.tool.input);
             blocks.push({
                 type: 'tool_use',
                 toolName: event.tool.name,
-                input: boundedValue(event.tool.input, fidelity, maxContentChars),
+                input: boundedValue(projected.input, fidelity, maxContentChars),
+                ...toolIdentity(projected),
             });
         }
         if (event.type === 'tool_result') {
@@ -90,6 +92,7 @@ function projectSessionTranscript(events, options = {}) {
                     timestamp: event.timestamp,
                     input: block.input,
                     command,
+                    ...toolIdentity(block),
                     source,
                 };
                 tools.push(call);
@@ -186,12 +189,14 @@ function contentBlocks(content, fidelity, maxChars, includeUnknown = false) {
             });
         }
         else if (block.type === 'tool_use' && typeof block.name === 'string') {
+            const projected = projectToolInput(block.input);
             result.push({
                 type: 'tool_use',
                 toolName: block.name,
                 toolUseId: typeof block.id === 'string' ? block.id : undefined,
-                input: boundedValue(block.input, fidelity, maxChars),
-                command: commandFromTool(block.name, block.input),
+                input: boundedValue(projected.input, fidelity, maxChars),
+                command: commandFromTool(block.name, projected.input),
+                ...toolIdentity(projected),
             });
         }
         else if (block.type === 'tool_result') {
@@ -215,6 +220,40 @@ function contentBlocks(content, fidelity, maxChars, includeUnknown = false) {
     }
     return result;
 }
+/** Prefix of the bookkeeping keys session parsers stash inside tool inputs. */
+const SIDEKICK_INPUT_KEY_PREFIX = '_sidekick';
+/**
+ * Lifts the parsers' `_sidekickRawToolName` / `_sidekickMcpServerName` out of
+ * a tool input and drops every other top-level `_sidekick*` key. Returns a
+ * copy when anything is removed; the source event is never modified.
+ */
+function projectToolInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return { input };
+    const source = input;
+    const keys = Object.keys(source);
+    if (!keys.some((key) => key.startsWith(SIDEKICK_INPUT_KEY_PREFIX)))
+        return { input };
+    const clean = {};
+    for (const key of keys) {
+        if (!key.startsWith(SIDEKICK_INPUT_KEY_PREFIX))
+            clean[key] = source[key];
+    }
+    return {
+        input: clean,
+        rawToolName: nonEmptyString(source._sidekickRawToolName),
+        mcpServerName: nonEmptyString(source._sidekickMcpServerName),
+    };
+}
+function toolIdentity(value) {
+    return {
+        ...(value.rawToolName ? { rawToolName: value.rawToolName } : {}),
+        ...(value.mcpServerName ? { mcpServerName: value.mcpServerName } : {}),
+    };
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
 function boundedText(text, fidelity, maxChars) {
     if (fidelity === 'full' || text.length <= maxChars)
         return { text, truncated: false };

package/dist/types/opencode.d.ts

@@ -42,6 +42,8 @@ export interface OpenCodeMessage {
         cacheRead?: number;
         cacheWrite?: number;
         reasoning?: number;
+        /** Provider-reported total; tells OpenCode's token layouts apart (see `normalizeOpenCodeUsage`). */
+        total?: number;
     };
     time: {
         created: string | number;

package/dist/usage/usageEvents.d.ts

@@ -11,9 +11,19 @@
  * every hit and pruned least-recently-used, once per collection.
  *
  * A Claude Code session's subagents write their own transcripts under
- * `<sessionId>/subagents/`; their usage is attributed to the parent session
- * and their sizes and mtimes join the fingerprint. (Codex spawned subagents
- * are top-level rollouts, already listed as sessions of their own.)
+ * `<sessionId>/subagents/`; their usage is attributed to the parent session,
+ * tagged with the subagent, and their sizes and mtimes join the fingerprint.
+ * (Codex spawned subagents and forks are top-level rollouts, already listed
+ * as sessions of their own; their events are tagged with the parent read
+ * from the rollout's first line.)
+ *
+ * Each event also carries the ordinal of the human prompt it answered, from
+ * the same scanner as `collectPromptHistory()`, so usage joins prompt history
+ * on `(provider, sessionId, ordinal)`.
+ *
+ * Cache files are named per cache version (`<provider>--<session>.v3.json`)
+ * so readers of different versions sharing the directory never overwrite each
+ * other's files; pruning ages out every version's files alike.
  *
  * Node-only: reads session files and the cache directory.
  *
@@ -25,9 +35,11 @@ import type { PricingProvenance } from '../usageNormalization';
 /**
  * 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
- * are counted once, and Claude subagent transcripts are included.
+ * are counted once, and Claude subagent transcripts are included. v3: events
+ * keep reasoning tokens, prompt ordinal, message id, and subagent, and files
+ * move to a versioned name (`<provider>--<session>.v3.json`).
  */
-export declare const USAGE_CACHE_VERSION = 2;
+export declare const USAGE_CACHE_VERSION = 3;
 /**
  * Most-recently-used cache files kept on disk. Sized for a busy month of
  * sessions (files are a few KB each); a collection larger than this still
@@ -47,11 +59,43 @@ export interface UsageEventRecord {
     /** Four buckets plus the provider-semantics-aware total. */
     tokens: TokenTotals & {
         totalTokens: number;
+        /**
+         * Reasoning tokens the provider reported, when any. Informational, never
+         * added to a total: Codex counts them inside `outputTokens`; OpenCode
+         * reports them apart, inside `totalTokens` but not `outputTokens`.
+         */
+        reasoningTokens?: number;
     };
     costUsd: number | null;
     costProvenance: PricingProvenance;
     /** Session file the event came from; tells apart two files with one session id. */
     filePath?: string;
+    /**
+     * Ordinal of the human prompt this call followed: the highest ordinal among
+     * the session's prompts timestamped at or before the event, as
+     * `collectPromptHistory()` numbers them with default bounds. Claude Code
+     * subagent calls map to the parent session's prompts. `null` when no prompt
+     * precedes the call, or the session has none (a Codex subagent or fork is a
+     * session of its own without human prompts). Absent when
+     * unknown: a provider without prompt history (OpenCode), or a cache entry
+     * written before prompt ordinals were recorded.
+     */
+    promptOrdinal?: number | null;
+    /**
+     * The provider's message id for the call (Claude Code, OpenCode). Absent for
+     * Codex, whose `token_count` lines carry no request id (the reader's
+     * timestamp-derived placeholder is not passed through).
+     */
+    requestId?: string;
+    /**
+     * Set when a subagent made the call. Claude Code: the agent id from its
+     * transcript name (`agent-<id>.jsonl`), parent = this session. Codex: the
+     * forked or spawned rollout's own session id and the session it came from.
+     */
+    subagent?: {
+        agentId: string;
+        parentSessionId: string;
+    };
 }
 /** One session that contributed events. */
 export interface UsageSessionRecord {
@@ -111,7 +155,11 @@ export interface CollectUsageEventsResult {
     roots?: string[];
 }
 export declare function getUsageCacheDir(): string;
-/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+/**
+ * Deletes all but the `keep` most recently used cache files (by mtime), of
+ * every cache version alike, so files no reader touches any more age out.
+ * Best-effort.
+ */
 export declare function pruneUsageCache(keep?: number, dir?: string): number;
 /**
  * Collect priced usage events for every session touched in the window.