The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
refactor(server): move the queued-comment queue mutations into the wake-queue module (#13145)
Nicky Leach0d8bbf7cf4fb
diff --git a/server/src/__tests__/issue-queued-comments-routes.test.ts b/server/src/__tests__/issue-queued-comments-routes.test.tsindex 253efb7e2c..6db7e9432d 100644--- a/server/src/__tests__/issue-queued-comments-routes.test.ts+++ b/server/src/__tests__/issue-queued-comments-routes.test.ts@@ -313,6 +313,45 @@ describeEmbeddedPostgres("issue queued-comment routes", () => {expect(storedIssue?.executionRunId).toBeNull();});+ it("keeps a mutation response's steering disposition in step with a fresh GET after promotion", async () => {+ const seeded = await seedQueue();+ await promoteQueue(seeded);+ const initial = await request(app(seeded.companyId))+ .get(`/api/issues/${seeded.issueId}/queued-comments`);+ expect(initial.body.steeringDisposition).toBe("temporarily_unavailable");++ const edited = await request(app(seeded.companyId))+ .patch(`/api/issues/${seeded.issueId}/queued-comments/${seeded.commentIds[0]}`)+ .send({ queueId: seeded.wakeId, revision: initial.body.revision, body: "edited during promotion" });+ expect(edited.status, JSON.stringify(edited.body)).toBe(200);+ const afterEdit = await request(app(seeded.companyId))+ .get(`/api/issues/${seeded.issueId}/queued-comments`);+ expect(edited.body.steeringDisposition).toBe(afterEdit.body.steeringDisposition);++ const reordered = await request(app(seeded.companyId))+ .put(`/api/issues/${seeded.issueId}/queued-comments/order`)+ .send({+ queueId: seeded.wakeId,+ revision: edited.body.revision,+ orderedCommentIds: [...seeded.commentIds].reverse(),+ });+ expect(reordered.status, JSON.stringify(reordered.body)).toBe(200);+ const afterReorder = await request(app(seeded.companyId))+ .get(`/api/issues/${seeded.issueId}/queued-comments`);+ expect(reordered.body.steeringDisposition).toBe(afterReorder.body.steeringDisposition);+ });++ it("returns entry objects with the same keys as the GET endpoint", async () => {+ const seeded = await seedQueue();+ const initial = await request(app(seeded.companyId))+ .get(`/api/issues/${seeded.issueId}/queued-comments`);+ const edited = await request(app(seeded.companyId))+ .patch(`/api/issues/${seeded.issueId}/queued-comments/${seeded.commentIds[0]}`)+ .send({ queueId: seeded.wakeId, revision: initial.body.revision, body: "edited body" });+ expect(edited.status, JSON.stringify(edited.body)).toBe(200);+ expect(Object.keys(edited.body.entries[0]).sort()).toEqual(Object.keys(initial.body.entries[0]).sort());+ });+it("cancels the deferred wake when the final message is discarded before promotion", async () => {const seeded = await seedQueue();await db.delete(issueComments).where(eq(issueComments.id, seeded.commentIds[1]));diff --git a/server/src/modules/wake-queue/adapters/queued-comment-postgres.test.ts b/server/src/modules/wake-queue/adapters/queued-comment-postgres.test.tsnew file mode 100644index 0000000000..9ca96964b8--- /dev/null+++ b/server/src/modules/wake-queue/adapters/queued-comment-postgres.test.ts@@ -0,0 +1,285 @@+import { randomUUID } from "node:crypto";+import { eq } from "drizzle-orm";+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import type { Db } from "@paperclipai/db";+import { agentWakeupRequests, agents, companies, createDb, heartbeatRuns, issueComments, issues } from "@paperclipai/db";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "../../../__tests__/helpers/embedded-postgres.js";+import { createQueuedCommentIssueLockWriter } from "./queued-comment-postgres.js";+import type { QueuedCommentQueuePostgresAdapterDeps } from "./queued-comment-postgres.js";+import { QueuedCommentMutationError } from "../application/queued-comment-use-cases.js";++// Proves the same two properties the release-half adapter test proves for+// this module's other transaction: the one company the caller names in+// `issue.companyId` binds every read and write for the whole transaction, so+// a caller-supplied `issue`/`wake` for the wrong company sees nothing, and a+// guarded write that affects no row rolls the transaction back instead of+// leaving a partial write. The decision branching itself is proven against+// plain facts in `domain/policy.test.ts`; the use-case orchestration is+// proven against a mocked port in `application/queued-comment-use-cases.test.ts`.+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres queued-comment adapter tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describeEmbeddedPostgres("queued-comment postgres adapter", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;++ const noopDeps: QueuedCommentQueuePostgresAdapterDeps = {+ syncCommentReferences: async () => {},+ deleteCommentReferenceSource: async () => {},+ syncCommentExternalObjectsSafely: async () => {},+ };++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-queued-comment-postgres-adapter-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ await db.delete(issueComments);+ await db.delete(heartbeatRuns);+ await db.delete(agentWakeupRequests);+ await db.delete(issues);+ await db.delete(agents);+ await db.delete(companies);+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ async function seedCompany(): Promise<string> {+ const companyId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ defaultResponsibleUserId: "responsible-user",+ });+ return companyId;+ }++ async function seedAgent(input: { companyId: string; adapterType?: string }): Promise<string> {+ const agentId = randomUUID();+ await db.insert(agents).values({+ id: agentId,+ companyId: input.companyId,+ name: "CodexCoder",+ role: "engineer",+ status: "active",+ adapterType: input.adapterType ?? "codex_local",+ adapterConfig: {},+ runtimeConfig: { heartbeat: { wakeOnDemand: true, maxConcurrentRuns: 1 } },+ permissions: {},+ });+ return agentId;+ }++ async function seedIssue(input: { companyId: string; assigneeAgentId: string | null }): Promise<string> {+ const issueId = randomUUID();+ await db.insert(issues).values({+ id: issueId,+ companyId: input.companyId,+ title: "Queued-comment adapter fixture issue",+ status: "in_progress",+ priority: "medium",+ assigneeAgentId: input.assigneeAgentId,+ });+ return issueId;+ }++ async function seedComment(input: { companyId: string; issueId: string; authorUserId: string }): Promise<string> {+ const commentId = randomUUID();+ await db.insert(issueComments).values({+ id: commentId,+ companyId: input.companyId,+ issueId: input.issueId,+ authorUserId: input.authorUserId,+ body: "queued message",+ });+ return commentId;+ }++ async function seedDeferredWake(input: {+ companyId: string;+ agentId: string;+ issueId: string;+ commentIds: string[];+ }): Promise<string> {+ const id = randomUUID();+ await db.insert(agentWakeupRequests).values({+ id,+ companyId: input.companyId,+ agentId: input.agentId,+ source: "automation",+ reason: "issue_commented",+ status: "deferred_issue_execution",+ requestedByActorType: "user",+ payload: {+ issueId: input.issueId,+ _paperclipWakeContext: { wakeCommentIds: input.commentIds },+ },+ });+ return id;+ }++ it("scopes the wake lookup to its own company: a foreign-company issue context resolves not_pending and deletes nothing", async () => {+ const companyId = await seedCompany();+ const otherCompanyId = await seedCompany();+ const agentId = await seedAgent({ companyId });+ const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });+ const commentId = await seedComment({ companyId, issueId, authorUserId: "user-1" });+ const wakeId = await seedDeferredWake({ companyId, agentId, issueId, commentIds: [commentId] });++ const issueLock = createQueuedCommentIssueLockWriter(db, noopDeps);+ await expect(+ issueLock.withLockedQueue(+ {+ // The caller mistakenly names the *other* company on the issue+ // context; that single value binds every read and write for the+ // whole transaction, so it alone must decide what is visible.+ issue: { id: issueId, companyId: otherCompanyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ queueId: wakeId,+ },+ async () => {+ throw new Error("fn must not run when the wake is invisible to the caller's company");+ },+ ),+ ).rejects.toMatchObject({ code: "queued_comment_not_pending" });++ const commentRow = (await db.select().from(issueComments).where(eq(issueComments.id, commentId)))[0];+ expect(commentRow?.deletedAt ?? null).toBeNull();+ const wakeRow = (await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, wakeId)))[0];+ expect(wakeRow?.status).toBe("deferred_issue_execution");+ });++ it("rolls back a discard when the comment id given belongs to a different issue than the one this transaction locked", async () => {+ const companyId = await seedCompany();+ const agentId = await seedAgent({ companyId });+ const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });+ const otherIssueId = await seedIssue({ companyId, assigneeAgentId: agentId });+ const commentId = await seedComment({ companyId, issueId: otherIssueId, authorUserId: "user-1" });+ const wakeId = await seedDeferredWake({ companyId, agentId, issueId, commentIds: [commentId] });++ const issueLock = createQueuedCommentIssueLockWriter(db, noopDeps);+ await expect(+ issueLock.withLockedQueue(+ {+ issue: { id: issueId, companyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ queueId: wakeId,+ },+ async (_locked, transaction) => {+ // The comment belongs to a different issue than the one this+ // transaction locked. The write's own `issueId` predicate, not+ // just the bound company, must decide what is visible.+ const deleted = await transaction.deleteComment({ issueId, commentId });+ if (!deleted) {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ return deleted;+ },+ ),+ ).rejects.toMatchObject({ code: "queued_comment_not_pending" });++ const commentRow = (await db.select().from(issueComments).where(eq(issueComments.id, commentId)))[0];+ expect(commentRow).toBeDefined();+ expect(commentRow?.deletedAt ?? null).toBeNull();+ });++ it("edits the comment body, syncs references, and rebuilds the queue snapshot inside one company-scoped transaction", async () => {+ const companyId = await seedCompany();+ const agentId = await seedAgent({ companyId });+ const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });+ const commentId = await seedComment({ companyId, issueId, authorUserId: "user-1" });+ const wakeId = await seedDeferredWake({ companyId, agentId, issueId, commentIds: [commentId] });++ let syncedCommentId: string | null = null;+ const deps: QueuedCommentQueuePostgresAdapterDeps = {+ ...noopDeps,+ syncCommentReferences: async (id) => {+ syncedCommentId = id;+ },+ };+ const issueLock = createQueuedCommentIssueLockWriter(db, deps);++ const queue = await issueLock.withLockedQueue(+ {+ issue: { id: issueId, companyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ queueId: wakeId,+ },+ async (locked, transaction) => {+ expect(locked.state).toBe("deferred");+ const updated = await transaction.updateCommentBody({+ issueId,+ commentId,+ body: "edited body",+ updatedAt: new Date(),+ });+ expect(updated).toBe(true);+ await transaction.syncCommentReferences(commentId);+ return transaction.buildQueueSnapshot({+ issue: { id: issueId, companyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ wake: locked.wake,+ state: locked.state,+ queueRun: locked.queueRun,+ activeRun: locked.activeRun,+ });+ },+ );++ expect(syncedCommentId).toBe(commentId);+ expect(queue.entries).toHaveLength(1);+ expect((queue.entries[0]!.comment as { body: string }).body).toBe("edited body");+ const commentRow = (await db.select().from(issueComments).where(eq(issueComments.id, commentId)))[0];+ expect(commentRow?.body).toBe("edited body");+ });++ // Pins a fact the database itself cannot persist today: `runtime_mode` is+ // a NOT NULL column, so a real active run's own field is never null. The+ // port type allows it (`runtimeMode: string | null`), so this test builds+ // the fact directly instead of through a database row, to keep this+ // branch of the shared steering rule under a regression test.+ it("answers the steering question for a deferred paperclip_runner queue whose active run has no persisted runtime mode yet", async () => {+ const companyId = await seedCompany();+ const agentId = await seedAgent({ companyId, adapterType: "paperclip_runner" });+ const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });+ const commentId = await seedComment({ companyId, issueId, authorUserId: "user-1" });+ const wakeId = await seedDeferredWake({ companyId, agentId, issueId, commentIds: [commentId] });++ const issueLock = createQueuedCommentIssueLockWriter(db, noopDeps);+ const queue = await issueLock.withLockedQueue(+ {+ issue: { id: issueId, companyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ queueId: wakeId,+ },+ async (locked, transaction) => {+ expect(locked.state).toBe("deferred");+ return transaction.buildQueueSnapshot({+ issue: { id: issueId, companyId, assigneeAgentId: agentId, executionRunId: null },+ actor: { actorType: "user", actorId: "user-1", agentId: null },+ wake: locked.wake,+ state: "deferred",+ queueRun: null,+ activeRun: { id: randomUUID(), status: "running", runtimeMode: null, contextSnapshot: {} },+ });+ },+ );++ expect(queue.protocol).toBe("paperclip_runner_v1");+ expect(queue.steeringDisposition).toBe("temporarily_unavailable");+ });+});diff --git a/server/src/modules/wake-queue/adapters/queued-comment-postgres.ts b/server/src/modules/wake-queue/adapters/queued-comment-postgres.tsnew file mode 100644index 0000000000..0d8d4e01c8--- /dev/null+++ b/server/src/modules/wake-queue/adapters/queued-comment-postgres.ts@@ -0,0 +1,287 @@+import { and, eq, inArray } from "drizzle-orm";+import type { Db } from "@paperclipai/db";+import { agentWakeupRequests, agents, heartbeatRuns, issueComments, issues } from "@paperclipai/db";+import type { IssueComment, IssueQueuedCommentQueue } from "@paperclipai/shared";+import {+ buildQueuedCommentQueueSnapshot,+ decideQueuedCommentQueueSteering,+ queuedCommentIdsFromWakePayload,+ withQueuedCommentIdsInRunContext,+ withQueuedCommentIdsInWakePayload,+} from "../../../services/issue-queued-comment-queue.js";+import { decideQueuedCommentWakeLookup } from "../domain/policy.js";+import { parseObject, readNonEmptyString } from "../domain/values.js";+import { QueuedCommentMutationError } from "../application/queued-comment-use-cases.js";+import type {+ LockedQueuedCommentState,+ QueuedCommentIssueLockWriter,+ QueuedCommentQueueTransaction,+ QueuedCommentRunRow,+ QueuedCommentWakeRow,+} from "../application/queued-comment-ports.js";++type WakeRow = typeof agentWakeupRequests.$inferSelect;+type RunRow = typeof heartbeatRuns.$inferSelect;++function toWakeRow(row: WakeRow): QueuedCommentWakeRow {+ return { id: row.id, agentId: row.agentId, status: row.status, runId: row.runId, payload: parseObject(row.payload) };+}++function toRunRow(row: RunRow): QueuedCommentRunRow {+ return { id: row.id, status: row.status, runtimeMode: row.runtimeMode, contextSnapshot: parseObject(row.contextSnapshot) };+}++export type QueuedCommentQueuePostgresAdapterDeps = {+ /** `issueReferenceService(db).syncComment`; runs on the module's own transaction. */+ syncCommentReferences(commentId: string, tx: Db): Promise<void>;+ /** `issueReferenceService(db).deleteCommentSource`; runs on the module's own transaction. */+ deleteCommentReferenceSource(commentId: string, tx: Db): Promise<void>;+ /** `externalObjectService(db, opts).syncCommentSafely`; runs on the module's own transaction. */+ syncCommentExternalObjectsSafely(commentId: string, tx: Db): Promise<void>;+};++function buildTransaction(tx: Db, companyId: string, deps: QueuedCommentQueuePostgresAdapterDeps): QueuedCommentQueueTransaction {+ return {+ async updateCommentBody({ issueId, commentId, body, updatedAt }) {+ const updated = await tx+ .update(issueComments)+ .set({ body, updatedAt })+ .where(and(eq(issueComments.id, commentId), eq(issueComments.issueId, issueId), eq(issueComments.companyId, companyId)))+ .returning({ id: issueComments.id })+ .then((rows) => rows[0] ?? null);+ return updated !== null;+ },++ async touchIssueUpdatedAt({ issueId, updatedAt }) {+ await tx.update(issues).set({ updatedAt }).where(and(eq(issues.id, issueId), eq(issues.companyId, companyId)));+ },++ async updateWakeQueuedCommentIds({ wakeId, payload, ids, updatedAt }) {+ const row = await tx+ .update(agentWakeupRequests)+ .set({ payload: withQueuedCommentIdsInWakePayload(payload, ids), updatedAt })+ .where(and(eq(agentWakeupRequests.id, wakeId), eq(agentWakeupRequests.companyId, companyId)))+ .returning()+ .then((rows) => rows[0]);+ return toWakeRow(row);+ },++ async updateQueueRunCommentIds({ queueRunId, contextSnapshot, ids, updatedAt }) {+ const row = await tx+ .update(heartbeatRuns)+ .set({ contextSnapshot: withQueuedCommentIdsInRunContext(contextSnapshot, ids), updatedAt })+ .where(and(eq(heartbeatRuns.id, queueRunId), eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.status, "queued")))+ .returning()+ .then((rows) => rows[0] ?? null);+ return row ? toRunRow(row) : null;+ },++ async deleteComment({ issueId, commentId }) {+ const row = await tx+ .delete(issueComments)+ .where(and(eq(issueComments.id, commentId), eq(issueComments.issueId, issueId), eq(issueComments.companyId, companyId)))+ .returning()+ .then((rows) => rows[0] ?? null);+ return row ? (row as IssueComment) : null;+ },++ async cancelWake({ wakeId, reason, now }) {+ await tx+ .update(agentWakeupRequests)+ .set({ status: "cancelled", finishedAt: now, error: reason, updatedAt: now })+ .where(and(eq(agentWakeupRequests.id, wakeId), eq(agentWakeupRequests.companyId, companyId)));+ },++ async cancelQueueRun({ queueRunId, reason, now }) {+ const row = await tx+ .update(heartbeatRuns)+ .set({ status: "cancelled", finishedAt: now, error: reason, errorCode: "queued_comment_discarded", updatedAt: now })+ .where(and(eq(heartbeatRuns.id, queueRunId), eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.status, "queued")))+ .returning({ id: heartbeatRuns.id })+ .then((rows) => rows[0] ?? null);+ return row ? { id: row.id } : null;+ },++ async clearExecutionLockAndTouchIssue({ issueId, executionRunId, updatedAt }) {+ await tx+ .update(issues)+ .set({ executionRunId: null, executionAgentNameKey: null, executionLockedAt: null, updatedAt })+ .where(and(eq(issues.id, issueId), eq(issues.companyId, companyId), eq(issues.executionRunId, executionRunId)));+ },++ async buildQueueSnapshot({ issue, actor, wake, state, queueRun, activeRun }): Promise<IssueQueuedCommentQueue> {+ const commentIds = queuedCommentIdsFromWakePayload(wake?.payload ?? null);+ const rows =+ commentIds.length > 0+ ? await tx+ .select()+ .from(issueComments)+ .where(+ and(+ eq(issueComments.companyId, companyId),+ eq(issueComments.issueId, issue.id),+ inArray(issueComments.id, commentIds),+ ),+ )+ : [];+ const byId = new Map(rows.map((row) => [row.id, row]));+ const comments = commentIds.flatMap((id) => {+ const row = byId.get(id);+ return row && !row.deletedAt ? [row] : [];+ });++ const assignedAgent = issue.assigneeAgentId+ ? await tx+ .select({ adapterType: agents.adapterType })+ .from(agents)+ .where(and(eq(agents.id, issue.assigneeAgentId), eq(agents.companyId, companyId)))+ .limit(1)+ .then((agentRows) => agentRows[0] ?? null)+ : null;++ // A queue mutation never delivers same-turn steering itself, so this+ // adapter never probes the live runner: it answers+ // "temporarily_unavailable" wherever the shared rule says a caller+ // may probe. Only the read path probes the live provider.+ const steering = decideQueuedCommentQueueSteering({+ state,+ queueRunRuntimeMode: queueRun?.runtimeMode ?? null,+ activeRun,+ assignedAgentAdapterType: assignedAgent?.adapterType ?? null,+ queuedCommentCount: comments.length,+ });+ const steeringDisposition: IssueQueuedCommentQueue["steeringDisposition"] =+ steering.kind === "probe" ? "temporarily_unavailable" : steering.kind;++ return buildQueuedCommentQueueSnapshot({+ issueId: issue.id,+ queueId: wake?.id ?? null,+ state,+ activeRunId: activeRun?.id ?? null,+ protocol: steering.protocol,+ steeringDisposition,+ comments,+ actorType: actor.actorType,+ actorId: actor.actorId,+ });+ },++ async syncCommentReferences(commentId) {+ await deps.syncCommentReferences(commentId, tx);+ },+ async deleteCommentReferenceSource(commentId) {+ await deps.deleteCommentReferenceSource(commentId, tx);+ },+ async syncCommentExternalObjectsSafely(commentId) {+ await deps.syncCommentExternalObjectsSafely(commentId, tx);+ },+ };+}++export function createQueuedCommentIssueLockWriter(db: Db, deps: QueuedCommentQueuePostgresAdapterDeps): QueuedCommentIssueLockWriter {+ return {+ async withLockedQueue(input, fn) {+ return db.transaction(async (rawTx) => {+ const tx = rawTx as unknown as Db;+ const companyId = input.issue.companyId;++ await tx+ .select({ id: issues.id })+ .from(issues)+ .where(and(eq(issues.id, input.issue.id), eq(issues.companyId, companyId)))+ .for("update");++ const wakeRow = await tx+ .select()+ .from(agentWakeupRequests)+ .where(+ and(+ eq(agentWakeupRequests.id, input.queueId),+ eq(agentWakeupRequests.companyId, companyId),+ input.issue.assigneeAgentId ? eq(agentWakeupRequests.agentId, input.issue.assigneeAgentId) : undefined,+ ),+ )+ .for("update")+ .limit(1)+ .then((rows) => rows[0] ?? null);++ const wakePayload = parseObject(wakeRow?.payload);+ const lookup = decideQueuedCommentWakeLookup({+ wakePresent: wakeRow !== null,+ wakeIssueIdMatches: readNonEmptyString(wakePayload.issueId) === input.issue.id,+ hasQueuedCommentIds: queuedCommentIdsFromWakePayload(wakeRow?.payload ?? null).length > 0,+ wakeStatus: wakeRow?.status ?? null,+ wakeHasRunId: Boolean(wakeRow?.runId),+ });++ if (lookup.kind === "not_pending") {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ if (lookup.kind === "already_dispatching") {+ throw new QueuedCommentMutationError("queued_comment_already_dispatching", "The queued message is already being dispatched");+ }++ // Unreachable: `decideQueuedCommentWakeLookup` only returns "deferred" or "check_queue_run" when the wake row is present.+ if (!wakeRow) throw new Error("wake-queue: queued-comment lookup resolved without a wake row");++ let state: "deferred" | "queued";+ let queueRunRow: RunRow | null = null;++ if (lookup.kind === "deferred") {+ state = "deferred";+ } else {+ // check_queue_run: `wakeHasRunId` was true for this branch to have been reached.+ queueRunRow = await tx+ .select()+ .from(heartbeatRuns)+ .where(+ and(+ eq(heartbeatRuns.id, wakeRow.runId!),+ eq(heartbeatRuns.companyId, companyId),+ eq(heartbeatRuns.agentId, wakeRow.agentId),+ eq(heartbeatRuns.wakeupRequestId, wakeRow.id),+ ),+ )+ .for("update")+ .limit(1)+ .then((rows) => rows[0] ?? null);+ if (!queueRunRow || queueRunRow.status !== "queued") {+ throw new QueuedCommentMutationError(+ "queued_comment_already_dispatching",+ "The queued message is already being dispatched",+ );+ }+ state = "queued";+ }++ const activeRunId = state === "deferred" ? input.issue.executionRunId : null;+ const activeRunRow = activeRunId+ ? await tx+ .select()+ .from(heartbeatRuns)+ .where(and(eq(heartbeatRuns.id, activeRunId), eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.status, "running")))+ .for("update")+ .limit(1)+ .then((rows) => rows[0] ?? null)+ : null;++ const transaction = buildTransaction(tx, companyId, deps);+ const wake = toWakeRow(wakeRow);+ const queueRun = queueRunRow ? toRunRow(queueRunRow) : null;+ const activeRun = activeRunRow ? toRunRow(activeRunRow) : null;++ const queue = await transaction.buildQueueSnapshot({+ issue: input.issue,+ actor: input.actor,+ wake,+ state,+ queueRun,+ activeRun,+ });++ const locked: LockedQueuedCommentState = { wake, state, queueRun, activeRun, queue };+ return fn(locked, transaction);+ });+ },+ };+}diff --git a/server/src/modules/wake-queue/application/queued-comment-ports.ts b/server/src/modules/wake-queue/application/queued-comment-ports.tsnew file mode 100644index 0000000000..36ca88c440--- /dev/null+++ b/server/src/modules/wake-queue/application/queued-comment-ports.ts@@ -0,0 +1,145 @@+// Ports for the three queued-comment queue mutations (edit, reorder,+// discard). Mirrors the release half's `IssueLockWriter` shape: the adapter+// owns the one transaction each mutation runs in, locks the issue and the+// wake row the caller named, classifies the locked state, and hands the+// caller a `LockedQueuedCommentState` plus a `QueuedCommentQueueTransaction`+// bound to that same transaction for every further read and write.++import type { IssueComment, IssueQueuedCommentEntry, IssueQueuedCommentQueue } from "@paperclipai/shared";++export type QueuedCommentActor = {+ actorType: "agent" | "user";+ /** The user id for a user actor, the agent id for an agent actor -- the same value `getActorInfo` names `actorId`. */+ actorId: string;+ /** Null for a user actor. */+ agentId: string | null;+};++export type QueuedCommentIssueContext = {+ id: string;+ companyId: string;+ assigneeAgentId: string | null;+ executionRunId: string | null;+};++export type QueuedCommentWakeRow = {+ id: string;+ agentId: string;+ status: string;+ runId: string | null;+ payload: Record<string, unknown>;+};++export type QueuedCommentRunRow = {+ id: string;+ status: string;+ runtimeMode: string | null;+ contextSnapshot: Record<string, unknown>;+};++/** The module's entry shape is the shared contract, so the compiler checks it directly; the route needs no cast. */+export type QueuedCommentEntrySnapshot = IssueQueuedCommentEntry;++/** The module's queue-snapshot shape is the shared contract, so the compiler checks it directly; the route needs no cast. */+export type QueuedCommentQueueSnapshot = IssueQueuedCommentQueue;++/** The locked, transaction-scoped state a mutation reads before it decides what to write. */+export type LockedQueuedCommentState = {+ wake: QueuedCommentWakeRow;+ state: "deferred" | "queued";+ queueRun: QueuedCommentRunRow | null;+ activeRun: QueuedCommentRunRow | null;+ queue: QueuedCommentQueueSnapshot;+};++/**+ * Every member is bound to the one transaction `withLockedQueue` owns, and+ * to the one company that transaction is open for. Every read and every+ * write names that bound `companyId` in its own predicate; a+ * caller-supplied `issue`/`wake`/`queueRun` value is never trusted as an+ * authorization boundary by itself.+ */+export interface QueuedCommentQueueTransaction {+ updateCommentBody(input: {+ issueId: string;+ commentId: string;+ body: string;+ updatedAt: Date;+ }): Promise<boolean>;+ touchIssueUpdatedAt(input: { issueId: string; updatedAt: Date }): Promise<void>;+ /** Compare-and-set on `id`; the wake's current status is not re-checked here because the row is already locked for the duration of this transaction. */+ updateWakeQueuedCommentIds(input: {+ wakeId: string;+ payload: Record<string, unknown>;+ ids: string[];+ updatedAt: Date;+ }): Promise<QueuedCommentWakeRow>;+ /** Guarded on the run's current `queued` status. Returns `null` when a concurrent writer already moved the run off `queued`. */+ updateQueueRunCommentIds(input: {+ queueRunId: string;+ /** The run's own context snapshot, as already read under lock; the rewrite is derived from this base. */+ contextSnapshot: Record<string, unknown>;+ ids: string[];+ updatedAt: Date;+ }): Promise<QueuedCommentRunRow | null>;+ /** Returns the full deleted comment row so the caller can echo it back as the delete route's response body. */+ deleteComment(input: {+ issueId: string;+ commentId: string;+ }): Promise<IssueComment | null>;+ cancelWake(input: { wakeId: string; reason: string; now: Date }): Promise<void>;+ /**+ * Guarded on the run's current `queued` status. Returns `null` when a+ * concurrent writer already moved the run off `queued`; returns just the+ * cancelled run's id, which is all a post-commit telemetry emission needs.+ */+ cancelQueueRun(input: {+ queueRunId: string;+ reason: string;+ now: Date;+ }): Promise<{ id: string } | null>;+ /**+ * Clears the issue's execution-lock columns and performs the `updatedAt`+ * touch, in the one update the original route issued for a discard that+ * empties the queue with a live queue run. The write is guarded on the+ * issue's current `executionRunId`; a lost guard silently skips the whole+ * update, matching the pre-existing behavior of this best-effort touch.+ */+ clearExecutionLockAndTouchIssue(input: {+ issueId: string;+ executionRunId: string;+ updatedAt: Date;+ }): Promise<void>;+ buildQueueSnapshot(input: {+ issue: QueuedCommentIssueContext;+ actor: QueuedCommentActor;+ wake: QueuedCommentWakeRow | null;+ state: "deferred" | "queued" | null;+ queueRun: QueuedCommentRunRow | null;+ activeRun: QueuedCommentRunRow | null;+ }): Promise<QueuedCommentQueueSnapshot>;+ syncCommentReferences(commentId: string): Promise<void>;+ deleteCommentReferenceSource(commentId: string): Promise<void>;+ syncCommentExternalObjectsSafely(commentId: string): Promise<void>;+}++export interface QueuedCommentIssueLockWriter {+ /**+ * Opens the one transaction a mutation runs in: locks the issue row, locks+ * the wake row named by `queueId`, classifies it (reading and locking the+ * linked heartbeat run when the classification needs it), and builds the+ * queue snapshot the caller's mutation target check compares against.+ * Throws `QueuedCommentMutationError` with code `queued_comment_not_pending`+ * or `queued_comment_already_dispatching` when the lock step itself cannot+ * resolve a live queue; `fn` never runs in that case.+ */+ withLockedQueue<T>(+ input: {+ /** Also carries the company id; every locked read and write binds its `companyId` predicate to `issue.companyId`. */+ issue: QueuedCommentIssueContext;+ actor: QueuedCommentActor;+ queueId: string;+ },+ fn: (locked: LockedQueuedCommentState, transaction: QueuedCommentQueueTransaction) => Promise<T>,+ ): Promise<T>;+}diff --git a/server/src/modules/wake-queue/application/queued-comment-use-cases.test.ts b/server/src/modules/wake-queue/application/queued-comment-use-cases.test.tsnew file mode 100644index 0000000000..6be0b8ba2a--- /dev/null+++ b/server/src/modules/wake-queue/application/queued-comment-use-cases.test.ts@@ -0,0 +1,374 @@+import { describe, expect, it, vi } from "vitest";+import type { IssueComment } from "@paperclipai/shared";+import {+ createDiscardQueuedComment,+ createEditQueuedComment,+ createReorderQueuedComments,+ QueuedCommentMutationError,+ QueuedCommentMutationForbiddenError,+} from "./queued-comment-use-cases.js";+import type {+ LockedQueuedCommentState,+ QueuedCommentActor,+ QueuedCommentEntrySnapshot,+ QueuedCommentIssueContext,+ QueuedCommentIssueLockWriter,+ QueuedCommentQueueSnapshot,+ QueuedCommentQueueTransaction,+ QueuedCommentRunRow,+ QueuedCommentWakeRow,+} from "./queued-comment-ports.js";++const ISSUE: QueuedCommentIssueContext = {+ id: "issue-1",+ companyId: "company-1",+ assigneeAgentId: "agent-1",+ executionRunId: null,+};++const USER_ACTOR: QueuedCommentActor = { actorType: "user", actorId: "user-1", agentId: null };+const AGENT_ACTOR: QueuedCommentActor = { actorType: "agent", actorId: "agent-1", agentId: "agent-1" };++function wakeRow(overrides: Partial<QueuedCommentWakeRow> = {}): QueuedCommentWakeRow {+ return { id: "wake-1", agentId: "agent-1", status: "deferred_issue_execution", runId: null, payload: {}, ...overrides };+}++function runRow(overrides: Partial<QueuedCommentRunRow> = {}): QueuedCommentRunRow {+ return { id: "run-1", status: "queued", runtimeMode: null, contextSnapshot: {}, ...overrides };+}++function commentFixture(overrides: Partial<IssueComment> = {}): IssueComment {+ return {+ id: "comment-1",+ companyId: "company-1",+ issueId: "issue-1",+ authorType: "user",+ authorAgentId: null,+ authorUserId: "user-1",+ body: "queued comment",+ presentation: null,+ metadata: null,+ createdAt: new Date("2026-01-01T00:00:00Z"),+ updatedAt: new Date("2026-01-01T00:00:00Z"),+ ...overrides,+ };+}++function entry(overrides: Partial<QueuedCommentEntrySnapshot> = {}): QueuedCommentEntrySnapshot {+ return {+ comment: commentFixture(),+ position: 0,+ canEdit: true,+ canDiscard: true,+ ...overrides,+ };+}++function queueSnapshot(overrides: Partial<QueuedCommentQueueSnapshot> = {}): QueuedCommentQueueSnapshot {+ return {+ issueId: ISSUE.id,+ queueId: "wake-1",+ state: "deferred",+ targetRunId: null,+ revision: "rev-1",+ protocol: "legacy",+ steeringDisposition: "unsupported",+ entries: [entry()],+ ...overrides,+ };+}++function lockedState(overrides: Partial<LockedQueuedCommentState> = {}): LockedQueuedCommentState {+ return {+ wake: wakeRow(),+ state: "deferred",+ queueRun: null,+ activeRun: null,+ queue: queueSnapshot(),+ ...overrides,+ };+}++function createFakeTransaction(overrides: Partial<QueuedCommentQueueTransaction> = {}): QueuedCommentQueueTransaction {+ return {+ updateCommentBody: vi.fn(async () => true),+ touchIssueUpdatedAt: vi.fn(async () => {}),+ updateWakeQueuedCommentIds: vi.fn(async (input) => wakeRow({ id: input.wakeId })),+ updateQueueRunCommentIds: vi.fn(async (input) => runRow({ id: input.queueRunId })),+ deleteComment: vi.fn(async () => commentFixture()),+ cancelWake: vi.fn(async () => {}),+ cancelQueueRun: vi.fn(async () => ({ id: "run-1" })),+ clearExecutionLockAndTouchIssue: vi.fn(async () => {}),+ buildQueueSnapshot: vi.fn(async () => queueSnapshot()),+ syncCommentReferences: vi.fn(async () => {}),+ deleteCommentReferenceSource: vi.fn(async () => {}),+ syncCommentExternalObjectsSafely: vi.fn(async () => {}),+ ...overrides,+ };+}++function createFakeIssueLock(locked: LockedQueuedCommentState, transaction: QueuedCommentQueueTransaction): QueuedCommentIssueLockWriter {+ return {+ withLockedQueue: vi.fn(async (_input, fn) => fn(locked, transaction)),+ };+}++describe("editQueuedComment", () => {+ it("updates the comment body and rebuilds the queue snapshot", async () => {+ const locked = lockedState();+ const transaction = createFakeTransaction();+ const issueLock = createFakeIssueLock(locked, transaction);+ const editQueuedComment = createEditQueuedComment({ issueLock });++ const result = await editQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ body: "updated body",+ now: new Date("2026-01-01T00:00:00Z"),+ });++ expect(transaction.updateCommentBody).toHaveBeenCalledWith(+ expect.objectContaining({ issueId: "issue-1", commentId: "comment-1", body: "updated body" }),+ );+ expect(transaction.syncCommentReferences).toHaveBeenCalledWith("comment-1");+ expect(transaction.syncCommentExternalObjectsSafely).toHaveBeenCalledWith("comment-1");+ expect(result).toEqual(queueSnapshot());+ });++ it("rejects a stale queue id with queued_comment_stale_queue", async () => {+ const locked = lockedState({ queue: queueSnapshot({ queueId: "wake-1" }) });+ const editQueuedComment = createEditQueuedComment({ issueLock: createFakeIssueLock(locked, createFakeTransaction()) });++ await expect(+ editQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-2",+ revision: "rev-1",+ body: "x",+ now: new Date(),+ }),+ ).rejects.toMatchObject({ code: "queued_comment_stale_queue" });+ });++ it("rejects a stale revision with queued_comment_revision_conflict", async () => {+ const locked = lockedState();+ const editQueuedComment = createEditQueuedComment({ issueLock: createFakeIssueLock(locked, createFakeTransaction()) });++ await expect(+ editQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "stale-rev",+ body: "x",+ now: new Date(),+ }),+ ).rejects.toBeInstanceOf(QueuedCommentMutationError);+ });++ it("rejects a comment the actor cannot edit", async () => {+ const locked = lockedState({ queue: queueSnapshot({ entries: [entry({ canEdit: false })] }) });+ const editQueuedComment = createEditQueuedComment({ issueLock: createFakeIssueLock(locked, createFakeTransaction()) });++ await expect(+ editQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ body: "x",+ now: new Date(),+ }),+ ).rejects.toBeInstanceOf(QueuedCommentMutationForbiddenError);+ });++ it("surfaces queued_comment_already_dispatching when the linked run left the queued status mid-mutation", async () => {+ const locked = lockedState({ queueRun: runRow({ id: "run-1" }) });+ const transaction = createFakeTransaction({ updateQueueRunCommentIds: vi.fn(async () => null) });+ const editQueuedComment = createEditQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ await expect(+ editQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ body: "x",+ now: new Date(),+ }),+ ).rejects.toMatchObject({ code: "queued_comment_already_dispatching" });+ });+});++describe("reorderQueuedComments", () => {+ it("rewrites the wake payload with the submitted order", async () => {+ const locked = lockedState({+ queue: queueSnapshot({ entries: [+ entry({ comment: commentFixture({ id: "a" }), position: 0 }),+ entry({ comment: commentFixture({ id: "b" }), position: 1 }),+ ] }),+ });+ const transaction = createFakeTransaction();+ const reorderQueuedComments = createReorderQueuedComments({ issueLock: createFakeIssueLock(locked, transaction) });++ await reorderQueuedComments({+ issue: ISSUE,+ actor: USER_ACTOR,+ queueId: "wake-1",+ revision: "rev-1",+ orderedCommentIds: ["b", "a"],+ now: new Date(),+ });++ expect(transaction.updateWakeQueuedCommentIds).toHaveBeenCalledWith(+ expect.objectContaining({ wakeId: "wake-1", ids: ["b", "a"] }),+ );+ });++ it("rejects an order that is not a permutation of the current queue", async () => {+ const locked = lockedState({ queue: queueSnapshot({ entries: [+ entry({ comment: commentFixture({ id: "a" }) }),+ entry({ comment: commentFixture({ id: "b" }) }),+ ] }) });+ const reorderQueuedComments = createReorderQueuedComments({ issueLock: createFakeIssueLock(locked, createFakeTransaction()) });++ await expect(+ reorderQueuedComments({+ issue: ISSUE,+ actor: USER_ACTOR,+ queueId: "wake-1",+ revision: "rev-1",+ orderedCommentIds: ["a"],+ now: new Date(),+ }),+ ).rejects.toMatchObject({ code: "queued_comment_order_mismatch" });+ });+});++describe("discardQueuedComment", () => {+ it("cancels the wake and the queued run when the discard empties the queue", async () => {+ const locked = lockedState({ state: "queued", queueRun: runRow({ id: "run-1" }) });+ const transaction = createFakeTransaction();+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ const result = await discardQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ now: new Date(),+ });++ expect(transaction.cancelWake).toHaveBeenCalledWith(expect.objectContaining({ wakeId: "wake-1" }));+ expect(transaction.cancelQueueRun).toHaveBeenCalledWith(expect.objectContaining({ queueRunId: "run-1" }));+ expect(transaction.clearExecutionLockAndTouchIssue).toHaveBeenCalledWith(+ expect.objectContaining({ executionRunId: "run-1" }),+ );+ expect(result.cancelledRun).toEqual({ id: "run-1" });+ });++ it("rewrites the remaining ids when other queued comments are left", async () => {+ const locked = lockedState({+ queue: queueSnapshot({ entries: [+ entry({ comment: commentFixture({ id: "comment-1" }) }),+ entry({ comment: commentFixture({ id: "comment-2" }) }),+ ] }),+ });+ const transaction = createFakeTransaction();+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ const result = await discardQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ now: new Date(),+ });++ expect(transaction.updateWakeQueuedCommentIds).toHaveBeenCalledWith(expect.objectContaining({ ids: ["comment-2"] }));+ expect(transaction.cancelWake).not.toHaveBeenCalled();+ expect(transaction.touchIssueUpdatedAt).toHaveBeenCalledWith(expect.objectContaining({ issueId: ISSUE.id }));+ expect(result.cancelledRun).toBeNull();+ });++ it("skips the mutation-target check when no revision is submitted, matching the comment-delete route's cancellation call site", async () => {+ const locked = lockedState({ queue: queueSnapshot({ revision: "some-other-revision" }) });+ const transaction = createFakeTransaction();+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ await expect(+ discardQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ now: new Date(),+ }),+ ).resolves.toBeDefined();+ });++ it("rejects a discard from an actor who did not author the comment", async () => {+ const locked = lockedState({ queue: queueSnapshot({ entries: [+ entry({ comment: commentFixture({ authorUserId: "user-2", authorAgentId: null }) }),+ ] }) });+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, createFakeTransaction()) });++ await expect(+ discardQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ now: new Date(),+ }),+ ).rejects.toBeInstanceOf(QueuedCommentMutationForbiddenError);+ });++ it("authorizes an agent actor discarding its own queued message", async () => {+ const locked = lockedState({+ queue: queueSnapshot({ entries: [+ entry({ comment: commentFixture({ authorUserId: null, authorAgentId: "agent-1" }) }),+ ] }),+ });+ const transaction = createFakeTransaction();+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ await expect(+ discardQueuedComment({+ issue: ISSUE,+ actor: AGENT_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ now: new Date(),+ }),+ ).resolves.toBeDefined();+ });++ it("rolls back when the queued run to cancel already left the queued status", async () => {+ const locked = lockedState({ queueRun: runRow({ id: "run-1" }) });+ const transaction = createFakeTransaction({ cancelQueueRun: vi.fn(async () => null) });+ const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });++ await expect(+ discardQueuedComment({+ issue: ISSUE,+ actor: USER_ACTOR,+ commentId: "comment-1",+ queueId: "wake-1",+ revision: "rev-1",+ now: new Date(),+ }),+ ).rejects.toMatchObject({ code: "queued_comment_already_dispatching" });+ });+});diff --git a/server/src/modules/wake-queue/application/queued-comment-use-cases.ts b/server/src/modules/wake-queue/application/queued-comment-use-cases.tsnew file mode 100644index 0000000000..9d9b6a3f94--- /dev/null+++ b/server/src/modules/wake-queue/application/queued-comment-use-cases.ts@@ -0,0 +1,285 @@+import type { IssueComment } from "@paperclipai/shared";+import {+ decideQueuedCommentActorOwnsEntry,+ decideQueuedCommentReorder,+} from "../domain/policy.js";+import type {+ QueuedCommentActor,+ QueuedCommentIssueContext,+ QueuedCommentIssueLockWriter,+ QueuedCommentQueueSnapshot,+ QueuedCommentQueueTransaction,+ QueuedCommentRunRow,+} from "./queued-comment-ports.js";++export type QueuedCommentMutationErrorCode =+ | "queued_comment_not_pending"+ | "queued_comment_already_dispatching"+ | "queued_comment_stale_queue"+ | "queued_comment_revision_conflict"+ | "queued_comment_order_mismatch";++/** The route maps this 1:1 onto the `conflict(...)` HTTP error it threw before this move, using `code` and `message` unchanged. */+export class QueuedCommentMutationError extends Error {+ constructor(+ readonly code: QueuedCommentMutationErrorCode,+ message: string,+ ) {+ super(message);+ this.name = "QueuedCommentMutationError";+ }+}++/** The route maps this onto the `forbidden(...)` HTTP error it threw before this move, using `message` unchanged. */+export class QueuedCommentMutationForbiddenError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "QueuedCommentMutationForbiddenError";+ }+}++function requireMutationTarget(queue: QueuedCommentQueueSnapshot, queueId: string, revision: string): void {+ if (queue.queueId !== queueId) {+ throw new QueuedCommentMutationError("queued_comment_stale_queue", "The queued message targets a stale queue");+ }+ if (queue.revision !== revision) {+ throw new QueuedCommentMutationError("queued_comment_revision_conflict", "The queued messages changed in another session");+ }+}++async function updateQueueRunCommentIdsGuarded(+ tx: QueuedCommentQueueTransaction,+ input: { queueRun: QueuedCommentRunRow | null; ids: string[]; updatedAt: Date },+): Promise<QueuedCommentRunRow | null> {+ if (!input.queueRun) return null;+ const updated = await tx.updateQueueRunCommentIds({+ queueRunId: input.queueRun.id,+ contextSnapshot: input.queueRun.contextSnapshot,+ ids: input.ids,+ updatedAt: input.updatedAt,+ });+ if (!updated) {+ throw new QueuedCommentMutationError("queued_comment_already_dispatching", "The queued message is already being dispatched");+ }+ return updated;+}++export type EditQueuedCommentInput = {+ issue: QueuedCommentIssueContext;+ actor: QueuedCommentActor;+ commentId: string;+ queueId: string;+ revision: string;+ body: string;+ now: Date;+};++export function createEditQueuedComment(deps: { issueLock: QueuedCommentIssueLockWriter }) {+ return async function editQueuedComment(input: EditQueuedCommentInput): Promise<QueuedCommentQueueSnapshot> {+ return deps.issueLock.withLockedQueue(+ { issue: input.issue, actor: input.actor, queueId: input.queueId },+ async (locked, tx) => {+ requireMutationTarget(locked.queue, input.queueId, input.revision);+ const entry = locked.queue.entries.find((candidate) => candidate.comment.id === input.commentId);+ if (!entry) {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ if (!entry.canEdit) {+ throw new QueuedCommentMutationForbiddenError("Only the queued message author can edit it");+ }++ const updated = await tx.updateCommentBody({+ issueId: input.issue.id,+ commentId: input.commentId,+ body: input.body,+ updatedAt: input.now,+ });+ if (!updated) {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ await tx.touchIssueUpdatedAt({ issueId: input.issue.id, updatedAt: input.now });+ await tx.syncCommentReferences(input.commentId);+ await tx.syncCommentExternalObjectsSafely(input.commentId);++ const ids = locked.queue.entries.map((candidate) => candidate.comment.id);+ const updatedQueueRun = await updateQueueRunCommentIdsGuarded(tx, {+ queueRun: locked.queueRun,+ ids,+ updatedAt: input.now,+ });++ return tx.buildQueueSnapshot({+ issue: input.issue,+ actor: input.actor,+ wake: locked.wake,+ state: locked.state,+ queueRun: updatedQueueRun ?? locked.queueRun,+ activeRun: locked.activeRun,+ });+ },+ );+ };+}++export type ReorderQueuedCommentsInput = {+ issue: QueuedCommentIssueContext;+ actor: QueuedCommentActor;+ queueId: string;+ revision: string;+ orderedCommentIds: string[];+ now: Date;+};++export function createReorderQueuedComments(deps: { issueLock: QueuedCommentIssueLockWriter }) {+ return async function reorderQueuedComments(input: ReorderQueuedCommentsInput): Promise<QueuedCommentQueueSnapshot> {+ return deps.issueLock.withLockedQueue(+ { issue: input.issue, actor: input.actor, queueId: input.queueId },+ async (locked, tx) => {+ requireMutationTarget(locked.queue, input.queueId, input.revision);++ const currentIds = locked.queue.entries.map((entry) => entry.comment.id);+ const reorderDecision = decideQueuedCommentReorder({ currentIds, orderedIds: input.orderedCommentIds });+ if (reorderDecision.kind === "mismatch") {+ throw new QueuedCommentMutationError(+ "queued_comment_order_mismatch",+ "The queued message order does not match the current queue",+ );+ }++ const updatedWake = await tx.updateWakeQueuedCommentIds({+ wakeId: locked.wake.id,+ payload: locked.wake.payload,+ ids: input.orderedCommentIds,+ updatedAt: input.now,+ });+ const updatedQueueRun = await updateQueueRunCommentIdsGuarded(tx, {+ queueRun: locked.queueRun,+ ids: input.orderedCommentIds,+ updatedAt: input.now,+ });++ return tx.buildQueueSnapshot({+ issue: input.issue,+ actor: input.actor,+ wake: updatedWake,+ state: locked.state,+ queueRun: updatedQueueRun ?? locked.queueRun,+ activeRun: locked.activeRun,+ });+ },+ );+ };+}++export type DiscardQueuedCommentInput = {+ issue: QueuedCommentIssueContext;+ actor: QueuedCommentActor;+ commentId: string;+ queueId: string;+ /** Skipped entirely when omitted, matching the comment-delete route's cancellation call site, which does not carry a revision. */+ revision?: string;+ now: Date;+};++export type DiscardQueuedCommentResult = {+ /** The full deleted comment row; the comment-delete route echoes it back as its own response body. */+ deleted: IssueComment;+ queue: QueuedCommentQueueSnapshot;+ /** Set only when the discard emptied the queue and cancelled a queued run; the caller emits telemetry for it after the transaction commits. */+ cancelledRun: { id: string } | null;+};++export function createDiscardQueuedComment(deps: { issueLock: QueuedCommentIssueLockWriter }) {+ return async function discardQueuedComment(input: DiscardQueuedCommentInput): Promise<DiscardQueuedCommentResult> {+ return deps.issueLock.withLockedQueue(+ { issue: input.issue, actor: input.actor, queueId: input.queueId },+ async (locked, tx) => {+ if (input.revision !== undefined) {+ requireMutationTarget(locked.queue, input.queueId, input.revision);+ }++ const entry = locked.queue.entries.find((candidate) => candidate.comment.id === input.commentId);+ if (!entry) {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ const owns = decideQueuedCommentActorOwnsEntry({+ actorType: input.actor.actorType,+ actorId: input.actor.actorId,+ actorAgentId: input.actor.agentId,+ authorAgentId: entry.comment.authorAgentId,+ authorUserId: entry.comment.authorUserId,+ });+ if (!owns) {+ throw new QueuedCommentMutationForbiddenError("Only the queued message author can discard it");+ }++ const deleted = await tx.deleteComment({ issueId: input.issue.id, commentId: input.commentId });+ if (!deleted) {+ throw new QueuedCommentMutationError("queued_comment_not_pending", "The queued message is no longer pending");+ }+ await tx.deleteCommentReferenceSource(input.commentId);+ await tx.syncCommentExternalObjectsSafely(input.commentId);++ const remainingIds = locked.queue.entries.map((candidate) => candidate.comment.id).filter((id) => id !== input.commentId);+ const queueBecomesEmpty = remainingIds.length === 0;++ let cancelledRun: { id: string } | null = null;+ let nextWake = locked.wake;+ let nextQueueRun = locked.queueRun;++ if (queueBecomesEmpty) {+ await tx.cancelWake({+ wakeId: locked.wake.id,+ reason: "Queued message discarded before dispatch",+ now: input.now,+ });+ if (locked.queueRun) {+ const cancelled = await tx.cancelQueueRun({+ queueRunId: locked.queueRun.id,+ reason: "Queued message discarded before dispatch",+ now: input.now,+ });+ if (!cancelled) {+ throw new QueuedCommentMutationError(+ "queued_comment_already_dispatching",+ "The queued message is already being dispatched",+ );+ }+ cancelledRun = cancelled;+ await tx.clearExecutionLockAndTouchIssue({+ issueId: input.issue.id,+ executionRunId: locked.queueRun.id,+ updatedAt: input.now,+ });+ } else {+ await tx.touchIssueUpdatedAt({ issueId: input.issue.id, updatedAt: input.now });+ }+ } else {+ nextWake = await tx.updateWakeQueuedCommentIds({+ wakeId: locked.wake.id,+ payload: locked.wake.payload,+ ids: remainingIds,+ updatedAt: input.now,+ });+ nextQueueRun = await updateQueueRunCommentIdsGuarded(tx, {+ queueRun: locked.queueRun,+ ids: remainingIds,+ updatedAt: input.now,+ });+ await tx.touchIssueUpdatedAt({ issueId: input.issue.id, updatedAt: input.now });+ }++ const queue = await tx.buildQueueSnapshot({+ issue: input.issue,+ actor: input.actor,+ wake: queueBecomesEmpty ? null : nextWake,+ state: queueBecomesEmpty ? null : locked.state,+ queueRun: queueBecomesEmpty ? null : (nextQueueRun ?? locked.queueRun),+ activeRun: locked.activeRun,+ });++ return { deleted, queue, cancelledRun };+ },+ );+ };+}diff --git a/server/src/modules/wake-queue/domain/policy.test.ts b/server/src/modules/wake-queue/domain/policy.test.tsindex 12119c0138..1d09806c3c 100644--- a/server/src/modules/wake-queue/domain/policy.test.ts+++ b/server/src/modules/wake-queue/domain/policy.test.ts@@ -2,6 +2,9 @@ import { describe, expect, it } from "vitest";import {decidePreDrain,decideQueuedCommentAction,+ decideQueuedCommentActorOwnsEntry,+ decideQueuedCommentReorder,+ decideQueuedCommentWakeLookup,decideReleaseRecovery,decideWakeAdmission,decideWakeOutcome,@@ -10,6 +13,9 @@ import {type DeferredWakeQueuedCommentFacts,type ImmediateRecoveryContextLabels,type PreDrainFacts,+ type QueuedCommentActorOwnershipFacts,+ type QueuedCommentReorderFacts,+ type QueuedCommentWakeLookupFacts,type ReleaseRecoveryFacts,type WakeAdmissionFacts,} from "./policy.js";@@ -544,3 +550,166 @@ describe("decideWakeAdmission", () => {});}});++describe("decideQueuedCommentWakeLookup", () => {+ const baseFacts: QueuedCommentWakeLookupFacts = {+ wakePresent: true,+ wakeIssueIdMatches: true,+ hasQueuedCommentIds: true,+ wakeStatus: "deferred_issue_execution",+ wakeHasRunId: false,+ };++ const cases: Array<{+ name: string;+ facts: QueuedCommentWakeLookupFacts;+ expected: ReturnType<typeof decideQueuedCommentWakeLookup>;+ }> = [+ {+ name: "not_pending: no wake row was found",+ facts: { ...baseFacts, wakePresent: false },+ expected: { kind: "not_pending" },+ },+ {+ name: "not_pending: the wake's payload names a different issue",+ facts: { ...baseFacts, wakeIssueIdMatches: false },+ expected: { kind: "not_pending" },+ },+ {+ name: "not_pending: the wake's payload carries no queued comment ids",+ facts: { ...baseFacts, hasQueuedCommentIds: false },+ expected: { kind: "not_pending" },+ },+ {+ name: "deferred: the wake is still waiting behind an active execution run",+ facts: baseFacts,+ expected: { kind: "deferred" },+ },+ {+ name: "check_queue_run: the wake is queued and carries a linked run id",+ facts: { ...baseFacts, wakeStatus: "queued", wakeHasRunId: true },+ expected: { kind: "check_queue_run" },+ },+ {+ name: "not_pending: the wake is queued but carries no linked run id",+ facts: { ...baseFacts, wakeStatus: "queued", wakeHasRunId: false },+ expected: { kind: "not_pending" },+ },+ {+ name: "already_dispatching: the wake was claimed",+ facts: { ...baseFacts, wakeStatus: "claimed" },+ expected: { kind: "already_dispatching" },+ },+ {+ name: "already_dispatching: the wake is running",+ facts: { ...baseFacts, wakeStatus: "running" },+ expected: { kind: "already_dispatching" },+ },+ {+ name: "already_dispatching: the wake succeeded and still carries a run id",+ facts: { ...baseFacts, wakeStatus: "succeeded", wakeHasRunId: true },+ expected: { kind: "already_dispatching" },+ },+ {+ name: "already_dispatching: the wake failed and still carries a run id",+ facts: { ...baseFacts, wakeStatus: "failed", wakeHasRunId: true },+ expected: { kind: "already_dispatching" },+ },+ {+ name: "not_pending: the wake succeeded but carries no run id",+ facts: { ...baseFacts, wakeStatus: "succeeded", wakeHasRunId: false },+ expected: { kind: "not_pending" },+ },+ {+ name: "not_pending: the wake was cancelled",+ facts: { ...baseFacts, wakeStatus: "cancelled" },+ expected: { kind: "not_pending" },+ },+ ];++ for (const testCase of cases) {+ it(testCase.name, () => {+ expect(decideQueuedCommentWakeLookup(testCase.facts)).toEqual(testCase.expected);+ });+ }+});++describe("decideQueuedCommentReorder", () => {+ const cases: Array<{+ name: string;+ facts: QueuedCommentReorderFacts;+ expected: ReturnType<typeof decideQueuedCommentReorder>;+ }> = [+ {+ name: "ok: the submitted order is a permutation of the current ids",+ facts: { currentIds: ["a", "b", "c"], orderedIds: ["c", "a", "b"] },+ expected: { kind: "ok" },+ },+ {+ name: "mismatch: the submitted order carries a duplicate id",+ facts: { currentIds: ["a", "b"], orderedIds: ["a", "a"] },+ expected: { kind: "mismatch" },+ },+ {+ name: "mismatch: the submitted order drops an id",+ facts: { currentIds: ["a", "b", "c"], orderedIds: ["a", "b"] },+ expected: { kind: "mismatch" },+ },+ {+ name: "mismatch: the submitted order adds an id the queue does not have",+ facts: { currentIds: ["a", "b"], orderedIds: ["a", "b", "c"] },+ expected: { kind: "mismatch" },+ },+ {+ name: "mismatch: the submitted order names an id the current queue does not have",+ facts: { currentIds: ["a", "b"], orderedIds: ["a", "c"] },+ expected: { kind: "mismatch" },+ },+ ];++ for (const testCase of cases) {+ it(testCase.name, () => {+ expect(decideQueuedCommentReorder(testCase.facts)).toEqual(testCase.expected);+ });+ }+});++describe("decideQueuedCommentActorOwnsEntry", () => {+ const cases: Array<{+ name: string;+ facts: QueuedCommentActorOwnershipFacts;+ expected: boolean;+ }> = [+ {+ name: "owns: a user actor authored the comment",+ facts: { actorType: "user", actorId: "user-1", actorAgentId: null, authorAgentId: null, authorUserId: "user-1" },+ expected: true,+ },+ {+ name: "does not own: a user actor did not author the comment",+ facts: { actorType: "user", actorId: "user-1", actorAgentId: null, authorAgentId: null, authorUserId: "user-2" },+ expected: false,+ },+ {+ name: "owns: an agent actor authored the comment as that agent",+ facts: { actorType: "agent", actorId: "agent-1", actorAgentId: "agent-1", authorAgentId: "agent-1", authorUserId: null },+ expected: true,+ },+ {+ name: "does not own: an agent actor authored a different comment",+ facts: { actorType: "agent", actorId: "agent-1", actorAgentId: "agent-1", authorAgentId: "agent-2", authorUserId: null },+ expected: false,+ },+ {+ name: "does not own: an agent actor with no resolved agent id",+ facts: { actorType: "agent", actorId: "agent-1", actorAgentId: null, authorAgentId: null, authorUserId: null },+ expected: false,+ },+ ];++ for (const testCase of cases) {+ it(testCase.name, () => {+ expect(decideQueuedCommentActorOwnsEntry(testCase.facts)).toBe(testCase.expected);+ });+ }+});diff --git a/server/src/modules/wake-queue/domain/policy.ts b/server/src/modules/wake-queue/domain/policy.tsindex f19b6e7b34..8ef20f07af 100644--- a/server/src/modules/wake-queue/domain/policy.ts+++ b/server/src/modules/wake-queue/domain/policy.ts@@ -273,6 +273,98 @@ export function deriveImmediateRecoveryContextLabels(issueStatus: string): Immed};}+// Pure decision rules for the three queued-comment queue mutations (edit,+// reorder, discard): the queue-mutation target check every mutation runs+// first, the wake and queue-run status classification the initial lock+// step needs, the reorder set-equality check, the queue-entry permission+// fields the response carries, the actor-ownership check discard enforces,+// and the empty-versus-partial outcome a discard resolves to. As with every+// other decision in this file, the caller reads the database and packs the+// result into a facts object; this file only branches on that object.++export type QueuedCommentWakeLookupFacts = {+ /** True when a wake row was found for the submitted queue id. */+ wakePresent: boolean;+ /** True when the wake's own payload still names this issue. */+ wakeIssueIdMatches: boolean;+ /** True when the wake's payload still carries one or more queued comment ids. */+ hasQueuedCommentIds: boolean;+ /** The wake row's own status. Meaningless when `wakePresent` is false. */+ wakeStatus: string | null;+ /** True when the wake row carries a linked heartbeat run id. */+ wakeHasRunId: boolean;+};++export type QueuedCommentWakeLookupDecision =+ | { kind: "not_pending" }+ | { kind: "deferred" }+ /** The caller must read the linked heartbeat run next and confirm it is still queued. */+ | { kind: "check_queue_run" }+ | { kind: "already_dispatching" };++/**+ * Classifies a locked wake row into the queue state a mutation needs: still+ * waiting behind an active run (`deferred`), queued behind a not-yet-running+ * turn (needs a second read to confirm, `check_queue_run`), already being+ * dispatched, or no longer a pending queue at all.+ */+export function decideQueuedCommentWakeLookup(facts: QueuedCommentWakeLookupFacts): QueuedCommentWakeLookupDecision {+ if (!facts.wakePresent || !facts.wakeIssueIdMatches || !facts.hasQueuedCommentIds) {+ return { kind: "not_pending" };+ }+ if (facts.wakeStatus === "deferred_issue_execution") return { kind: "deferred" };+ if (facts.wakeStatus === "queued" && facts.wakeHasRunId) return { kind: "check_queue_run" };+ if (+ facts.wakeStatus === "claimed" ||+ facts.wakeStatus === "running" ||+ (facts.wakeHasRunId && (facts.wakeStatus === "succeeded" || facts.wakeStatus === "failed"))+ ) {+ return { kind: "already_dispatching" };+ }+ return { kind: "not_pending" };+}++export type QueuedCommentReorderFacts = {+ currentIds: string[];+ orderedIds: string[];+};++export type QueuedCommentReorderDecision = { kind: "ok" } | { kind: "mismatch" };++/** Decides whether a submitted order is a permutation of the queue's current comment ids: no duplicates, no drops, no additions. */+export function decideQueuedCommentReorder(facts: QueuedCommentReorderFacts): QueuedCommentReorderDecision {+ const orderedSet = new Set(facts.orderedIds);+ if (+ orderedSet.size !== facts.orderedIds.length ||+ facts.orderedIds.length !== facts.currentIds.length ||+ facts.currentIds.some((id) => !orderedSet.has(id))+ ) {+ return { kind: "mismatch" };+ }+ return { kind: "ok" };+}++export type QueuedCommentActorOwnershipFacts = {+ actorType: "agent" | "user";+ actorId: string;+ actorAgentId: string | null;+ authorAgentId: string | null;+ authorUserId: string | null;+};++/**+ * Decides whether the actor discarding a queued message authored it. A user+ * actor must be the board user who wrote the message. An agent actor must be+ * the agent that wrote it, because an agent actor can discard its own queued+ * message through the general comment-delete route.+ */+export function decideQueuedCommentActorOwnsEntry(facts: QueuedCommentActorOwnershipFacts): boolean {+ if (facts.actorType === "agent") {+ return facts.actorAgentId !== null && facts.authorAgentId === facts.actorAgentId;+ }+ return facts.authorUserId === facts.actorId;+}+/*** Decides the release-recovery outcome once the deferred-wake queue is* empty and no wake was promoted. The review-participant branch and thediff --git a/server/src/modules/wake-queue/index.ts b/server/src/modules/wake-queue/index.tsindex 57f02cca2c..7f6e086679 100644--- a/server/src/modules/wake-queue/index.ts+++ b/server/src/modules/wake-queue/index.ts@@ -5,7 +5,14 @@ import {createWakeAdmissionReader,createWakeAdmissionWriter,} from "./adapters/postgres.js";+import { createQueuedCommentIssueLockWriter } from "./adapters/queued-comment-postgres.js";+import type { QueuedCommentQueuePostgresAdapterDeps } from "./adapters/queued-comment-postgres.js";import { createAdmitWakeBehindIssueExecution, createReleaseIssueExecution } from "./application/use-cases.js";+import {+ createDiscardQueuedComment,+ createEditQueuedComment,+ createReorderQueuedComments,+} from "./application/queued-comment-use-cases.js";import type {IssueSnapshot,RecoveryEscalationPort,@@ -29,6 +36,23 @@ export type {TransactionScope,} from "./application/ports.js";export type { AdmitWakeBehindIssueExecutionInput, AdmitWakeBehindIssueExecutionResult, ReleaseIssueExecutionInput } from "./application/use-cases.js";+export {+ QueuedCommentMutationError,+ QueuedCommentMutationForbiddenError,+} from "./application/queued-comment-use-cases.js";+export type {+ DiscardQueuedCommentInput,+ DiscardQueuedCommentResult,+ EditQueuedCommentInput,+ QueuedCommentMutationErrorCode,+ ReorderQueuedCommentsInput,+} from "./application/queued-comment-use-cases.js";+export type {+ QueuedCommentActor,+ QueuedCommentIssueContext,+ QueuedCommentQueueSnapshot,+} from "./application/queued-comment-ports.js";+export type { QueuedCommentQueuePostgresAdapterDeps } from "./adapters/queued-comment-postgres.js";export type WakeQueueDeps = {/** Stays in `heartbeat.ts`; resolves the responsible user for a promoted or recovery run seed. */@@ -80,3 +104,23 @@ export function createWakeQueue(db: Db, deps: WakeQueueDeps) {}export type WakeQueue = ReturnType<typeof createWakeQueue>;++/**+ * Composes the three queued-comment queue mutations (edit, reorder,+ * discard): the Postgres adapter, which owns the one transaction each+ * mutation runs in, and the three use cases. This is a separate factory+ * from `createWakeQueue` because these mutations need none of the release+ * or admission host callbacks -- only the small set of comment-reference+ * and external-object sync callbacks in `deps`, which a caller outside+ * `heartbeat.ts` (the queued-comment route) can supply directly.+ */+export function createQueuedCommentQueue(db: Db, deps: QueuedCommentQueuePostgresAdapterDeps) {+ const issueLock = createQueuedCommentIssueLockWriter(db, deps);+ return {+ editQueuedComment: createEditQueuedComment({ issueLock }),+ reorderQueuedComments: createReorderQueuedComments({ issueLock }),+ discardQueuedComment: createDiscardQueuedComment({ issueLock }),+ };+}++export type QueuedCommentQueue = ReturnType<typeof createQueuedCommentQueue>;diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex b0b98a2e50..31cabea88e 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -123,6 +123,7 @@ import {type IssueRelationIssueSummary,type IssueReviewPolicy,type IssueThreadInteractionCanonicalResolverPolicy,+ type IssueComment,type IssueCommentPresentation,type IssueQueuedCommentQueue,type IssueWatchdogDiscoveryKind,@@ -179,7 +180,13 @@ import {} from "../services/runner-goals.js";import { queueLiveRunnerPrpCommand } from "../realtime/runner-prp-ws.js";import { questionResponseDeliveryService } from "../services/question-response-delivery.js";-import { emitAgentTaskRun } from "../services/agent-task-run-telemetry.js";+import { emitAgentTaskRunById } from "../services/agent-task-run-telemetry.js";+import {+ createQueuedCommentQueue,+ QueuedCommentMutationError,+ QueuedCommentMutationForbiddenError,+ type QueuedCommentIssueContext,+} from "../modules/wake-queue/index.js";import { artifactReviewDocumentService } from "../services/artifact-review-documents.js";import { assertCanResolveProposal } from "../services/secret-proposal-authorization.js";import {@@ -330,8 +337,9 @@ import {steerNativeSession,} from "../services/native-runtime/native-session-executor.js";import {+ buildQueuedCommentQueueSnapshot,+ decideQueuedCommentQueueSteering,queuedCommentIdsFromWakePayload,- withQueuedCommentIdsInRunContext,withQueuedCommentIdsInWakePayload,} from "../services/issue-queued-comment-queue.js";@@ -3689,6 +3697,11 @@ export function issueRoutes(enabled: async () =>(await instanceSettings.getExperimental()).enableExternalObjects === true,});+ const queuedCommentQueue = createQueuedCommentQueue(db, {+ syncCommentReferences: (commentId, tx) => issueReferencesSvc.syncComment(commentId, tx),+ deleteCommentReferenceSource: (commentId, tx) => issueReferencesSvc.deleteCommentSource(commentId, tx),+ syncCommentExternalObjectsSafely: (commentId, tx) => externalObjectsSvc.syncCommentSafely(commentId, tx),+ });const routinesSvc = routineService(db, {pluginWorkerManager: opts.pluginWorkerManager,});@@ -6747,24 +6760,6 @@ export function issueRoutes(queueRun: IssueQueueRun | null;};- function queueRevision(input: {- wake: IssueQueueWake | null;- comments: Array<{ id: string; updatedAt: Date }>;- }): string {- return createHash("sha256")- .update(- JSON.stringify({- queueId: input.wake?.id ?? null,- comments: input.comments.map((comment) => [- comment.id,- comment.updatedAt.toISOString(),- ]),- }),- )- .digest("hex")- .slice(0, 32);- }-async function findQueuedCommentWake(executor: IssueQueueDb,issue: { id: string; companyId: string; assigneeAgentId: string | null },@@ -6865,53 +6860,31 @@ export function issueRoutes(.limit(1).then((rows) => rows[0] ?? null): null;- const persistedRuntimeMode =- queueState?.state === "queued" && queueState.queueRun- ? queueState.queueRun.runtimeMode- : queueState?.state === "deferred" && input.activeRun- ? input.activeRun.runtimeMode- : null;- const protocol =- persistedRuntimeMode === "native" ||- (persistedRuntimeMode === null &&- assignedAgent?.adapterType === "paperclip_runner")- ? ("paperclip_runner_v1" as const)- : ("legacy" as const);- const steeringRun =- queueState?.state === "deferred" ? input.activeRun : null;- let steeringDisposition =- input.steeringDisposition ??- (protocol === "paperclip_runner_v1" && steeringRun- ? await getNativeSessionSteeringState(steeringRun.id)+ const steering = decideQueuedCommentQueueSteering({+ state: queueState?.state ?? null,+ queueRunRuntimeMode: queueState?.state === "queued" ? queueState.queueRun?.runtimeMode ?? null : null,+ activeRun: input.activeRun,+ assignedAgentAdapterType: assignedAgent?.adapterType ?? null,+ queuedCommentCount: comments.length,+ });+ const steeringDisposition: IssueQueuedCommentQueue["steeringDisposition"] =+ steering.kind !== "probe"+ ? steering.kind+ : input.steeringDisposition+ ?? (await getNativeSessionSteeringState(steering.steeringRunId).then((state) => state.disposition)- .catch(() => "temporarily_unavailable" as const)- : ("unsupported" as const));- if (- protocol === "paperclip_runner_v1" &&- (!steeringRun || comments.length === 0)- ) {- steeringDisposition = "temporarily_unavailable";- }- return {+ .catch(() => "temporarily_unavailable" as const));+ return buildQueuedCommentQueueSnapshot({issueId: input.issue.id,queueId: wake?.id ?? null,state: queueState?.state ?? null,- targetRunId: steeringRun?.id ?? null,- revision: queueRevision({ wake, comments }),- protocol,+ activeRunId: input.activeRun?.id ?? null,+ protocol: steering.protocol,steeringDisposition,- entries: comments.map((comment, position) => ({- comment:- comment as IssueQueuedCommentQueue["entries"][number]["comment"],- position,- canEdit:- input.actor.actorType === "user" &&- comment.authorUserId === input.actor.actorId,- canDiscard:- input.actor.actorType === "user" &&- comment.authorUserId === input.actor.actorId,- })),- };+ comments,+ actorType: input.actor.actorType,+ actorId: input.actor.actorId,+ });}function assertQueueMutationTarget(input: {@@ -7063,211 +7036,7 @@ export function issueRoutes(return { activeRun, wake, queueRun, state, queue, queueState };}- async function updateQueuedRunCommentIds(- tx: IssueQueueTx,- queueRun: IssueQueueRun | null,- ids: string[],- updatedAt: Date,- ) {- if (!queueRun) return null;- const updated = await tx- .update(heartbeatRuns)- .set({- contextSnapshot: withQueuedCommentIdsInRunContext(- queueRun.contextSnapshot,- ids,- ),- updatedAt,- })- .where(- and(- eq(heartbeatRuns.id, queueRun.id),- eq(heartbeatRuns.status, "queued"),- ),- )- .returning()- .then((rows) => rows[0] ?? null);- if (!updated) {- throw conflict("The queued message is already being dispatched", {- code: "queued_comment_already_dispatching",- });- }- return updated;- }-- async function discardQueuedComment(input: {- issue: {- id: string;- companyId: string;- assigneeAgentId: string | null;- executionRunId?: string | null;- };- actor: ReturnType<typeof getActorInfo>;- commentId: string;- queueId: string;- revision?: string;- }) {- let cancelledRunToEmit: typeof heartbeatRuns.$inferSelect | null = null;- const result = await db.transaction(async (tx) => {- const locked = await lockQueuedCommentState({- tx,- issue: input.issue,- actor: input.actor,- queueId: input.queueId,- });- if (input.revision) {- assertQueueMutationTarget({- queue: locked.queue,- queueId: input.queueId,- revision: input.revision,- });- }- const entry = locked.queue.entries.find(- (candidate) => candidate.comment.id === input.commentId,- );- if (!entry) {- throw conflict("The queued message is no longer pending", {- code: "queued_comment_not_pending",- });- }- const actorOwnsEntry =- input.actor.actorType === "agent"- ? entry.comment.authorAgentId === input.actor.agentId- : entry.comment.authorUserId === input.actor.actorId;- if (!actorOwnsEntry) {- throw forbidden("Only the queued message author can discard it");- }-- const deleted = await tx- .delete(issueComments)- .where(- and(- eq(issueComments.id, input.commentId),- eq(issueComments.issueId, input.issue.id),- ),- )- .returning()- .then((rows) => rows[0] ?? null);- if (!deleted) {- throw conflict("The queued message is no longer pending", {- code: "queued_comment_not_pending",- });- }- await issueReferencesSvc.deleteCommentSource(input.commentId, tx);- await externalObjectsSvc.syncCommentSafely(input.commentId, tx);-- const remainingIds = locked.queue.entries- .map((candidate) => candidate.comment.id)- .filter((candidateId) => candidateId !== input.commentId);- const now = new Date();- let nextQueueState: IssueQueueState | null = null;-- if (remainingIds.length === 0) {- await tx- .update(agentWakeupRequests)- .set({- status: "cancelled",- finishedAt: now,- error: "Queued message discarded before dispatch",- updatedAt: now,- })- .where(eq(agentWakeupRequests.id, locked.wake.id));-- if (locked.queueRun) {- const cancelledRun = await tx- .update(heartbeatRuns)- .set({- status: "cancelled",- finishedAt: now,- error: "Queued message discarded before dispatch",- errorCode: "queued_comment_discarded",- updatedAt: now,- })- .where(- and(- eq(heartbeatRuns.id, locked.queueRun.id),- eq(heartbeatRuns.status, "queued"),- ),- )- .returning()- .then((rows) => rows[0] ?? null);- if (!cancelledRun) {- throw conflict("The queued message is already being dispatched", {- code: "queued_comment_already_dispatching",- });- }- cancelledRunToEmit = cancelledRun;- }- } else {- const updatedWake = await tx- .update(agentWakeupRequests)- .set({- payload: withQueuedCommentIdsInWakePayload(- locked.wake.payload,- remainingIds,- ),- updatedAt: now,- })- .where(eq(agentWakeupRequests.id, locked.wake.id))- .returning()- .then((rows) => rows[0] ?? locked.wake);- const updatedQueueRun = await updateQueuedRunCommentIds(- tx,- locked.queueRun,- remainingIds,- now,- );- nextQueueState = {- wake: updatedWake,- state: locked.state,- queueRun: updatedQueueRun ?? locked.queueRun,- };- }-- await tx- .update(issueRows)- .set({- ...(locked.queueRun && remainingIds.length === 0- ? {- executionRunId: null,- executionAgentNameKey: null,- executionLockedAt: null,- }- : {}),- updatedAt: now,- })- .where(- and(- eq(issueRows.id, input.issue.id),- locked.queueRun && remainingIds.length === 0- ? eq(issueRows.executionRunId, locked.queueRun.id)- : undefined,- ),- );-- return {- deleted,- queue: await buildQueuedCommentQueue({- executor: tx,- issue: input.issue,- activeRun: locked.activeRun,- actor: input.actor,- queueState: nextQueueState,- }),- };- });- // Telemetry is best-effort background work; it must not delay the- // response with a slow lookup, so fire it and do not await it.- if (cancelledRunToEmit) {- void emitAgentTaskRun(db, cancelledRunToEmit);- }- return result;- }-- function operatorInterruptCancelOptions(input: {- issueId: string;- actor: ReturnType<typeof getActorInfo>;- }) {+ function operatorInterruptCancelOptions(input: { issueId: string; actor: ReturnType<typeof getActorInfo> }) {return {errorCode: "operator_interrupted",resultJson: {@@ -15300,6 +15069,41 @@ export function issueRoutes();});+ /** Maps a wake-queue queued-comment mutation error onto the same HTTP error the route threw before this mutation moved into the module. */+ function throwForQueuedCommentMutationError(error: unknown): never {+ if (error instanceof QueuedCommentMutationError) {+ throw conflict(error.message, { code: error.code });+ }+ if (error instanceof QueuedCommentMutationForbiddenError) {+ throw forbidden(error.message);+ }+ throw error;+ }++ /** Builds the four-field issue context every queued-comment queue mutation call site passes, from the route's already-loaded issue. */+ function buildQueuedCommentIssueContext(issue: {+ id: string;+ companyId: string;+ assigneeAgentId: string | null;+ executionRunId: string | null | undefined;+ }): QueuedCommentIssueContext {+ return {+ id: issue.id,+ companyId: issue.companyId,+ assigneeAgentId: issue.assigneeAgentId,+ executionRunId: issue.executionRunId ?? null,+ };+ }++ /** Runs a queued-comment queue mutation and maps its error onto the route's HTTP error, so each call site is a `const`. */+ async function runQueuedCommentMutation<T>(run: () => Promise<T>): Promise<T> {+ try {+ return await run();+ } catch (error) {+ throwForQueuedCommentMutationError(error);+ }+ }+router.get("/issues/:id/queued-comments", async (req, res) => {const id = req.params.id as string;const issue = await getAccessibleResource(@@ -15337,70 +15141,18 @@ export function issueRoutes();if (!issue) return;const actor = getActorInfo(req);- const queue = await db.transaction(async (tx) => {- const locked = await lockQueuedCommentState({- tx,- issue,+ const queue = await runQueuedCommentMutation(() =>+ queuedCommentQueue.editQueuedComment({+ issue: buildQueuedCommentIssueContext(issue),actor,- queueId: req.body.queueId,- });- assertQueueMutationTarget({- queue: locked.queue,+ commentId,queueId: req.body.queueId,revision: req.body.revision,- });- const entry = locked.queue.entries.find(- (candidate) => candidate.comment.id === commentId,- );- if (!entry)- throw conflict("The queued message is no longer pending", {- code: "queued_comment_not_pending",- });- if (!entry.canEdit)- throw forbidden("Only the queued message author can edit it");- const updatedAt = new Date();- const updated = await tx- .update(issueComments)- .set({ body: req.body.body, updatedAt })- .where(- and(- eq(issueComments.id, commentId),- eq(issueComments.issueId, issue.id),- ),- )- .returning({ id: issueComments.id })- .then((rows) => rows[0] ?? null);- if (!updated)- throw conflict("The queued message is no longer pending", {- code: "queued_comment_not_pending",- });- await tx- .update(issueRows)- .set({ updatedAt })- .where(eq(issueRows.id, issue.id));- await issueReferencesSvc.syncComment(commentId, tx);- await externalObjectsSvc.syncCommentSafely(commentId, tx);- const updatedQueueRun = await updateQueuedRunCommentIds(- tx,- locked.queueRun,- locked.queue.entries.map((candidate) => candidate.comment.id),- updatedAt,- );- return buildQueuedCommentQueue({- executor: tx,- issue,- activeRun: locked.activeRun,- actor,- queueState: {- wake: locked.wake,- state: locked.state,- queueRun: updatedQueueRun ?? locked.queueRun,- },- });- });- res.json(- await runRedactions.redactForIssue(issue.companyId, issue.id, queue),+ body: req.body.body,+ now: new Date(),+ }),);+ res.json(await runRedactions.redactForIssue(issue.companyId, issue.id, queue));},);@@ -15419,69 +15171,17 @@ export function issueRoutes();if (!issue) return;const actor = getActorInfo(req);- const queue = await db.transaction(async (tx) => {- const locked = await lockQueuedCommentState({- tx,- issue,+ const queue = await runQueuedCommentMutation(() =>+ queuedCommentQueue.reorderQueuedComments({+ issue: buildQueuedCommentIssueContext(issue),actor,queueId: req.body.queueId,- });- assertQueueMutationTarget({- queue: locked.queue,- queueId: req.body.queueId,revision: req.body.revision,- });- const currentIds = locked.queue.entries.map(- (entry) => entry.comment.id,- );- const orderedIds = req.body.orderedCommentIds as string[];- const orderedSet = new Set(orderedIds);- if (- orderedSet.size !== orderedIds.length ||- orderedIds.length !== currentIds.length ||- currentIds.some((commentId) => !orderedSet.has(commentId))- ) {- throw conflict(- "The queued message order does not match the current queue",- {- code: "queued_comment_order_mismatch",- },- );- }- const now = new Date();- const updatedWake = await tx- .update(agentWakeupRequests)- .set({- payload: withQueuedCommentIdsInWakePayload(- locked.wake.payload,- orderedIds,- ),- updatedAt: now,- })- .where(eq(agentWakeupRequests.id, locked.wake.id))- .returning()- .then((rows) => rows[0] ?? locked.wake);- const updatedQueueRun = await updateQueuedRunCommentIds(- tx,- locked.queueRun,- orderedIds,- now,- );- return buildQueuedCommentQueue({- executor: tx,- issue,- activeRun: locked.activeRun,- actor,- queueState: {- wake: updatedWake,- state: locked.state,- queueRun: updatedQueueRun ?? locked.queueRun,- },- });- });- res.json(- await runRedactions.redactForIssue(issue.companyId, issue.id, queue),+ orderedCommentIds: req.body.orderedCommentIds as string[],+ now: new Date(),+ }),);+ res.json(await runRedactions.redactForIssue(issue.companyId, issue.id, queue));},);@@ -15759,16 +15459,22 @@ export function issueRoutes();if (!issue) return;const actor = getActorInfo(req);- const { queue } = await discardQueuedComment({- issue,- actor,- commentId,- queueId: req.body.queueId,- revision: req.body.revision,- });- res.json(- await runRedactions.redactForIssue(issue.companyId, issue.id, queue),+ const result = await runQueuedCommentMutation(() =>+ queuedCommentQueue.discardQueuedComment({+ issue: buildQueuedCommentIssueContext(issue),+ actor,+ commentId,+ queueId: req.body.queueId,+ revision: req.body.revision,+ now: new Date(),+ }),);+ // Telemetry is best-effort background work; it must not delay the+ // response with a slow lookup, so fire it and do not await it.+ if (result.cancelledRun) {+ void emitAgentTaskRunById(db, { runId: result.cancelledRun.id, companyId: issue.companyId });+ }+ res.json(await runRedactions.redactForIssue(issue.companyId, issue.id, result.queue));},);@@ -16932,20 +16638,25 @@ export function issueRoutes(return;}- const queueWakeForCancellation =- deleteMode === "cancel" ? authoritativeQueueWake : pendingQueueWake;- const removed = queueWakeForCancellation- ? (- await discardQueuedComment({- issue,+ const queueWakeForCancellation = deleteMode === "cancel"+ ? authoritativeQueueWake+ : pendingQueueWake;+ let removed: IssueComment | null;+ if (queueWakeForCancellation) {+ removed = (+ await runQueuedCommentMutation(() =>+ queuedCommentQueue.discardQueuedComment({+ issue: buildQueuedCommentIssueContext(issue),actor,commentId,queueId: queueWakeForCancellation.id,- })- ).deleted- : activeRun && isLegacyQueuedComment- ? await svc.removeComment(commentId)- : null;+ now: new Date(),+ }),+ )+ ).deleted;+ } else {+ removed = activeRun && isLegacyQueuedComment ? await svc.removeComment(commentId) : null;+ }if (!removed) {res.status(409).json({error: activeRun@@ -16954,7 +16665,6 @@ export function issueRoutes(});return;}-await logActivity(db, {companyId: issue.companyId,actorType: actor.actorType,diff --git a/server/src/services/issue-queued-comment-queue.test.ts b/server/src/services/issue-queued-comment-queue.test.tsnew file mode 100644index 0000000000..a7c771641b--- /dev/null+++ b/server/src/services/issue-queued-comment-queue.test.ts@@ -0,0 +1,117 @@+import { describe, expect, it } from "vitest";+import { buildQueuedCommentQueueSnapshot, decideQueuedCommentQueueSteering } from "./issue-queued-comment-queue.js";++describe("decideQueuedCommentQueueSteering", () => {+ it("answers unsupported on the legacy protocol", () => {+ const decision = decideQueuedCommentQueueSteering({+ state: "deferred",+ queueRunRuntimeMode: null,+ activeRun: { id: "run-1", runtimeMode: "legacy" },+ assignedAgentAdapterType: "codex_local",+ queuedCommentCount: 1,+ });++ expect(decision).toEqual({ protocol: "legacy", kind: "unsupported" });+ });++ it("answers temporarily_unavailable for a promoted native queue with no deferred run", () => {+ const decision = decideQueuedCommentQueueSteering({+ state: "queued",+ queueRunRuntimeMode: "native",+ activeRun: null,+ assignedAgentAdapterType: "paperclip_runner",+ queuedCommentCount: 1,+ });++ expect(decision).toEqual({ protocol: "paperclip_runner_v1", kind: "temporarily_unavailable" });+ });++ it("answers temporarily_unavailable when the queue holds no live comments", () => {+ const decision = decideQueuedCommentQueueSteering({+ state: "deferred",+ queueRunRuntimeMode: null,+ activeRun: { id: "run-1", runtimeMode: "native" },+ assignedAgentAdapterType: "paperclip_runner",+ queuedCommentCount: 0,+ });++ expect(decision).toEqual({ protocol: "paperclip_runner_v1", kind: "temporarily_unavailable" });+ });++ it("tells the caller it may probe a running deferred turn on the native protocol", () => {+ const decision = decideQueuedCommentQueueSteering({+ state: "deferred",+ queueRunRuntimeMode: null,+ activeRun: { id: "run-1", runtimeMode: "native" },+ assignedAgentAdapterType: "paperclip_runner",+ queuedCommentCount: 1,+ });++ expect(decision).toEqual({ protocol: "paperclip_runner_v1", kind: "probe", steeringRunId: "run-1" });+ });++ // Acceptance-criterion fact pattern: a deferred queue whose active run+ // has not resolved a runtime mode yet, for an agent on the+ // `paperclip_runner` adapter. The protocol resolves to+ // `paperclip_runner_v1` through the adapter-type fallback, and the+ // decision hands the run to the caller to probe live — it never answers+ // the flat "unsupported" value a duplicated, unshared rule can drift to.+ it("resolves the protocol through the adapter-type fallback and asks the caller to probe", () => {+ const decision = decideQueuedCommentQueueSteering({+ state: "deferred",+ queueRunRuntimeMode: null,+ activeRun: { id: "run-1", runtimeMode: null },+ assignedAgentAdapterType: "paperclip_runner",+ queuedCommentCount: 1,+ });++ expect(decision).toEqual({ protocol: "paperclip_runner_v1", kind: "probe", steeringRunId: "run-1" });+ });+});++describe("buildQueuedCommentQueueSnapshot entry permissions", () => {+ const baseFacts = {+ issueId: "issue-1",+ queueId: "queue-1",+ state: "queued" as const,+ activeRunId: null,+ protocol: "legacy" as const,+ steeringDisposition: "unsupported" as const,+ };++ it("grants edit and discard to the user who authored the queued comment", () => {+ const queue = buildQueuedCommentQueueSnapshot({+ ...baseFacts,+ actorType: "user",+ actorId: "user-1",+ comments: [{ id: "comment-1", updatedAt: new Date(), authorUserId: "user-1" }],+ });++ expect(queue.entries[0]?.canEdit).toBe(true);+ expect(queue.entries[0]?.canDiscard).toBe(true);+ });++ it("denies edit and discard to a user who did not author the queued comment", () => {+ const queue = buildQueuedCommentQueueSnapshot({+ ...baseFacts,+ actorType: "user",+ actorId: "user-1",+ comments: [{ id: "comment-1", updatedAt: new Date(), authorUserId: "user-2" }],+ });++ expect(queue.entries[0]?.canEdit).toBe(false);+ expect(queue.entries[0]?.canDiscard).toBe(false);+ });++ it("denies edit and discard to an agent actor even when the comment carries a matching author id", () => {+ const queue = buildQueuedCommentQueueSnapshot({+ ...baseFacts,+ actorType: "agent",+ actorId: "user-1",+ comments: [{ id: "comment-1", updatedAt: new Date(), authorUserId: "user-1" }],+ });++ expect(queue.entries[0]?.canEdit).toBe(false);+ expect(queue.entries[0]?.canDiscard).toBe(false);+ });+});diff --git a/server/src/services/issue-queued-comment-queue.ts b/server/src/services/issue-queued-comment-queue.tsindex 13700f33ad..0fb59fc625 100644--- a/server/src/services/issue-queued-comment-queue.ts+++ b/server/src/services/issue-queued-comment-queue.ts@@ -1,3 +1,6 @@+import { createHash } from "node:crypto";+import type { IssueComment, IssueQueuedCommentQueue } from "@paperclipai/shared";+const QUEUE_CONTEXT_KEY = "_paperclipWakeContext";const QUEUE_IDS_KEY = "wakeCommentIds";@@ -49,6 +52,27 @@ export function withQueuedCommentIdsInWakePayload(return payload;}+/**+ * Fingerprints one queued-comment queue: the wake id plus every comment's id+ * and last-updated time. A mutation that changes the queue changes this+ * value, so a caller can echo it back to detect a queue it no longer holds+ * the latest view of. The read path (`GET /queued-comments`) and every queue+ * mutation must call this same function, so a client's fingerprint always+ * compares against the same computation.+ */+export function queuedCommentQueueRevision(input: {+ queueId: string | null;+ comments: Array<{ id: string; updatedAt: Date }>;+}): string {+ return createHash("sha256")+ .update(JSON.stringify({+ queueId: input.queueId,+ comments: input.comments.map((comment) => [comment.id, comment.updatedAt.toISOString()]),+ }))+ .digest("hex")+ .slice(0, 32);+}+export function withQueuedCommentIdsInRunContext(contextValue: unknown,ids: string[],@@ -73,3 +97,102 @@ export function withQueuedCommentIdsInRunContext(delete context.paperclipTaskMarkdownCompact;return context;}++export type QueuedCommentQueueProtocol = "paperclip_runner_v1" | "legacy";++export type QueuedCommentQueueSteeringDecision =+ | { protocol: QueuedCommentQueueProtocol; kind: "unsupported" }+ | { protocol: QueuedCommentQueueProtocol; kind: "temporarily_unavailable" }+ /** Only the caller can probe the live runner. `steeringRunId` names the run to probe. */+ | { protocol: "paperclip_runner_v1"; kind: "probe"; steeringRunId: string };++/**+ * Decides the queue protocol and the steering answer for one queued-comment+ * queue, from plain facts. This is the one place that resolves the+ * `paperclip_runner_v1`/`legacy` protocol and the steering answer; every+ * caller that builds a queue response must call this function instead of+ * repeating the rule.+ *+ * When the decision is `"probe"`, only the caller can answer the question:+ * it must ask the live runner (through a call such as+ * `getNativeSessionSteeringState`) and fall back to+ * `"temporarily_unavailable"` on failure. A caller that never probes the+ * live runner must answer `"temporarily_unavailable"` for a `"probe"`+ * decision instead.+ */+export function decideQueuedCommentQueueSteering(facts: {+ state: "deferred" | "queued" | null;+ /** The queued run's own runtime mode. Read only when `state` is `"queued"`. */+ queueRunRuntimeMode: string | null;+ /** The currently running turn, if any. Read only when `state` is `"deferred"`. */+ activeRun: { id: string; runtimeMode: string | null } | null;+ assignedAgentAdapterType: string | null;+ queuedCommentCount: number;+}): QueuedCommentQueueSteeringDecision {+ const persistedRuntimeMode =+ facts.state === "queued"+ ? facts.queueRunRuntimeMode+ : facts.state === "deferred"+ ? facts.activeRun?.runtimeMode ?? null+ : null;++ const protocol: QueuedCommentQueueProtocol =+ persistedRuntimeMode === "native"+ || (persistedRuntimeMode === null && facts.assignedAgentAdapterType === "paperclip_runner")+ ? "paperclip_runner_v1"+ : "legacy";++ if (protocol !== "paperclip_runner_v1") {+ return { protocol, kind: "unsupported" };+ }++ const steeringRun = facts.state === "deferred" ? facts.activeRun : null;+ if (!steeringRun || facts.queuedCommentCount === 0) {+ return { protocol, kind: "temporarily_unavailable" };+ }++ return { protocol, kind: "probe", steeringRunId: steeringRun.id };+}++type QueuedCommentQueueEntryFacts = {+ id: string;+ updatedAt: Date;+ authorUserId: string | null;+};++/**+ * Assembles the shared `IssueQueuedCommentQueue` response from the already+ * resolved facts: the queue identity, the already-decided protocol and+ * steering answer, the live comment rows, and the actor who reads the+ * queue. This is the one place that builds the response shape; every+ * caller that builds a queue response must call this function instead of+ * repeating the rule.+ */+export function buildQueuedCommentQueueSnapshot<TComment extends QueuedCommentQueueEntryFacts>(facts: {+ issueId: string;+ queueId: string | null;+ state: "deferred" | "queued" | null;+ /** The currently running turn's id. Read only when `state` is `"deferred"`. */+ activeRunId: string | null;+ protocol: QueuedCommentQueueProtocol;+ steeringDisposition: IssueQueuedCommentQueue["steeringDisposition"];+ comments: TComment[];+ actorType: "agent" | "user";+ actorId: string;+}): IssueQueuedCommentQueue {+ return {+ issueId: facts.issueId,+ queueId: facts.queueId,+ state: facts.state,+ targetRunId: facts.state === "deferred" ? facts.activeRunId : null,+ revision: queuedCommentQueueRevision({ queueId: facts.queueId, comments: facts.comments }),+ protocol: facts.protocol,+ steeringDisposition: facts.steeringDisposition,+ entries: facts.comments.map((comment, position) => ({+ comment: comment as unknown as IssueComment,+ position,+ canEdit: facts.actorType === "user" && comment.authorUserId === facts.actorId,+ canDiscard: facts.actorType === "user" && comment.authorUserId === facts.actorId,+ })),+ };+}