ompchamber 0.3.0

package/src/server/lib/omp/session/usage.ts

@@ -0,0 +1,298 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Real token/cost usage aggregation from oh-my-pi session files
+ * (~/.omp/agent/sessions/<project>/*.jsonl). Faithful to the omp session
+ * format parsed by lib/omp/session (usage blocks with input/output/cache/
+ * reasoning tokens and per-message cost). Powers /api/telemetry/tokens in
+ * real mode so telemetry reflects actual omp activity instead of zeros.
+ */
+
+import fs from 'fs';
+import { join } from 'path';
+import { getSessionsDir } from '@/server/lib/omp/core/paths';
+import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
+import type { BreakdownRow, CadenceType, ChartSeriesPoint, TimeRangeType, TokenUsageMetricSet } from '@/shared/types';
+import type { OmpMessageEntry } from '@/shared/types/omp/session';
+
+export type UsageWindow =
+  | { kind: 'preset'; range: Exclude<TimeRangeType, 'custom'> }
+  | { kind: 'custom'; from: string; to: string }
+  | { kind: 'all' };
+
+const PRESET_DAYS: Record<Exclude<TimeRangeType, 'custom' | 'all'>, number> = { today: 1, '7d': 7, '30d': 30, '90d': 90 };
+
+const TTL_MS = 60_000;
+const cache = new Map<string, { at: number; data: UsageAggregate }>();
+
+export interface UsageAggregate {
+  scannedTranscripts: number;
+  usageRecords: number;
+  costTotal: number;
+  costInput: number;
+  costOutput: number;
+  costCacheRead: number;
+  costCacheWrite: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  reasoningTokens: number;
+  activeDays: Set<string>;
+  byModel: Map<string, { tokens: number; cost: number }>;
+  byDay: Map<string, { tokens: number; cost: number }>;
+  byProject: Map<string, { tokens: number; cost: number }>;
+}
+
+function emptyAggregate(): UsageAggregate {
+  return {
+    scannedTranscripts: 0,
+    usageRecords: 0,
+    costTotal: 0,
+    costInput: 0,
+    costOutput: 0,
+    costCacheRead: 0,
+    costCacheWrite: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    reasoningTokens: 0,
+    activeDays: new Set(),
+    byModel: new Map(),
+    byDay: new Map(),
+    byProject: new Map(),
+  };
+}
+
+function bump(map: Map<string, { tokens: number; cost: number }>, key: string, tokens: number, cost: number): void {
+  const current = map.get(key) ?? { tokens: 0, cost: 0 };
+  current.tokens += tokens;
+  current.cost += cost;
+  map.set(key, current);
+}
+
+function inRange(timestampIso: string | undefined, window: UsageWindow, now: number): boolean {
+  if (window.kind === 'all') return true;
+  if (!timestampIso) return true; // keep entries without timestamps (conservative)
+  const ts = Date.parse(timestampIso);
+  if (Number.isNaN(ts)) return true;
+  if (window.kind === 'custom') {
+    const from = Date.parse(`${window.from}T00:00:00`);
+    const to = Date.parse(`${window.to}T23:59:59.999`);
+    if (Number.isNaN(from) || Number.isNaN(to) || from > to) return true;
+    return ts >= from && ts <= to;
+  }
+  if (window.range === 'today') {
+    const d = new Date(ts);
+    const n = new Date(now);
+    return d.getFullYear() === n.getFullYear() && d.getMonth() === n.getMonth() && d.getDate() === n.getDate();
+  }
+  if (window.range === 'all') return true;
+  return now - ts <= PRESET_DAYS[window.range] * 24 * 60 * 60 * 1000;
+}
+
+function cacheKey(window: UsageWindow): string {
+  if (window.kind === 'all') return 'all';
+  if (window.kind === 'custom') return `custom:${window.from}:${window.to}`;
+  return window.range;
+}
+
+/** Aggregate all omp session files within a time window. Cached for 60s. */
+export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregate> {
+  const key = cacheKey(window);
+  const cached = cache.get(key);
+  if (cached && Date.now() - cached.at < TTL_MS) return cached.data;
+
+  const sessionsRoot = getSessionsDir();
+  const aggregate = emptyAggregate();
+  const now = Date.now();
+  let projectDirs: string[] = [];
+  try {
+    projectDirs = (await fs.promises.readdir(sessionsRoot, { withFileTypes: true }))
+      .filter((d) => d.isDirectory() || d.isFile())
+      .map((d) => d.name);
+  } catch {
+    cache.set(key, { at: Date.now(), data: aggregate });
+    return aggregate;
+  }
+
+  for (const project of projectDirs) {
+    const projectPath = join(sessionsRoot, project);
+    let files: string[] = [];
+    try {
+      if ((await Bun.file(projectPath).stat()).isFile()) {
+        files = project.endsWith('.jsonl') ? [projectPath] : [];
+      } else {
+        files = (await fs.promises.readdir(projectPath))
+          .filter((f) => f.endsWith('.jsonl'))
+          .map((f) => join(projectPath, f));
+      }
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      aggregate.scannedTranscripts++;
+      try {
+        const ufile = Bun.file(file);
+        if ((await ufile.stat()).size > 64 * 1024 * 1024) continue;
+        const entries = parseJsonlLenient<OmpMessageEntry>(await ufile.text());
+        for (const entry of entries) {
+          if (entry.type !== 'message' || !entry.message?.usage) continue;
+          const ts = entry.timestamp;
+          if (!inRange(ts, window, now)) continue;
+          const usage = entry.message.usage;
+          const cost = usage.cost?.total ?? 0;
+          const total = usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+          aggregate.usageRecords++;
+          aggregate.costTotal += cost;
+          aggregate.costInput += usage.cost?.input ?? 0;
+          aggregate.costOutput += usage.cost?.output ?? 0;
+          aggregate.costCacheRead += usage.cost?.cacheRead ?? 0;
+          aggregate.costCacheWrite += usage.cost?.cacheWrite ?? 0;
+          aggregate.inputTokens += usage.input ?? 0;
+          aggregate.outputTokens += usage.output ?? 0;
+          aggregate.cacheReadTokens += usage.cacheRead ?? 0;
+          aggregate.cacheWriteTokens += usage.cacheWrite ?? 0;
+          aggregate.reasoningTokens += usage.reasoningTokens ?? 0;
+          if (ts) {
+            const day = ts.slice(0, 10);
+            aggregate.activeDays.add(day);
+            bump(aggregate.byDay, day, total, cost);
+          }
+          const model = entry.message.model || 'unknown';
+          bump(aggregate.byModel, model, total, cost);
+          bump(aggregate.byProject, project, total, cost);
+        }
+      } catch {
+        // Unreadable transcript — skip rather than failing the whole report.
+      }
+    }
+  }
+
+  const data = aggregate;
+  if (cache.size > 20) cache.clear();
+  cache.set(key, { at: Date.now(), data });
+  return data;
+}
+
+const fmtInt = (value: number): string => value.toLocaleString('en-US');
+const fmtUsd = (value: number): string => `$${value.toFixed(2)}`;
+
+const MONTH_LABELS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] as const;
+
+function dayLabel(dayKey: string): string {
+  const date = new Date(`${dayKey}T00:00:00`);
+  return Number.isNaN(date.getTime()) ? dayKey : `${MONTH_LABELS[date.getMonth()]} ${date.getDate()}`;
+}
+
+function bucketKey(dayKey: string, cadence: CadenceType): string {
+  if (cadence === 'monthly') return dayKey.slice(0, 7);
+  if (cadence === 'weekly') {
+    const date = new Date(`${dayKey}T00:00:00`);
+    if (Number.isNaN(date.getTime())) return dayKey;
+    const monday = new Date(date);
+    const shift = (date.getDay() + 6) % 7;
+    monday.setDate(date.getDate() - shift);
+    return monday.toISOString().slice(0, 10);
+  }
+  return dayKey;
+}
+
+function labelForBucket(key: string, cadence: CadenceType): string {
+  if (cadence === 'monthly') {
+    const [year, month] = key.split('-');
+    const monthIndex = Number(month) - 1;
+    const label = MONTH_LABELS[monthIndex] ?? key;
+    return year && Number(year) !== new Date().getFullYear() ? `${label} ${year}` : label;
+  }
+  return dayLabel(key);
+}
+
+/** Shape the per-day aggregate into an ordered chart series for the cadence:
+ * weekly buckets align to Monday, monthly to YYYY-MM, and the series is
+ * truncated to the last 60 buckets so the SVG path stays readable. */
+export function buildChartSeries(a: UsageAggregate, cadence: CadenceType): ChartSeriesPoint[] {
+  const buckets = new Map<string, { cost: number; tokens: number }>();
+  for (const [dayKey, v] of a.byDay) {
+    const key = bucketKey(dayKey, cadence);
+    const current = buckets.get(key) ?? { cost: 0, tokens: 0 };
+    current.cost += v.cost;
+    current.tokens += v.tokens;
+    buckets.set(key, current);
+  }
+  return [...buckets.entries()]
+    .sort(([aKey], [bKey]) => (aKey < bKey ? -1 : aKey > bKey ? 1 : 0))
+    .slice(-60)
+    .map(([key, v]) => ({ label: labelForBucket(key, cadence), cost: v.cost, tokens: v.tokens }));
+}
+
+export function toMetricSet(a: UsageAggregate, cadence: CadenceType = 'daily'): TokenUsageMetricSet {
+  const observedInput = a.inputTokens + a.cacheReadTokens;
+  const cachedPercent = observedInput > 0 ? ((a.cacheReadTokens / observedInput) * 100).toFixed(1) : '0.0';
+  const unit = cadence === 'weekly' ? 'week' : cadence === 'monthly' ? 'month' : 'day';
+  return {
+    rawCost: fmtUsd(a.costTotal),
+    processedTokens: fmtInt(a.inputTokens + a.outputTokens + a.cacheReadTokens + a.cacheWriteTokens),
+    activeRate: `${a.activeDays.size} active ${unit}${a.activeDays.size === 1 ? '' : 's'}`,
+    cachedInput: fmtInt(a.cacheReadTokens),
+    cachedPercent: `${cachedPercent}% of observed input`,
+    uncachedInput: fmtInt(a.inputTokens),
+    outputTokens: fmtInt(a.outputTokens),
+    reasoning: `includes ${fmtInt(a.reasoningTokens)} reasoning`,
+    cacheSavings: fmtUsd(a.costCacheRead),
+    scannedTranscripts: a.scannedTranscripts,
+    usageRecords: a.usageRecords,
+  };
+}
+
+const BREAKDOWN_DOT_COLORS = [
+  'bg-[var(--theme-ink)]',
+  'bg-[var(--theme-ink)]/70',
+  'bg-[var(--theme-ink)]/50',
+  'bg-[var(--theme-ink)]/35',
+  'bg-[var(--theme-ink)]/20',
+] as const;
+
+/** Build breakdown rows (model/day/project) from the aggregate; the `day` tab
+ * is bucketed by the cadence (day/week/month) so it stays consistent with the chart. */
+export function toBreakdownRows(
+  a: UsageAggregate,
+  tab: 'model' | 'day' | 'project',
+  cadence: CadenceType = 'daily',
+): BreakdownRow[] {
+  if (tab === 'day' && cadence !== 'daily') {
+    const buckets = new Map<string, { tokens: number; cost: number }>();
+    for (const [dayKey, v] of a.byDay) {
+      const key = bucketKey(dayKey, cadence);
+      const current = buckets.get(key) ?? { tokens: 0, cost: 0 };
+      current.tokens += v.tokens;
+      current.cost += v.cost;
+      buckets.set(key, current);
+    }
+    const merged: UsageAggregate = { ...a, byDay: buckets };
+    return toBreakdownRows(merged, 'day', 'daily');
+  }
+  const source = tab === 'model' ? a.byModel : tab === 'day' ? a.byDay : a.byProject;
+  return [...source.entries()]
+    .map(([name, v]) => ({
+      name: tab === 'day' ? labelForBucket(name, cadence) : name,
+      tokens: v.tokens,
+      cost: v.cost,
+      sharePercent: a.costTotal > 0 ? Math.round((v.cost / a.costTotal) * 100) : 0,
+    }))
+    .sort((x, y) => y.cost - x.cost)
+    .slice(0, 12)
+    .map((row, index) => ({
+      name: row.name,
+      tokens: fmtInt(row.tokens),
+      cost: fmtUsd(row.cost),
+      share: `${row.sharePercent}%`,
+      sharePercent: row.sharePercent,
+      dotColorClass: BREAKDOWN_DOT_COLORS[index % BREAKDOWN_DOT_COLORS.length],
+    }));
+}

package/src/server/lib/omp/subagent/history/fold.ts

@@ -0,0 +1,196 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Per-entry roster fold for on-disk subagent history.
+ *
+ * Each parent `task` toolResult carries `progress` (running snapshots) and
+ * `results` (settled telemetry) for the agents it spawned. The factory owns
+ * the mutable fold state (`byId`, `batchSeqById`, `detachedIds`, the
+ * launch-order counters) so ingestion is a per-entry step; the caller supplies
+ * the authoritative call order and walks the session entries in order.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import { SUBAGENT_ID_RE } from '@/server/lib/omp/subagent/history/paths';
+import { progressStatusToHistory, progressUpsertBlocked, resultStatus } from '@/shared/lib/omp/subagent/history/status';
+import { parseSubagentProgress } from '@/shared/lib/omp/subagent/parse';
+import { asAgentSource, asNumber, asString, taskResultStructuredOutput, taskResultUsageCost } from '@/shared/lib/omp/subagent/result-details';
+import type { OmpMessageEntry } from '@/shared/lib/omp/session/messages-parse';
+import type { SubagentHistoryEntry, SubagentHistoryResult } from '@/shared/types/omp/subagent';
+
+/**
+ * Mutable roster fold seeded from parent `task` toolResults. `callOrder` is the
+ * assistant-message ordinal of each `task` call (see `buildCallOrder` in
+ * `@/lib/omp/subagent/history`).
+ */
+export function createFolder(callOrder: Map<string, number>) {
+  const byId = new Map<string, SubagentHistoryEntry>();
+  // `index` is the position inside ONE `task` call's batch and restarts at 0 for
+  // every call, so sorting by it alone interleaves the agents of separate calls.
+  // Pair it with the ordinal of the call that spawned each agent.
+  const batchSeqById = new Map<string, number>();
+  let batchSeq = -1;
+  let unannouncedCalls = 0;
+  const upsert = (entry: SubagentHistoryEntry, options?: { ignoreTerminal?: boolean }): void => {
+    if (!SUBAGENT_ID_RE.test(entry.id)) return;
+    const existing = byId.get(entry.id);
+    if (!existing) {
+      batchSeqById.set(entry.id, batchSeq);
+      byId.set(entry.id, entry);
+      return;
+    }
+    // A stale/duplicate progress snapshot must not regress a settled agent:
+    // once a result is recorded (or status went terminal via results), skip
+    // the whole overwrite. `ignoreTerminal` opts the results loop out — its
+    // own field-by-field guards already make it authoritative.
+    if (!options?.ignoreTerminal && progressUpsertBlocked(existing)) return;
+    const preservedBatchSeq = batchSeqById.get(entry.id) ?? batchSeq;
+    batchSeqById.set(entry.id, preservedBatchSeq);
+    byId.set(entry.id, {
+      ...existing,
+      ...entry,
+      parentToolCallId: entry.parentToolCallId ?? existing.parentToolCallId,
+      batchSeq: preservedBatchSeq,
+      result: entry.result ?? existing.result,
+    });
+  };
+
+  // Detached async spawns — jobIds collected in the same pass below.
+  const detachedIds = new Set<string>();
+
+  const ingest = (entry: OmpMessageEntry): void => {
+    const message = entry.message;
+    if (entry.type !== 'message' || !message || message.role !== 'toolResult') return;
+    if (message.toolName !== 'task') return;
+    const toolCallId = asString(message.toolCallId);
+    // A result whose call block never made it into the file (truncated or
+    // imported session) keeps arrival order, placed after every announced call.
+    const announced = toolCallId !== undefined ? callOrder.get(toolCallId) : undefined;
+    batchSeq = announced ?? callOrder.size + unannouncedCalls++;
+    const details: Record<string, unknown> = isRecord(message.details) ? message.details : {};
+    const progressArr = Array.isArray(details.progress) ? details.progress : [];
+    const resultsArr = Array.isArray(details.results) ? details.results : [];
+    const asyncInfo = isRecord(details.async) ? details.async : undefined;
+    const asyncJobId = asyncInfo ? asString(asyncInfo.jobId) : undefined;
+    if (asyncJobId) detachedIds.add(asyncJobId);
+
+    for (const raw of progressArr) {
+      const progress = parseSubagentProgress(raw);
+      if (!progress?.id) continue;
+      upsert({
+        id: progress.id,
+        agent: progress.agent ?? 'subagent',
+        agentSource: progress.agentSource,
+        status: progressStatusToHistory(progress.status),
+        task: progress.task,
+        assignment: progress.assignment,
+        description: progress.description,
+        index: progress.index ?? 0,
+        ...(toolCallId !== undefined ? { parentToolCallId: toolCallId } : {}),
+        lastIntent: progress.lastIntent,
+        toolCount: progress.toolCount,
+        requests: progress.requests,
+        tokens: progress.tokens,
+        contextTokens: progress.contextTokens,
+        contextWindow: progress.contextWindow,
+        cost: progress.cost,
+        durationMs: progress.durationMs,
+        modelOverride: progress.modelOverride,
+        modelRole: progress.modelRole,
+        resolvedModel: progress.resolvedModel,
+        resolvedModelIsFallback: progress.resolvedModelIsFallback,
+        retryFailure: progress.retryFailure,
+        transcriptAvailable: false,
+      });
+    }
+
+    for (const raw of resultsArr) {
+      if (!isRecord(raw)) continue;
+      const id = asString(raw.id);
+      if (!id) continue;
+      const prior = byId.get(id);
+      const result: SubagentHistoryResult = {};
+      const exitCode = asNumber(raw.exitCode);
+      if (exitCode !== undefined) result.exitCode = exitCode;
+      // NOTE: `output`/`stderr` are deliberately NOT copied — the roster route
+      // must stay telemetry-only (task outputs can be ~500KB per agent).
+      if (raw.truncated === true) result.truncated = true;
+      const cost = asNumber(raw.cost) ?? taskResultUsageCost(raw.usage);
+      if (cost !== undefined) result.cost = cost;
+      const structured = taskResultStructuredOutput(raw.structuredOutput);
+      if (structured !== undefined) result.structuredOutput = structured;
+      const error = asString(raw.error);
+      if (error !== undefined) result.error = error;
+      if (raw.aborted === true) result.aborted = true;
+      const abortReason = asString(raw.abortReason);
+      if (abortReason !== undefined) result.abortReason = abortReason;
+      const outputPath = asString(raw.outputPath);
+      if (outputPath !== undefined) result.outputPath = outputPath;
+      const patchPath = asString(raw.patchPath);
+      if (patchPath !== undefined) result.patchPath = patchPath;
+      const branchName = asString(raw.branchName);
+      if (branchName !== undefined) result.branchName = branchName;
+      let retryFailure = prior?.retryFailure;
+      const retryRaw = raw.retryFailure;
+      if (isRecord(retryRaw)) {
+        const attempt = asNumber(retryRaw.attempt);
+        const errorMessage = asString(retryRaw.errorMessage);
+        if (attempt !== undefined && errorMessage !== undefined) retryFailure = { attempt, errorMessage };
+      }
+      const modelOverride = typeof raw.modelOverride === 'string'
+        ? raw.modelOverride
+        : Array.isArray(raw.modelOverride) && raw.modelOverride.every((model): model is string => typeof model === 'string')
+          ? raw.modelOverride
+          : prior?.modelOverride;
+      upsert({
+        id,
+        agent: asString(raw.agent) ?? prior?.agent ?? 'subagent',
+        agentSource: asAgentSource(raw.agentSource) ?? prior?.agentSource,
+        status: resultStatus(raw),
+        task: asString(raw.task) ?? prior?.task,
+        assignment: asString(raw.assignment) ?? prior?.assignment,
+        description: asString(raw.description) ?? prior?.description,
+        index: asNumber(raw.index) ?? prior?.index ?? 0,
+        ...(toolCallId !== undefined ? { parentToolCallId: toolCallId } : {}),
+        lastIntent: asString(raw.lastIntent) ?? prior?.lastIntent,
+        toolCount: asNumber(raw.toolCount) ?? prior?.toolCount,
+        requests: asNumber(raw.requests) ?? prior?.requests,
+        tokens: asNumber(raw.tokens) ?? prior?.tokens,
+        contextTokens: asNumber(raw.contextTokens) ?? prior?.contextTokens,
+        contextWindow: asNumber(raw.contextWindow) ?? prior?.contextWindow,
+        cost: asNumber(raw.cost) ?? taskResultUsageCost(raw.usage) ?? prior?.cost,
+        durationMs: asNumber(raw.durationMs) ?? prior?.durationMs,
+        modelOverride,
+        modelRole: asString(raw.modelRole) ?? prior?.modelRole,
+        resolvedModel: asString(raw.resolvedModel) ?? prior?.resolvedModel,
+        resolvedModelIsFallback: typeof raw.resolvedModelIsFallback === 'boolean'
+          ? raw.resolvedModelIsFallback
+          : prior?.resolvedModelIsFallback,
+        retryFailure,
+        transcriptAvailable: false,
+        result: Object.keys(result).length > 0 ? result : undefined,
+      }, { ignoreTerminal: true });
+    }
+
+    // Detached async spawns can persist with an empty results[] while still
+    // running — async.jobId still names the agent.
+    if (asyncInfo) {
+      const jobId = asString(asyncInfo.jobId);
+      if (jobId && !byId.has(jobId)) {
+        upsert({
+          id: jobId,
+          agent: 'task',
+          status: asyncInfo.state === 'completed' ? 'completed' : asyncInfo.state === 'failed' ? 'failed' : 'started',
+          index: byId.size,
+          ...(toolCallId !== undefined ? { parentToolCallId: toolCallId } : {}),
+          transcriptAvailable: false,
+        }, { ignoreTerminal: true });
+      }
+    }
+  };
+
+  return { byId, batchSeqById, detachedIds, ingest };
+}

package/src/server/lib/omp/subagent/history/index.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * On-disk subagent history recovery for oh-my-pi sessions.
+ *
+ * omp writes each subagent's transcript to the PARENT session's sibling
+ * artifacts directory: `<session-dir>/<subagent-id>.jsonl`. The parent's task
+ * toolResult `details` persist `progress` (running snapshots) and `results`
+ * (settled telemetry), so the roster survives a reload without the live RPC
+ * registry — which only knows currently-running subagents.
+ *
+ * Ported from omp-web/lib/subagent-history.ts; path helpers live in
+ * `@/lib/omp/subagent/history/paths`, status projection in `history/status`,
+ * the per-entry toolResult fold in `history/fold`, async settlement in
+ * `history/settlement`, and byte-window transcript paging in
+ * `@/lib/omp/subagent/history/transcript`.
+ */
+
+import { join } from 'path';
+import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
+import { isRecord } from '@/shared/lib/util/guards';
+import { createFolder } from '@/server/lib/omp/subagent/history/fold';
+import { SUBAGENT_ID_RE, siblingDirForSession } from '@/server/lib/omp/subagent/history/paths';
+import { foldSettlements } from '@/shared/lib/omp/subagent/history/settlement';
+import { asString } from '@/shared/lib/omp/subagent/result-details';
+import type { OmpMessageEntry } from '@/shared/lib/omp/session/messages-parse';
+import type { SubagentHistoryEntry } from '@/shared/types/omp/subagent';
+
+/** Byte cap on the parent session file parsed for history (chat reload cap). */
+const MAX_HISTORY_SESSION_BYTES = 512 * 1024 * 1024;
+
+/** Read + lenient-parse every JSONL entry of a session file (bounded). */
+async function loadSessionEntries(sessionFilePath: string): Promise<OmpMessageEntry[]> {
+  const file = Bun.file(sessionFilePath);
+  try {
+    if ((await file.stat()).size > MAX_HISTORY_SESSION_BYTES) return [];
+  } catch {
+    return [];
+  }
+  try {
+    return parseJsonlLenient<OmpMessageEntry>(await file.text());
+  } catch {
+    return [];
+  }
+}
+
+/** Build the authoritative launch order of the session's `task` toolCall
+ *  blocks, keyed by call id and valued by the ordinal of the assistant
+ *  message that issued them. */
+function buildCallOrder(entries: OmpMessageEntry[]): Map<string, number> {
+  const callOrder = new Map<string, number>();
+  // Authoritative launch order: the assistant message that spawns a batch lists
+  // its `task` toolCall blocks in the order the model issued them. Ordering by
+  // toolResult arrival instead would misplace parallel calls, whose results are
+  // appended as each one finishes rather than as each one started.
+  for (const entry of entries) {
+    const message = entry.message;
+    if (entry.type !== 'message' || !message || message.role !== 'assistant') continue;
+    const content = message.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!isRecord(block) || block.type !== 'toolCall' || block.name !== 'task') continue;
+      const callId = asString(block.id);
+      if (callId !== undefined && !callOrder.has(callId)) callOrder.set(callId, callOrder.size);
+    }
+  }
+  return callOrder;
+}
+
+/**
+ * Recover the subagent roster from a parent session file. Walks task
+ * toolResults, merging `progress` (live-snapshot fields) with `results`
+ * (settled per-subagent telemetry), then resolves sibling transcript files.
+ */
+export async function extractSubagentHistory(sessionFilePath: string): Promise<SubagentHistoryEntry[]> {
+  const entries = await loadSessionEntries(sessionFilePath);
+  if (entries.length === 0) return [];
+
+  const callOrder = buildCallOrder(entries);
+  const folder = createFolder(callOrder);
+  for (const entry of entries) folder.ingest(entry);
+  foldSettlements(entries, folder.byId);
+
+  // Resolve sibling transcript files and detached markers.
+  const { byId, batchSeqById, detachedIds } = folder;
+  const dir = siblingDirForSession(sessionFilePath);
+  const roster = [...byId.values()];
+  for (const entry of roster) {
+    // The client cannot derive this: neither a live snapshot nor a partial
+    // history fetch reveals which call came first.
+    entry.batchSeq = batchSeqById.get(entry.id) ?? 0;
+    if (detachedIds.has(entry.id)) entry.detached = true;
+    if (!SUBAGENT_ID_RE.test(entry.id)) continue;
+    // Guard against crafted ids probing outside the sibling dir (e.g. "../");
+    // the path is derived from untrusted session content.
+    const candidate = join(dir, `${entry.id}.jsonl`);
+    if (await Bun.file(candidate).exists()) {
+      entry.sessionFile = candidate;
+      entry.transcriptAvailable = true;
+    }
+  }
+  return roster.sort((a, b) =>
+    (batchSeqById.get(a.id) ?? 0) - (batchSeqById.get(b.id) ?? 0)
+    || a.index - b.index
+    || a.id.localeCompare(b.id),
+  );
+}

package/src/server/lib/omp/subagent/history/paths.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Path derivation + id grammar for on-disk subagent artifacts.
+ *
+ * A subagent's transcript lives in the parent session's sibling artifacts
+ * directory (`<session-dir>/<subagent-id>.jsonl`), so the id grammar bounds
+ * session-content-derived ids before they are joined into a path.
+ */
+
+import { basename, dirname, join } from 'path';
+
+/** Subagent ids are AdjectiveNoun names, dotted for nested spawns. The grammar
+ *  bounds session-content-derived ids before they are joined into a path. */
+export const SUBAGENT_ID_RE = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/;
+export const SUBAGENT_ID_MAX_LENGTH = 100;
+
+/** Sibling artifacts directory for a parent session file. */
+export function siblingDirForSession(sessionFilePath: string): string {
+  return join(dirname(sessionFilePath), basename(sessionFilePath, '.jsonl'));
+}
+
+/** Subagent transcript path for a roster id within a parent session. */
+export function subagentTranscriptPath(sessionFilePath: string, subagentId: string): string {
+  return join(siblingDirForSession(sessionFilePath), `${subagentId}.jsonl`);
+}