sidekick-shared 0.29.0 → 0.30.0

package/dist/esm/parsers/subagentTraceParser.js

@@ -5,10 +5,13 @@
  * (not just stats) for drill-down trace visualization. Applies noise classification
  * and tool summary formatting from the formatters module.
  *
- * Three-phase parent-child linking:
- * 1. Result-based: match toolUseResult.agentId → parent tool_use_id
- * 2. Team summary: parse <teammate-message> XML blocks
- * 3. Positional fallback: timestamp ordering + proximity
+ * Parent-child linking, exact links first:
+ * 1. Meta `parentAgentId` (Claude Code writes it for nested spawns)
+ * 2. The child's spawning tool_use id (meta `toolUseId`) found in another
+ *    trace's `Agent` / `Task` calls
+ * Only traces without that spawn metadata (older Claude Code) fall back to:
+ * 3. Team summary: parse <teammate-message> XML blocks
+ * 4. Positional fallback: timestamp ordering + proximity
  *
  * @module parsers/subagentTraceParser
  */
@@ -19,6 +22,9 @@ import { isHardNoise, classifyMessage, getSoftNoiseReason } from '../formatters/
 import { ClaudeUsageDeduper, dedupedRawClaudeUsage } from '../usage/claudeUsageDedupe';
 import { addUsageToSubagent } from '../usage/subagentUsage';
 import { readAgentMeta } from './subagentScanner';
+import { SubagentEndTracker } from './subagentEndState';
+import { isSubagentSpawnTool } from '../subagentSpawn';
+import { ownValue } from '../ownKey';
 // ── Constants ──
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
 // ── Public API ──
@@ -50,10 +56,8 @@ export function scanSubagentTraces(sessionDir, sessionId) {
             if (trace)
                 traces.push(trace);
         }
-        // Link parent-child relationships
-        linkTraces(traces);
-        // Return only top-level traces (those without parents)
-        return traces.filter((t) => !t.parentToolUseId);
+        // Link parent-child relationships; returns the traces with no parent agent.
+        return linkTraces(traces);
     }
     catch {
         return [];
@@ -70,6 +74,7 @@ function parseAgentTrace(filePath, agentId) {
         let description;
         const tokens = { agentId, toolCalls: [], inputTokens: 0, outputTokens: 0 };
         const usageDeduper = new ClaudeUsageDeduper();
+        const endTracker = new SubagentEndTracker();
         let startTime;
         let endTime;
         for (const line of lines) {
@@ -79,6 +84,7 @@ function parseAgentTrace(filePath, agentId) {
                 if (!startTime)
                     startTime = timestamp;
                 endTime = timestamp;
+                endTracker.observe(raw);
                 // Build SessionEvent from raw JSONL
                 const sessionEvent = rawToSessionEvent(raw);
                 if (!sessionEvent)
@@ -133,8 +139,8 @@ function parseAgentTrace(filePath, agentId) {
                                 input: block.input || {},
                                 timestamp,
                             });
-                            // Extract agent info from Task tool
-                            if (block.name === 'Task' && block.input) {
+                            // Extract agent info from an Agent/Task spawn
+                            if (isSubagentSpawnTool(block.name) && block.input) {
                                 if (block.input.subagent_type && !agentType) {
                                     agentType = String(block.input.subagent_type);
                                 }
@@ -171,6 +177,16 @@ function parseAgentTrace(filePath, agentId) {
             agentId,
             agentType,
             description,
+            filePath,
+            ...(meta.toolUseId
+                ? { spawnToolUseId: meta.toolUseId, parentToolUseId: meta.toolUseId }
+                : {}),
+            ...(meta.parentAgentId ? { parentAgentId: meta.parentAgentId } : {}),
+            ...(meta.requestShape ? { background: meta.requestShape === 'background' } : {}),
+            ...(meta.finished !== undefined ? { finished: meta.finished } : {}),
+            ...(meta.stoppedByUser !== undefined ? { stoppedByUser: meta.stoppedByUser } : {}),
+            ...(endTime ? { lastActivityAt: endTime } : {}),
+            endedCleanly: endTracker.endedCleanly(),
             events,
             children: [],
             stats: {
@@ -187,6 +203,7 @@ function parseAgentTrace(filePath, agentId) {
                 startTime,
                 endTime,
                 durationMs,
+                endedCleanly: endTracker.endedCleanly(),
             },
         };
     }
@@ -195,23 +212,61 @@ function parseAgentTrace(filePath, agentId) {
     }
 }
 // ── Parent-Child Linking ──
+/**
+ * Nests child traces under their parents and returns the traces with no
+ * parent agent. Exact metadata links come first; the heuristics only place
+ * traces Claude Code recorded no spawn metadata for.
+ */
 function linkTraces(traces) {
     const traceById = new Map();
     for (const trace of traces) {
         traceById.set(trace.agentId, trace);
     }
-    // Phase 1: Result-based linking
-    // Look for tool_result events that contain agentId references
+    const parentOf = new Map();
+    const attach = (parent, child) => {
+        if (parent === child || parentOf.has(child))
+            return false;
+        // Never nest an agent under its own descendant (malformed metadata).
+        for (let up = parent; up; up = parentOf.get(up)) {
+            if (up === child)
+                return false;
+        }
+        parentOf.set(child, parent);
+        parent.children.push(child);
+        return true;
+    };
+    // Phase 1: the meta file names the parent agent
+    for (const child of traces) {
+        const parent = child.parentAgentId ? traceById.get(child.parentAgentId) : undefined;
+        if (parent)
+            attach(parent, child);
+    }
+    // Phase 2: the child's spawning call is in another trace
+    const spawnOwner = new Map();
     for (const trace of traces) {
-        for (const traceEvent of trace.events) {
-            const evt = traceEvent.event;
-            if (evt.type === 'tool_use' && evt.tool?.name === 'Task') {
-                // The tool_use_id from this call should appear as a result in the parent
-                // but we can link via timestamp proximity to child traces
-            }
+        for (const id of spawnToolUseIdsOf(trace)) {
+            if (!spawnOwner.has(id))
+                spawnOwner.set(id, trace);
         }
     }
-    // Phase 2: Team summary linking
+    for (const child of traces) {
+        if (parentOf.has(child) || !child.spawnToolUseId)
+            continue;
+        const parent = spawnOwner.get(child.spawnToolUseId);
+        if (parent && attach(parent, child))
+            child.parentAgentId ??= parent.agentId;
+    }
+    // Heuristic links set parentAgentId and, as before, parentToolUseId to the
+    // parent's agent id.
+    const unresolved = (trace) => !parentOf.has(trace) && !trace.spawnToolUseId && !trace.parentAgentId;
+    const linkHeuristically = (parent, child) => {
+        if (!attach(parent, child))
+            return false;
+        child.parentAgentId = parent.agentId;
+        child.parentToolUseId = parent.agentId;
+        return true;
+    };
+    // Phase 3: Team summary linking
     for (const trace of traces) {
         for (const traceEvent of trace.events) {
             const content = traceEvent.event.message?.content;
@@ -219,45 +274,56 @@ function linkTraces(traces) {
                 // Parse teammate agent IDs from XML blocks
                 const matches = content.matchAll(/agent[_-]id['":\s]+([a-f0-9]+)/gi);
                 for (const match of matches) {
-                    const childId = match[1];
-                    const child = traceById.get(childId);
-                    if (child && child !== trace && !child.parentToolUseId) {
-                        child.parentToolUseId = trace.agentId;
-                        trace.children.push(child);
-                    }
+                    const child = traceById.get(match[1]);
+                    if (child && unresolved(child))
+                        linkHeuristically(trace, child);
                 }
             }
         }
     }
-    // Phase 3: Positional fallback — timestamp proximity
+    // Phase 4: Positional fallback — timestamp proximity
     // Traces without parents that fall within another trace's time window
-    const parentless = traces.filter((t) => !t.parentToolUseId);
-    for (const child of parentless) {
+    for (const child of traces.filter(unresolved)) {
         if (!child.stats.startTime)
             continue;
         const childStart = child.stats.startTime.getTime();
-        // Find a trace that was active (Task tool call) right before this child started
+        // Find a top-level trace that spawned an agent right before this child started
         for (const potential of traces) {
-            if (potential === child)
+            if (potential === child || parentOf.has(potential))
                 continue;
-            if (potential.parentToolUseId)
-                continue; // Already linked
             for (const traceEvent of potential.events) {
                 const evt = traceEvent.event;
-                if (evt.type === 'assistant' && evt.tool?.name === 'Task') {
+                if (evt.type === 'assistant' && isSubagentSpawnTool(evt.tool?.name)) {
                     const taskTime = new Date(evt.timestamp).getTime();
                     // Within 2 seconds before child start
                     if (taskTime <= childStart && childStart - taskTime < 2000) {
-                        child.parentToolUseId = potential.agentId;
-                        potential.children.push(child);
+                        linkHeuristically(potential, child);
                         break;
                     }
                 }
             }
-            if (child.parentToolUseId)
+            if (parentOf.has(child))
                 break;
         }
     }
+    return traces.filter((trace) => !parentOf.has(trace));
+}
+/** Ids of the `Agent` / `Task` calls a trace made. */
+function spawnToolUseIdsOf(trace) {
+    const ids = [];
+    for (const traceEvent of trace.events) {
+        const content = traceEvent.event.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type === 'tool_use' &&
+                typeof block.id === 'string' &&
+                isSubagentSpawnTool(block.name)) {
+                ids.push(block.id);
+            }
+        }
+    }
+    return ids;
 }
 // ── Helpers ──
 function rawToSessionEvent(raw) {
@@ -272,7 +338,7 @@ function rawToSessionEvent(raw) {
         tool_result: 'tool_result',
         summary: 'summary',
     };
-    const mappedType = typeMap[type];
+    const mappedType = ownValue(typeMap, type);
     if (!mappedType)
         return null;
     const message = raw.message;

package/dist/esm/pricingCatalog.js

@@ -20,6 +20,7 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { _setCatalogContextWindows } from './modelContext';
 import { _setPricingOverrides, getPricingCatalogInfo } from './modelInfo';
+import { setOwnValue } from './ownKey';
 import { getConfigDir } from './paths';
 import { atomicWriteJson } from './writers/atomic';
 // ── Constants ──
@@ -117,7 +118,7 @@ export function normalizeLiteLlmCatalog(raw) {
             continue;
         // Catalog keys use both `provider/model` and bare `model` forms. Record both
         // the raw key and the bare-model form so lookups work regardless of caller.
-        out[key] = pricing;
+        setOwnValue(out, key, pricing);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key && !out[bare]) {
             out[bare] = pricing;
@@ -154,7 +155,7 @@ export function normalizeLiteLlmContextWindows(raw) {
         const window = entry.max_input_tokens;
         if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
             continue;
-        out[key] = window;
+        setOwnValue(out, key, window);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key) {
             const seen = aliasWindows.get(bare) ?? new Set();

package/dist/esm/promptHistory.js

@@ -24,11 +24,11 @@
  * answering call brings model or usage (`metadataStatus` says how settled).
  */
 import { createHash } from 'crypto';
-import * as fs from 'fs';
 import * as path from 'path';
 import { HUMAN_CODEX_SOURCES, humanPromptText } from './humanPrompt';
 import { listClaudeSessionFilesAsync } from './providers/claudeListing';
 import { listCodexSessionFilesAsync } from './providers/codexRollouts';
+import { canReadCompressedRollouts, openRolloutReadHandle, statRolloutContent, } from './providers/compressedRollouts';
 import { DirectoryListingCache } from './providers/directoryListingCache';
 import { realpathOrNull, resolveWorkspaceRoots } from './workspaceRoots';
 import { fileHeadOf, HEAD_BYTES, headMatches } from './fileHead';
@@ -105,7 +105,9 @@ export async function collectPromptHistory(options) {
         return finish();
     const sinceMs = options.since ? options.since.getTime() : null;
     const providers = options.providers ?? ALL_PROVIDERS;
-    const candidates = rotate(await listCandidates(providers, listingRoots, sinceMs), previousNext);
+    const candidates = rotate(await listCandidates(providers, listingRoots, sinceMs, {
+        includeCompressedRollouts: options.includeCompressedRollouts,
+    }), previousNext);
     const moved = movedSessionKeys(previous, candidates);
     const context = {
         roots,
@@ -141,7 +143,8 @@ export async function collectPromptHistory(options) {
         }
         let stat;
         try {
-            stat = await fs.promises.stat(candidate.filePath);
+            // A compressed rollout's size is its decompressed content's.
+            stat = await statRolloutContent(candidate.filePath);
         }
         catch {
             continue;
@@ -246,7 +249,7 @@ export async function collectPromptHistory(options) {
  */
 export async function readPromptOrdinalMarks(provider, sessionId, filePath) {
     const marks = [];
-    const stat = await fs.promises.stat(filePath);
+    const stat = await statRolloutContent(filePath);
     const unbounded = Number.MAX_SAFE_INTEGER;
     const context = {
         roots: [],
@@ -435,19 +438,24 @@ function scopedCwd(cwd, roots, realpaths) {
     return null;
 }
 /** @internal */
-export async function listCandidates(providers, listingRoots, sinceMs) {
+export async function listCandidates(providers, listingRoots, sinceMs, options = {}) {
     const byPath = new Map();
     const listOptions = sinceMs !== null ? { since: sinceMs } : {};
     for (const provider of [...new Set(providers)]) {
         if (!ALL_PROVIDERS.includes(provider))
             continue;
         // Listings are only candidate supersets; scope is re-checked per prompt.
-        const list = provider === 'claude-code' ? listClaudeSessionFilesAsync : listCodexSessionFilesAsync;
         const cache = new DirectoryListingCache();
         for (const root of listingRoots) {
             let files;
             try {
-                files = await list(root, listOptions, cache);
+                files =
+                    provider === 'claude-code'
+                        ? await listClaudeSessionFilesAsync(root, listOptions, cache)
+                        : await listCodexSessionFilesAsync(root, {
+                            ...listOptions,
+                            includeCompressed: options.includeCompressedRollouts === true && canReadCompressedRollouts(),
+                        }, cache);
             }
             catch {
                 files = [];
@@ -469,11 +477,11 @@ export async function listCandidates(providers, listingRoots, sinceMs) {
         compareStrings(left.sessionId, right.sessionId) ||
         compareStrings(left.key, right.key));
 }
-/** True when the file's first bytes still match a recorded head. */
+/** True when the file's first bytes (a compressed rollout's content) still match a recorded head. */
 async function fileStartsWith(filePath, head) {
     let handle;
     try {
-        handle = await fs.promises.open(filePath, 'r');
+        ({ handle } = await openRolloutReadHandle(filePath));
         return headMatches(head, await readAt(handle, 0, Math.min(HEAD_BYTES, head.bytes)));
     }
     catch {
@@ -546,8 +554,11 @@ async function verifyFile(handle, size, session) {
     return { head: fileHeadOf(head), bytesRead };
 }
 /** @internal */
-export async function scanFile(candidate, stat, prior, budget, context) {
-    const handle = await fs.promises.open(candidate.filePath, 'r');
+export async function scanFile(candidate, fileStat, prior, budget, context) {
+    // A compressed rollout is scanned over its decompressed content.
+    const opened = await openRolloutReadHandle(candidate.filePath);
+    const handle = opened.handle;
+    const stat = opened.size === null ? fileStat : { size: opened.size, mtimeMs: fileStat.mtimeMs };
     try {
         let bytesRead = 0;
         const verified = await verifyFile(handle, stat.size, prior);

package/dist/esm/providers/claudeCode.js

@@ -13,7 +13,8 @@ import { StringDecoder } from 'string_decoder';
 import { readSessionContextSnapshot } from '../context/sessionContext';
 import { readSessionFileStats } from '../sessionStats';
 import { JsonlParser } from '../parsers/jsonl';
-import { ClaudeUsageDeduper, normalizeClaudeUsage } from '../usage/claudeUsageDedupe';
+import { FileContinuity } from '../fileContinuity';
+import { ClaudeUsageDeduper, normalizeClaudeUsage, } from '../usage/claudeUsageDedupe';
 import { ProviderDiagnosticTracker } from './diagnostics';
 import { DirectoryListingCache, splitWatchedPath } from './directoryListingCache';
 import { encodeWorkspacePath as encodeWsPath, getSessionDirectory as getSessionDir, discoverSessionDirectory as discoverSessionDir, findActiveSession as findActiveSessionPath, findAllSessions as findAllSessionPaths, findSessionsInDirectory as findSessionsInDir, decodeEncodedPath, getAllProjectFolders as getAllProjectFoldersRaw, findSessionFilesWithStats, } from '../parsers/sessionPathResolver';
@@ -110,7 +111,10 @@ class ClaudeCodeReader {
     /** Cursor after the last complete line, safe to persist across restarts. */
     committedPosition = 0;
     events = [];
-    _wasTruncated = false;
+    /** Why the last `readNew()` started over from offset 0, if it did. */
+    _lastReset = null;
+    /** Whether the file is still the one the positions refer to. */
+    continuity = new FileContinuity();
     decoder = new StringDecoder('utf8');
     /** Split lines of one response repeat its usage; count each response once. */
     usageDeduper;
@@ -119,7 +123,8 @@ class ClaudeCodeReader {
         this.usageDeduper = usageDeduper ?? new ClaudeUsageDeduper();
         this.parser = new JsonlParser({
             onEvent: (raw) => {
-                for (const event of extractSessionEvents(raw)) {
+                // Mid-turn task notifications finish background subagents.
+                for (const event of extractSessionEvents(raw, { includeTaskNotifications: true })) {
                     this.events.push(this.usageDeduper.apply(normalizeClaudeUsage(event)));
                 }
             },
@@ -130,37 +135,28 @@ class ClaudeCodeReader {
     }
     readNew() {
         this.events = [];
-        this._wasTruncated = false;
+        this._lastReset = null;
+        let fd = null;
         try {
-            if (!fs.existsSync(this.sessionPath)) {
-                return [];
-            }
-            const stats = fs.statSync(this.sessionPath);
+            // Open first and stat the descriptor: the size and identity checked
+            // are those of the file actually read, even if the path is replaced.
+            fd = fs.openSync(this.sessionPath, 'r');
+            const stats = fs.fstatSync(fd);
+            const reason = this.continuity.check(fd, stats, this.filePosition, this.committedPosition);
+            // Truncated, rewritten, or replaced: what was read no longer describes
+            // the file, so start over from its beginning.
+            if (reason !== null)
+                this.restart(reason);
+            this.continuity.adopt(stats);
             const currentSize = stats.size;
-            // Handle truncation
-            if (currentSize < this.filePosition) {
-                this._wasTruncated = true;
-                this.filePosition = 0;
-                this.committedPosition = 0;
-                this.parser.reset();
-                this.decoder = new StringDecoder('utf8');
-                this.usageDeduper.reset();
-            }
             // No new content
             if (currentSize <= this.filePosition) {
-                return [];
+                return this.events;
             }
             // Read new bytes from last position
-            const fd = fs.openSync(this.sessionPath, 'r');
             const bufferSize = currentSize - this.filePosition;
             const buffer = Buffer.alloc(bufferSize);
-            let bytesRead = 0;
-            try {
-                bytesRead = fs.readSync(fd, buffer, 0, bufferSize, this.filePosition);
-            }
-            finally {
-                fs.closeSync(fd);
-            }
+            const bytesRead = fs.readSync(fd, buffer, 0, bufferSize, this.filePosition);
             const bytes = buffer.subarray(0, bytesRead);
             const newline = bytes.lastIndexOf(0x0a);
             if (newline >= 0)
@@ -170,10 +166,31 @@ class ClaudeCodeReader {
             this.filePosition += bytesRead;
         }
         catch (error) {
-            console.error(`ClaudeCodeReader: error reading ${this.sessionPath}: ${error}`);
+            if (error?.code !== 'ENOENT') {
+                console.error(`ClaudeCodeReader: error reading ${this.sessionPath}: ${error}`);
+            }
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    // Ignore close errors.
+                }
+            }
         }
         return this.events;
     }
+    /** Starts over from offset 0 of a file that was truncated, rewritten, or replaced. */
+    restart(reason) {
+        this._lastReset = { reason, previousPosition: this.committedPosition };
+        this.filePosition = 0;
+        this.committedPosition = 0;
+        this.parser.reset();
+        this.decoder = new StringDecoder('utf8');
+        this.usageDeduper.reset();
+    }
     readAll() {
         this.reset();
         return this.readNew();
@@ -184,7 +201,8 @@ class ClaudeCodeReader {
         this.parser.reset();
         this.decoder = new StringDecoder('utf8');
         this.usageDeduper.reset();
-        this._wasTruncated = false;
+        this._lastReset = null;
+        this.continuity.forget();
     }
     exists() {
         return fs.existsSync(this.sessionPath);
@@ -204,9 +222,22 @@ class ClaudeCodeReader {
         this.committedPosition = position;
         this.parser.reset();
         this.decoder = new StringDecoder('utf8');
+        // The position comes from elsewhere (a snapshot): adopt the file the next
+        // read finds rather than compare it with one read before.
+        this.continuity.forget();
     }
     wasTruncated() {
-        return this._wasTruncated;
+        return this._lastReset !== null;
+    }
+    lastReset() {
+        return this._lastReset ? { ...this._lastReset } : null;
+    }
+    /** The usage deduper's recent message ids, so a resumed reader does not recount a split response. */
+    getResumeState() {
+        return this.usageDeduper.exportState();
+    }
+    restoreResumeState(state) {
+        return this.usageDeduper.importState(state);
     }
 }
 /**