mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
Move fresh issue run and receipt writes into wake-queue (#22266)
## Thinking Path > - Paperclip manages AI agents at work. > - Assigning a task or resuming it from a comment can create a queued run. > - The wake-queue module handles admission behind an active execution. Heartbeat also writes the receipt and run when a new execution is needed. > - These writes share the issue lock. Splitting them across transactions would allow duplicate or partially bound work. > - This change puts the fresh writes in the wake-queue module under the existing lock. ## Linked Issues or Issue Description **What existing behavior does this improve?** Creating a queued run for an assigned or continued task. **Subsystem affected** Server task admission. **Current behavior** Heartbeat constructs the receipt and run, handles retry lineage, and ties adopted receipts to the run. **Proposed behavior** Wake-queue owns receipt promotion, fresh-run construction, and receipt binding. Heartbeat still selects saved comments and orders recovery effects inside the same transaction. **Additional context** Earlier module boundaries were introduced in #13136 and #13145. ## What Changed - Move fresh receipt, run, and binding writes to a transaction-bound Postgres adapter. - Keep explicit continuation and reconciled retry lineage in the application layer. - Scope receipt updates by company and durable promotion by agent. Cover both predicates with a database test. ## Verification On commit7479acbd22, all 104 heartbeat queue tests passed using the repository Postgres command runner. All 297 assertions passed in the six-file sweep. The standalone cluster cleanup timeout also reproduced on pristine base92dbf39e6fafter all 103 base tests passed. `node cli/node_modules/tsx/dist/cli.mjs packages/db/src/test-postgres-command.ts -- node node_modules/vitest/vitest.mjs run server/src/services/heartbeat/queue.test.ts` Run `pnpm exec vitest run server/src/services/heartbeat/queue.test.ts server/src/__tests__/heartbeat-comment-wake-batching.test.ts server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts`. Run `pnpm --filter @paperclipai/server typecheck` and `node scripts/check-module-boundaries.mjs`. ## Risks Changing write order can attach the wrong receipt or lose retry lineage. The caller retains the transaction and the interleaved chat and recovery effects. This is a structural change. No latency improvement is claimed. ## 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:
1 parent
1dba97303e
commit
f324238f73
6 files changed
+231
-90
No files matched your search
@@ -85,6 +85,7 @@ import type {
|
||||
WakeQueueHost,
|
||||
WakeQueueTransaction,
|
||||
} from "../application/ports.js";
|
||||
import type { FreshIssueRunWriter } from "../application/fresh-issue-run.js";
|
||||
import type { RunSummary } from "../application/types.js";
|
||||
|
||||
const DEFERRED_WAKE_STATUS = "deferred_issue_execution";
|
||||
@@ -1535,3 +1536,54 @@ export function createPostgresWakeQueueAdapter(db: Db, deps: WakeQueuePostgresAd
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export function createFreshIssueRunWriter(
|
||||
scope: TransactionScope,
|
||||
companyId: string,
|
||||
): FreshIssueRunWriter<HeartbeatRunRow> {
|
||||
const tx = requireAdmissionTx(scope, companyId);
|
||||
return {
|
||||
async saveReceipt(input) {
|
||||
if (input.kind === "insert") {
|
||||
const [receipt] = await tx.insert(agentWakeupRequests).values({
|
||||
...input.seed, companyId, status: "queued",
|
||||
}).returning();
|
||||
return receipt;
|
||||
}
|
||||
const [receipt] = await tx.update(agentWakeupRequests).set({
|
||||
payload: input.payload, status: "queued", error: null, finishedAt: null, updatedAt: new Date(),
|
||||
}).where(and(
|
||||
eq(agentWakeupRequests.id, input.wakeId),
|
||||
eq(agentWakeupRequests.companyId, companyId),
|
||||
eq(agentWakeupRequests.agentId, input.agentId),
|
||||
eq(agentWakeupRequests.status, "deferred_issue_execution"),
|
||||
isNull(agentWakeupRequests.runId),
|
||||
)).returning();
|
||||
return receipt;
|
||||
},
|
||||
async insertQueuedRun(seed) {
|
||||
const [run] = await tx.insert(heartbeatRuns).values({
|
||||
...seed, companyId, status: "queued",
|
||||
}).returning();
|
||||
return run;
|
||||
},
|
||||
async bindReceipts({ wakeId, runId, failedChatRetryReceiptId, adopted }) {
|
||||
const inCompany = eq(agentWakeupRequests.companyId, companyId);
|
||||
const primaryReceipt = and(inCompany, eq(agentWakeupRequests.id, wakeId));
|
||||
await tx.update(agentWakeupRequests).set({ runId, updatedAt: new Date() })
|
||||
.where(primaryReceipt);
|
||||
if (failedChatRetryReceiptId) {
|
||||
await tx.update(agentWakeupRequests).set({
|
||||
status: "coalesced", runId, finishedAt: new Date(), updatedAt: new Date(),
|
||||
}).where(and(inCompany, eq(agentWakeupRequests.id, failedChatRetryReceiptId),
|
||||
eq(agentWakeupRequests.status, "deferred_issue_execution")));
|
||||
}
|
||||
if (adopted) {
|
||||
await tx.update(agentWakeupRequests).set({
|
||||
status: "coalesced", runId, finishedAt: new Date(), updatedAt: new Date(),
|
||||
}).where(and(inCompany, inArray(agentWakeupRequests.id, adopted.wakeIds)));
|
||||
await tx.update(agentWakeupRequests).set({ payload: adopted.payload }).where(primaryReceipt);
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
import type { DurableWakeAdmissionReceipt } from "./ports.js";
|
||||
import { readNonEmptyString } from "../domain/values.js";
|
||||
|
||||
type WakeReceiptSeed = {
|
||||
agentId: string;
|
||||
source: string;
|
||||
triggerDetail: string | null;
|
||||
reason: string | null;
|
||||
payload: Record<string, unknown> | null;
|
||||
requestedByActorType: string | null;
|
||||
requestedByActorId: string | null;
|
||||
idempotencyKey: string | null;
|
||||
};
|
||||
|
||||
type QueuedRunSeed = {
|
||||
id?: string;
|
||||
agentId: string;
|
||||
scopeKind: "issue" | "company";
|
||||
issueId: string | null;
|
||||
invocationSource: string;
|
||||
triggerDetail: string | null;
|
||||
responsibleUserId: string;
|
||||
wakeupRequestId: string;
|
||||
retryOfRunId: string | null;
|
||||
contextSnapshot: Record<string, unknown>;
|
||||
sessionIdBefore: string | null;
|
||||
continuationAttempt: number;
|
||||
scheduledRetryAttempt?: number;
|
||||
scheduledRetryReason?: "transient_failure";
|
||||
};
|
||||
|
||||
type SaveWakeReceipt =
|
||||
| { kind: "insert"; seed: WakeReceiptSeed & Partial<DurableWakeAdmissionReceipt> }
|
||||
| { kind: "promote"; wakeId: string; agentId: string; payload: WakeReceiptSeed["payload"] };
|
||||
|
||||
export type FreshIssueRunWriter<Run> = {
|
||||
saveReceipt(input: SaveWakeReceipt): Promise<{ id: string } | undefined>;
|
||||
insertQueuedRun(seed: QueuedRunSeed): Promise<Run>;
|
||||
bindReceipts(input: {
|
||||
wakeId: string;
|
||||
runId: string;
|
||||
failedChatRetryReceiptId?: string;
|
||||
adopted?: { wakeIds: string[]; payload: Record<string, unknown> };
|
||||
}): Promise<void>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Runs under heartbeat's existing issue lock. The caller validates admission,
|
||||
* selects saved comments and records specialized continuation delivery between
|
||||
* run creation and receipt binding.
|
||||
*/
|
||||
export function createFreshIssueRunAdmission<Run>(writer: FreshIssueRunWriter<Run>) {
|
||||
return {
|
||||
createReceipt(input: WakeReceiptSeed & {
|
||||
durableReceipt?: DurableWakeAdmissionReceipt;
|
||||
deferredChatReceiptId?: string;
|
||||
}) {
|
||||
const { durableReceipt, deferredChatReceiptId, ...seed } = input;
|
||||
// A deferred durable chat wake keeps its original identity and source.
|
||||
return writer.saveReceipt(deferredChatReceiptId
|
||||
? { kind: "promote", wakeId: deferredChatReceiptId, agentId: seed.agentId, payload: seed.payload }
|
||||
: {
|
||||
kind: "insert",
|
||||
seed: durableReceipt
|
||||
? { ...seed, id: durableReceipt.id, requestedAt: durableReceipt.requestedAt }
|
||||
: seed,
|
||||
});
|
||||
},
|
||||
createRun(input: Omit<QueuedRunSeed,
|
||||
"id" | "scopeKind" | "issueId" | "scheduledRetryAttempt" | "scheduledRetryReason"
|
||||
> & {
|
||||
explicitContinuationRunId: string | null;
|
||||
reconciledSourceRunId: string | null;
|
||||
reconciledRestoreRetryCount: number | null;
|
||||
issueId: unknown;
|
||||
}) {
|
||||
const {
|
||||
explicitContinuationRunId, reconciledSourceRunId, reconciledRestoreRetryCount, issueId, ...seed
|
||||
} = input;
|
||||
const scopedIssueId = readNonEmptyString(issueId);
|
||||
return writer.insertQueuedRun({
|
||||
...seed,
|
||||
...(explicitContinuationRunId ? { id: explicitContinuationRunId } : {}),
|
||||
scopeKind: scopedIssueId ? "issue" : "company",
|
||||
issueId: scopedIssueId,
|
||||
retryOfRunId: reconciledSourceRunId || seed.retryOfRunId,
|
||||
sessionIdBefore: explicitContinuationRunId ? null : seed.sessionIdBefore,
|
||||
...(reconciledRestoreRetryCount !== null ? {
|
||||
scheduledRetryAttempt: reconciledRestoreRetryCount,
|
||||
scheduledRetryReason: "transient_failure",
|
||||
} : {}),
|
||||
});
|
||||
},
|
||||
bindReceipts: writer.bindReceipts,
|
||||
};
|
||||
}
|
||||
@@ -1,12 +1,14 @@
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import {
|
||||
createAdmissionTransactionScope as buildAdmissionTransactionScope,
|
||||
createFreshIssueRunWriter,
|
||||
createPostgresWakeQueueAdapter,
|
||||
createWakeAdmissionReader,
|
||||
createWakeAdmissionWriter,
|
||||
} from "./adapters/postgres.js";
|
||||
import { createQueuedCommentIssueLockWriter } from "./adapters/queued-comment-postgres.js";
|
||||
import type { QueuedCommentQueuePostgresAdapterDeps } from "./adapters/queued-comment-postgres.js";
|
||||
import { createFreshIssueRunAdmission } from "./application/fresh-issue-run.js";
|
||||
import { createAdmitWakeBehindIssueExecution, createReleaseIssueExecution } from "./application/use-cases.js";
|
||||
import {
|
||||
createDiscardQueuedComment,
|
||||
@@ -110,6 +112,11 @@ export function createWakeQueue(db: Db, deps: WakeQueueDeps) {
|
||||
|
||||
export type WakeQueue = ReturnType<typeof createWakeQueue>;
|
||||
|
||||
/** Uses the transaction that already owns the issue's admission lock. */
|
||||
export function bindFreshIssueRunAdmission(companyId: string, tx: Db) {
|
||||
return createFreshIssueRunAdmission(createFreshIssueRunWriter(buildAdmissionTransactionScope(companyId, tx), companyId));
|
||||
}
|
||||
|
||||
/**
|
||||
* Composes the three queued-comment queue mutations (edit, reorder,
|
||||
* discard): the Postgres adapter, which owns the one transaction each
|
||||
|
||||
Reference in new issue
Block a user