@codecaine-ai/agent-kernel-db 0.0.0-stage → 0.0.2

package/src/actions/tx-local.ts

@@ -0,0 +1,254 @@
+/**
+ * Synchronous, transaction-local write helpers.
+ *
+ * bun-sqlite Drizzle transactions are SYNCHRONOUS: `db.transaction(fn,
+ * { behavior })` runs fn inside bun:sqlite's native transaction and does not
+ * await a returned promise (drizzle-orm/bun-sqlite/session.js). An async
+ * callback commits at its first `await` and runs the rest outside the
+ * transaction. Every helper here therefore takes the transaction handle and
+ * returns synchronously, using only `.run()`, `.all()` and `.get()`. Never
+ * call the async actions (usage.ts, trace-events.ts, pi-agent-sessions.ts)
+ * from inside a transaction; the async actions stay as they are for every
+ * other caller.
+ */
+import { and, asc, eq, sql } from "drizzle-orm";
+import type { TraceEvent } from "@codecaine-ai/agent-kernel-protocol";
+import type { KernelDatabase } from "../client";
+import { agentRuns, type RunStatus } from "../schema/agent-runs";
+import { containers } from "../schema/containers";
+import {
+  piAgentSessions,
+  type SessionStatus,
+} from "../schema/pi-agent-sessions";
+import { traceBlobs } from "../schema/trace-blobs";
+import { traceEvents } from "../schema/trace-events";
+import type {
+  NewAgentRun,
+  NewPiAgentSession,
+  NewTraceEventRow,
+  TraceBlobInput,
+} from "../types";
+import { isSqliteBusyError } from "../upgrade";
+import type { UsageDelta } from "./usage";
+
+/** The transaction handle `db.transaction` passes to its (synchronous) callback. */
+export type KernelTx = Parameters<Parameters<KernelDatabase["transaction"]>[0]>[0];
+
+/** SQLITE_BUSY on BEGIN IMMEDIATE is retried with these waits, outside the transaction. */
+const BUSY_RETRY_DELAYS_MS = [50, 100, 200, 400, 800] as const;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Run a synchronous callback in one `BEGIN IMMEDIATE` transaction. Any throw
+ * inside rolls everything back and rejects. SQLITE_BUSY is retried 5 times
+ * (50, 100, 200, 400, 800 ms); a rolled-back attempt left nothing behind, so
+ * rerunning it is safe. The rest parameter rejects promise-returning
+ * callbacks at compile time.
+ */
+export async function runImmediateTransaction<T>(
+  db: KernelDatabase,
+  fn: (tx: KernelTx) => T,
+  ..._syncOnly: T extends PromiseLike<unknown> ? [never] : []
+): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return db.transaction(fn, { behavior: "immediate" });
+    } catch (error) {
+      const delay = BUSY_RETRY_DELAYS_MS[attempt];
+      if (!isSqliteBusyError(error) || delay === undefined) throw error;
+      await sleep(delay);
+    }
+  }
+}
+
+/**
+ * Column row for one envelope. The transport-only piSessionUuid is resolved
+ * into the pi_session_id column at write time.
+ */
+export function traceEventToRow(e: TraceEvent): NewTraceEventRow {
+  return {
+    eventId: e.eventId,
+    containerId: e.containerId,
+    runId: e.runId ?? null,
+    piSessionId: e.piSessionUuid ?? null,
+    agentId: e.agentId ?? null,
+    userId: e.userId ?? null,
+    type: e.type,
+    source: e.source,
+    traceLevel: e.traceLevel,
+    eventData: e.eventData,
+    spanId: e.spanId ?? null,
+    parentEventId: e.parentEventId ?? null,
+    timestamp: e.timestamp,
+  };
+}
+
+/** INSERT … ON CONFLICT(event_id) DO NOTHING. Returns the number of rows inserted. */
+export function insertTraceEventsTx(tx: KernelTx, events: TraceEvent[]): number {
+  if (events.length === 0) return 0;
+  return tx
+    .insert(traceEvents)
+    .values(events.map(traceEventToRow))
+    .onConflictDoNothing({ target: traceEvents.eventId })
+    .returning({ eventId: traceEvents.eventId })
+    .all().length;
+}
+
+/** Content-addressed, immutable: an existing hash is left untouched. */
+export function upsertTraceBlobsTx(tx: KernelTx, blobs: TraceBlobInput[]): void {
+  if (blobs.length === 0) return;
+  tx.insert(traceBlobs)
+    .values(blobs)
+    .onConflictDoNothing({ target: traceBlobs.hash })
+    .run();
+}
+
+/**
+ * Insert a session, or refresh the descriptive fields that are defined on
+ * `row` (same conflict rules as upsertPiAgentSession; created_at is kept).
+ */
+export function upsertPiAgentSessionTx(tx: KernelTx, row: NewPiAgentSession): void {
+  tx.insert(piAgentSessions)
+    .values(row)
+    .onConflictDoUpdate({
+      target: piAgentSessions.id,
+      set: {
+        containerId: row.containerId,
+        ...(row.parentSessionId !== undefined && {
+          parentSessionId: row.parentSessionId,
+        }),
+        ...(row.parentToolUseId !== undefined && {
+          parentToolUseId: row.parentToolUseId,
+        }),
+        ...(row.agentName !== undefined && { agentName: row.agentName }),
+        ...(row.displayLabel !== undefined && { displayLabel: row.displayLabel }),
+        ...(row.model !== undefined && { model: row.model }),
+        ...(row.promptHash !== undefined && { promptHash: row.promptHash }),
+        ...(row.status !== undefined && { status: row.status }),
+        ...(row.phase !== undefined && { phase: row.phase }),
+        ...(row.endedAt !== undefined && { endedAt: row.endedAt }),
+        ...(row.kind !== undefined && { kind: row.kind }),
+      },
+    })
+    .run();
+}
+
+/** Plain insert: a duplicate run id or a missing parent run throws (FK). */
+export function insertAgentRunTx(tx: KernelTx, row: NewAgentRun): void {
+  tx.insert(agentRuns).values(row).run();
+}
+
+/**
+ * Set a run's status, end time and (optionally) outbound event. With
+ * `onlyIfStatus`, only a run currently in that status changes. Returns the
+ * number of rows changed.
+ */
+export function setRunStatusTx(
+  tx: KernelTx,
+  args: {
+    runId: string;
+    status: RunStatus;
+    endedAt: string;
+    outboundEventId?: string;
+    onlyIfStatus?: RunStatus;
+  },
+): number {
+  const where =
+    args.onlyIfStatus === undefined
+      ? eq(agentRuns.id, args.runId)
+      : and(eq(agentRuns.id, args.runId), eq(agentRuns.status, args.onlyIfStatus));
+  return tx
+    .update(agentRuns)
+    .set({
+      status: args.status,
+      endedAt: args.endedAt,
+      ...(args.outboundEventId !== undefined && {
+        outboundEventId: args.outboundEventId,
+      }),
+    })
+    .where(where)
+    .returning({ id: agentRuns.id })
+    .all().length;
+}
+
+/** `endedAt: null` clears the end time (a session reopened for a new attempt). */
+export function setSessionStatusTx(
+  tx: KernelTx,
+  args: { sessionId: string; status: SessionStatus; endedAt: string | null },
+): void {
+  tx.update(piAgentSessions)
+    .set({ status: args.status, endedAt: args.endedAt })
+    .where(eq(piAgentSessions.id, args.sessionId))
+    .run();
+}
+
+/**
+ * Additive usage rollup for one run, its session and its container in one
+ * go (the transaction-local twin of usage.ts). Cost columns stay NULL unless
+ * a cost is present.
+ */
+export function applyUsageTx(
+  tx: KernelTx,
+  ids: { runId: string; sessionId: string; containerId: string },
+  delta: UsageDelta,
+): void {
+  tx.update(agentRuns)
+    .set({
+      usageInputTokens: sql`${agentRuns.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${agentRuns.usageOutputTokens} + ${delta.outputTokens}`,
+      usageCacheRead: sql`${agentRuns.usageCacheRead} + ${delta.cacheReadTokens}`,
+      usageCacheWrite: sql`${agentRuns.usageCacheWrite} + ${delta.cacheWriteTokens}`,
+      ...(delta.costEstimate !== undefined && {
+        usageCostEstimate: sql`coalesce(${agentRuns.usageCostEstimate}, 0) + ${delta.costEstimate}`,
+      }),
+    })
+    .where(eq(agentRuns.id, ids.runId))
+    .run();
+
+  tx.update(piAgentSessions)
+    .set({
+      usageInputTokens: sql`${piAgentSessions.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${piAgentSessions.usageOutputTokens} + ${delta.outputTokens}`,
+    })
+    .where(eq(piAgentSessions.id, ids.sessionId))
+    .run();
+
+  tx.update(containers)
+    .set({
+      usageInputTokens: sql`${containers.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${containers.usageOutputTokens} + ${delta.outputTokens}`,
+      usageCacheRead: sql`${containers.usageCacheRead} + ${delta.cacheReadTokens}`,
+      usageCacheWrite: sql`${containers.usageCacheWrite} + ${delta.cacheWriteTokens}`,
+      ...(delta.costEstimate !== undefined && {
+        usageCostEstimate: sql`coalesce(${containers.usageCostEstimate}, 0) + ${delta.costEstimate}`,
+      }),
+    })
+    .where(eq(containers.id, ids.containerId))
+    .run();
+}
+
+/** A session's runs, oldest first. `inboundEventId` locates each run's start event. */
+export function listRunsForSessionTx(
+  tx: KernelTx,
+  sessionId: string,
+): Array<{
+  id: string;
+  status: RunStatus;
+  startedAt: string;
+  inboundEventId: string | null;
+}> {
+  return tx
+    .select({
+      id: agentRuns.id,
+      status: agentRuns.status,
+      startedAt: agentRuns.startedAt,
+      inboundEventId: agentRuns.inboundEventId,
+    })
+    .from(agentRuns)
+    .where(eq(agentRuns.piSessionId, sessionId))
+    .orderBy(asc(agentRuns.startedAt), asc(agentRuns.id))
+    .all();
+}

package/src/actions/usage.ts

@@ -0,0 +1,79 @@
+/**
+ * Usage rollup write path (Phase 2) — dumb additive SQL increments.
+ *
+ * Turn usage lands on the run row as each pi_turn_end arrives; run totals are
+ * folded into the session and container rows when the run closes. costEstimate
+ * columns are nullable — increments treat NULL as 0 and only touch the column
+ * when a delta is present, so rows with no cost data stay NULL.
+ */
+import { eq, sql } from "drizzle-orm";
+import type { KernelDatabase } from "../client";
+import { agentRuns } from "../schema/agent-runs";
+import { containers } from "../schema/containers";
+import { piAgentSessions } from "../schema/pi-agent-sessions";
+
+export interface UsageDelta {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costEstimate?: number;
+}
+
+/** Additively increment a run's usage rollup columns (one pi_turn_end). */
+export async function updateRunUsage(
+  db: KernelDatabase,
+  runId: string,
+  delta: UsageDelta,
+): Promise<void> {
+  await db
+    .update(agentRuns)
+    .set({
+      usageInputTokens: sql`${agentRuns.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${agentRuns.usageOutputTokens} + ${delta.outputTokens}`,
+      usageCacheRead: sql`${agentRuns.usageCacheRead} + ${delta.cacheReadTokens}`,
+      usageCacheWrite: sql`${agentRuns.usageCacheWrite} + ${delta.cacheWriteTokens}`,
+      ...(delta.costEstimate !== undefined && {
+        usageCostEstimate: sql`coalesce(${agentRuns.usageCostEstimate}, 0) + ${delta.costEstimate}`,
+      }),
+    })
+    .where(eq(agentRuns.id, runId));
+}
+
+/**
+ * Fold run totals into the session rollup. Sessions carry input/output
+ * columns only (see pi_agent_sessions schema).
+ */
+export async function incrementSessionUsage(
+  db: KernelDatabase,
+  piSessionId: string,
+  delta: { inputTokens: number; outputTokens: number },
+): Promise<void> {
+  await db
+    .update(piAgentSessions)
+    .set({
+      usageInputTokens: sql`${piAgentSessions.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${piAgentSessions.usageOutputTokens} + ${delta.outputTokens}`,
+    })
+    .where(eq(piAgentSessions.id, piSessionId));
+}
+
+/** Fold run totals into the container rollup. */
+export async function incrementContainerUsage(
+  db: KernelDatabase,
+  containerId: string,
+  delta: UsageDelta,
+): Promise<void> {
+  await db
+    .update(containers)
+    .set({
+      usageInputTokens: sql`${containers.usageInputTokens} + ${delta.inputTokens}`,
+      usageOutputTokens: sql`${containers.usageOutputTokens} + ${delta.outputTokens}`,
+      usageCacheRead: sql`${containers.usageCacheRead} + ${delta.cacheReadTokens}`,
+      usageCacheWrite: sql`${containers.usageCacheWrite} + ${delta.cacheWriteTokens}`,
+      ...(delta.costEstimate !== undefined && {
+        usageCostEstimate: sql`coalesce(${containers.usageCostEstimate}, 0) + ${delta.costEstimate}`,
+      }),
+    })
+    .where(eq(containers.id, containerId));
+}

package/src/bootstrap.ts

@@ -0,0 +1,143 @@
+/**
+ * Schema bootstrap — CREATE TABLE IF NOT EXISTS statements mirroring the
+ * Drizzle SQLite schema in ./schema. No migration tooling: the schema is
+ * created idempotently on kernel start against the local trace.db, then
+ * ./upgrade adds any column an older database lacks.
+ */
+import { sql } from "drizzle-orm";
+import type { KernelDatabase } from "./client";
+import { upgradeKernelObservabilitySchema } from "./upgrade";
+
+export async function ensureKernelObservabilitySchema(
+  db: KernelDatabase,
+): Promise<void> {
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS containers (
+      id                  TEXT PRIMARY KEY,
+      kernel_id           TEXT NOT NULL,
+      kind                TEXT NOT NULL,
+      app_key             TEXT NOT NULL,
+      label               TEXT,
+      status              TEXT NOT NULL DEFAULT 'active',
+      parent_container_id TEXT REFERENCES containers(id),
+      phase               TEXT,
+      phase_vocabulary    TEXT,
+      working_dir         TEXT,
+      metadata            TEXT,
+      usage_input_tokens  INTEGER NOT NULL DEFAULT 0,
+      usage_output_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_cache_read    INTEGER NOT NULL DEFAULT 0,
+      usage_cache_write   INTEGER NOT NULL DEFAULT 0,
+      usage_cost_estimate REAL,
+      created_at          TEXT NOT NULL,
+      started_at          TEXT,
+      ended_at            TEXT,
+      UNIQUE (kernel_id, kind, app_key)
+    )
+  `);
+
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS pi_agent_sessions (
+      id                  TEXT PRIMARY KEY,
+      container_id        TEXT NOT NULL REFERENCES containers(id),
+      parent_session_id   TEXT REFERENCES pi_agent_sessions(id),
+      parent_tool_use_id  TEXT,
+      agent_name          TEXT NOT NULL,
+      display_label       TEXT,
+      model               TEXT,
+      prompt_hash         TEXT,
+      status              TEXT NOT NULL,
+      phase               TEXT,
+      usage_input_tokens  INTEGER NOT NULL DEFAULT 0,
+      usage_output_tokens INTEGER NOT NULL DEFAULT 0,
+      created_at          TEXT NOT NULL,
+      ended_at            TEXT,
+      kind                TEXT NOT NULL DEFAULT 'pi'
+    )
+  `);
+
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS agent_runs (
+      id                  TEXT PRIMARY KEY,
+      pi_session_id       TEXT NOT NULL REFERENCES pi_agent_sessions(id),
+      container_id        TEXT NOT NULL REFERENCES containers(id),
+      parent_run_id       TEXT REFERENCES agent_runs(id),
+      parent_tool_use_id  TEXT,
+      agent_name          TEXT NOT NULL,
+      trigger             TEXT NOT NULL,
+      inbound_event_id    TEXT,
+      outbound_event_id   TEXT,
+      display_label       TEXT,
+      phase               TEXT,
+      status              TEXT NOT NULL,
+      usage_input_tokens  INTEGER NOT NULL DEFAULT 0,
+      usage_output_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_cache_read    INTEGER NOT NULL DEFAULT 0,
+      usage_cache_write   INTEGER NOT NULL DEFAULT 0,
+      usage_cost_estimate REAL,
+      started_at          TEXT NOT NULL,
+      ended_at            TEXT
+    )
+  `);
+
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS trace_events (
+      event_id        TEXT PRIMARY KEY,
+      container_id    TEXT NOT NULL,
+      run_id          TEXT,
+      pi_session_id   TEXT,
+      agent_id        TEXT,
+      user_id         TEXT,
+      type            TEXT NOT NULL,
+      source          TEXT NOT NULL,
+      trace_level     INTEGER NOT NULL,
+      event_data      TEXT NOT NULL,
+      span_id         TEXT,
+      parent_event_id TEXT,
+      timestamp       TEXT NOT NULL
+    )
+  `);
+
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS trace_blobs (
+      hash            TEXT PRIMARY KEY,
+      kind            TEXT NOT NULL,
+      mime_type       TEXT NOT NULL,
+      byte_length     INTEGER NOT NULL,
+      data            BLOB NOT NULL,
+      created_at      TEXT NOT NULL
+    )
+  `);
+
+  db.run(sql`
+    CREATE TABLE IF NOT EXISTS prompt_revisions (
+      hash            TEXT PRIMARY KEY,
+      agent_name      TEXT NOT NULL,
+      schema_version  TEXT NOT NULL,
+      document        TEXT NOT NULL,
+      rendered_text   TEXT NOT NULL,
+      source          TEXT NOT NULL,
+      created_at      TEXT NOT NULL
+    )
+  `);
+
+  const indexes = [
+    sql`CREATE INDEX IF NOT EXISTS idx_events_container_ts ON trace_events (container_id, timestamp)`,
+    sql`CREATE INDEX IF NOT EXISTS idx_events_run ON trace_events (run_id)`,
+    sql`CREATE INDEX IF NOT EXISTS idx_events_pi_session ON trace_events (pi_session_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_containers_parent_container_id ON containers (parent_container_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_pi_agent_sessions_container_id ON pi_agent_sessions (container_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_pi_agent_sessions_parent_session_id ON pi_agent_sessions (parent_session_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_agent_runs_pi_session_id ON agent_runs (pi_session_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_agent_runs_container_id ON agent_runs (container_id)`,
+    sql`CREATE INDEX IF NOT EXISTS ix_agent_runs_parent_run_id ON agent_runs (parent_run_id)`,
+  ];
+
+  for (const statement of indexes) {
+    db.run(statement);
+  }
+
+  // Columns added after a table shipped: CREATE TABLE IF NOT EXISTS leaves an
+  // existing table untouched, so existing databases gain them here.
+  await upgradeKernelObservabilitySchema(db);
+}

package/src/client.ts

@@ -0,0 +1,64 @@
+/**
+ * SQLite client helper — one database file per kernel.
+ *
+ * Standard path convention: <root>/.agent-kernel/trace.db. WAL mode is
+ * enabled on open so readers (viewer) never block the writer (kernel).
+ */
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { drizzle, type BunSQLiteDatabase } from "drizzle-orm/bun-sqlite";
+
+/** Standard per-kernel database file, relative to the kernel's root dir. */
+export const KERNEL_DB_RELATIVE_PATH = ".agent-kernel/trace.db";
+
+/** The Drizzle handle every db action is typed against (SQLite-first). */
+export type KernelDatabase = BunSQLiteDatabase<Record<string, never>>;
+
+export interface KernelDatabaseHandle {
+  db: KernelDatabase;
+  /** Absolute or caller-provided path of the opened database file. */
+  path: string;
+  close: () => void;
+}
+
+/** Resolve the standard trace.db path under a kernel root directory. */
+export function kernelDatabasePath(rootDir: string): string {
+  return join(rootDir, KERNEL_DB_RELATIVE_PATH);
+}
+
+/**
+ * Open (creating if needed) a kernel SQLite database: mkdir -p the parent
+ * directory, open the file, enable WAL, and return a Drizzle handle plus
+ * close(). Schema creation is separate — see ensureKernelObservabilitySchema.
+ */
+export function openKernelDatabase(opts: { path: string }): KernelDatabaseHandle {
+  mkdirSync(dirname(opts.path), { recursive: true });
+  const sqlite = new Database(opts.path, { create: true });
+  sqlite.exec("PRAGMA journal_mode = WAL;");
+  sqlite.exec("PRAGMA foreign_keys = ON;");
+  const db = drizzle(sqlite);
+  return {
+    db,
+    path: opts.path,
+    close: () => sqlite.close(),
+  };
+}
+
+/**
+ * Open an existing kernel SQLite database without allowing mutations.
+ *
+ * Unlike openKernelDatabase, this does not create the parent directory or
+ * database, set write-related PRAGMAs, or initialize the observability schema.
+ */
+export function openKernelDatabaseReadOnly(
+  dbPath: string,
+): KernelDatabaseHandle {
+  const sqlite = new Database(dbPath, { readonly: true });
+  const db = drizzle(sqlite);
+  return {
+    db,
+    path: dbPath,
+    close: () => sqlite.close(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./schema";
+export {
+  SESSION_KIND,
+  type SessionKind,
+} from "./schema/pi-agent-sessions";
+export * from "./types";
+export * from "./actions";
+export * from "./bootstrap";
+export * from "./upgrade";
+export * from "./read-compat";
+export * from "./client";
+export * from "./manifest";

package/src/manifest.ts

@@ -0,0 +1,140 @@
+/**
+ * Local kernel manifest — replaces the old kernel_registrations table.
+ *
+ * With one SQLite database per kernel there is no shared plane to register
+ * with; a kernel just writes a small JSON manifest next to its trace.db:
+ * <root>/.agent-kernel/kernel.json.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export const KERNEL_MANIFEST_RELATIVE_PATH = ".agent-kernel/kernel.json";
+
+interface KernelManifestBase {
+  kernelId: string;
+  displayName: string;
+  /** Directory Pi writes its durable JSONL transcripts into. */
+  piSessionsDir: string;
+  /** Base URL of a viewer serving this kernel, when one is running. */
+  viewerBaseUrl?: string;
+}
+
+/** Legacy manifest shape, retained for backward-compatible reads. */
+export interface KernelManifestV1 extends KernelManifestBase {
+  manifestVersion?: 1;
+  kernelRoot?: undefined;
+  dbPath?: undefined;
+  catalogRoots?: undefined;
+  readApiBaseUrl?: undefined;
+}
+
+/** Self-describing kernel manifest written by current harnesses. */
+export interface KernelManifest extends KernelManifestBase {
+  manifestVersion: 2;
+  /** Absolute path to this kernel's .agent-kernel directory. */
+  kernelRoot: string;
+  /** Absolute path to this kernel's trace database. */
+  dbPath: string;
+  /** Absolute paths to the agent-catalog roots exposed by this kernel. */
+  catalogRoots: string[];
+  /** Base URL of the harness read/catalog API, when one is running. */
+  readApiBaseUrl?: string;
+}
+
+export type ReadKernelManifest = KernelManifest | KernelManifestV1;
+
+/** Resolve the manifest path under a kernel root directory. */
+export function kernelManifestPath(rootDir: string): string {
+  return join(rootDir, KERNEL_MANIFEST_RELATIVE_PATH);
+}
+
+/**
+ * Atomically write <dir>/.agent-kernel/kernel.json (creating the directory if
+ * needed). Returns the path written.
+ */
+export async function writeKernelManifest(
+  dir: string,
+  manifest: KernelManifest,
+): Promise<string> {
+  const path = kernelManifestPath(dir);
+  const manifestDir = dirname(path);
+  const temporaryPath = join(
+    manifestDir,
+    `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+
+  await mkdir(manifestDir, { recursive: true });
+  let replaced = false;
+  try {
+    await writeFile(
+      temporaryPath,
+      `${JSON.stringify(manifest, null, 2)}\n`,
+      { encoding: "utf-8", flag: "wx" },
+    );
+    await rename(temporaryPath, path);
+    replaced = true;
+  } finally {
+    if (!replaced) {
+      // Best-effort cleanup must not replace the original write/rename error.
+      await unlink(temporaryPath).catch(() => undefined);
+    }
+  }
+  return path;
+}
+
+/**
+ * Read <dir>/.agent-kernel/kernel.json. Returns undefined when the manifest
+ * does not exist; throws on malformed JSON or a missing required field.
+ */
+export async function readKernelManifest(
+  dir: string,
+): Promise<ReadKernelManifest | undefined> {
+  const path = kernelManifestPath(dir);
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Kernel manifest at ${path} must be a JSON object`);
+  }
+
+  for (const field of ["kernelId", "displayName", "piSessionsDir"] as const) {
+    if (typeof parsed[field] !== "string" || parsed[field].length === 0) {
+      throw new Error(`Kernel manifest at ${path} is missing "${field}"`);
+    }
+  }
+
+  if (
+    parsed.manifestVersion !== undefined &&
+    parsed.manifestVersion !== 1 &&
+    parsed.manifestVersion !== 2
+  ) {
+    throw new Error(
+      `Kernel manifest at ${path} has unsupported "manifestVersion"`,
+    );
+  }
+
+  if (parsed.manifestVersion === 2) {
+    for (const field of ["kernelRoot", "dbPath"] as const) {
+      if (typeof parsed[field] !== "string" || parsed[field].length === 0) {
+        throw new Error(`Kernel manifest at ${path} is missing "${field}"`);
+      }
+    }
+    if (
+      !Array.isArray(parsed.catalogRoots) ||
+      parsed.catalogRoots.some(
+        (root) => typeof root !== "string" || root.length === 0,
+      )
+    ) {
+      throw new Error(`Kernel manifest at ${path} is missing "catalogRoots"`);
+    }
+  }
+
+  return parsed as unknown as ReadKernelManifest;
+}