sidekick-shared 0.28.3 → 0.29.1

package/dist/esm/toolCallOrigins.js

@@ -0,0 +1,310 @@
+/**
+ * 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
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { listCandidates, readPromptOrdinalMarks, resolveRoots, } from './promptHistory';
+import { codexRolloutOrigin } from './parsers/codexRolloutOrigin';
+import { realpathOrNull } from './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.
+ */
+export 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 } = 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 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 = 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 = 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 = 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/esm/transcript.js

@@ -1,4 +1,5 @@
 import { calculateNormalizedUsageCost, extractNormalizedUsage, } from './usageNormalization';
+import { isTaskNotificationSystemEvent } from './subagentSpawn';
 const EMPTY_TOTALS = {
     uncachedInputTokens: 0,
     cacheReadTokens: 0,
@@ -25,6 +26,9 @@ export function projectSessionTranscript(events, options = {}) {
     let cwd;
     let gitBranch;
     events.forEach((event, eventIndex) => {
+        // A reader's synthetic notice that a background task finished, not a message.
+        if (isTaskNotificationSystemEvent(event))
+            return;
         if (nonEmpty(event.cwd))
             cwd = event.cwd;
         if (nonEmpty(event.gitBranch))
@@ -63,10 +67,12 @@ export 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') {
@@ -87,6 +93,7 @@ export function projectSessionTranscript(events, options = {}) {
                     timestamp: event.timestamp,
                     input: block.input,
                     command,
+                    ...toolIdentity(block),
                     source,
                 };
                 tools.push(call);
@@ -183,12 +190,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') {
@@ -212,6 +221,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/esm/turns/assistantTurn.js

@@ -1,10 +1,10 @@
 import { formatToolSummary, truncate } from '../formatters/toolSummary';
+import { isSubagentSpawnTool } from '../subagentSpawn';
 const DEFAULT_NARRATION_CHARS = 4000;
 const DEFAULT_REASONING_CHARS = 8000;
 const DEFAULT_PROCESS_STEPS = 60;
 const DEFAULT_REASONING_BLOCKS = 24;
 const DEFAULT_TOOL_INPUT_CHARS = 200;
-const SUBAGENT_TOOL_NAMES = new Set(['Task']);
 const LABEL_MAX = 80;
 const TITLE_RE = /^\s*\*\*([^*\n]+)\*\*[ \t]*(?:\n+([\s\S]*))?$/;
 const TITLE_MAX = 100;
@@ -22,8 +22,9 @@ export function reasoningSummary(text) {
     }
     return { title: null, body: trimmed };
 }
+/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
 export function isAssistantTurnSubagentTool(toolName) {
-    return toolName != null && SUBAGENT_TOOL_NAMES.has(toolName);
+    return isSubagentSpawnTool(toolName);
 }
 export function segmentAssistantTurn(events, options = {}) {
     const maxNarrationChars = options.maxNarrationChars ?? DEFAULT_NARRATION_CHARS;

package/dist/esm/usage/claudeUsageDedupe.js

@@ -59,6 +59,25 @@ export function normalizeClaudeUsage(event) {
         },
     };
 }
+const BUCKET_KEYS = ['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning'];
+/** Entries {@link ClaudeUsageDeduper.exportState} keeps by default. */
+const DEFAULT_EXPORT_LIMIT = 256;
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function bucketsFrom(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const buckets = {};
+    for (const key of BUCKET_KEYS) {
+        const count = record[key];
+        if (!isCount(count))
+            return null;
+        buckets[key] = count;
+    }
+    return buckets;
+}
 function bucketsOf(usage) {
     return {
         input: usage.uncachedInputTokens,
@@ -163,6 +182,55 @@ export class ClaudeUsageDeduper {
     reset() {
         this.seen.clear();
     }
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit = DEFAULT_EXPORT_LIMIT) {
+        const count = limit >= 0 ? Math.min(this.seen.size, Math.floor(limit)) : 0;
+        const entries = [];
+        if (count > 0) {
+            let skip = this.seen.size - count;
+            for (const [id, buckets] of this.seen) {
+                if (skip > 0) {
+                    skip -= 1;
+                    continue;
+                }
+                entries.push([id, { ...buckets }]);
+            }
+        }
+        return { version: 1, entries };
+    }
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state) {
+        if (!state || typeof state !== 'object')
+            return false;
+        const { version, entries } = state;
+        if (version !== 1 || !Array.isArray(entries))
+            return false;
+        const parsed = [];
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || entry.length !== 2)
+                return false;
+            const [id, value] = entry;
+            if (typeof id !== 'string' || id.length === 0)
+                return false;
+            const buckets = bucketsFrom(value);
+            if (!buckets)
+                return false;
+            parsed.push([id, buckets]);
+        }
+        this.seen.clear();
+        for (const [id, buckets] of parsed)
+            this.remember(id, buckets);
+        return true;
+    }
     remember(id, buckets) {
         this.seen.delete(id);
         this.seen.set(id, buckets);