bopodev-api 0.1.24 → 0.1.26

package/src/routes/heartbeats.ts

@@ -1,12 +1,17 @@
 import { Router } from "express";
 import { z } from "zod";
 import { and, eq } from "drizzle-orm";
-import { agents, heartbeatRuns } from "bopodev-db";
+import { agents, heartbeatRuns, listHeartbeatQueueJobs } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
-import { runHeartbeatForAgent, runHeartbeatSweep, stopHeartbeatRun } from "../services/heartbeat-service";
+import {
+  findPendingProjectBudgetOverrideBlocksForAgent,
+  runHeartbeatSweep,
+  stopHeartbeatRun
+} from "../services/heartbeat-service";
+import { enqueueHeartbeatQueueJob, triggerHeartbeatQueueWorker } from "../services/heartbeat-queue-service";
 
 const runAgentSchema = z.object({
   agentId: z.string().min(1)
@@ -14,6 +19,12 @@ const runAgentSchema = z.object({
 const runIdParamsSchema = z.object({
   runId: z.string().min(1)
 });
+const queueQuerySchema = z.object({
+  status: z.enum(["pending", "running", "completed", "failed", "dead_letter", "canceled"]).optional(),
+  agentId: z.string().min(1).optional(),
+  jobType: z.enum(["manual", "scheduler", "resume", "redo", "comment_dispatch"]).optional(),
+  limit: z.coerce.number().int().min(1).max(1000).optional()
+});
 
 export function createHeartbeatRouter(ctx: AppContext) {
   const router = Router();
@@ -39,31 +50,37 @@ export function createHeartbeatRouter(ctx: AppContext) {
     if (agent.status === "paused" || agent.status === "terminated") {
       return sendError(res, `Agent is not invokable in status '${agent.status}'.`, 409);
     }
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(
+      ctx.db,
+      req.companyId!,
+      parsed.data.agentId
+    );
+    if (blockedProjectIds.length > 0) {
+      return sendError(
+        res,
+        `Agent is blocked by pending project budget approval for project(s): ${blockedProjectIds.join(", ")}.`,
+        423
+      );
+    }
 
-    const runId = await runHeartbeatForAgent(ctx.db, req.companyId!, parsed.data.agentId, {
+    const job = await enqueueHeartbeatQueueJob(ctx.db, {
+      companyId: req.companyId!,
+      agentId: parsed.data.agentId,
+      jobType: "manual",
+      priority: 30,
+      idempotencyKey: req.requestId ? `manual:${parsed.data.agentId}:${req.requestId}` : null,
+      payload: {}
+    });
+    triggerHeartbeatQueueWorker(ctx.db, req.companyId!, {
       requestId: req.requestId,
-      trigger: "manual",
       realtimeHub: ctx.realtimeHub
     });
-    if (!runId) {
-      return sendError(res, "Heartbeat could not be started for this agent.", 409);
-    }
-    const [runRow] = await ctx.db
-      .select({ id: heartbeatRuns.id, status: heartbeatRuns.status, message: heartbeatRuns.message })
-      .from(heartbeatRuns)
-      .where(and(eq(heartbeatRuns.companyId, req.companyId!), eq(heartbeatRuns.id, runId)))
-      .limit(1);
-    const invokeStatus =
-      runRow?.status === "skipped" && String(runRow.message ?? "").includes("already in progress")
-        ? "skipped_overlap"
-        : runRow?.status === "skipped"
-          ? "skipped"
-          : "started";
     return sendOk(res, {
-      runId,
+      runId: null,
+      jobId: job.id,
       requestId: req.requestId,
-      status: invokeStatus,
-      message: runRow?.message ?? null
+      status: "queued",
+      message: "Heartbeat queued."
     });
   });
 
@@ -127,32 +144,32 @@ export function createHeartbeatRouter(ctx: AppContext) {
     if (agent.status === "paused" || agent.status === "terminated") {
       return { ok: false as const, statusCode: 409, message: `Agent is not invokable in status '${agent.status}'.` };
     }
-    const nextRunId = await runHeartbeatForAgent(ctx.db, input.companyId, run.agentId, {
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(ctx.db, input.companyId, run.agentId);
+    if (blockedProjectIds.length > 0) {
+      return {
+        ok: false as const,
+        statusCode: 423,
+        message: `Agent is blocked by pending project budget approval for project(s): ${blockedProjectIds.join(", ")}.`
+      };
+    }
+    const job = await enqueueHeartbeatQueueJob(ctx.db, {
+      companyId: input.companyId,
+      agentId: run.agentId,
+      jobType: input.mode,
+      priority: 30,
+      idempotencyKey: input.requestId ? `${input.mode}:${run.agentId}:${run.id}:${input.requestId}` : null,
+      payload: { sourceRunId: run.id }
+    });
+    triggerHeartbeatQueueWorker(ctx.db, input.companyId, {
       requestId: input.requestId,
-      trigger: "manual",
-      realtimeHub: ctx.realtimeHub,
-      mode: input.mode,
-      sourceRunId: run.id
+      realtimeHub: ctx.realtimeHub
     });
-    if (!nextRunId) {
-      return { ok: false as const, statusCode: 409, message: "Heartbeat could not be started for this agent." };
-    }
-    const [runRow] = await ctx.db
-      .select({ id: heartbeatRuns.id, status: heartbeatRuns.status, message: heartbeatRuns.message })
-      .from(heartbeatRuns)
-      .where(and(eq(heartbeatRuns.companyId, input.companyId), eq(heartbeatRuns.id, nextRunId)))
-      .limit(1);
-    const invokeStatus =
-      runRow?.status === "skipped" && String(runRow.message ?? "").includes("already in progress")
-        ? "skipped_overlap"
-        : runRow?.status === "skipped"
-          ? "skipped"
-          : "started";
     return {
       ok: true as const,
-      runId: nextRunId,
-      status: invokeStatus,
-      message: runRow?.message ?? null
+      runId: null,
+      jobId: job.id,
+      status: "queued" as const,
+      message: "Heartbeat queued."
     };
   }
 
@@ -176,6 +193,7 @@ export function createHeartbeatRouter(ctx: AppContext) {
     }
     return sendOk(res, {
       runId: result.runId,
+      jobId: result.jobId,
       requestId: req.requestId,
       status: result.status,
       message: result.message
@@ -202,6 +220,7 @@ export function createHeartbeatRouter(ctx: AppContext) {
     }
     return sendOk(res, {
       runId: result.runId,
+      jobId: result.jobId,
       requestId: req.requestId,
       status: result.status,
       message: result.message
@@ -220,5 +239,24 @@ export function createHeartbeatRouter(ctx: AppContext) {
     return sendOk(res, { runIds, requestId: req.requestId });
   });
 
+  router.get("/queue", async (req, res) => {
+    requirePermission("heartbeats:run")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = queueQuerySchema.safeParse(req.query);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const jobs = await listHeartbeatQueueJobs(ctx.db, {
+      companyId: req.companyId!,
+      status: parsed.data.status,
+      agentId: parsed.data.agentId,
+      jobType: parsed.data.jobType,
+      limit: parsed.data.limit
+    });
+    return sendOk(res, { items: jobs });
+  });
+
   return router;
 }

package/src/routes/issues.ts

@@ -1,9 +1,10 @@
 import { Router } from "express";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
-import { and, eq } from "drizzle-orm";
+import { and, desc, eq, inArray } from "drizzle-orm";
 import multer from "multer";
 import { z } from "zod";
+import { IssueSchema } from "bopodev-contracts";
 import {
   addIssueAttachment,
   addIssueComment,
@@ -14,6 +15,7 @@ import {
   deleteIssueAttachment,
   deleteIssueComment,
   deleteIssue,
+  heartbeatRuns,
   getIssueAttachment,
   issues,
   listIssueAttachments,
@@ -27,10 +29,18 @@ import {
 } from "bopodev-db";
 import { nanoid } from "nanoid";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
+import {
+  dedupeCommentRecipients,
+  normalizeRecipientsForPersistence,
+  type CommentRecipientInput,
+  type PersistedCommentRecipient
+} from "../lib/comment-recipients";
 import { isInsidePath, normalizeCompanyWorkspacePath, resolveProjectWorkspacePath } from "../lib/instance-paths";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
+import { triggerIssueCommentDispatchWorker } from "../services/comment-recipient-dispatch-service";
+import { publishAttentionSnapshot } from "../realtime/attention";
 
 const createIssueSchema = z.object({
   projectId: z.string().min(1),
@@ -43,6 +53,8 @@ const createIssueSchema = z.object({
         .object({
           intentType: z.literal("agent_hiring_request"),
           requestedRole: z.string().nullable().optional(),
+          requestedRoleKey: z.string().nullable().optional(),
+          requestedTitle: z.string().nullable().optional(),
           requestedName: z.string().nullable().optional(),
           requestedManagerAgentId: z.string().nullable().optional(),
           requestedProviderType: z.string().nullable().optional(),
@@ -60,6 +72,14 @@ const createIssueSchema = z.object({
 
 const createIssueCommentSchema = z.object({
   body: z.string().min(1),
+  recipients: z
+    .array(
+      z.object({
+        recipientType: z.enum(["agent", "board", "member"]),
+        recipientId: z.string().nullable().optional()
+      })
+    )
+    .default([]),
   authorType: z.enum(["human", "agent", "system"]).optional(),
   authorId: z.string().optional()
 });
@@ -67,6 +87,14 @@ const createIssueCommentSchema = z.object({
 const createIssueCommentLegacySchema = z.object({
   issueId: z.string().min(1),
   body: z.string().min(1),
+  recipients: z
+    .array(
+      z.object({
+        recipientType: z.enum(["agent", "board", "member"]),
+        recipientId: z.string().nullable().optional()
+      })
+    )
+    .default([]),
   authorType: z.enum(["human", "agent", "system"]).optional(),
   authorId: z.string().optional()
 });
@@ -99,6 +127,7 @@ const ALLOWED_ATTACHMENT_EXTENSIONS = parseCsvSet(
 );
 
 type IssueAttachmentResponse = Record<string, unknown> & { id: string; downloadPath: string };
+const COMMENT_RUN_ID_HEADER = "x-bopodev-run-id";
 
 function parseStringArray(value: unknown) {
   if (Array.isArray(value)) {
@@ -153,9 +182,11 @@ export function createIssuesRouter(ctx: AppContext) {
   router.get("/", async (req, res) => {
     const projectId = req.query.projectId?.toString();
     const rows = await listIssues(ctx.db, req.companyId!, projectId);
-    return sendOk(
+    return sendOkValidated(
       res,
-      rows.map((row) => toIssueResponse(row as unknown as Record<string, unknown>))
+      IssueSchema.array(),
+      rows.map((row) => toIssueResponse(row as unknown as Record<string, unknown>)),
+      "issues.list"
     );
   });
 
@@ -427,32 +458,13 @@ export function createIssuesRouter(ctx: AppContext) {
     if (!parsed.success) {
       return sendError(res, parsed.error.message, 422);
     }
-    const author = resolveIssueCommentAuthor(req.actor?.type, req.actor?.id, parsed.data);
-    const comment = await addIssueComment(ctx.db, {
-      companyId: req.companyId!,
+    return createIssueCommentWithRecipients(ctx, req, res, {
       issueId: req.params.issueId,
       body: parsed.data.body,
-      authorType: author.authorType,
-      authorId: author.authorId
-    });
-    await appendActivity(ctx.db, {
-      companyId: req.companyId!,
-      issueId: comment.issueId,
-      actorType: comment.authorType,
-      actorId: comment.authorId,
-      eventType: "issue.comment_added",
-      payload: { commentId: comment.id }
-    });
-    await appendAuditEvent(ctx.db, {
-      companyId: req.companyId!,
-      actorType: comment.authorType,
-      actorId: comment.authorId,
-      eventType: "issue.comment_added",
-      entityType: "issue_comment",
-      entityId: comment.id,
-      payload: comment
+      recipients: parsed.data.recipients,
+      authorType: parsed.data.authorType,
+      authorId: parsed.data.authorId
     });
-    return sendOk(res, comment);
   });
 
   // Backward-compatible endpoint used by older clients.
@@ -465,32 +477,13 @@ export function createIssuesRouter(ctx: AppContext) {
     if (!parsed.success) {
       return sendError(res, parsed.error.message, 422);
     }
-    const author = resolveIssueCommentAuthor(req.actor?.type, req.actor?.id, parsed.data);
-    const comment = await addIssueComment(ctx.db, {
-      companyId: req.companyId!,
+    return createIssueCommentWithRecipients(ctx, req, res, {
       issueId: parsed.data.issueId,
       body: parsed.data.body,
-      authorType: author.authorType,
-      authorId: author.authorId
-    });
-    await appendActivity(ctx.db, {
-      companyId: req.companyId!,
-      issueId: comment.issueId,
-      actorType: comment.authorType,
-      actorId: comment.authorId,
-      eventType: "issue.comment_added",
-      payload: { commentId: comment.id }
+      recipients: parsed.data.recipients,
+      authorType: parsed.data.authorType,
+      authorId: parsed.data.authorId
     });
-    await appendAuditEvent(ctx.db, {
-      companyId: req.companyId!,
-      actorType: comment.authorType,
-      actorId: comment.authorId,
-      eventType: "issue.comment_added",
-      entityType: "issue_comment",
-      entityId: comment.id,
-      payload: comment
-    });
-    return sendOk(res, comment);
   });
 
   router.put("/:issueId/comments/:commentId", async (req, res) => {
@@ -503,11 +496,16 @@ export function createIssuesRouter(ctx: AppContext) {
       return sendError(res, parsed.error.message, 422);
     }
 
+    const body =
+      req.actor?.type === "agent" ? sanitizeCommentBodyForAuthor(parsed.data.body, "agent") : parsed.data.body;
+    if (req.actor?.type === "agent" && !body) {
+      return sendError(res, "Agent comments must include non-emoji text.", 422);
+    }
     const comment = await updateIssueComment(ctx.db, {
       companyId: req.companyId!,
       issueId: req.params.issueId,
       id: req.params.commentId,
-      body: parsed.data.body
+      body
     });
     if (!comment) {
       return sendError(res, "Comment not found.", 404);
@@ -516,13 +514,15 @@ export function createIssuesRouter(ctx: AppContext) {
     await appendActivity(ctx.db, {
       companyId: req.companyId!,
       issueId: req.params.issueId,
-      actorType: "human",
+      actorType: req.actor?.type === "agent" ? "agent" : "human",
+      actorId: req.actor?.id,
       eventType: "issue.comment_updated",
       payload: { commentId: comment.id }
     });
     await appendAuditEvent(ctx.db, {
       companyId: req.companyId!,
-      actorType: "human",
+      actorType: req.actor?.type === "agent" ? "agent" : "human",
+      actorId: req.actor?.id,
       eventType: "issue.comment_updated",
       entityType: "issue_comment",
       entityId: comment.id,
@@ -544,13 +544,15 @@ export function createIssuesRouter(ctx: AppContext) {
     await appendActivity(ctx.db, {
       companyId: req.companyId!,
       issueId: req.params.issueId,
-      actorType: "human",
+      actorType: req.actor?.type === "agent" ? "agent" : "human",
+      actorId: req.actor?.id,
       eventType: "issue.comment_deleted",
       payload: { commentId: req.params.commentId }
     });
     await appendAuditEvent(ctx.db, {
       companyId: req.companyId!,
-      actorType: "human",
+      actorType: req.actor?.type === "agent" ? "agent" : "human",
+      actorId: req.actor?.id,
       eventType: "issue.comment_deleted",
       entityType: "issue_comment",
       entityId: req.params.commentId,
@@ -680,20 +682,249 @@ function parsePayload(payloadJson: string) {
   }
 }
 
+async function createIssueCommentWithRecipients(
+  ctx: AppContext,
+  req: {
+    companyId?: string;
+    actor?: { type?: "board" | "member" | "agent"; id?: string };
+    requestId?: string;
+    header(name: string): string | undefined;
+  },
+  res: Parameters<typeof sendOk>[0],
+  input: {
+    issueId: string;
+    body: string;
+    recipients: CommentRecipientInput[];
+    authorType?: "human" | "agent" | "system";
+    authorId?: string;
+  }
+) {
+  const spoofValidationError = validateCommentAuthorInput(req.actor?.type, req.actor?.id, {
+    authorType: input.authorType,
+    authorId: input.authorId
+  });
+  if (spoofValidationError) {
+    return sendError(res, spoofValidationError, 422);
+  }
+  const author = resolveIssueCommentAuthor(req.actor?.type, req.actor?.id, {
+    authorType: input.authorType,
+    authorId: input.authorId
+  });
+  let normalizedRecipients: PersistedCommentRecipient[];
+  try {
+    normalizedRecipients = await normalizeCommentRecipients(ctx, req.companyId!, input.recipients);
+  } catch (error) {
+    return sendError(res, error instanceof Error ? error.message : "Invalid recipients.", 422);
+  }
+  const runId = await resolveIssueCommentRunId(ctx, {
+    companyId: req.companyId!,
+    actorType: req.actor?.type,
+    actorId: req.actor?.id,
+    runIdHeader: req.header(COMMENT_RUN_ID_HEADER)
+  });
+  const sanitizedBody = sanitizeCommentBodyForAuthor(input.body, author.authorType);
+  if (!sanitizedBody) {
+    return sendError(res, "Agent/system comments must include non-emoji text.", 422);
+  }
+  const comment = await addIssueComment(ctx.db, {
+    companyId: req.companyId!,
+    issueId: input.issueId,
+    body: sanitizedBody,
+    authorType: author.authorType,
+    authorId: author.authorId,
+    runId,
+    recipients: normalizedRecipients
+  });
+  await appendActivity(ctx.db, {
+    companyId: req.companyId!,
+    issueId: comment.issueId,
+    actorType: coerceActorType(comment.authorType),
+    actorId: comment.authorId,
+    eventType: "issue.comment_added",
+    payload: {
+      commentId: comment.id,
+      runId: comment.runId ?? null,
+      recipientCount: normalizedRecipients.length
+    }
+  });
+  await appendAuditEvent(ctx.db, {
+    companyId: req.companyId!,
+    actorType: coerceActorType(comment.authorType),
+    actorId: comment.authorId,
+    eventType: "issue.comment_added",
+    entityType: "issue_comment",
+    entityId: comment.id,
+    payload: comment
+  });
+  if (normalizedRecipients.some((recipient) => recipient.recipientType === "board")) {
+    await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
+  }
+  triggerIssueCommentDispatchWorker(ctx.db, req.companyId!, {
+    requestId: req.requestId,
+    realtimeHub: ctx.realtimeHub,
+    limit: 10
+  });
+  return sendOk(res, comment);
+}
+
 function resolveIssueCommentAuthor(
   actorType: "board" | "member" | "agent" | undefined,
   actorId: string | undefined,
   input: { authorType?: "human" | "agent" | "system"; authorId?: string }
 ) {
-  const inferredAuthorType = actorType === "agent" ? "agent" : "human";
-  const authorType = input.authorType ?? inferredAuthorType;
-  if (input.authorId) {
-    return { authorType, authorId: input.authorId };
+  if ((actorType === "board" || actorType === undefined) && (input.authorType || input.authorId)) {
+    return {
+      authorType: input.authorType ?? "human",
+      authorId: input.authorId
+    };
+  }
+  if (actorType === "agent") {
+    return { authorType: "agent" as const, authorId: actorId };
+  }
+  return { authorType: "human" as const, authorId: actorId };
+}
+
+function validateCommentAuthorInput(
+  actorType: "board" | "member" | "agent" | undefined,
+  actorId: string | undefined,
+  input: { authorType?: "human" | "agent" | "system"; authorId?: string }
+) {
+  if (!input.authorType && !input.authorId) {
+    return null;
+  }
+  if (actorType !== "member" && actorType !== "agent") {
+    // Board/default channels are trusted for migration/backfill and may set explicit authorship.
+    return null;
+  }
+  const expectedAuthorType = actorType === "agent" ? "agent" : "human";
+  if (input.authorType && input.authorType !== expectedAuthorType) {
+    return "Comment author fields are derived from actor identity and cannot be overridden.";
+  }
+  if (input.authorId && actorId && input.authorId !== actorId) {
+    return "Comment author fields are derived from actor identity and cannot be overridden.";
+  }
+  if (input.authorId && !actorId) {
+    return "Comment author fields are derived from actor identity and cannot be overridden.";
+  }
+  return null;
+}
+
+function coerceActorType(value: string | null | undefined): "human" | "agent" | "system" {
+  if (value === "agent" || value === "system") {
+    return value;
+  }
+  return "human";
+}
+
+function sanitizeCommentBodyForAuthor(body: string, authorType: "human" | "agent" | "system") {
+  if (authorType === "human") {
+    return body;
+  }
+  const withoutEmoji = body.replace(/[\p{Extended_Pictographic}\uFE0F\u200D]/gu, "");
+  const trimmed = withoutEmoji.trim();
+  const extractedSummary = extractSummaryFromJsonLikeText(trimmed);
+  const isPureJsonLike =
+    /^\s*\{[\s\S]*\}\s*$/m.test(trimmed) || /^\s*```(?:json)?[\s\S]*```\s*$/im.test(trimmed);
+  if (isPureJsonLike && extractedSummary) {
+    return extractedSummary;
+  }
+  const trailingJsonSummary = trimmed.match(/^(?<main>[\s\S]*?)\n+\{[\s\S]*"summary"\s*:\s*"[\s\S]*?"[\s\S]*\}\s*$/);
+  if (trailingJsonSummary?.groups?.main) {
+    return trailingJsonSummary.groups.main.trim();
+  }
+  return trimmed;
+}
+
+function extractSummaryFromJsonLikeText(input: string) {
+  const fencedMatch = input.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fencedMatch?.[1]?.trim() ?? input.match(/\{[\s\S]*\}\s*$/)?.[0]?.trim();
+  if (!candidate) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(candidate) as Record<string, unknown>;
+    const summary = parsed.summary;
+    if (typeof summary === "string" && summary.trim().length > 0) {
+      return summary.trim();
+    }
+  } catch {
+    // Fall through to regex extraction for loosely-formatted JSON.
+  }
+  const summaryMatch = candidate.match(/"summary"\s*:\s*"([\s\S]*?)"/);
+  const summary = summaryMatch?.[1]
+    ?.replace(/\\"/g, "\"")
+    .replace(/\\n/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return summary && summary.length > 0 ? summary : null;
+}
+
+async function resolveIssueCommentRunId(
+  ctx: AppContext,
+  input: {
+    companyId: string;
+    actorType: "board" | "member" | "agent" | undefined;
+    actorId: string | undefined;
+    runIdHeader: string | undefined;
+  }
+) {
+  const runId = input.runIdHeader?.trim();
+  if (runId) {
+    const [run] = await ctx.db
+      .select({ id: heartbeatRuns.id, agentId: heartbeatRuns.agentId })
+      .from(heartbeatRuns)
+      .where(and(eq(heartbeatRuns.companyId, input.companyId), eq(heartbeatRuns.id, runId)))
+      .limit(1);
+    if (!run) {
+      return null;
+    }
+    if (input.actorType === "agent" && input.actorId && run.agentId !== input.actorId) {
+      return null;
+    }
+    return run.id;
+  }
+  if (input.actorType !== "agent" || !input.actorId) {
+    return null;
+  }
+  const [latestRun] = await ctx.db
+    .select({ id: heartbeatRuns.id })
+    .from(heartbeatRuns)
+    .where(
+      and(
+        eq(heartbeatRuns.companyId, input.companyId),
+        eq(heartbeatRuns.agentId, input.actorId),
+        eq(heartbeatRuns.status, "started")
+      )
+    )
+    .orderBy(desc(heartbeatRuns.startedAt))
+    .limit(1);
+  return latestRun?.id ?? null;
+}
+
+async function normalizeCommentRecipients(
+  ctx: AppContext,
+  companyId: string,
+  recipients: CommentRecipientInput[]
+): Promise<PersistedCommentRecipient[]> {
+  if (recipients.length === 0) {
+    return [] as PersistedCommentRecipient[];
   }
-  if (authorType === "agent" && actorId) {
-    return { authorType, authorId: actorId };
+  const deduped = dedupeCommentRecipients(recipients);
+  const agentIds = deduped
+    .filter((recipient) => recipient.recipientType === "agent" && recipient.recipientId)
+    .map((recipient) => recipient.recipientId as string);
+  if (agentIds.length > 0) {
+    const existingAgents = await ctx.db
+      .select({ id: agents.id })
+      .from(agents)
+      .where(and(eq(agents.companyId, companyId), inArray(agents.id, agentIds)));
+    const existingAgentIds = new Set(existingAgents.map((agent) => agent.id));
+    const missing = agentIds.find((id) => !existingAgentIds.has(id));
+    if (missing) {
+      throw new Error(`Recipient agent not found: ${missing}`);
+    }
   }
-  return { authorType, authorId: undefined };
+  return normalizeRecipientsForPersistence(deduped);
 }
 
 async function validateIssueAssignmentScope(