@sixb/pg 0.0.1

package/src/agents/messages.ts

@@ -0,0 +1,144 @@
+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 { SqlParameter } from "../pg-client"
+import { isUniqueViolation } from "../storage-errors"
+import { type PgStoreClient, runPgTransaction } from "../transactions"
+import { type AgentMessageRow, queryAgentList, rowToMessageRecord } from "./rows"
+
+export class PgAgentMessageStore implements AgentMessageStore {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async append(input: AppendAgentMessageInput): Promise<AgentMessageRecord> {
+    const createdAt = input.createdAt ?? new Date()
+
+    try {
+      return await runPgTransaction(this.sql, async (tx) => {
+        const [thread] = await tx<{ id: string }[]>`
+          SELECT id FROM agent_threads
+          WHERE project_id = ${input.projectId} AND id = ${input.threadId}
+          FOR UPDATE
+        `
+
+        if (!thread) {
+          throw new AgentStorageError(
+            "thread_not_found",
+            `[SixbPg] Agent thread '${input.threadId}' not found for project '${input.projectId}'.`
+          )
+        }
+
+        if (input.runId !== null) {
+          const [run] = await tx<{ id: string }[]>`
+            SELECT id FROM agent_runs WHERE project_id = ${input.projectId} AND id = ${input.runId}
+          `
+
+          if (!run) {
+            throw new AgentStorageError(
+              "run_not_found",
+              `[SixbPg] Agent run '${input.runId}' not found for project '${input.projectId}'.`
+            )
+          }
+        }
+
+        const [seqRow] = await tx<{ next: number | string }[]>`
+          SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM agent_messages
+          WHERE project_id = ${input.projectId} AND thread_id = ${input.threadId}
+        `
+
+        const [row] = await tx<AgentMessageRow[]>`
+          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 (
+            ${input.projectId},
+            ${input.id},
+            ${input.threadId},
+            ${input.runId},
+            ${input.role},
+            ${input.authorPrincipal?.type ?? null},
+            ${input.authorPrincipal?.id ?? null},
+            ${Number(seqRow.next)},
+            ${JSON.stringify(input.parts)}::text::jsonb,
+            ${input.metadata === undefined ? null : JSON.stringify(input.metadata)}::text::jsonb,
+            ${AGENT_MESSAGE_CONTENT_VERSION},
+            ${createdAt},
+            ${input.completedAt ?? null}
+          )
+          RETURNING *
+        `
+
+        await tx`
+          UPDATE agent_threads
+          SET message_count = message_count + 1, last_message_at = ${createdAt}, updated_at = ${createdAt}
+          WHERE project_id = ${input.projectId} AND id = ${input.threadId}
+        `
+
+        return rowToMessageRecord(row)
+      })
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new AgentStorageError(
+          "duplicate_id",
+          `[SixbPg] Agent message '${input.id}' already exists for project '${input.projectId}'.`
+        )
+      }
+
+      throw error
+    }
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null> {
+    const [row] = await this.sql<AgentMessageRow[]>`
+      SELECT * FROM agent_messages WHERE project_id = ${params.projectId} AND id = ${params.id}
+    `
+
+    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 = $1", "thread_id = $2"]
+    const params: SqlParameter[] = [input.projectId, input.threadId]
+    let index = 3
+
+    if (input.roles) {
+      const placeholders = input.roles.map(() => `$${index++}`)
+      whereClauses.push(`role IN (${placeholders.join(", ")})`)
+      params.push(...input.roles)
+    }
+
+    const dir = input.order === "desc" ? "DESC" : "ASC"
+    const { rows, total, hasMore } = await queryAgentList<AgentMessageRow>({
+      sql: this.sql,
+      table: "agent_messages",
+      whereClauses,
+      params,
+      nextIndex: index,
+      orderBy: `seq ${dir}`,
+      limit: input.limit,
+      offset: input.offset,
+    })
+
+    return { messages: rows.map(rowToMessageRecord), hasMore, total }
+  }
+}

package/src/agents/rows.ts

@@ -0,0 +1,227 @@
+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 { SQLClient, SqlParameter } from "../pg-client"
+
+// ── row shapes (porsager returns timestamptz as Date, jsonb parsed, int as number — typed loosely
+//    to tolerate the string forms some drivers/poolers surface) ──────────────────────────────────
+
+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: Date | string | null
+  message_count: number | string
+  created_at: Date | string
+  updated_at: Date | 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 | string | null
+  usage_output_tokens: number | string | null
+  usage_total_tokens: number | string | null
+  usage_reasoning_tokens: number | string | null
+  usage_cached_input_tokens: number | string | null
+  error: string | null
+  diagnostics: AgentRunDiagnostic[] | string | null
+  attempt: number | string
+  execution_token: string | null
+  execution_queue_lease_expires_at: Date | string | null
+  created_at: Date | string
+  started_at: Date | string | null
+  completed_at: Date | 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 | string
+  parts: AgentMessagePart[] | string
+  metadata: unknown
+  content_version: number | string
+  created_at: Date | string
+  completed_at: Date | 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: Number(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: normalizeDiagnostics(row.diagnostics),
+    attempt: Number(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: Number(row.seq),
+    parts:
+      typeof row.parts === "string" ? (JSON.parse(row.parts) as AgentMessagePart[]) : row.parts,
+    // 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: normalizeMetadata(row.metadata),
+    contentVersion: Number(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: Number(row.usage_input_tokens) }),
+    ...(row.usage_output_tokens === null ? {} : { outputTokens: Number(row.usage_output_tokens) }),
+    ...(row.usage_total_tokens === null ? {} : { totalTokens: Number(row.usage_total_tokens) }),
+    ...(row.usage_reasoning_tokens === null
+      ? {}
+      : { reasoningTokens: Number(row.usage_reasoning_tokens) }),
+    ...(row.usage_cached_input_tokens === null
+      ? {}
+      : { cachedInputTokens: Number(row.usage_cached_input_tokens) }),
+  }
+  return Object.keys(usage).length === 0 ? undefined : usage
+}
+
+function normalizeMetadata(value: unknown): AgentMessageRecord["metadata"] {
+  if (value === null || value === undefined) {
+    return undefined
+  }
+  const parsed = typeof value === "string" ? JSON.parse(value) : value
+  return parsed === null ? undefined : (parsed as AgentMessageRecord["metadata"])
+}
+
+function normalizeDiagnostics(
+  value: AgentRunRow["diagnostics"]
+): readonly AgentRunDiagnostic[] | undefined {
+  if (value === null) {
+    return undefined
+  }
+  return typeof value === "string" ? (JSON.parse(value) as AgentRunDiagnostic[]) : value
+}
+
+// ── offset pagination (threads / messages order by their own column, not started_at) ─────────────
+
+export async function queryAgentList<TRow>(input: {
+  readonly sql: SQLClient
+  readonly table: "agent_threads" | "agent_messages"
+  readonly whereClauses: readonly string[]
+  readonly params: readonly SqlParameter[]
+  readonly nextIndex: number
+  readonly orderBy: string
+  readonly limit?: number
+  readonly offset?: number
+}): Promise<{ readonly rows: readonly TRow[]; readonly total: number; readonly hasMore: boolean }> {
+  const where = `WHERE ${input.whereClauses.join(" AND ")}`
+  const offset = input.offset ?? 0
+
+  const [totalRow] = await input.sql.unsafe<{ count: string | number }[]>(
+    `SELECT COUNT(*)::bigint AS count FROM ${input.table} ${where}`,
+    [...input.params] as SqlParameter[]
+  )
+
+  const queryParams = [...input.params] as SqlParameter[]
+  let query = `SELECT * FROM ${input.table} ${where} ORDER BY ${input.orderBy}`
+  let nextIndex = input.nextIndex
+
+  if (input.limit !== undefined) {
+    query += ` LIMIT $${nextIndex++} OFFSET $${nextIndex++}`
+    queryParams.push(input.limit, offset)
+  } else if (offset > 0) {
+    query += ` OFFSET $${nextIndex++}`
+    queryParams.push(offset)
+  }
+
+  const rows = await input.sql.unsafe<TRow[]>(query, queryParams)
+  const total = Number(totalRow?.count ?? 0)
+  return { rows, total, hasMore: offset + rows.length < total }
+}

package/src/agents/runs.ts

@@ -0,0 +1,330 @@
+import {
+  type AgentRunRecord,
+  type AgentRunStore,
+  AgentStorageError,
+  type ConfirmAgentRunExecutionOwnershipInput,
+  type CreateAgentRunInput,
+  type FinishAgentRunInput,
+  type FinishQueuedAgentRunInput,
+  type ListAgentRunsInput,
+  type ListAgentRunsResult,
+  type ReclaimAgentRunInput,
+  type StartAgentRunInput,
+} from "@sixb/core/storage"
+import type { SQLClient, SqlParameter } from "../pg-client"
+import { appendRunListFilters, hasEmptyStatuses, queryRunList } from "../run-list-query"
+import { isUniqueViolation } from "../storage-errors"
+import { type PgStoreClient, runPgTransaction } from "../transactions"
+import { type AgentRunRow, rowToRunRecord } from "./rows"
+
+const PG_RUN_ID_BATCH_SIZE = 10_000
+
+export class PgAgentRunStore implements AgentRunStore {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async create(input: CreateAgentRunInput): Promise<AgentRunRecord> {
+    const createdAt = input.createdAt ?? new Date()
+
+    try {
+      return await runPgTransaction(this.sql, async (tx) => {
+        const [thread] = await tx<{ active_run_id: string | null }[]>`
+          SELECT active_run_id FROM agent_threads
+          WHERE project_id = ${input.projectId} AND id = ${input.threadId}
+          FOR UPDATE
+        `
+
+        if (!thread) {
+          throw new AgentStorageError(
+            "thread_not_found",
+            `[SixbPg] Agent thread '${input.threadId}' not found for project '${input.projectId}'.`
+          )
+        }
+
+        if (thread.active_run_id !== null) {
+          throw new AgentStorageError(
+            "active_run_exists",
+            `[SixbPg] Agent thread '${input.threadId}' already has an active run '${thread.active_run_id}'.`
+          )
+        }
+
+        const [row] = await tx<AgentRunRow[]>`
+          INSERT INTO agent_runs (
+            project_id,
+            id,
+            thread_id,
+            agent_id,
+            trigger_message_id,
+            requested_by_principal_type,
+            requested_by_principal_id,
+            status,
+            attempt,
+            created_at
+          ) VALUES (
+            ${input.projectId},
+            ${input.id},
+            ${input.threadId},
+            ${input.agentId},
+            ${input.triggerMessageId},
+            ${input.requestedByPrincipal.type},
+            ${input.requestedByPrincipal.id},
+            ${"queued"},
+            ${0},
+            ${createdAt}
+          )
+          RETURNING *
+        `
+
+        await tx`
+          UPDATE agent_threads SET active_run_id = ${input.id}, updated_at = ${createdAt}
+          WHERE project_id = ${input.projectId} AND id = ${input.threadId}
+        `
+
+        return rowToRunRecord(row)
+      })
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new AgentStorageError(
+          "duplicate_id",
+          `[SixbPg] Agent run '${input.id}' already exists for project '${input.projectId}'.`
+        )
+      }
+
+      throw error
+    }
+  }
+
+  async start(input: StartAgentRunInput): Promise<AgentRunRecord> {
+    const startedAt = input.startedAt ?? new Date()
+    return runPgTransaction(this.sql, async (tx) => {
+      await this.lockStatus(tx, input.projectId, input.id, "queued")
+      const [row] = await tx<AgentRunRow[]>`
+        UPDATE agent_runs
+        SET
+          status = ${"running"},
+          execution_principal_type = ${input.executionPrincipal?.type ?? null},
+          execution_principal_id = ${input.executionPrincipal?.id ?? null},
+          model_id = ${input.modelId ?? null},
+          attempt = ${1},
+          execution_token = ${input.execution.token},
+          execution_queue_lease_expires_at = ${input.execution.queueLeaseExpiresAt},
+          started_at = ${startedAt}
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+      return rowToRunRecord(row)
+    })
+  }
+
+  async finishQueued(input: FinishQueuedAgentRunInput): Promise<AgentRunRecord> {
+    const completedAt = input.completedAt ?? new Date()
+    return runPgTransaction(this.sql, async (tx) => {
+      const run = await this.lockStatus(tx, input.projectId, input.id, "queued")
+      const [row] = await tx<AgentRunRow[]>`
+        UPDATE agent_runs
+        SET status = ${input.status}, error = ${input.error ?? null}, completed_at = ${completedAt}
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+      await this.releaseThread(tx, run, completedAt)
+      return rowToRunRecord(row)
+    })
+  }
+
+  async reclaim(input: ReclaimAgentRunInput): Promise<AgentRunRecord> {
+    return runPgTransaction(this.sql, async (tx) => {
+      await this.lockRunning(tx, input.projectId, input.id)
+      const [row] = await tx<AgentRunRow[]>`
+        UPDATE agent_runs
+        SET
+          attempt = attempt + 1,
+          execution_token = ${input.execution.token},
+          execution_queue_lease_expires_at = ${input.execution.queueLeaseExpiresAt}
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+
+      return rowToRunRecord(row)
+    })
+  }
+
+  async confirmExecutionOwnership(
+    input: ConfirmAgentRunExecutionOwnershipInput
+  ): Promise<AgentRunRecord> {
+    return runPgTransaction(this.sql, async (tx) => {
+      const run = await this.lockRunning(tx, input.projectId, input.id)
+      if (run.execution_token !== input.executionToken) {
+        throw new AgentStorageError(
+          "execution_lost",
+          `[SixbPg] Execution token is no longer current on agent run '${input.id}'.`
+        )
+      }
+
+      const [row] = await tx<AgentRunRow[]>`
+        UPDATE agent_runs
+        SET execution_queue_lease_expires_at = GREATEST(
+          execution_queue_lease_expires_at,
+          ${input.queueLeaseExpiresAt}
+        )
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+      return rowToRunRecord(row)
+    })
+  }
+
+  async finish(input: FinishAgentRunInput): Promise<AgentRunRecord> {
+    const completedAt = input.completedAt ?? new Date()
+    const errorValue = input.status === "succeeded" ? null : (input.error ?? null)
+
+    return runPgTransaction(this.sql, async (tx) => {
+      const run = await this.lockRunning(tx, input.projectId, input.id)
+
+      if (run.execution_token !== input.executionToken) {
+        throw new AgentStorageError(
+          "execution_lost",
+          `[SixbPg] Execution token is no longer current on agent run '${input.id}'.`
+        )
+      }
+
+      const [row] = await tx<AgentRunRow[]>`
+        UPDATE agent_runs
+        SET
+          status = ${input.status},
+          model_id = COALESCE(${input.modelId ?? null}, model_id),
+          finish_reason = ${input.finishReason ?? null},
+          usage_input_tokens = ${input.usage?.inputTokens ?? null},
+          usage_output_tokens = ${input.usage?.outputTokens ?? null},
+          usage_total_tokens = ${input.usage?.totalTokens ?? null},
+          usage_reasoning_tokens = ${input.usage?.reasoningTokens ?? null},
+          usage_cached_input_tokens = ${input.usage?.cachedInputTokens ?? null},
+          error = ${errorValue},
+          diagnostics = ${input.diagnostics === undefined ? null : JSON.stringify(input.diagnostics)}::text::jsonb,
+          execution_token = ${null},
+          execution_queue_lease_expires_at = ${null},
+          completed_at = ${completedAt}
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+
+      await this.releaseThread(tx, run, completedAt)
+
+      return rowToRunRecord(row)
+    })
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<AgentRunRecord | null> {
+    const [row] = await this.sql<AgentRunRow[]>`
+      SELECT * FROM agent_runs WHERE project_id = ${params.projectId} AND id = ${params.id}
+    `
+
+    return row ? rowToRunRecord(row) : null
+  }
+
+  async getByIds(params: {
+    projectId: string
+    ids: readonly string[]
+  }): Promise<readonly AgentRunRecord[]> {
+    const ids = [...new Set(params.ids)]
+    if (ids.length === 0) {
+      return []
+    }
+
+    const rows: AgentRunRow[] = []
+    for (let offset = 0; offset < ids.length; offset += PG_RUN_ID_BATCH_SIZE) {
+      const batch = ids.slice(offset, offset + PG_RUN_ID_BATCH_SIZE)
+      const placeholders = batch.map((_, index) => `$${index + 2}`).join(", ")
+      rows.push(
+        ...(await this.sql.unsafe<AgentRunRow[]>(
+          `SELECT * FROM agent_runs WHERE project_id = $1 AND id IN (${placeholders})`,
+          [params.projectId, ...batch] as SqlParameter[]
+        ))
+      )
+    }
+    const byId = new Map(rows.map((row) => [row.id, rowToRunRecord(row)]))
+    return ids.flatMap((id) => {
+      const run = byId.get(id)
+      return run ? [run] : []
+    })
+  }
+
+  async list(input: ListAgentRunsInput): Promise<ListAgentRunsResult> {
+    if (hasEmptyStatuses(input)) {
+      return { runs: [], hasMore: false, total: 0 }
+    }
+
+    const whereClauses = ["project_id = $1"]
+    const params: SqlParameter[] = [input.projectId]
+    let index = 2
+
+    if (input.threadId) {
+      whereClauses.push(`thread_id = $${index++}`)
+      params.push(input.threadId)
+    }
+
+    if (input.agentId) {
+      whereClauses.push(`agent_id = $${index++}`)
+      params.push(input.agentId)
+    }
+
+    index = appendRunListFilters(
+      whereClauses,
+      params,
+      index,
+      input,
+      "COALESCE(started_at, created_at)"
+    )
+
+    const { rows, total, hasMore } = await queryRunList<AgentRunRow>({
+      sql: this.sql,
+      tableName: "agent_runs",
+      whereClauses,
+      params,
+      nextIndex: index,
+      order: input.order,
+      limit: input.limit,
+      offset: input.offset,
+    })
+
+    return { runs: rows.map(rowToRunRecord), hasMore, total }
+  }
+
+  private lockRunning(sql: SQLClient, projectId: string, id: string): Promise<AgentRunRow> {
+    return this.lockStatus(sql, projectId, id, "running")
+  }
+
+  private async lockStatus(
+    sql: SQLClient,
+    projectId: string,
+    id: string,
+    status: AgentRunRecord["status"]
+  ): Promise<AgentRunRow> {
+    const [row] = await sql<AgentRunRow[]>`
+      SELECT * FROM agent_runs
+      WHERE project_id = ${projectId} AND id = ${id}
+      FOR UPDATE
+    `
+
+    if (!row) {
+      throw new AgentStorageError(
+        "run_not_found",
+        `[SixbPg] Agent run '${id}' not found for project '${projectId}'.`
+      )
+    }
+
+    if (row.status !== status) {
+      throw new AgentStorageError(
+        "invalid_state",
+        `[SixbPg] Agent run '${id}' is not ${status} (status '${row.status}').`
+      )
+    }
+
+    return row
+  }
+
+  private async releaseThread(sql: SQLClient, run: AgentRunRow, completedAt: Date): Promise<void> {
+    await sql`
+      UPDATE agent_threads SET active_run_id = ${null}, updated_at = ${completedAt}
+      WHERE project_id = ${run.project_id} AND id = ${run.thread_id} AND active_run_id = ${run.id}
+    `
+  }
+}