fix(runner): stop a turn that keeps resending a refused tool call and continue fresh (#21734)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native agent runs call Paperclip tools, and
`RepeatedToolFailureGuard` refuses an exact repeat of a call that
already failed validation twice
> - The refusals are not counted and never end the turn, so a model
whose host drops an argument can resend the same refused call until the
run's wall clock
> - In a recorded restart-chaos wave, an opencode/DeepSeek agent sent
the same `PATCH /api/issues/{id}` through `call_api` 431 times in 40
minutes without `body`; 427 were refused. The run held an agent slot and
delayed other tasks
> - The system knows the next step (stop the turn and continue on a
fresh session), so the harness must own it, with no Retry banner
> - This pull request counts refusals, stops the provider turn after a
bounded number with the classified cause `agent_tool_call_loop`, and
queues an automatic fresh-session continuation that tells the model to
use a dedicated tool
> - It also records the declared argument names that each opencode tool
call delivered, so we can tell whether the bridge or the model drops
`body`
> - The benefit is that a looping agent frees its slot in seconds
instead of 40 minutes, and the task continues by itself

## Linked Issues or Issue Description

**What happened?**
An opencode agent on DeepSeek created two subtasks and then tried to set
their descriptions with `call_api` `PATCH /api/issues/{id}`. Every call
arrived with `operationId`, `pathParams`, `query` and `responseText`,
but without `body`. The guard refused each repeat. The model said "I
need to include body" more than 20 times and kept sending the same call:
431 calls, 427 refused, over 40 minutes. The run stayed active and its
agent slot delayed other queued work.

**Expected behavior**
After a small, bounded number of refusals, Paperclip stops the provider
turn and continues the task automatically on a fresh session, with a
hint to use a dedicated Paperclip tool. The board shows no Retry banner
because the system owns this recovery.

**Steps to reproduce**
1. Run a native agent whose model resends one tool call with a missing
required argument.
2. The guard refuses the third and later identical calls.
3. On master, the refusals never end the turn.

**Paperclip version or commit**
`master` at 6400698a8e.

## What Changed

- `repeated-tool-failure-guard.ts`: counts refusals per exact call and
per run. At 6 refusals of one call, or 20 refusals in the run, it throws
`ToolCallLoopError` (`code: "agent_tool_call_loop"`, tool, counts and
argument names, never values). The message tells the model the turn
stops and gives a short hint.
- `paperclip-runner-tool-authority.ts`:
`scheduleToolCallLoopContinuation` writes one idempotent native
status-wake outbox row (key `agent_tool_call_loop:<runId>`) with
`forceFreshSession: true` and the hint as the wake instruction. The
outbox dispatcher admits it with `allowRunCoalescing: false`, so it
never merges into a deferred comment wake or the active run. An assignee
run uses `issue_continuation_needed`. A completion-review run uses
`native_completion_review` with its review assignment, which the
dispatcher revalidates, so the fresh reviewer session keeps the review.
- `native-session-executor.ts`: the session authority epoch queues that
continuation when the guard raises the loop error. The governed-wait
lookup finds the wake on the next tool event and ends the provider turn
as `yielded` with a `same_agent` continuation, the same way the
connection-tools refresh ends a turn. If the wake cannot be queued, the
refusal still reaches the model and the error is logged.
- `status-decision-committer.ts`: a yielded continuation with that key
binds to the queued wake instead of creating a second one.
- `status-arbiter.ts` and `native-run-finalizer.ts`: a pending review
run that ended through this continuation skips the
`native_review_unresolved` resume recovery, because the queued review
wake owns the next reviewer run.
- `mcp-bridge.ts` and `opencode-proxy-finish-diagnostics.ts`: the
opencode tool-delivery diagnostic records `argumentNames` (only names
declared in the tool's input schema, sorted, at most 1,024 characters of
JSON), `argumentNamesTruncated` and `undeclaredArgumentCount`. Values
and undeclared names are never recorded. The forwarder's closed key
allowlist accepts the new fields and validates them, so a record stays
under its 2,048-character limit.

### Threshold choice

- **6 refusals of one exact call.** The guard already runs a call twice
and then refuses with an explicit correction. Six more refusals (eight
identical attempts in total) give a model that reads errors many chances
to change its arguments. In the recorded run the model never changed
them in 427 refusals, so six refusals end that loop within seconds.
- **20 refusals in the run.** A model can alternate between a few
refused variants and keep each one under 6. Refusals happen only for
exact repeats of a certain validation failure, so a healthy run almost
never reaches 20.

### Previous-release story

The guard counters live in memory for one run's tool authority, as
before. A deploy or restart during a run starts the counters again at
zero on the new process; that only delays the stop. The continuation is
an ordinary wake row. If a server on the previous release finalizes a
run that a new server parked, it does not know the key and queues its
own `same_agent` continuation too; the issue execution lock lets one run
and the other coalesces.

## Verification

- Red then green, `repeated-tool-failure-guard.test.ts`: "after N
refusals the guard raises a turn-stopping loop error" and "stops the
turn once refusals across different calls reach the run limit". Both
fail on master.
- Red then green, `native-session-executor.test.ts`: "a turn whose model
repeats a refused call N times ends with agent_tool_call_loop and
schedules a continuation". With the epoch handling disabled it fails (13
calls instead of 8, nothing parked). Also "keeps the refused call's
error when the loop continuation cannot be queued".
- `paperclip-runner-tool-authority.test.ts`: "queues one fresh-session
continuation outbox for the assignee / a completion reviewer stopped by
a tool-call loop" (real Postgres; idempotent).
- `native-tool-call-loop-continuation.test.ts`: with a comment wake
already deferred behind the looping run, the continuation keeps its own
keyed deferred wake, the comment wake is unchanged, and after release a
run starts with `forceFreshSession` and the loop cause.
- `status-arbiter.test.ts`: a pending reviewer stopped by a loop
releases its checkout without a resume recovery.
- `native-status-arbiter-corpus.test.ts`: the existing wake-binding test
now also covers the `agent_tool_call_loop` key.
- `mcp-bridge-delivery.test.ts` and
`opencode-proxy-finish-diagnostics.test.ts`: argument names are
recorded, values and undeclared names are not, invalid records are
dropped, and a boundary test with 32 names of 64 characters stays
forwardable with `argumentNamesTruncated: true`.
- Server: the six touched test files pass (1755 tests). Runner:
`src/drivers/opencode` and `src/cli` pass (569 tests). `tsc --noEmit`
passes for `server` and `packages/paperclip-runner`.
- `pnpm verify` exits 2 (runner package changes need broad coverage), so
required CI supplies the broad run.

## Risks

- A run that hits the limit ends its turn early. The limits are far
above what a model that reads its errors needs, and the task continues
automatically on a fresh session.
- The fresh session loses the in-turn conversation. The task, its
comments, documents and workspace stay, and the continuation names the
cause and the hint.
- The diagnostic now carries declared argument names. These are schema
names, not values, and the forwarder validates the shape before it
forwards a record.

## 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 #21360

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-15 01:52:50 -06:00
1 parent c7efca1eaf
commit 01c1e708e9
16 files changed
+493 -15

No files matched your search

@@ -115,6 +115,27 @@ it("forwards closed tool delivery records after binding and drops any record tha
message: JSON.stringify({ ...delivery, socketRequestIndex: 2, socketIdleMs: 5270 }) } }]);
});
it("forwards delivery records with argument names and drops names that could carry values", () => {
const frames: { params: { message: string } }[] = [];
const forward = createOpenCodeFinishDiagnosticForwarder(frame => frames.push(frame as never));
forward.bind("session");
const delivery = { schema: "paperclip.opencode.tool-delivery-diagnostic/v1", callIdSha256: "e".repeat(64),
socketRequestIndex: 1, socketIdleMs: null, handlerMs: 4, outcome: "result", written: true,
argumentNames: ["operationId", "pathParams", "query", "responseText"], argumentNamesTruncated: false, undeclaredArgumentCount: 0 };
for (const bad of [
{ ...delivery, argumentNames: ["body value"] },
{ ...delivery, argumentNames: "operationId" },
{ ...delivery, argumentNames: Array.from({ length: 20 }, (_, n) => `${n}${"a".repeat(60)}`) },
{ ...delivery, argumentNamesTruncated: "no" },
{ ...delivery, undeclaredArgumentCount: -1 },
{ ...delivery, undeclaredArgumentCount: "1" },
]) forward.diagnostic(JSON.stringify(bad));
expect(frames).toEqual([]);
forward.diagnostic(JSON.stringify(delivery));
forward.diagnostic(JSON.stringify({ ...delivery, argumentNames: null }));
expect(frames.map(frame => JSON.parse(frame.params.message).argumentNames)).toEqual([delivery.argumentNames, null]);
});
it("forwards closed input-coercion records and drops any that could carry values", () => {
const frames: { params: { message: string } }[] = [];
const forward = createOpenCodeFinishDiagnosticForwarder(frame => frames.push(frame as never));
@@ -52,11 +52,15 @@ export function createOpenCodeFinishDiagnosticForwarder(send: (frame: Warning) =
}
const TOOL_DELIVERY_KEYS = "callIdSha256,handlerMs,outcome,schema,socketIdleMs,socketRequestIndex,written";
const TOOL_DELIVERY_KEYS_WITH_ARGUMENTS = "argumentNames,argumentNamesTruncated,callIdSha256,handlerMs,outcome,schema,socketIdleMs,socketRequestIndex,undeclaredArgumentCount,written";
const validArgumentNames = (names: unknown) => names === null || (Array.isArray(names) && JSON.stringify(names).length <= 1_024
&& names.every(name => typeof name === "string" && /^[A-Za-z0-9_.-]{1,64}$/.test(name)));
// Delivery records carry only hashes, counters and timings. Reject anything
// else so this channel cannot forward tool inputs or results.
function validToolDelivery(value: Record<string, unknown>): boolean {
const count = (entry: unknown) => typeof entry === "number" && Number.isSafeInteger(entry) && entry >= 0;
return Object.keys(value).sort().join(",") === TOOL_DELIVERY_KEYS
const keys = Object.keys(value).sort().join(",");
return (keys === TOOL_DELIVERY_KEYS || (keys === TOOL_DELIVERY_KEYS_WITH_ARGUMENTS && validArgumentNames(value.argumentNames) && typeof value.argumentNamesTruncated === "boolean" && count(value.undeclaredArgumentCount)))
&& typeof value.callIdSha256 === "string" && /^[a-f0-9]{64}$/.test(value.callIdSha256)
&& count(value.socketRequestIndex) && count(value.handlerMs)
&& (value.socketIdleMs === null || count(value.socketIdleMs))
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
import { Agent, request } from "node:http";
import { afterEach, expect, it } from "vitest";
import { startOpenCodeMcpBridge, type OpenCodeMcpBridge } from "./mcp-bridge.js";
import { createOpenCodeFinishDiagnosticForwarder } from "../../cli/opencode-proxy-finish-diagnostics.js";
const bridges: OpenCodeMcpBridge[] = [];
const agents: Agent[] = [];
@@ -88,6 +89,9 @@ it("answers each tool call, including a parallel pair on a pooled keep-alive cli
socketRequestIndex: expect.any(Number),
socketIdleMs: delivery.socketRequestIndex === 1 ? null : expect.any(Number),
handlerMs: expect.any(Number),
argumentNames: [],
argumentNamesTruncated: false,
undeclaredArgumentCount: 0,
outcome: "result",
written: true,
});
@@ -140,3 +144,56 @@ it("records a rejected call as an answered error", async () => {
callIdSha256: createHash("sha256").update("11").digest("hex"), outcome: "error", written: true,
});
});
it("records the declared argument names a call delivered, never their values or undeclared names", async () => {
const messages: string[] = [];
const bridge = await startOpenCodeMcpBridge({
tools: [{ name: "call_api", inputSchema: { type: "object", properties: {
operationId: { type: "string" }, pathParams: { type: "object" }, query: { type: "object" }, body: {}, responseText: { type: "object" },
} } }],
handler: async () => ({ ok: false, status: 400 }),
onDiagnostic: message => { if (message.includes("tool-delivery-diagnostic")) messages.push(message); },
});
bridges.push(bridge);
await (await fetch(bridge.url, {
method: "POST",
headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: 12, method: "tools/call", params: { name: "call_api", arguments: {
operationId: "PATCH /api/issues/{id}", pathParams: { id: "secret-issue" }, query: {}, responseText: { limitBytes: 8192 }, PRIVATE_FIELD: 1,
} } }),
})).json();
await expect.poll(() => messages.length).toBe(1);
expect(JSON.parse(messages[0]!)).toMatchObject({ argumentNames: ["operationId", "pathParams", "query", "responseText"],
argumentNamesTruncated: false, undeclaredArgumentCount: 1, outcome: "result" });
expect(messages[0]).not.toMatch(/PATCH|secret-issue|8192|PRIVATE_FIELD/);
});
it("bounds many long argument names so the forwarder keeps the whole delivery record", async () => {
const names = Array.from({ length: 32 }, (_, n) => `${String(n).padStart(2, "0")}${"a".repeat(62)}`);
const messages: string[] = [];
const bridge = await startOpenCodeMcpBridge({
tools: [{ name: "wide_tool", inputSchema: { type: "object", properties: Object.fromEntries(names.map(name => [name, {}])) } }],
handler: async () => ({ ok: true }),
onDiagnostic: message => { if (message.includes("tool-delivery-diagnostic")) messages.push(message); },
});
bridges.push(bridge);
await (await fetch(bridge.url, {
method: "POST",
headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: 13, method: "tools/call", params: { name: "wide_tool",
arguments: Object.fromEntries(names.map(name => [name, 1])) } }),
})).json();
await expect.poll(() => messages.length).toBe(1);
const record = JSON.parse(messages[0]!);
expect(record.argumentNamesTruncated).toBe(true);
expect(record.argumentNames.length).toBeGreaterThan(0);
expect(record.argumentNames.length).toBeLessThan(names.length);
expect(record.argumentNames).toEqual(names.slice(0, record.argumentNames.length));
expect(JSON.stringify(record.argumentNames).length).toBeLessThanOrEqual(1_024);
expect(messages[0]!.length).toBeLessThanOrEqual(2_048);
const frames: unknown[] = [];
const forward = createOpenCodeFinishDiagnosticForwarder(frame => frames.push(frame));
forward.bind("session");
forward.diagnostic(messages[0]!);
expect(frames).toHaveLength(1);
});
@@ -65,6 +65,8 @@ const MAX_RESULT_BYTES = 1_048_576;
const TOOL_DELIVERY_DIAGNOSTIC_SCHEMA = "paperclip.opencode.tool-delivery-diagnostic/v1";
const MAX_TOOL_DELIVERY_DIAGNOSTICS = 256;
const MAX_TOOL_INPUT_COERCION_DIAGNOSTICS = 64;
const MAX_TOOL_DELIVERY_ARGUMENT_NAMES_CHARS = 1_024;
const TOOL_DELIVERY_ARGUMENT_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
type SocketUse = { requests: number; lastResponseAt: number | null };
type ToolDelivery = {
@@ -73,6 +75,7 @@ type ToolDelivery = {
receivedAt: number;
};
type ToolDeliveryOutcome = "result" | "error" | "unanswered";
type ToolDeliveryInput = { argumentNames: string[] | null; argumentNamesTruncated: boolean; undeclaredArgumentCount: number };
export function canonicalOpenCodeMcpToolName(name: string): string {
const trimmed = name.trim();
@@ -131,11 +134,14 @@ export async function startOpenCodeMcpBridge(
delivery: ToolDelivery,
outcome: ToolDeliveryOutcome,
written: boolean,
input?: ToolDeliveryInput,
) => {
if (!options.onDiagnostic || deliveryDiagnostics++ >= MAX_TOOL_DELIVERY_DIAGNOSTICS) return;
const diagnostic = {
schema: TOOL_DELIVERY_DIAGNOSTIC_SCHEMA,
callIdSha256: createHash("sha256").update(callId).digest("hex"),
...(input ? { argumentNames: input.argumentNames, argumentNamesTruncated: input.argumentNamesTruncated,
undeclaredArgumentCount: input.undeclaredArgumentCount } : {}),
socketRequestIndex: delivery.socketRequestIndex,
socketIdleMs: delivery.socketIdleMs,
handlerMs: Date.now() - delivery.receivedAt,
@@ -200,6 +206,18 @@ export async function startOpenCodeMcpBridge(
};
}
function boundedArgumentNames(names: string[] | null): Pick<ToolDeliveryInput, "argumentNames" | "argumentNamesTruncated"> {
if (!names) return { argumentNames: null, argumentNamesTruncated: false };
const kept: string[] = [];
let size = 2;
for (const name of [...names].sort()) {
size += JSON.stringify(name).length + (kept.length ? 1 : 0);
if (size > MAX_TOOL_DELIVERY_ARGUMENT_NAMES_CHARS) return { argumentNames: kept, argumentNamesTruncated: true };
kept.push(name);
}
return { argumentNames: kept, argumentNamesTruncated: false };
}
function inputShape(input: unknown): "omitted" | "null" | "array" | "object" | "string" | "number" | "boolean" | "other" {
if (input === undefined) return "omitted";
if (input === null) return "null";
@@ -250,7 +268,7 @@ async function handleRequest(
response: ServerResponse,
context: {
delivery: ToolDelivery;
diagnoseToolDelivery: (callId: string, delivery: ToolDelivery, outcome: ToolDeliveryOutcome, written: boolean) => void;
diagnoseToolDelivery: (callId: string, delivery: ToolDelivery, outcome: ToolDeliveryOutcome, written: boolean, input?: ToolDeliveryInput) => void;
secret: string;
tools: OpenCodeMcpToolDefinition[];
admittedTools: OpenCodeMcpToolDefinition[];
@@ -345,8 +363,9 @@ async function handleRequest(
// client that never consumes a written answer can be told apart from a
// bridge that never answered it.
let outcome: ToolDeliveryOutcome = "unanswered";
let deliveredInput: ToolDeliveryInput | undefined;
response.once("close", () => {
context.diagnoseToolDelivery(callId, context.delivery, outcome, response.writableFinished);
context.diagnoseToolDelivery(callId, context.delivery, outcome, response.writableFinished, deliveredInput);
});
const rawName = typeof params.name === "string" ? params.name : "";
// A declared operation may itself start with paperclip_. Preserve that
@@ -361,6 +380,14 @@ async function handleRequest(
return;
}
const received = params.arguments ?? {};
const declaredSchema = context.admittedTools.find(entry => entry.name === tool)?.inputSchema.properties;
const declaredArguments = isRecord(declaredSchema) ? declaredSchema : {};
const receivedNames = isRecord(received) ? Object.keys(received) : null;
const declaredNames = receivedNames?.filter(name => Object.hasOwn(declaredArguments, name) && TOOL_DELIVERY_ARGUMENT_NAME.test(name)) ?? null;
deliveredInput = {
...boundedArgumentNames(declaredNames),
undeclaredArgumentCount: (receivedNames?.length ?? 0) - (declaredNames?.length ?? 0),
};
const validator = context.validators.get(tool);
const admitted = admitToolInput(validator, received);
const { args, schemaValid } = admitted;
@@ -3874,11 +3874,14 @@ describe("P6-31 Section 18.13 executable status-authority corpus", () => {
]);
});
it("binds a tools-refresh continuation to its existing durable wake without a duplicate", async () => {
it.each([
["tools-refresh", (runId: string) => `connection-intent:tools:${runId}:fixture-digest`],
["tool-call-loop", (runId: string) => `agent_tool_call_loop:${runId}`],
] as const)("binds a %s continuation to its existing durable wake without a duplicate", async (name, keyFor) => {
const template = corpus.fixtures.find((candidate) => candidate.mode === "native")!;
const fixture = { ...template, id: "in-feed-tools-refresh", given: { ...template.given, priorIssueStatus: "in_progress" } };
const fixture = { ...template, id: `in-feed-${name}`, given: { ...template.given, priorIssueStatus: "in_progress" } };
const seeded = await seedFixture(fixture);
const key = `connection-intent:tools:${seeded.runId}:fixture-digest`;
const key = keyFor(seeded.runId);
const [wake] = await db.insert(agentWakeupRequests).values({ companyId, agentId, source: "assignment", status: "queued", idempotencyKey: key,
payload: { issueId: seeded.issueId, mutation: "connection_tools_refreshed" } }).returning();
const decision: NativeStatusDecision = { policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION, statusAction: "in_progress", toStatus: "in_progress",
@@ -0,0 +1,126 @@
import { randomUUID } from "node:crypto";
import { and, eq } from "drizzle-orm";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import {
agents,
agentWakeupRequests,
authUsers,
companies,
companyMemberships,
createDb,
EMBEDDED_POSTGRES_TEST_TIMEOUT_MS,
heartbeatRuns,
issues,
} from "@paperclipai/db";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
import { drainHeartbeatRunsToQuiescence } from "./helpers/drain-heartbeat-runs.js";
import { heartbeatService } from "../services/heartbeat.ts";
import { type AdapterExecutionContext, type AdapterExecutionResult } from "../adapters/index.ts";
import { PaperclipRunnerToolAuthority } from "../services/native-runtime/paperclip-runner-tool-authority.js";
import { ToolCallLoopError, toolCallLoopContinuationKey } from "../services/native-runtime/repeated-tool-failure-guard.js";
const mockAdapterExecute = vi.hoisted(() =>
vi.fn(async (_context: AdapterExecutionContext): Promise<AdapterExecutionResult> => ({
exitCode: 0, signal: null, timedOut: false, errorMessage: null,
summary: "Tool-call loop continuation test run.", provider: "test", model: "test-model",
})),
);
vi.mock("../adapters/index.ts", async () => {
const actual = await vi.importActual<typeof import("../adapters/index.ts")>("../adapters/index.ts");
return { ...actual, getServerAdapter: vi.fn(() => ({ supportsLocalAgentJwt: false, execute: mockAdapterExecute })) };
});
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
if (!embeddedPostgresSupport.supported) {
console.warn(
`Skipping tool-call loop continuation tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
);
}
describeEmbeddedPostgres("the continuation of a turn stopped by a tool-call loop", () => {
let db!: ReturnType<typeof createDb>;
let heartbeat!: ReturnType<typeof heartbeatService>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
beforeAll(async () => {
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-tool-call-loop-continuation-");
db = createDb(tempDb.connectionString);
heartbeat = heartbeatService(db, { runtimeEnv: { ...process.env, PAPERCLIP_IN_WORKTREE: "false" } });
}, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS);
afterAll(async () => {
await drainHeartbeatRunsToQuiescence(db, heartbeat);
await db?.$client.end();
await tempDb?.cleanup();
});
it("keeps its own keyed wake when a comment wake is already deferred behind the looping run", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const issueId = randomUUID();
await db.insert(companies).values({
id: companyId, name: "Loop Co", issuePrefix: `L${companyId.replace(/-/g, "").slice(0, 5).toUpperCase()}`,
defaultResponsibleUserId: "responsible-user", requireBoardApprovalForNewAgents: false,
});
await db.insert(authUsers).values({
id: "responsible-user", name: "Fixture user", email: "responsible-user@example.test",
createdAt: new Date(), updatedAt: new Date(),
}).onConflictDoNothing();
await db.insert(companyMemberships).values({
companyId, principalType: "user", principalId: "responsible-user", status: "active", membershipRole: "member",
});
await db.insert(agents).values({
id: agentId, companyId, name: "Looper", role: "engineer", status: "idle", adapterType: "codex_local",
adapterConfig: {}, runtimeConfig: { heartbeat: { wakeOnDemand: true, maxConcurrentRuns: 1 } }, permissions: {},
});
await db.insert(issues).values({
id: issueId, companyId, title: "Describe the subtasks", status: "todo", priority: "medium",
assigneeAgentId: agentId, responsibleUserId: "responsible-user",
});
let finishLoopingRun!: () => void;
const loopingRunFinished = new Promise<void>((resolve) => { finishLoopingRun = resolve; });
mockAdapterExecute.mockImplementationOnce(async () => {
await loopingRunFinished;
return { exitCode: 0, signal: null, timedOut: false, errorMessage: null,
summary: "Stopped after a tool-call loop.", provider: "test", model: "test-model" };
});
const loopingRun = await heartbeat.wakeup(agentId, {
source: "assignment", triggerDetail: "system", reason: "issue_assigned",
requestedByActorType: "system", payload: { issueId }, contextSnapshot: { issueId, wakeReason: "issue_assigned" },
});
expect(loopingRun).not.toBeNull();
await vi.waitFor(() => expect(mockAdapterExecute).toHaveBeenCalledTimes(1), { timeout: 30_000 });
const [commentWake] = await db.insert(agentWakeupRequests).values({
companyId, agentId, source: "automation", triggerDetail: "system", reason: "issue_commented",
status: "deferred_issue_execution", requestedByActorType: "user", requestedByActorId: "responsible-user",
payload: { issueId, _paperclipWakeContext: { issueId, wakeReason: "issue_commented" } },
}).returning();
const authority = new PaperclipRunnerToolAuthority(db, { companyId, agentId, issueId, runId: loopingRun!.id, workMode: "standard" });
await authority.scheduleToolCallLoopContinuation(new ToolCallLoopError("call_api", 6, 6, ["operationId", "pathParams"], 400, "refused"));
await heartbeat.dispatchPendingNativeStatusWakeups({ companyId });
await heartbeat.dispatchPendingNativeStatusWakeups({ companyId });
const key = toolCallLoopContinuationKey(loopingRun!.id);
const keyed = await db.select().from(agentWakeupRequests).where(and(
eq(agentWakeupRequests.companyId, companyId), eq(agentWakeupRequests.idempotencyKey, key),
));
expect(keyed.some((wake) => wake.status === "deferred_issue_execution" && wake.id !== commentWake!.id)).toBe(true);
expect(keyed.every((wake) => !["skipped", "failed", "cancelled"].includes(wake.status))).toBe(true);
const [comment] = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, commentWake!.id));
expect(comment).toMatchObject({ status: "deferred_issue_execution", coalescedCount: 0, idempotencyKey: null });
finishLoopingRun();
await vi.waitFor(async () => {
const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, companyId));
expect(runs.some((run) => run.id !== loopingRun!.id && run.contextSnapshot?.livenessContinuationReason === "agent_tool_call_loop"
&& run.contextSnapshot?.forceFreshSession === true)).toBe(true);
}, { timeout: 30_000 });
}, 90_000);
});
@@ -36,6 +36,7 @@ import { explainFailedRun, explainNativeTurnFailure, NATIVE_RUN_FAILED_UNEXPLAIN
import { dismissAutomaticCompletionReviews } from "./automatic-completion-reviews.js";
import { findSupersededExternalReviewRequests } from "./superseded-external-review-requests.js";
import { getNativeReviewAssignment, readNativeReviewAssignmentContext } from "./native-review-participant.js";
import { toolCallLoopContinuationKey } from "./repeated-tool-failure-guard.js";
import { conversationNativeDecision, isConversation, settleConversationTurnForRun } from "../agent-conversations.js";
import { issueTreeControlService } from "../issue-tree-control.js";
import { COMPLETION_REVIEW_STAGE_REASON, completionReviewStageEntry } from "../issue-execution-policy.js";
@@ -1765,6 +1766,8 @@ export async function finalizeNativeRun(input: {
// into a blocker; the committer rechecks that under the issue lock.
failedTurnContinuationUsed: terminalState === "failed" && ownsProviderFailureDecision && !reviewContext
&& await isFailedTurnContinuationRun(input.db, run, authoritativeIssue.id),
toolCallLoopContinuation: assessment.reportedDisposition === "yielded"
&& assessment.continuation?.idempotencyKey === toolCallLoopContinuationKey(run.id),
...(reviewContext ? { nativeReviewOutcome: nativeReview
? nativeReview.interaction.status === "pending" ? "pending" as const : "resolved" as const
: "stale" as const } : {}),
@@ -21,6 +21,7 @@ import { trace } from "@opentelemetry/api";
import { InMemorySpanExporter, SimpleSpanProcessor, TracerProvider } from "@opentelemetry/sdk-trace";
import { configuredEnvironment, configuredEnvironmentProjection } from "../../vendor/paperclip-runner/index.js";
import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";
import { TOOL_CALL_LOOP_REFUSAL_LIMIT, ToolCallLoopError, toolCallLoopContinuationKey } from "./repeated-tool-failure-guard.js";
import { enableReattachPhase, isReattachPhaseActive, joinReattachPhase, onReattachPhaseEnd, resetReattachPhaseForTests, type ReattachPhaseSummary } from "../heartbeat/run-admission.js";
import { createSystemRecovery, failSystemRecovery, reserveSystemRecoveryAttempt, SystemRecoveryFailure } from "../system-recovery-state.js";
import { registerRunStartHandover } from "../run-start-handover.js";
@@ -81,7 +82,9 @@ import {
type NativeExecutionInputV3,
type NativeExecutionInput,
type PrpEvent,
type PrpStructuredRunResult,
} from "@paperclipai/paperclip-runner";
import { HttpError } from "../../errors.js";
import { existsSync } from "node:fs";
import { createHash, generateKeyPairSync, randomUUID } from "node:crypto";
import { createServer as createNetServer } from "node:net";
@@ -468,6 +471,8 @@ import {
nativeGovernedWaitResult,
nativeConversationReplyResult,
nativeToolsRefreshWaitResult,
nativeToolCallLoopWaitResult,
SessionAuthorityEpoch,
parseRemoteExecutableCandidate,
buildRemoteCodexLauncherCommand,
mayUsePreinstalledRunnerArtifact,
@@ -7912,6 +7917,66 @@ describe("native conversation replies", () => {
});
describe("native governed waits", () => {
it("a turn whose model repeats a refused call N times ends with agent_tool_call_loop and schedules a continuation", async () => {
const wakes: Array<{ id: string; key: string; loop: ToolCallLoopError }> = [];
const authority = {
execute: vi.fn(async () => { throw new HttpError(400, "body is required"); }),
scheduleToolCallLoopContinuation: vi.fn(async (loop: ToolCallLoopError) => {
if (!wakes.length) wakes.push({ id: "wake-loop", key: toolCallLoopContinuationKey("run-1"), loop });
return true;
}),
close: () => {},
};
const epoch = new SessionAuthorityEpoch("run-1", authority as never);
const contract = { revision: "4", objective: "Describe the subtasks", criteria: [{ id: "describe", requirement: "Describe them" }] };
const observation = createGovernedWaitEventObservation(async () => wakes[0]
? nativeToolCallLoopWaitResult({ wakeId: wakes[0].id, key: wakes[0].key, completionContract: contract }) : null);
const args = { operationId: "PATCH /api/issues/{id}", pathParams: { id: "issue-a" }, query: {}, responseText: { limitBytes: 8192 } };
const toolEvent = (n: number): PrpEvent => ({
schema: "paperclip.prp.event.v1", sourceInstanceId: "runner-1", sourceEventId: `runner-1:item:${n}`, sourceSeq: n,
sourceKind: "runner", runId: "run-1", normalizedSessionId: "session-1", turnId: "turn-1", itemId: `call-${n}`,
eventType: "item.completed", schemaVersion: 1, priority: 0, emittedAt: "2026-11-15T05:00:00.000Z",
payload: { kind: "dynamicToolCall", item: { type: "tool_result", is_error: true } },
});
let parked: PrpStructuredRunResult | null = null;
let calls = 0;
let lastError: unknown;
while (!parked && calls < 2 + TOOL_CALL_LOOP_REFUSAL_LIMIT + 5) {
calls += 1;
lastError = await epoch.execute({ tool: "call_api", callId: `call-${calls}`, arguments: args }).then(() => null, (error: unknown) => error);
await observation.observe(toolEvent(calls), true);
parked = observation.consume(toolEvent(calls));
}
expect(calls).toBe(2 + TOOL_CALL_LOOP_REFUSAL_LIMIT);
expect(authority.execute).toHaveBeenCalledTimes(2);
expect(lastError).toBeInstanceOf(ToolCallLoopError);
expect(lastError).toMatchObject({ code: "agent_tool_call_loop", refusals: TOOL_CALL_LOOP_REFUSAL_LIMIT });
expect(authority.scheduleToolCallLoopContinuation).toHaveBeenCalledTimes(1);
expect(parked).toMatchObject({
reportedWorkDisposition: "yielded",
completionClaim: { objectiveSatisfied: false },
evidence: [{ ref: "wakeup:wake-loop" }],
continuation: { kind: "same_agent", idempotencyKey: "agent_tool_call_loop:run-1", summary: "Continue the task in a fresh session." },
});
});
it("keeps the refused call's error when the loop continuation cannot be queued", async () => {
const authority = {
execute: vi.fn(async () => { throw new HttpError(400, "body is required"); }),
scheduleToolCallLoopContinuation: vi.fn(async () => { throw new Error("queue unavailable"); }),
close: () => {},
};
const epoch = new SessionAuthorityEpoch("run-1", authority as never);
let error: unknown;
for (let n = 0; n < 2 + TOOL_CALL_LOOP_REFUSAL_LIMIT; n++) {
error = await epoch.execute({ tool: "call_api", callId: `c-${n}`, arguments: {} }).then(() => null, (failure: unknown) => failure);
}
expect(error).toBeInstanceOf(ToolCallLoopError);
expect(authority.scheduleToolCallLoopContinuation).toHaveBeenCalledTimes(1);
});
it("yields to an existing tools-refresh wake without claiming completion or a human interaction", () => {
const result = nativeToolsRefreshWaitResult({
wakeId: "wake-1",
@@ -271,7 +271,7 @@ import { redactRunnerApiPayloads } from "./runner-api-log-redaction.js";
import { appendHeartbeatRunEvent } from "../heartbeat-run-events.js";
import { createNativeCredentialUpdateOwner, appendNativeCredentialUpdate } from "./native-credential-updates.js";
import { canonicalNativeJson, nativeSha256 } from "./canonical.js";
import { RepeatedToolFailureGuard } from "./repeated-tool-failure-guard.js";
import { RepeatedToolFailureGuard, ToolCallLoopError, toolCallLoopContinuationKey } from "./repeated-tool-failure-guard.js";
import { lockSourceRecoveryCoordinators } from "./native-source-recovery-ownership.js";
import { PaperclipRunnerToolAuthority } from "./paperclip-runner-tool-authority.js";
import { dispatchToolCallback, recoverToolCallback, type SemanticInputAdmission } from "../../vendor/paperclip-runner/index.js";
@@ -1933,6 +1933,29 @@ export function nativeToolsRefreshWaitResult(input: {
};
}
export function nativeToolCallLoopWaitResult(input: {
wakeId: string;
key: string;
completionContract: NativeExecutionInput["completionContract"]["contract"];
}): PrpStructuredRunResult {
const ref = `wakeup:${input.wakeId}`;
return {
...nativeToolsRefreshWaitResult(input),
summary: "Paperclip stopped a tool call that kept failing the same way. The task continues in a fresh session.",
completionClaim: {
contractRevision: input.completionContract.revision,
objectiveSatisfied: false,
criteria: input.completionContract.criteria.map((criterion) => ({
criterionId: criterion.id,
status: "unknown",
evidenceRefs: [ref],
})),
remainingWork: [{ description: "Continue the task in a fresh session.", blocksCompletion: true }],
},
continuation: { kind: "same_agent", summary: "Continue the task in a fresh session.", idempotencyKey: input.key },
};
}
/**
* Partial item-verdict responses deliberately leave their original durable
* interaction pending. They are already authority-checked before entering the
@@ -2293,7 +2316,14 @@ export class SessionAuthorityEpoch {
async execute(call: Parameters<PaperclipRunnerToolAuthority["execute"]>[0]) {
this.#assertCurrent();
const execute = () => this.#repeatedFailures.run(call, () => this.#authority.execute(call));
const execute = () => this.#repeatedFailures.run(call, () => this.#authority.execute(call)).catch(async (error: unknown) => {
if (error instanceof ToolCallLoopError) {
await this.#authority.scheduleToolCallLoopContinuation?.(error).catch((scheduleError: unknown) => {
logger.warn({ err: scheduleError, runId: this.runId, tool: error.tool }, "tool-call loop continuation was not queued");
});
}
throw error;
});
return dispatchToolCallback(this.runId, call.callId, async () => this.toolTrace
? await this.toolTrace.execute(call, execute)
: await execute());
@@ -12254,10 +12284,28 @@ async function executePaperclipNativeSessionAttempt(
),
)
.limit(1);
return refresh?.key
? nativeToolsRefreshWaitResult({
wakeId: refresh.id,
key: refresh.key,
if (refresh?.key)
return nativeToolsRefreshWaitResult({
wakeId: refresh.id,
key: refresh.key,
completionContract: input.execution.completionContract.contract,
});
const loopKey = toolCallLoopContinuationKey(input.execution.binding.runId);
const [loop] = await input.db
.select({ id: agentWakeupRequests.id })
.from(agentWakeupRequests)
.where(
and(
eq(agentWakeupRequests.companyId, input.execution.binding.companyId),
eq(agentWakeupRequests.idempotencyKey, loopKey),
notInArray(agentWakeupRequests.status, ["skipped", "failed", "cancelled"]),
),
)
.limit(1);
return loop
? nativeToolCallLoopWaitResult({
wakeId: loop.id,
key: loopKey,
completionContract: input.execution.completionContract.contract,
})
: null;
@@ -8,6 +8,7 @@ import { LOW_TRUST_REVIEW_PRESET, upsertIssueDocumentSchema } from "@paperclipai
import { and, eq, inArray } from "drizzle-orm";
import {
activityLog,
agentWakeupRequests,
agents,
authUsers,
approvals,
@@ -30,6 +31,7 @@ import { initializeRunIdentity, reserveSteeredIdentity, reconcileSteeredIdentity
import { documentService } from "../documents.js";
import { issueService } from "../issues.js";
import { PaperclipRunnerToolAuthority } from "./paperclip-runner-tool-authority.js";
import { TOOL_CALL_LOOP_HINT, ToolCallLoopError } from "./repeated-tool-failure-guard.js";
import { PaperclipRunnerSemanticAuthority } from "./runner-semantic-authority.js";
import { createAssignedMcpTools } from "./assigned-mcp-tools.js";
import type { ToolGatewayService } from "../tool-gateway.js";
@@ -1610,6 +1612,32 @@ describe("PaperclipRunnerToolAuthority", () => {
.rejects.toThrow(/conversation cannot be a parent/i);
});
it.each([
["the assignee", null],
["a completion reviewer", { nativeReviewInteractionId: "7f0b4f3e-2c1d-4a5b-8c6d-0e1f2a3b4c5d", nativeReviewDecisionId: "8a1c5e4f-3d2e-4b6c-9d7e-1f2a3b4c5d6e" }],
] as const)("queues one fresh-session continuation outbox for %s stopped by a tool-call loop", async (_who, nativeReview) => {
const authority = new PaperclipRunnerToolAuthority(db, {
companyId, agentId, issueId, runId, workMode: "standard", ...(nativeReview ? { nativeReview } : {}),
});
const key = `agent_tool_call_loop:${runId}`;
const loop = new ToolCallLoopError("call_api", 6, 6, ["operationId", "pathParams"], 400, "refused");
await expect(authority.scheduleToolCallLoopContinuation(loop)).resolves.toBe(true);
await expect(authority.scheduleToolCallLoopContinuation(loop)).resolves.toBe(true);
const rows = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.idempotencyKey, key));
expect(rows).toHaveLength(1);
expect(rows[0]).toMatchObject({
agentId, status: "queued", runId: null, requestedByActorType: "system", requestedByActorId: "native-status-committer",
reason: nativeReview ? "native_completion_review" : "issue_continuation_needed",
payload: {
issueId, sourceRunId: runId, continuationCause: "agent_tool_call_loop", tool: "call_api", argumentNames: ["operationId", "pathParams"],
...(nativeReview ?? {}),
_paperclipWakeContext: { issueId, forceFreshSession: true, livenessContinuationSourceRunId: runId,
livenessContinuationReason: "agent_tool_call_loop", livenessContinuationInstruction: TOOL_CALL_LOOP_HINT, ...(nativeReview ?? {}) },
},
});
await db.delete(agentWakeupRequests).where(eq(agentWakeupRequests.idempotencyKey, key));
});
it("creates ordinary children, preserves blockers, and deduplicates across runs", async () => {
const wakes: Array<{ agentId: string; options: Record<string, unknown> }> =
[];
@@ -79,6 +79,8 @@ import { assertRunnerApiDispatchable, executeRunnerApi, validateRunnerApiCall, R
import { finishPendingRunnerApiCaptureDeletes, markRunnerApiCaptureEvictions, RUNNER_API_CAPTURE_EVICTION_PASSES, runnerApiCaptureCleanupStalled, runnerApiCaptureUsageBytes } from "./runner-api-capture-retention.js";
import { acquireRunnerApiResponseSlot, RUNNER_API_RESPONSE_DEADLINE_MS, RunnerApiCaptureReservationReclaimedError, runnerApiCompanyCaptureMaxBytes, RUNNER_API_RESPONSE_MAX_BYTES, RUNNER_API_RESPONSE_RUN_MAX_BYTES, RunnerApiResponseLimitError } from "./runner-api-response-limits.js";
import { and, desc, eq, inArray, isNull, notInArray, sql } from "drizzle-orm";
import { AGENT_TOOL_CALL_LOOP, TOOL_CALL_LOOP_HINT, toolCallLoopContinuationKey, type ToolCallLoopError } from "./repeated-tool-failure-guard.js";
import { enqueueWake } from "./status-decision-committer.js";
import type { Db } from "@paperclipai/db";
import {
authUsers,
@@ -350,6 +352,25 @@ export class PaperclipRunnerToolAuthority {
#taskAttachmentCache = new TaskAttachmentReadCache();
#skillLibraryCache = new SkillLibraryReadCache();
close() { this.#taskAttachmentCache.close(); this.#skillLibraryCache.close(); this.binding.assignedMcpTools?.close?.(); }
async scheduleToolCallLoopContinuation(loop: ToolCallLoopError): Promise<boolean> {
const review = this.binding.nativeReview;
const loopContext = { sourceRunId: this.binding.runId, continuationCause: AGENT_TOOL_CALL_LOOP,
tool: loop.tool, refusals: loop.refusals, runRefusals: loop.runRefusals, argumentNames: loop.argumentNames };
await this.db.transaction(tx => enqueueWake({
tx: tx as unknown as Db,
originRunId: this.binding.runId,
companyId: this.binding.companyId,
issueId: this.binding.issueId,
agentId: this.binding.agentId,
reason: review ? "native_completion_review" : "issue_continuation_needed",
idempotencyKey: toolCallLoopContinuationKey(this.binding.runId),
payload: { ...(review ?? {}), ...loopContext },
contextSnapshot: { ...(review ?? {}), forceFreshSession: true, livenessContinuationSourceRunId: this.binding.runId,
livenessContinuationReason: AGENT_TOOL_CALL_LOOP, livenessContinuationInstruction: TOOL_CALL_LOOP_HINT },
}));
return true;
}
constructor(readonly db: Db, readonly binding: Binding) {}
definitions(): Array<Record<string, unknown>> {
@@ -3,6 +3,7 @@ import { HttpError, badRequest } from "../../errors.js";
import { SessionAuthorityEpoch } from "./native-session-executor.js";
import type { PaperclipRunnerToolAuthority } from "./paperclip-runner-tool-authority.js";
import { executeRunnerApi } from "./runner-api-client.js";
import { TOOL_CALL_LOOP_REFUSAL_LIMIT, TOOL_CALL_LOOP_RUN_REFUSAL_LIMIT, ToolCallLoopError } from "./repeated-tool-failure-guard.js";
const context = { companyId: "company-a", issueId: "issue-a", issueIdentifier: "API-1", runId: "run-a", workMode: "standard" };
@@ -53,6 +54,39 @@ describe("repeated identical failing tool calls", () => {
expect(fetcher).not.toHaveBeenCalled();
});
it("after N refusals the guard raises a turn-stopping loop error", async () => {
const { authority, epoch } = epochWith(async () => { throw badRequest("body is required"); });
const call = (n: number) => ({ tool: "call_api", callId: `loop-${n}`, arguments: dropped });
await failure(epoch, call(1));
await failure(epoch, call(2));
for (let n = 1; n < TOOL_CALL_LOOP_REFUSAL_LIMIT; n++) {
const refused = await failure(epoch, call(2 + n));
expect(refused).not.toBeInstanceOf(ToolCallLoopError);
expect(refused?.message).toMatch(/^This call was not run/);
}
const stopped = await failure(epoch, call(2 + TOOL_CALL_LOOP_REFUSAL_LIMIT));
expect(stopped).toBeInstanceOf(ToolCallLoopError);
expect(stopped).toMatchObject({ code: "agent_tool_call_loop", tool: "call_api", refusals: TOOL_CALL_LOOP_REFUSAL_LIMIT,
argumentNames: ["operationId", "pathParams", "query", "responseText"] });
expect(authority.execute).toHaveBeenCalledTimes(2);
});
it("stops the turn once refusals across different calls reach the run limit", async () => {
const { epoch } = epochWith(async () => { throw badRequest("body is required"); });
let stopped: Error | null = null;
let refusals = 0;
for (let variant = 0; !stopped && variant < TOOL_CALL_LOOP_RUN_REFUSAL_LIMIT; variant++) {
const args = { ...dropped, pathParams: { id: `issue-${variant}` } };
for (let n = 0; n < 2 + TOOL_CALL_LOOP_REFUSAL_LIMIT - 1 && !stopped; n++) {
const error = await failure(epoch, { tool: "call_api", callId: `v${variant}-${n}`, arguments: args });
if (error instanceof ToolCallLoopError) stopped = error;
else if (error?.message.startsWith("This call was not run")) refusals++;
}
}
expect(stopped).toBeInstanceOf(ToolCallLoopError);
expect(refusals + 1).toBe(TOOL_CALL_LOOP_RUN_REFUSAL_LIMIT);
});
it("runs the call again once its arguments change", async () => {
const { authority, epoch } = epochWith(async call => {
if (!(call.arguments as { body?: unknown }).body) throw badRequest("body is required");
@@ -3,6 +3,16 @@ import { nativeSha256 } from "./canonical.js";
/** Identical failures after which the exact call is no longer run. */
export const REPEATED_TOOL_FAILURE_LIMIT = 2;
export const TOOL_CALL_LOOP_REFUSAL_LIMIT = 6;
export const TOOL_CALL_LOOP_RUN_REFUSAL_LIMIT = 20;
export const AGENT_TOOL_CALL_LOOP = "agent_tool_call_loop";
export function toolCallLoopContinuationKey(runId: string): string {
return `${AGENT_TOOL_CALL_LOOP}:${runId}`;
}
export const TOOL_CALL_LOOP_HINT = "The previous turn kept sending one tool call that Paperclip had already refused. "
+ "Do not send it again unchanged. Prefer a dedicated Paperclip tool, such as set_task_title, report_progress or write_document, over call_api. "
+ "If call_api is the only way, send every required argument, including body, as a top-level argument.";
const MAX_TRACKED_FAILURES = 64;
const MAX_RESPONSE_EXCERPT = 2_000;
@@ -14,8 +24,18 @@ type Failure = {
details?: unknown;
/** Returned by the route as an `ok: false` response rather than refused before sending. */
returned: boolean;
refusals?: number;
};
export class ToolCallLoopError extends HttpError {
readonly code = AGENT_TOOL_CALL_LOOP;
constructor(readonly tool: string, readonly refusals: number, readonly runRefusals: number,
readonly argumentNames: string[], status: number, message: string, details?: unknown) {
super(status, message, details);
this.name = "ToolCallLoopError";
}
}
/**
* Stops a model from resending the same rejected tool call. Some model hosts
* drop optional arguments, so the model can believe it fixed a call that
@@ -36,6 +56,7 @@ export class RepeatedToolFailureGuard {
// Identical calls a model sends in parallel run one after another, so each
// sees the failures before it. Different calls never wait on each other.
readonly #inFlight = new Map<string, Promise<unknown>>();
#runRefusals = 0;
run<T>(call: ToolCall, execute: () => Promise<T>): Promise<T> {
const key = callKey(call);
@@ -50,6 +71,14 @@ export class RepeatedToolFailureGuard {
async #run<T>(key: string, call: ToolCall, execute: () => Promise<T>): Promise<T> {
const prior = this.#failures.get(key);
if (prior && prior.count >= REPEATED_TOOL_FAILURE_LIMIT) {
prior.refusals = (prior.refusals ?? 0) + 1;
this.#runRefusals += 1;
if (prior.refusals >= TOOL_CALL_LOOP_REFUSAL_LIMIT || this.#runRefusals >= TOOL_CALL_LOOP_RUN_REFUSAL_LIMIT) {
throw new ToolCallLoopError(call.tool, prior.refusals, this.#runRefusals, argumentNames(call.arguments), prior.status,
`This call was not run, and Paperclip stopped this turn: ${call.tool} was refused ${prior.refusals} times in this run with these exact arguments. `
+ `${receivedArguments(call.arguments)} The task continues in a fresh session. ${TOOL_CALL_LOOP_HINT}`,
prior.details);
}
throw new HttpError(prior.status, `This call was not run: ${call.tool} already failed ${prior.count} times in this run with these exact arguments. `
+ `${receivedArguments(call.arguments)} ${prior.returned ? `The response each time was HTTP ${prior.status}: ` : "The error each time was: "}${prior.message} `
+ "Repeating it unchanged cannot succeed. Send it again only with the change that error asks for, or stop calling it and tell the user what blocked you.", prior.details);
@@ -131,7 +160,11 @@ function repeatedNote(count: number, call: ToolCall): string {
+ "Paperclip will not run this exact call again in this run. Change the arguments, or stop and tell the user what blocked you.";
}
function argumentNames(value: unknown): string[] {
return value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value).sort() : [];
}
function receivedArguments(value: unknown): string {
const names = value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value).sort() : [];
const names = argumentNames(value);
return `Arguments received each time: ${names.length ? names.join(", ") : "none"}.`;
}
@@ -151,6 +151,12 @@ describe("native status authority", () => {
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("treats only the authorized Board response_wake as passive and preserves governance", () => {
const passive = assessment({
reportedDisposition: "yielded",
@@ -240,6 +240,7 @@ export function arbitrateNativeStatus(input: {
reviewOwnerUserId?: string | null;
/** Review decisions own task state; a reviewer's finish report cannot override them. */
nativeReviewOutcome?: "resolved" | "pending" | "stale";
toolCallLoopContinuation?: boolean;
/**
* This run, as the configured participant, recorded the approval that
* completed the task's final execution-policy stage. That durable decision is
@@ -375,7 +376,7 @@ export function arbitrateNativeStatus(input: {
unblockDescriptor: null,
effects: [
{ kind: "release_checkout" },
...(input.nativeReviewOutcome === "pending" ? [{
...(input.nativeReviewOutcome === "pending" && !input.toolCallLoopContinuation ? [{
kind: "record_recovery" as const, cause: "native_review_unresolved",
nextAction: "The named reviewer must resolve the pending completion review or explain the concrete blocker. Do not restart the worker's assignment or create another review request.",
agentId: input.agentId,
@@ -1,4 +1,5 @@
import { notifyNativeStatusWakeWork } from "../deferred-execution-notifications.js";
import { toolCallLoopContinuationKey } from "./repeated-tool-failure-guard.js";
import { assertAgentInteraction } from "../agent-interaction-policy.js";
import { forbidden, HttpError } from "../../errors.js";
import { agentInteractionDeliveryDenial, agentWakeInteractionTexts, INTERACTION_DELIVERY_DENIED, withInteractionDeliveryOrigin } from "../agent-interaction-delivery.js";
@@ -795,7 +796,7 @@ async function materializeDecisionEffect(input: {
if (
effect.idempotencyKey.startsWith(
`connection-intent:tools:${input.runId}:`,
)
) || effect.idempotencyKey === toolCallLoopContinuationKey(input.runId)
) {
const [refresh] = await input.tx
.select({ id: agentWakeupRequests.id })