mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Native agent runs call Paperclip tools through the runner's provider tool bridge > - The bridge reserves 768 KiB for each pending call against an 8 MiB budget per turn > - When an agent sends many tool calls in parallel, the reserve for the pending calls can go over the budget, although the bytes the turn really holds are small > - The bridge then reports the durable receipt limit, and the backend stops the whole turn. The run ends as cancelled with `needs_review`, and the task stays blocked with a Retry button > - This pull request rejects only the overflow call as retryable, and keeps the turn stop for real held bytes. It also adds a server backstop: a turn stopped at the receipt limit continues by itself in a fresh session > - The benefit is that a parallel burst of tool calls no longer leaves a task waiting for a person ## Linked Issues or Issue Description **What happened?** In a restart-chaos wave, an opencode agent sent 10 parallel `get_task` calls. The turn already held about 0.7 MB of results. 10 × 768 KiB plus 0.7 MB is more than 8 MiB, so `begin_call` returned `active_turn_receipt_limit()` for the 10th call. This branch does not set `durable_run_receipt_limit_reached`, so it is a temporary reserve overflow. `handle_tool_call` sends every receipt-limit error to `stop_turn_at_tool_receipt_limit`, which interrupts the turn. The run ended as cancelled with `needs_review` and a human review request. The release then blocked the task (`native_continuation_requires_reconciliation`) and showed Retry. No continuation was scheduled. The task moved again only because a person posted a comment ten minutes later. **Expected behavior** The overflow call gets a normal, retryable rejection, and the turn continues. The agent can send the call again after a pending result arrives. If a turn does stop at the receipt limit, Paperclip continues the task in a fresh session, as it does for `agent_tool_call_loop` (#21734). The task does not show Retry. **Steps to reproduce** 1. Start a native turn that holds about 600 KiB of settled tool results. 2. Send 10 tool calls in parallel. 3. On master, the 10th call stops the turn, and the task becomes blocked with Retry. **Paperclip version or commit** `master` atc5218f5ec4(wave), rebased on991f773d7f. ## What Changed - `provider_bridge.rs`: the two `begin_call` branches that fail only because of the per-call result reserve now return a new retryable error (`tool_calls_in_flight`). The provider sees "Too many tool calls are in flight. This call was not executed. Wait for the pending tool results, then retry it." The branches that set `durable_run_receipt_limit_reached` (real held bytes, exact identity capacity, saturated replay history) still stop the turn. - `provider_backend.rs`: the invalid tool call result sets `retryable` from the error, so this rejection is `retryable: true`. Other rejections stay `false`. - `native-tool-receipt-limit.ts` (new): reads the persisted, source-bound `harness.diagnostic` event with code `semantic_tool_turn_receipt_limit` for the run, and holds the lane constants and the hint for the next session. - `status-arbiter.ts`: a run that did not succeed and whose runner stopped it at the receipt limit preserves the task status and schedules a retry with cause `semantic_tool_turn_receipt_limit` (and releases run resources when it was cancelled). This applies only when the task owner holds the decision, with no review, governance gate, open blocker, pause hold or prior `blocked` status, and at most 2 times per chain. Other cases keep their current path. - `native-provider-capacity-retry.ts`: the capacity retry is now one lane of a shared fresh-session retry helper. The new receipt-limit lane creates a `scheduled_retry` run due in 5 seconds with `forceFreshSession` and a liveness instruction that tells the agent to make fewer parallel calls. - `status-decision-committer.ts` and `native-run-finalizer.ts`: wire the new lane, and require the task owner under the issue lock, as for the capacity retry. - `acpx_provider_session.rs` (Claude, Cursor and other ACPX agents) handles the same retryable error per call: it drops the pending sidecar call and resolves only that call with the retryable error. Other `begin_call` errors still fail closed. - The external provider path (Dot/Muse) is out of scope and unchanged: it still fails closed on this overflow, as on master. Making a same-requestId retry safe there needs retry generations across the executor, the driver command ids and the broker receipts. That is a follow-up. - The receipt-limit backstop reads only the diagnostic of the final turn in the run's session. - A person's Stop always wins: the finalizer re-reads the saved Stop on each arbitration attempt, the retry helper refuses under the run lock, and the #21734 tool-call loop continuation is not queued, or is cancelled, for a stopped run. The runner change is runner-image content. The Daytona runner image must be rebuilt before sandboxes get the runner fix. The server backstop works with older images. ## Verification - Red then green, `provider_bridge.rs` unit test `parallel_calls_over_the_result_reserve_reject_only_the_overflow_call`: with about 600 KiB settled, 9 calls are admitted. On master the 10th returns `is_active_turn_receipt_limit()`. Now it is a retryable rejection, the durable flag stays false, and the same call is admitted after one pending result settles. - Negative, `held_result_bytes_over_the_limit_still_stop_the_turn`: real held bytes over the limit still return the receipt limit with the durable flag set. - `cargo test -p paperclip-runner-core -- --skip task_memory::`: all pass (640 lib tests plus the integration suites). The `task_memory` monitor tests are timing-based kernel OOM monitor tests that do not run correctly on macOS (one hangs); this change does not touch them, and CI runs them on Linux. - Red then green, `native-tool-receipt-limit.integration.test.ts` (real Postgres): a run stopped at the receipt limit gets one `scheduled_retry` successor with `forceFreshSession` and the hint. The release does not block the task and creates no recovery action. The task stays `in_progress`. The presentation shows `retry_scheduled` with no Retry, then `working` after promotion. With the master arbiter, no successor is created. A negative case (another diagnostic code) keeps `cancellation_run_only`. - Red then green: ACPX `receiver_rejects_only_the_tool_call_that_overflows_the_result_reserve` (11-call burst through the fake sidecar). - Red then green, server: an earlier turn's diagnostic gives no continuation; a Stop saved before or right after the finalizer's first read gives no continuation and settles the cancellation with no recovery action; the retry helper throws `NativeStatusRaceError` for a stopped run; the loop continuation is not queued, and a queued one is cancelled, for a stopped run. - `status-arbiter.test.ts`: the new branch, the 2-continuation bound, and the `blocked` exclusion. - Focused server tests pass: the new test, `native-provider-overload.integration.test.ts`, `status-arbiter.test.ts`, `native-status-arbiter-corpus.test.ts`, `heartbeat-run-dispatch-work.test.ts`, `native-run-finalizer-telemetry.test.ts`, `native-workspace-finalizer.test.ts` (306 tests). `tsc --noEmit` passes for `server`. - `pnpm verify` exits 2 (a runner-core change needs broad coverage), so required CI supplies it. ## Risks - Dot/Muse agents still lose the turn on this overflow until the follow-up lands (no change from master). - An agent that keeps more than about ten large calls in flight now gets rejections for the extra calls instead of a stopped turn. It can send them again after results arrive. Real held bytes still stop the turn. - The receipt-limit continuation starts a fresh session. The in-turn conversation is lost; the task, comments, documents and saved workspace stay. It runs at most 2 times per chain, then the current path applies. - The retry lane shares the failure-retry count with the capacity lane. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude Code with tool use and code 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 Refs #21734 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
761 lines
29 KiB
TypeScript
761 lines
29 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import type { NativeEvidenceAssessment } from "./evidence-classifier.js";
|
|
import { arbitrateNativeStatus } from "./status-arbiter.js";
|
|
|
|
function assessment(
|
|
overrides: Partial<NativeEvidenceAssessment> = {},
|
|
): NativeEvidenceAssessment {
|
|
return {
|
|
objectiveClaimSatisfied: true,
|
|
objectiveSatisfied: true,
|
|
allCriteriaSatisfied: true,
|
|
verificationPassed: true,
|
|
hasFailedVerification: false,
|
|
hasBlockingRemainingWork: false,
|
|
reportedDisposition: "done",
|
|
summary: "Complete",
|
|
contractRevisionMatches: true,
|
|
criterionAssessments: [],
|
|
verificationAssessments: [],
|
|
verificationCaveats: [],
|
|
acceptedEvidenceRefs: ["event:2"],
|
|
missingRequirements: [],
|
|
rejectedEvidence: [],
|
|
unverifiableEvidence: [],
|
|
blocker: null,
|
|
continuation: null,
|
|
attentionRequests: [],
|
|
ignoredAttentionRequests: [],
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
function arbitrate(
|
|
overrides: Partial<Parameters<typeof arbitrateNativeStatus>[0]> = {},
|
|
) {
|
|
return arbitrateNativeStatus({
|
|
assessment: assessment(),
|
|
terminalState: "succeeded",
|
|
workspaceFinalizeStatus: "succeeded",
|
|
agentId: "agent",
|
|
priorIssueStatus: "in_progress",
|
|
...overrides,
|
|
});
|
|
}
|
|
|
|
describe("native status authority", () => {
|
|
it("completes a reviewer's done report from its own recorded final-stage approval", () => {
|
|
// Retained live failure: the reviewer approved its stage, then cited free-text
|
|
// evidence; the report was graded as incomplete and the task reopened.
|
|
const freeText = assessment({ objectiveSatisfied: false, allCriteriaSatisfied: false, verificationPassed: false });
|
|
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review" }))
|
|
.toMatchObject({ toStatus: "in_progress", reasonCode: "completion_evidence_incomplete" });
|
|
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
|
|
.toMatchObject({ toStatus: "done", reasonCode: "execution_stage_approved" });
|
|
// The decision authorizes completion only for a clean done report.
|
|
expect(arbitrate({ assessment: { ...freeText, hasBlockingRemainingWork: true }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
|
|
.not.toMatchObject({ toStatus: "done" });
|
|
expect(arbitrate({ assessment: { ...freeText, hasFailedVerification: true }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
|
|
.not.toMatchObject({ toStatus: "done" });
|
|
expect(arbitrate({ assessment: { ...freeText, reportedDisposition: "needs_review" }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
|
|
.not.toMatchObject({ toStatus: "done" });
|
|
// A still-pending stage keeps governing the task.
|
|
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review", executionStageApprovedByRun: true, governanceGate: { kind: "execution_stage", id: "run" } }))
|
|
.toMatchObject({ toStatus: "in_review", reasonCode: "governed_gate_pending" });
|
|
});
|
|
it("cannot complete an explicitly required quality review from claims or file evidence", () => {
|
|
expect(arbitrate({ completionClaimPolicyAccepted: true, requiredQualityReviewSatisfied: false }))
|
|
.toMatchObject({ toStatus: "in_progress", reasonCode: "required_quality_review_incomplete" });
|
|
expect(arbitrate({ completionClaimPolicyAccepted: false, requiredQualityReviewSatisfied: false }))
|
|
.toMatchObject({ toStatus: "in_progress", reasonCode: "required_quality_review_incomplete" });
|
|
expect(arbitrate({ requiredQualityReviewSatisfied: true })).toMatchObject({ toStatus: "done" });
|
|
expect(arbitrate()).toMatchObject({ toStatus: "done" });
|
|
expect(arbitrate({ requiredQualityReviewSatisfied: false, governanceGate: { kind: "interaction", id: "quality" } }))
|
|
.toMatchObject({ toStatus: "in_review", reasonCode: "governed_gate_pending" });
|
|
});
|
|
it("waits on a published external review without creating human attention", () => {
|
|
const wait = assessment({ reportedDisposition: "yielded",
|
|
continuation: { kind: "response_wake", summary: "Wait for the PR update", idempotencyKey: "pr-wait" } });
|
|
expect(arbitrate({ assessment: wait, publishedExternalReview: true, externalChatResponseWaitAuthorization: "authorized" }))
|
|
.toMatchObject({ toStatus: "in_review", reasonCode: "external_chat_response_waiting", effects: [] });
|
|
expect(arbitrate({ assessment: wait, publishedExternalReview: true, externalChatResponseWaitAuthorization: "revoked" }))
|
|
.toMatchObject({ statusAction: "preserve", effects: [] });
|
|
expect(arbitrate({ assessment: wait, publishedExternalReview: true,
|
|
externalChatResponseWaitAuthorization: "authorized", governanceGate: { kind: "approval", id: "access" } }))
|
|
.toMatchObject({ reasonCode: "governed_response_waiting", effects: [{ kind: "create_interaction" }] });
|
|
const monitor = { ...wait, continuation: { ...wait.continuation!, kind: "monitor" as const } };
|
|
expect(arbitrate({ assessment: monitor, publishedExternalReview: true, monitorWaitAuthorized: true }))
|
|
.toMatchObject({ toStatus: "in_review", reasonCode: "scheduled_monitor_waiting", effects: [{ kind: "release_checkout" }] });
|
|
expect(arbitrate({ assessment: monitor, publishedExternalReview: true }))
|
|
.toMatchObject({ statusAction: "preserve", reasonCode: "monitor_wait_authority_lost" });
|
|
});
|
|
it("preserves an open task after an accepted case handoff even if the departing model claims done", () => {
|
|
expect(arbitrate({ caseHandoffAuthorized: true })).toMatchObject({
|
|
statusAction: "preserve", toStatus: "in_progress", reasonCode: "case_handoff_waiting_for_release",
|
|
effects: [{ kind: "release_checkout" }],
|
|
});
|
|
});
|
|
|
|
it("preserves the task status after a context compaction run", () => {
|
|
for (const priorIssueStatus of ["in_progress", "in_review", "blocked", "todo"] as const) {
|
|
expect(arbitrate({
|
|
contextCompactionRun: true,
|
|
priorIssueStatus,
|
|
assessment: assessment({ reportedDisposition: "yielded", objectiveSatisfied: false, allCriteriaSatisfied: false }),
|
|
})).toMatchObject({
|
|
statusAction: "preserve", toStatus: priorIssueStatus, reasonCode: "context_compaction_status_preserved", effects: [],
|
|
});
|
|
}
|
|
});
|
|
|
|
it("keeps workspace repair ahead of an accepted case handoff", () => {
|
|
expect(arbitrate({ caseHandoffAuthorized: true, workspaceFinalizeStatus: "failed" })).toMatchObject({
|
|
statusAction: "preserve", reasonCode: "finalization_failed_claim_preserved",
|
|
});
|
|
});
|
|
it("keeps a verified accepted Cursor plan passive without completing or replaying work", () => {
|
|
const passive = assessment({ reportedDisposition: "yielded", objectiveSatisfied: false,
|
|
allCriteriaSatisfied: false, hasBlockingRemainingWork: true,
|
|
continuation: { kind: "response_wake", summary: "Explicit continuation needed", idempotencyKey: "cursor-plan-wait:event" } });
|
|
expect(arbitrate({ assessment: passive, planWaitAuthorized: true })).toMatchObject({
|
|
toStatus: "in_progress", reasonCode: "native_plan_accepted_waiting_for_continuation", effects: [],
|
|
});
|
|
expect(arbitrate({ assessment: passive })).toMatchObject({
|
|
toStatus: "in_progress",
|
|
reasonCode: "completion_evidence_incomplete",
|
|
effects: [expect.objectContaining({
|
|
kind: "enqueue_continuation",
|
|
continuationKind: "same_agent",
|
|
idempotencyKey: "native-completion-incomplete",
|
|
})],
|
|
});
|
|
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, terminalState: "failed" }).reasonCode).not.toBe("native_plan_accepted_waiting_for_continuation");
|
|
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, priorIssueStatus: "cancelled" }).toStatus).toBe("cancelled");
|
|
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, governanceGate: { kind: "interaction", id: "pending" } }).toStatus).toBe("in_review");
|
|
});
|
|
|
|
it("a reviewer finishes its decision without completing rejected or still-reviewed work", () => {
|
|
for (const priorIssueStatus of ["in_progress", "in_review"] as const) {
|
|
const decision = arbitrate({ priorIssueStatus, nativeReviewOutcome: "resolved" });
|
|
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: priorIssueStatus });
|
|
expect(decision.effects).not.toContainEqual(expect.objectContaining({ kind: "enqueue_continuation" }));
|
|
}
|
|
});
|
|
|
|
it("routes an unfinished reviewer action to bounded recovery instead of retrying the worker task", () => {
|
|
const decision = arbitrate({ priorIssueStatus: "in_review", nativeReviewOutcome: "pending" });
|
|
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: "in_review" });
|
|
expect(decision.effects).toContainEqual(expect.objectContaining({
|
|
kind: "record_recovery", cause: "native_review_unresolved", agentId: "agent",
|
|
}));
|
|
expect(decision.effects.some((effect) => ["enqueue_continuation", "schedule_retry"].includes(effect.kind))).toBe(false);
|
|
});
|
|
|
|
it("lets a reviewer stopped by a tool-call loop continue through its queued review wake instead of a resume recovery", () => {
|
|
const decision = arbitrate({ priorIssueStatus: "in_review", nativeReviewOutcome: "pending", toolCallLoopContinuation: true });
|
|
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: "in_review", reasonCode: "native_review_unresolved" });
|
|
expect(decision.effects).toEqual([{ kind: "release_checkout" }]);
|
|
});
|
|
|
|
it("continues a turn stopped at its tool receipt limit in a fresh session, within its bound", () => {
|
|
const stopped = arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true });
|
|
expect(stopped).toMatchObject({ statusAction: "preserve", toStatus: "in_progress", reasonCode: "semantic_tool_turn_receipt_limit" });
|
|
expect(stopped.effects).toEqual([
|
|
{ kind: "schedule_retry", cause: "semantic_tool_turn_receipt_limit", summary: "Continue the task in a fresh session.", agentId: expect.any(String) },
|
|
{ kind: "release_run_resources" },
|
|
]);
|
|
expect(arbitrate({ terminalState: "failed", toolReceiptLimitStopped: true }).effects)
|
|
.toEqual([expect.objectContaining({ kind: "schedule_retry", cause: "semantic_tool_turn_receipt_limit" })]);
|
|
expect(arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true, failureRetryCount: 2 }).reasonCode).toBe("cancellation_run_only");
|
|
expect(arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true, priorIssueStatus: "blocked" }).reasonCode).toBe("cancellation_run_only");
|
|
expect(arbitrate({ terminalState: "cancelled" }).reasonCode).toBe("cancellation_run_only");
|
|
});
|
|
|
|
it("treats only the authorized Board response_wake as passive and preserves governance", () => {
|
|
const passive = assessment({
|
|
reportedDisposition: "yielded",
|
|
continuation: {
|
|
kind: "response_wake",
|
|
summary: "Wait for the next request",
|
|
idempotencyKey: "board-wait",
|
|
},
|
|
});
|
|
expect(
|
|
arbitrate({ assessment: passive, boardResponseWaitAuthorized: true }),
|
|
).toMatchObject({
|
|
reasonCode: "board_response_waiting",
|
|
toStatus: "in_progress",
|
|
effects: [],
|
|
});
|
|
expect(arbitrate({ assessment: passive })).toMatchObject({
|
|
reasonCode: "response_wake_waiting_for_input",
|
|
toStatus: "in_progress",
|
|
effects: [],
|
|
});
|
|
expect(
|
|
arbitrate({ assessment: passive, boardResponseWaitOrigin: true }),
|
|
).toMatchObject({
|
|
reasonCode: "board_response_wait_superseded",
|
|
statusAction: "preserve",
|
|
effects: [],
|
|
});
|
|
expect(
|
|
arbitrate({
|
|
assessment: passive,
|
|
boardResponseWaitAuthorized: true,
|
|
governanceGate: { kind: "approval", id: "approval" },
|
|
}),
|
|
).toMatchObject({
|
|
reasonCode: "governed_response_waiting",
|
|
toStatus: "in_review",
|
|
effects: [expect.objectContaining({ kind: "create_interaction" })],
|
|
});
|
|
for (const kind of ["same_agent", "retry"] as const) {
|
|
expect(
|
|
arbitrate({
|
|
assessment: {
|
|
...passive,
|
|
continuation: { ...passive.continuation!, kind },
|
|
},
|
|
boardResponseWaitAuthorized: true,
|
|
}),
|
|
).toMatchObject({
|
|
reasonCode: "live_continuation_registered",
|
|
effects: [expect.objectContaining({ continuationKind: kind })],
|
|
});
|
|
}
|
|
});
|
|
it("repairs unfinished response waits once using the server continuation budget", () => {
|
|
const unfinished = assessment({
|
|
reportedDisposition: "yielded", hasBlockingRemainingWork: true,
|
|
continuation: { kind: "response_wake", summary: "Answered status; await next message", idempotencyKey: "model-key" },
|
|
});
|
|
for (const boardResponseWaitAuthorized of [true, false]) {
|
|
expect(arbitrate({ assessment: unfinished, boardResponseWaitAuthorized })).toMatchObject({
|
|
reasonCode: "completion_evidence_incomplete",
|
|
toStatus: "in_progress",
|
|
effects: [{ kind: "enqueue_continuation", continuationKind: "same_agent", idempotencyKey: "native-completion-incomplete" }],
|
|
});
|
|
expect(arbitrate({ assessment: unfinished, boardResponseWaitAuthorized, allowIncompleteContinuation: false })).toMatchObject({
|
|
reasonCode: "prior_status_preserved_no_live_path",
|
|
effects: [{ kind: "record_finalization_error", cause: "completion_evidence_incomplete" }],
|
|
});
|
|
}
|
|
expect(arbitrate({ assessment: unfinished, boardResponseWaitOrigin: true, boardResponseWaitAuthorized: true }))
|
|
.toMatchObject({ reasonCode: "completion_evidence_incomplete" });
|
|
expect(arbitrate({ assessment: unfinished, boardResponseWaitOrigin: true, boardResponseWaitAuthorized: false }))
|
|
.toMatchObject({ reasonCode: "board_response_wait_superseded", effects: [] });
|
|
expect(arbitrate({ assessment: unfinished, hasActivePauseHold: true }))
|
|
.toMatchObject({ reasonCode: "response_wait_pause_preserved", effects: [] });
|
|
expect(arbitrate({ assessment: unfinished, hasUnresolvedIssueBlockers: true }))
|
|
.toMatchObject({ toStatus: "blocked", reasonCode: "durable_dependency_blocker_bound", effects: [] });
|
|
expect(arbitrate({ assessment: unfinished, governanceGate: { kind: "interaction", id: "question" } }))
|
|
.toMatchObject({ reasonCode: "governed_response_waiting", effects: [{ kind: "create_interaction" }] });
|
|
expect(arbitrate({ assessment: unfinished, externalChatResponseWaitAuthorization: "authorized" }))
|
|
.toMatchObject({ reasonCode: "external_chat_response_waiting", effects: [] });
|
|
expect(arbitrate({ assessment: unfinished, externalChatResponseWaitAuthorization: "revoked" }))
|
|
.toMatchObject({ reasonCode: "external_chat_response_wait_authorization_lost", effects: [] });
|
|
expect(arbitrate({ assessment: unfinished, isConversation: true, boardResponseWaitAuthorized: true }))
|
|
.toMatchObject({ reasonCode: "board_response_waiting", effects: [] });
|
|
});
|
|
|
|
it("marks done only from successful finalization and complete durable evidence", () => {
|
|
expect(arbitrate()).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "done",
|
|
toStatus: "done",
|
|
reasonCode: "completion_contract_satisfied",
|
|
effects: [{ kind: "release_checkout" }],
|
|
}),
|
|
);
|
|
expect(arbitrate({ completionClaimPolicyAccepted: true })).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "done",
|
|
reasonCode: "completion_claim_policy_accepted",
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
verificationPassed: false,
|
|
missingRequirements: ["test"],
|
|
}),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "in_progress",
|
|
toStatus: "in_progress",
|
|
reasonCode: "completion_evidence_incomplete",
|
|
effects: [expect.objectContaining({ kind: "enqueue_continuation" })],
|
|
}),
|
|
);
|
|
const claimOnly = assessment({
|
|
objectiveSatisfied: false,
|
|
allCriteriaSatisfied: false,
|
|
verificationPassed: false,
|
|
criterionAssessments: [
|
|
{
|
|
criterionId: "objective",
|
|
claimStatus: "satisfied",
|
|
outcome: "missing",
|
|
evidenceRefs: [],
|
|
reasonCode: "criterion_evidence_missing",
|
|
},
|
|
],
|
|
verificationAssessments: [
|
|
{
|
|
commandOrCheck: "Answered the question",
|
|
claimStatus: "passed",
|
|
outcome: "unverifiable",
|
|
evidenceRef: null,
|
|
reasonCode: "verification_has_no_durable_reference",
|
|
reportedReasonCode: null,
|
|
detail: null,
|
|
},
|
|
],
|
|
acceptedEvidenceRefs: [],
|
|
missingRequirements: ["objective"],
|
|
});
|
|
expect(arbitrate({ assessment: claimOnly })).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_progress",
|
|
reasonCode: "completion_evidence_incomplete",
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({ assessment: claimOnly, completionClaimPolicyAccepted: true }),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "done",
|
|
reasonCode: "completion_claim_policy_accepted",
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("creates explicit liveness paths for review, continuation, cancellation, and governance", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({ reportedDisposition: "needs_review" }),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_progress",
|
|
effects: [expect.objectContaining({ kind: "enqueue_continuation" })],
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "yielded",
|
|
continuation: {
|
|
kind: "retry",
|
|
summary: "Retry the task",
|
|
idempotencyKey: "retry-task",
|
|
},
|
|
}),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_progress",
|
|
effects: [
|
|
expect.objectContaining({
|
|
kind: "enqueue_continuation",
|
|
continuationKind: "retry",
|
|
}),
|
|
],
|
|
}),
|
|
);
|
|
const externalChatWait = assessment({
|
|
reportedDisposition: "yielded",
|
|
continuation: {
|
|
kind: "response_wake",
|
|
summary: "Wait for the next authorized provider message",
|
|
idempotencyKey: "external-chat-wait",
|
|
},
|
|
});
|
|
expect(
|
|
arbitrate({
|
|
assessment: externalChatWait,
|
|
externalChatResponseWaitAuthorization: "authorized",
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "in_progress",
|
|
toStatus: "in_progress",
|
|
reasonCode: "external_chat_response_waiting",
|
|
effects: [],
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({
|
|
assessment: externalChatWait,
|
|
externalChatResponseWaitAuthorization: "revoked",
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "preserve",
|
|
toStatus: "in_progress",
|
|
reasonCode: "external_chat_response_wait_authorization_lost",
|
|
effects: [],
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({
|
|
assessment: externalChatWait,
|
|
externalChatResponseWaitAuthorization: "not_applicable",
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "in_progress",
|
|
reasonCode: "response_wake_waiting_for_input",
|
|
effects: [],
|
|
}),
|
|
);
|
|
expect(arbitrate({ terminalState: "cancelled" })).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_progress",
|
|
effects: [expect.objectContaining({ kind: "release_run_resources" })],
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({ governanceGate: { kind: "interaction", id: "interaction" } }),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_review",
|
|
reasonCode: "governed_gate_pending",
|
|
effects: [
|
|
{
|
|
kind: "create_interaction",
|
|
gate: { kind: "interaction", id: "interaction" },
|
|
},
|
|
{
|
|
kind: "notify_owner",
|
|
agentId: "agent",
|
|
reason: "governed_gate_pending",
|
|
},
|
|
],
|
|
}),
|
|
);
|
|
expect(
|
|
arbitrate({
|
|
governanceGate: { kind: "interaction", id: "interaction" },
|
|
assessment: assessment({
|
|
reportedDisposition: "yielded",
|
|
continuation: {
|
|
kind: "response_wake",
|
|
summary: "Resume from the response",
|
|
idempotencyKey: "interaction-response:interaction",
|
|
},
|
|
}),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_review",
|
|
reasonCode: "governed_response_waiting",
|
|
effects: [
|
|
{
|
|
kind: "create_interaction",
|
|
gate: { kind: "interaction", id: "interaction" },
|
|
},
|
|
],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("accepts low-risk completion claims with unrun verification caveats", () => {
|
|
const withCaveat = assessment({
|
|
verificationPassed: false,
|
|
criterionAssessments: [
|
|
{
|
|
criterionId: "objective",
|
|
claimStatus: "satisfied",
|
|
outcome: "missing",
|
|
evidenceRefs: [],
|
|
reasonCode: "criterion_evidence_missing",
|
|
},
|
|
],
|
|
verificationAssessments: [
|
|
{
|
|
commandOrCheck: "Run npm test",
|
|
claimStatus: "not_run",
|
|
outcome: "missing",
|
|
evidenceRef: null,
|
|
reasonCode: "verification_not_run",
|
|
reportedReasonCode: "tool_unavailable",
|
|
detail: "Node and npm are unavailable in this environment.",
|
|
},
|
|
],
|
|
verificationCaveats: [
|
|
{
|
|
commandOrCheck: "Run npm test",
|
|
reasonCode: "tool_unavailable",
|
|
detail: "Node and npm are unavailable in this environment.",
|
|
},
|
|
],
|
|
});
|
|
|
|
expect(
|
|
arbitrate({
|
|
assessment: withCaveat,
|
|
completionClaimPolicyAccepted: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "done",
|
|
reasonCode: "completion_claim_policy_accepted",
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("keeps failed verification with the agent and routes explicit attention to its owner", () => {
|
|
const failed = assessment({
|
|
verificationPassed: false,
|
|
hasFailedVerification: true,
|
|
verificationAssessments: [
|
|
{
|
|
commandOrCheck: "Run npm test",
|
|
claimStatus: "failed",
|
|
outcome: "rejected",
|
|
evidenceRef: null,
|
|
reasonCode: "verification_reported_failed",
|
|
reportedReasonCode: null,
|
|
detail: "One test failed.",
|
|
},
|
|
],
|
|
});
|
|
expect(
|
|
arbitrate({
|
|
assessment: failed,
|
|
completionClaimPolicyAccepted: true,
|
|
reviewOwnerUserId: "user-1",
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_progress",
|
|
reasonCode: "completion_evidence_incomplete",
|
|
effects: [
|
|
expect.objectContaining({
|
|
kind: "enqueue_continuation",
|
|
agentId: "agent",
|
|
}),
|
|
],
|
|
}),
|
|
);
|
|
|
|
const withAttention = assessment({
|
|
attentionRequests: [
|
|
{
|
|
kind: "approval",
|
|
summary: "Approve publication",
|
|
ownerClass: "human",
|
|
targetAgentId: null,
|
|
sourceIndex: 0,
|
|
sourceKind: "approval",
|
|
legacy: false,
|
|
},
|
|
],
|
|
});
|
|
expect(
|
|
arbitrate({
|
|
assessment: withAttention,
|
|
completionClaimPolicyAccepted: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "in_review",
|
|
reasonCode: "actionable_attention_pending",
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("blocks only for a task-wide blocker with a named owner and action", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "blocked",
|
|
blocker: {
|
|
boardOwned: true,
|
|
scope: "task_wide",
|
|
unblockAction: "Approve access",
|
|
},
|
|
}),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "blocked",
|
|
unblockDescriptor: { owner: "board", action: "Approve access" },
|
|
effects: [
|
|
{ kind: "bind_blocker", owner: "board", action: "Approve access" },
|
|
{
|
|
kind: "notify_owner",
|
|
agentId: "agent",
|
|
reason: "task_wide_blocker_bound",
|
|
},
|
|
],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("waits for an explicit unblock instead of inventing another productive track", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "blocked",
|
|
objectiveClaimSatisfied: false,
|
|
objectiveSatisfied: false,
|
|
allCriteriaSatisfied: false,
|
|
verificationPassed: false,
|
|
hasBlockingRemainingWork: true,
|
|
blocker: {
|
|
boardOwned: false,
|
|
scope: "current_track",
|
|
unblockAction:
|
|
"Grant access to the current Board comment attachment, then explicitly retry.",
|
|
},
|
|
}),
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "blocked",
|
|
toStatus: "blocked",
|
|
policyVersion: "phase6-v14",
|
|
reasonCode: "current_track_blocker_waiting",
|
|
unblockDescriptor: {
|
|
owner: "board",
|
|
action:
|
|
"Grant access to the current Board comment attachment, then explicitly retry.",
|
|
},
|
|
effects: [
|
|
{
|
|
kind: "bind_blocker",
|
|
owner: "board",
|
|
action:
|
|
"Grant access to the current Board comment attachment, then explicitly retry.",
|
|
},
|
|
],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("blocks a current-track result when a durable dependency already gates the issue", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "blocked",
|
|
blocker: {
|
|
boardOwned: false,
|
|
scope: "current_track",
|
|
unblockAction: "Wait for child task DOT-52",
|
|
},
|
|
}),
|
|
hasUnresolvedIssueBlockers: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "blocked",
|
|
toStatus: "blocked",
|
|
reasonCode: "durable_dependency_blocker_bound",
|
|
unblockDescriptor: {
|
|
owner: { agentId: "agent" },
|
|
action: "Wait for child task DOT-52",
|
|
},
|
|
effects: [],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("lets a durable dependency override an optimistic done result", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({ reportedDisposition: "done", blocker: null }),
|
|
completionClaimPolicyAccepted: true,
|
|
hasUnresolvedIssueBlockers: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "blocked",
|
|
toStatus: "blocked",
|
|
reasonCode: "durable_dependency_blocker_bound",
|
|
effects: [],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("does not create a duplicate review after this run's review was already accepted", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "needs_review",
|
|
attentionRequests: [
|
|
{
|
|
kind: "review",
|
|
summary: "Accept the plan",
|
|
ownerClass: "human",
|
|
targetAgentId: null,
|
|
sourceIndex: 0,
|
|
sourceKind: "review",
|
|
legacy: false,
|
|
},
|
|
],
|
|
}),
|
|
governanceResolvedForRun: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "in_review",
|
|
reasonCode: "governance_response_continuation_queued",
|
|
effects: [],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("does not create a duplicate review after this run's planning confirmation was already accepted", () => {
|
|
expect(
|
|
arbitrate({
|
|
assessment: assessment({
|
|
reportedDisposition: "blocked",
|
|
attentionRequests: [
|
|
{
|
|
kind: "approval",
|
|
summary: "Accept the pinned plan revision.",
|
|
ownerClass: "human",
|
|
targetAgentId: null,
|
|
sourceIndex: 0,
|
|
sourceKind: "approval",
|
|
legacy: false,
|
|
},
|
|
],
|
|
}),
|
|
governanceResolvedForRun: true,
|
|
}),
|
|
).toEqual(
|
|
expect.objectContaining({
|
|
statusAction: "in_review",
|
|
reasonCode: "governance_response_continuation_queued",
|
|
effects: [],
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("preserves authoritative terminal statuses", () => {
|
|
expect(arbitrate({ priorIssueStatus: "done" })).toEqual(
|
|
expect.objectContaining({
|
|
toStatus: "done",
|
|
reasonCode: "terminal_status_preserved",
|
|
effects: [],
|
|
}),
|
|
);
|
|
});
|
|
it("routes each explicit request to its own reviewer", () => {
|
|
const decision = arbitrate({ assessment: assessment({ attentionRequests: [
|
|
{ kind: "approval", summary: "Approve release", ownerClass: "human", targetAgentId: null, sourceIndex: 0, sourceKind: "approval", legacy: false },
|
|
{ kind: "review", summary: "Review code", ownerClass: "agent", targetAgentId: "review-agent", sourceIndex: 1, sourceKind: "review", legacy: false },
|
|
] }), reviewOwnerUserId: "release-owner" });
|
|
expect(decision.effects).toEqual([
|
|
expect.objectContaining({ kind: "bind_reviewer", requestKey: "attention-0", prompt: "Approve release", ownerUserId: "release-owner", ownerAgentId: null }),
|
|
expect.objectContaining({ kind: "bind_reviewer", requestKey: "attention-1", prompt: "Review code", ownerUserId: null, ownerAgentId: "review-agent" }),
|
|
]);
|
|
});
|
|
|
|
});
|