sidekick-shared 0.28.3 → 0.29.1

package/dist/parsers/codexRolloutOrigin.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Where a Codex rollout came from, read from its `session_meta` record:
+ * a session a person started, a fork of another session, or a subagent.
+ *
+ * Codex writes `session_meta.source` as a plain string for sessions started
+ * from a surface (`cli`, `vscode`, `exec`, …) and as an object for subagents:
+ * `{ subagent: { thread_spawn: { parent_thread_id, … } } }` for a spawned
+ * agent, `{ subagent: { other: 'guardian' } }` for internal reviewers, or
+ * `{ subagent: 'review' }`. The same JSON appears as a string in the state
+ * database's `threads.source`. A forked rollout records `forked_from_id`, and
+ * embeds its parent's `session_meta` after its own, so only the first counts.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module parsers/codexRolloutOrigin
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexSpawnParentFromSource = codexSpawnParentFromSource;
+exports.codexRolloutOrigin = codexRolloutOrigin;
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** A `source` value as an object: rollouts store it parsed, the database as JSON text. */
+function sourceObject(source) {
+    if (typeof source !== 'string')
+        return record(source);
+    if (!source.startsWith('{'))
+        return undefined;
+    try {
+        return record(JSON.parse(source));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parent thread id of a spawned subagent's `source` (object, or JSON text as
+ * stored in `threads.source`): `subagent.thread_spawn.parent_thread_id`.
+ */
+function codexSpawnParentFromSource(source) {
+    const spawn = record(record(sourceObject(source)?.subagent)?.thread_spawn);
+    const parent = spawn?.parent_thread_id;
+    return typeof parent === 'string' ? parent : undefined;
+}
+function subagentKindOf(subagent) {
+    if (typeof subagent === 'string')
+        return nonEmpty(subagent);
+    const variant = record(subagent);
+    if (!variant)
+        return undefined;
+    const other = nonEmpty(variant.other);
+    if (other)
+        return other;
+    return Object.keys(variant)[0];
+}
+/** The `session_meta` payload of a record, of a bare payload, or of the first in a list. */
+function metaPayload(input) {
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            const row = record(item);
+            if (row?.type === 'session_meta')
+                return record(row.payload);
+        }
+        return undefined;
+    }
+    const row = record(input);
+    if (!row)
+        return undefined;
+    if (row.type === 'session_meta')
+        return record(row.payload);
+    // A payload on its own, as `readSessionMeta()` returns it.
+    if (row.type === undefined && row.payload === undefined)
+        return row;
+    return undefined;
+}
+/**
+ * Origin of a Codex rollout from its `session_meta`. Accepts the parsed
+ * `session_meta` record, its payload, or the rollout's records in order (the
+ * first `session_meta` wins: a fork embeds its parent's after its own).
+ * Anything else yields `{ isSubagent: false }`.
+ */
+function codexRolloutOrigin(input) {
+    const payload = metaPayload(input);
+    if (!payload)
+        return { isSubagent: false };
+    const forkedFromId = nonEmpty(payload.forked_from_id);
+    const object = sourceObject(payload.source);
+    const isSubagent = object !== undefined && 'subagent' in object;
+    const source = typeof payload.source === 'string' && object === undefined
+        ? nonEmpty(payload.source)
+        : isSubagent
+            ? 'subagent'
+            : undefined;
+    const parentId = forkedFromId ??
+        nonEmpty(codexSpawnParentFromSource(object)) ??
+        (isSubagent ? nonEmpty(payload.parent_thread_id) : undefined);
+    const subagentKind = isSubagent ? subagentKindOf(object?.subagent) : undefined;
+    return {
+        ...(forkedFromId ? { forkedFromId } : {}),
+        ...(source ? { source } : {}),
+        isSubagent,
+        ...(parentId ? { parentId } : {}),
+        ...(subagentKind ? { subagentKind } : {}),
+    };
+}

package/dist/parsers/openCodeParser.d.ts

@@ -12,6 +12,7 @@
  */
 import type { SessionEvent } from '../types/sessionEvent';
 import type { OpenCodeMessage, OpenCodePart, DbMessage, DbPart } from '../types/opencode';
+import { type NormalizedUsage } from '../usageNormalization';
 /**
  * Normalizes an OpenCode tool name to PascalCase.
  *
@@ -38,6 +39,43 @@ export declare function detectPlanModeFromText(text: string): 'enter' | 'exit' |
  * This adds snake_case aliases without removing the originals.
  */
 export declare function normalizeToolInput(input: Record<string, unknown>): Record<string, unknown>;
+/** OpenCode token counts as stored on an assistant message or step. */
+export interface OpenCodeTokenCounts {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    /** Provider-reported total, stored by OpenCode since late 2025. */
+    total?: number;
+}
+/**
+ * Token counts from a message in either storage shape: database rows are
+ * mapped to flat `cacheRead` / `cacheWrite`, while file-storage messages keep
+ * OpenCode's nested `cache: { read, write }`.
+ * @internal
+ */
+export declare function openCodeTokenCounts(tokens: unknown): OpenCodeTokenCounts;
+/**
+ * How a stored OpenCode message splits its tokens. Current OpenCode stores
+ * every bucket disjoint for every provider: `input` excludes cache reads and
+ * writes (since 2025-11) and `output` excludes `reasoning` (since 2026-04),
+ * with `total` equal to their sum. Older messages either counted cached input
+ * in `input` (OpenAI-compatible providers) or reasoning in `output`. The
+ * stored `total` tells the layouts apart; without it the current layout is
+ * assumed.
+ * @internal
+ */
+export declare function openCodeTokenLayout(tokens: OpenCodeTokenCounts): {
+    inputIncludesCache: boolean;
+    reasoningInOutput: boolean;
+};
+/** Normalizes one OpenCode message's or step's stored tokens. @internal */
+export declare function normalizeOpenCodeUsage(tokens: OpenCodeTokenCounts, providerID: string | undefined, extra?: {
+    source?: string;
+    model?: string;
+    reportedCostUsd?: number;
+}): NormalizedUsage;
 /**
  * Converts an OpenCode message and its parts into SessionEvent array.
  *

package/dist/parsers/openCodeParser.js

@@ -15,10 +15,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeToolName = normalizeToolName;
 exports.detectPlanModeFromText = detectPlanModeFromText;
 exports.normalizeToolInput = normalizeToolInput;
+exports.openCodeTokenCounts = openCodeTokenCounts;
+exports.openCodeTokenLayout = openCodeTokenLayout;
+exports.normalizeOpenCodeUsage = normalizeOpenCodeUsage;
 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.
@@ -54,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.
@@ -123,6 +127,78 @@ function toISOString(time) {
         return time;
     return new Date(time).toISOString();
 }
+/**
+ * Token counts from a message in either storage shape: database rows are
+ * mapped to flat `cacheRead` / `cacheWrite`, while file-storage messages keep
+ * OpenCode's nested `cache: { read, write }`.
+ * @internal
+ */
+function openCodeTokenCounts(tokens) {
+    const raw = (tokens ?? {});
+    const cache = (raw.cache ?? {});
+    const num = (value) => (typeof value === 'number' ? value : undefined);
+    return {
+        input: num(raw.input),
+        output: num(raw.output),
+        reasoning: num(raw.reasoning),
+        cacheRead: num(raw.cacheRead) ?? num(cache.read),
+        cacheWrite: num(raw.cacheWrite) ?? num(cache.write),
+        total: num(raw.total),
+    };
+}
+/**
+ * How a stored OpenCode message splits its tokens. Current OpenCode stores
+ * every bucket disjoint for every provider: `input` excludes cache reads and
+ * writes (since 2025-11) and `output` excludes `reasoning` (since 2026-04),
+ * with `total` equal to their sum. Older messages either counted cached input
+ * in `input` (OpenAI-compatible providers) or reasoning in `output`. The
+ * stored `total` tells the layouts apart; without it the current layout is
+ * assumed.
+ * @internal
+ */
+function openCodeTokenLayout(tokens) {
+    const n = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+    const input = n(tokens.input);
+    const output = n(tokens.output);
+    const reasoning = n(tokens.reasoning);
+    const cache = n(tokens.cacheRead) + n(tokens.cacheWrite);
+    const total = n(tokens.total);
+    if (total > 0 && total !== input + cache + output + reasoning) {
+        if (reasoning > 0 && total === input + cache + output) {
+            return { inputIncludesCache: false, reasoningInOutput: true };
+        }
+        if (cache > 0 && total === input + output + reasoning) {
+            return { inputIncludesCache: true, reasoningInOutput: false };
+        }
+        if (cache > 0 && reasoning > 0 && total === input + output) {
+            return { inputIncludesCache: true, reasoningInOutput: true };
+        }
+    }
+    return { inputIncludesCache: false, reasoningInOutput: false };
+}
+/** Normalizes one OpenCode message's or step's stored tokens. @internal */
+function normalizeOpenCodeUsage(tokens, providerID, extra = {}) {
+    const layout = openCodeTokenLayout(tokens);
+    return (0, usageNormalization_1.normalizeProviderUsage)({
+        // `openai` semantics subtract cache reads from input; only an old
+        // cache-inclusive message needs that.
+        semantics: layout.inputIncludesCache
+            ? 'openai'
+            : providerID === 'anthropic'
+                ? 'anthropic'
+                : 'sidekick',
+        provider: providerID ?? 'opencode',
+        ...(extra.source ? { source: extra.source } : {}),
+        ...(extra.model ? { model: extra.model } : {}),
+        inputTokens: tokens.input,
+        outputTokens: tokens.output,
+        cacheReadTokens: tokens.cacheRead,
+        cacheWriteTokens: tokens.cacheWrite,
+        reasoningTokens: tokens.reasoning,
+        reasoningIncludedInOutput: layout.reasoningInOutput,
+        ...(extra.reportedCostUsd !== undefined ? { reportedCostUsd: extra.reportedCostUsd } : {}),
+    });
+}
 /**
  * Converts an OpenCode message and its parts into SessionEvent array.
  *
@@ -328,31 +404,20 @@ function convertAssistantMessage(message, parts) {
         : stepFinishCost > 0
             ? stepFinishCost
             : undefined;
-    const usage = {
-        input_tokens: message.tokens.input || 0,
-        output_tokens: message.tokens.output || 0,
-        cache_creation_input_tokens: message.tokens.cacheWrite || 0,
-        cache_read_input_tokens: message.tokens.cacheRead || 0,
-        reported_cost: reportedCost,
-        reasoning_tokens: message.tokens.reasoning || 0,
-    };
-    const normalizedUsage = (0, usageNormalization_1.normalizeProviderUsage)({
-        semantics: message.providerID === 'openai'
-            ? 'openai'
-            : message.providerID === 'anthropic'
-                ? 'anthropic'
-                : 'sidekick',
-        provider: message.providerID ?? 'opencode',
+    const counts = openCodeTokenCounts(message.tokens);
+    const normalizedUsage = normalizeOpenCodeUsage(counts, message.providerID, {
         source: 'opencode-message',
         model: message.modelID,
-        inputTokens: message.tokens.input,
-        outputTokens: message.tokens.output,
-        cacheReadTokens: message.tokens.cacheRead,
-        cacheWriteTokens: message.tokens.cacheWrite,
-        reasoningTokens: message.tokens.reasoning,
-        reasoningIncludedInOutput: message.providerID === 'openai',
         reportedCostUsd: reportedCost,
     });
+    const usage = {
+        input_tokens: normalizedUsage.uncachedInputTokens,
+        output_tokens: counts.output || 0,
+        cache_creation_input_tokens: counts.cacheWrite || 0,
+        cache_read_input_tokens: counts.cacheRead || 0,
+        reported_cost: reportedCost,
+        reasoning_tokens: counts.reasoning || 0,
+    };
     const timestamp = toISOString(message.time.completed || message.time.created);
     const retryAttempts = parts
         .filter((part) => part.type === 'retry')
@@ -491,6 +556,7 @@ function parseDbMessageData(row) {
             cacheRead: cache?.read || 0,
             cacheWrite: cache?.write || 0,
             reasoning: tokens?.reasoning || 0,
+            ...(typeof tokens?.total === 'number' ? { total: tokens.total } : {}),
         },
         time: {
             created: time?.created || row.time_created,

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.