mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 02:20:38 +09:00
Guard cheap recovery model usage (#6371)
## Thinking Path > - Paperclip is the control plane that coordinates AI-agent work through issues, heartbeats, comments, approvals, and auditable recovery paths. > - The affected subsystem is heartbeat/recovery orchestration, especially the optional cheap model profile used for operational recovery overhead. > - Cheap recovery should repair status and liveness, but it must not become the worker lane that writes deliverables, continues source work, or propagates cheap execution hints into downstream retries. > - The gap was that cheap-profile hints could follow recovery wake contexts and assignment overrides farther than intended, making real work eligible to run on the cheap model. > - This pull request separates status-only cheap recovery from normal source-work continuations, adds route guards for deliverable mutations during cheap status-only runs, and documents the invariant. > - The benefit is safer retry/recovery behavior: cheap runs can clean up control-plane state, while any remaining source work resumes through a normal/original model path. ## What Changed - Added recovery model-profile work classes so status-only recovery carries explicit guard context and normal-model continuations scrub cheap hints. - Updated heartbeat, productivity review, liveness continuation, and recovery service wakeups to request cheap only for bounded status-only recovery work. - Blocked cheap status-only recovery runs from writing issue documents, plans, attachments, work products, or assigning downstream work back to `modelProfile: "cheap"`. - Added/updated server tests for cheap profile propagation, artifact/document guards, route authorization, retry scheduling, and successful-run handoff behavior. - Documented the recovery model-profile lane in `doc/SPEC-implementation.md` and `doc/execution-semantics.md`. - After rebasing onto current `public-gh/master`, stabilized the new `InstanceSidebar` plugin-filter tests so the PR check lane stays green. ## Verification - Local: `pnpm exec vitest run --config vitest.config.ts src/services/recovery/model-profile-hint.test.ts src/__tests__/issue-agent-mutation-ownership-routes.test.ts src/__tests__/issue-document-restore-routes.test.ts` from `server/` - 3 files, 37 tests passed after final edits. - Local: `pnpm exec vitest run --config vitest.config.ts src/__tests__/heartbeat-process-recovery.test.ts` from `server/` - 44 tests passed after rerunning the cleanup-sensitive file alone. - Local: `pnpm --filter @paperclipai/ui exec vitest run src/components/InstanceSidebar.test.tsx` - 4 tests passed. - Local: `pnpm --filter @paperclipai/server typecheck` - passed. - Local: `pnpm --filter @paperclipai/ui typecheck` - passed. - PR checks on latest head `6f8c3b1380f5bd872c6f49f6f7188ecf3bb6d263` - all green, including `verify`, build, typecheck, server/general/serialized tests, e2e, Snyk, and policy. - Greptile: pass 3 returned Confidence Score 5/5 with zero unresolved Greptile review threads. ## Risks - Medium risk: recovery behavior is intentionally stricter, so any path that incorrectly relies on cheap recovery to keep doing source work will now need to hand back to a normal-model run. - Low migration risk: no schema changes. - No product UI changes; the UI file touched is a test-only stabilization after rebasing onto current `master`. > 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 - OpenAI Codex coding agent, GPT-5 model family (`gpt-5`), tool use and local code execution enabled; context window not exposed in this environment. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (N/A: no product UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
This commit is contained in:
Dotta
GitHub
parent
24748de421
commit
bfe6369ef5
17 changed files with 529 additions and 78 deletions
|
|
@ -7,6 +7,7 @@ import type { Db } from "@paperclipai/db";
|
|||
import {
|
||||
activityLog,
|
||||
executionWorkspaces,
|
||||
heartbeatRuns,
|
||||
issueExecutionDecisions,
|
||||
issueRelations,
|
||||
issues as issueRows,
|
||||
|
|
@ -1331,6 +1332,87 @@ export function issueRoutes(
|
|||
return true;
|
||||
}
|
||||
|
||||
function isStatusOnlyCheapRecoveryContext(contextSnapshot: unknown) {
|
||||
if (!contextSnapshot || typeof contextSnapshot !== "object" || Array.isArray(contextSnapshot)) return false;
|
||||
const context = contextSnapshot as Record<string, unknown>;
|
||||
return context.modelProfile === "cheap" &&
|
||||
context.recoveryIntent === "status_only" &&
|
||||
context.allowDeliverableWork === false &&
|
||||
context.allowDocumentUpdates === false &&
|
||||
context.resumeRequiresNormalModel === true;
|
||||
}
|
||||
|
||||
function requestsCheapIssueAssigneeModelProfile(input: { assigneeAdapterOverrides?: unknown }) {
|
||||
const overrides = input.assigneeAdapterOverrides;
|
||||
return !!overrides &&
|
||||
typeof overrides === "object" &&
|
||||
!Array.isArray(overrides) &&
|
||||
(overrides as Record<string, unknown>).modelProfile === "cheap";
|
||||
}
|
||||
|
||||
async function loadActorRunContext(req: Request, companyId: string) {
|
||||
if (req.actor.type !== "agent") return null;
|
||||
const runId = req.actor.runId?.trim();
|
||||
if (!runId) return null;
|
||||
const run = await db
|
||||
.select({
|
||||
id: heartbeatRuns.id,
|
||||
companyId: heartbeatRuns.companyId,
|
||||
agentId: heartbeatRuns.agentId,
|
||||
contextSnapshot: heartbeatRuns.contextSnapshot,
|
||||
})
|
||||
.from(heartbeatRuns)
|
||||
.where(eq(heartbeatRuns.id, runId))
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (!run || run.companyId !== companyId || run.agentId !== req.actor.agentId) return null;
|
||||
return run;
|
||||
}
|
||||
|
||||
async function assertCheapRecoveryIssueAssigneeProfileAllowed(
|
||||
req: Request,
|
||||
res: Response,
|
||||
issue: { id?: string; companyId: string },
|
||||
input: { assigneeAdapterOverrides?: unknown },
|
||||
) {
|
||||
if (!requestsCheapIssueAssigneeModelProfile(input)) return true;
|
||||
const run = await loadActorRunContext(req, issue.companyId);
|
||||
if (!run || !isStatusOnlyCheapRecoveryContext(run.contextSnapshot)) return true;
|
||||
|
||||
res.status(403).json({
|
||||
error: "Cheap status-only recovery runs cannot assign downstream issue work to the cheap model profile",
|
||||
details: {
|
||||
issueId: issue.id ?? null,
|
||||
runId: run.id,
|
||||
modelProfile: "cheap",
|
||||
recoveryIntent: "status_only",
|
||||
resumeRequiresNormalModel: true,
|
||||
},
|
||||
});
|
||||
return false;
|
||||
}
|
||||
|
||||
async function assertDeliverableMutationAllowedByRunContext(
|
||||
req: Request,
|
||||
res: Response,
|
||||
issue: { id: string; companyId: string },
|
||||
) {
|
||||
const run = await loadActorRunContext(req, issue.companyId);
|
||||
if (!run) return true;
|
||||
if (!isStatusOnlyCheapRecoveryContext(run.contextSnapshot)) return true;
|
||||
|
||||
res.status(403).json({
|
||||
error: "Cheap status-only recovery runs cannot update issue documents, plans, or deliverable artifacts",
|
||||
details: {
|
||||
issueId: issue.id,
|
||||
runId: run.id,
|
||||
modelProfile: "cheap",
|
||||
recoveryIntent: "status_only",
|
||||
resumeRequiresNormalModel: true,
|
||||
},
|
||||
});
|
||||
return false;
|
||||
}
|
||||
|
||||
function assertStructuredCommentFieldsAllowed(
|
||||
req: Request,
|
||||
res: Response,
|
||||
|
|
@ -2319,6 +2401,7 @@ export function issueRoutes(
|
|||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
|
|
@ -2523,6 +2606,7 @@ export function issueRoutes(
|
|||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
|
|
@ -2682,6 +2766,7 @@ export function issueRoutes(
|
|||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
const product = await workProductsSvc.createForIssue(issue.id, issue.companyId, {
|
||||
...req.body,
|
||||
projectId: req.body.projectId ?? issue.projectId ?? null,
|
||||
|
|
@ -2725,6 +2810,7 @@ export function issueRoutes(
|
|||
return;
|
||||
}
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
const product = await workProductsSvc.update(id, req.body);
|
||||
if (!product) {
|
||||
res.status(404).json({ error: "Work product not found" });
|
||||
|
|
@ -2765,6 +2851,7 @@ export function issueRoutes(
|
|||
return;
|
||||
}
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
const removed = await workProductsSvc.remove(id);
|
||||
if (!removed) {
|
||||
res.status(404).json({ error: "Work product not found" });
|
||||
|
|
@ -2998,6 +3085,7 @@ export function issueRoutes(
|
|||
const companyId = req.params.companyId as string;
|
||||
assertCompanyAccess(req, companyId);
|
||||
assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
|
||||
if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, { companyId }, req.body))) return;
|
||||
if (req.body.assigneeAgentId || req.body.assigneeUserId) {
|
||||
await assertCanAssignTasks(req, companyId);
|
||||
}
|
||||
|
|
@ -3093,6 +3181,7 @@ export function issueRoutes(
|
|||
}
|
||||
assertCompanyAccess(req, parent.companyId);
|
||||
assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
|
||||
if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, parent, req.body))) return;
|
||||
if (req.body.assigneeAgentId || req.body.assigneeUserId) {
|
||||
await assertCanAssignTasks(req, parent.companyId);
|
||||
}
|
||||
|
|
@ -3239,6 +3328,7 @@ export function issueRoutes(
|
|||
assertCompanyAccess(req, existing.companyId);
|
||||
assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, existing))) return;
|
||||
if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, existing, req.body))) return;
|
||||
|
||||
const actor = getActorInfo(req);
|
||||
const isClosed = isClosedIssueStatus(existing.status);
|
||||
|
|
@ -5261,6 +5351,7 @@ export function issueRoutes(
|
|||
return;
|
||||
}
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
|
||||
const company = await companiesSvc.getById(companyId);
|
||||
const attachmentMaxBytes = normalizeIssueAttachmentMaxBytes(company?.attachmentMaxBytes);
|
||||
|
|
@ -5380,6 +5471,7 @@ export function issueRoutes(
|
|||
return;
|
||||
}
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue))) return;
|
||||
|
||||
try {
|
||||
await storage.deleteObject(attachment.companyId, attachment.objectKey);
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue