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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codecaine AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# Agent Kernel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+- An opinionated system for building **problem-specific agent harnesses** on top of the Pi Agent SDK
+- Designed for high-volume multi-agent systems that do one class of work extremely well
+
+## Why this exists
+
+- Mass multi-agent systems are the next step for agentic software:
+  - Dozens of workers
+  - Long pipelines
+  - Deep subagent trees
+- At that scale, token spend becomes a commodity resource:
+  - Meter it like water.
+  - Map where it flows.
+  - Find the leaks.
+  - Cut or reroute work that does not earn its cost.
+- General tools like Codex and Claude Code are useful execution environments, but they do not give a purpose-built harness deep observability into spawned agents, token budgets, trace lineage, and model effectiveness.
+
+- Agent Kernel is opinionated about that layer:
+
+  - **Extreme observability.** 
+    - Every prompt, context load, tool call, subagent spawn, and lifecycle event is captured as a durable, explicitly-linked trace. 
+    - You can answer "where did the tokens go and what did they produce?" without guesswork or timestamp reconstruction.
+  - **Extreme control.** 
+    - Per-kernel and per-agent concurrency, explicit boundaries, scoped run context, abort/stop semantics, and a spawn pipeline you can audit end to end. 
+    - You decide how many workers run and how they're contained.
+  - **Any model, per agent.** 
+    - Agents are declarative definitions, not hardcoded to one model. 
+    - Route each agent in a harness to the model that earns its tokens
+
+- The kernel stays deliberately neutral about *what problem your harness solves*.
+- Workflow semantics, domain tools, and product rules belong to your harness.
+- The kernel owns the runtime and observability foundation that makes a harness safe to scale — because scaling blindly is how agent projects get quietly expensive.
+
+## Packages
+
+- This is a platform monorepo while the contracts settle:
+
+  - `@codecaine-ai/agent-kernel-protocol` — trace/event envelopes, event factories, deterministic event ids, and turn usage
+  - `@codecaine-ai/agent-kernel-db` — per-kernel SQLite observability store, schema, kernel manifest, and query helpers
+  - `@codecaine-ai/agent-kernel` — `createKernel` runtime, container identity, registry, context assembly, spawn pipeline, in-process emitter, subagents, trace doctor, read API, and transcript recovery
+  - `@codecaine-ai/prompt-kit` — prompt document model, canonicalization/hashing, renderers, and editor primitives (sibling repo and Core workspace member)
+  - `@codecaine-ai/agent-kernel-viewer-core` — viewer DTOs, read/catalog API paths, trace transforms, and prompt diffing
+  - `@codecaine-ai/agent-kernel-viewer-ui` — trace tree and card system, the detail panel and its data-only renderer contract, prompt lab components
+  - `@codecaine-ai/agent-kernel-viewer-shell` — mountable trace workspace, the tree/detail viewer, and the shared style system
+
+## Building a harness on it
+
+- A harness is the problem-specific application layer that makes the kernel good at one task.
+- A host application (the harness) consumes the kernel through a thin adapter.
+- The harness owns workflow sessions, phase semantics, domain tools, app-specific loaders, app DB tables, and custom viewer panels.
+- The kernel owns spawning, context assembly, observability storage, trace reading, and viewer primitives.
+- The identity model behind all of this (containers, sessions, runs, turns, linkage invariants) is documented in [docs/10-system-design/15-identity-model/](docs/10-system-design/15-identity-model/); the overhaul plan that produced it lives in [docs/.drafts/agent-kernel-overhaul.plan.md](docs/.drafts/agent-kernel-overhaul.plan.md).
+
+## Setup
+
+- Install dependencies with `bun install`.
+
+## Validation
+
+- Run `bun run test:boundaries`.
+- Run `bun run typecheck`.
+- Run `bun run test`.
+- The boundary check is the important portability gate: platform packages must not import the host application or reference host-app paths.
+- Per-package typechecks exist as `bun run typecheck:<name>` for `protocol`, `db`, `kernel`, `tui`, `core-harness`, `viewer-core`, `viewer-ui`, `viewer-shell`, and `examples`.
+- When changing package boundaries, also sweep manually: `rg -n "@spectre|\.spectre|Spectre|SPECTRE|apps/backend|apps/frontend|checkpoint-slice|SessionStateManager" packages docs` — app-specific names may appear in docs only when explaining adapter boundaries, never in package source.
+- To check a kernel trace database against the linkage/usage invariants, run the trace doctor: `bun run packages/kernel/src/doctor-cli.ts <db-path>`. Without an argument it defaults to `.agent-kernel/trace.db` under the current directory; non-zero exit means violations.
+
+## Running this repo's kernel
+
+- This repo is itself a kernel; its service leg is the core harness: `bun run core-harness` serves health, the kernel read API, catalog routes, and prompt-edit sessions on `http://127.0.0.1:4860`.
+- The terminal harness (`/kernel` inside pi) is [`packages/tui`](packages/tui/README.md) — setup, usage, and troubleshooting live in its README.
+- To fold marked TUI sessions into the owning kernel's `trace.db`, run `bunx agent-kernel-tui-ingest` (batch, idempotent).
+- To register a kernel with the Observatory, run `bun run registry:check` / `bun run registry:sync` in the observatory repo (Core's doctor warns on drift).
+
+## Examples
+
+- The Prompt Kit kernel host has moved to the sibling Prompt Kit repo at `../prompt-kit/packages/prompt-kit-agent`; from `../prompt-kit`, start it with `bun run dev:agent`.
+- `examples/simple-research-kernel` is a runnable standalone Simple Research Kernel — run instructions in [its README](examples/simple-research-kernel/README.md).
+- The example defines agents in a catalog (folder-form bundles: `agent.json` + `prompt/` + `context/` + `tools/`), loads context sidecars, spawns scout subagents, waits for their reports, reviews gaps, queues a report writer, writes working memory, persists kernel observability rows, and renders traces through the viewer shell.
+- Start it with `bun run dev:simple-research` — SQLite only, no service processes.
+- It runs against a single local SQLite file (`examples/simple-research-kernel/.agent-kernel/trace.db`, WAL mode) created on boot, alongside a local kernel manifest (`.agent-kernel/kernel.json`).
+- The launcher starts the API on `http://127.0.0.1:8788` and the viewer on `http://127.0.0.1:5174`.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@codecaine-ai/agent-kernel-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Codecaine-AI/agent-kernel.git",
+    "directory": "packages/db"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./actions": "./src/actions/index.ts",
+    "./schema": "./src/schema/index.ts",
+    "./client": "./src/client.ts",
+    "./manifest": "./src/manifest.ts",
+    "./types": "./src/types.ts"
+  },
+  "dependencies": {
+    "@codecaine-ai/agent-kernel-protocol": "^0.0.3",
+    "drizzle-orm": "^0.45.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/actions/agent-runs.ts

@@ -0,0 +1,146 @@
+import { asc, eq } from "drizzle-orm";
+import type { KernelDatabase } from "../client";
+import { agentRuns, type RunStatus } from "../schema/agent-runs";
+import type { AgentRun, NewAgentRun } from "../types";
+
+export async function createAgentRun(
+  db: KernelDatabase,
+  data: NewAgentRun,
+): Promise<AgentRun> {
+  const [row] = await db.insert(agentRuns).values(data).returning();
+  return row;
+}
+
+export async function upsertAgentRun(
+  db: KernelDatabase,
+  data: NewAgentRun,
+): Promise<AgentRun> {
+  const [row] = await db
+    .insert(agentRuns)
+    .values(data)
+    .onConflictDoUpdate({
+      target: agentRuns.id,
+      set: {
+        piSessionId: data.piSessionId,
+        containerId: data.containerId,
+        ...(data.parentRunId !== undefined && { parentRunId: data.parentRunId }),
+        ...(data.parentToolUseId !== undefined && {
+          parentToolUseId: data.parentToolUseId,
+        }),
+        ...(data.agentName !== undefined && { agentName: data.agentName }),
+        ...(data.trigger !== undefined && { trigger: data.trigger }),
+        ...(data.inboundEventId !== undefined && {
+          inboundEventId: data.inboundEventId,
+        }),
+        ...(data.outboundEventId !== undefined && {
+          outboundEventId: data.outboundEventId,
+        }),
+        ...(data.displayLabel !== undefined && { displayLabel: data.displayLabel }),
+        ...(data.phase !== undefined && { phase: data.phase }),
+        ...(data.status !== undefined && { status: data.status }),
+        ...(data.startedAt !== undefined && { startedAt: data.startedAt }),
+        ...(data.endedAt !== undefined && { endedAt: data.endedAt }),
+      },
+    })
+    .returning();
+  return row;
+}
+
+/**
+ * Close or update a run: status transition plus the outbound event that
+ * closed it and the usage rollup (Phase 2 populates usage).
+ */
+export async function updateAgentRunStatus(
+  db: KernelDatabase,
+  runId: string,
+  status: RunStatus,
+  opts?: {
+    endedAt?: string;
+    outboundEventId?: string;
+    usageInputTokens?: number;
+    usageOutputTokens?: number;
+    usageCacheRead?: number;
+    usageCacheWrite?: number;
+    usageCostEstimate?: number;
+  },
+): Promise<AgentRun | undefined> {
+  const [row] = await db
+    .update(agentRuns)
+    .set({
+      status,
+      ...(opts?.endedAt !== undefined && { endedAt: opts.endedAt }),
+      ...(opts?.outboundEventId !== undefined && {
+        outboundEventId: opts.outboundEventId,
+      }),
+      ...(opts?.usageInputTokens !== undefined && {
+        usageInputTokens: opts.usageInputTokens,
+      }),
+      ...(opts?.usageOutputTokens !== undefined && {
+        usageOutputTokens: opts.usageOutputTokens,
+      }),
+      ...(opts?.usageCacheRead !== undefined && {
+        usageCacheRead: opts.usageCacheRead,
+      }),
+      ...(opts?.usageCacheWrite !== undefined && {
+        usageCacheWrite: opts.usageCacheWrite,
+      }),
+      ...(opts?.usageCostEstimate !== undefined && {
+        usageCostEstimate: opts.usageCostEstimate,
+      }),
+    })
+    .where(eq(agentRuns.id, runId))
+    .returning();
+  return row;
+}
+
+/**
+ * Record the message event that opened the run. With the in-process emitter,
+ * the inbound user_message id is only known once the emitter observes it —
+ * after the run row was inserted.
+ */
+export async function updateAgentRunInboundEvent(
+  db: KernelDatabase,
+  runId: string,
+  inboundEventId: string,
+): Promise<AgentRun | undefined> {
+  const [row] = await db
+    .update(agentRuns)
+    .set({ inboundEventId })
+    .where(eq(agentRuns.id, runId))
+    .returning();
+  return row;
+}
+
+export async function getAgentRun(
+  db: KernelDatabase,
+  runId: string,
+): Promise<AgentRun | undefined> {
+  const [row] = await db
+    .select()
+    .from(agentRuns)
+    .where(eq(agentRuns.id, runId))
+    .limit(1);
+  return row;
+}
+
+export async function listAgentRunsForPiSession(
+  db: KernelDatabase,
+  piSessionId: string,
+): Promise<AgentRun[]> {
+  return db
+    .select()
+    .from(agentRuns)
+    .where(eq(agentRuns.piSessionId, piSessionId))
+    .orderBy(asc(agentRuns.startedAt));
+}
+
+export async function listAgentRunsForContainer(
+  db: KernelDatabase,
+  containerId: string,
+): Promise<AgentRun[]> {
+  return db
+    .select()
+    .from(agentRuns)
+    .where(eq(agentRuns.containerId, containerId))
+    .orderBy(asc(agentRuns.startedAt));
+}

package/src/actions/containers.ts

@@ -0,0 +1,138 @@
+import { asc, eq } from "drizzle-orm";
+import type { KernelDatabase } from "../client";
+import { containers, type ContainerStatus } from "../schema/containers";
+import type { Container } from "../types";
+
+export interface UpsertContainerInput {
+  /**
+   * Caller-derived deterministic id (the kernel derives
+   * uuidv5(kernelNamespace(kernelId), `${kind}\n${key.join("\n")}`)).
+   * On conflict with an existing (kernelId, kind, appKey) row, the existing
+   * row's id wins — the same identity always resolves to the same container.
+   */
+  id: string;
+  kernelId: string;
+  kind: string;
+  appKey: string[];
+  label?: string;
+  status?: ContainerStatus;
+  parentContainerId?: string | null;
+  phase?: string | null;
+  phaseVocabulary?: string[] | null;
+  workingDir?: string | null;
+  metadata?: Record<string, unknown> | null;
+  createdAt?: string;
+  startedAt?: string | null;
+  endedAt?: string | null;
+}
+
+/**
+ * Idempotent container upsert keyed by (kernel_id, kind, app_key).
+ * Identity columns and created_at are never updated on conflict; descriptive
+ * fields are refreshed when provided.
+ */
+export async function upsertContainer(
+  db: KernelDatabase,
+  input: UpsertContainerInput,
+): Promise<Container> {
+  const set = {
+    ...(input.label !== undefined && { label: input.label }),
+    ...(input.status !== undefined && { status: input.status }),
+    ...(input.parentContainerId !== undefined && {
+      parentContainerId: input.parentContainerId,
+    }),
+    ...(input.phase !== undefined && { phase: input.phase }),
+    ...(input.phaseVocabulary !== undefined && {
+      phaseVocabulary: input.phaseVocabulary,
+    }),
+    ...(input.workingDir !== undefined && { workingDir: input.workingDir }),
+    ...(input.metadata !== undefined && { metadata: input.metadata }),
+    ...(input.startedAt !== undefined && { startedAt: input.startedAt }),
+    ...(input.endedAt !== undefined && { endedAt: input.endedAt }),
+  };
+
+  const [row] = await db
+    .insert(containers)
+    .values({
+      id: input.id,
+      kernelId: input.kernelId,
+      kind: input.kind,
+      appKey: input.appKey,
+      label: input.label,
+      status: input.status,
+      parentContainerId: input.parentContainerId,
+      phase: input.phase,
+      phaseVocabulary: input.phaseVocabulary,
+      workingDir: input.workingDir,
+      metadata: input.metadata,
+      createdAt: input.createdAt ?? new Date().toISOString(),
+      startedAt: input.startedAt,
+      endedAt: input.endedAt,
+    })
+    .onConflictDoUpdate({
+      target: [containers.kernelId, containers.kind, containers.appKey],
+      // DO UPDATE requires a non-empty set; kind = kind is a no-op refresh.
+      set: Object.keys(set).length > 0 ? set : { kind: input.kind },
+    })
+    .returning();
+  return row;
+}
+
+export async function updateContainerStatus(
+  db: KernelDatabase,
+  containerId: string,
+  status: ContainerStatus,
+  opts?: {
+    phase?: string;
+    startedAt?: string;
+    endedAt?: string;
+    metadata?: Record<string, unknown>;
+  },
+): Promise<Container | undefined> {
+  const [row] = await db
+    .update(containers)
+    .set({
+      status,
+      ...(opts?.phase !== undefined && { phase: opts.phase }),
+      ...(opts?.startedAt !== undefined && { startedAt: opts.startedAt }),
+      ...(opts?.endedAt !== undefined && { endedAt: opts.endedAt }),
+      ...(opts?.metadata !== undefined && { metadata: opts.metadata }),
+    })
+    .where(eq(containers.id, containerId))
+    .returning();
+  return row;
+}
+
+export async function getContainer(
+  db: KernelDatabase,
+  containerId: string,
+): Promise<Container | undefined> {
+  const [row] = await db
+    .select()
+    .from(containers)
+    .where(eq(containers.id, containerId))
+    .limit(1);
+  return row;
+}
+
+export async function listChildContainers(
+  db: KernelDatabase,
+  parentContainerId: string,
+): Promise<Container[]> {
+  return db
+    .select()
+    .from(containers)
+    .where(eq(containers.parentContainerId, parentContainerId))
+    .orderBy(asc(containers.createdAt));
+}
+
+export async function listContainersForKernel(
+  db: KernelDatabase,
+  kernelId: string,
+): Promise<Container[]> {
+  return db
+    .select()
+    .from(containers)
+    .where(eq(containers.kernelId, kernelId))
+    .orderBy(asc(containers.createdAt));
+}

package/src/actions/index.ts

@@ -0,0 +1,10 @@
+export * from "./containers";
+export * from "./pi-agent-sessions";
+export * from "./agent-runs";
+export * from "./trace-events";
+export * from "./trace-blobs";
+export * from "./prompt-revisions";
+export * from "./read-api";
+export * from "./usage";
+export * from "./tx-local";
+export * from "./node-sessions";