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

package/src/persistence/brain_message_repository.ts

@@ -0,0 +1,106 @@
+/**
+ * `BrainMessageRepository` — data-access object for `BrainMessage`.
+ *
+ * Append-only by design: messages get inserted and never updated.
+ * `appendTurn` handles the next-`turn_index` lookup + INSERT in a
+ * single round-trip via `INSERT ... SELECT COALESCE(MAX, -1) + 1`
+ * so concurrent appends on the same thread don't race.
+ *
+ * Reads:
+ *   - `loadForThread(threadId, opts?)` — paginated history,
+ *     ordered by `turn_index ASC`.
+ *   - `countForThread(threadId)` — total turn count, useful for
+ *     pagination UIs.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase needs to be a value import for @inject().
+import { PostgresDatabase, quoteIdent, Repository, type RepositoryScope } from '@strav/database'
+// biome-ignore lint/style/useImportType: EventBus value import for @inject().
+import { EventBus, inject, ulid } from '@strav/kernel'
+import type { ChatUsage, ContentBlock } from '../types.ts'
+import { BrainMessage, type BrainMessageRole } from './brain_message.ts'
+import { brainMessageSchema } from './schema/brain_message_schema.ts'
+
+export interface AppendTurnInput {
+  threadId: string
+  role: BrainMessageRole
+  content: string | ContentBlock[]
+  model?: string
+  usage?: ChatUsage
+  stopReason?: string
+  responseId?: string
+}
+
+export interface LoadMessagesOptions {
+  /** Pagination — defaults to no limit (full history). */
+  limit?: number
+  offset?: number
+}
+
+@inject()
+export class BrainMessageRepository extends Repository<BrainMessage> {
+  static override readonly schema = brainMessageSchema
+  static override readonly model = BrainMessage
+
+  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor for @inject() metadata emission.
+  constructor(db: PostgresDatabase, events: EventBus) {
+    super(db, events)
+  }
+
+  /**
+   * Insert a new turn at the next `turn_index` for the thread. The
+   * `turn_index` is computed in-SQL so two concurrent appends
+   * don't collide — the unique `(thread_id, turn_index)` index on
+   * the table catches any race that slips through.
+   *
+   * Lifecycle: routes through `create()` so `brain_message.created`
+   * events fire. The `turn_index` is filled in by the SELECT side
+   * of an explicit INSERT here rather than `create()` because the
+   * value isn't known client-side.
+   */
+  async appendTurn(input: AppendTurnInput, opts?: RepositoryScope): Promise<BrainMessage> {
+    const table = quoteIdent(brainMessageSchema.name)
+    const sql = `
+      INSERT INTO ${table}
+        ("id", "thread_id", "turn_index", "role", "content",
+         "model", "usage", "stop_reason", "response_id", "created_at")
+      SELECT
+        $1, $2,
+        COALESCE((SELECT MAX("turn_index") FROM ${table} WHERE "thread_id" = $2), -1) + 1,
+        $3, $4::jsonb, $5, $6::jsonb, $7, $8, NOW()
+      RETURNING *
+    `
+    const params = [
+      ulid(),
+      input.threadId,
+      input.role,
+      JSON.stringify(input.content),
+      input.model ?? null,
+      input.usage !== undefined ? JSON.stringify(input.usage) : null,
+      input.stopReason ?? null,
+      input.responseId ?? null,
+    ]
+    const rows = await this.executor(opts).query<Record<string, unknown>>(sql, params)
+    if (rows.length === 0) {
+      throw new Error('BrainMessageRepository.appendTurn: INSERT returned no rows.')
+    }
+    return this.hydrate(rows[0]!)
+  }
+
+  /** Load every turn for a thread, ordered by `turn_index ASC`. */
+  async loadForThread(
+    threadId: string,
+    opts: LoadMessagesOptions = {},
+  ): Promise<BrainMessage[]> {
+    let q = this.query().where('thread_id', threadId).orderBy('turn_index', 'asc')
+    if (opts.limit !== undefined) q = q.limit(opts.limit)
+    if (opts.offset !== undefined) q = q.offset(opts.offset)
+    return q.get()
+  }
+
+  /** Total turn count for a thread — useful for pagination UIs. */
+  async countForThread(threadId: string): Promise<number> {
+    return this.count({ thread_id: threadId } as Partial<BrainMessage>)
+  }
+}
+

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,
+    }))
+  }
+}