From 3cd671575d62d5d94d324a604329aecca6c92088 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:04:30 -0600 Subject: [PATCH] perf(attention): scope native finalization retention hints to the run's task graph (#21521) 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 > - The server archives old attention items (reviews, blocked tasks, decisions, failed runs) in a background queue, `attention-retention`. > - A hint for a whole company makes this queue reload every attention candidate of the company, 100 per page. Each page also reads review attention, blocker graphs and source evidence. > - Each native run finalization sent such a company hint, although a run changes only the attention items of its own task graph. > - On a hosted instance with about 1,400 open tasks and live native runs, the decision retention read ran 26.7 times per second. Native run finalization is one of the producers that sent a company hint on every run. > - The same finalization already sends the issue-scoped hint through `notifyNativeStatusReassessment` when the run has a task or a run id. This pull request sends the company hint only when the run has neither. > - The benefit is that a finished run reloads only the candidates of its task, its ancestors and the tasks it blocks, not every candidate of the company. ## Linked Issues or Issue Description No issue exists. This describes the problem with the fields of `.github/ISSUE_TEMPLATE/enhancement.yml`. **What existing behavior does this improve?** The attention retention hint that native run finalization sends (`notifyNativeFinalizationWork` in `server/src/services/native-finalization-notifications.ts`). **Current behavior** `notifyNativeFinalizationWork` calls `notifyAttentionRetentionWork(tx, { companyId })`. The `attention-retention` queue has no reconstruction interval, so each finalization reloads all eight candidate kinds of the company, page by page, with the batch eligibility reads for each page. **Proposed behavior** `notifyNativeFinalizationWork` sends the company hint only when the scope has no `issueId` and no `runId`. Otherwise `notifyNativeStatusReassessment`, which the same function already calls, sends `notifyIssueAttentionRetentionWork(tx, { companyId, issueId, runId })`. That helper resolves the task of the run, adds its parents and the tasks it blocks (at most 100), and sends a hint with these task ids. When the run has no task, or the graph has more than 100 tasks, the helper sends the company hint itself. **Reason and benefit** Background work must not grow with the backlog of open tasks. The attention items that a run can change are the failed run, the review, the recovery actions, the decisions and the blocker items of its task graph. The issue-scoped hint covers all of them, and the ordinary task write path uses the same helper. ## What Changed - `server/src/services/native-finalization-notifications.ts`: send the company attention retention hint only for a finalization without a task or run. - `server/src/__tests__/attention-retention-work.test.ts`: new test `scopes native run finalization to the task graph of the run`. ## Verification - The new test sends the finalization hint once with a run id and once with a task id. Before the change both hints are `{ companyId }`. After the change both hints name the task and its parent. - `npx vitest run src/__tests__/attention-retention-work.test.ts` and the native work tests (`native-result-commit-work`, `native-environment-settlement-work`, `native-run-projection-work`, `native-recovery-notice-work`, `retained-native-session-cleanup-work`, `native-status-reassessment-work`, `muse-terminal-settlement`, `ownership-reconciliation-report`) pass (in `server/`). - `pnpm check:module-boundaries` passes. ## Risks - No new reads. The issue-scoped hint was already computed in the same transaction by `notifyNativeStatusReassessment`. - An attention item outside the task graph of the run is not reloaded by this hint. Agent status, budget and company changes keep their own hints. - Low risk. No schema change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## 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 - [ ] 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 --- .../__tests__/attention-retention-work.test.ts | 18 ++++++++++++++++++ .../native-finalization-notifications.ts | 2 +- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/server/src/__tests__/attention-retention-work.test.ts b/server/src/__tests__/attention-retention-work.test.ts index 916bde23579..cb08a3de0e8 100644 --- a/server/src/__tests__/attention-retention-work.test.ts +++ b/server/src/__tests__/attention-retention-work.test.ts @@ -21,6 +21,7 @@ import { issueThreadInteractionService } from "../services/issue-thread-interact import { createAgentLifecycle } from "../services/agent-lifecycle.js"; import { BLOCKER_ATTENTION_MAX_DEPTH, BLOCKER_ATTENTION_MAX_NODES, issueService } from "../services/issues.js"; import { notifyAttentionRetentionWork, notifyIssueAttentionRetentionWork } from "../services/retention-work-notifications.js"; +import { notifyNativeFinalizationWork } from "../services/native-finalization-notifications.js"; import { idleWorkSnapshot } from "../services/task-admission.js"; import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; @@ -859,6 +860,23 @@ const delay = DEFAULT_DECISION_ARCHIVE_DAYS * 86_400_000; expect(hints).toEqual([JSON.stringify({ companyId, issueId: issue.id }), JSON.stringify({ companyId })]); }); + it("scopes native run finalization to the task graph of the run", async () => { + const parent = await insertIssue("blocked"); + const issue = await insertIssue("todo", { parentId: parent.id }); + const [run] = await db.insert(heartbeatRuns).values({ companyId, agentId, status: "succeeded", + contextSnapshot: { issueId: issue.id } }).returning(); + const hints: string[] = []; + const unsubscribe = subscribeDatabaseWork(db, DELIVERY_QUEUES.attentionRetention, (event, values) => { + if (event === "settled") hints.push(...values ?? []); + }); + try { + await db.transaction(tx => notifyNativeFinalizationWork(tx, { companyId, runId: run.id })); + await db.transaction(tx => notifyNativeFinalizationWork(tx, { companyId, issueId: issue.id })); + } finally { unsubscribe(); } + const scoped = JSON.stringify({ companyId, issueIds: [issue.id, parent.id].sort() }); + expect(hints).toEqual([scoped, scoped]); + }); + it("accepts ordinary liveness incident creation and completion with a none leaf sentinel", async () => { const source = await insertIssue("blocked", { responsibleUserId: "board" }); const service = issueService(db); diff --git a/server/src/services/native-finalization-notifications.ts b/server/src/services/native-finalization-notifications.ts index cae576bd2bb..e3d6bfba6b5 100644 --- a/server/src/services/native-finalization-notifications.ts +++ b/server/src/services/native-finalization-notifications.ts @@ -17,7 +17,7 @@ import { notifyQueuedRunDispatch } from "./run-dispatch-notifications.js"; export type NativeFinalizationWorkScope = { companyId: string; runId?: string; issueId?: string }; export async function notifyNativeFinalizationWork(transaction: object, scope: NativeFinalizationWorkScope) { - await notifyAttentionRetentionWork(transaction, { companyId: scope.companyId }); + if (!scope.issueId && !scope.runId) await notifyAttentionRetentionWork(transaction, { companyId: scope.companyId }); if (scope.issueId || scope.runId) { await notifyLiveRunRecovery(transaction, scope); await notifyNativeEnvironmentSettlement(transaction, scope);