@omercnet/paseo-omp 0.2.1 → 0.3.0-next.92.1

package/server/provider/profile-providers.ts

@@ -0,0 +1,249 @@
+import { type Dir, opendirSync } from "node:fs";
+import { opendir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { isOmpProfileName } from "../../shared/omp-store";
+import { ompAgentDir, ompCacheDir, ompDataDir, ompSessionDir, ompStateDir } from "../paths";
+import { OmpRpcRuntime, type OmpRuntime, type OmpStartOptions } from "./omp-rpc";
+import { parseOmpProviderOptions } from "./provider-options";
+import { createOmpProvider, type OmpProviderOptions } from "./registration";
+import { OmpPublicError } from "./security";
+
+const MAX_PROFILES = 128;
+const MAX_DIRECTORY_ENTRIES = 4_096;
+const STORE_ENV_NAMES: Readonly<Record<string, true>> = {
+  OMP_PROFILE: true,
+  PI_PROFILE: true,
+  PASEO_OMP_AGENT_DIR: true,
+  OMP_AGENT_DIR: true,
+  PI_CODING_AGENT_DIR: true,
+  OMP_SESSION_DIR: true,
+  PI_CODING_AGENT_SESSION_DIR: true,
+  PI_CONFIG_FILES: true,
+};
+const PROFILE_OVERRIDE_ENV_NAMES: Readonly<Record<string, true>> = {
+  ...STORE_ENV_NAMES,
+  PI_CONFIG_DIR: true,
+  HOME: true,
+  USERPROFILE: true,
+  XDG_DATA_HOME: true,
+  XDG_STATE_HOME: true,
+  XDG_CACHE_HOME: true,
+};
+
+function validateProfile(profile: string): void {
+  if (!isOmpProfileName(profile)) throw new OmpPublicError("Invalid named OMP profile");
+}
+
+function profileDirectory(environment: NodeJS.ProcessEnv): string {
+  return join(
+    environment.HOME ?? environment.USERPROFILE ?? homedir(),
+    environment.PI_CONFIG_DIR || ".omp",
+    "profiles",
+  );
+}
+
+/** Paseo 0.8 contribution registration is synchronous; inspect directory names only. */
+export function discoverOmpProfilesSync(environment: NodeJS.ProcessEnv = process.env): string[] {
+  let directory: Dir;
+  try {
+    directory = opendirSync(profileDirectory(environment));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw new OmpPublicError("OMP profile directory could not be read");
+  }
+  const profiles: string[] = [];
+  let count = 0;
+  try {
+    for (let entry = directory.readSync(); entry; entry = directory.readSync()) {
+      if (++count > MAX_DIRECTORY_ENTRIES)
+        throw new OmpPublicError("OMP profile directory is too large");
+      if (entry.isDirectory() && isOmpProfileName(entry.name)) profiles.push(entry.name);
+    }
+  } finally {
+    directory.closeSync();
+  }
+  return profiles.sort().slice(0, MAX_PROFILES);
+}
+
+/** Enumerate names only; never open profile configuration, databases, or credential files. */
+export async function discoverOmpProfiles(
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<string[]> {
+  let directory: Dir;
+  try {
+    directory = await opendir(profileDirectory(environment));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw new OmpPublicError("OMP profile directory could not be read");
+  }
+  const profiles: string[] = [];
+  let count = 0;
+  for await (const entry of directory) {
+    if (++count > MAX_DIRECTORY_ENTRIES) {
+      throw new OmpPublicError("OMP profile directory is too large");
+    }
+    if (entry.isDirectory() && isOmpProfileName(entry.name)) profiles.push(entry.name);
+  }
+  return profiles.sort().slice(0, MAX_PROFILES);
+}
+
+export function profileProviderId(profile: string): string {
+  validateProfile(profile);
+  return `omp-plugin-${profile}`;
+}
+
+function fixedEnvironment(profile: string, source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const environment = { ...source };
+  for (const name of Object.keys(environment)) {
+    if (STORE_ENV_NAMES[name.toUpperCase()]) delete environment[name];
+  }
+  environment.OMP_PROFILE = profile;
+  environment.PI_CODING_AGENT_DIR = join(profileDirectory(source), profile, "agent");
+  return environment;
+}
+
+function profileCommand(
+  command: readonly string[],
+  profile: string,
+  sessionDir: string,
+): readonly string[] {
+  // Environment-control flags can erase or replace the fixed profile/config/XDG
+  // roots before OMP sees --profile. Allow plain assignment wrappers, not env's
+  // -i, -u, -S, -C (or their long forms), including wrappers nested after `--`.
+  for (let index = 0; index < command.length; index += 1) {
+    const executable = basename(command[index]).toLowerCase();
+    if (executable !== "env" && executable !== "env.exe") continue;
+    for (const argument of command.slice(index + 1)) {
+      if (argument === "--") break;
+      if (argument.startsWith("-"))
+        throw new OmpPublicError("OMP profile command cannot alter its environment with env flags");
+      if (!/^[A-Za-z_][A-Za-z0-9_]*=/u.test(argument)) break;
+    }
+  }
+  let hasProfile = false;
+  for (let index = 1; index < command.length; index += 1) {
+    const argument = command[index];
+    const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=/u.exec(argument);
+    if (assignment && PROFILE_OVERRIDE_ENV_NAMES[assignment[1].toUpperCase()]) {
+      throw new OmpPublicError("OMP profile command cannot override its selected store");
+    }
+    if (argument === "--profile" || argument.startsWith("--profile=")) {
+      const selected = argument === "--profile" ? command[++index] : argument.slice(10);
+      if (selected !== profile) {
+        throw new OmpPublicError("OMP command profile conflicts with the selected provider");
+      }
+      hasProfile = true;
+    } else if (argument === "--session-dir" || argument.startsWith("--session-dir=")) {
+      const selected = argument === "--session-dir" ? command[++index] : argument.slice(14);
+      if (!selected || resolve(selected) !== sessionDir) {
+        throw new OmpPublicError(
+          "OMP command session directory conflicts with the selected profile",
+        );
+      }
+    }
+  }
+  return hasProfile ? command : [...command, "--profile", profile];
+}
+
+/** Each provider owns one profile before the host requests a catalog or creates an agent. */
+export function createProfileOmpProvider(profile: string, options: OmpProviderOptions = {}) {
+  const id = profileProviderId(profile);
+  const environment = fixedEnvironment(profile, options.environment ?? process.env);
+  const sessionDir = resolve(ompSessionDir(environment));
+  const runtime = options.runtime ?? new OmpRpcRuntime({ environment });
+  const readPersistedSessionTranscript = runtime.readPersistedSessionTranscript?.bind(runtime);
+  const assertSessionDir = (requested?: string) => {
+    if (requested !== undefined && resolve(requested) !== sessionDir) {
+      throw new OmpPublicError("OMP session directory conflicts with the selected profile");
+    }
+  };
+  const assertEnvironment = (sessionEnv?: Readonly<Record<string, string>>) => {
+    for (const name of Object.keys(sessionEnv ?? {})) {
+      if (PROFILE_OVERRIDE_ENV_NAMES[name.toUpperCase()]) {
+        throw new OmpPublicError("OMP session environment cannot override its selected profile");
+      }
+    }
+  };
+  const scopedRuntime: OmpRuntime = {
+    get supportsPersistence() {
+      return runtime.supportsPersistence;
+    },
+    async startSession(start: OmpStartOptions) {
+      assertSessionDir(start.sessionDir);
+      assertEnvironment(start.env);
+      return runtime.startSession({
+        ...start,
+        command: profileCommand(
+          start.command ?? [environment.OMP_COMMAND ?? "omp"],
+          profile,
+          sessionDir,
+        ),
+        environment,
+        sessionDir,
+      });
+    },
+    async listSessions(listOptions) {
+      assertSessionDir(listOptions.sessionDir);
+      return runtime.listSessions({ ...listOptions, sessionDir });
+    },
+    ...(readPersistedSessionTranscript
+      ? {
+          readPersistedSessionTranscript(input) {
+            return readPersistedSessionTranscript(input);
+          },
+        }
+      : {}),
+    readPersistedSubagentTranscript(input) {
+      return runtime.readPersistedSubagentTranscript(input);
+    },
+  };
+  const provider = createOmpProvider({
+    ...options,
+    runtime: scopedRuntime,
+    environment,
+    catalogIdentity: {
+      profile,
+      agentRoot: ompAgentDir(environment),
+      dataRoot: ompDataDir(environment),
+      cacheRoot: ompCacheDir(environment),
+      stateRoot: ompStateDir(environment),
+      sessionRoot: sessionDir,
+    },
+  });
+  const validateCatalog = (
+    input: Parameters<NonNullable<typeof provider.getCatalogCacheKey>>[0],
+  ) => {
+    const parsed = parseOmpProviderOptions(input.providerOptions);
+    assertEnvironment(parsed.env);
+    assertSessionDir(parsed.params?.sessionDir);
+    return profileCommand(
+      parsed.command ?? [environment.OMP_COMMAND ?? "omp"],
+      profile,
+      sessionDir,
+    );
+  };
+  return {
+    ...provider,
+    async getCatalogCacheKey(
+      input: Parameters<NonNullable<typeof provider.getCatalogCacheKey>>[0],
+    ) {
+      validateCatalog(input);
+      return provider.getCatalogCacheKey?.(input);
+    },
+    async checkAvailability(
+      input: Parameters<NonNullable<typeof provider.checkAvailability>>[0],
+      context?: Parameters<NonNullable<typeof provider.checkAvailability>>[1],
+    ) {
+      const command = validateCatalog(input);
+      if (!provider.checkAvailability)
+        throw new OmpPublicError("OMP availability probe is unavailable");
+      return provider.checkAvailability(
+        { ...input, providerOptions: { ...input.providerOptions, command } },
+        context,
+      );
+    },
+    id,
+    label: `OMP · ${profile}`,
+  };
+}

package/server/provider/registration.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import type { ProviderRegistration } from "@getpaseo/plugin/server/provider";
 import { z } from "zod";
+import type { OmpBrowserAuthorizationRegistry } from "../mcp-browser";
 import { probeOmpAvailability } from "../provider-diagnostics";
 import { createOmpConnection, OmpNativeSessionReservations } from "./connection";
 import type { OmpMcpConnector } from "./host-tools";
@@ -48,6 +49,7 @@ const CAPABILITIES = [
   "session.subsession",
   "session.revert.conversation",
   "permission",
+  "timeline.plugin",
 ] as const;
 const ConnectRequestSchema = z.object({
   versions: z.array(z.number().int().positive().max(16)).min(1).max(8),
@@ -59,8 +61,11 @@ export interface OmpProviderOptions {
   timelineScheduler?: OmpTimelineScheduler;
   replayTimeoutMs?: number;
   environment?: NodeJS.ProcessEnv;
+  /** Fixed, non-secret profile/store identity for providers whose configuration is server-owned. */
+  catalogIdentity?: Readonly<Record<string, string>>;
   mcpInitializationTimeoutMs?: number;
   mcpConnector?: OmpMcpConnector;
+  browserAuthorizationRegistry?: OmpBrowserAuthorizationRegistry;
   availabilityProbe?: (
     options: ProviderCatalogOptionsCompat,
     timeoutMs: number | undefined,
@@ -90,9 +95,14 @@ export function createOmpProvider(options: OmpProviderOptions = {}): ProviderReg
     providerOptionsSchema: OmpProviderOptionsSchema,
     async getCatalogCacheKey(catalogOptions) {
       const providerOptions = parseOmpProviderOptions(catalogOptions.providerOptions);
+      // Profile providers cannot safely hash explicit environment values because they may be
+      // credentials. Disable sharing for that case; otherwise retain every normalized option
+      // that can change discovery alongside the fixed, non-secret store identity.
+      if (options.catalogIdentity && Object.keys(providerOptions.env ?? {}).length > 0) return;
       const identity = {
         scope: catalogOptions.scope,
         ...(catalogOptions.scope === "workspace" ? { cwd: catalogOptions.cwd } : {}),
+        ...(options.catalogIdentity ? { store: options.catalogIdentity } : {}),
         providerOptions,
         settings: catalogOptions.settings ?? {},
         defaultCommand: (options.environment ?? process.env).OMP_COMMAND ?? "omp",
@@ -145,6 +155,7 @@ export function createOmpProvider(options: OmpProviderOptions = {}): ProviderReg
         options.mcpConnector,
         options.mcpInitializationTimeoutMs,
         options.replayTimeoutMs,
+        options.browserAuthorizationRegistry,
       );
     },
   };

package/server/provider/session-descriptors.ts

@@ -1,5 +1,6 @@
+import { createHash } from "node:crypto";
 import { constants, type Dir } from "node:fs";
-import { type FileHandle, open, opendir, realpath } from "node:fs/promises";
+import { type FileHandle, lstat, open, opendir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { ompSessionDir } from "../paths";
@@ -16,6 +17,12 @@ const SCAN_YIELD_INTERVAL = 128;
 const MAX_LIST_RESULTS = 500;
 const MAX_CHILD_TRANSCRIPT_BYTES = 16 * 1024 * 1024;
 const MAX_CHILD_TRANSCRIPT_MESSAGES = 100_000;
+const MAX_SESSION_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+const MAX_SESSION_TRANSCRIPT_ENTRIES = 200_000;
+const MAX_SESSION_TRANSCRIPT_BLOB_BYTES = 16 * 1024 * 1024;
+const MAX_SESSION_IMAGE_BLOB_BYTES = 6 * 1024 * 1024;
+const FILE_READ_CHUNK_BYTES = 64 * 1024;
+const BLOB_REFERENCE = /^blob:sha256:([a-f0-9]{64})$/u;
 const CHILD_TRANSCRIPT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/u;
 const NATIVE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/u;
 
@@ -35,6 +42,13 @@ export interface OmpPersistedSubagentTranscript {
   byteLength: number;
   messages: unknown[];
 }
+
+export interface OmpPersistedSessionTranscript {
+  sessionFile: string;
+  nativeSessionId: string;
+  byteLength: number;
+  messages: unknown[];
+}
 export interface OmpSessionListOptions {
   cwd?: string;
   query?: string;
@@ -142,6 +156,128 @@ async function yieldToEventLoop(): Promise<void> {
   setImmediate(result.resolve);
   await result.promise;
 }
+async function readStableFile(
+  handle: FileHandle,
+  byteLength: number,
+  signal: AbortSignal | undefined,
+  changedMessage: string,
+): Promise<Buffer> {
+  const bytes = Buffer.allocUnsafe(byteLength);
+  let offset = 0;
+  while (offset < byteLength) {
+    signal?.throwIfAborted();
+    const { bytesRead } = await handle.read(
+      bytes,
+      offset,
+      Math.min(FILE_READ_CHUNK_BYTES, byteLength - offset),
+      offset,
+    );
+    if (bytesRead === 0) throw new Error(changedMessage);
+    offset += bytesRead;
+  }
+  signal?.throwIfAborted();
+  const extra = Buffer.allocUnsafe(1);
+  if ((await handle.read(extra, 0, 1, byteLength)).bytesRead !== 0) throw new Error(changedMessage);
+  return bytes;
+}
+
+async function hydrateBlobImageData(
+  data: string,
+  blobDirectory: string,
+  budget: { bytes: number },
+  signal?: AbortSignal,
+): Promise<string> {
+  const match = BLOB_REFERENCE.exec(data);
+  if (!match) return data;
+  const hash = match[1];
+  const blobFile = join(blobDirectory, hash);
+  let handle: FileHandle;
+  try {
+    handle = await open(
+      blobFile,
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
+    );
+  } catch {
+    throw new Error("OMP transcript image blob could not be opened");
+  }
+  try {
+    const [stat, pathStat] = await Promise.all([handle.stat(), lstat(blobFile)]);
+    if (
+      !stat.isFile() ||
+      !pathStat.isFile() ||
+      pathStat.isSymbolicLink() ||
+      stat.dev !== pathStat.dev ||
+      stat.ino !== pathStat.ino ||
+      stat.size > MAX_SESSION_IMAGE_BLOB_BYTES ||
+      budget.bytes + stat.size > MAX_SESSION_TRANSCRIPT_BLOB_BYTES
+    ) {
+      throw new Error("OMP transcript image blob failed ownership or size validation");
+    }
+    const bytes = await readStableFile(
+      handle,
+      stat.size,
+      signal,
+      "OMP transcript image blob changed while reading",
+    );
+    if (createHash("sha256").update(bytes).digest("hex") !== hash) {
+      throw new Error("OMP transcript image blob failed integrity validation");
+    }
+    budget.bytes += bytes.byteLength;
+    return bytes.toString("base64");
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+}
+
+async function hydrateImageParts(
+  value: unknown,
+  blobDirectory: string,
+  budget: { bytes: number },
+  signal?: AbortSignal,
+): Promise<unknown> {
+  if (!Array.isArray(value)) return value;
+  let hydrated: unknown[] | undefined;
+  for (let index = 0; index < value.length; index += 1) {
+    const part = value[index];
+    if (
+      !part ||
+      typeof part !== "object" ||
+      Array.isArray(part) ||
+      !("type" in part) ||
+      part.type !== "image" ||
+      !("data" in part) ||
+      typeof part.data !== "string" ||
+      !BLOB_REFERENCE.test(part.data)
+    ) {
+      continue;
+    }
+    const data = await hydrateBlobImageData(part.data, blobDirectory, budget, signal);
+    hydrated ??= [...value];
+    hydrated[index] = { ...part, data };
+  }
+  return hydrated ?? value;
+}
+
+async function hydratePersistedMessageImages(
+  message: unknown,
+  blobDirectory: string | undefined,
+  budget: { bytes: number },
+  signal?: AbortSignal,
+): Promise<unknown> {
+  if (!blobDirectory || !message || typeof message !== "object" || Array.isArray(message)) {
+    return message;
+  }
+  const record = message as Record<string, unknown>;
+  let content = await hydrateImageParts(record.content, blobDirectory, budget, signal);
+  if (content && typeof content === "object" && !Array.isArray(content)) {
+    const contentRecord = content as Record<string, unknown>;
+    const nested = await hydrateImageParts(contentRecord.content, blobDirectory, budget, signal);
+    if (nested !== contentRecord.content) content = { ...contentRecord, content: nested };
+  }
+  const images = await hydrateImageParts(record.images, blobDirectory, budget, signal);
+  if (content === record.content && images === record.images) return message;
+  return { ...record, content, images };
+}
 
 async function parseDescriptor(
   file: string,
@@ -336,6 +472,175 @@ export async function listOmpSessionDescriptors(
   return matches;
 }
 
+interface PersistedTranscriptNode {
+  parentId: string | null;
+  message?: unknown;
+}
+
+function persistedTranscriptMessage(record: Record<string, unknown>, entryId: string): unknown {
+  if (record.type === "message") {
+    if (!record.message || typeof record.message !== "object" || Array.isArray(record.message))
+      return;
+    return { ...(record.message as Record<string, unknown>), entryId };
+  }
+  if (record.type !== "custom_message") return;
+  return {
+    role: "custom",
+    entryId,
+    customType: record.customType,
+    content: record.content,
+    display: record.display,
+    details: record.details,
+  };
+}
+
+/**
+ * Reads the active root-to-leaf display history from an already authorized native transcript.
+ * OMP's get_messages endpoint exposes model-safe context and deliberately removes failed turns,
+ * so persisted replay must use the journal to preserve user-visible assistant and tool history.
+ */
+export async function readOmpPersistedSessionTranscript(
+  sessionFile: string,
+  sessionId: string,
+  cwd: string,
+  signal?: AbortSignal,
+  blobDirectory?: string,
+): Promise<OmpPersistedSessionTranscript> {
+  signal?.throwIfAborted();
+  const expectedSessionId = validateNativeSessionId(sessionId);
+  if (
+    !isAbsolute(sessionFile) ||
+    !sessionFile.endsWith(".jsonl") ||
+    sessionFile.includes("\0") ||
+    validatedCwd(cwd) !== cwd
+  ) {
+    throw new Error("Invalid OMP session transcript descriptor");
+  }
+  const expectedFile = resolve(sessionFile);
+  let handle: FileHandle;
+  try {
+    handle = await open(
+      expectedFile,
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
+    );
+  } catch {
+    throw new Error("OMP session transcript could not be opened");
+  }
+  try {
+    const [stat, pathStat, canonicalFile] = await Promise.all([
+      handle.stat(),
+      lstat(expectedFile),
+      realpath(expectedFile),
+    ]);
+    if (
+      !stat.isFile() ||
+      !pathStat.isFile() ||
+      pathStat.isSymbolicLink() ||
+      stat.dev !== pathStat.dev ||
+      stat.ino !== pathStat.ino ||
+      stat.size > MAX_SESSION_TRANSCRIPT_BYTES
+    ) {
+      throw new Error("OMP session transcript failed ownership validation");
+    }
+    const bytes = await readStableFile(
+      handle,
+      stat.size,
+      signal,
+      "OMP session transcript changed while reading",
+    );
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const nodes = new Map<string, PersistedTranscriptNode>();
+    let nativeSessionId: string | undefined;
+    let leafId: string | undefined;
+    let recordsRead = 0;
+    for (const line of text.split("\n")) {
+      signal?.throwIfAborted();
+      recordsRead += 1;
+      if (recordsRead % 1_024 === 0) await yieldToEventLoop();
+      if (!line.trim()) continue;
+      const value: unknown = JSON.parse(line);
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      const record = value as Record<string, unknown>;
+      if (record.type === "session") {
+        const candidateId = validateNativeSessionId(record.id);
+        if (candidateId !== expectedSessionId || validatedCwd(record.cwd) !== cwd) {
+          throw new Error("OMP session transcript identity does not match its descriptor");
+        }
+        nativeSessionId ??= candidateId;
+        if (nativeSessionId !== candidateId) {
+          throw new Error("OMP session transcript identity changed");
+        }
+        continue;
+      }
+      if (typeof record.id !== "string" || !CHILD_TRANSCRIPT_ID.test(record.id)) {
+        if (record.type === "message" || record.type === "custom_message") {
+          throw new Error("OMP session transcript contains an unlinked message");
+        }
+        continue;
+      }
+      const parentId = record.parentId;
+      if (
+        parentId !== null &&
+        (typeof parentId !== "string" || !CHILD_TRANSCRIPT_ID.test(parentId))
+      ) {
+        throw new Error("OMP session transcript contains an invalid parent identity");
+      }
+      if (nodes.size >= MAX_SESSION_TRANSCRIPT_ENTRIES) {
+        throw new Error("OMP session transcript exceeds entry limits");
+      }
+      if (nodes.has(record.id))
+        throw new Error("OMP session transcript contains duplicate entries");
+      nodes.set(record.id, {
+        parentId,
+        message: persistedTranscriptMessage(record, record.id),
+      });
+      leafId = record.id;
+    }
+    if (!nativeSessionId) throw new Error("OMP session transcript is missing session identity");
+
+    const messages: unknown[] = [];
+    const seen = new Set<string>();
+    let currentId = leafId;
+    let pathEntriesRead = 0;
+    while (currentId) {
+      pathEntriesRead += 1;
+      if (pathEntriesRead % 1_024 === 0) {
+        await yieldToEventLoop();
+        signal?.throwIfAborted();
+      }
+      if (seen.has(currentId)) throw new Error("OMP session transcript contains a parent cycle");
+      seen.add(currentId);
+      const node = nodes.get(currentId);
+      if (!node) throw new Error("OMP session transcript contains an unresolved parent");
+      if (node.message !== undefined) messages.push(node.message);
+      currentId = node.parentId ?? undefined;
+    }
+    messages.reverse();
+    if (messages.length > MAX_CHILD_TRANSCRIPT_MESSAGES) {
+      throw new Error("OMP session transcript exceeds message limits");
+    }
+    const hydratedMessages: unknown[] = [];
+    const blobBudget = { bytes: 0 };
+    for (const message of messages) {
+      signal?.throwIfAborted();
+      hydratedMessages.push(
+        await hydratePersistedMessageImages(message, blobDirectory, blobBudget, signal),
+      );
+    }
+    return {
+      sessionFile: canonicalFile,
+      nativeSessionId,
+      byteLength: bytes.byteLength,
+      messages: hydratedMessages,
+    };
+  } catch (error) {
+    if (error instanceof Error) throw error;
+    throw new Error("OMP session transcript could not be decoded");
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+}
+
 export async function readOmpPersistedSubagentTranscript(
   parentSessionFile: string,
   childTranscriptId: string,