From 6ac7211cb9d81ff9f425480e2db4eeb76a1f8690 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:23:34 -0600 Subject: [PATCH] fix(heartbeat): stop re-delivering a remote-stop follow-up that a succeeded run already read (#21203) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A person's follow-up comment must reach the agent once > - #21175 made a succeeded run's mid-turn read of a comment (through `get_task_history`) count as delivery for the queued-comment paths > - The remote-Stop resume path decides delivery with `undeliveredLegacyUserCommentIds`, which ignores those reads > - So a follow-up that a succeeded run already read was sent again, and the agent posted a second DONE on a finished task > - This pull request applies the same rule on that path and adds a read helper for a later change > - The benefit is one answer per follow-up on every resume path, with no dropped messages ## Linked Issues or Issue Description Refs #21175 **What happened?** A saved follow-up comment was resumed after a remote Stop (wake reason `issue_commented`, idempotency key `remote-stop-comment:…`). A succeeded run had already read this comment mid-turn. The resumed wake started a new turn, and the agent posted a second DONE on a finished task. The cause: `undeliveredLegacyUserCommentIds` (explicit-native-continuation.ts) checks only wake input and accepted first turns. It does not check the `task_history.read` records that #21175 added. **Expected behavior** A follow-up that a succeeded run read at its current revision is delivered. The remote-Stop resume path skips it. A read by a run that did not succeed does not count, so that follow-up is still delivered once. **Steps to reproduce** 1. A native run reads the task history after a person posts a follow-up. 2. The run succeeds. The follow-up stays saved as a deferred wake. 3. The remote-Stop resume path runs for that wake. 4. Before this change, the follow-up is delivered again. **Paperclip version or commit** `master` at 549816e6a0. ## What Changed - `server/src/services/queued-comment-delivery.ts`: `historyReadDeliveredCommentIds` exposes the #21175 rule for a list of comment IDs. `taskHistoryReadsForRun({ companyId, runId })` returns each comment one run read, with the read time and the comment revision that the read returned. It returns these whatever the run's outcome. It reads only that run's events through `heartbeat_run_events_company_run_idx`. No delivery decision uses it. - `server/src/services/explicit-native-continuation.ts`: `undeliveredLegacyUserCommentIds` also removes comments that a succeeded run read at their current revision. Its two callers are the remote-Stop resume path and the queued explicit-continuation check, and both now use the #21175 rule. - Deliberate asymmetry: a read by a run that did not succeed never counts. A dropped person's message is worse than a duplicate answer. - `doc/run-log-events.md`: documents both points. - New test file `server/src/services/queued-comment-history-read.test.ts`. ## Verification - RED on `549816e6a0` (`npx vitest run src/services/queued-comment-history-read.test.ts`): 2 failed, 1 passed. - The follow-up that a succeeded run read was still returned as owed. - `taskHistoryReadsForRun` did not exist. - The case where a failed run read the follow-up (still owed) passed, as intended. - GREEN: 3/3 pass. - Neighbouring suites (`first-turn-queued-input`, `explicit-native-continuation`, `heartbeat-agent-directory-busy`, `heartbeat-held-comment-wake`, `execution-control-work`): 517/517 pass. Server `tsc` is clean. ## Risks - Low risk. The function and its callers keep their contract. It returns fewer comment IDs only when a succeeded run of the assignee read that exact revision. - Comments read through the REST API by non-native adapters are not recorded, so their behavior does not change. - No migration. The added lookup uses the time-bounded, index-backed query from #21175. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (shell, file edit, test execution). ## 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 --- doc/run-log-events.md | 6 +- .../services/explicit-native-continuation.ts | 6 +- .../src/services/queued-comment-delivery.ts | 29 ++++++++ .../queued-comment-history-read.test.ts | 73 +++++++++++++++++++ 4 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 server/src/services/queued-comment-history-read.test.ts diff --git a/doc/run-log-events.md b/doc/run-log-events.md index 0c80422eff0..5615b6851a4 100644 --- a/doc/run-log-events.md +++ b/doc/run-log-events.md @@ -1017,7 +1017,11 @@ wake then neither reopens the finished task nor starts another turn. An edit after the read, or a read by a run that did not succeed, leaves the comment owed, so it is delivered once. The check reads only the assignee's succeeded runs of that task that finished at or after the comment's current revision, -through the existing run-binding and `(company_id, run_id)` event indexes. A failure to write the event leaves the comment +through the existing run-binding and `(company_id, run_id)` event indexes. +A saved follow-up resumed after a remote Stop uses the same rule. A read by a +run that did not succeed never counts. `taskHistoryReadsForRun` lists the +comments one run read, with each read's time and the comment revision it saw, +whatever the run's outcome. A failure to write the event leaves the comment owed in the same way. ## Managed Agent File Save Receipts diff --git a/server/src/services/explicit-native-continuation.ts b/server/src/services/explicit-native-continuation.ts index c02780a1b6c..f3f4bc110f8 100644 --- a/server/src/services/explicit-native-continuation.ts +++ b/server/src/services/explicit-native-continuation.ts @@ -35,7 +35,7 @@ import { activeIssueInteractionCondition } from "./issue-question-context.js"; import { historicalAdapterType, isConversationAdapter } from "./conversation-continuation.js"; import { queuedCommentIdsFromWakePayload } from "./issue-queued-comment-queue.js"; -import { firstTurnDeliveredCommentIds } from "./queued-comment-delivery.js"; +import { firstTurnDeliveredCommentIds, historyReadDeliveredCommentIds } from "./queued-comment-delivery.js"; import { canResumePreservedResultFinalization } from "./preserved-result-finalization.js"; import { isServerReplacementInterruption } from "./server-replacement-interruption.js"; import { normalizeAgentNameKey } from "./agent-name-key.js"; @@ -129,7 +129,9 @@ export async function undeliveredLegacyUserCommentIds( } // An accepted first turn that took a queued message consumed it too. const firstTurn = await firstTurnDeliveredCommentIds(db, { companyId, issueId, agentId, commentIds: [...valid] }); - return commentIds.filter(id => valid.has(id) && !firstTurn.has(id)); + const historyRead = await historyReadDeliveredCommentIds(db, { companyId, issueId, agentId, + commentIds: [...valid].filter(id => !firstTurn.has(id)) }); + return commentIds.filter(id => valid.has(id) && !firstTurn.has(id) && !historyRead.has(id)); } /** Called under the issue lock, in the transaction that creates the new turn. diff --git a/server/src/services/queued-comment-delivery.ts b/server/src/services/queued-comment-delivery.ts index 69d97ee4d41..98664b6ef78 100644 --- a/server/src/services/queued-comment-delivery.ts +++ b/server/src/services/queued-comment-delivery.ts @@ -59,6 +59,35 @@ export async function recordTaskHistoryRead(db: Db, input: { payload: { comments: Object.fromEntries(input.comments.map(comment => [comment.id, comment.updatedAt.toISOString()])) } }); } +export async function taskHistoryReadsForRun(db: Pick, input: { companyId: string; runId: string }): Promise> { + const rows = await db.select({ readAt: heartbeatRunEvents.createdAt, payload: heartbeatRunEvents.payload }) + .from(heartbeatRunEvents).where(and(eq(heartbeatRunEvents.companyId, input.companyId), + eq(heartbeatRunEvents.runId, input.runId), eq(heartbeatRunEvents.eventType, TASK_HISTORY_READ_EVENT))) + .orderBy(heartbeatRunEvents.seq); + const latest = new Map(); + for (const row of rows) { + const comments = row.payload?.comments; + if (!comments || typeof comments !== "object" || Array.isArray(comments)) continue; + for (const [commentId, value] of Object.entries(comments as Record)) { + const revision = typeof value === "string" ? new Date(value) : null; + if (revision && !Number.isNaN(revision.getTime())) latest.set(commentId, { commentId, readAt: row.readAt, revision }); + } + } + return [...latest.values()]; +} + +export async function historyReadDeliveredCommentIds(tx: Pick, input: { + companyId: string; issueId: string; agentId: string; commentIds: string[]; +}): Promise> { + if (input.commentIds.length === 0) return new Set(); + const rows = await tx.select({ id: issueComments.id }).from(issueComments).where(and( + eq(issueComments.companyId, input.companyId), eq(issueComments.issueId, input.issueId), + inArray(issueComments.id, input.commentIds), historyReadDeliveredSql(input.companyId, input.issueId, input.agentId))); + return new Set(rows.map(row => row.id)); +} + function historyReadDeliveredSql(companyId: string, issueId: string, agentId: string) { const readBy = (binding: SQL) => sql`exists (select 1 from ${heartbeatRuns} reading_run cross join lateral (select 1 from ${heartbeatRunEvents} history_read diff --git a/server/src/services/queued-comment-history-read.test.ts b/server/src/services/queued-comment-history-read.test.ts new file mode 100644 index 00000000000..8f04500a9bc --- /dev/null +++ b/server/src/services/queued-comment-history-read.test.ts @@ -0,0 +1,73 @@ +import { randomUUID } from "node:crypto"; +import { eq } from "drizzle-orm"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { agents, companies, createDb, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS, heartbeatRuns, issueComments, issues } from "@paperclipai/db"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "../__tests__/helpers/embedded-postgres.js"; +import { undeliveredLegacyUserCommentIds } from "./explicit-native-continuation.js"; +import { PaperclipRunnerToolAuthority } from "./native-runtime/paperclip-runner-tool-authority.js"; +import { taskHistoryReadsForRun } from "./queued-comment-delivery.js"; + +const support = await getEmbeddedPostgresTestSupport(); +const USER = "history-read-user"; + +describe.skipIf(!support.supported)("task history reads", () => { + let database: Awaited>; + let db: ReturnType; + beforeAll(async () => { + database = await startEmbeddedPostgresTestDatabase("paperclip-history-read-"); + db = createDb(database.connectionString); + }, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS); + afterAll(async () => { await db?.$client.end(); await database?.cleanup(); }); + + async function seed() { + const [company] = await db.insert(companies).values({ name: "History read", issuePrefix: `H${randomUUID().slice(0, 4)}` }).returning(); + const [agent] = await db.insert(agents).values({ companyId: company!.id, name: "Codie", adapterType: "paperclip_runner" }).returning(); + const issueId = randomUUID(); + const [run] = await db.insert(heartbeatRuns).values({ companyId: company!.id, agentId: agent!.id, status: "running", + runtimeMode: "native", runtimeModeResolvedAt: new Date(), nativeIssueId: issueId, + startedAt: new Date(Date.now() - 60_000), contextSnapshot: { issueId } }).returning(); + await db.insert(issues).values({ id: issueId, companyId: company!.id, title: "Fix the reports", status: "in_progress", + assigneeAgentId: agent!.id, executionRunId: run!.id }); + return { companyId: company!.id, agentId: agent!.id, issueId, runId: run!.id }; + } + + const comment = async (f: Awaited>, body: string) => (await db.insert(issueComments).values({ + companyId: f.companyId, issueId: f.issueId, authorType: "user", authorUserId: USER, body }).returning())[0]!; + + async function readHistory(f: Awaited>) { + const reader = new PaperclipRunnerToolAuthority(db, { companyId: f.companyId, agentId: f.agentId, issueId: f.issueId, runId: f.runId }); + try { await reader.execute({ tool: "get_task_history", callId: randomUUID(), arguments: {} }); } finally { reader.close(); } + } + + const finish = (f: { runId: string }, status: "succeeded" | "failed") => db.update(heartbeatRuns) + .set({ status, finishedAt: new Date(Date.now() + 1_000) }).where(eq(heartbeatRuns.id, f.runId)); + + it("lists the comments a failed run read, with the read time and the revision it saw", async () => { + const f = await seed(); + const first = await comment(f, "Also include the FOLLOWUP line."); + const second = await comment(f, "And keep the ledger sorted."); + const before = new Date(); + await readHistory(f); + await finish(f, "failed"); + const reads = await taskHistoryReadsForRun(db, { companyId: f.companyId, runId: f.runId }); + expect(reads.map(read => read.commentId).sort()).toEqual([first.id, second.id].sort()); + for (const read of reads) { + const seen = read.commentId === first.id ? first : second; + expect(read.revision.toISOString()).toBe(seen.updatedAt.toISOString()); + expect(read.readAt.getTime()).toBeGreaterThanOrEqual(before.getTime() - 1_000); + } + expect(await taskHistoryReadsForRun(db, { companyId: randomUUID(), runId: f.runId })).toEqual([]); + }); + + it.each([ + { status: "succeeded" as const, owed: false }, + { status: "failed" as const, owed: true }, + ])("treats a remote-stop follow-up that a $status run read mid-turn as owed: $owed", async ({ status, owed }) => { + const f = await seed(); + const followUp = await comment(f, "Additional requirement: include the FOLLOWUP line."); + await readHistory(f); + await finish(f, status); + expect(await undeliveredLegacyUserCommentIds(db, f.companyId, f.issueId, f.agentId, [followUp.id])) + .toEqual(owed ? [followUp.id] : []); + }); +});