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

package/src/read-compat.ts

@@ -0,0 +1,35 @@
+/**
+ * Read compatibility with databases that predate a column.
+ *
+ * Read-only handles (viewers, the read API) cannot upgrade the schema, so
+ * selecting a column that an older database lacks would fail. Readers select
+ * through these concrete Drizzle selections instead, which substitute the
+ * column's default when it is missing and keep the declared row types.
+ */
+import { getTableColumns, sql, type SQL } from "drizzle-orm";
+import type { KernelDatabase } from "./client";
+import { piAgentSessions, type SessionKind } from "./schema/pi-agent-sessions";
+import { hasSessionKindColumn } from "./upgrade";
+
+const { kind: _kind, ...piAgentSessionBaseColumns } =
+  getTableColumns(piAgentSessions);
+
+export type PiAgentSessionSelection = typeof piAgentSessionBaseColumns & {
+  kind: SQL.Aliased<SessionKind>;
+};
+
+/**
+ * Every pi_agent_sessions column, with `kind` read as 'pi' when the column
+ * does not exist yet. Rows keep the PiAgentSession shape:
+ * `db.select(piAgentSessionSelection(db)).from(piAgentSessions)`.
+ */
+export function piAgentSessionSelection(
+  db: KernelDatabase,
+): PiAgentSessionSelection {
+  return {
+    ...piAgentSessionBaseColumns,
+    kind: hasSessionKindColumn(db)
+      ? sql<SessionKind>`${piAgentSessions.kind}`.as("kind")
+      : sql<SessionKind>`'pi'`.as("kind"),
+  };
+}

package/src/schema/agent-runs.ts

@@ -0,0 +1,80 @@
+import {
+  foreignKey,
+  index,
+  integer,
+  real,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+import { containers } from "./containers";
+import { piAgentSessions } from "./pi-agent-sessions";
+
+/** What opened the run. Closed vocabulary per the identity model. */
+export const RUN_TRIGGER = {
+  OPERATOR: "operator",
+  PARENT_TOOL: "parent-tool",
+  STEER: "steer",
+  RESUME: "resume",
+  SYSTEM: "system",
+  /** A model node describing a finished parent run. */
+  POST_RUN: "post-run",
+  /** A decision node judging something on behalf of its caller. */
+  JUDGE: "judge",
+} as const;
+
+export type RunTrigger = (typeof RUN_TRIGGER)[keyof typeof RUN_TRIGGER];
+
+/** Run status. Closed vocabulary: every run reaches a terminal status. */
+export const RUN_STATUS = {
+  RUNNING: "running",
+  DONE: "done",
+  ERROR: "error",
+  ABORTED: "aborted",
+  TURN_LIMIT: "turn-limit",
+} as const;
+
+export type RunStatus = (typeof RUN_STATUS)[keyof typeof RUN_STATUS];
+
+/**
+ * One processing loop: message in -> response out. A session holds many runs.
+ * inbound_event_id is the message that opened the run; outbound_event_id the
+ * response that closed it.
+ */
+export const agentRuns = sqliteTable(
+  "agent_runs",
+  {
+    id: text("id").primaryKey(),
+    piSessionId: text("pi_session_id")
+      .notNull()
+      .references(() => piAgentSessions.id),
+    containerId: text("container_id")
+      .notNull()
+      .references(() => containers.id),
+    parentRunId: text("parent_run_id"),
+    parentToolUseId: text("parent_tool_use_id"),
+    agentName: text("agent_name").notNull(),
+    trigger: text("trigger").$type<RunTrigger>().notNull(),
+    inboundEventId: text("inbound_event_id"),
+    outboundEventId: text("outbound_event_id"),
+    displayLabel: text("display_label"),
+    phase: text("phase"),
+    status: text("status").$type<RunStatus>().notNull(),
+    usageInputTokens: integer("usage_input_tokens").notNull().default(0),
+    usageOutputTokens: integer("usage_output_tokens").notNull().default(0),
+    usageCacheRead: integer("usage_cache_read").notNull().default(0),
+    usageCacheWrite: integer("usage_cache_write").notNull().default(0),
+    usageCostEstimate: real("usage_cost_estimate"),
+    startedAt: text("started_at").notNull(),
+    endedAt: text("ended_at"),
+  },
+  (table) => [
+    index("ix_agent_runs_pi_session_id").on(table.piSessionId),
+    index("ix_agent_runs_container_id").on(table.containerId),
+    index("ix_agent_runs_parent_run_id").on(table.parentRunId),
+    foreignKey({
+      columns: [table.parentRunId],
+      foreignColumns: [table.id],
+      name: "agent_runs_parent_run_id_fkey",
+    }),
+  ],
+);

package/src/schema/containers.ts

@@ -0,0 +1,72 @@
+import {
+  foreignKey,
+  index,
+  integer,
+  real,
+  sqliteTable,
+  text,
+  unique,
+} from "drizzle-orm/sqlite-core";
+
+/**
+ * Container status vocabulary. Open string — the kind/status vocabulary
+ * belongs to the host app; these are the kernel's conventional values.
+ */
+export const CONTAINER_STATUS = {
+  ACTIVE: "active",
+  DONE: "done",
+  ERROR: "error",
+  ABORTED: "aborted",
+} as const;
+
+export type ContainerStatus =
+  | (typeof CONTAINER_STATUS)[keyof typeof CONTAINER_STATUS]
+  | (string & {});
+
+/**
+ * The single grouping primitive. Identified deterministically from
+ * (kernel_id, kind, app_key) — same identity always upserts the same row.
+ * Usage rollup columns land in Phase 1 and are populated in Phase 2.
+ */
+export const containers = sqliteTable(
+  "containers",
+  {
+    id: text("id").primaryKey(),
+    kernelId: text("kernel_id").notNull(),
+    kind: text("kind").notNull(),
+    /** JSON array of app-defined key segments. */
+    appKey: text("app_key", { mode: "json" }).$type<string[]>().notNull(),
+    label: text("label"),
+    status: text("status")
+      .$type<ContainerStatus>()
+      .notNull()
+      .default(CONTAINER_STATUS.ACTIVE),
+    parentContainerId: text("parent_container_id"),
+    phase: text("phase"),
+    phaseVocabulary: text("phase_vocabulary", { mode: "json" }).$type<string[]>(),
+    workingDir: text("working_dir"),
+    /** Opaque to the kernel. */
+    metadata: text("metadata", { mode: "json" }).$type<Record<string, unknown>>(),
+    usageInputTokens: integer("usage_input_tokens").notNull().default(0),
+    usageOutputTokens: integer("usage_output_tokens").notNull().default(0),
+    usageCacheRead: integer("usage_cache_read").notNull().default(0),
+    usageCacheWrite: integer("usage_cache_write").notNull().default(0),
+    usageCostEstimate: real("usage_cost_estimate"),
+    createdAt: text("created_at").notNull(),
+    startedAt: text("started_at"),
+    endedAt: text("ended_at"),
+  },
+  (table) => [
+    unique("ux_containers_kernel_kind_app_key").on(
+      table.kernelId,
+      table.kind,
+      table.appKey,
+    ),
+    index("ix_containers_parent_container_id").on(table.parentContainerId),
+    foreignKey({
+      columns: [table.parentContainerId],
+      foreignColumns: [table.id],
+      name: "containers_parent_container_id_fkey",
+    }),
+  ],
+);

package/src/schema/index.ts

@@ -0,0 +1,31 @@
+/**
+ * SQLite schema (the only dialect). One database file per kernel:
+ * .agent-kernel/trace.db, opened with Bun's built-in SQLite driver
+ * through Drizzle (see ../client.ts).
+ */
+export {
+  containers,
+  CONTAINER_STATUS,
+  type ContainerStatus,
+} from "./containers";
+export {
+  piAgentSessions,
+  SESSION_KIND,
+  SESSION_STATUS,
+  type SessionKind,
+  type SessionStatus,
+} from "./pi-agent-sessions";
+export {
+  agentRuns,
+  RUN_STATUS,
+  RUN_TRIGGER,
+  type RunStatus,
+  type RunTrigger,
+} from "./agent-runs";
+export { traceEvents } from "./trace-events";
+export { traceBlobs } from "./trace-blobs";
+export {
+  promptRevisions,
+  PROMPT_REVISION_SOURCE,
+  type PromptRevisionSource,
+} from "./prompt-revisions";

package/src/schema/pi-agent-sessions.ts

@@ -0,0 +1,82 @@
+import {
+  foreignKey,
+  index,
+  integer,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+import { containers } from "./containers";
+
+/**
+ * Session status vocabulary. Open string; conventional kernel values below.
+ * A session is "active" while its agent can still receive runs.
+ */
+export const SESSION_STATUS = {
+  ACTIVE: "active",
+  ENDED: "ended",
+  ERROR: "error",
+} as const;
+
+export type SessionStatus =
+  | (typeof SESSION_STATUS)[keyof typeof SESSION_STATUS]
+  | (string & {});
+
+/**
+ * What produced the session. "pi" is a Pi agent conversation; "call" and
+ * "decision" are model-node sessions (one structured request or one
+ * classification per run). Open string; rows written before the column
+ * existed read as "pi".
+ */
+export const SESSION_KIND = {
+  PI: "pi",
+  CALL: "call",
+  DECISION: "decision",
+} as const;
+
+export type SessionKind =
+  | (typeof SESSION_KIND)[keyof typeof SESSION_KIND]
+  | (string & {});
+
+/**
+ * One Pi conversation. The system prompt is frozen at session creation, so
+ * prompt_hash lives here (populated from Phase 3). A subagent's session
+ * carries parent_session_id and parent_tool_use_id.
+ */
+export const piAgentSessions = sqliteTable(
+  "pi_agent_sessions",
+  {
+    id: text("id").primaryKey(),
+    containerId: text("container_id")
+      .notNull()
+      .references(() => containers.id),
+    parentSessionId: text("parent_session_id"),
+    /** Set when spawned by a parent's tool call. */
+    parentToolUseId: text("parent_tool_use_id"),
+    agentName: text("agent_name").notNull(),
+    displayLabel: text("display_label"),
+    model: text("model"),
+    /** Phase 3: prompt revision hash ("pk1-<sha256>") at session creation. */
+    promptHash: text("prompt_hash"),
+    status: text("status").$type<SessionStatus>().notNull(),
+    phase: text("phase"),
+    usageInputTokens: integer("usage_input_tokens").notNull().default(0),
+    usageOutputTokens: integer("usage_output_tokens").notNull().default(0),
+    createdAt: text("created_at").notNull(),
+    endedAt: text("ended_at"),
+    /**
+     * Added after the table shipped: existing databases gain it through
+     * upgradeKernelObservabilitySchema, and readers go through
+     * piAgentSessionSelection so un-upgraded read-only handles still work.
+     */
+    kind: text("kind").$type<SessionKind>().notNull().default(SESSION_KIND.PI),
+  },
+  (table) => [
+    index("ix_pi_agent_sessions_container_id").on(table.containerId),
+    index("ix_pi_agent_sessions_parent_session_id").on(table.parentSessionId),
+    foreignKey({
+      columns: [table.parentSessionId],
+      foreignColumns: [table.id],
+      name: "pi_agent_sessions_parent_session_id_fkey",
+    }),
+  ],
+);

package/src/schema/prompt-revisions.ts

@@ -0,0 +1,34 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/** Where a prompt revision came from. */
+export const PROMPT_REVISION_SOURCE = {
+  REGISTRY_BOOT: "registry-boot",
+  LAB_SAVE: "lab-save",
+  DISK_SYNC: "disk-sync",
+  /** Direct mutation committed by the Prompt Kit MCP shared store. */
+  PROMPT_KIT_MCP: "prompt-kit-mcp",
+  MIGRATION: "migration",
+  /** Accepted prompt-editor agent proposal applied by the Phase 2 apply path. */
+  AGENT_RUN: "agent-run",
+} as const;
+
+export type PromptRevisionSource =
+  (typeof PROMPT_REVISION_SOURCE)[keyof typeof PROMPT_REVISION_SOURCE];
+
+/**
+ * Content-addressed prompt revisions. The table lands in Phase 1;
+ * Phase 3 (prompt.json + revisions) populates it.
+ */
+export const promptRevisions = sqliteTable("prompt_revisions", {
+  /** "pk1-<sha256>" of the canonicalized PromptDocument. */
+  hash: text("hash").primaryKey(),
+  agentName: text("agent_name").notNull(),
+  /** e.g. "prompt-kit/v1". */
+  schemaVersion: text("schema_version").notNull(),
+  /** Canonical JSON PromptDocument. */
+  document: text("document").notNull(),
+  /** XML-tagged Markdown rendered at save time. */
+  renderedText: text("rendered_text").notNull(),
+  source: text("source").$type<PromptRevisionSource>().notNull(),
+  createdAt: text("created_at").notNull(),
+});

package/src/schema/trace-blobs.ts

@@ -0,0 +1,20 @@
+import { blob, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/**
+ * Content-addressed blob store for binary/JSON trace payloads — images
+ * captured from agent conversations, sanitized message JSON, system prompt
+ * text. Rows are immutable and keyed by content hash, so inserts are
+ * idempotent and identical payloads dedupe for free.
+ */
+export const traceBlobs = sqliteTable("trace_blobs", {
+  /** "b1-<sha256hex>" of the raw bytes. */
+  hash: text("hash").primaryKey(),
+  /** "image" | "message" | "text" | "tools" (open string). */
+  kind: text("kind").notNull(),
+  mimeType: text("mime_type").notNull(),
+  byteLength: integer("byte_length").notNull(),
+  /** Raw payload bytes. */
+  data: blob("data", { mode: "buffer" }).notNull(),
+  /** ISO-8601, caller-supplied like the other tables. */
+  createdAt: text("created_at").notNull(),
+});

package/src/schema/trace-events.ts

@@ -0,0 +1,30 @@
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/**
+ * The event log. container_id is the single required grouping identity;
+ * run/session/agent/user linkage is stamped when known at emit time.
+ * event_id is the idempotent insert key (INSERT OR IGNORE).
+ */
+export const traceEvents = sqliteTable(
+  "trace_events",
+  {
+    eventId: text("event_id").primaryKey(),
+    containerId: text("container_id").notNull(),
+    runId: text("run_id"),
+    piSessionId: text("pi_session_id"),
+    agentId: text("agent_id"),
+    userId: text("user_id"),
+    type: text("type").notNull(),
+    source: text("source").notNull(),
+    traceLevel: integer("trace_level").notNull(),
+    eventData: text("event_data", { mode: "json" }).notNull(),
+    spanId: text("span_id"),
+    parentEventId: text("parent_event_id"),
+    timestamp: text("timestamp").notNull(),
+  },
+  (table) => [
+    index("idx_events_container_ts").on(table.containerId, table.timestamp),
+    index("idx_events_run").on(table.runId),
+    index("idx_events_pi_session").on(table.piSessionId),
+  ],
+);

package/src/types.ts

@@ -0,0 +1,29 @@
+import type {
+  agentRuns,
+  containers,
+  piAgentSessions,
+  promptRevisions,
+  traceBlobs,
+  traceEvents,
+} from "./schema";
+
+export type Container = typeof containers.$inferSelect;
+export type NewContainer = typeof containers.$inferInsert;
+
+export type TraceEventRow = typeof traceEvents.$inferSelect;
+export type NewTraceEventRow = typeof traceEvents.$inferInsert;
+
+export type PiAgentSession = typeof piAgentSessions.$inferSelect;
+export type NewPiAgentSession = typeof piAgentSessions.$inferInsert;
+
+export type AgentRun = typeof agentRuns.$inferSelect;
+export type NewAgentRun = typeof agentRuns.$inferInsert;
+
+export type PromptRevision = typeof promptRevisions.$inferSelect;
+export type NewPromptRevision = typeof promptRevisions.$inferInsert;
+
+export type TraceBlob = typeof traceBlobs.$inferSelect;
+export type NewTraceBlob = typeof traceBlobs.$inferInsert;
+
+/** One blob to store through the transaction-local write path (content-addressed by `hash`). */
+export type TraceBlobInput = NewTraceBlob;

package/src/upgrade.ts

@@ -0,0 +1,138 @@
+/**
+ * Idempotent, additive schema upgrades for databases created before a column
+ * existed. No migration tooling: each step probes the live schema and applies
+ * a metadata-only change when it is missing.
+ *
+ * `ALTER TABLE … ADD COLUMN` with a constant default rewrites no rows in
+ * SQLite, so it is safe on very large databases. No index is added for the
+ * new column: CREATE INDEX would scan the whole table.
+ */
+import { sql } from "drizzle-orm";
+import type { KernelDatabase } from "./client";
+
+export interface SchemaUpgradeReport {
+  /** Steps that added something (including a column another handle added concurrently). */
+  applied: string[];
+  /** Steps with nothing to do, or that could not run on a read-only handle. */
+  skipped: string[];
+  /** True when a needed step could not run because the handle is read-only. */
+  readOnly: boolean;
+}
+
+const SESSION_KIND_STEP = "pi_agent_sessions.kind";
+
+/** SQLITE_BUSY retries for the ALTER: 5 retries, 100 ms apart. */
+const BUSY_RETRIES = 5;
+const BUSY_RETRY_DELAY_MS = 100;
+
+/**
+ * Handles known to have pi_agent_sessions.kind. Only positive results are
+ * cached: a column is never removed, but a read-only handle must notice as
+ * soon as another process adds it.
+ */
+const sessionKindColumnKnown = new WeakMap<KernelDatabase, true>();
+
+/**
+ * The error and its causes: Drizzle wraps driver errors from `db.run()` in a
+ * DrizzleError whose `cause` is the bun:sqlite error.
+ */
+function errorChain(error: unknown): unknown[] {
+  const chain: unknown[] = [];
+  let current = error;
+  while (current !== undefined && current !== null && chain.length < 5) {
+    chain.push(current);
+    current = (current as { cause?: unknown }).cause;
+  }
+  return chain;
+}
+
+/** True when the error (or a cause) has a SQLite code starting with `prefix`. */
+function hasSqliteCode(error: unknown, prefix: string): boolean {
+  return errorChain(error).some((link) => {
+    const code = (link as { code?: unknown }).code;
+    return typeof code === "string" && code.startsWith(prefix);
+  });
+}
+
+/** SQLITE_BUSY (or an extended BUSY code) anywhere in the cause chain. */
+export function isSqliteBusyError(error: unknown): boolean {
+  return hasSqliteCode(error, "SQLITE_BUSY");
+}
+
+function isSqliteReadOnlyError(error: unknown): boolean {
+  return hasSqliteCode(error, "SQLITE_READONLY");
+}
+
+function isDuplicateColumnError(error: unknown): boolean {
+  return errorChain(error).some(
+    (link) => link instanceof Error && /duplicate column name/i.test(link.message),
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function tableColumns(db: KernelDatabase, table: string): string[] {
+  return db
+    .all<{ name: string }>(sql`PRAGMA table_info(${sql.identifier(table)})`)
+    .map((column) => column.name);
+}
+
+/**
+ * True when pi_agent_sessions has `kind`. Safe on read-only handles. Caches
+ * only a POSITIVE result per handle; a negative result re-probes
+ * `PRAGMA table_info` on every call (microseconds), so a long-lived read-only
+ * handle sees the column as soon as another process upgrades the database.
+ */
+export function hasSessionKindColumn(db: KernelDatabase): boolean {
+  if (sessionKindColumnKnown.has(db)) return true;
+  const present = tableColumns(db, "pi_agent_sessions").includes("kind");
+  if (present) sessionKindColumnKnown.set(db, true);
+  return present;
+}
+
+/**
+ * Bring an existing kernel database up to the current schema. Idempotent;
+ * a duplicate-column error from a concurrent upgrader counts as applied,
+ * SQLITE_BUSY is retried, and a read-only handle is reported (not thrown).
+ * Any other failure throws.
+ */
+export async function upgradeKernelObservabilitySchema(
+  db: KernelDatabase,
+): Promise<SchemaUpgradeReport> {
+  const report: SchemaUpgradeReport = { applied: [], skipped: [], readOnly: false };
+
+  const columns = tableColumns(db, "pi_agent_sessions");
+  // No table yet: the bootstrap CREATE (which already has `kind`) makes it.
+  if (columns.length === 0 || columns.includes("kind")) {
+    if (columns.length > 0) sessionKindColumnKnown.set(db, true);
+    report.skipped.push(SESSION_KIND_STEP);
+    return report;
+  }
+
+  for (let attempt = 0; ; attempt++) {
+    try {
+      db.run(
+        sql`ALTER TABLE pi_agent_sessions ADD COLUMN kind TEXT NOT NULL DEFAULT 'pi'`,
+      );
+      break;
+    } catch (error) {
+      if (isDuplicateColumnError(error)) break;
+      if (isSqliteReadOnlyError(error)) {
+        report.readOnly = true;
+        report.skipped.push(SESSION_KIND_STEP);
+        return report;
+      }
+      if (isSqliteBusyError(error) && attempt < BUSY_RETRIES) {
+        await sleep(BUSY_RETRY_DELAY_MS);
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  sessionKindColumnKnown.set(db, true);
+  report.applied.push(SESSION_KIND_STEP);
+  return report;
+}