sidekick-shared 0.29.0 → 0.29.1

package/dist/ownKey.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Own-property lookups for plain-object tables indexed by external strings.
+ *
+ * `table[key]` also finds inherited members, so a model id, tool name, or
+ * error code such as `constructor`, `toString`, or `__proto__` would return an
+ * `Object.prototype` member instead of `undefined`.
+ *
+ * @module ownKey
+ */
+/** The value stored under `key` in `table` itself, or `undefined`. */
+export declare function ownValue<T>(table: Readonly<Record<string, T>>, key: string): T | undefined;
+/**
+ * Store `value` as an own, enumerable property, even for `__proto__`, which a
+ * plain assignment would treat as a prototype change.
+ */
+export declare function setOwnValue<T>(table: Record<string, T>, key: string, value: T): void;

package/dist/ownKey.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Own-property lookups for plain-object tables indexed by external strings.
+ *
+ * `table[key]` also finds inherited members, so a model id, tool name, or
+ * error code such as `constructor`, `toString`, or `__proto__` would return an
+ * `Object.prototype` member instead of `undefined`.
+ *
+ * @module ownKey
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownValue = ownValue;
+exports.setOwnValue = setOwnValue;
+const hasOwn = Object.prototype.hasOwnProperty;
+/** The value stored under `key` in `table` itself, or `undefined`. */
+function ownValue(table, key) {
+    return hasOwn.call(table, key) ? table[key] : undefined;
+}
+/**
+ * Store `value` as an own, enumerable property, even for `__proto__`, which a
+ * plain assignment would treat as a prototype change.
+ */
+function setOwnValue(table, key, value) {
+    Object.defineProperty(table, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}

package/dist/parsers/codexParser.d.ts

@@ -13,6 +13,21 @@
  */
 import type { SessionEvent } from '../types/sessionEvent';
 import type { CodexRolloutLine, CodexSessionMeta, CodexTokenUsage, CodexRateLimits } from '../types/codex';
+/** Pending exec command awaiting its end event. */
+interface PendingExecCommand {
+    call_id: string;
+    command: string[];
+    workdir?: string;
+    timestamp: string;
+}
+/** Pending MCP tool call awaiting its end event. */
+interface PendingMcpToolCall {
+    call_id: string;
+    server_name?: string;
+    tool_name: string;
+    arguments?: Record<string, unknown>;
+    timestamp: string;
+}
 /**
  * Resolve the usage of the single call a Codex `token_count` event reports.
  *
@@ -85,6 +100,35 @@ export interface CodexPendingStats {
     /** Pending calls forgotten because `maxPendingBytes` was exceeded. */
     evictedByBytes: number;
 }
+/**
+ * JSON-serializable continuation state of a {@link CodexRolloutParser}, from
+ * `exportResumeState()`, for `importResumeState()` in a parser that resumes
+ * at the same rollout position (for example from a persisted session
+ * snapshot). Every table lists its entries oldest first.
+ */
+export interface CodexRolloutResumeState {
+    version: 1;
+    sessionMeta: CodexSessionMeta | null;
+    /** Model from the latest `turn_context`, attributed to later events. */
+    currentModel: string | null;
+    /** Cumulative total of the previous token_count event, to skip its duplicates. */
+    prevTotalUsage: CodexTokenUsage | null;
+    lastTokenUsage: CodexTokenUsage | null;
+    modelContextWindow: number | null;
+    lastRateLimits: CodexRateLimits | null;
+    hasAggregateRateLimits: boolean;
+    inPlanMode: boolean;
+    /** Call ids whose tool use was already emitted, so their end event does not emit another. */
+    emittedToolUseIds: string[];
+    /** `apply_patch` calls awaiting output: call id and its per-file tool-use ids. */
+    patchExpandedToolUseIds: Array<[string, string[]]>;
+    /** `exec_command_begin` events awaiting their end. */
+    pendingExecCommands: PendingExecCommand[];
+    /** `mcp_tool_call_begin` events awaiting their end. */
+    pendingMcpToolCalls: PendingMcpToolCall[];
+}
+/** A valid `CodexTokenUsage` (copied), `null` for `null`, or `undefined` when invalid. Internal. */
+export declare function codexTokenUsageFrom(value: unknown): CodexTokenUsage | null | undefined;
 /**
  * Stateful parser for Codex JSONL rollout lines.
  *
@@ -130,6 +174,21 @@ export declare class CodexRolloutParser {
     getModelContextWindow(): number | null;
     /** Get the last observed rate limits from token_count events. */
     getLastRateLimits(): CodexRateLimits | null;
+    /**
+     * The state later lines depend on — session metadata, current model,
+     * previous cumulative token total, context window, rate limits, plan mode,
+     * and the tool-call correlation tables (newest `limit` entries each) — as
+     * JSON-serializable data. Eviction counters are not included.
+     */
+    exportResumeState(limit?: number): CodexRolloutResumeState;
+    /**
+     * Replaces this parser's state with one from {@link exportResumeState}, as
+     * if it had parsed the rollout up to where that state was taken. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state.
+     * This parser's own `maxTrackedToolCalls`, `maxPendingBytes`, and
+     * `metadataOnly` options apply to the imported tables.
+     */
+    importResumeState(state: unknown): boolean;
     /**
      * Converts a single rollout line to zero or more session events.
      */
@@ -142,6 +201,9 @@ export declare class CodexRolloutParser {
      * first.
      */
     private putPending;
+    private putPendingExec;
+    private putPendingMcp;
+    private putPendingPatch;
     /** Removes and returns a pending call. */
     private takePending;
     private forgetPendingBytes;
@@ -164,3 +226,4 @@ export declare class CodexRolloutParser {
     private handleEventMsg;
     private handleTokenCount;
 }
+export {};

package/dist/parsers/codexParser.js

@@ -18,6 +18,7 @@ exports.resolveCodexCallUsage = resolveCodexCallUsage;
 exports.normalizeCodexToolName = normalizeCodexToolName;
 exports.normalizeCodexToolInput = normalizeCodexToolInput;
 exports.extractPatchFilePaths = extractPatchFilePaths;
+exports.codexTokenUsageFrom = codexTokenUsageFrom;
 const codex_1 = require("../types/codex");
 const openCodeParser_1 = require("./openCodeParser");
 const usageNormalization_1 = require("../usageNormalization");
@@ -178,6 +179,61 @@ function extractPatchFilePaths(input) {
 }
 /** Default cap on each piece of per-call correlation state the parser keeps. */
 exports.DEFAULT_MAX_TRACKED_TOOL_CALLS = 4096;
+/** Entries per table {@link CodexRolloutParser.exportResumeState} keeps by default. */
+const DEFAULT_RESUME_STATE_LIMIT = 256;
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isTokenCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/** A valid `CodexTokenUsage` (copied), `null` for `null`, or `undefined` when invalid. Internal. */
+function codexTokenUsageFrom(value) {
+    if (value === null)
+        return null;
+    if (!isPlainObject(value))
+        return undefined;
+    if (!isTokenCount(value.input_tokens) || !isTokenCount(value.output_tokens))
+        return undefined;
+    const usage = {
+        input_tokens: value.input_tokens,
+        output_tokens: value.output_tokens,
+    };
+    for (const field of ['cached_input_tokens', 'reasoning_output_tokens', 'total_tokens']) {
+        const count = value[field];
+        if (count === undefined)
+            continue;
+        if (!isTokenCount(count))
+            return undefined;
+        usage[field] = count;
+    }
+    return usage;
+}
+/** Last `limit` items of an insertion-ordered collection, oldest first. */
+function newest(items, size, limit) {
+    const count = limit >= 0 ? Math.min(size, Math.floor(limit)) : 0;
+    const kept = [];
+    let skip = size - count;
+    for (const item of items) {
+        if (kept.length >= count)
+            break;
+        if (skip > 0) {
+            skip -= 1;
+            continue;
+        }
+        kept.push(item);
+    }
+    return kept;
+}
 /** Fixed per-entry cost added to each pending call's byte estimate. */
 const PENDING_ENTRY_OVERHEAD_BYTES = 64;
 /** Prefix of the bookkeeping keys the parser stashes inside tool inputs. */
@@ -289,6 +345,118 @@ class CodexRolloutParser {
     getLastRateLimits() {
         return this.lastRateLimits;
     }
+    /**
+     * The state later lines depend on — session metadata, current model,
+     * previous cumulative token total, context window, rate limits, plan mode,
+     * and the tool-call correlation tables (newest `limit` entries each) — as
+     * JSON-serializable data. Eviction counters are not included.
+     */
+    exportResumeState(limit = DEFAULT_RESUME_STATE_LIMIT) {
+        return cloneJson({
+            version: 1,
+            sessionMeta: this.sessionMeta,
+            currentModel: this.currentModel,
+            prevTotalUsage: this.prevTotalUsage,
+            lastTokenUsage: this.lastTokenUsage,
+            modelContextWindow: this.modelContextWindow,
+            lastRateLimits: this.lastRateLimits,
+            hasAggregateRateLimits: this.hasAggregateRateLimits,
+            inPlanMode: this.inPlanMode,
+            emittedToolUseIds: newest(this.emittedToolUseIds, this.emittedToolUseIds.size, limit),
+            patchExpandedToolUseIds: newest(this.patchExpandedToolUseIds, this.patchExpandedToolUseIds.size, limit),
+            pendingExecCommands: newest(this.pendingExecCommands.values(), this.pendingExecCommands.size, limit),
+            pendingMcpToolCalls: newest(this.pendingMcpToolCalls.values(), this.pendingMcpToolCalls.size, limit),
+        });
+    }
+    /**
+     * Replaces this parser's state with one from {@link exportResumeState}, as
+     * if it had parsed the rollout up to where that state was taken. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state.
+     * This parser's own `maxTrackedToolCalls`, `maxPendingBytes`, and
+     * `metadataOnly` options apply to the imported tables.
+     */
+    importResumeState(state) {
+        if (!isPlainObject(state) || state.version !== 1)
+            return false;
+        const s = state;
+        const prevTotalUsage = codexTokenUsageFrom(s.prevTotalUsage);
+        const lastTokenUsage = codexTokenUsageFrom(s.lastTokenUsage);
+        if (prevTotalUsage === undefined || lastTokenUsage === undefined)
+            return false;
+        if (s.sessionMeta !== null && !isPlainObject(s.sessionMeta))
+            return false;
+        if (s.lastRateLimits !== null && !isPlainObject(s.lastRateLimits))
+            return false;
+        if (s.currentModel !== null && typeof s.currentModel !== 'string')
+            return false;
+        const contextWindow = s.modelContextWindow;
+        if (contextWindow !== null &&
+            !(typeof contextWindow === 'number' && Number.isFinite(contextWindow) && contextWindow > 0)) {
+            return false;
+        }
+        if (typeof s.hasAggregateRateLimits !== 'boolean' || typeof s.inPlanMode !== 'boolean') {
+            return false;
+        }
+        if (!isStringArray(s.emittedToolUseIds))
+            return false;
+        const patches = s.patchExpandedToolUseIds;
+        if (!Array.isArray(patches) ||
+            !patches.every((entry) => Array.isArray(entry) &&
+                entry.length === 2 &&
+                typeof entry[0] === 'string' &&
+                isStringArray(entry[1]))) {
+            return false;
+        }
+        const execs = s.pendingExecCommands;
+        if (!Array.isArray(execs) ||
+            !execs.every((entry) => isPlainObject(entry) &&
+                typeof entry.call_id === 'string' &&
+                isStringArray(entry.command) &&
+                isOptionalString(entry.workdir) &&
+                typeof entry.timestamp === 'string')) {
+            return false;
+        }
+        const mcps = s.pendingMcpToolCalls;
+        if (!Array.isArray(mcps) ||
+            !mcps.every((entry) => isPlainObject(entry) &&
+                typeof entry.call_id === 'string' &&
+                typeof entry.tool_name === 'string' &&
+                isOptionalString(entry.server_name) &&
+                (entry.arguments === undefined || isPlainObject(entry.arguments)) &&
+                typeof entry.timestamp === 'string')) {
+            return false;
+        }
+        const copy = cloneJson({
+            sessionMeta: s.sessionMeta,
+            lastRateLimits: s.lastRateLimits,
+            patches: patches,
+            execs: execs,
+            mcps: mcps,
+        });
+        this.reset();
+        this.sessionMeta = copy.sessionMeta;
+        this.currentModel = s.currentModel;
+        this.prevTotalUsage = prevTotalUsage;
+        this.lastTokenUsage = lastTokenUsage;
+        this.modelContextWindow = contextWindow;
+        this.lastRateLimits = copy.lastRateLimits;
+        this.hasAggregateRateLimits = s.hasAggregateRateLimits;
+        this.inPlanMode = s.inPlanMode;
+        for (const id of s.emittedToolUseIds) {
+            rememberBounded(this.emittedToolUseIds, id, this.maxTrackedToolCalls);
+        }
+        for (const [callId, toolUseIds] of copy.patches)
+            this.putPendingPatch(callId, toolUseIds);
+        for (const pending of copy.execs) {
+            this.putPendingExec(this.metadataOnly
+                ? { call_id: pending.call_id, command: [], timestamp: pending.timestamp }
+                : pending);
+        }
+        for (const pending of copy.mcps) {
+            this.putPendingMcp(this.metadataOnly ? { ...pending, arguments: undefined } : pending);
+        }
+        return true;
+    }
     /**
      * Converts a single rollout line to zero or more session events.
      */
@@ -360,6 +528,16 @@ class CodexRolloutParser {
             this.evictedByBytes += 1;
         }
     }
+    putPendingExec(pending) {
+        this.putPending(this.pendingExecCommands, pending.call_id, pending, () => stringBytes(pending.call_id, pending.workdir, pending.timestamp, ...(Array.isArray(pending.command) ? pending.command : [])));
+    }
+    putPendingMcp(pending) {
+        this.putPending(this.pendingMcpToolCalls, pending.call_id, pending, () => stringBytes(pending.call_id, pending.server_name, pending.tool_name, pending.timestamp) +
+            approxJsonBytes(pending.arguments));
+    }
+    putPendingPatch(callId, toolUseIds) {
+        this.putPending(this.patchExpandedToolUseIds, callId, toolUseIds, () => stringBytes(callId, ...toolUseIds));
+    }
     /** Removes and returns a pending call. */
     takePending(table, callId) {
         const value = table.get(callId);
@@ -589,7 +767,7 @@ class CodexRolloutParser {
             if (filePaths.length === 0)
                 return [];
             const toolUseIds = filePaths.map((fp) => `${item.call_id}-${fp}`);
-            this.putPending(this.patchExpandedToolUseIds, item.call_id, toolUseIds, () => stringBytes(item.call_id, ...toolUseIds));
+            this.putPendingPatch(item.call_id, toolUseIds);
             for (const id of toolUseIds) {
                 rememberBounded(this.emittedToolUseIds, id, this.maxTrackedToolCalls);
             }
@@ -739,7 +917,7 @@ class CodexRolloutParser {
                 const pending = this.metadataOnly
                     ? { call_id: e.call_id, command: [], timestamp }
                     : { call_id: e.call_id, command: e.command, workdir: e.workdir, timestamp };
-                this.putPending(this.pendingExecCommands, e.call_id, pending, () => stringBytes(pending.call_id, pending.workdir, pending.timestamp, ...(Array.isArray(pending.command) ? pending.command : [])));
+                this.putPendingExec(pending);
                 return [];
             }
             case 'exec_command_end': {
@@ -802,8 +980,7 @@ class CodexRolloutParser {
                     arguments: this.metadataOnly ? undefined : e.arguments,
                     timestamp,
                 };
-                this.putPending(this.pendingMcpToolCalls, e.call_id, pending, () => stringBytes(pending.call_id, pending.server_name, pending.tool_name, timestamp) +
-                    approxJsonBytes(pending.arguments));
+                this.putPendingMcp(pending);
                 return [];
             }
             case 'mcp_tool_call_end': {

package/dist/parsers/openCodeParser.js

@@ -22,6 +22,7 @@ exports.convertOpenCodeMessage = convertOpenCodeMessage;
 exports.parseDbMessageData = parseDbMessageData;
 exports.parseDbPartData = parseDbPartData;
 const usageNormalization_1 = require("../usageNormalization");
+const ownKey_1 = require("../ownKey");
 /**
  * OpenCode → Claude Code tool name mapping.
  * OpenCode uses lowercase names; downstream code expects PascalCase.
@@ -57,7 +58,7 @@ function normalizeToolName(name) {
     if (!name)
         return name;
     // Check mapping (case-insensitive lookup via lowercase key)
-    const mapped = TOOL_NAME_MAP[name.toLowerCase()];
+    const mapped = (0, ownKey_1.ownValue)(TOOL_NAME_MAP, name.toLowerCase());
     if (mapped)
         return mapped;
     // Already PascalCase (starts with uppercase)? Pass through.

package/dist/parsers/subagentScanner.d.ts

@@ -8,15 +8,28 @@
  * @module parsers/subagentScanner
  */
 import type { SubagentStats, TaskState } from '../types/sessionEvent';
+/** Fields of a Claude Code `agent-<id>.meta.json`; each is present only when well-typed. */
+export interface AgentMeta {
+    agentType?: string;
+    description?: string;
+    /** The tool_use id of the `Agent` / `Task` call that spawned this agent. */
+    toolUseId?: string;
+    /** The agent that spawned this one, for spawns nested inside a subagent. */
+    parentAgentId?: string;
+    /** `'background'` for an agent launched in the background. */
+    requestShape?: string;
+    /** Written as `true` once a background agent is done (newer Claude Code). */
+    finished?: boolean;
+    /** The user stopped the agent. */
+    stoppedByUser?: boolean;
+}
 /**
  * Reads `agent-<id>.meta.json` (written by Claude Code next to the transcript)
- * for the spawn's agent type and description. Missing or malformed files
- * yield an empty object.
+ * for the spawn's agent type, description, spawning tool_use id, parent agent,
+ * and completion flags. Missing or malformed files yield an empty object;
+ * wrongly typed fields are left out.
  */
-export declare function readAgentMeta(agentFilePath: string): {
-    agentType?: string;
-    description?: string;
-};
+export declare function readAgentMeta(agentFilePath: string): AgentMeta;
 /**
  * Scans subagent directory for agent JSONL files and extracts tool calls.
  *

package/dist/parsers/subagentScanner.js

@@ -51,28 +51,49 @@ const path = __importStar(require("path"));
 const claudeUsageDedupe_1 = require("../usage/claudeUsageDedupe");
 const subagentUsage_1 = require("../usage/subagentUsage");
 const subagentStatsCache_1 = require("./subagentStatsCache");
+const subagentSpawn_1 = require("../subagentSpawn");
 /**
  * Pattern for matching subagent JSONL files.
  * Files are named like: agent-<hash>.jsonl
  */
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
+function metaString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
 /**
  * Reads `agent-<id>.meta.json` (written by Claude Code next to the transcript)
- * for the spawn's agent type and description. Missing or malformed files
- * yield an empty object.
+ * for the spawn's agent type, description, spawning tool_use id, parent agent,
+ * and completion flags. Missing or malformed files yield an empty object;
+ * wrongly typed fields are left out.
  */
 function readAgentMeta(agentFilePath) {
     try {
         const metaPath = agentFilePath.replace(/\.jsonl$/, '.meta.json');
         const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-        return {
-            ...(typeof parsed.agentType === 'string' && parsed.agentType
-                ? { agentType: parsed.agentType }
-                : {}),
-            ...(typeof parsed.description === 'string' && parsed.description
-                ? { description: parsed.description }
-                : {}),
-        };
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const record = parsed;
+        const meta = {};
+        const agentType = metaString(record.agentType);
+        if (agentType)
+            meta.agentType = agentType;
+        const description = metaString(record.description);
+        if (description)
+            meta.description = description;
+        const toolUseId = metaString(record.toolUseId);
+        if (toolUseId)
+            meta.toolUseId = toolUseId;
+        const parentAgentId = metaString(record.parentAgentId);
+        if (parentAgentId)
+            meta.parentAgentId = parentAgentId;
+        const requestShape = metaString(record.requestShape);
+        if (requestShape)
+            meta.requestShape = requestShape;
+        if (typeof record.finished === 'boolean')
+            meta.finished = record.finished;
+        if (typeof record.stoppedByUser === 'boolean')
+            meta.stoppedByUser = record.stoppedByUser;
+        return meta;
     }
     catch {
         return {};
@@ -247,8 +268,8 @@ function parseAgentFile(filePath, agentId, log) {
                                 }
                             }
                             toolCalls.push(toolCall);
-                            // If this is a Task tool call (spawning another subagent), extract info
-                            if (toolUse.name === 'Task' && toolUse.input) {
+                            // If this is an Agent/Task call (spawning another subagent), extract info
+                            if ((0, subagentSpawn_1.isSubagentSpawnTool)(toolUse.name) && toolUse.input) {
                                 if (toolUse.input.subagent_type && !agentType) {
                                     agentType = String(toolUse.input.subagent_type);
                                 }

package/dist/parsers/subagentTraceParser.d.ts

@@ -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
  */
@@ -41,8 +44,25 @@ export interface SubagentTrace {
     children: SubagentTrace[];
     /** Basic stats (tokens, duration, etc.) */
     stats: SubagentStats;
-    /** Parent tool_use_id that spawned this agent */
+    /**
+     * Parent tool_use_id that spawned this agent: the spawning `Agent` / `Task`
+     * call's id when Claude Code recorded it (also for top-level traces, whose
+     * spawn is in the main session). For a heuristic link without that
+     * metadata it holds the parent's agent id, as before; see `parentAgentId`.
+     */
     parentToolUseId?: string;
+    /** Path of this agent's `agent-<id>.jsonl` transcript. */
+    filePath?: string;
+    /** The tool_use id of the call that spawned this agent (meta `toolUseId`). */
+    spawnToolUseId?: string;
+    /** Agent id of the parent trace, for agents spawned by another subagent. */
+    parentAgentId?: string;
+    /** Launched in the background (meta `requestShape: 'background'`). */
+    background?: boolean;
+    /** Claude Code marked the background agent done (meta `finished`). */
+    finished?: boolean;
+    /** The user stopped the agent (meta `stoppedByUser`). */
+    stoppedByUser?: boolean;
 }
 /**
  * Scans and parses subagent traces with full conversation events.