mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 20:12:20 +01:00
## Thinking Path > - Paperclip runs agent work for a company. > - A task drain holds new run starts while maintenance or idle handoff is in progress. > - A queued dispatcher can keep an unreconciled request and a 30-second retry while the drain is active. > - Ending the drain can resume domain work without refreshing that dispatcher's saved deadline. > - This change refreshes the pending queued owner when a drain ends or its expiry is observed. > - Normal admission checks and real retry deadlines still apply. ## Linked Issues or Issue Description Related: #20640. That change refreshes deferred receipt workers. This change refreshes the separate queued-run dispatcher. **What happened?** A queued-work notification received during a drain could leave a 30-second fallback in the dispatcher after the drain ended. The owner stayed unreconciled after useful work had settled. This delayed its next pass and the instance's idle state. **Expected behavior** Refresh an unreconciled queued owner when normal dispatch becomes allowed. Keep other drain holds, admission rules and scheduled retry deadlines. **Steps to reproduce** 1. Let the normal dispatcher complete its first pass. 2. Start an idle task drain and commit a company-scoped queued-work notification. 3. Stop the drain, or observe its expiry, before the saved fallback is due. 4. Check that the scoped queued pass runs before that fallback. The two regression cases fail on the unchanged owner and pass with the fix. **Paperclip version or commit** The main-specific patch is based on `f7b1651799d8c0c660a76266878c420a12f0beca`. The bug was found in assembled sleep acceptance. The affected queued-dispatch, drain and notification modules match main. ## What Changed - Listen for normal drain changes and observed expiry in the queued-run owner. - Wake that owner only when dispatch is allowed and its reconciliation is pending. - Forward the deadline worker's optional stop callback after its stop fence. - Remove both subscriptions when the owner or coordinator stops. - Add release, expiry, remaining-gate, shutdown, retry-deadline and idle controls. ## Verification Local checks used the integrated feature branch that exposed the issue. The main-specific port preserves main's existing `canRun` logic and excludes the private branch's extra cancellation hook. - Both new release and expiry cases failed at the intended scoped-resume assertion before the product change. - Six dispatch cases pass with the normal package import. - Fourteen existing deadline controls and nineteen queue-order controls pass. Their inputs did not change during the test-import correction. - The complete normal Server typecheck and its three affected-file program checks pass. - The first typecheck caught a test import outside the Server root. The import now uses the existing public package wildcard. The corrected six-case suite and normal typecheck pass. - Normal Source SDK input verification passes. - Exact-head CI at `fd623d3ba9345e5ec8f252c55932ff797cd57e8f` completed: 54 passing checks, four expected skips and one neutral result; Snyk passed. Greptile reviewed this exact head at 5/5 with no actionable findings. All review threads were read; none remain open. A full local repository build and suite were not run in this checkout. The existing admission-drain contract in `doc/execution-semantics.md` already requires prompt admission after drain release. This fix restores that contract. No configuration or command documentation changes are needed. ## Risks Drain events can request an earlier pass for a pending owner. The normal permission, reconciliation, coalescing and earliest-time checks remain active. The scheduled retry owner has no new listener. Shutdown must remove both listeners; the coordinator-stop control covers that path. This PR does not claim deployed suspension or complete transport sleep acceptance. ## Model Used OpenAI `gpt-6.1-sol` assisted with implementation and independent review. The Codex managing agent performed technical review and verification. The host does not expose its exact runtime model ID or context-window size. Tools used include source inspection, code edits and local 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 (not required: the existing contract remains accurate) - [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
75 lines
3.2 KiB
TypeScript
75 lines
3.2 KiB
TypeScript
import { randomUUID } from "node:crypto";
|
|
import type { DeadlineReconciliationSnapshot } from "./deadline-reconciliation.js";
|
|
import type { createDeliveryWorkCoordinator } from "./delivery-work-coordinator.js";
|
|
import type { DeliveryQueue } from "./delivery-work-notifications.js";
|
|
|
|
export function registerDeadlineWork(
|
|
coordinator: Pick<ReturnType<typeof createDeliveryWorkCoordinator>, "register">,
|
|
queue: DeliveryQueue,
|
|
task: {
|
|
run: (signal: AbortSignal) => Promise<unknown>;
|
|
next: () => Promise<number | null>;
|
|
canRun: () => boolean;
|
|
retryMs: number;
|
|
onSettled?: (hints?: ReadonlySet<string>) => void;
|
|
onStop?: () => void;
|
|
continuationMs?: number;
|
|
// Optional batching latency for notifications; already-known deadlines still preempt it.
|
|
notificationCoalesceMs?: number;
|
|
|
|
minimumSpacingMs?: number;
|
|
},
|
|
) {
|
|
const ownerRevision = randomUUID();
|
|
let revision = 0, running = false, stopped = false;
|
|
let requested = 1, reconciled = 0;
|
|
let next: number | null = null;
|
|
let earliest = 0;
|
|
let coalesceUntil = 0;
|
|
const worker = coordinator.register(queue, {
|
|
retryMs: task.retryMs,
|
|
pausePassiveMaintenance: true,
|
|
onStop: () => { stopped = true; revision++; task.onStop?.(); },
|
|
onSettled: hints => { revision++; requested++; task.onSettled?.(hints); },
|
|
run: async signal => {
|
|
revision++; running = true;
|
|
try {
|
|
if (!task.canRun()) { requested++; return; }
|
|
if (Date.now() < earliest) { next = earliest; return; }
|
|
if (Date.now() < coalesceUntil && (next === null || next > Date.now())) {
|
|
next = next === null ? coalesceUntil : Math.min(next, coalesceUntil);
|
|
return;
|
|
}
|
|
const generation = ++requested;
|
|
const startedAt = Date.now();
|
|
earliest = startedAt + Math.max(task.retryMs, task.minimumSpacingMs ?? 0);
|
|
await task.run(signal);
|
|
if (signal.aborted || !task.canRun()) { next = null; return; }
|
|
const deadline = await task.next();
|
|
|
|
if (!task.canRun()) { next = null; return; }
|
|
earliest = deadline === null || deadline > Date.now()
|
|
? (task.minimumSpacingMs ? Date.now() + task.minimumSpacingMs : 0)
|
|
: startedAt + Math.max(task.continuationMs ?? task.retryMs, task.minimumSpacingMs ?? 0);
|
|
next = deadline === null ? null : Math.max(earliest, deadline);
|
|
coalesceUntil = Date.now() + (task.notificationCoalesceMs ?? 0);
|
|
reconciled = generation;
|
|
} finally { running = false; revision++; }
|
|
},
|
|
// A settled producer must release its admission hold during drain. Keep
|
|
// the unreconciled generation and an in-memory resume wake, without asking
|
|
// the domain to probe its database while dispatch is closed.
|
|
hasPending: async () => task.canRun() && requested !== reconciled,
|
|
nextRunAt: () => !task.canRun() && requested !== reconciled
|
|
? Date.now() + task.retryMs
|
|
: next,
|
|
});
|
|
return { ...worker,
|
|
reconciliationSnapshot: (): DeadlineReconciliationSnapshot => ({
|
|
revision: `${ownerRevision}:${revision}`,
|
|
reconciled: !stopped && !running && requested === reconciled,
|
|
}),
|
|
wake: () => { revision++; requested++; worker.wake(); },
|
|
};
|
|
}
|