sidekick-shared 0.29.1 → 0.30.0

package/dist/node.js

@@ -8,8 +8,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.subagentTokenTotals = exports.scanSessionSubagents = exports.readMainThreadTokenTotals = exports.combineSessionTokenTotals = exports.collectSessionTokenTotals = exports.pruneUsageCache = exports.getUsageCacheDir = exports.collectUsageEvents = exports.USAGE_CACHE_VERSION = exports.MAX_USAGE_CACHE_FILES = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.sessionFingerprintParts = exports.fingerprintString = exports.readSessionReportInputs = exports.readSessionFileStats = exports.providerContextSizeFn = exports.firstUserPrompt = exports.computeSessionFileStats = exports.isHumanPrompt = exports.humanPromptText = exports.HUMAN_CODEX_SOURCES = exports.HUMAN_CLAUDE_ENTRYPOINTS = exports.collectSessionPromptHistory = exports.findToolCallOrigins = exports.PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES = exports.parsePromptHistoryCursor = exports.isPromptHistorySessionSettled = exports.collectPromptHistory = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
-exports.atomicWriteJson = exports.compareCodexAuthFreshness = exports.codexRefreshFingerprint = exports.codexIdentitiesMatch = exports.readCodexAccessTokenExpiry = exports.readCodexLastRefresh = exports.readCodexAuthIdentity = exports.parseCodexAuthJson = exports.CODEX_ARCHIVED_SESSIONS_SUBDIR = exports.CODEX_SESSIONS_SUBDIR = exports.forceFileCredentialStore = exports.getCodexCredentialStoreMode = exports.getCodexSessionsDirs = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.getCodexMonitoringHomes = exports.getSystemCodexHome = exports.getClaudeProjectsDir = exports.isDefaultClaudeHome = exports.getDefaultClaudeHome = exports.getLiveClaudeHome = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.getDefaultConfigDir = exports.getConfigDirOverride = exports.getConfigDir = exports.CONFIG_DIR_ENV_VAR = exports.SYNTHETIC_MODEL = exports.createSessionProviders = exports.splitWatchedPath = exports.DirectoryListingCache = exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionPreviewAsync = exports.readSessionPreview = exports.listSessionPreviewsAsync = exports.listSessionPreviews = exports.readCodexHistory = exports.walkRolloutFilesAsync = exports.walkRolloutFiles = exports.findCodexRolloutFile = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.importSessionHistory = exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = exports.sessionSummaryFromStats = void 0;
-exports.verifyJsonlCheckpoint = exports.JsonlTailSymlinkError = exports.JSONL_TAIL_CHECKPOINT_VERSION = exports.DEFAULT_JSONL_TAIL_READ_BYTES = exports.DEFAULT_JSONL_TAIL_MAX_LINE_BYTES = exports.createJsonlTail = exports.captureJsonlCheckpoint = exports.resolveWorktreeMainRepo = exports.discoverWorktreeSiblings = exports.resolveWorkspaceRoots = exports.TOOL_CATEGORIES = exports.classifyTool = exports.fetchProviderServiceStatus = exports.clearRegisteredModelPricing = exports.registerModelPricing = exports.getPricingCatalogInfo = exports.codexSpawnParentFromSource = exports.codexRolloutOrigin = exports.parseCodexLoginStatus = exports.parseClaudeAuthStatus = exports.atomicWriteJsonSync = void 0;
+exports.readCodexAuthIdentity = exports.parseCodexAuthJson = exports.CODEX_ARCHIVED_SESSIONS_SUBDIR = exports.CODEX_SESSIONS_SUBDIR = exports.forceFileCredentialStore = exports.getCodexCredentialStoreMode = exports.getCodexSessionsDirs = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.getCodexMonitoringHomes = exports.getSystemCodexHome = exports.getClaudeProjectsDir = exports.isDefaultClaudeHome = exports.getDefaultClaudeHome = exports.getLiveClaudeHome = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.getDefaultConfigDir = exports.getConfigDirOverride = exports.getConfigDir = exports.CONFIG_DIR_ENV_VAR = exports.SYNTHETIC_MODEL = exports.createSessionProviders = exports.splitWatchedPath = exports.DirectoryListingCache = exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionPreviewAsync = exports.readSessionPreview = exports.listSessionPreviewsAsync = exports.listSessionPreviews = exports.readCodexHistory = exports.resolveRolloutPath = exports.readRolloutText = exports.readRolloutBuffer = exports.isZstdDecompressionAvailable = exports.isCompressedRolloutPath = exports.COMPRESSED_ROLLOUT_SUFFIX = exports.walkRolloutFilesAsync = exports.walkRolloutFiles = exports.findCodexRolloutFile = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.importSessionHistory = exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = exports.sessionSummaryFromStats = void 0;
+exports.verifyJsonlCheckpoint = exports.JsonlTailSymlinkError = exports.JSONL_TAIL_CHECKPOINT_VERSION = exports.DEFAULT_JSONL_TAIL_READ_BYTES = exports.DEFAULT_JSONL_TAIL_MAX_LINE_BYTES = exports.createJsonlTail = exports.captureJsonlCheckpoint = exports.resolveWorktreeMainRepo = exports.discoverWorktreeSiblings = exports.resolveWorkspaceRoots = exports.TOOL_CATEGORIES = exports.classifyTool = exports.fetchProviderServiceStatus = exports.clearRegisteredModelPricing = exports.registerModelPricing = exports.getPricingCatalogInfo = exports.subagentActivityFromEvent = exports.parseCodexAgentMessageText = exports.isSubagentActivitySystemEvent = exports.describeSubagentActivity = exports.SUBAGENT_ACTIVITY_ORIGIN_KIND = exports.SUBAGENT_ACTIVITY_BLOCK_TYPE = exports.codexSpawnParentFromSource = exports.codexRolloutOrigin = exports.parseCodexLoginStatus = exports.parseClaudeAuthStatus = exports.atomicWriteJsonSync = exports.atomicWriteJson = exports.compareCodexAuthFreshness = exports.codexRefreshFingerprint = exports.codexIdentitiesMatch = exports.readCodexAccessTokenExpiry = exports.readCodexLastRefresh = void 0;
 var pricingCatalog_1 = require("./pricingCatalog");
 Object.defineProperty(exports, "hydratePricingCatalog", { enumerable: true, get: function () { return pricingCatalog_1.hydratePricingCatalog; } });
 Object.defineProperty(exports, "normalizeLiteLlmCatalog", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmCatalog; } });
@@ -89,6 +89,13 @@ Object.defineProperty(exports, "findCodexRolloutFile", { enumerable: true, get:
 var rolloutWalker_1 = require("./providers/rolloutWalker");
 Object.defineProperty(exports, "walkRolloutFiles", { enumerable: true, get: function () { return rolloutWalker_1.walkRolloutFiles; } });
 Object.defineProperty(exports, "walkRolloutFilesAsync", { enumerable: true, get: function () { return rolloutWalker_1.walkRolloutFilesAsync; } });
+var compressedRollouts_1 = require("./providers/compressedRollouts");
+Object.defineProperty(exports, "COMPRESSED_ROLLOUT_SUFFIX", { enumerable: true, get: function () { return compressedRollouts_1.COMPRESSED_ROLLOUT_SUFFIX; } });
+Object.defineProperty(exports, "isCompressedRolloutPath", { enumerable: true, get: function () { return compressedRollouts_1.isCompressedRolloutPath; } });
+Object.defineProperty(exports, "isZstdDecompressionAvailable", { enumerable: true, get: function () { return compressedRollouts_1.isZstdDecompressionAvailable; } });
+Object.defineProperty(exports, "readRolloutBuffer", { enumerable: true, get: function () { return compressedRollouts_1.readRolloutBuffer; } });
+Object.defineProperty(exports, "readRolloutText", { enumerable: true, get: function () { return compressedRollouts_1.readRolloutText; } });
+Object.defineProperty(exports, "resolveRolloutPath", { enumerable: true, get: function () { return compressedRollouts_1.resolveRolloutPath; } });
 var codexHistory_1 = require("./parsers/codexHistory");
 Object.defineProperty(exports, "readCodexHistory", { enumerable: true, get: function () { return codexHistory_1.readCodexHistory; } });
 var sessionPreviews_1 = require("./sessionPreviews");
@@ -151,6 +158,13 @@ Object.defineProperty(exports, "parseCodexLoginStatus", { enumerable: true, get:
 var codexRolloutOrigin_1 = require("./parsers/codexRolloutOrigin");
 Object.defineProperty(exports, "codexRolloutOrigin", { enumerable: true, get: function () { return codexRolloutOrigin_1.codexRolloutOrigin; } });
 Object.defineProperty(exports, "codexSpawnParentFromSource", { enumerable: true, get: function () { return codexRolloutOrigin_1.codexSpawnParentFromSource; } });
+var subagentActivity_1 = require("./subagentActivity");
+Object.defineProperty(exports, "SUBAGENT_ACTIVITY_BLOCK_TYPE", { enumerable: true, get: function () { return subagentActivity_1.SUBAGENT_ACTIVITY_BLOCK_TYPE; } });
+Object.defineProperty(exports, "SUBAGENT_ACTIVITY_ORIGIN_KIND", { enumerable: true, get: function () { return subagentActivity_1.SUBAGENT_ACTIVITY_ORIGIN_KIND; } });
+Object.defineProperty(exports, "describeSubagentActivity", { enumerable: true, get: function () { return subagentActivity_1.describeSubagentActivity; } });
+Object.defineProperty(exports, "isSubagentActivitySystemEvent", { enumerable: true, get: function () { return subagentActivity_1.isSubagentActivitySystemEvent; } });
+Object.defineProperty(exports, "parseCodexAgentMessageText", { enumerable: true, get: function () { return subagentActivity_1.parseCodexAgentMessageText; } });
+Object.defineProperty(exports, "subagentActivityFromEvent", { enumerable: true, get: function () { return subagentActivity_1.subagentActivityFromEvent; } });
 var modelInfo_1 = require("./modelInfo");
 Object.defineProperty(exports, "getPricingCatalogInfo", { enumerable: true, get: function () { return modelInfo_1.getPricingCatalogInfo; } });
 Object.defineProperty(exports, "registerModelPricing", { enumerable: true, get: function () { return modelInfo_1.registerModelPricing; } });

package/dist/parsers/codexParser.d.ts

@@ -88,6 +88,15 @@ export interface CodexRolloutParserOptions {
      * unchanged. For cheap passes over large rollouts; default false.
      */
     metadataOnly?: boolean;
+    /**
+     * Emit the multi-agent lifecycle as `system` events with `origin: { kind:
+     * 'subagent-activity' }` (read them with `subagentActivityFromEvent()`):
+     * `SubAgentActivity` items (`started`, `completed`, `interacted`,
+     * `interrupted`) and each `FINAL_ANSWER` agent message. Transcripts,
+     * context attribution, and the aggregator's message counts skip them.
+     * Default false: those records produce no events.
+     */
+    includeSubagentActivity?: boolean;
 }
 /** Pending tool-call state counters from {@link CodexRolloutParser.getPendingStats}. */
 export interface CodexPendingStats {
@@ -126,6 +135,18 @@ export interface CodexRolloutResumeState {
     pendingExecCommands: PendingExecCommand[];
     /** `mcp_tool_call_begin` events awaiting their end. */
     pendingMcpToolCalls: PendingMcpToolCall[];
+    /**
+     * Multi-agent tool calls by call id with their raw tool names, so a later
+     * `SubAgentActivity` record names its tool. Optional: absent in states
+     * from earlier versions (and when `includeSubagentActivity` is off).
+     */
+    collaborationCalls?: Array<[string, string]>;
+    /**
+     * Forked subagent rollouts: the ordinal below which records are the
+     * embedded parent history (see `getInheritedHistoryEnd()`). Optional:
+     * absent (nothing skipped) in states from earlier versions.
+     */
+    inheritedHistoryEnd?: number | null;
 }
 /** A valid `CodexTokenUsage` (copied), `null` for `null`, or `undefined` when invalid. Internal. */
 export declare function codexTokenUsageFrom(value: unknown): CodexTokenUsage | null | undefined;
@@ -156,6 +177,15 @@ export declare class CodexRolloutParser {
     /** Byte budget for pending calls; `null` = unlimited (no accounting). */
     private readonly maxPendingBytes;
     private readonly metadataOnly;
+    private readonly includeSubagentActivity;
+    /**
+     * Set once a forked child's rollout embeds an ancestor's session_meta: its
+     * own `subagent_history_start_ordinal`, below which records are the
+     * parent's history and are skipped. `null` while nothing is skipped.
+     */
+    private historyStartOrdinal;
+    /** Multi-agent tool calls (call id → raw name), only with `includeSubagentActivity`. */
+    private collaborationCalls;
     /** Pending calls in insertion order, for the byte budget. */
     private pendingLedger;
     private pendingBytes;
@@ -174,6 +204,14 @@ export declare class CodexRolloutParser {
     getModelContextWindow(): number | null;
     /** Get the last observed rate limits from token_count events. */
     getLastRateLimits(): CodexRateLimits | null;
+    /**
+     * In a forked subagent's rollout, the ordinal of its first own record:
+     * records with a lower `ordinal` are the parent history the fork embeds
+     * and produce no events. Known once the rollout's second line (an embedded
+     * ancestor `session_meta`) was parsed; `null` otherwise, and for every
+     * rollout that is not such a fork.
+     */
+    getInheritedHistoryEnd(): number | null;
     /**
      * The state later lines depend on — session metadata, current model,
      * previous cumulative token total, context window, rate limits, plan mode,
@@ -214,6 +252,12 @@ export declare class CodexRolloutParser {
     private toolOutput;
     private handleSessionMeta;
     private handleResponseItem;
+    private rememberCollaborationCall;
+    private subagentActivityEvent;
+    /** A child's `FINAL_ANSWER` message to its parent (opt-in). */
+    private handleAgentMessage;
+    /** A `SubAgentActivity` turn item (opt-in). */
+    private handleItemCompleted;
     private handleMessage;
     private handleReasoning;
     private handleFunctionCall;

package/dist/parsers/codexParser.js

@@ -22,6 +22,7 @@ exports.codexTokenUsageFrom = codexTokenUsageFrom;
 const codex_1 = require("../types/codex");
 const openCodeParser_1 = require("./openCodeParser");
 const usageNormalization_1 = require("../usageNormalization");
+const subagentActivity_1 = require("../subagentActivity");
 function reportedCompaction(tokensBefore, tokensAfter) {
     if (typeof tokensBefore !== 'number' ||
         typeof tokensAfter !== 'number' ||
@@ -181,6 +182,29 @@ function extractPatchFilePaths(input) {
 exports.DEFAULT_MAX_TRACKED_TOOL_CALLS = 4096;
 /** Entries per table {@link CodexRolloutParser.exportResumeState} keeps by default. */
 const DEFAULT_RESUME_STATE_LIMIT = 256;
+/** Raw names of Codex's multi-agent tools (namespace `collaboration`). */
+const COLLABORATION_TOOL_NAMES = new Set([
+    'spawn_agent',
+    'followup_task',
+    'send_message',
+    'interrupt_agent',
+    'wait_agent',
+    'list_agents',
+]);
+const SUBAGENT_ACTIVITY_KINDS = new Set([
+    'started',
+    'completed',
+    'interacted',
+    'interrupted',
+]);
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** `subagent_history_start_ordinal` of a session_meta payload, when valid. */
+function historyStartOrdinalOf(meta) {
+    const value = meta?.subagent_history_start_ordinal;
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
+}
 function isPlainObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -298,6 +322,15 @@ class CodexRolloutParser {
     /** Byte budget for pending calls; `null` = unlimited (no accounting). */
     maxPendingBytes;
     metadataOnly;
+    includeSubagentActivity;
+    /**
+     * Set once a forked child's rollout embeds an ancestor's session_meta: its
+     * own `subagent_history_start_ordinal`, below which records are the
+     * parent's history and are skipped. `null` while nothing is skipped.
+     */
+    historyStartOrdinal = null;
+    /** Multi-agent tool calls (call id → raw name), only with `includeSubagentActivity`. */
+    collaborationCalls = new Map();
     /** Pending calls in insertion order, for the byte budget. */
     pendingLedger = new Map();
     pendingBytes = 0;
@@ -313,6 +346,7 @@ class CodexRolloutParser {
                 ? Math.floor(maxBytes)
                 : null;
         this.metadataOnly = options.metadataOnly === true;
+        this.includeSubagentActivity = options.includeSubagentActivity === true;
     }
     /** Counters for the pending tool-call state and what the caps evicted. */
     getPendingStats() {
@@ -345,6 +379,16 @@ class CodexRolloutParser {
     getLastRateLimits() {
         return this.lastRateLimits;
     }
+    /**
+     * In a forked subagent's rollout, the ordinal of its first own record:
+     * records with a lower `ordinal` are the parent history the fork embeds
+     * and produce no events. Known once the rollout's second line (an embedded
+     * ancestor `session_meta`) was parsed; `null` otherwise, and for every
+     * rollout that is not such a fork.
+     */
+    getInheritedHistoryEnd() {
+        return this.historyStartOrdinal;
+    }
     /**
      * The state later lines depend on — session metadata, current model,
      * previous cumulative token total, context window, rate limits, plan mode,
@@ -366,6 +410,14 @@ class CodexRolloutParser {
             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),
+            ...(this.historyStartOrdinal !== null
+                ? { inheritedHistoryEnd: this.historyStartOrdinal }
+                : {}),
+            ...(this.collaborationCalls.size > 0
+                ? {
+                    collaborationCalls: newest(this.collaborationCalls, this.collaborationCalls.size, limit),
+                }
+                : {}),
         });
     }
     /**
@@ -426,6 +478,21 @@ class CodexRolloutParser {
                 typeof entry.timestamp === 'string')) {
             return false;
         }
+        const inheritedEnd = s.inheritedHistoryEnd;
+        if (inheritedEnd !== undefined &&
+            inheritedEnd !== null &&
+            !(typeof inheritedEnd === 'number' && Number.isInteger(inheritedEnd) && inheritedEnd > 0)) {
+            return false;
+        }
+        const collaborationCalls = s.collaborationCalls;
+        if (collaborationCalls !== undefined &&
+            !(Array.isArray(collaborationCalls) &&
+                collaborationCalls.every((entry) => Array.isArray(entry) &&
+                    entry.length === 2 &&
+                    typeof entry[0] === 'string' &&
+                    typeof entry[1] === 'string'))) {
+            return false;
+        }
         const copy = cloneJson({
             sessionMeta: s.sessionMeta,
             lastRateLimits: s.lastRateLimits,
@@ -435,6 +502,7 @@ class CodexRolloutParser {
         });
         this.reset();
         this.sessionMeta = copy.sessionMeta;
+        this.historyStartOrdinal = typeof inheritedEnd === 'number' ? inheritedEnd : null;
         this.currentModel = s.currentModel;
         this.prevTotalUsage = prevTotalUsage;
         this.lastTokenUsage = lastTokenUsage;
@@ -455,15 +523,28 @@ class CodexRolloutParser {
         for (const pending of copy.mcps) {
             this.putPendingMcp(this.metadataOnly ? { ...pending, arguments: undefined } : pending);
         }
+        if (this.includeSubagentActivity && Array.isArray(collaborationCalls)) {
+            for (const [callId, name] of collaborationCalls) {
+                this.rememberCollaborationCall(callId, name);
+            }
+        }
         return true;
     }
     /**
      * Converts a single rollout line to zero or more session events.
      */
     convertLine(line) {
+        if (line.type === 'session_meta') {
+            return this.handleSessionMeta(line.timestamp, line.payload, line.ordinal);
+        }
+        // A forked subagent rollout embeds the parent's history before its own
+        // records; that history is the parent's, not the child's.
+        if (this.historyStartOrdinal !== null &&
+            typeof line.ordinal === 'number' &&
+            line.ordinal < this.historyStartOrdinal) {
+            return [];
+        }
         switch (line.type) {
-            case 'session_meta':
-                return this.handleSessionMeta(line.timestamp, line.payload);
             case 'response_item':
                 return this.handleResponseItem(line.timestamp, line.payload);
             case 'compacted':
@@ -479,6 +560,8 @@ class CodexRolloutParser {
     /** Reset all parser state. */
     reset() {
         this.sessionMeta = null;
+        this.historyStartOrdinal = null;
+        this.collaborationCalls.clear();
         this.currentModel = null;
         this.pendingExecCommands.clear();
         this.pendingMcpToolCalls.clear();
@@ -568,7 +651,25 @@ class CodexRolloutParser {
         return this.metadataOnly ? '' : content;
     }
     // --- Handlers ---
-    handleSessionMeta(timestamp, payload) {
+    handleSessionMeta(timestamp, payload, ordinal) {
+        if (this.sessionMeta) {
+            // Only the rollout's own (first) session_meta counts. A forked child
+            // embeds its parent's right after its own, followed by the parent's
+            // history up to the child's `subagent_history_start_ordinal`; from
+            // here on, records below that ordinal are skipped. (Children whose
+            // rollout has no embedded meta keep every record: in some, Codex
+            // recorded a start ordinal past their own records.)
+            const start = historyStartOrdinalOf(this.sessionMeta);
+            if (this.historyStartOrdinal === null &&
+                start !== null &&
+                typeof ordinal === 'number' &&
+                ordinal < start) {
+                this.historyStartOrdinal = start;
+            }
+            return [];
+        }
+        if (!payload || typeof payload !== 'object')
+            return [];
         this.sessionMeta = payload;
         const text = payload.base_instructions?.text?.trim();
         return [
@@ -608,10 +709,91 @@ class CodexRolloutParser {
                 return this.handleCustomToolCall(timestamp, payload);
             case 'custom_tool_call_output':
                 return this.handleCustomToolCallOutput(timestamp, payload);
+            case 'agent_message':
+                return this.handleAgentMessage(timestamp, payload);
             default:
                 return [];
         }
     }
+    // --- Subagent activity ---
+    rememberCollaborationCall(callId, name) {
+        this.collaborationCalls.delete(callId);
+        this.collaborationCalls.set(callId, name);
+        while (this.collaborationCalls.size > this.maxTrackedToolCalls) {
+            this.collaborationCalls.delete(this.collaborationCalls.keys().next().value);
+        }
+    }
+    subagentActivityEvent(timestamp, id, activity) {
+        return {
+            type: 'system',
+            timestamp,
+            origin: { kind: subagentActivity_1.SUBAGENT_ACTIVITY_ORIGIN_KIND },
+            message: {
+                role: 'system',
+                id: `subagent-activity:${id}`,
+                sourceLabel: 'subagent activity',
+                content: [{ type: subagentActivity_1.SUBAGENT_ACTIVITY_BLOCK_TYPE, ...activity }],
+            },
+            providerMetadata: { providerId: 'codex', source: 'codex-rollout' },
+        };
+    }
+    /** A child's `FINAL_ANSWER` message to its parent (opt-in). */
+    handleAgentMessage(timestamp, item) {
+        if (!this.includeSubagentActivity || !Array.isArray(item.content))
+            return [];
+        const first = item.content.find((part) => !!part && typeof part === 'object' && typeof part.text === 'string');
+        const parsed = (0, subagentActivity_1.parseCodexAgentMessageText)(first?.text);
+        if (!parsed || parsed.messageType !== 'FINAL_ANSWER')
+            return [];
+        const agentPath = nonEmptyString(item.author) ?? parsed.sender;
+        const recipient = nonEmptyString(item.recipient) ?? parsed.taskName;
+        const text = this.metadataOnly ? undefined : nonEmptyString(parsed.payload.trim());
+        const activity = {
+            kind: 'final-answer',
+            ...(agentPath ? { agentPath } : {}),
+            ...(recipient ? { recipient } : {}),
+            ...(text ? { text } : {}),
+        };
+        return [
+            this.subagentActivityEvent(timestamp, nonEmptyString(item.id) ?? `final-answer-${timestamp}-${agentPath ?? ''}`, activity),
+        ];
+    }
+    /** A `SubAgentActivity` turn item (opt-in). */
+    handleItemCompleted(timestamp, event) {
+        if (!this.includeSubagentActivity)
+            return [];
+        const item = event.item;
+        if (!item || item.type !== 'SubAgentActivity')
+            return [];
+        const kind = typeof item.kind === 'string' ? item.kind : '';
+        if (!SUBAGENT_ACTIVITY_KINDS.has(kind))
+            return [];
+        const itemId = nonEmptyString(item.id);
+        const completedTurn = kind === 'completed' && itemId?.startsWith('subagent-completed-')
+            ? nonEmptyString(itemId.slice('subagent-completed-'.length))
+            : undefined;
+        const callId = kind === 'completed' ? undefined : itemId;
+        const tool = callId ? this.collaborationCalls.get(callId) : undefined;
+        const fields = {
+            callId,
+            tool,
+            turnId: completedTurn,
+            agentThreadId: nonEmptyString(item.agent_thread_id),
+            agentPath: nonEmptyString(item.agent_path),
+            model: nonEmptyString(item.model),
+            reasoningEffort: nonEmptyString(item.reasoning_effort),
+            parentThreadId: nonEmptyString(event.thread_id),
+            parentTurnId: nonEmptyString(event.turn_id),
+        };
+        const activity = { kind: kind };
+        for (const [key, value] of Object.entries(fields)) {
+            if (value !== undefined)
+                activity[key] = value;
+        }
+        return [
+            this.subagentActivityEvent(timestamp, itemId ?? `${kind}-${timestamp}-${activity.agentThreadId ?? ''}`, activity),
+        ];
+    }
     handleMessage(timestamp, item) {
         const text = extractTextFromContent(item.content);
         if (!text)
@@ -693,6 +875,11 @@ class CodexRolloutParser {
         const canonicalName = normalizeCodexToolName(item.name);
         const normalizedInput = normalizeCodexToolInput(canonicalName, item.name, parsedArgs);
         rememberBounded(this.emittedToolUseIds, item.call_id, this.maxTrackedToolCalls);
+        if (this.includeSubagentActivity &&
+            typeof item.call_id === 'string' &&
+            (item.namespace === 'collaboration' || COLLABORATION_TOOL_NAMES.has(item.name))) {
+            this.rememberCollaborationCall(item.call_id, item.name);
+        }
         return [
             {
                 type: 'assistant',
@@ -1149,6 +1336,8 @@ class CodexRolloutParser {
                         timestamp,
                     },
                 ];
+            case 'item_completed':
+                return this.handleItemCompleted(timestamp, event);
             case 'turn_aborted':
             case 'agent_reasoning':
             case 'agent_message':

package/dist/parsers/subagentEndState.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a Claude Code subagent transcript ended cleanly, read line by line.
+ *
+ * Clean means: the last user or assistant line is an assistant line that
+ * stopped with `end_turn` or `stop_sequence`, and every `tool_use` in the
+ * transcript has its `tool_result`. A user line after that (a resumed agent's
+ * new prompt) makes it unfinished again.
+ *
+ * Pure. Internal to the subagent parsers.
+ *
+ * @module parsers/subagentEndState
+ */
+export declare class SubagentEndTracker {
+    private readonly unanswered;
+    private lastWasCleanAssistant;
+    /** Feeds one parsed JSONL line, in file order. */
+    observe(raw: unknown): void;
+    /** Whether the lines so far end cleanly. */
+    endedCleanly(): boolean;
+}

package/dist/parsers/subagentEndState.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Whether a Claude Code subagent transcript ended cleanly, read line by line.
+ *
+ * Clean means: the last user or assistant line is an assistant line that
+ * stopped with `end_turn` or `stop_sequence`, and every `tool_use` in the
+ * transcript has its `tool_result`. A user line after that (a resumed agent's
+ * new prompt) makes it unfinished again.
+ *
+ * Pure. Internal to the subagent parsers.
+ *
+ * @module parsers/subagentEndState
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubagentEndTracker = void 0;
+const ENDED_STOP_REASONS = new Set(['end_turn', 'stop_sequence']);
+/** Bounds the unanswered-call set for pathological transcripts. */
+const MAX_PENDING_TOOL_USES = 4096;
+class SubagentEndTracker {
+    unanswered = new Set();
+    lastWasCleanAssistant = false;
+    /** Feeds one parsed JSONL line, in file order. */
+    observe(raw) {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const line = raw;
+        if (line.type !== 'assistant' && line.type !== 'user')
+            return;
+        const message = line.message && typeof line.message === 'object'
+            ? line.message
+            : undefined;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        if (line.type === 'user') {
+            for (const block of content) {
+                if (!block || typeof block !== 'object')
+                    continue;
+                const typed = block;
+                if (typed.type === 'tool_result' && typeof typed.tool_use_id === 'string') {
+                    this.unanswered.delete(typed.tool_use_id);
+                }
+            }
+            this.lastWasCleanAssistant = false;
+            return;
+        }
+        let callsTool = false;
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const typed = block;
+            if (typed.type !== 'tool_use')
+                continue;
+            callsTool = true;
+            if (typeof typed.id === 'string' && this.unanswered.size < MAX_PENDING_TOOL_USES) {
+                this.unanswered.add(typed.id);
+            }
+        }
+        const stop = typeof message?.stop_reason === 'string' ? message.stop_reason : '';
+        this.lastWasCleanAssistant = !callsTool && ENDED_STOP_REASONS.has(stop);
+    }
+    /** Whether the lines so far end cleanly. */
+    endedCleanly() {
+        return this.lastWasCleanAssistant && this.unanswered.size === 0;
+    }
+}
+exports.SubagentEndTracker = SubagentEndTracker;

package/dist/parsers/subagentScanner.js

@@ -52,6 +52,7 @@ const claudeUsageDedupe_1 = require("../usage/claudeUsageDedupe");
 const subagentUsage_1 = require("../usage/subagentUsage");
 const subagentStatsCache_1 = require("./subagentStatsCache");
 const subagentSpawn_1 = require("../subagentSpawn");
+const subagentEndState_1 = require("./subagentEndState");
 /**
  * Pattern for matching subagent JSONL files.
  * Files are named like: agent-<hash>.jsonl
@@ -199,6 +200,7 @@ function parseAgentFile(filePath, agentId, log) {
         let description;
         const tokens = { agentId, toolCalls: [], inputTokens: 0, outputTokens: 0 };
         const usageDeduper = new claudeUsageDedupe_1.ClaudeUsageDeduper();
+        const endTracker = new subagentEndState_1.SubagentEndTracker();
         let startTime;
         let endTime;
         // Task tracking state
@@ -215,6 +217,7 @@ function parseAgentFile(filePath, agentId, log) {
                 if (!startTime)
                     startTime = eventTimestamp;
                 endTime = eventTimestamp;
+                endTracker.observe(event);
                 // Extract token usage from assistant messages. Split lines of one
                 // response repeat its usage, so count each response once.
                 const usage = (0, claudeUsageDedupe_1.dedupedRawClaudeUsage)(event, usageDeduper);
@@ -337,6 +340,7 @@ function parseAgentFile(filePath, agentId, log) {
                 startTime,
                 endTime,
                 durationMs,
+                endedCleanly: endTracker.endedCleanly(),
             };
         }
         return null;

package/dist/parsers/subagentTraceParser.d.ts

@@ -63,6 +63,14 @@ export interface SubagentTrace {
     finished?: boolean;
     /** The user stopped the agent (meta `stoppedByUser`). */
     stoppedByUser?: boolean;
+    /** Time of the transcript's last record (the same as `stats.endTime`). */
+    lastActivityAt?: Date;
+    /**
+     * The transcript ended cleanly: its last assistant turn stopped with
+     * `end_turn` / `stop_sequence` and no tool call is unanswered. A resumed
+     * agent's next prompt clears it.
+     */
+    endedCleanly?: boolean;
 }
 /**
  * Scans and parses subagent traces with full conversation events.

package/dist/parsers/subagentTraceParser.js

@@ -58,6 +58,7 @@ const noiseClassifier_1 = require("../formatters/noiseClassifier");
 const claudeUsageDedupe_1 = require("../usage/claudeUsageDedupe");
 const subagentUsage_1 = require("../usage/subagentUsage");
 const subagentScanner_1 = require("./subagentScanner");
+const subagentEndState_1 = require("./subagentEndState");
 const subagentSpawn_1 = require("../subagentSpawn");
 const ownKey_1 = require("../ownKey");
 // ── Constants ──
@@ -109,6 +110,7 @@ function parseAgentTrace(filePath, agentId) {
         let description;
         const tokens = { agentId, toolCalls: [], inputTokens: 0, outputTokens: 0 };
         const usageDeduper = new claudeUsageDedupe_1.ClaudeUsageDeduper();
+        const endTracker = new subagentEndState_1.SubagentEndTracker();
         let startTime;
         let endTime;
         for (const line of lines) {
@@ -118,6 +120,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)
@@ -218,6 +221,8 @@ function parseAgentTrace(filePath, agentId) {
             ...(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: {
@@ -234,6 +239,7 @@ function parseAgentTrace(filePath, agentId) {
                 startTime,
                 endTime,
                 durationMs,
+                endedCleanly: endTracker.endedCleanly(),
             },
         };
     }

package/dist/promptHistory.d.ts

@@ -23,8 +23,8 @@
  * the prompt is returned again under the same identity once its first
  * answering call brings model or usage (`metadataStatus` says how settled).
  */
-import * as fs from 'fs';
 import { type HumanPromptProvider } from './humanPrompt';
+import { type RolloutContentStat } from './providers/compressedRollouts';
 export type PromptHistoryProvider = HumanPromptProvider;
 export type PromptHistoryBound = 'maxSessions' | 'maxFileBytes' | 'maxTotalBytes' | 'maxEntries' | 'deadline' | 'aborted';
 export interface PromptHistoryBounds {
@@ -235,6 +235,14 @@ export interface CollectPromptHistoryOptions {
      * both modes, so a cursor written in one mode resumes in the other.
      */
     includeText?: boolean;
+    /**
+     * Codex: also scan compressed rollouts (`….jsonl.zst`, decompressed when
+     * the runtime has `zlib.zstdDecompressSync`; skipped otherwise). Offsets
+     * and sizes in the cursor are then those of the decompressed content, so
+     * a session whose rollout Codex compressed continues where it stopped.
+     * Default false.
+     */
+    includeCompressedRollouts?: boolean;
 }
 export interface PromptHistoryResult {
     /** Ordered by provider, session, then ordinal. */
@@ -375,6 +383,8 @@ export declare function resolveRoots(workspacePaths: string[], includeWorktrees:
     listingRoots: string[];
 };
 /** @internal */
-export declare function listCandidates(providers: PromptHistoryProvider[], listingRoots: string[], sinceMs: number | null): Promise<Candidate[]>;
+export declare function listCandidates(providers: PromptHistoryProvider[], listingRoots: string[], sinceMs: number | null, options?: {
+    includeCompressedRollouts?: boolean;
+}): Promise<Candidate[]>;
 /** @internal */
-export declare function scanFile(candidate: Candidate, stat: fs.Stats, prior: PromptHistoryCursorSession | undefined, budget: FileBudget, context: ScanContext): Promise<FileOutcome>;
+export declare function scanFile(candidate: Candidate, fileStat: RolloutContentStat, prior: PromptHistoryCursorSession | undefined, budget: FileBudget, context: ScanContext): Promise<FileOutcome>;