Admit saved task comments with the fresh issue run (#22268)

## Thinking Path

> - Paperclip agents take work from assigned tasks and from user
comments.
> - A fresh task run can include saved comments when the current agent
or a confirmed former assignee owns them.
> - Connected chat messages and resolved interactions have separate
authority and session requirements.
> - Heartbeat previously decided which receipts to adopt between the
three calls that saved a new run.
> - One wake-queue use case now selects the receipts and commits the
same run and comment lineage.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Assignment and comment continuation when a task needs a fresh run.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat chooses the comment receipts to consume, reads their source,
and builds the final run context.

**Proposed behavior**

One application operation admits the run. Its Postgres adapter loads
eligible company and agent receipts under the issue lock. The caller
supplies the responsible user and records the specialized continuation.

**Additional context**

Builds on #22266. The existing release and queued-comment boundaries are
in #13136 and #13145.

## What Changed

- Keep exact resumed receipts separate from ordinary board comments.
Adopt a prior assignee’s comments only when the interrupted run proves a
handoff.
- Use the same canonical comment ID codecs for admission and dispatch.
- Test the assignment path with one or two saved comments and
independent chat and interaction receipts.

## Verification

On c957f8529c, 260 tests passed across the four admission, liveness and
responsible-user suites. The saved Grok interrupt route passed its
exactly-once continuation test. A separate Postgres run passed the
ordered comment and rollback checks, both reassignment cases, and the
company isolation test. Server typecheck and module boundaries passed.

Check the fresh admission and handoff cases in
`server/src/services/heartbeat/queue.test.ts`. Run `pnpm exec vitest run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/services/issue-queued-comment-queue.test.ts`, `pnpm --filter
@paperclipai/server typecheck`, and `node
scripts/check-module-boundaries.mjs`.

## Risks

Receipt selection controls which user input reaches the next agent. The
store requires the same company, issue and executor or a verified
handoff. Chat and interaction receipts preserve their independent
delivery.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Nicky LeachandPaperclip authored and GitHub committed 2026-11-18 19:24:39 -08:00
1 parent f324238f73
commit eca7f85778
12 files changed
+372 -283

No files matched your search

+49 -8
View File
@@ -7,11 +7,11 @@ import { eq, inArray, sql } from "drizzle-orm";
import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { resolveExternalTestDatabaseUrl } from "../../__tests__/helpers/external-test-database.js";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "../../__tests__/helpers/embedded-postgres.js";
import { createPostgresWakeQueueAdapter, createWakeAdmissionWriter } from "../../modules/wake-queue/adapters/postgres.js";
import { createFreshIssueRunStore, createPostgresWakeQueueAdapter, createWakeAdmissionWriter } from "../../modules/wake-queue/adapters/postgres.js";
import { createReleaseIssueExecution } from "../../modules/wake-queue/application/use-cases.js";
import { closeProcessRunAdmission, resetProcessRunAdmissionForTests } from "./run-admission.js";
import { createHeartbeatQueue, DEFERRED_WAKE_CONTEXT_KEY, notifyOtherAgentsQueuedOnSettledIssue, shouldDeferFollowupWakeForSameIssue, shouldQueueFollowupForRunningIssueWake, type HeartbeatQueueDependencies } from "./queue.js";
import { bindFreshIssueRunAdmission, createWakeQueue } from "../../modules/wake-queue/index.js";
import { createWakeQueue } from "../../modules/wake-queue/index.js";
import { TransactionScope } from "../../modules/wake-queue/application/ports.js";
import { enrichWakeContextSnapshot, mergeCoalescedContextSnapshot } from "./run-preparation.js";
import { withQueuedCommentIdsInWakePayload, withQueuedCommentIdsInRunContext } from "../issue-queued-comment-queue.js";
@@ -494,6 +494,49 @@ describe.skipIf(!support.supported)("heartbeat queue database wiring", () => {
return { company, agent, issue, wake, run };
}
it.each([true, false])("adopts only eligible saved comments from the exact reassignment source (%s)", async (matchingIssue) => {
const { user, company, agent, issue, deps, queue } = await waitingConversationFixture();
await db.update(issues).set({ conversationAgentId: null, conversationUserId: null,
conversationState: null, status: "todo" }).where(eq(issues.id, issue.id));
const [previousAgent] = await db.insert(agents).values({ companyId: company.id,
name: "Previous assignee", adapterType: "process" }).returning();
const [interruptedRun] = await db.insert(heartbeatRuns).values({ companyId: company.id, agentId: previousAgent.id,
status: "cancelled", errorCode: "issue_reassigned", finishedAt: new Date(),
contextSnapshot: { issueId: matchingIssue ? issue.id : randomUUID() } }).returning();
const [earlier, later] = await db.insert(issueComments).values(["Earlier", "Later"].map(body => ({
companyId: company.id, issueId: issue.id, authorType: "user" as const, authorUserId: user.id, body,
}))).returning();
const [local, handoff, chat, interaction] = await db.insert(agentWakeupRequests).values([
{ agentId: agent.id, commentId: later.id, requestedAt: new Date(2) },
{ agentId: previousAgent.id, commentId: earlier.id, requestedAt: new Date(1) },
{ agentId: agent.id, commentId: randomUUID(), requestedAt: new Date(3), idempotencyKey: `chat-inbound:${randomUUID()}` },
{ agentId: agent.id, commentId: randomUUID(), requestedAt: new Date(4), mutation: "interaction" },
].map(({ agentId, commentId, requestedAt, idempotencyKey, mutation }) => ({
companyId: company.id, agentId, source: "automation", reason: "issue_commented", status: "deferred_issue_execution",
requestedAt, idempotencyKey, requestedByActorType: "user", requestedByActorId: user.id,
payload: withQueuedCommentIdsInWakePayload({ issueId: issue.id, mutation }, [commentId]),
}))).returning();
const run = await queue.enqueueWakeup(agent.id, {
source: "assignment", triggerDetail: "system", reason: "issue_assigned", requestedByActorType: "system",
payload: { issueId: issue.id }, contextSnapshot: { issueId: issue.id, interruptedRunId: interruptedRun.id },
});
const commentIds = matchingIssue ? [earlier.id, later.id] : [later.id];
expect(run).toMatchObject({ status: "queued", responsibleUserId: user.id, invocationSource: "assignment",
contextSnapshot: { wakeCommentIds: commentIds, wakeCommentId: later.id,
queuedCommentSourceWakeIds: matchingIssue ? [handoff.id, local.id] : [local.id] } });
const receipts = new Map((await db.select().from(agentWakeupRequests)).map(wake => [wake.id, wake]));
expect(receipts.get(run!.wakeupRequestId!)).toMatchObject({ runId: run!.id, source: "assignment",
requestedByActorType: "system", payload: { _paperclipWakeContext: { wakeCommentIds: commentIds } } });
expect(receipts.get(local.id)).toMatchObject({ status: "coalesced", runId: run!.id, requestedByActorId: user.id });
expect(receipts.get(handoff.id)).toMatchObject(matchingIssue
? { status: "coalesced", runId: run!.id, agentId: previousAgent.id }
: { status: "deferred_issue_execution", runId: null });
for (const receipt of [chat, interaction]) expect(receipts.get(receipt.id)).toEqual(receipt);
expect(deps.executeRun).not.toHaveBeenCalled();
});
it("only promotes a deferred chat receipt for its agent and binds receipts within its company", async () => {
const local = await fixture("queued");
const [foreignCompany] = await db.insert(companies).values({ name: "Other company", issuePrefix: "OC" }).returning();
@@ -510,13 +553,11 @@ describe.skipIf(!support.supported)("heartbeat queue database wiring", () => {
}).returning();
await db.transaction(async (tx) => {
const admission = bindFreshIssueRunAdmission(local.company.id, tx as unknown as Db);
expect(await admission.createReceipt({
deferredChatReceiptId: localDeferredWake.id, agentId: foreignAgent.id, source: "automation",
triggerDetail: null, reason: null, payload: null, requestedByActorType: null,
requestedByActorId: null, idempotencyKey: null,
const store = createFreshIssueRunStore(TransactionScope.create(local.company.id, tx), local.company.id);
expect(await store.saveReceipt({
kind: "promote", wakeId: localDeferredWake.id, agentId: foreignAgent.id, payload: null,
})).toBeUndefined();
await admission.bindReceipts({
await store.bindReceipts({
wakeId: foreignWake.id, runId: local.run.id, failedChatRetryReceiptId: foreignWake.id,
adopted: { wakeIds: [foreignWake.id, localDeferredWake.id], payload: { replaced: true } },
});
+42 -127
View File
@@ -144,11 +144,12 @@ import { isUniqueViolation } from "../../db-errors.js";
import { publishLiveEvent } from "../live-events.js";
import { allocateHeartbeatRunEventSeq } from "../heartbeat-run-events.js";
import {
DEFERRED_WAKE_CONTEXT_KEY,
queuedCommentIdsFromWakePayload,
queuedCommentIdsFromRunContext,
withQueuedCommentIdsInWakePayload,
withQueuedCommentIdsInRunContext,
} from "../issue-queued-comment-queue.js";
} from "../../lib/queued-comment-context.js";
import { parseObject } from "../../adapters/utils.js";
import { isExternalChatWaitAuthorizationContention } from "../native-runtime/chat-attachment-reuse.js";
import { emitAgentTaskRun } from "../agent-task-run-telemetry.js";
@@ -278,7 +279,7 @@ export interface HeartbeatQueueDependencies extends Pick<HeartbeatRetryDependenc
export const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext";
export { DEFERRED_WAKE_CONTEXT_KEY } from "../../lib/queued-comment-context.js";
export const EXECUTION_PATH_HEARTBEAT_RUN_STATUSES = [
"queued",
@@ -5074,141 +5075,55 @@ export function createHeartbeatQueue(db: Db, dependencies: HeartbeatQueueDepende
}, issueActivityPublications);
}
const freshIssueRun = bindFreshIssueRunAdmission(agent.companyId, tx as unknown as Db);
const wakeupRequest = await freshIssueRun.createReceipt({
const admitFreshIssueRun = bindFreshIssueRunAdmission(agent.companyId, tx as unknown as Db);
const newRun = await admitFreshIssueRun({
receipt: {
agentId,
source,
triggerDetail,
reason,
payload,
requestedByActorType: opts.requestedByActorType ?? null,
requestedByActorId: opts.requestedByActorId ?? null,
idempotencyKey: opts.idempotencyKey ?? null,
},
issue: { id: issue.id, assigneeAgentId: issue.assigneeAgentId, isConversation: isConversation(issue) },
durableReceipt: receiptRequest,
deferredChatReceiptId: durableRequest && executionWaitRequestId === durableRequest.id
? durableRequest.id : undefined,
agentId,
source,
triggerDetail,
reason,
payload,
requestedByActorType: opts.requestedByActorType ?? null,
requestedByActorId: opts.requestedByActorId ?? null,
idempotencyKey: opts.idempotencyKey ?? null,
});
if (!wakeupRequest) return { kind: "deferred" as const };
// A handoff changes the executor, not the owner of saved user input.
// Validate its exact stopped source while the issue row is locked;
// unrelated agents and dedicated continuations keep their own wakes.
const interruptedRunId = readNonEmptyString(enrichedContextSnapshot.interruptedRunId);
const handoffSource = source === "assignment" && reason === "issue_assigned" &&
issue.assigneeAgentId === agentId && interruptedRunId && isUuidLike(interruptedRunId)
? await tx.select({ agentId: heartbeatRuns.agentId }).from(heartbeatRuns).where(and(
eq(heartbeatRuns.id, interruptedRunId), eq(heartbeatRuns.companyId, issue.companyId),
eq(heartbeatRuns.status, "cancelled"), eq(heartbeatRuns.errorCode, "issue_reassigned"),
ne(heartbeatRuns.agentId, agentId),
sql`${heartbeatRuns.contextSnapshot}->>'issueId' = ${issue.id}`,
or(isNull(heartbeatRuns.nativeIssueId), eq(heartbeatRuns.nativeIssueId, issue.id)),
)).then(rows => rows[0] ?? null)
: null;
// External input owns an exact authorized source batch. Board input
// must retain its separate receipt, including during normal resume.
const canCoalesceComments = !durableRequest && !isConversation(issue) && opts.allowRunCoalescing !== false;
// A resumed receipt already passed admission under this issue lock.
// Consume it with its successor even when chat keeps other messages
// in separate turns, or finalization will deliver it a second time.
const pendingComments =
(executionWaitRequestId || canCoalesceComments) &&
(ownsReconstructionContinuation || !(await getExecutionBlocker(tx as unknown as Db, issue.companyId, issue.id)))
? await tx
.select()
.from(agentWakeupRequests)
.where(
and(
eq(agentWakeupRequests.companyId, issue.companyId),
inArray(agentWakeupRequests.agentId, handoffSource ? [agentId, handoffSource.agentId] : [agentId]),
eq(agentWakeupRequests.status, "deferred_issue_execution"),
sql`${agentWakeupRequests.payload}->>'issueId' = ${issue.id}`,
// Chat Retry already pins its complete authorized source
// batch. Keep separate board input for its own admission.
canCoalesceComments || (opts.taskRetryRequestId && !failedChatRetry)
? undefined : eq(agentWakeupRequests.id, executionWaitRequestId!),
),
)
.orderBy(asc(agentWakeupRequests.requestedAt))
: [];
const adoptedComments = pendingComments.filter((wake) => {
if (wake.id === executionWaitRequestId) return true;
if (wake.id === opts.queuedCommentInterruptId || wake.id === opts.queuedCommentRequestId) return true;
const deferredPayload = parseObject(wake.payload);
const deferredContext = parseObject(
deferredPayload[DEFERRED_WAKE_CONTEXT_KEY],
);
// Dedicated interaction wakes carry their own source and session
// contract. ID-only adoption must not erase that continuation.
return (
// Durable chat work must keep its receipt, actor, source, and
// session contract through normal promotion and authorization.
!wake.idempotencyKey?.startsWith("chat-inbound:") &&
!isInteractionResolutionWakePayload(deferredPayload) &&
!hasInteractionContinuationWakeContext(deferredContext) &&
["issue_commented", "issue_reopened_via_comment"].includes(String(deferredContext.wakeReason ?? wake.reason)) &&
queuedCommentIdsFromWakePayload(wake.payload).length > 0
);
});
let adoptedCommentIds = [
...new Set([
...adoptedComments.flatMap((wake) =>
queuedCommentIdsFromWakePayload(wake.payload),
),
...queuedCommentIdsFromRunContext(enrichedContextSnapshot),
]),
];
if (opts.queuedCommentRequestId || (opts.taskRetryRequestId && !failedChatRetry) || handoffSource) {
adoptedCommentIds = await undeliveredLegacyUserCommentIds(tx as unknown as Db,
agent.companyId, issueId, agentId, adoptedCommentIds);
}
await notifyChatRunMilestones(tx, { companyId: agent.companyId, issueId: issueId ?? undefined });
const newRun = await freshIssueRun.createRun({
durableChatReceiptId: durableRequest?.id,
allowRunCoalescing: opts.allowRunCoalescing,
executionWaitRequestId,
queuedCommentInterruptId: opts.queuedCommentInterruptId,
queuedCommentRequestId: opts.queuedCommentRequestId,
boardRetryReceiptId: failedChatRetry ? undefined : opts.taskRetryRequestId,
failedChatRetryReceiptId: failedChatRetry ? opts.taskRetryRequestId : undefined,
ownsReconstructionContinuation: Boolean(ownsReconstructionContinuation),
explicitContinuationRunId: explicitContinuation ? explicitContinuationRunId : null,
agentId,
issueId: enrichedContextSnapshot.issueId,
invocationSource: source,
triggerDetail,
responsibleUserId: await resolveQueuedResponsibleUserId(),
wakeupRequestId: wakeupRequest.id,
retryOfRunId: failedChatRetry
? durableRequest!.failedRunRetry!.failedRunId
: opts.failedRunId ?? automaticParentRunId,
contextSnapshot: adoptedComments.length
? withQueuedCommentIdsInRunContext(
enrichedContextSnapshot,
adoptedCommentIds,
adoptedComments.map((wake) => wake.id),
)
: enrichedContextSnapshot,
contextSnapshot: enrichedContextSnapshot,
sessionIdBefore: sessionBefore,
continuationAttempt,
reconciledSourceRunId,
reconciledRestoreRetryCount,
resolveResponsibleUserId: resolveQueuedResponsibleUserId,
async recordContinuationDelivery(runId) {
if (ownsReconstructionContinuation) {
await tx.update(issueRecoveryActions).set({ evidence: sql`${issueRecoveryActions.evidence} || ${JSON.stringify({
continuationDelivery: "delivered", continuationRunId: runId,
})}::jsonb` }).where(and(eq(issueRecoveryActions.companyId, issue.companyId),
eq(issueRecoveryActions.id, String(enrichedContextSnapshot.recoveryActionId)),
sql`${issueRecoveryActions.evidence}->>'continuationDelivery' = 'pending'`));
}
if (continuationToDeliver)
await deliverContinuationAsRun(tx as unknown as Db, { companyId: issue.companyId, issueId: issue.id,
runId, continuation: continuationToDeliver });
else if (reconciledSourceRunId)
await foldWaitingRetriesIntoRecordedContinuation(tx as unknown as Db, { companyId: issue.companyId, issueId: issue.id,
runId, recoveryActionId: readNonEmptyString(enrichedContextSnapshot.recoveryActionId), sourceRunId: reconciledSourceRunId });
},
});
if (ownsReconstructionContinuation) {
await tx.update(issueRecoveryActions).set({ evidence: sql`${issueRecoveryActions.evidence} || ${JSON.stringify({
continuationDelivery: "delivered", continuationRunId: newRun.id,
})}::jsonb` }).where(and(eq(issueRecoveryActions.companyId, issue.companyId),
eq(issueRecoveryActions.id, String(enrichedContextSnapshot.recoveryActionId)),
sql`${issueRecoveryActions.evidence}->>'continuationDelivery' = 'pending'`));
}
if (continuationToDeliver)
await deliverContinuationAsRun(tx as unknown as Db, { companyId: issue.companyId, issueId: issue.id, runId: newRun.id,
continuation: continuationToDeliver });
else if (reconciledSourceRunId)
await foldWaitingRetriesIntoRecordedContinuation(tx as unknown as Db, { companyId: issue.companyId, issueId: issue.id,
runId: newRun.id, recoveryActionId: readNonEmptyString(enrichedContextSnapshot.recoveryActionId), sourceRunId: reconciledSourceRunId });
await freshIssueRun.bindReceipts({
wakeId: wakeupRequest.id,
runId: newRun.id,
failedChatRetryReceiptId: failedChatRetry ? opts.taskRetryRequestId : undefined,
adopted: adoptedComments.length ? {
wakeIds: adoptedComments.map((wake) => wake.id),
payload: withQueuedCommentIdsInWakePayload(payload, adoptedCommentIds),
} : undefined,
});
if (!newRun) return { kind: "deferred" as const };
// executionRunId is NOT stamped here (enqueueWakeup queues the run but
// doesn't start it). It will be stamped in claimQueuedRun() once the run
@@ -1,8 +1,12 @@
import { createHash } from "node:crypto";
import type { IssueComment, IssueQueuedCommentQueue } from "@paperclipai/shared";
const QUEUE_CONTEXT_KEY = "_paperclipWakeContext";
const QUEUE_IDS_KEY = "wakeCommentIds";
export {
queuedCommentIdsFromRunContext,
queuedCommentIdsFromWakePayload,
withQueuedCommentIdsInRunContext,
withQueuedCommentIdsInWakePayload,
} from "../lib/queued-comment-context.js";
function record(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -10,51 +14,6 @@ function record(value: unknown): Record<string, unknown> {
: {};
}
function uniqueIds(value: unknown): string[] {
if (!Array.isArray(value)) return [];
const seen = new Set<string>();
return value.flatMap((candidate) => {
if (typeof candidate !== "string" || !candidate || seen.has(candidate)) return [];
seen.add(candidate);
return [candidate];
});
}
export function queuedCommentIdsFromWakePayload(payloadValue: unknown): string[] {
const payload = record(payloadValue);
const context = record(payload[QUEUE_CONTEXT_KEY]);
return uniqueIds(context[QUEUE_IDS_KEY]);
}
export function queuedCommentIdsFromRunContext(contextValue: unknown): string[] {
return uniqueIds(record(contextValue)[QUEUE_IDS_KEY]);
}
export function withQueuedCommentIdsInWakePayload(
payloadValue: unknown,
ids: string[],
options: { preserveSource?: boolean } = {},
): Record<string, unknown> {
const payload = { ...record(payloadValue) };
const context = { ...record(payload[QUEUE_CONTEXT_KEY]) };
if (ids.length > 0) {
const latestId = ids[ids.length - 1]!;
context[QUEUE_IDS_KEY] = ids;
if (!options.preserveSource) {
context.wakeCommentId = latestId;
context.commentId = latestId;
payload.commentId = latestId;
}
} else {
delete context[QUEUE_IDS_KEY];
delete context.wakeCommentId;
delete context.commentId;
delete payload.commentId;
}
payload[QUEUE_CONTEXT_KEY] = context;
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
@@ -76,41 +35,6 @@ export function queuedCommentQueueRevision(input: {
.slice(0, 32);
}
export function withQueuedCommentIdsInRunContext(
contextValue: unknown,
ids: string[],
sourceWakeIds?: string[],
): Record<string, unknown> {
const context = { ...record(contextValue) };
if (sourceWakeIds) {
context.queuedCommentSourceWakeIds = uniqueIds([
...uniqueIds(context.queuedCommentSourceWakeIds),
...sourceWakeIds,
]);
}
if (ids.length > 0) {
const latestId = ids[ids.length - 1]!;
context[QUEUE_IDS_KEY] = ids;
context.wakeCommentId = latestId;
context.commentId = latestId;
} else {
delete context[QUEUE_IDS_KEY];
delete context.wakeCommentId;
delete context.commentId;
}
// These projections are generated immediately before dispatch. Any queue
// mutation must force them to be rebuilt from the canonical comment ids.
delete context.paperclipWake;
delete context.paperclipWakeComment;
delete context.paperclipTaskMarkdown;
delete context.paperclipTaskMarkdownCompact;
delete context.paperclipTaskMarkdownAssignment;
delete context.paperclipTaskMarkdownAssignmentCompact;
delete context.paperclipTurnContext;
return context;
}
export type QueuedCommentQueueProtocol = "paperclip_runner_v1" | "legacy";
export type QueuedCommentQueueSteeringDecision =