@strav/brain 1.0.0-alpha.16 → 1.0.0-alpha.18

package/src/persistence/brain_store.ts

@@ -0,0 +1,166 @@
+/**
+ * `BrainStore` — the storage abstraction for `@strav/brain`
+ * conversation state.
+ *
+ * Apps call into `BrainStore` to persist threads, append turns,
+ * and track human-in-the-loop suspended runs. The default
+ * implementation (`DatabaseBrainStore`) is backed by the three
+ * shipped schemas + repositories against Postgres. Apps that want
+ * a different backend (Redis / Mongo / in-memory for tests)
+ * implement this interface directly — the schemas + repositories
+ * stay optional.
+ *
+ * Multitenancy: `BrainStore` itself is tenant-agnostic. Tenant
+ * scoping is the caller's responsibility — wrap calls in
+ * `tenants.withTenant(...)` and the backend (RLS, app-level
+ * filters, separate keyspaces) does its thing.
+ *
+ * Integration with `Thread`: this abstraction is intentionally
+ * parallel to `Thread`. Apps don't call `Thread.send()` and
+ * `store.appendTurn()` simultaneously by default — pick the side
+ * that fits the request lifecycle:
+ *
+ *   - **Stateless request handlers** (one request = one turn):
+ *     load the thread state via `store.loadThread(id)`, build a
+ *     fresh `Thread` from it, call `thread.send(text)`, persist
+ *     the user + assistant turns via `store.appendTurn(...)`,
+ *     return the response. The `Thread` instance dies with the
+ *     request.
+ *
+ *   - **Long-lived workers** (e.g., chat-streaming connections):
+ *     keep the `Thread` in memory for the connection's lifetime
+ *     and call `store.appendTurn(...)` after each `send()`.
+ */
+
+import type { SuspendedState } from '../suspended_run.ts'
+import type {
+  ChatOptions,
+  ChatUsage,
+  ContentBlock,
+  SystemPrompt,
+  ToolUseBlock,
+} from '../types.ts'
+
+// ─── Thread inputs / outputs ─────────────────────────────────────────────
+
+export interface CreateThreadInput {
+  /** App-defined owner. Optional — anonymous / shared threads are fine. */
+  userId?: string
+  /** Human label. Apps set it from the first user turn or via a "rename" UI. */
+  title?: string
+  /** Thread-owned system prompt — applied on every `send()`. */
+  system?: SystemPrompt
+  /** Per-thread defaults merged with per-call options on every `send()`. */
+  options?: ChatOptions
+}
+
+/**
+ * What `loadThread(id)` returns. `state` is the shape `Thread.fromJSON`
+ * accepts directly; metadata fields surface alongside for app code
+ * that wants the row's bookkeeping (timestamps, title, user id) too.
+ */
+export interface LoadedThread {
+  id: string
+  state: {
+    messages: Array<{ role: 'user' | 'assistant'; content: string | ContentBlock[] }>
+    system?: SystemPrompt
+    options?: ChatOptions
+    lastResponseId?: string
+  }
+  metadata: {
+    userId: string | null
+    title: string | null
+    createdAt: Date
+    updatedAt: Date
+  }
+}
+
+export interface TurnInput {
+  role: 'user' | 'assistant'
+  content: string | ContentBlock[]
+  /** Model used for assistant turns. Omitted for user turns. */
+  model?: string
+  /** Token usage from the model call. Assistant turns only. */
+  usage?: ChatUsage
+  /** Provider terminal reason — `end_turn`, `max_iterations`, etc. */
+  stopReason?: string
+  /**
+   * Provider response id when surfaced — OpenAI Responses API today.
+   * Also bumps `last_response_id` on the parent thread so subsequent
+   * sends auto-thread it via `previousResponseId`.
+   */
+  responseId?: string
+}
+
+export interface ThreadFilter {
+  userId?: string
+  limit?: number
+  offset?: number
+}
+
+export interface ThreadSummary {
+  id: string
+  userId: string | null
+  title: string | null
+  lastResponseId: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+// ─── Suspended-run inputs / outputs ──────────────────────────────────────
+
+export interface SaveSuspendedRunInput {
+  /** Optional link to the thread the run came from. */
+  threadId?: string
+  /** App-defined approver. */
+  userId?: string
+  pendingToolCalls: ToolUseBlock[]
+  state: SuspendedState
+}
+
+export interface LoadedSuspendedRun {
+  id: string
+  threadId: string | null
+  userId: string | null
+  pendingToolCalls: ToolUseBlock[]
+  state: SuspendedState
+  status: 'pending' | 'resumed' | 'cancelled'
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface SuspendedFilter {
+  userId?: string
+  threadId?: string
+  limit?: number
+  offset?: number
+}
+
+export interface SuspendedSummary {
+  id: string
+  threadId: string | null
+  userId: string | null
+  status: 'pending' | 'resumed' | 'cancelled'
+  createdAt: Date
+}
+
+// ─── The interface ───────────────────────────────────────────────────────
+
+export interface BrainStore {
+  // ── Threads ───────────────────────────────────────────────────────────
+  createThread(input: CreateThreadInput): Promise<{ id: string }>
+  loadThread(id: string): Promise<LoadedThread | null>
+  appendTurn(threadId: string, turn: TurnInput): Promise<void>
+  updateThreadResponseId(threadId: string, responseId: string): Promise<void>
+  listThreads(filter: ThreadFilter): Promise<ThreadSummary[]>
+  deleteThread(id: string): Promise<void>
+
+  // ── Suspended runs ────────────────────────────────────────────────────
+  saveSuspendedRun(run: SaveSuspendedRunInput): Promise<{ id: string }>
+  loadSuspendedRun(id: string): Promise<LoadedSuspendedRun | null>
+  markSuspendedRunStatus(
+    id: string,
+    status: 'resumed' | 'cancelled',
+  ): Promise<void>
+  listPendingSuspendedRuns(filter: SuspendedFilter): Promise<SuspendedSummary[]>
+}

package/src/persistence/brain_suspended_run.ts

@@ -0,0 +1,30 @@
+/**
+ * `BrainSuspendedRun` — the typed row of `brain_suspended_run`.
+ *
+ * `pending_tool_calls` and `state` round-trip the framework's
+ * `SuspendedRun` shape verbatim — apps load this row, take the
+ * model's `pending_tool_calls`, gather human approvals, and call
+ * `brain.resumeTools(state, results, tools, options)` with the
+ * `state` field unchanged.
+ */
+
+import { Model } from '@strav/database'
+import type { SuspendedState } from '../suspended_run.ts'
+import type { ToolUseBlock } from '../types.ts'
+import { brainSuspendedRunSchema } from './schema/brain_suspended_run_schema.ts'
+
+export type BrainSuspendedRunStatus = 'pending' | 'resumed' | 'cancelled'
+
+export class BrainSuspendedRun extends Model {
+  static override readonly schema = brainSuspendedRunSchema
+
+  id!: string
+  tenant_id!: string
+  thread_id!: string | null
+  user_id!: string | null
+  pending_tool_calls!: ToolUseBlock[]
+  state!: SuspendedState
+  status!: BrainSuspendedRunStatus
+  created_at!: Date
+  updated_at!: Date
+}

package/src/persistence/brain_suspended_run_repository.ts

@@ -0,0 +1,68 @@
+/**
+ * `BrainSuspendedRunRepository` — data-access for paused agentic
+ * runs.
+ *
+ * Adds two domain helpers on top of generic CRUD:
+ *
+ *   - `markResumed(id)` / `markCancelled(id)` — flip the status
+ *     enum once the human approval has been processed. Apps can
+ *     filter `listPending(...)` on `status = 'pending'` to see
+ *     what's still waiting.
+ *   - `listPending(filter?)` — paginate pending runs, optionally
+ *     filtered by `user_id` or `thread_id`.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject().
+import { PostgresDatabase, Repository } from '@strav/database'
+// biome-ignore lint/style/useImportType: EventBus value import for @inject().
+import { EventBus, inject } from '@strav/kernel'
+import { BrainSuspendedRun, type BrainSuspendedRunStatus } from './brain_suspended_run.ts'
+import { brainSuspendedRunSchema } from './schema/brain_suspended_run_schema.ts'
+
+export interface ListPendingOptions {
+  /** Filter by app-defined user — useful when an app has per-user approval queues. */
+  userId?: string
+  /** Filter by the linked thread (when set). */
+  threadId?: string
+  /** Pagination — defaults to 50. */
+  limit?: number
+  offset?: number
+}
+
+@inject()
+export class BrainSuspendedRunRepository extends Repository<BrainSuspendedRun> {
+  static override readonly schema = brainSuspendedRunSchema
+  static override readonly model = BrainSuspendedRun
+
+  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor for @inject() metadata emission.
+  constructor(db: PostgresDatabase, events: EventBus) {
+    super(db, events)
+  }
+
+  /** Flip status to `resumed` after `brain.resumeTools(state, ...)` succeeds. */
+  async markResumed(run: BrainSuspendedRun): Promise<BrainSuspendedRun> {
+    return this.markStatus(run, 'resumed')
+  }
+
+  /** Flip status to `cancelled` when the human approver declined the run. */
+  async markCancelled(run: BrainSuspendedRun): Promise<BrainSuspendedRun> {
+    return this.markStatus(run, 'cancelled')
+  }
+
+  /** List pending runs, newest-first by default. */
+  async listPending(opts: ListPendingOptions = {}): Promise<BrainSuspendedRun[]> {
+    let q = this.query().where('status', 'pending')
+    if (opts.userId !== undefined) q = q.where('user_id', opts.userId)
+    if (opts.threadId !== undefined) q = q.where('thread_id', opts.threadId)
+    q = q.orderBy('created_at', 'desc').limit(opts.limit ?? 50)
+    if (opts.offset !== undefined) q = q.offset(opts.offset)
+    return q.get()
+  }
+
+  private markStatus(
+    run: BrainSuspendedRun,
+    status: BrainSuspendedRunStatus,
+  ): Promise<BrainSuspendedRun> {
+    return this.update(run, { status } as Partial<BrainSuspendedRun>)
+  }
+}

package/src/persistence/brain_thread.ts

@@ -0,0 +1,30 @@
+/**
+ * `BrainThread` — the typed row of `brain_thread`. One per
+ * conversation.
+ *
+ * The model's `system` / `options` / `last_response_id` columns
+ * mirror `ThreadState` so apps that hydrate a thread can rebuild a
+ * `Thread` instance via `BrainStore.loadThread(...)`.
+ *
+ * `user_id` is app-defined — the framework doesn't constrain user
+ * shapes. Apps that want FK enforcement add it in a follow-up
+ * migration (same pattern as `@strav/auth`'s `session.user_id`).
+ */
+
+import { Model } from '@strav/database'
+import type { ChatOptions, SystemPrompt } from '../types.ts'
+import { brainThreadSchema } from './schema/brain_thread_schema.ts'
+
+export class BrainThread extends Model {
+  static override readonly schema = brainThreadSchema
+
+  id!: string
+  tenant_id!: string
+  user_id!: string | null
+  title!: string | null
+  system!: SystemPrompt | null
+  options!: ChatOptions | null
+  last_response_id!: string | null
+  created_at!: Date
+  updated_at!: Date
+}

package/src/persistence/brain_thread_repository.ts

@@ -0,0 +1,65 @@
+/**
+ * `BrainThreadRepository` — data-access object for `BrainThread`.
+ *
+ * Adds thread-specific helpers on top of the generic CRUD surface:
+ *
+ *   - `listForUser(userId, opts?)` — paginate threads for a user,
+ *     ordered by `updated_at DESC` (most-recently-active first).
+ *   - `updateResponseId(thread, id)` — small helper that wraps the
+ *     `update()` call apps make when threading
+ *     `previousResponseId` forward.
+ *
+ * Multitenancy: every query auto-scopes to the current tenant via
+ * RLS when wrapped in `tenants.withTenant(...)`. No tenant filter
+ * shows up in this code — the database enforces isolation.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase needs to be a value import — the @inject() decorator below resolves the constructor param via reflect-metadata, which requires the runtime class reference.
+import { PostgresDatabase, Repository } from '@strav/database'
+// biome-ignore lint/style/useImportType: EventBus has the same constraint as PostgresDatabase.
+import { EventBus, inject } from '@strav/kernel'
+import { BrainThread } from './brain_thread.ts'
+import { brainThreadSchema } from './schema/brain_thread_schema.ts'
+
+export interface ListThreadsOptions {
+  /** Pagination — defaults to 50. */
+  limit?: number
+  offset?: number
+}
+
+@inject()
+export class BrainThreadRepository extends Repository<BrainThread> {
+  static override readonly schema = brainThreadSchema
+  static override readonly model = BrainThread
+
+  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TypeScript to emit `design:paramtypes` metadata on the subclass for the @inject() decorator above.
+  constructor(db: PostgresDatabase, events: EventBus) {
+    super(db, events)
+  }
+
+  /**
+   * List threads for a given app-defined user, newest-first. Empty
+   * `userId` lists every thread visible under RLS — useful for
+   * admin views or tenant-wide audits.
+   */
+  async listForUser(
+    userId: string | null,
+    opts: ListThreadsOptions = {},
+  ): Promise<BrainThread[]> {
+    let q = this.query()
+    if (userId !== null) q = q.where('user_id', userId)
+    q = q.orderBy('updated_at', 'desc').limit(opts.limit ?? 50)
+    if (opts.offset !== undefined) q = q.offset(opts.offset)
+    return q.get()
+  }
+
+  /**
+   * Update a thread's `last_response_id`. Wraps `update()` so the
+   * standard `updated_at` bump + repository lifecycle events still
+   * fire — apps that watch `brain_thread.updated` see the
+   * transition.
+   */
+  async updateResponseId(thread: BrainThread, responseId: string): Promise<BrainThread> {
+    return this.update(thread, { last_response_id: responseId } as Partial<BrainThread>)
+  }
+}

package/src/persistence/database_brain_store.ts

@@ -0,0 +1,190 @@
+/**
+ * `DatabaseBrainStore` — Postgres-backed implementation of
+ * `BrainStore`. Composes the three shipped repositories
+ * (`BrainThreadRepository`, `BrainMessageRepository`,
+ * `BrainSuspendedRunRepository`) into a single store surface.
+ *
+ * All multitenancy is transparent here — the repositories scope
+ * via RLS when the call is wrapped in `tenants.withTenant(...)`.
+ * Apps wire this once via `app.resolve(DatabaseBrainStore)` and
+ * inject it where conversations need to be persisted.
+ *
+ * Apps that need a different backend implement `BrainStore`
+ * directly against Redis / Mongo / in-memory / etc. — the
+ * schemas + repositories are framework conveniences, not
+ * obligations.
+ */
+
+// biome-ignore lint/style/useImportType: classes are value imports for @inject() param-type metadata.
+import { inject } from '@strav/kernel'
+// biome-ignore lint/style/useImportType: repository classes value imports for @inject().
+import { BrainMessageRepository } from './brain_message_repository.ts'
+// biome-ignore lint/style/useImportType: repository classes value imports for @inject().
+import { BrainSuspendedRunRepository } from './brain_suspended_run_repository.ts'
+// biome-ignore lint/style/useImportType: repository classes value imports for @inject().
+import { BrainThreadRepository } from './brain_thread_repository.ts'
+import type {
+  BrainStore,
+  CreateThreadInput,
+  LoadedSuspendedRun,
+  LoadedThread,
+  SaveSuspendedRunInput,
+  SuspendedFilter,
+  SuspendedSummary,
+  ThreadFilter,
+  ThreadSummary,
+  TurnInput,
+} from './brain_store.ts'
+
+@inject()
+export class DatabaseBrainStore implements BrainStore {
+  constructor(
+    private readonly threads: BrainThreadRepository,
+    private readonly messages: BrainMessageRepository,
+    private readonly suspendedRuns: BrainSuspendedRunRepository,
+  ) {}
+
+  // ── Threads ────────────────────────────────────────────────────────────
+
+  async createThread(input: CreateThreadInput): Promise<{ id: string }> {
+    const created = await this.threads.create({
+      user_id: input.userId ?? null,
+      title: input.title ?? null,
+      system: input.system ?? null,
+      options: input.options ?? null,
+      last_response_id: null,
+    })
+    return { id: created.id }
+  }
+
+  async loadThread(id: string): Promise<LoadedThread | null> {
+    const thread = await this.threads.find(id)
+    if (!thread) return null
+    const rows = await this.messages.loadForThread(id)
+    const result: LoadedThread = {
+      id: thread.id,
+      state: {
+        messages: rows.map((m) => ({ role: m.role, content: m.content })),
+      },
+      metadata: {
+        userId: thread.user_id,
+        title: thread.title,
+        createdAt: thread.created_at,
+        updatedAt: thread.updated_at,
+      },
+    }
+    if (thread.system !== null) result.state.system = thread.system
+    if (thread.options !== null) result.state.options = thread.options
+    if (thread.last_response_id !== null) {
+      result.state.lastResponseId = thread.last_response_id
+    }
+    return result
+  }
+
+  async appendTurn(threadId: string, turn: TurnInput): Promise<void> {
+    await this.messages.appendTurn({
+      threadId,
+      role: turn.role,
+      content: turn.content,
+      ...(turn.model !== undefined ? { model: turn.model } : {}),
+      ...(turn.usage !== undefined ? { usage: turn.usage } : {}),
+      ...(turn.stopReason !== undefined ? { stopReason: turn.stopReason } : {}),
+      ...(turn.responseId !== undefined ? { responseId: turn.responseId } : {}),
+    })
+    // When the model surfaced a new response id, also bump the
+    // thread-level pointer so subsequent loads + sends thread it via
+    // `previousResponseId` automatically.
+    if (turn.responseId !== undefined) {
+      const thread = await this.threads.find(threadId)
+      if (thread) {
+        await this.threads.updateResponseId(thread, turn.responseId)
+      }
+    }
+  }
+
+  async updateThreadResponseId(threadId: string, responseId: string): Promise<void> {
+    const thread = await this.threads.find(threadId)
+    if (!thread) return
+    await this.threads.updateResponseId(thread, responseId)
+  }
+
+  async listThreads(filter: ThreadFilter): Promise<ThreadSummary[]> {
+    const list = await this.threads.listForUser(filter.userId ?? null, {
+      ...(filter.limit !== undefined ? { limit: filter.limit } : {}),
+      ...(filter.offset !== undefined ? { offset: filter.offset } : {}),
+    })
+    return list.map((t) => ({
+      id: t.id,
+      userId: t.user_id,
+      title: t.title,
+      lastResponseId: t.last_response_id,
+      createdAt: t.created_at,
+      updatedAt: t.updated_at,
+    }))
+  }
+
+  async deleteThread(id: string): Promise<void> {
+    const thread = await this.threads.find(id)
+    if (!thread) return
+    await this.threads.delete(thread)
+  }
+
+  // ── Suspended runs ─────────────────────────────────────────────────────
+
+  async saveSuspendedRun(input: SaveSuspendedRunInput): Promise<{ id: string }> {
+    const created = await this.suspendedRuns.create({
+      thread_id: input.threadId ?? null,
+      user_id: input.userId ?? null,
+      pending_tool_calls: input.pendingToolCalls,
+      state: input.state,
+      status: 'pending',
+    })
+    return { id: created.id }
+  }
+
+  async loadSuspendedRun(id: string): Promise<LoadedSuspendedRun | null> {
+    const row = await this.suspendedRuns.find(id)
+    if (!row) return null
+    return {
+      id: row.id,
+      threadId: row.thread_id,
+      userId: row.user_id,
+      pendingToolCalls: row.pending_tool_calls,
+      state: row.state,
+      status: row.status,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    }
+  }
+
+  async markSuspendedRunStatus(
+    id: string,
+    status: 'resumed' | 'cancelled',
+  ): Promise<void> {
+    const row = await this.suspendedRuns.find(id)
+    if (!row) return
+    if (status === 'resumed') {
+      await this.suspendedRuns.markResumed(row)
+    } else {
+      await this.suspendedRuns.markCancelled(row)
+    }
+  }
+
+  async listPendingSuspendedRuns(
+    filter: SuspendedFilter,
+  ): Promise<SuspendedSummary[]> {
+    const rows = await this.suspendedRuns.listPending({
+      ...(filter.userId !== undefined ? { userId: filter.userId } : {}),
+      ...(filter.threadId !== undefined ? { threadId: filter.threadId } : {}),
+      ...(filter.limit !== undefined ? { limit: filter.limit } : {}),
+      ...(filter.offset !== undefined ? { offset: filter.offset } : {}),
+    })
+    return rows.map((r) => ({
+      id: r.id,
+      threadId: r.thread_id,
+      userId: r.user_id,
+      status: r.status,
+      createdAt: r.created_at,
+    }))
+  }
+}

package/src/persistence/index.ts

@@ -0,0 +1,48 @@
+// Public API of `@strav/brain/persistence` — recommended schema +
+// repositories for persisting conversations (threads + turns) and
+// human-in-the-loop suspended runs to Postgres via `@strav/database`.
+//
+// Apps that need a different backend implement `BrainStore`
+// directly — the schemas + repositories are conveniences, not
+// obligations.
+
+export {
+  BrainMessage,
+  type BrainMessageRole,
+} from './brain_message.ts'
+export {
+  type AppendTurnInput,
+  BrainMessageRepository,
+  type LoadMessagesOptions,
+} from './brain_message_repository.ts'
+export type {
+  BrainStore,
+  CreateThreadInput,
+  LoadedSuspendedRun,
+  LoadedThread,
+  SaveSuspendedRunInput,
+  SuspendedFilter,
+  SuspendedSummary,
+  ThreadFilter,
+  ThreadSummary,
+  TurnInput,
+} from './brain_store.ts'
+export {
+  BrainSuspendedRun,
+  type BrainSuspendedRunStatus,
+} from './brain_suspended_run.ts'
+export {
+  type ListPendingOptions,
+  BrainSuspendedRunRepository,
+} from './brain_suspended_run_repository.ts'
+export { BrainThread } from './brain_thread.ts'
+export {
+  BrainThreadRepository,
+  type ListThreadsOptions,
+} from './brain_thread_repository.ts'
+export { DatabaseBrainStore } from './database_brain_store.ts'
+export {
+  brainMessageSchema,
+  brainSuspendedRunSchema,
+  brainThreadSchema,
+} from './schema/index.ts'

package/src/persistence/schema/brain_message_schema.ts

@@ -0,0 +1,61 @@
+/**
+ * `brainMessageSchema` — one row per assistant or user turn within
+ * a thread. Append-only; rows are inserted in `turn_index` order
+ * and never updated (compaction blocks live as a regular assistant
+ * row whose `content` includes a `CompactionBlock`).
+ *
+ * Why per-turn rather than a JSONB blob on `brain_thread`:
+ *
+ *   - **Pagination.** UIs render the latest N turns; queries select
+ *     by `(thread_id, turn_index)` instead of parsing a JSON array.
+ *   - **Per-turn metadata.** `model` / `usage` / `stop_reason` /
+ *     `response_id` are indexed and queryable for cost analytics,
+ *     audit, and routing (e.g., "which threads used gpt-5?").
+ *   - **Append cost.** Each `send()` is a single INSERT, not a
+ *     rewrite of the entire array.
+ *
+ * Columns:
+ *
+ *   - `id`           ULID primary key.
+ *   - `thread_id`    FK → `brain_thread`. `onDelete: cascade` —
+ *                    deleting a thread drops its history.
+ *   - `turn_index`   0-based ordinal. Unique with `thread_id` (app
+ *                    migration adds the index).
+ *   - `role`         `user` or `assistant`. The framework's
+ *                    `Message.role` union; tool_result blocks land
+ *                    on user turns per the assistant ↔ user
+ *                    handshake, so `role` reflects that.
+ *   - `content`      JSONB — `string | ContentBlock[]`. Carries
+ *                    every typed block: text, image, document,
+ *                    audio, tool_use, tool_result, mcp_*, compaction.
+ *   - `model`        Model identifier used for assistant turns
+ *                    (NULL for user turns).
+ *   - `usage`        JSONB — `ChatUsage` for assistant turns.
+ *   - `stop_reason`  Provider terminal reason (`end_turn`, etc.).
+ *   - `response_id`  OpenAI Responses API id when surfaced. Indexed
+ *                    via partial index in the recommended migration.
+ *   - `created_at`   Timestamp.
+ *
+ * Archetype.Event — append-only semantics; no `updated_at`.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+import { brainThreadSchema } from './brain_thread_schema.ts'
+
+export const brainMessageSchema = defineSchema(
+  'brain_message',
+  Archetype.Event,
+  (t) => {
+    t.id()
+    t.reference('thread_id').to(brainThreadSchema).onDelete('cascade').notNull()
+    t.integer('turn_index').notNull()
+    t.enum('role', ['user', 'assistant']).notNull()
+    t.json('content').notNull()
+    t.string('model').max(128).nullable()
+    t.json('usage').nullable()
+    t.string('stop_reason').max(64).nullable()
+    t.string('response_id').max(128).nullable()
+    t.timestamp('created_at').notNull()
+  },
+  { tenanted: true },
+)