@data-club/ai-hub-server 0.0.1

package/src/db/schema.ts

@@ -0,0 +1,750 @@
+/**
+ * Drizzle schema for the ai-hub server's SQLite database.
+ *
+ * One row per real-world entity. v1 has no tenant scoping — a deployment is
+ * one customer organization, every row belongs to that customer.
+ *
+ * The shapes here are the canonical source of truth: the migration runner
+ * (`migrate.ts`) builds tables off these definitions, and every handler reads
+ * and writes through Drizzle's typed query builder.
+ *
+ * Forward-compat seams (intentionally non-obvious — see §6.7 "Future
+ * direction"):
+ *
+ * - `user.password_hash` is **nullable**. v1 always populates it (local login is
+ *   the only flow that creates users). Future external IdPs leave it NULL.
+ * - `user.identity_source` defaults to `"local"`. v1 only ever writes
+ *   `"local"`; future external IdPs add values like `"oidc:bankxyz"`.
+ * - `agent.is_archived` and `session.is_archived` are soft-hide flags.
+ *   **Agents and sessions cannot be hard-deleted in v1** (§6.3.4 / §11) — the
+ *   FK on `session.agent_id` is therefore always satisfiable and orphan
+ *   sessions never happen.
+ *
+ * @see SPECIFICATIONS.md §11 — data model
+ * @see SPECIFICATIONS.md §6.7 — auth model + future IdPs
+ * @see SPECIFICATIONS.md §6.8 — persistence
+ */
+
+import { sql } from "drizzle-orm";
+import {
+  blob,
+  index,
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  user                                                                      */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Every human in this deployment, including super admins. ai-hub owns auth.
+ *
+ * The PRD uses singular table names; we follow that exactly so SQL tooling
+ * matches what implementing agents see in the spec.
+ *
+ * @see SPECIFICATIONS.md §11
+ */
+export const user = sqliteTable(
+  "user",
+  {
+    /** Stable UUID PK assigned at insert time (server-generated). */
+    id: text("id").notNull().primaryKey(),
+    /** Login identifier — unique per deployment. */
+    username: text("username").notNull().unique(),
+    /** Optional human-readable name shown in the admin user list. */
+    displayName: text("display_name"),
+    /**
+     * Argon2id encoded hash (PHC string format: embeds m / t / p / salt /
+     * digest). Nullable for forward-compat with external IdPs (§6.7); v1
+     * always populates it.
+     */
+    passwordHash: text("password_hash"),
+    /**
+     * `"local"` in v1. Future external IdPs add values like `"oidc:bankxyz"`.
+     * Designed-for-extension seam per §6.7.
+     */
+    identitySource: text("identity_source").notNull().default("local"),
+    /**
+     * `true` = the user must change their password on the next successful
+     * login (§8.5). Set on the seeded super-admin and after every admin-driven
+     * password reset.
+     */
+    isInitialPassword: integer("is_initial_password", { mode: "boolean" })
+      .notNull()
+      .default(false),
+    /** One of the four roles in §8.1. */
+    role: text("role", {
+      enum: ["user", "power_user", "admin", "super_admin"],
+    })
+      .notNull()
+      .default("user"),
+    /**
+     * `"light"` / `"dark"` / NULL. NULL = follow `admin_setting.theme_default`.
+     * Set when the user picks via `AIHub.ThemeSwitcher`. Ignored as long as
+     * `theme_switcher_enabled = false` (§7.6).
+     */
+    themePreference: text("theme_preference", { enum: ["light", "dark"] }),
+    /**
+     * ISO-8601 timestamp of the last password mutation. Bumped on:
+     *
+     * - Admin password reset (`POST /admin/users/:id/reset-password`).
+     * - Voluntary password change (`POST /auth/change-password` with a
+     *   session token + `current_password`).
+     * - Forced change after admin reset (`POST /auth/change-password`
+     *   with a password-change-only token).
+     *
+     * The middleware compares `passwordChangedAt` against the JWT's
+     * `iat` claim — session tokens issued **before** the last password
+     * mutation are rejected as `401 invalid_credentials`. This is how
+     * an admin-driven reset signs the affected user out immediately
+     * without waiting for the 24h JWT expiry (Step 11 bugfix).
+     */
+    passwordChangedAt: text("password_changed_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+    /** ISO-8601-string seconds-precision timestamp (better-sqlite3 stores as TEXT). */
+    createdAt: text("created_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+    /** Bumped on every UPDATE — handlers SET this explicitly so it's deterministic. */
+    updatedAt: text("updated_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  },
+  (t) => ({
+    /** Speeds up the role-matrix's "find any user with role super_admin" query. */
+    roleIdx: index("user_role_idx").on(t.role),
+  }),
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  agent                                                                     */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `power_user`/`admin`/`super_admin`-curated catalog of ai-hub agents.
+ *
+ * Each row is a use-case (e.g. *Customer Support*) backed by exactly one Letta
+ * agent. Shared across every user in the deployment (§13.2).
+ *
+ * Cannot be hard-deleted in v1 — only archived. `is_archived = true` filters
+ * the row out of the user-facing `GET /agents` response so no new sessions can
+ * start against it; existing sessions remain readable + writable.
+ *
+ * @see SPECIFICATIONS.md §11 — `agent` table
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery defaults
+ */
+export const agent = sqliteTable("agent", {
+  /** Stable UUID PK. */
+  id: text("id").notNull().primaryKey(),
+  /** Operator-facing display name (no length cap in v1). */
+  displayName: text("display_name").notNull(),
+  /**
+   * The Letta-side agent's id. Validated against `client.agents.list` at
+   * write time (Step 5 wires the real check; Step 4 stubs it through).
+   */
+  lettaAgentId: text("letta_agent_id").notNull(),
+  /** Master toggle for the §6.5 recovery loop. Default `false`. */
+  tpmRecoveryEnabled: integer("tpm_recovery_enabled", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  /** Effective ceiling on recovery attempts (§6.5 double-failure abort). */
+  maxRecoveryAttempts: integer("max_recovery_attempts").notNull().default(2),
+  /** Used when 429 doesn't include `Retry-After`. Default 65 (§6.5). */
+  defaultRetryAfterSeconds: integer("default_retry_after_seconds")
+    .notNull()
+    .default(65),
+  /**
+   * Inter-event idle watchdog for the chat stream. If no Letta event
+   * arrives within this many seconds while a turn is `running`, the
+   * runner aborts the turn cleanly: emits
+   * `error{code:"stream_idle"}` + `stream_end{reason:"error"}`, cancels
+   * the upstream Letta run via `client.agents.messages.cancel`, and
+   * transitions `turn.status -> failed`. The timer **resets on every
+   * received event** — well-behaved long-running turns (lots of small
+   * deltas) never trip it; truly wedged ones (provider hang, Letta
+   * deadlock) terminate predictably. Default 60s. Set higher for
+   * tool-heavy agents whose tools may legitimately take longer to run
+   * with no streaming output in between; set lower if you'd rather
+   * fail fast on a stalled provider.
+   */
+  streamIdleTimeoutSeconds: integer("stream_idle_timeout_seconds")
+    .notNull()
+    .default(60),
+  /**
+   * Step-12.5 specialized-agent lever #1 — per-session sandbox directories.
+   *
+   * Relative folder name under `{AI_HUB_FILES_DIR}/seeds/` whose contents
+   * the server recursively copies into `{AI_HUB_FILES_DIR}/sandboxes/{session_id}/`
+   * at session-create time. The Letta Code subprocess for the session then
+   * spawns with `cwd` pointed at the sandbox, and its bundled filesystem
+   * tools (`Read` / `Write` / `Edit` / `Bash` / `Grep` / `Glob`) are
+   * re-enabled so the agent can use the seeded files. NULL = no sandbox;
+   * sessions run with no `cwd` and the existing disallowed-tools list
+   * (today's stateless agent behavior). Validated `^[a-zA-Z0-9_-]+$` at
+   * admin-write time + checked to exist on disk.
+   *
+   * @see docs/server/session-sandboxes.md
+   */
+  sandboxSeedName: text("sandbox_seed_name"),
+  /**
+   * Step-12.5 specialized-agent lever #2 — base-conversation forking.
+   *
+   * Letta conversation id (e.g. `conv-…`) to fork from at `POST /sessions`
+   * time via `client.conversations.fork(...)`. The fork inherits the
+   * source's in-context messages + gets a freshly compiled system message.
+   * NULL = brand-new conversation via `client.conversations.create({ agent_id })`
+   * (today's behavior). Validated at admin-write time: must resolve via
+   * `client.conversations.retrieve` AND its `agent_id` must equal
+   * `letta_agent_id`.
+   *
+   * @see docs/server/session-sandboxes.md
+   */
+  forkSourceConversationId: text("fork_source_conversation_id"),
+  /** Soft-hide flag — see file-level comment. */
+  isArchived: integer("is_archived", { mode: "boolean" }).notNull().default(false),
+  /** ISO-8601 timestamp. */
+  createdAt: text("created_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  /** ISO-8601 timestamp. */
+  updatedAt: text("updated_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+});
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  session                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * One row per ai-hub session — a user's chat against a given ai-hub agent.
+ *
+ * `letta_conversation_id` is server-internal: the React client sees only
+ * `id`. `letta_agent_id` is a snapshot of `agent.letta_agent_id` at session
+ * creation time (re-pointing the catalog row does not migrate existing
+ * conversations).
+ *
+ * @see SPECIFICATIONS.md §11 — `session` table
+ * @see SPECIFICATIONS.md §6.3.1 — sessions API
+ */
+export const session = sqliteTable(
+  "session",
+  {
+    /** Stable UUID PK. */
+    id: text("id").notNull().primaryKey(),
+    /** Owner — enforces (caller_id === user_id) on read/write (§13.2). */
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    /**
+     * The ai-hub agent (use-case) this session is scoped to. RESTRICT-on-delete
+     * is moot in v1 because agents are never hard-deleted — only archived.
+     */
+    agentId: text("agent_id")
+      .notNull()
+      .references(() => agent.id, { onDelete: "restrict" }),
+    /** Identifier returned by Letta on `client.conversations.create`. */
+    lettaConversationId: text("letta_conversation_id").notNull(),
+    /**
+     * Snapshot of `agent.letta_agent_id` at create-time. Re-pointing the
+     * catalog entry does not move existing conversations.
+     */
+    lettaAgentId: text("letta_agent_id").notNull(),
+    /**
+     * Required at create-time (1..80 chars enforced by Zod at the handler
+     * layer, §6.3.1); editable via PATCH `/sessions/{id}`.
+     */
+    title: text("title").notNull(),
+    /**
+     * Soft-hide. Excluded from `GET /sessions` by default; `?include_archived=true`
+     * surfaces archived rows. There is no hard-delete (§6.3.1).
+     */
+    isArchived: integer("is_archived", { mode: "boolean" }).notNull().default(false),
+    /**
+     * Per-session reasoning effort, applied to the agent's `model_settings`
+     * before each turn. NULL = use agent's persisted default. The accepted
+     * values depend on the agent's model — Anthropic uses `low|medium|high|xhigh|max`,
+     * OpenAI uses `none|minimal|low|medium|high|xhigh`. The capability map
+     * (computed from the agent's model handle) drives UI rendering.
+     */
+    reasoningEffort: text("reasoning_effort"),
+    /**
+     * Per-session verbosity, OpenAI-family models only. NULL = default.
+     */
+    verbosity: text("verbosity"),
+    /**
+     * Per-session thinking budget for Google AI/Vertex models (numeric token
+     * budget). NULL = default.
+     */
+    thinkingBudget: integer("thinking_budget"),
+    /**
+     * Step-12.5 — absolute filesystem path of the per-session sandbox
+     * directory. Populated at create time **only when** the parent agent's
+     * `sandbox_seed_name` was non-null (the server recursively copied the
+     * seed folder into this path before responding with the new session).
+     * NULL = no sandbox; the Letta Code subprocess for this session spawns
+     * with no `cwd` and the existing disallowed-tools list.
+     *
+     * Server-internal — never exposed via wire (mirrors
+     * `letta_conversation_id`). Cleared to NULL by
+     * `POST /admin/sessions/:id/purge-sandbox`.
+     *
+     * @see docs/server/session-sandboxes.md
+     */
+    sandboxDir: text("sandbox_dir"),
+    /** ISO-8601 timestamp. */
+    createdAt: text("created_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+    /** ISO-8601 timestamp. */
+    updatedAt: text("updated_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  },
+  (t) => ({
+    /** Drives the user-scoped session list + the per-caller session_count on /agents. */
+    userAgentIdx: index("session_user_agent_idx").on(t.userId, t.agentId),
+  }),
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  turn                                                                      */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * One row per AI turn (user message + assistant response cycle).
+ *
+ * Lives in the ai-hub DB for the *streaming session* (resumption + state
+ * transitions); message history itself is Letta-owned.
+ *
+ * @see SPECIFICATIONS.md §11
+ * @see SPECIFICATIONS.md §10 — state machine
+ */
+export const turn = sqliteTable("turn", {
+  /** Stable UUID PK. */
+  id: text("id").notNull().primaryKey(),
+  /** Parent session. Cascades on delete — but sessions never delete in v1. */
+  sessionId: text("session_id")
+    .notNull()
+    .references(() => session.id, { onDelete: "cascade" }),
+  /** Top-level §10.1 turn status. `idle` is excluded — no row exists yet then. */
+  status: text("status", {
+    enum: ["running", "done", "cancelled", "failed"],
+  }).notNull(),
+  /** Sub-state per §10.1; only meaningful while `status = 'running'`. */
+  phase: text("phase", {
+    enum: [
+      "model_text",
+      "model_reasoning",
+      "model_tool_input",
+      "tool_executing",
+      "waiting_provider",
+      "awaiting_user",
+    ],
+  }),
+  /** Highest emitted `seq` (§9). 0 if no events yet. */
+  lastSeq: integer("last_seq").notNull().default(0),
+  /** Optional client-supplied key for resume-by-rerequest (§6.3.2). */
+  idempotencyKey: text("idempotency_key"),
+  /** ISO-8601. */
+  startedAt: text("started_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  /** ISO-8601 — set when the turn enters a terminal state. */
+  finishedAt: text("finished_at"),
+});
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  turn_event                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Append-only log of SSE events per turn for `/chat/{turn_id}/events`
+ * resumption. Composite PK = `(turn_id, seq)`.
+ *
+ * @see SPECIFICATIONS.md §11
+ * @see SPECIFICATIONS.md §6.6 — state machine and SSE
+ */
+export const turnEvent = sqliteTable(
+  "turn_event",
+  {
+    /** Parent turn. Cascade on parent delete (rare in practice — turns persist). */
+    turnId: text("turn_id")
+      .notNull()
+      .references(() => turn.id, { onDelete: "cascade" }),
+    /** Monotonic per-turn (§9). 0-based. */
+    seq: integer("seq").notNull(),
+    /** Discriminator from the §9 wire protocol. */
+    eventName: text("event_name").notNull(),
+    /** JSON-serialized payload. Written via `JSON.stringify` at the handler layer. */
+    data: text("data", { mode: "json" }).notNull(),
+    /** `(status, phase)` snapshot at emission. */
+    state: text("state", { mode: "json" }).notNull(),
+    /** ISO-8601 timestamp. */
+    createdAt: text("created_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.turnId, t.seq] }),
+  }),
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  admin_setting                                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Singleton row holding deployment-wide settings.
+ *
+ * `id` is a fixed integer (= 1) so the singleton constraint is enforceable
+ * via PK. The encryption key (`AI_HUB_ENCRYPTION_KEY`) is **not** a column —
+ * it lives in env only (§6.8 / §12.1).
+ *
+ * Bootstrap-only env semantics for `service_token_signing_key` and
+ * `metrics_scrape_token` are documented in §6.7 / §6.10 / §12.1: on first
+ * boot, env values seed these columns; after that, env is no longer
+ * consulted. Rotation lives at `/admin/settings/rotate-{signing-key,
+ * metrics-token}`.
+ *
+ * @see SPECIFICATIONS.md §11
+ * @see SPECIFICATIONS.md §6.10 — `/metrics` bearer auth
+ * @see SPECIFICATIONS.md §6.7 — single signing key
+ * @see SPECIFICATIONS.md §12.1 — env vars
+ */
+export const adminSetting = sqliteTable("admin_setting", {
+  /** Always 1 — singleton row. */
+  id: integer("id").notNull().primaryKey(),
+  /** AES-256 encrypted Letta API key. Encrypted under env `AI_HUB_ENCRYPTION_KEY`. */
+  lettaApiKeyEncrypted: blob("letta_api_key_encrypted", { mode: "buffer" }),
+  /** Letta server base URL (e.g. `http://localhost:8283/v1`). */
+  lettaBaseUrl: text("letta_base_url"),
+  /** Optional super-admin override for the "Open Letta ADE" link target (§6.3.4). */
+  lettaAdeUrl: text("letta_ade_url"),
+  /** Flat JSON blob of UI feature toggles per §8.4. Defaults to `{}`. */
+  featureToggles: text("feature_toggles", { mode: "json" }).notNull().default("{}"),
+  /** When false, the deployment is single-theme (§7.6). */
+  themeSwitcherEnabled: integer("theme_switcher_enabled", { mode: "boolean" })
+    .notNull()
+    .default(true),
+  /** `"light"` | `"dark"`. Initial theme for new users (§7.6). */
+  themeDefault: text("theme_default", { enum: ["light", "dark"] })
+    .notNull()
+    .default("light"),
+  /**
+   * JWT signing key. Bootstrap-seeded from env `SERVICE_TOKEN_SIGNING_KEY` on
+   * first boot if set, else random. Authoritative after first boot — rotate
+   * via `/admin/settings/rotate-signing-key` (§6.7).
+   */
+  serviceTokenSigningKey: blob("service_token_signing_key", { mode: "buffer" }),
+  /**
+   * 32-byte hex token used by `/metrics` (§6.10). Bootstrap-seeded from env
+   * `METRICS_SCRAPE_TOKEN` if set, else random + logged once on stdout.
+   */
+  metricsScrapeToken: text("metrics_scrape_token"),
+  /** Last rotation timestamp; surfaced in the metrics-token settings section. */
+  metricsScrapeTokenRotatedAt: text("metrics_scrape_token_rotated_at"),
+  /** Last rotation timestamp; surfaced in the signing-key settings section. */
+  signingKeyRotatedAt: text("signing_key_rotated_at"),
+  /** ISO-8601 timestamp. */
+  updatedAt: text("updated_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+});
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  message_override                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Per-conversation, per-position **two-layer** content overrides for the
+ * messages rendered by `GET /sessions/:id/messages` and (forward-looking)
+ * the LLM-visible content at that position.
+ *
+ * **Why two layers.** Every message has two viewpoints that can legitimately
+ * diverge in tier-3 customizations:
+ *
+ * - **system view** (`system_override`) — what the LLM saw / should see at
+ *   this position. Today this column is *stored but inert at read time* —
+ *   we keep it because Letta owns its own conversation history and we
+ *   can't actually rewrite past rows it persisted. It exists for two
+ *   forward-looking purposes: audit/debug tooling that wants to know
+ *   what the operator intends the LLM context to look like, and a future
+ *   context-replay feature.
+ *
+ * - **user view** (`user_override`) — what the human sees in the chat
+ *   transcript at this position. This is what the messages-list route
+ *   substitutes for display.
+ *
+ * Both columns are nullable; at least one must be non-null per a CHECK
+ * constraint (enforced in the migration SQL). The "set just one column"
+ * shape lets one writer set the user-facing view without clobbering an
+ * earlier-set system-facing one and vice-versa.
+ *
+ * **Why position-keyed instead of id-keyed.** Letta rotates the
+ * `system_message.id` on every prompt recompile, so id-based keys would
+ * go stale. The chronologically-sorted index into
+ * `listMessages(conversation_id)` is stable across recompiles.
+ *
+ * **Lifecycle / writers.**
+ *
+ * - The `POST /chat` post-turn writer creates a row with `user_override`
+ *   populated (and `system_override` left null) when the request body
+ *   carried a `user_override` parameter AND the turn terminated `done`.
+ *   It runs immediately after the turn-end event, at which point we know
+ *   the user message persisted and no turn is active.
+ *
+ * - `PUT /sessions/:id/message-overrides/:position` is the manual writer
+ *   for past messages — operator / SDK callers. Gated by two checks: the
+ *   position must already exist in Letta's message list, and no turn for
+ *   the session may be live. Merge semantics: only the columns the body
+ *   provided are written; an existing column on the other layer is
+ *   preserved.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — sessions API
+ * @see SPECIFICATIONS.md §6.4 — Letta integration boundary
+ */
+export const messageOverride = sqliteTable(
+  "message_override",
+  {
+    /** Letta conversation id this override applies within. */
+    conversationId: text("conversation_id").notNull(),
+    /**
+     * 0-based index into the chronologically-sorted message list returned
+     * by `LettaClient.listMessages(conversationId)`. Stable across
+     * system-prompt recompiles — only the `system_message` id rotates,
+     * not its position.
+     */
+    ordinalPosition: integer("ordinal_position").notNull(),
+    /**
+     * What the LLM saw / should see at this position. Stored but inert
+     * at display time today (Letta owns its own history). Tomorrow:
+     * audit/debug rendering, context-replay features. NULL when only the
+     * `user_override` layer was set.
+     */
+    systemOverride: text("system_override"),
+    /**
+     * What the human sees in the chat transcript at this position.
+     * Substituted verbatim into the wire `content` field by the
+     * messages-list route. Empty string is valid — it hides the message
+     * visually but keeps the bubble slot (use DELETE to remove the slot
+     * entirely). NULL when only the `system_override` layer was set.
+     */
+    userOverride: text("user_override"),
+    /** ISO-8601 timestamp. */
+    createdAt: text("created_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+    /** ISO-8601 timestamp. */
+    updatedAt: text("updated_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.conversationId, t.ordinalPosition] }),
+  }),
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Inferred row types                                                        */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Row shape for the `user` table (Drizzle-inferred). */
+export type UserRow = typeof user.$inferSelect;
+/** Insert shape for the `user` table. */
+export type UserInsert = typeof user.$inferInsert;
+/** Row shape for the `agent` table. */
+export type AgentRow = typeof agent.$inferSelect;
+/** Insert shape for the `agent` table. */
+export type AgentInsert = typeof agent.$inferInsert;
+/** Row shape for the `session` table. */
+export type SessionRow = typeof session.$inferSelect;
+/** Insert shape for the `session` table. */
+export type SessionInsert = typeof session.$inferInsert;
+/** Row shape for the `turn` table. */
+export type TurnRow = typeof turn.$inferSelect;
+/** Insert shape for the `turn` table. */
+export type TurnInsert = typeof turn.$inferInsert;
+/** Row shape for the `turn_event` table. */
+export type TurnEventRow = typeof turnEvent.$inferSelect;
+/** Insert shape for the `turn_event` table. */
+export type TurnEventInsert = typeof turnEvent.$inferInsert;
+/** Row shape for the `admin_setting` table. */
+export type AdminSettingRow = typeof adminSetting.$inferSelect;
+/** Insert shape for the `admin_setting` table. */
+export type AdminSettingInsert = typeof adminSetting.$inferInsert;
+/** Row shape for the `message_override` table. */
+export type MessageOverrideRow = typeof messageOverride.$inferSelect;
+/** Insert shape for the `message_override` table. */
+export type MessageOverrideInsert = typeof messageOverride.$inferInsert;
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  message_usage                                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Provider-reported per-turn token usage, stamped on the LAST assistant
+ * message of each turn. Surfaced to the chat UI via a hover badge so
+ * users can see (a) total tokens consumed and (b) prompt-cache
+ * hit/miss split (Anthropic + OpenAI + Gemini all report
+ * `cached_input_tokens`; Anthropic also reports `cache_write_tokens`).
+ *
+ * The runner fetches Letta's `GET /v1/runs/{run_id}/messages` after
+ * the turn ends, finds the `usage_statistics`-typed message, and
+ * inserts one row here keyed by the last assistant message's Letta id.
+ *
+ * @see SPECIFICATIONS.md §9 — `usage` SSE event
+ * @see docs/server/chat-sse.md — wire protocol
+ */
+export const messageUsage = sqliteTable(
+  "message_usage",
+  {
+    /**
+     * Letta message id this usage belongs to — typically the LAST
+     * assistant message of the turn that produced it.
+     */
+    lettaMessageId: text("letta_message_id").notNull().primaryKey(),
+    /** Owning session; cascade-deletes when the session is hard-deleted. */
+    sessionId: text("session_id")
+      .notNull()
+      .references(() => session.id, { onDelete: "cascade" }),
+    /** Total non-cached prompt tokens (input). */
+    promptTokens: integer("prompt_tokens"),
+    /** Completion tokens (output). */
+    completionTokens: integer("completion_tokens"),
+    /** Sum reported by the provider — may differ from prompt+completion when reasoning is counted separately. */
+    totalTokens: integer("total_tokens"),
+    /** Prompt-cache HIT tokens. Anthropic / OpenAI / Gemini all report. */
+    cachedInputTokens: integer("cached_input_tokens"),
+    /** Prompt-cache WRITE tokens. Anthropic only — null elsewhere. */
+    cacheWriteTokens: integer("cache_write_tokens"),
+    /** Reasoning/thinking tokens. Anthropic + OpenAI o-series. */
+    reasoningTokens: integer("reasoning_tokens"),
+    /** Rolling context-window size estimate post-turn (Letta-side). */
+    contextTokens: integer("context_tokens"),
+    /** Optional Letta run id for traceback. */
+    runId: text("run_id"),
+    /** Stamped at insert time. */
+    createdAt: text("created_at")
+      .notNull()
+      .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  },
+  (t) => ({
+    /** Per-session lookups when rendering /sessions/{id}/messages. */
+    sessionIdx: index("message_usage_session_idx").on(t.sessionId),
+  }),
+);
+
+/** Row shape for the `message_usage` table. */
+export type MessageUsageRow = typeof messageUsage.$inferSelect;
+/** Insert shape for the `message_usage` table. */
+export type MessageUsageInsert = typeof messageUsage.$inferInsert;
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  rotating_message                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Admin-curated **rotating starting message** — a prompt that ai-hub runs
+ * against a Letta agent on a schedule, capturing the agent's reply as a
+ * *pre-prepared conversation* that refreshes automatically.
+ *
+ * This is an automated, self-refreshing evolution of `agent.fork_source_conversation_id`
+ * (static base-conversation forking). Instead of an operator hand-authoring a
+ * base conversation in the ADE and pasting its id, a rotation runner:
+ *
+ *   1. `createConversation(letta_agent_id)`,
+ *   2. sends `prompt` (drained to completion via the normal streaming path),
+ *   3. deletes the prompt's `user_message` so the conversation opens with the
+ *      agent's reply,
+ *   4. stores the resulting conversation id in `current_conversation_id`.
+ *
+ * The row's `id` (a `rmsg-…` token) is the identifier callers reference
+ * anywhere a conversation is referenced. Today that's the agent's **Base
+ * conversation ID** field: an `agent.fork_source_conversation_id` of
+ * `rmsg-<id>` resolves (at `POST /sessions`) to this row's
+ * `current_conversation_id`, which is then forked like any static base.
+ *
+ * **Same-agent fork constraint.** Letta's fork API requires the new
+ * conversation to share the source's agent, so a rotating message can only
+ * back ai-hub agents whose `letta_agent_id` equals this row's
+ * `letta_agent_id`. The admin agents validator enforces this at write time
+ * (mirrors the static `fork_source_agent_mismatch` check).
+ *
+ * **Resilience.** A failed rotation never blanks a working
+ * `current_conversation_id` — the runner keeps the last-good value, records
+ * `last_status = 'error'` + `last_error`, and retries on the next interval.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+export const rotatingMessage = sqliteTable("rotating_message", {
+  /** Stable PK in `rmsg-<uuid>` form — also the public reference token. */
+  id: text("id").notNull().primaryKey(),
+  /** Operator-facing display name. */
+  displayName: text("display_name").notNull(),
+  /** The prompt sent to the agent each rotation. */
+  prompt: text("prompt").notNull(),
+  /**
+   * Raw Letta agent id the prompt runs against. Validated via
+   * `client.agents.retrieve` at admin-write time. Must equal the
+   * `letta_agent_id` of any ai-hub agent that references this row.
+   */
+  lettaAgentId: text("letta_agent_id").notNull(),
+  /**
+   * Schedule discriminator:
+   * - `"every"`  — fixed interval; `interval_seconds` is authoritative.
+   * - `"daily"`  — once per day at `daily_time` (`"HH:MM"`, server-local).
+   * - `"cron"`   — `cron_expression` (5-field) parsed via `cron-parser`.
+   */
+  scheduleKind: text("schedule_kind", {
+    enum: ["every", "daily", "cron"],
+  }).notNull(),
+  /** Period in seconds for `schedule_kind = 'every'`. NULL otherwise. */
+  intervalSeconds: integer("interval_seconds"),
+  /** `"HH:MM"` (24h, server-local) for `schedule_kind = 'daily'`. NULL otherwise. */
+  dailyTime: text("daily_time"),
+  /** 5-field cron expression for `schedule_kind = 'cron'`. NULL otherwise. */
+  cronExpression: text("cron_expression"),
+  /**
+   * The current pre-prepared, forkable Letta conversation id. NULL until the
+   * first successful rotation; kept at its last-good value across failures.
+   */
+  currentConversationId: text("current_conversation_id"),
+  /** Outcome of the most recent rotation attempt. */
+  lastStatus: text("last_status", {
+    enum: ["pending", "ok", "error"],
+  })
+    .notNull()
+    .default("pending"),
+  /** Human-readable error from the last failed rotation. NULL when ok/pending. */
+  lastError: text("last_error"),
+  /** ISO-8601 timestamp of the last successful rotation. NULL until first success. */
+  lastRotatedAt: text("last_rotated_at"),
+  /**
+   * ISO-8601 timestamp the scheduler compares against `now` to decide when to
+   * rotate next. Set to "now" on create (so the first rotation fires on the
+   * next tick) and recomputed after every attempt.
+   */
+  nextRotationAt: text("next_rotation_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  /** Soft-hide flag — archived rows are skipped by the scheduler + rejected as fork sources. */
+  isArchived: integer("is_archived", { mode: "boolean" }).notNull().default(false),
+  /** ISO-8601 timestamp. */
+  createdAt: text("created_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+  /** ISO-8601 timestamp. */
+  updatedAt: text("updated_at")
+    .notNull()
+    .default(sql`(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`),
+});
+
+/** Row shape for the `rotating_message` table. */
+export type RotatingMessageRow = typeof rotatingMessage.$inferSelect;
+/** Insert shape for the `rotating_message` table. */
+export type RotatingMessageInsert = typeof rotatingMessage.$inferInsert;