@sixb/sqlite 0.0.1

package/src/agents/agent-storage.ts

@@ -0,0 +1,46 @@
+import type { AgentStorage } from "@sixb/core/storage"
+import { installFreshSqliteSchema } from "../migrations"
+import {
+  closeSqliteStoreConnection,
+  openSqliteStoreConnection,
+  type SqliteStoreConnection,
+} from "../transactions"
+import { SqliteAgentMessageStore } from "./messages"
+import { SqliteAgentRunStore } from "./runs"
+import { SqliteAgentThreadStore } from "./threads"
+
+export interface SqliteAgentStorageOptions {
+  /** Path to SQLite database file. Defaults to ':memory:' for in-memory database. */
+  path?: string
+  /** Internal shared connection used by bundled SqliteStorage. */
+  connection?: SqliteStoreConnection
+}
+
+/**
+ * SQLite-backed agent persistence: thread / run / message sub-stores sharing one connection. The
+ * cross-table writes (reserve + finish touch the thread anchor, append bumps thread stats) run in
+ * SQLite transactions; the bundled {@link SqliteStorage} serializes all of them on one connection.
+ */
+export class SqliteAgentStorage implements AgentStorage {
+  readonly threads: SqliteAgentThreadStore
+  readonly runs: SqliteAgentRunStore
+  readonly messages: SqliteAgentMessageStore
+
+  private readonly connection: SqliteStoreConnection
+
+  constructor(options: SqliteAgentStorageOptions = {}) {
+    this.connection = openSqliteStoreConnection(options)
+
+    if (this.connection.installFreshSchema) {
+      installFreshSqliteSchema(this.connection.db)
+    }
+
+    this.threads = new SqliteAgentThreadStore(this.connection.db)
+    this.runs = new SqliteAgentRunStore(this.connection.db)
+    this.messages = new SqliteAgentMessageStore(this.connection.db)
+  }
+
+  close(): void {
+    closeSqliteStoreConnection(this.connection)
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,5 @@
+export type { SqliteAgentStorageOptions } from "./agent-storage"
+export { SqliteAgentStorage } from "./agent-storage"
+export { SqliteAgentMessageStore } from "./messages"
+export { SqliteAgentRunStore } from "./runs"
+export { SqliteAgentThreadStore } from "./threads"

package/src/agents/messages.ts

@@ -0,0 +1,162 @@
+import type { Database } from "bun:sqlite"
+import { AGENT_MESSAGE_CONTENT_VERSION } from "@sixb/core/internal/agents"
+import {
+  type AgentMessageRecord,
+  type AgentMessageStore,
+  AgentStorageError,
+  type AppendAgentMessageInput,
+  type ListAgentMessagesInput,
+  type ListAgentMessagesResult,
+} from "@sixb/core/storage"
+import type { SqliteValue } from "../run-list-query"
+import { isUniqueConstraintError } from "../storage-errors"
+import { type AgentMessageRow, queryAgentList, rowToMessageRecord } from "./rows"
+
+export class SqliteAgentMessageStore implements AgentMessageStore {
+  constructor(private readonly db: Database) {}
+
+  async append(input: AppendAgentMessageInput): Promise<AgentMessageRecord> {
+    const createdAt = input.createdAt ?? new Date()
+
+    return this.db.transaction(() => {
+      const thread = this.db
+        .query("SELECT 1 AS present FROM agent_threads WHERE project_id = ? AND id = ?")
+        .get(input.projectId, input.threadId) as { present: number } | null
+
+      if (!thread) {
+        throw new AgentStorageError(
+          "thread_not_found",
+          `[SixbSqlite] Agent thread '${input.threadId}' not found for project '${input.projectId}'.`
+        )
+      }
+
+      if (input.runId !== null) {
+        const run = this.db
+          .query("SELECT 1 AS present FROM agent_runs WHERE project_id = ? AND id = ?")
+          .get(input.projectId, input.runId) as { present: number } | null
+
+        if (!run) {
+          throw new AgentStorageError(
+            "run_not_found",
+            `[SixbSqlite] Agent run '${input.runId}' not found for project '${input.projectId}'.`
+          )
+        }
+      }
+
+      const seqRow = this.db
+        .query(
+          "SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM agent_messages WHERE project_id = ? AND thread_id = ?"
+        )
+        .get(input.projectId, input.threadId) as { next: number }
+
+      try {
+        this.db
+          .query(
+            `
+            INSERT INTO agent_messages (
+              project_id,
+              id,
+              thread_id,
+              run_id,
+              role,
+              author_principal_type,
+              author_principal_id,
+              seq,
+              parts,
+              metadata,
+              content_version,
+              created_at,
+              completed_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `
+          )
+          .run(
+            input.projectId,
+            input.id,
+            input.threadId,
+            input.runId,
+            input.role,
+            input.authorPrincipal?.type ?? null,
+            input.authorPrincipal?.id ?? null,
+            seqRow.next,
+            JSON.stringify(input.parts),
+            input.metadata === undefined ? null : JSON.stringify(input.metadata),
+            AGENT_MESSAGE_CONTENT_VERSION,
+            createdAt.toISOString(),
+            input.completedAt ? input.completedAt.toISOString() : null
+          )
+      } catch (error) {
+        if (isUniqueConstraintError(error)) {
+          throw new AgentStorageError(
+            "duplicate_id",
+            `[SixbSqlite] Agent message '${input.id}' already exists for project '${input.projectId}'.`
+          )
+        }
+
+        throw error
+      }
+
+      this.db
+        .query(
+          `
+          UPDATE agent_threads
+          SET message_count = message_count + 1, last_message_at = ?, updated_at = ?
+          WHERE project_id = ? AND id = ?
+        `
+        )
+        .run(createdAt.toISOString(), createdAt.toISOString(), input.projectId, input.threadId)
+
+      return this.requireMessage(input.projectId, input.id)
+    })()
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null> {
+    const row = this.db
+      .query("SELECT * FROM agent_messages WHERE project_id = ? AND id = ?")
+      .get(params.projectId, params.id) as AgentMessageRow | null
+
+    return row ? rowToMessageRecord(row) : null
+  }
+
+  async list(input: ListAgentMessagesInput): Promise<ListAgentMessagesResult> {
+    if (input.roles !== undefined && input.roles.length === 0) {
+      return { messages: [], hasMore: false, total: 0 }
+    }
+
+    const whereClauses = ["project_id = ?", "thread_id = ?"]
+    const args: SqliteValue[] = [input.projectId, input.threadId]
+
+    if (input.roles) {
+      whereClauses.push(`role IN (${input.roles.map(() => "?").join(", ")})`)
+      args.push(...input.roles)
+    }
+
+    const dir = input.order === "desc" ? "DESC" : "ASC"
+    const { rows, total, hasMore } = queryAgentList<AgentMessageRow>({
+      db: this.db,
+      table: "agent_messages",
+      whereClauses,
+      args,
+      orderBy: `seq ${dir}`,
+      limit: input.limit,
+      offset: input.offset,
+    })
+
+    return { messages: rows.map(rowToMessageRecord), hasMore, total }
+  }
+
+  private requireMessage(projectId: string, id: string): AgentMessageRecord {
+    const row = this.db
+      .query("SELECT * FROM agent_messages WHERE project_id = ? AND id = ?")
+      .get(projectId, id) as AgentMessageRow | null
+
+    if (!row) {
+      throw new AgentStorageError(
+        "invalid_state",
+        `[SixbSqlite] Failed to load agent message '${id}' for project '${projectId}'.`
+      )
+    }
+
+    return rowToMessageRecord(row)
+  }
+}

package/src/agents/rows.ts

@@ -0,0 +1,205 @@
+import type { Database } from "bun:sqlite"
+import { type AgentMessagePart, type Principal, SYSTEM_PRINCIPAL } from "@sixb/core"
+import {
+  type AgentMessageRecord,
+  type AgentRunDiagnostic,
+  type AgentRunRecord,
+  type AgentRunUsage,
+  type AgentThreadRecord,
+  coerceAgentRunFinishReason,
+} from "@sixb/core/storage"
+import type { SqliteValue } from "../run-list-query"
+
+// ── row shapes (snake_case, as stored) ──────────────────────────────────────────────────────────
+
+export interface AgentThreadRow {
+  project_id: string
+  id: string
+  agent_id: string
+  owner_principal_type: Principal["type"]
+  owner_principal_id: string
+  title: string | null
+  status: AgentThreadRecord["status"]
+  active_run_id: string | null
+  last_message_at: string | null
+  message_count: number
+  created_at: string
+  updated_at: string
+}
+
+export interface AgentRunRow {
+  project_id: string
+  id: string
+  thread_id: string
+  agent_id: string
+  trigger_message_id: string
+  requested_by_principal_type: Principal["type"] | null
+  requested_by_principal_id: string | null
+  execution_principal_type: "serviceAccount" | null
+  execution_principal_id: string | null
+  status: AgentRunRecord["status"]
+  model_id: string | null
+  finish_reason: string | null
+  usage_input_tokens: number | null
+  usage_output_tokens: number | null
+  usage_total_tokens: number | null
+  usage_reasoning_tokens: number | null
+  usage_cached_input_tokens: number | null
+  error: string | null
+  diagnostics: string | null
+  attempt: number
+  execution_token: string | null
+  execution_queue_lease_expires_at: string | null
+  created_at: string
+  started_at: string | null
+  completed_at: string | null
+}
+
+export interface AgentMessageRow {
+  project_id: string
+  id: string
+  thread_id: string
+  run_id: string | null
+  role: AgentMessageRecord["role"]
+  author_principal_type: Principal["type"] | null
+  author_principal_id: string | null
+  seq: number
+  parts: string
+  metadata: string | null
+  content_version: number
+  created_at: string
+  completed_at: string | null
+}
+
+// ── row → record mappers ────────────────────────────────────────────────────────────────────────
+
+export function rowToThreadRecord(row: AgentThreadRow): AgentThreadRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    agentId: row.agent_id,
+    ownerPrincipal: { type: row.owner_principal_type, id: row.owner_principal_id },
+    title: row.title ?? undefined,
+    status: row.status,
+    activeRunId: row.active_run_id,
+    lastMessageAt: row.last_message_at ? new Date(row.last_message_at) : undefined,
+    messageCount: row.message_count,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  }
+}
+
+export function rowToRunRecord(row: AgentRunRow): AgentRunRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    threadId: row.thread_id,
+    agentId: row.agent_id,
+    triggerMessageId: row.trigger_message_id,
+    requestedByPrincipal:
+      principalFromColumns(row.requested_by_principal_type, row.requested_by_principal_id) ??
+      SYSTEM_PRINCIPAL,
+    executionPrincipal: serviceAccountPrincipalFromColumns(
+      row.execution_principal_type,
+      row.execution_principal_id
+    ),
+    status: row.status,
+    modelId: row.model_id ?? undefined,
+    finishReason: coerceAgentRunFinishReason(row.finish_reason),
+    usage: rowToUsage(row),
+    error: row.error ?? undefined,
+    diagnostics:
+      row.diagnostics === null ? undefined : (JSON.parse(row.diagnostics) as AgentRunDiagnostic[]),
+    attempt: row.attempt,
+    execution:
+      row.execution_token && row.execution_queue_lease_expires_at
+        ? {
+            token: row.execution_token,
+            queueLeaseExpiresAt: new Date(row.execution_queue_lease_expires_at),
+          }
+        : undefined,
+    createdAt: new Date(row.created_at),
+    startedAt: row.started_at ? new Date(row.started_at) : undefined,
+    completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
+  }
+}
+
+export function rowToMessageRecord(row: AgentMessageRow): AgentMessageRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    threadId: row.thread_id,
+    runId: row.run_id,
+    role: row.role,
+    authorPrincipal: principalFromColumns(row.author_principal_type, row.author_principal_id),
+    seq: row.seq,
+    parts: JSON.parse(row.parts) as AgentMessagePart[],
+    // A null/absent column and an explicit JSON `null` both mean "no metadata" (jsonb cannot tell
+    // SQL NULL from a json null on read, so both backends normalise to `undefined` for parity).
+    metadata: row.metadata === null ? undefined : (JSON.parse(row.metadata) ?? undefined),
+    contentVersion: row.content_version,
+    createdAt: new Date(row.created_at),
+    completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
+  }
+}
+
+function principalFromColumns(
+  type: Principal["type"] | null | undefined,
+  id: string | null | undefined
+): Principal | undefined {
+  return type && id ? { type, id } : undefined
+}
+
+function serviceAccountPrincipalFromColumns(
+  type: "serviceAccount" | null | undefined,
+  id: string | null | undefined
+): Extract<Principal, { readonly type: "serviceAccount" }> | undefined {
+  return type === "serviceAccount" && id ? { type, id } : undefined
+}
+
+function rowToUsage(row: AgentRunRow): AgentRunUsage | undefined {
+  const usage: AgentRunUsage = {
+    ...(row.usage_input_tokens === null ? {} : { inputTokens: row.usage_input_tokens }),
+    ...(row.usage_output_tokens === null ? {} : { outputTokens: row.usage_output_tokens }),
+    ...(row.usage_total_tokens === null ? {} : { totalTokens: row.usage_total_tokens }),
+    ...(row.usage_reasoning_tokens === null ? {} : { reasoningTokens: row.usage_reasoning_tokens }),
+    ...(row.usage_cached_input_tokens === null
+      ? {}
+      : { cachedInputTokens: row.usage_cached_input_tokens }),
+  }
+  return Object.keys(usage).length === 0 ? undefined : usage
+}
+
+// ── offset pagination (threads / messages order by their own column, not started_at) ─────────────
+
+export function queryAgentList<TRow>(input: {
+  readonly db: Database
+  readonly table: "agent_threads" | "agent_messages"
+  readonly whereClauses: readonly string[]
+  readonly args: readonly SqliteValue[]
+  readonly orderBy: string
+  readonly limit?: number
+  readonly offset?: number
+}): { readonly rows: readonly TRow[]; readonly total: number; readonly hasMore: boolean } {
+  const where = `WHERE ${input.whereClauses.join(" AND ")}`
+  const offset = input.offset ?? 0
+
+  const totalRow = input.db
+    .query(`SELECT COUNT(*) AS count FROM ${input.table} ${where}`)
+    .get(...input.args) as { count: number }
+
+  let query = `SELECT * FROM ${input.table} ${where} ORDER BY ${input.orderBy}`
+  const queryArgs = [...input.args]
+
+  if (input.limit !== undefined) {
+    query += " LIMIT ? OFFSET ?"
+    queryArgs.push(input.limit, offset)
+  } else if (offset > 0) {
+    query += " LIMIT -1 OFFSET ?"
+    queryArgs.push(offset)
+  }
+
+  const rows = input.db.query(query).all(...queryArgs) as TRow[]
+  const total = totalRow.count
+  return { rows, total, hasMore: offset + rows.length < total }
+}