sidekick-shared 0.28.3 → 0.29.1

package/dist/parsers/subagentTraceParser.js

@@ -6,10 +6,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
  */
@@ -55,6 +58,8 @@ const noiseClassifier_1 = require("../formatters/noiseClassifier");
 const claudeUsageDedupe_1 = require("../usage/claudeUsageDedupe");
 const subagentUsage_1 = require("../usage/subagentUsage");
 const subagentScanner_1 = require("./subagentScanner");
+const subagentSpawn_1 = require("../subagentSpawn");
+const ownKey_1 = require("../ownKey");
 // ── Constants ──
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
 // ── Public API ──
@@ -86,10 +91,8 @@ function scanSubagentTraces(sessionDir, sessionId) {
             if (trace)
                 traces.push(trace);
         }
-        // Link parent-child relationships
-        linkTraces(traces);
-        // Return only top-level traces (those without parents)
-        return traces.filter((t) => !t.parentToolUseId);
+        // Link parent-child relationships; returns the traces with no parent agent.
+        return linkTraces(traces);
     }
     catch {
         return [];
@@ -169,8 +172,8 @@ function parseAgentTrace(filePath, agentId) {
                                 input: block.input || {},
                                 timestamp,
                             });
-                            // Extract agent info from Task tool
-                            if (block.name === 'Task' && block.input) {
+                            // Extract agent info from an Agent/Task spawn
+                            if ((0, subagentSpawn_1.isSubagentSpawnTool)(block.name) && block.input) {
                                 if (block.input.subagent_type && !agentType) {
                                     agentType = String(block.input.subagent_type);
                                 }
@@ -207,6 +210,14 @@ function parseAgentTrace(filePath, agentId) {
             agentId,
             agentType,
             description,
+            filePath,
+            ...(meta.toolUseId
+                ? { spawnToolUseId: meta.toolUseId, parentToolUseId: meta.toolUseId }
+                : {}),
+            ...(meta.parentAgentId ? { parentAgentId: meta.parentAgentId } : {}),
+            ...(meta.requestShape ? { background: meta.requestShape === 'background' } : {}),
+            ...(meta.finished !== undefined ? { finished: meta.finished } : {}),
+            ...(meta.stoppedByUser !== undefined ? { stoppedByUser: meta.stoppedByUser } : {}),
             events,
             children: [],
             stats: {
@@ -231,23 +242,61 @@ function parseAgentTrace(filePath, agentId) {
     }
 }
 // ── Parent-Child Linking ──
+/**
+ * Nests child traces under their parents and returns the traces with no
+ * parent agent. Exact metadata links come first; the heuristics only place
+ * traces Claude Code recorded no spawn metadata for.
+ */
 function linkTraces(traces) {
     const traceById = new Map();
     for (const trace of traces) {
         traceById.set(trace.agentId, trace);
     }
-    // Phase 1: Result-based linking
-    // Look for tool_result events that contain agentId references
+    const parentOf = new Map();
+    const attach = (parent, child) => {
+        if (parent === child || parentOf.has(child))
+            return false;
+        // Never nest an agent under its own descendant (malformed metadata).
+        for (let up = parent; up; up = parentOf.get(up)) {
+            if (up === child)
+                return false;
+        }
+        parentOf.set(child, parent);
+        parent.children.push(child);
+        return true;
+    };
+    // Phase 1: the meta file names the parent agent
+    for (const child of traces) {
+        const parent = child.parentAgentId ? traceById.get(child.parentAgentId) : undefined;
+        if (parent)
+            attach(parent, child);
+    }
+    // Phase 2: the child's spawning call is in another trace
+    const spawnOwner = new Map();
     for (const trace of traces) {
-        for (const traceEvent of trace.events) {
-            const evt = traceEvent.event;
-            if (evt.type === 'tool_use' && evt.tool?.name === 'Task') {
-                // The tool_use_id from this call should appear as a result in the parent
-                // but we can link via timestamp proximity to child traces
-            }
+        for (const id of spawnToolUseIdsOf(trace)) {
+            if (!spawnOwner.has(id))
+                spawnOwner.set(id, trace);
         }
     }
-    // Phase 2: Team summary linking
+    for (const child of traces) {
+        if (parentOf.has(child) || !child.spawnToolUseId)
+            continue;
+        const parent = spawnOwner.get(child.spawnToolUseId);
+        if (parent && attach(parent, child))
+            child.parentAgentId ??= parent.agentId;
+    }
+    // Heuristic links set parentAgentId and, as before, parentToolUseId to the
+    // parent's agent id.
+    const unresolved = (trace) => !parentOf.has(trace) && !trace.spawnToolUseId && !trace.parentAgentId;
+    const linkHeuristically = (parent, child) => {
+        if (!attach(parent, child))
+            return false;
+        child.parentAgentId = parent.agentId;
+        child.parentToolUseId = parent.agentId;
+        return true;
+    };
+    // Phase 3: Team summary linking
     for (const trace of traces) {
         for (const traceEvent of trace.events) {
             const content = traceEvent.event.message?.content;
@@ -255,45 +304,56 @@ function linkTraces(traces) {
                 // Parse teammate agent IDs from XML blocks
                 const matches = content.matchAll(/agent[_-]id['":\s]+([a-f0-9]+)/gi);
                 for (const match of matches) {
-                    const childId = match[1];
-                    const child = traceById.get(childId);
-                    if (child && child !== trace && !child.parentToolUseId) {
-                        child.parentToolUseId = trace.agentId;
-                        trace.children.push(child);
-                    }
+                    const child = traceById.get(match[1]);
+                    if (child && unresolved(child))
+                        linkHeuristically(trace, child);
                 }
             }
         }
     }
-    // Phase 3: Positional fallback — timestamp proximity
+    // Phase 4: Positional fallback — timestamp proximity
     // Traces without parents that fall within another trace's time window
-    const parentless = traces.filter((t) => !t.parentToolUseId);
-    for (const child of parentless) {
+    for (const child of traces.filter(unresolved)) {
         if (!child.stats.startTime)
             continue;
         const childStart = child.stats.startTime.getTime();
-        // Find a trace that was active (Task tool call) right before this child started
+        // Find a top-level trace that spawned an agent right before this child started
         for (const potential of traces) {
-            if (potential === child)
+            if (potential === child || parentOf.has(potential))
                 continue;
-            if (potential.parentToolUseId)
-                continue; // Already linked
             for (const traceEvent of potential.events) {
                 const evt = traceEvent.event;
-                if (evt.type === 'assistant' && evt.tool?.name === 'Task') {
+                if (evt.type === 'assistant' && (0, subagentSpawn_1.isSubagentSpawnTool)(evt.tool?.name)) {
                     const taskTime = new Date(evt.timestamp).getTime();
                     // Within 2 seconds before child start
                     if (taskTime <= childStart && childStart - taskTime < 2000) {
-                        child.parentToolUseId = potential.agentId;
-                        potential.children.push(child);
+                        linkHeuristically(potential, child);
                         break;
                     }
                 }
             }
-            if (child.parentToolUseId)
+            if (parentOf.has(child))
                 break;
         }
     }
+    return traces.filter((trace) => !parentOf.has(trace));
+}
+/** Ids of the `Agent` / `Task` calls a trace made. */
+function spawnToolUseIdsOf(trace) {
+    const ids = [];
+    for (const traceEvent of trace.events) {
+        const content = traceEvent.event.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type === 'tool_use' &&
+                typeof block.id === 'string' &&
+                (0, subagentSpawn_1.isSubagentSpawnTool)(block.name)) {
+                ids.push(block.id);
+            }
+        }
+    }
+    return ids;
 }
 // ── Helpers ──
 function rawToSessionEvent(raw) {
@@ -308,7 +368,7 @@ function rawToSessionEvent(raw) {
         tool_result: 'tool_result',
         summary: 'summary',
     };
-    const mappedType = typeMap[type];
+    const mappedType = (0, ownKey_1.ownValue)(typeMap, type);
     if (!mappedType)
         return null;
     const message = raw.message;

package/dist/pricing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `sidekick-shared/pricing` — model pricing, model-id identity, usage
+ * normalization and cost, cost provenance, cost/token formatting, and text
+ * token estimates, as one small pure entry (no filesystem, network, or Zod).
+ *
+ * For hosts that price usage or format costs without session reading: it
+ * loads a handful of modules instead of the full browser surface. LiteLLM
+ * catalog hydration stays Node-only in `sidekick-shared/node`
+ * (`hydratePricingCatalog`); once hydrated, lookups here see the catalog.
+ * Everything here is also exported from the package root and
+ * `sidekick-shared/browser`.
+ *
+ * @module pricing
+ */
+export { MODEL_PROVIDER_IDS, canonicalModelId, isMovingModelAlias, parseModelId, compareModelIds, sortModelIds, shortModelName, getModelDisplayInfo, getModelInfo, getModelPricing, resolveModelPricing, registerModelPricing, clearRegisteredModelPricing, getPricingCatalogInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, costSourceFromPricingProvenance, mergeCostComponents, formatCost, } from './modelInfo';
+export type { ModelPricing, ModelPricingSource, ModelPricingMatch, ModelPricingProvenance, ResolvedModelPricing, ResolveModelPricingOptions, RegisterModelPricingOptions, PricingCatalogSource, PricingCatalogInfo, CostComponent, CostTokenUsage, ModelProvider, ParsedModelId, ModelInfo, CostSource, CostProvenanceInput, CostWithProvenance, ModelDisplayInfo, FormatCostOptions, } from './modelInfo';
+export { normalizeProviderUsage, extractNormalizedUsage, calculateNormalizedUsageCost, } from './usageNormalization';
+export type { UsageProvider, UsageSemantics, UsageNormalizationProvenance, AnthropicUsageInput, OpenAIUsageInput, SidekickUsageInput, ProviderUsageInput, NormalizedUsage, PricingProvenance, NormalizedUsageCostInput, NormalizedUsageCost, } from './usageNormalization';
+export { formatTokenCount, formatDurationMs } from './formatting';
+export type { FormatTokenCountOptions, FormatDurationMsOptions } from './formatting';
+export { ASCII_CHARS_PER_TOKEN, estimateTextTokens, estimateSerializedTokens, } from './tokenEstimation';
+export type { TokenEstimationMethod, TokenEstimationConfidence, ExactTokenCounterContext, ExactTokenCounter, TokenEstimationOptions, TokenEstimate, } from './tokenEstimation';

package/dist/pricing.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * `sidekick-shared/pricing` — model pricing, model-id identity, usage
+ * normalization and cost, cost provenance, cost/token formatting, and text
+ * token estimates, as one small pure entry (no filesystem, network, or Zod).
+ *
+ * For hosts that price usage or format costs without session reading: it
+ * loads a handful of modules instead of the full browser surface. LiteLLM
+ * catalog hydration stays Node-only in `sidekick-shared/node`
+ * (`hydratePricingCatalog`); once hydrated, lookups here see the catalog.
+ * Everything here is also exported from the package root and
+ * `sidekick-shared/browser`.
+ *
+ * @module pricing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateSerializedTokens = exports.estimateTextTokens = exports.ASCII_CHARS_PER_TOKEN = exports.formatDurationMs = exports.formatTokenCount = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.formatCost = exports.mergeCostComponents = exports.costSourceFromPricingProvenance = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getPricingCatalogInfo = exports.clearRegisteredModelPricing = exports.registerModelPricing = exports.resolveModelPricing = exports.getModelPricing = exports.getModelInfo = exports.getModelDisplayInfo = exports.shortModelName = exports.sortModelIds = exports.compareModelIds = exports.parseModelId = exports.isMovingModelAlias = exports.canonicalModelId = exports.MODEL_PROVIDER_IDS = void 0;
+var modelInfo_1 = require("./modelInfo");
+Object.defineProperty(exports, "MODEL_PROVIDER_IDS", { enumerable: true, get: function () { return modelInfo_1.MODEL_PROVIDER_IDS; } });
+Object.defineProperty(exports, "canonicalModelId", { enumerable: true, get: function () { return modelInfo_1.canonicalModelId; } });
+Object.defineProperty(exports, "isMovingModelAlias", { enumerable: true, get: function () { return modelInfo_1.isMovingModelAlias; } });
+Object.defineProperty(exports, "parseModelId", { enumerable: true, get: function () { return modelInfo_1.parseModelId; } });
+Object.defineProperty(exports, "compareModelIds", { enumerable: true, get: function () { return modelInfo_1.compareModelIds; } });
+Object.defineProperty(exports, "sortModelIds", { enumerable: true, get: function () { return modelInfo_1.sortModelIds; } });
+Object.defineProperty(exports, "shortModelName", { enumerable: true, get: function () { return modelInfo_1.shortModelName; } });
+Object.defineProperty(exports, "getModelDisplayInfo", { enumerable: true, get: function () { return modelInfo_1.getModelDisplayInfo; } });
+Object.defineProperty(exports, "getModelInfo", { enumerable: true, get: function () { return modelInfo_1.getModelInfo; } });
+Object.defineProperty(exports, "getModelPricing", { enumerable: true, get: function () { return modelInfo_1.getModelPricing; } });
+Object.defineProperty(exports, "resolveModelPricing", { enumerable: true, get: function () { return modelInfo_1.resolveModelPricing; } });
+Object.defineProperty(exports, "registerModelPricing", { enumerable: true, get: function () { return modelInfo_1.registerModelPricing; } });
+Object.defineProperty(exports, "clearRegisteredModelPricing", { enumerable: true, get: function () { return modelInfo_1.clearRegisteredModelPricing; } });
+Object.defineProperty(exports, "getPricingCatalogInfo", { enumerable: true, get: function () { return modelInfo_1.getPricingCatalogInfo; } });
+Object.defineProperty(exports, "calculateCost", { enumerable: true, get: function () { return modelInfo_1.calculateCost; } });
+Object.defineProperty(exports, "calculateCostWithPricing", { enumerable: true, get: function () { return modelInfo_1.calculateCostWithPricing; } });
+Object.defineProperty(exports, "calculateCostWithProvenance", { enumerable: true, get: function () { return modelInfo_1.calculateCostWithProvenance; } });
+Object.defineProperty(exports, "mergeCostSources", { enumerable: true, get: function () { return modelInfo_1.mergeCostSources; } });
+Object.defineProperty(exports, "costSourceFromPricingProvenance", { enumerable: true, get: function () { return modelInfo_1.costSourceFromPricingProvenance; } });
+Object.defineProperty(exports, "mergeCostComponents", { enumerable: true, get: function () { return modelInfo_1.mergeCostComponents; } });
+Object.defineProperty(exports, "formatCost", { enumerable: true, get: function () { return modelInfo_1.formatCost; } });
+var usageNormalization_1 = require("./usageNormalization");
+Object.defineProperty(exports, "normalizeProviderUsage", { enumerable: true, get: function () { return usageNormalization_1.normalizeProviderUsage; } });
+Object.defineProperty(exports, "extractNormalizedUsage", { enumerable: true, get: function () { return usageNormalization_1.extractNormalizedUsage; } });
+Object.defineProperty(exports, "calculateNormalizedUsageCost", { enumerable: true, get: function () { return usageNormalization_1.calculateNormalizedUsageCost; } });
+var formatting_1 = require("./formatting");
+Object.defineProperty(exports, "formatTokenCount", { enumerable: true, get: function () { return formatting_1.formatTokenCount; } });
+Object.defineProperty(exports, "formatDurationMs", { enumerable: true, get: function () { return formatting_1.formatDurationMs; } });
+var tokenEstimation_1 = require("./tokenEstimation");
+Object.defineProperty(exports, "ASCII_CHARS_PER_TOKEN", { enumerable: true, get: function () { return tokenEstimation_1.ASCII_CHARS_PER_TOKEN; } });
+Object.defineProperty(exports, "estimateTextTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateTextTokens; } });
+Object.defineProperty(exports, "estimateSerializedTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateSerializedTokens; } });

package/dist/pricingCatalog.d.ts

@@ -51,6 +51,12 @@ export interface HydrateResult {
     contextWindowEntries: number;
     /** ISO timestamp of the fetch that produced the cache. */
     fetchedAt: string;
+    /**
+     * `getPricingCatalogInfo().digest` after hydration: a stable fingerprint of
+     * every active pricing table, so callers can record which prices produced
+     * an estimate. See `getPricingCatalogInfo()` for the source and staleness.
+     */
+    digest: string;
 }
 export declare const LITELLM_CATALOG_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
 /**
@@ -61,6 +67,10 @@ export declare const LITELLM_CATALOG_URL = "https://raw.githubusercontent.com/Be
  *   2. Otherwise attempt a network fetch; on success, persist + apply.
  *   3. On any failure, load a stale cache if present; else leave overrides empty.
  *
+ * `getPricingCatalogInfo().source` afterwards reads `litellm` for a fresh fetch
+ * or a cache within `ttlMs`, and `stale-cache` for a cache older than `ttlMs`
+ * — whether the refresh failed or `offline` skipped it.
+ *
  * Always resolves — never throws. Offline-safe.
  */
 export declare function hydratePricingCatalog(options?: HydrateOptions): Promise<HydrateResult>;

package/dist/pricingCatalog.js

@@ -59,6 +59,7 @@ const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
 const modelContext_1 = require("./modelContext");
 const modelInfo_1 = require("./modelInfo");
+const ownKey_1 = require("./ownKey");
 const paths_1 = require("./paths");
 const atomic_1 = require("./writers/atomic");
 // ── Constants ──
@@ -75,6 +76,10 @@ const DEFAULT_TIMEOUT_MS = 3_000;
  *   2. Otherwise attempt a network fetch; on success, persist + apply.
  *   3. On any failure, load a stale cache if present; else leave overrides empty.
  *
+ * `getPricingCatalogInfo().source` afterwards reads `litellm` for a fresh fetch
+ * or a cache within `ttlMs`, and `stale-cache` for a cache older than `ttlMs`
+ * — whether the refresh failed or `offline` skipped it.
+ *
  * Always resolves — never throws. Offline-safe.
  */
 async function hydratePricingCatalog(options = {}) {
@@ -83,8 +88,9 @@ async function hydratePricingCatalog(options = {}) {
     const now = Date.now();
     // 1. Fresh cache? (Offline callers take any cache, however old.)
     const cached = await readCache(cachePath);
-    if (cached && (offline || now - Date.parse(cached.fetchedAt) < ttlMs)) {
-        return applyCacheFile(cached, 'cache');
+    const cacheFresh = cached !== null && now - Date.parse(cached.fetchedAt) < ttlMs;
+    if (cached && (offline || cacheFresh)) {
+        return applyCacheFile(cached, 'cache', cacheFresh ? 'litellm' : 'stale-cache');
     }
     // 2. Try network.
     if (fetchImpl && !offline) {
@@ -97,12 +103,12 @@ async function hydratePricingCatalog(options = {}) {
                 contextWindows: normalizeLiteLlmContextWindows(fetched),
             };
             await writeCache(cachePath, payload, logger);
-            return applyCacheFile(payload, 'network');
+            return applyCacheFile(payload, 'network', 'litellm');
         }
     }
     // 3. Fall back to stale cache if present.
     if (cached) {
-        return applyCacheFile(cached, 'cache');
+        return applyCacheFile(cached, 'cache', 'stale-cache');
     }
     // 4. Nothing we can do — stay on static tables.
     return {
@@ -110,6 +116,7 @@ async function hydratePricingCatalog(options = {}) {
         entries: 0,
         contextWindowEntries: 0,
         fetchedAt: new Date(now).toISOString(),
+        digest: (0, modelInfo_1.getPricingCatalogInfo)().digest,
     };
 }
 /**
@@ -117,9 +124,9 @@ async function hydratePricingCatalog(options = {}) {
  * `contextWindows` is absent on caches written before context hydration; those
  * contribute no overrides rather than clearing whatever is already loaded.
  */
-function applyCacheFile(cache, source) {
+function applyCacheFile(cache, source, basis) {
     const contextWindows = cache.contextWindows ?? {};
-    (0, modelInfo_1._setPricingOverrides)(cache.overrides);
+    (0, modelInfo_1._setPricingOverrides)(cache.overrides, { source: basis, fetchedAt: cache.fetchedAt });
     if (Object.keys(contextWindows).length > 0) {
         (0, modelContext_1._setCatalogContextWindows)(contextWindows);
     }
@@ -128,6 +135,7 @@ function applyCacheFile(cache, source) {
         entries: Object.keys(cache.overrides).length,
         contextWindowEntries: Object.keys(contextWindows).length,
         fetchedAt: cache.fetchedAt,
+        digest: (0, modelInfo_1.getPricingCatalogInfo)().digest,
     };
 }
 /**
@@ -149,7 +157,7 @@ function normalizeLiteLlmCatalog(raw) {
             continue;
         // Catalog keys use both `provider/model` and bare `model` forms. Record both
         // the raw key and the bare-model form so lookups work regardless of caller.
-        out[key] = pricing;
+        (0, ownKey_1.setOwnValue)(out, key, pricing);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key && !out[bare]) {
             out[bare] = pricing;
@@ -186,7 +194,7 @@ function normalizeLiteLlmContextWindows(raw) {
         const window = entry.max_input_tokens;
         if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
             continue;
-        out[key] = window;
+        (0, ownKey_1.setOwnValue)(out, key, window);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key) {
             const seen = aliasWindows.get(bare) ?? new Set();

package/dist/promptHistory.d.ts

@@ -14,6 +14,10 @@
  * record over `maxRecordBytes` is skipped without being buffered and reported
  * in `exclusions`, the only way a record is permanently left out.
  *
+ * `includeText: false` returns the same entries, ordinals, timestamps,
+ * metadata, exclusions, and cursor without prompt text, for consumers that
+ * only count or attribute prompts. Cursors are interchangeable between modes.
+ *
  * A prompt can be written before its answer. The cursor then keeps the byte
  * offset of that prompt's line and its answer-tracking state (never text), and
  * the prompt is returned again under the same identity once its first
@@ -34,8 +38,14 @@ export interface PromptHistoryBounds {
     /** Bytes read across all files in this call. Default 256 MiB. */
     maxTotalBytes?: number;
     /**
-     * Largest single log record that is parsed. Default 16 MiB. A longer record
-     * is skipped without being buffered and reported in `exclusions`.
+     * Largest single log record that is parsed. Default 16 MiB
+     * (`PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES`). A longer record is skipped
+     * without being buffered and reported in `exclusions`.
+     *
+     * Ordinals depend on this bound: a prompt inside a skipped record is never
+     * seen, so later prompts in that file do not count it. Ordinals are only
+     * stable across runs and across consumers (for example usage events'
+     * `promptOrdinal`) when every reader uses the default.
      */
     maxRecordBytes?: number;
     /** Entries returned by one call. Default 10 000. */
@@ -139,8 +149,10 @@ export interface PromptHistoryEntry {
     ordinal: number;
     /** ISO timestamp from the log line; never synthesized. */
     timestamp: string;
-    /** Full prompt text, untruncated. */
+    /** Full prompt text, untruncated; `''` when the call passed `includeText: false`. */
     text: string;
+    /** Set when `text` was left out by `includeText: false`; the prompt was not empty. */
+    textOmitted?: true;
     /** Realpath of the working directory; always inside an allowed root. */
     cwd: string;
     gitBranch?: string;
@@ -170,7 +182,9 @@ export interface PromptHistorySessionRef {
 /**
  * A log record permanently left out. Records over `maxRecordBytes` and lines
  * that are not valid JSON are never parsed, so any prompt inside is lost, and
- * the ordinals of later prompts in that file do not count it.
+ * the ordinals of later prompts in that file do not count it. Because of
+ * that, ordinals are only stable across runs and consumers that all use the
+ * default `maxRecordBytes` (`PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES`).
  */
 export interface PromptHistoryExclusion {
     provider: PromptHistoryProvider;
@@ -213,6 +227,14 @@ export interface CollectPromptHistoryOptions {
     cursor?: PromptHistoryCursor;
     bounds?: PromptHistoryBounds;
     signal?: AbortSignal;
+    /**
+     * Return prompt text. Default true. With `false`, entries keep their
+     * ordinal, timestamp, cwd, branch, and answer metadata but carry `text: ''`
+     * and `textOmitted: true`, and no prompt text is kept past classifying its
+     * line. Ordinals, timestamps, exclusions, and the cursor are identical in
+     * both modes, so a cursor written in one mode resumes in the other.
+     */
+    includeText?: boolean;
 }
 export interface PromptHistoryResult {
     /** Ordered by provider, session, then ordinal. */
@@ -235,6 +257,13 @@ export interface PromptHistoryResult {
     /** Realpaths of the roots scanned, after worktree expansion. */
     roots?: string[];
 }
+/**
+ * The default `maxRecordBytes` (16 MiB). Prompt ordinals are only comparable
+ * between readers that skip the same records, so every reader that publishes
+ * or joins on ordinals (prompt history, session prompt history, usage events'
+ * `promptOrdinal`) uses this bound.
+ */
+export declare const PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES: number;
 /** @internal */
 export declare const DEFAULT_BOUNDS: Required<PromptHistoryBounds>;
 /** Test hooks; not part of the public entry points. */
@@ -257,6 +286,17 @@ export type RecordObserver = (record: Record<string, unknown>, info: {
     ordinal: number;
     lineOffset: number;
 }) => void;
+/**
+ * Sees every human prompt as it is given its ordinal, before the timestamp and
+ * scope checks, so prompts that are not returned are seen too. `timestamp` is
+ * undefined when the line has no usable one.
+ * @internal
+ */
+export type PromptObserver = (prompt: {
+    ordinal: number;
+    timestamp: string | undefined;
+    lineOffset: number;
+}) => void;
 /** @internal */
 export interface ScanContext {
     roots: string[];
@@ -269,6 +309,9 @@ export interface ScanContext {
     entriesSoFar: () => number;
     exclude: (exclusion: PromptHistoryExclusion) => void;
     observe?: RecordObserver;
+    onPrompt?: PromptObserver;
+    /** Keep prompt text on entries. Default true. */
+    includeText?: boolean;
 }
 /** @internal */
 export interface FileBudget {
@@ -293,6 +336,24 @@ export interface FileOutcome {
 }
 /** Collect human-typed prompts from Claude Code and Codex logs under the given roots. */
 export declare function collectPromptHistory(options: CollectPromptHistoryOptions): Promise<PromptHistoryResult>;
+/** One human prompt of a session file: its ordinal and parsed timestamp. @internal */
+export interface PromptOrdinalMark {
+    ordinal: number;
+    /** Prompt line timestamp, ms since epoch. */
+    timestampMs: number;
+}
+/**
+ * Every human prompt of one session file with its ordinal and timestamp, read
+ * whole in one pass with the default record bound, so the ordinals are the
+ * ones `collectPromptHistory()` returns with default bounds. No scope check
+ * and no text: prompts are counted wherever their cwd points. Prompts whose
+ * line has no usable timestamp still take an ordinal but are left out. A
+ * non-interactive Codex session (subagent, fork, unknown source) has none.
+ * In file order. Rejects when the file cannot be opened or changes while its
+ * head is read.
+ * @internal
+ */
+export declare function readPromptOrdinalMarks(provider: PromptHistoryProvider, sessionId: string, filePath: string): Promise<PromptOrdinalMark[]>;
 /** @internal */
 export declare function emptyStats(): PromptHistoryStats;
 /**