bopodev-db 0.1.23 → 0.1.25

package/src/repositories.ts

@@ -4,12 +4,14 @@ import type { BopoDb } from "./client";
 import {
   activityLogs,
   agents,
+  attentionInboxStates,
   approvalInboxStates,
   approvalRequests,
   auditEvents,
   companies,
   costLedger,
   goals,
+  heartbeatRunQueue,
   heartbeatRuns,
   heartbeatRunMessages,
   issueAttachments,
@@ -134,6 +136,9 @@ export async function createProject(
     description?: string | null;
     status?: "planned" | "active" | "paused" | "blocked" | "completed" | "archived";
     plannedStartAt?: Date | null;
+    monthlyBudgetUsd?: string;
+    usedBudgetUsd?: string;
+    budgetWindowStartAt?: Date | null;
     executionWorkspacePolicy?: Record<string, unknown> | null;
     workspaceLocalPath?: string | null;
     workspaceGithubRepo?: string | null;
@@ -147,6 +152,9 @@ export async function createProject(
     description: input.description ?? null,
     status: input.status ?? "planned",
     plannedStartAt: input.plannedStartAt ?? null,
+    monthlyBudgetUsd: input.monthlyBudgetUsd ?? "100.0000",
+    usedBudgetUsd: input.usedBudgetUsd ?? "0.0000",
+    budgetWindowStartAt: input.budgetWindowStartAt ?? new Date(),
     executionWorkspacePolicy: input.executionWorkspacePolicy ? JSON.stringify(input.executionWorkspacePolicy) : null
   });
   const legacyWorkspaceLocalPath = input.workspaceLocalPath?.trim();
@@ -173,6 +181,9 @@ export async function updateProject(
     description?: string | null;
     status?: "planned" | "active" | "paused" | "blocked" | "completed" | "archived";
     plannedStartAt?: Date | null;
+    monthlyBudgetUsd?: string;
+    usedBudgetUsd?: string;
+    budgetWindowStartAt?: Date | null;
     executionWorkspacePolicy?: Record<string, unknown> | null;
     workspaceLocalPath?: string | null;
     workspaceGithubRepo?: string | null;
@@ -186,6 +197,9 @@ export async function updateProject(
         description: input.description,
         status: input.status,
         plannedStartAt: input.plannedStartAt,
+        monthlyBudgetUsd: input.monthlyBudgetUsd,
+        usedBudgetUsd: input.usedBudgetUsd,
+        budgetWindowStartAt: input.budgetWindowStartAt,
         executionWorkspacePolicy:
           input.executionWorkspacePolicy === undefined
             ? undefined
@@ -472,6 +486,9 @@ async function hydrateProjectsWithWorkspaces(
     return [] as Array<
       typeof projects.$inferSelect & {
         executionWorkspacePolicy: Record<string, unknown> | null;
+        monthlyBudgetUsd: number;
+        usedBudgetUsd: number;
+        budgetWindowStartAt: string | null;
         workspaces: Array<typeof projectWorkspaces.$inferSelect>;
         primaryWorkspace: typeof projectWorkspaces.$inferSelect | null;
       }
@@ -504,6 +521,9 @@ async function hydrateProjectsWithWorkspaces(
     }
     return {
       ...project,
+      monthlyBudgetUsd: Number(project.monthlyBudgetUsd),
+      usedBudgetUsd: Number(project.usedBudgetUsd),
+      budgetWindowStartAt: project.budgetWindowStartAt ? project.budgetWindowStartAt.toISOString() : null,
       workspaceLocalPath: primaryWorkspace?.cwd ?? null,
       workspaceGithubRepo: primaryWorkspace?.repoUrl ?? null,
       executionWorkspacePolicy,
@@ -687,29 +707,55 @@ export async function addIssueComment(
     issueId: string;
     authorType: "human" | "agent" | "system";
     authorId?: string | null;
+    runId?: string | null;
+    recipients?: Array<{
+      recipientType: "agent" | "board" | "member";
+      recipientId?: string | null;
+      deliveryStatus?: "pending" | "dispatched" | "failed" | "skipped";
+      dispatchedRunId?: string | null;
+      dispatchedAt?: string | null;
+      acknowledgedAt?: string | null;
+    }>;
     body: string;
   }
 ) {
   await assertIssueBelongsToCompany(db, input.companyId, input.issueId);
   const id = nanoid(12);
-  await db.insert(issueComments).values({
-    id,
-    companyId: input.companyId,
-    issueId: input.issueId,
-    authorType: input.authorType,
-    authorId: input.authorId ?? null,
-    body: input.body
-  });
-
-  return { id, ...input };
+  const [comment] = await db
+    .insert(issueComments)
+    .values({
+      id,
+      companyId: input.companyId,
+      issueId: input.issueId,
+      authorType: input.authorType,
+      authorId: input.authorId ?? null,
+      recipientsJson: JSON.stringify(input.recipients ?? []),
+      runId: input.runId ?? null,
+      body: input.body
+    })
+    .returning();
+  if (!comment) {
+    return {
+      id,
+      companyId: input.companyId,
+      issueId: input.issueId,
+      authorType: input.authorType,
+      authorId: input.authorId ?? null,
+      body: input.body,
+      runId: input.runId ?? null,
+      recipients: input.recipients ?? []
+    };
+  }
+  return normalizeIssueComment(comment);
 }
 
 export async function listIssueComments(db: BopoDb, companyId: string, issueId: string) {
-  return db
+  const comments = await db
     .select()
     .from(issueComments)
     .where(and(eq(issueComments.companyId, companyId), eq(issueComments.issueId, issueId)))
-    .orderBy(desc(issueComments.createdAt));
+    .orderBy(asc(issueComments.createdAt));
+  return comments.map((comment) => normalizeIssueComment(comment));
 }
 
 export async function listIssueActivity(db: BopoDb, companyId: string, issueId: string, limit = 100) {
@@ -741,7 +787,37 @@ export async function updateIssueComment(
       )
     )
     .returning();
-  return comment ?? null;
+  return comment ? normalizeIssueComment(comment) : null;
+}
+
+export async function updateIssueCommentRecipients(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    issueId: string;
+    id: string;
+    recipients: Array<{
+      recipientType: "agent" | "board" | "member";
+      recipientId?: string | null;
+      deliveryStatus?: "pending" | "dispatched" | "failed" | "skipped";
+      dispatchedRunId?: string | null;
+      dispatchedAt?: string | null;
+      acknowledgedAt?: string | null;
+    }>;
+  }
+) {
+  const [comment] = await db
+    .update(issueComments)
+    .set({ recipientsJson: JSON.stringify(input.recipients ?? []) })
+    .where(
+      and(
+        eq(issueComments.companyId, input.companyId),
+        eq(issueComments.issueId, input.issueId),
+        eq(issueComments.id, input.id)
+      )
+    )
+    .returning();
+  return comment ? normalizeIssueComment(comment) : null;
 }
 
 export async function deleteIssueComment(db: BopoDb, companyId: string, issueId: string, id: string) {
@@ -752,6 +828,86 @@ export async function deleteIssueComment(db: BopoDb, companyId: string, issueId:
   return Boolean(deletedComment);
 }
 
+function normalizeIssueComment(comment: typeof issueComments.$inferSelect) {
+  const { recipientsJson, ...rest } = comment;
+  return {
+    ...rest,
+    recipients: parseIssueCommentRecipients(recipientsJson)
+  };
+}
+
+function parseIssueCommentRecipients(raw: string | null) {
+  if (!raw) {
+    return [] as Array<{
+      recipientType: "agent" | "board" | "member";
+      recipientId: string | null;
+      deliveryStatus: "pending" | "dispatched" | "failed" | "skipped";
+      dispatchedRunId: string | null;
+      dispatchedAt: string | null;
+      acknowledgedAt: string | null;
+    }>;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed
+      .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+          return null;
+        }
+        const candidate = entry as Record<string, unknown>;
+        const recipientTypeRaw = String(candidate.recipientType ?? "").trim();
+        if (recipientTypeRaw !== "agent" && recipientTypeRaw !== "board" && recipientTypeRaw !== "member") {
+          return null;
+        }
+        const recipientType = recipientTypeRaw as "agent" | "board" | "member";
+        const deliveryStatusRaw = String(candidate.deliveryStatus ?? "").trim();
+        const deliveryStatus =
+          deliveryStatusRaw === "pending" ||
+          deliveryStatusRaw === "dispatched" ||
+          deliveryStatusRaw === "failed" ||
+          deliveryStatusRaw === "skipped"
+            ? deliveryStatusRaw
+            : "pending";
+        const recipientId = typeof candidate.recipientId === "string" && candidate.recipientId.trim().length > 0
+          ? candidate.recipientId.trim()
+          : null;
+        const dispatchedRunId =
+          typeof candidate.dispatchedRunId === "string" && candidate.dispatchedRunId.trim().length > 0
+            ? candidate.dispatchedRunId.trim()
+            : null;
+        const dispatchedAt =
+          typeof candidate.dispatchedAt === "string" && candidate.dispatchedAt.trim().length > 0
+            ? candidate.dispatchedAt.trim()
+            : null;
+        const acknowledgedAt =
+          typeof candidate.acknowledgedAt === "string" && candidate.acknowledgedAt.trim().length > 0
+            ? candidate.acknowledgedAt.trim()
+            : null;
+        return {
+          recipientType,
+          recipientId,
+          deliveryStatus,
+          dispatchedRunId,
+          dispatchedAt,
+          acknowledgedAt
+        };
+      })
+      .filter(Boolean) as Array<{
+      recipientType: "agent" | "board" | "member";
+      recipientId: string | null;
+      deliveryStatus: "pending" | "dispatched" | "failed" | "skipped";
+      dispatchedRunId: string | null;
+      dispatchedAt: string | null;
+      acknowledgedAt: string | null;
+    }>;
+  } catch {
+    return [];
+  }
+}
+
 export async function createGoal(
   db: BopoDb,
   input: {
@@ -837,6 +993,8 @@ export async function createAgent(
     companyId: string;
     managerAgentId?: string | null;
     role: string;
+    roleKey?: string | null;
+    title?: string | null;
     name: string;
     providerType:
       | "claude_code"
@@ -875,6 +1033,8 @@ export async function createAgent(
     companyId: input.companyId,
     managerAgentId: input.managerAgentId ?? null,
     role: input.role,
+    roleKey: input.roleKey ?? null,
+    title: input.title ?? null,
     name: input.name,
     providerType: input.providerType,
     heartbeatCron: input.heartbeatCron,
@@ -908,6 +1068,8 @@ export async function updateAgent(
     id: string;
     managerAgentId?: string | null;
     role?: string;
+    roleKey?: string | null;
+    title?: string | null;
     name?: string;
     providerType?:
       | "claude_code"
@@ -945,6 +1107,8 @@ export async function updateAgent(
       compactUpdate({
         managerAgentId: input.managerAgentId,
         role: input.role,
+        roleKey: input.roleKey,
+        title: input.title,
         name: input.name,
         providerType: input.providerType,
         status: input.status,
@@ -1149,6 +1313,147 @@ export async function clearApprovalInboxDismissed(
     });
 }
 
+export async function listAttentionInboxStates(db: BopoDb, companyId: string, actorId: string) {
+  return db
+    .select()
+    .from(attentionInboxStates)
+    .where(and(eq(attentionInboxStates.companyId, companyId), eq(attentionInboxStates.actorId, actorId)))
+    .orderBy(desc(attentionInboxStates.updatedAt));
+}
+
+export async function markAttentionInboxSeen(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    actorId: string;
+    itemKey: string;
+    seenAt?: Date;
+  }
+) {
+  const seenAt = input.seenAt ?? new Date();
+  await db
+    .insert(attentionInboxStates)
+    .values({
+      companyId: input.companyId,
+      actorId: input.actorId,
+      itemKey: input.itemKey,
+      seenAt
+    })
+    .onConflictDoUpdate({
+      target: [attentionInboxStates.companyId, attentionInboxStates.actorId, attentionInboxStates.itemKey],
+      set: {
+        seenAt,
+        updatedAt: sql`CURRENT_TIMESTAMP`
+      }
+    });
+}
+
+export async function markAttentionInboxAcknowledged(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    actorId: string;
+    itemKey: string;
+    acknowledgedAt?: Date;
+  }
+) {
+  const acknowledgedAt = input.acknowledgedAt ?? new Date();
+  await db
+    .insert(attentionInboxStates)
+    .values({
+      companyId: input.companyId,
+      actorId: input.actorId,
+      itemKey: input.itemKey,
+      acknowledgedAt
+    })
+    .onConflictDoUpdate({
+      target: [attentionInboxStates.companyId, attentionInboxStates.actorId, attentionInboxStates.itemKey],
+      set: {
+        acknowledgedAt,
+        updatedAt: sql`CURRENT_TIMESTAMP`
+      }
+    });
+}
+
+export async function markAttentionInboxDismissed(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    actorId: string;
+    itemKey: string;
+    dismissedAt?: Date;
+  }
+) {
+  const dismissedAt = input.dismissedAt ?? new Date();
+  await db
+    .insert(attentionInboxStates)
+    .values({
+      companyId: input.companyId,
+      actorId: input.actorId,
+      itemKey: input.itemKey,
+      dismissedAt
+    })
+    .onConflictDoUpdate({
+      target: [attentionInboxStates.companyId, attentionInboxStates.actorId, attentionInboxStates.itemKey],
+      set: {
+        dismissedAt,
+        updatedAt: sql`CURRENT_TIMESTAMP`
+      }
+    });
+}
+
+export async function clearAttentionInboxDismissed(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    actorId: string;
+    itemKey: string;
+  }
+) {
+  await db
+    .insert(attentionInboxStates)
+    .values({
+      companyId: input.companyId,
+      actorId: input.actorId,
+      itemKey: input.itemKey,
+      dismissedAt: null
+    })
+    .onConflictDoUpdate({
+      target: [attentionInboxStates.companyId, attentionInboxStates.actorId, attentionInboxStates.itemKey],
+      set: {
+        dismissedAt: null,
+        updatedAt: sql`CURRENT_TIMESTAMP`
+      }
+    });
+}
+
+export async function markAttentionInboxResolved(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    actorId: string;
+    itemKey: string;
+    resolvedAt?: Date;
+  }
+) {
+  const resolvedAt = input.resolvedAt ?? new Date();
+  await db
+    .insert(attentionInboxStates)
+    .values({
+      companyId: input.companyId,
+      actorId: input.actorId,
+      itemKey: input.itemKey,
+      resolvedAt
+    })
+    .onConflictDoUpdate({
+      target: [attentionInboxStates.companyId, attentionInboxStates.actorId, attentionInboxStates.itemKey],
+      set: {
+        resolvedAt,
+        updatedAt: sql`CURRENT_TIMESTAMP`
+      }
+    });
+}
+
 export async function appendCost(
   db: BopoDb,
   input: {
@@ -1203,6 +1508,293 @@ export async function listHeartbeatRuns(db: BopoDb, companyId: string, limit = 1
     .limit(limit);
 }
 
+export type HeartbeatQueueJobType = "manual" | "scheduler" | "resume" | "redo" | "comment_dispatch";
+export type HeartbeatQueueJobStatus = "pending" | "running" | "completed" | "failed" | "dead_letter" | "canceled";
+
+type HeartbeatQueueJobRow = typeof heartbeatRunQueue.$inferSelect;
+
+function normalizeHeartbeatQueueJob(rawRow: HeartbeatQueueJobRow | Record<string, unknown>) {
+  const row = {
+    id: String((rawRow as Record<string, unknown>).id ?? ""),
+    companyId: String((rawRow as Record<string, unknown>).companyId ?? (rawRow as Record<string, unknown>).company_id ?? ""),
+    agentId: String((rawRow as Record<string, unknown>).agentId ?? (rawRow as Record<string, unknown>).agent_id ?? ""),
+    jobType: String((rawRow as Record<string, unknown>).jobType ?? (rawRow as Record<string, unknown>).job_type ?? ""),
+    payloadJson: String((rawRow as Record<string, unknown>).payloadJson ?? (rawRow as Record<string, unknown>).payload_json ?? "{}"),
+    status: String((rawRow as Record<string, unknown>).status ?? "pending"),
+    priority: Number((rawRow as Record<string, unknown>).priority ?? 100),
+    idempotencyKey:
+      typeof (rawRow as Record<string, unknown>).idempotencyKey === "string"
+        ? ((rawRow as Record<string, unknown>).idempotencyKey as string)
+        : typeof (rawRow as Record<string, unknown>).idempotency_key === "string"
+          ? ((rawRow as Record<string, unknown>).idempotency_key as string)
+          : null,
+    availableAt: coerceDate((rawRow as Record<string, unknown>).availableAt ?? (rawRow as Record<string, unknown>).available_at) ?? new Date(),
+    attemptCount: Number((rawRow as Record<string, unknown>).attemptCount ?? (rawRow as Record<string, unknown>).attempt_count ?? 0),
+    maxAttempts: Number((rawRow as Record<string, unknown>).maxAttempts ?? (rawRow as Record<string, unknown>).max_attempts ?? 10),
+    lastError:
+      typeof (rawRow as Record<string, unknown>).lastError === "string"
+        ? ((rawRow as Record<string, unknown>).lastError as string)
+        : typeof (rawRow as Record<string, unknown>).last_error === "string"
+          ? ((rawRow as Record<string, unknown>).last_error as string)
+          : null,
+    startedAt: coerceDate((rawRow as Record<string, unknown>).startedAt ?? (rawRow as Record<string, unknown>).started_at),
+    finishedAt: coerceDate((rawRow as Record<string, unknown>).finishedAt ?? (rawRow as Record<string, unknown>).finished_at),
+    heartbeatRunId:
+      typeof (rawRow as Record<string, unknown>).heartbeatRunId === "string"
+        ? ((rawRow as Record<string, unknown>).heartbeatRunId as string)
+        : typeof (rawRow as Record<string, unknown>).heartbeat_run_id === "string"
+          ? ((rawRow as Record<string, unknown>).heartbeat_run_id as string)
+          : null,
+    createdAt: coerceDate((rawRow as Record<string, unknown>).createdAt ?? (rawRow as Record<string, unknown>).created_at) ?? new Date(),
+    updatedAt: coerceDate((rawRow as Record<string, unknown>).updatedAt ?? (rawRow as Record<string, unknown>).updated_at) ?? new Date()
+  } satisfies HeartbeatQueueJobRow;
+  let payload: Record<string, unknown> = {};
+  try {
+    payload = JSON.parse(row.payloadJson ?? "{}") as Record<string, unknown>;
+  } catch {
+    payload = {};
+  }
+  return {
+    ...row,
+    payload
+  };
+}
+
+function coerceDate(value: unknown) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+  return null;
+}
+
+export async function enqueueHeartbeatJob(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    agentId: string;
+    jobType: HeartbeatQueueJobType;
+    payload?: Record<string, unknown>;
+    priority?: number;
+    availableAt?: Date;
+    maxAttempts?: number;
+    idempotencyKey?: string | null;
+  }
+) {
+  await assertAgentBelongsToCompany(db, input.companyId, input.agentId);
+  const normalizedIdempotencyKey = input.idempotencyKey?.trim() || null;
+  if (normalizedIdempotencyKey) {
+    const [existing] = await db
+      .select()
+      .from(heartbeatRunQueue)
+      .where(
+        and(
+          eq(heartbeatRunQueue.companyId, input.companyId),
+          eq(heartbeatRunQueue.agentId, input.agentId),
+          eq(heartbeatRunQueue.idempotencyKey, normalizedIdempotencyKey),
+          notInArray(heartbeatRunQueue.status, ["failed", "dead_letter", "canceled"])
+        )
+      )
+      .orderBy(desc(heartbeatRunQueue.createdAt))
+      .limit(1);
+    if (existing) {
+      return normalizeHeartbeatQueueJob(existing);
+    }
+  }
+  const id = nanoid(14);
+  const [job] = await db
+    .insert(heartbeatRunQueue)
+    .values({
+      id,
+      companyId: input.companyId,
+      agentId: input.agentId,
+      jobType: input.jobType,
+      payloadJson: JSON.stringify(input.payload ?? {}),
+      status: "pending",
+      priority: Number.isFinite(input.priority) ? Math.max(0, Math.floor(input.priority!)) : 100,
+      idempotencyKey: normalizedIdempotencyKey,
+      availableAt: input.availableAt ?? new Date(),
+      maxAttempts: Number.isFinite(input.maxAttempts) ? Math.max(1, Math.floor(input.maxAttempts!)) : 10
+    })
+    .returning();
+  if (!job) {
+    throw new RepositoryValidationError("Failed to enqueue heartbeat job.");
+  }
+  return normalizeHeartbeatQueueJob(job);
+}
+
+export async function claimNextHeartbeatJob(db: BopoDb, companyId: string) {
+  const result = await db.execute(sql`
+    WITH candidate AS (
+      SELECT q.id
+      FROM heartbeat_run_queue q
+      WHERE q.company_id = ${companyId}
+        AND q.status = 'pending'
+        AND q.available_at <= CURRENT_TIMESTAMP
+        AND NOT EXISTS (
+          SELECT 1
+          FROM heartbeat_run_queue active_q
+          WHERE active_q.company_id = q.company_id
+            AND active_q.agent_id = q.agent_id
+            AND active_q.status = 'running'
+        )
+        AND NOT EXISTS (
+          SELECT 1
+          FROM heartbeat_runs r
+          WHERE r.company_id = q.company_id
+            AND r.agent_id = q.agent_id
+            AND r.status = 'started'
+        )
+      ORDER BY q.priority ASC, q.created_at ASC
+      LIMIT 1
+      FOR UPDATE SKIP LOCKED
+    )
+    UPDATE heartbeat_run_queue q
+    SET
+      status = 'running',
+      started_at = CURRENT_TIMESTAMP,
+      updated_at = CURRENT_TIMESTAMP,
+      attempt_count = q.attempt_count + 1
+    FROM candidate c
+    WHERE q.id = c.id
+    RETURNING q.*;
+  `);
+  const row = (result.rows ?? [])[0] as Record<string, unknown> | undefined;
+  return row ? normalizeHeartbeatQueueJob(row) : null;
+}
+
+export async function getHeartbeatQueueJob(db: BopoDb, companyId: string, id: string) {
+  const [job] = await db
+    .select()
+    .from(heartbeatRunQueue)
+    .where(and(eq(heartbeatRunQueue.companyId, companyId), eq(heartbeatRunQueue.id, id)))
+    .limit(1);
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function markHeartbeatJobCompleted(
+  db: BopoDb,
+  input: { companyId: string; id: string; heartbeatRunId?: string | null }
+) {
+  const [job] = await db
+    .update(heartbeatRunQueue)
+    .set({
+      status: "completed",
+      heartbeatRunId: input.heartbeatRunId ?? null,
+      finishedAt: new Date(),
+      updatedAt: touchUpdatedAtSql
+    })
+    .where(and(eq(heartbeatRunQueue.companyId, input.companyId), eq(heartbeatRunQueue.id, input.id)))
+    .returning();
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function markHeartbeatJobRetry(
+  db: BopoDb,
+  input: { companyId: string; id: string; retryAt: Date; error?: string | null; heartbeatRunId?: string | null }
+) {
+  const [job] = await db
+    .update(heartbeatRunQueue)
+    .set({
+      status: "pending",
+      availableAt: input.retryAt,
+      lastError: input.error ?? null,
+      heartbeatRunId: input.heartbeatRunId ?? null,
+      updatedAt: touchUpdatedAtSql
+    })
+    .where(and(eq(heartbeatRunQueue.companyId, input.companyId), eq(heartbeatRunQueue.id, input.id)))
+    .returning();
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function markHeartbeatJobFailed(
+  db: BopoDb,
+  input: { companyId: string; id: string; error?: string | null; heartbeatRunId?: string | null }
+) {
+  const [job] = await db
+    .update(heartbeatRunQueue)
+    .set({
+      status: "failed",
+      lastError: input.error ?? null,
+      heartbeatRunId: input.heartbeatRunId ?? null,
+      finishedAt: new Date(),
+      updatedAt: touchUpdatedAtSql
+    })
+    .where(and(eq(heartbeatRunQueue.companyId, input.companyId), eq(heartbeatRunQueue.id, input.id)))
+    .returning();
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function markHeartbeatJobDeadLetter(
+  db: BopoDb,
+  input: { companyId: string; id: string; error?: string | null; heartbeatRunId?: string | null }
+) {
+  const [job] = await db
+    .update(heartbeatRunQueue)
+    .set({
+      status: "dead_letter",
+      lastError: input.error ?? null,
+      heartbeatRunId: input.heartbeatRunId ?? null,
+      finishedAt: new Date(),
+      updatedAt: touchUpdatedAtSql
+    })
+    .where(and(eq(heartbeatRunQueue.companyId, input.companyId), eq(heartbeatRunQueue.id, input.id)))
+    .returning();
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function cancelHeartbeatJob(db: BopoDb, input: { companyId: string; id: string }) {
+  const [job] = await db
+    .update(heartbeatRunQueue)
+    .set({
+      status: "canceled",
+      finishedAt: new Date(),
+      updatedAt: touchUpdatedAtSql
+    })
+    .where(
+      and(
+        eq(heartbeatRunQueue.companyId, input.companyId),
+        eq(heartbeatRunQueue.id, input.id),
+        notInArray(heartbeatRunQueue.status, ["completed", "failed", "dead_letter", "canceled"])
+      )
+    )
+    .returning();
+  return job ? normalizeHeartbeatQueueJob(job) : null;
+}
+
+export async function listHeartbeatQueueJobs(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    status?: HeartbeatQueueJobStatus;
+    agentId?: string;
+    jobType?: HeartbeatQueueJobType;
+    limit?: number;
+  }
+) {
+  const conditions = [eq(heartbeatRunQueue.companyId, input.companyId)];
+  if (input.status) {
+    conditions.push(eq(heartbeatRunQueue.status, input.status));
+  }
+  if (input.agentId) {
+    conditions.push(eq(heartbeatRunQueue.agentId, input.agentId));
+  }
+  if (input.jobType) {
+    conditions.push(eq(heartbeatRunQueue.jobType, input.jobType));
+  }
+  const limit = Math.min(Math.max(input.limit ?? 200, 1), 1000);
+  const rows = await db
+    .select()
+    .from(heartbeatRunQueue)
+    .where(and(...conditions))
+    .orderBy(asc(heartbeatRunQueue.priority), asc(heartbeatRunQueue.availableAt), asc(heartbeatRunQueue.createdAt))
+    .limit(limit);
+  return rows.map((row) => normalizeHeartbeatQueueJob(row));
+}
+
 export async function getHeartbeatRun(db: BopoDb, companyId: string, runId: string) {
   const [run] = await db
     .select()