sidekick-shared 0.29.0 → 0.30.0

package/dist/providers/codexCompressedReader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session reader for a compressed Codex rollout (`rollout-…jsonl.zst`).
+ *
+ * Codex compresses only rollouts it no longer writes, so the content is
+ * decompressed and parsed whole on the first read; later reads cost one
+ * stat and return nothing until the file changes (then the rollout is read
+ * again from the start, reported as `replaced`). Positions are offsets in
+ * the decompressed content. Live tailing stays with the `.jsonl` reader.
+ *
+ * Node-only: reads files.
+ *
+ * @module providers/codexCompressedReader
+ */
+import { type CodexRolloutResumeState } from '../parsers/codexParser';
+import type { CodexRateLimits, CodexSessionMeta } from '../types/codex';
+import type { SessionEvent, TokenUsage } from '../types/sessionEvent';
+import { type ReadRolloutOptions } from './compressedRollouts';
+import type { SessionReader } from './types';
+type ReaderReset = NonNullable<ReturnType<NonNullable<SessionReader['lastReset']>>>;
+export interface CompressedCodexReaderCallbacks {
+    onContextWindowLimit?: (limit: number, modelId?: string) => void;
+    onRateLimits?: (limits: CodexRateLimits) => void;
+    onTokenUsage?: (usage: TokenUsage) => void;
+    onDiagnostic?: ReadRolloutOptions['onDiagnostic'];
+}
+/** Reads a `.jsonl.zst` rollout through a {@link CodexRolloutParser}. */
+export declare class CompressedCodexRolloutReader implements SessionReader {
+    private readonly rolloutPath;
+    private readonly callbacks;
+    private parser;
+    /** Offset after the last line parsed (the content is complete, so its end). */
+    private position;
+    /** Size and mtime of the compressed file the position refers to. */
+    private source;
+    private reset_;
+    /** Position from `seekTo()` whose prefix still has to be parsed for context. */
+    private pendingSeek;
+    constructor(rolloutPath: string, callbacks?: CompressedCodexReaderCallbacks);
+    getSessionMeta(): CodexSessionMeta | null;
+    readNew(): SessionEvent[];
+    readAll(): SessionEvent[];
+    reset(): void;
+    exists(): boolean;
+    flush(): void;
+    getPosition(): number;
+    seekTo(position: number): void;
+    wasTruncated(): boolean;
+    lastReset(): ReaderReset | null;
+    getResumeState(): CodexRolloutResumeState;
+    restoreResumeState(state: unknown): boolean;
+    /** Parses the content past `position`; `emit` false only rebuilds parser state. */
+    private readFrom;
+    /** Rebuilds parser context for a pending `seekTo()` position. */
+    private settleSeek;
+    /** Hands the parser's context window, rate limits, and last usage to the provider. */
+    private propagateParserState;
+}
+export {};

package/dist/providers/codexCompressedReader.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Session reader for a compressed Codex rollout (`rollout-…jsonl.zst`).
+ *
+ * Codex compresses only rollouts it no longer writes, so the content is
+ * decompressed and parsed whole on the first read; later reads cost one
+ * stat and return nothing until the file changes (then the rollout is read
+ * again from the start, reported as `replaced`). Positions are offsets in
+ * the decompressed content. Live tailing stays with the `.jsonl` reader.
+ *
+ * Node-only: reads files.
+ *
+ * @module providers/codexCompressedReader
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompressedCodexRolloutReader = void 0;
+const fs = __importStar(require("fs"));
+const codexParser_1 = require("../parsers/codexParser");
+const usageNormalization_1 = require("../usageNormalization");
+const compressedRollouts_1 = require("./compressedRollouts");
+/** Reads a `.jsonl.zst` rollout through a {@link CodexRolloutParser}. */
+class CompressedCodexRolloutReader {
+    rolloutPath;
+    callbacks;
+    parser = new codexParser_1.CodexRolloutParser({ includeSubagentActivity: true });
+    /** Offset after the last line parsed (the content is complete, so its end). */
+    position = 0;
+    /** Size and mtime of the compressed file the position refers to. */
+    source = null;
+    reset_ = null;
+    /** Position from `seekTo()` whose prefix still has to be parsed for context. */
+    pendingSeek = null;
+    constructor(rolloutPath, callbacks = {}) {
+        this.rolloutPath = rolloutPath;
+        this.callbacks = callbacks;
+    }
+    getSessionMeta() {
+        this.settleSeek();
+        return this.parser.getSessionMeta();
+    }
+    readNew() {
+        this.settleSeek();
+        this.reset_ = null;
+        return this.readFrom(true);
+    }
+    readAll() {
+        this.reset();
+        return this.readNew();
+    }
+    reset() {
+        this.parser.reset();
+        this.position = 0;
+        this.source = null;
+        this.reset_ = null;
+        this.pendingSeek = null;
+    }
+    exists() {
+        return fs.existsSync(this.rolloutPath);
+    }
+    flush() {
+        // Nothing is buffered: each read parses through the end of the content.
+    }
+    getPosition() {
+        return this.position;
+    }
+    seekTo(position) {
+        this.reset();
+        this.position = Math.max(0, position);
+        if (this.position > 0)
+            this.pendingSeek = this.position;
+    }
+    wasTruncated() {
+        return this.reset_ !== null;
+    }
+    lastReset() {
+        return this.reset_ ? { ...this.reset_ } : null;
+    }
+    getResumeState() {
+        this.settleSeek();
+        return this.parser.exportResumeState();
+    }
+    restoreResumeState(state) {
+        if (!this.parser.importResumeState(state))
+            return false;
+        this.pendingSeek = null;
+        this.propagateParserState();
+        return true;
+    }
+    /** Parses the content past `position`; `emit` false only rebuilds parser state. */
+    readFrom(emit, endPosition) {
+        let stat;
+        try {
+            stat = fs.statSync(this.rolloutPath);
+        }
+        catch {
+            return [];
+        }
+        const current = { size: stat.size, mtimeMs: stat.mtimeMs };
+        if (this.source &&
+            (this.source.size !== current.size || this.source.mtimeMs !== current.mtimeMs)) {
+            // Another file has the path: what was read no longer describes it.
+            this.reset_ = { reason: 'replaced', previousPosition: this.position };
+            this.parser.reset();
+            this.position = 0;
+        }
+        else if (this.source) {
+            return [];
+        }
+        const content = (0, compressedRollouts_1.readRolloutBuffer)(this.rolloutPath, {
+            onDiagnostic: this.callbacks.onDiagnostic,
+        });
+        if (!content)
+            return [];
+        this.source = current;
+        const end = Math.min(content.length, endPosition ?? content.length);
+        if (this.position > end) {
+            // The position sought lies past this content: start over.
+            this.reset_ = { reason: 'truncated', previousPosition: this.position };
+            this.parser.reset();
+            this.position = 0;
+        }
+        const events = [];
+        const text = content.toString('utf8', this.position, end);
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const converted = this.parser.convertLine(JSON.parse(trimmed));
+                if (emit)
+                    events.push(...converted);
+            }
+            catch {
+                // Skip malformed lines.
+            }
+        }
+        this.position = end;
+        if (end < content.length)
+            this.source = null;
+        this.propagateParserState();
+        return events;
+    }
+    /** Rebuilds parser context for a pending `seekTo()` position. */
+    settleSeek() {
+        const position = this.pendingSeek;
+        if (position === null)
+            return;
+        this.pendingSeek = null;
+        this.parser.reset();
+        this.position = 0;
+        this.source = null;
+        this.readFrom(false, position);
+    }
+    /** Hands the parser's context window, rate limits, and last usage to the provider. */
+    propagateParserState() {
+        const { onContextWindowLimit, onRateLimits, onTokenUsage } = this.callbacks;
+        const window = this.parser.getModelContextWindow();
+        if (window && onContextWindowLimit) {
+            onContextWindowLimit(window, this.parser.getCurrentModel() ?? undefined);
+        }
+        const rateLimits = this.parser.getLastRateLimits();
+        if (rateLimits && onRateLimits)
+            onRateLimits(rateLimits);
+        const lastUsage = this.parser.getLastTokenUsage();
+        if (lastUsage && onTokenUsage) {
+            const normalized = (0, usageNormalization_1.normalizeProviderUsage)({
+                semantics: 'openai',
+                provider: 'openai',
+                source: 'codex-reader-snapshot',
+                model: this.parser.getCurrentModel() || undefined,
+                inputTokens: lastUsage.input_tokens,
+                outputTokens: lastUsage.output_tokens,
+                cacheReadTokens: lastUsage.cached_input_tokens,
+                reasoningTokens: lastUsage.reasoning_output_tokens,
+            });
+            onTokenUsage({
+                inputTokens: normalized.uncachedInputTokens,
+                outputTokens: normalized.outputTokens,
+                cacheWriteTokens: normalized.cacheWriteTokens,
+                cacheReadTokens: normalized.cacheReadTokens,
+                reasoningTokens: normalized.reasoningTokens,
+                model: this.parser.getCurrentModel() || 'unknown',
+                timestamp: new Date(),
+            });
+        }
+    }
+}
+exports.CompressedCodexRolloutReader = CompressedCodexRolloutReader;

package/dist/providers/codexDatabase.d.ts

@@ -7,6 +7,21 @@ import type { ProviderRuntimeStatus } from './types';
 import { codexSpawnParentFromSource as spawnParentFromSource } from '../parsers/codexRolloutOrigin';
 /** Parent thread id of a spawned subagent's `source`; one rule shared with rollout parsing. */
 export { spawnParentFromSource };
+/** Default levels {@link CodexDatabase.getSpawnedDescendantThreads} follows. */
+export declare const DEFAULT_SUBAGENT_TREE_MAX_DEPTH = 8;
+/** A spawned thread below a session, with the thread that spawned it. */
+export interface CodexSpawnedThread {
+    thread: CodexDbThread;
+    /** The thread that spawned it: the session for depth 1, else another descendant. */
+    parentId: string;
+    /** 1 for the session's own children, 2 for theirs, … */
+    depth: number;
+}
+/**
+ * Whether a thread row is a subagent's rather than a session a person
+ * started: `thread_source: 'subagent'`, or a `{ subagent: … }` source.
+ */
+export declare function isCodexSubagentThread(thread: Pick<CodexDbThread, 'source' | 'thread_source'>): boolean;
 export declare class CodexDatabase {
     private readonly dbPath;
     private sqlite3Available;
@@ -20,6 +35,10 @@ export declare class CodexDatabase {
     private queryAsync;
     private queryOne;
     getThreadsByCwd(cwd: string): CodexDbThread[];
+    /**
+     * The workspace's most recently updated thread that a person started:
+     * subagent threads (which share their parent's cwd) are skipped.
+     */
     getMostRecentThread(cwd: string): CodexDbThread | null;
     getAllDistinctCwds(): Array<{
         cwd: string;
@@ -47,6 +66,12 @@ export declare class CodexDatabase {
      * the LIKE narrows the scan and the JSON parse confirms the match.
      */
     getSpawnedChildThreads(parentId: string): CodexDbThread[];
+    /**
+     * Every subagent thread below a session, level by level (one query per
+     * level, in chunks of ids), oldest first within a level: its children,
+     * their children, and so on up to `maxDepth` levels.
+     */
+    getSpawnedDescendantThreads(rootId: string, maxDepth?: number): CodexSpawnedThread[];
     /** Get the database file's mtime (ms epoch). Returns 0 if unavailable. */
     getDbMtime(): number;
 }

package/dist/providers/codexDatabase.js

@@ -37,7 +37,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CodexDatabase = exports.spawnParentFromSource = void 0;
+exports.CodexDatabase = exports.DEFAULT_SUBAGENT_TREE_MAX_DEPTH = exports.spawnParentFromSource = void 0;
+exports.isCodexSubagentThread = isCodexSubagentThread;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -48,6 +49,17 @@ Object.defineProperty(exports, "spawnParentFromSource", { enumerable: true, get:
  * element to sqlite3, so an unbounded list would hit E2BIG on large stores.
  */
 const SQL_ID_CHUNK_SIZE = 400;
+/** Default levels {@link CodexDatabase.getSpawnedDescendantThreads} follows. */
+exports.DEFAULT_SUBAGENT_TREE_MAX_DEPTH = 8;
+/**
+ * Whether a thread row is a subagent's rather than a session a person
+ * started: `thread_source: 'subagent'`, or a `{ subagent: … }` source.
+ */
+function isCodexSubagentThread(thread) {
+    if (thread.thread_source === 'subagent')
+        return true;
+    return (0, codexRolloutOrigin_1.codexRolloutOrigin)({ source: thread.source }).isSubagent;
+}
 class CodexDatabase {
     dbPath;
     sqlite3Available = null;
@@ -176,8 +188,12 @@ class CodexDatabase {
                 threadCwd.startsWith(normalized + path.sep));
         });
     }
+    /**
+     * The workspace's most recently updated thread that a person started:
+     * subagent threads (which share their parent's cwd) are skipped.
+     */
     getMostRecentThread(cwd) {
-        return this.getThreadsByCwd(cwd)[0] ?? null;
+        return this.getThreadsByCwd(cwd).find((thread) => !isCodexSubagentThread(thread)) ?? null;
     }
     getAllDistinctCwds() {
         return this.query('SELECT cwd, COUNT(*) as count, MAX(updated_at) as lastUpdated FROM threads GROUP BY cwd ORDER BY lastUpdated DESC');
@@ -230,6 +246,36 @@ class CodexDatabase {
         const rows = this.query('SELECT * FROM threads WHERE source LIKE ? ORDER BY created_at ASC', [`%${parentId}%`]);
         return rows.filter((row) => (0, codexRolloutOrigin_1.codexSpawnParentFromSource)(row.source) === parentId);
     }
+    /**
+     * Every subagent thread below a session, level by level (one query per
+     * level, in chunks of ids), oldest first within a level: its children,
+     * their children, and so on up to `maxDepth` levels.
+     */
+    getSpawnedDescendantThreads(rootId, maxDepth = exports.DEFAULT_SUBAGENT_TREE_MAX_DEPTH) {
+        if (!this.getThreadColumns().has('source'))
+            return [];
+        const found = [];
+        const seen = new Set([rootId]);
+        let level = [rootId];
+        for (let depth = 1; depth <= maxDepth && level.length > 0; depth++) {
+            const parents = new Set(level);
+            const next = [];
+            for (let i = 0; i < level.length; i += SQL_ID_CHUNK_SIZE) {
+                const chunk = level.slice(i, i + SQL_ID_CHUNK_SIZE);
+                const rows = this.query(`SELECT * FROM threads WHERE ${chunk.map(() => 'source LIKE ?').join(' OR ')} ORDER BY created_at ASC`, chunk.map((id) => `%${id}%`));
+                for (const row of rows) {
+                    const parentId = (0, codexRolloutOrigin_1.codexSpawnParentFromSource)(row.source);
+                    if (!parentId || !parents.has(parentId) || seen.has(row.id))
+                        continue;
+                    seen.add(row.id);
+                    found.push({ thread: row, parentId, depth });
+                    next.push(row.id);
+                }
+            }
+            level = next;
+        }
+        return found;
+    }
     /** Get the database file's mtime (ms epoch). Returns 0 if unavailable. */
     getDbMtime() {
         try {

package/dist/providers/codexRollouts.d.ts

@@ -11,7 +11,8 @@ import type { ListSessionFilesOptions, SessionFileInfo } from './types';
 export declare function getSessionsDirs(): string[];
 /**
  * Read the first N complete lines from a file using chunked reads.
- * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
+ * Handles arbitrarily long lines (Codex session_meta can be 10KB+), and
+ * compressed rollouts (`.jsonl.zst`, decompressed when the runtime can).
  */
 export declare function readFirstLines(filePath: string, maxLines: number, maxBytes?: number): string[];
 /** Read session_meta from the beginning of a rollout file. */
@@ -36,12 +37,20 @@ export declare function initializeCounters(stats: ListSessionFilesOptions['stats
 export declare function cwdMatches(sessionCwd: string, workspacePath: string): boolean;
 /** Normalize a path using realpathSync. */
 export declare function normalizePath(input: string): string;
+/** Options for {@link listCodexSessionFilesAsync}. */
+export interface ListCodexSessionFilesOptions extends ListSessionFilesOptions {
+    /**
+     * Also list compressed rollouts (`.jsonl.zst`; default false). Do not
+     * reuse one `cache` across calls that differ in this option.
+     */
+    includeCompressed?: boolean;
+}
 /**
  * List rollout files across the monitored Codex homes, newest first. With
  * `workspacePath`, keeps rollouts whose session_meta cwd equals, contains, or
  * sits inside it.
  */
-export declare function listCodexSessionFilesAsync(workspacePath?: string, options?: ListSessionFilesOptions, cache?: DirectoryListingCache): Promise<SessionFileInfo[]>;
+export declare function listCodexSessionFilesAsync(workspacePath?: string, options?: ListCodexSessionFilesOptions, cache?: DirectoryListingCache): Promise<SessionFileInfo[]>;
 export interface FindCodexRolloutFileOptions {
     /**
      * Codex home whose `sessions/` subtree to search. Defaults to every
@@ -49,6 +58,11 @@ export interface FindCodexRolloutFileOptions {
      * profile homes that recorded sessions.
      */
     codexHome?: string;
+    /**
+     * Also match a compressed rollout (`.jsonl.zst`) when no `.jsonl` for the
+     * id exists (default false).
+     */
+    includeCompressed?: boolean;
 }
 /**
  * Locates the rollout file for a Codex session id by walking

package/dist/providers/codexRollouts.js

@@ -56,15 +56,19 @@ const path = __importStar(require("path"));
 const codexPaths_1 = require("../codexPaths");
 const directoryListingCache_1 = require("./directoryListingCache");
 const rolloutWalker_1 = require("./rolloutWalker");
+const compressedRollouts_1 = require("./compressedRollouts");
 /** Every directory across the monitored homes that may hold rollouts, archived ones included. */
 function getSessionsDirs() {
     return (0, codexPaths_1.getCodexSessionsDirs)();
 }
 /**
  * Read the first N complete lines from a file using chunked reads.
- * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
+ * Handles arbitrarily long lines (Codex session_meta can be 10KB+), and
+ * compressed rollouts (`.jsonl.zst`, decompressed when the runtime can).
  */
 function readFirstLines(filePath, maxLines, maxBytes = 256 * 1024) {
+    if ((0, compressedRollouts_1.isCompressedRolloutPath)(filePath))
+        return (0, compressedRollouts_1.readRolloutFirstLines)(filePath, maxLines, maxBytes);
     const lines = [];
     let fd;
     try {
@@ -128,6 +132,14 @@ async function readFirstLineAsync(rolloutPath) {
     // `instructions` and can far exceed a single chunk.
     const maxBytes = 256 * 1024;
     const chunkSize = 64 * 1024;
+    if ((0, compressedRollouts_1.isCompressedRolloutPath)(rolloutPath)) {
+        // Compressed rollouts are complete: their first line is final.
+        const head = (0, compressedRollouts_1.readRolloutHead)(rolloutPath, maxBytes);
+        if (head.length === 0)
+            return { line: null, complete: false };
+        const firstLine = head.toString('utf8').split('\n', 1)[0]?.trim();
+        return { line: firstLine || null, complete: true };
+    }
     let handle = null;
     try {
         handle = await fs.promises.open(rolloutPath, 'r');
@@ -245,6 +257,7 @@ async function listCodexSessionFilesAsync(workspacePath, options = {}, cache = n
         cache,
         revalidateRecent: options.revalidateRecent,
         stats: options.stats,
+        includeCompressed: options.includeCompressed,
     });
     for (const file of files) {
         if (options.limit !== undefined && results.length >= options.limit)
@@ -281,5 +294,10 @@ function findCodexRolloutFile(sessionId, options = {}) {
         ? (0, codexPaths_1.getCodexSessionsDirs)([options.codexHome])
         : getSessionsDirs();
     // Name-only filter, one walk across the homes, newest modification first.
-    return (0, rolloutWalker_1.walkRolloutFiles)(sessionsDirs, { sessionId: normalizedId })[0]?.path ?? null;
+    const matches = (0, rolloutWalker_1.walkRolloutFiles)(sessionsDirs, {
+        sessionId: normalizedId,
+        includeCompressed: options.includeCompressed,
+    });
+    // A live `.jsonl` wins over a compressed copy found in another home.
+    return (matches.find((file) => !(0, compressedRollouts_1.isCompressedRolloutPath)(file.path)) ?? matches[0])?.path ?? null;
 }

package/dist/providers/codexSubagents.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Codex subagent discovery for `CodexProvider.scanSubagents()`.
+ *
+ * Every spawned thread below a session (children, their children, …), each
+ * with its rollout, the parent's spawn call that started it, its nickname and
+ * agent path, and stats from the child's own records. A forked child's
+ * rollout embeds the parent's session_meta and history before
+ * `session_meta.subagent_history_start_ordinal`; that prefix is the parent's
+ * and is not counted (the parser skips it, and so do the timestamps here).
+ *
+ * The spawn link comes from the parent's rollout: the `item_completed` →
+ * `SubAgentActivity` record with `kind: 'started'` names the spawn call id
+ * and the child thread. When a parent has no such record (older Codex), the
+ * spawn call whose output named the child's agent path
+ * (`{"task_name":"/root/x"}`) is used. Parent scans are cached and read
+ * incrementally as the parent rollout grows.
+ *
+ * Node-only: reads files.
+ *
+ * @module providers/codexSubagents
+ */
+import type { SubagentStats } from '../types/sessionEvent';
+import type { CodexDatabase } from './codexDatabase';
+import { type ReadRolloutOptions } from './compressedRollouts';
+import type { RolloutFileInfo } from './rolloutWalker';
+/** The spawn calls a rollout records, from its own (not inherited) records. */
+export interface CodexSpawnLinks {
+    /** Child thread id → the spawn call that started it (`SubAgentActivity` `started`). */
+    started: Map<string, {
+        callId: string;
+        agentPath?: string;
+    }>;
+    /** Agent path → the spawn calls whose output named it, in file order. */
+    spawnedPaths: Map<string, string[]>;
+}
+/** @internal Test hook. */
+export declare function clearCodexSpawnLinkCache(): void;
+/**
+ * The spawn calls a rollout records (see {@link CodexSpawnLinks}). Cached per
+ * path; a growing `.jsonl` is read only past what was read before, a
+ * compressed one whole. `null` when the rollout cannot be read.
+ */
+export declare function readCodexSpawnLinks(filePath: string, options?: ReadRolloutOptions): CodexSpawnLinks | null;
+/**
+ * Stats of one subagent rollout from its own records: tool calls, tokens,
+ * and first/last timestamps after the embedded parent history (the child's
+ * own `session_meta` counts). Reads `.jsonl.zst` when the runtime can.
+ * `null` when the rollout is missing or cannot be read.
+ */
+export declare function buildCodexSubagentStats(agentId: string, rolloutPath: string, description?: string | null, options?: ReadRolloutOptions): SubagentStats | null;
+export interface DiscoverCodexSubagentsOptions extends ReadRolloutOptions {
+    /** The session's state database, when available. */
+    db: CodexDatabase | null;
+    /** Read compressed rollouts (`.jsonl.zst`) for children whose `.jsonl` is gone. */
+    includeCompressed: boolean;
+    /** The session's own rollout, or a lookup for it (needed for spawn links). */
+    sessionRolloutPath: () => string | null;
+    /** Rollouts to inspect when the database has no answer (newest first). */
+    fallbackFiles: () => RolloutFileInfo[];
+}
+/**
+ * Every subagent below a session with links and own-record stats. Children
+ * whose rollout is gone (or compressed, without `includeCompressed`) are
+ * left out, as before.
+ */
+export declare function discoverCodexSubagents(sessionId: string, options: DiscoverCodexSubagentsOptions): SubagentStats[];