mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
fix(heartbeat): stop re-delivering a remote-stop follow-up that a succeeded run already read (#21203)
## 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 <noreply@anthropic.com>
This commit is contained in:
1 parent
57aeda190b
commit
6ac7211cb9
4 files changed
+111
-3
No files matched your search
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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<Db, "select">, input: { companyId: string; runId: string }): Promise<Array<{
|
||||
commentId: string; readAt: Date; revision: Date;
|
||||
}>> {
|
||||
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<string, { commentId: string; readAt: Date; revision: Date }>();
|
||||
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<string, unknown>)) {
|
||||
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<Db, "select">, input: {
|
||||
companyId: string; issueId: string; agentId: string; commentIds: string[];
|
||||
}): Promise<Set<string>> {
|
||||
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
|
||||
|
||||
@@ -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<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
let db: ReturnType<typeof createDb>;
|
||||
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<ReturnType<typeof seed>>, 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<ReturnType<typeof seed>>) {
|
||||
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] : []);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user