From 5e8f216709ef194bdad05a569bb6277da7341260 Mon Sep 17 00:00:00 2001 From: Vadym O Date: Fri, 13 Nov 2026 18:57:45 +0800 Subject: [PATCH] pinned helper refusal: name the refused helper, the pin, and one next step (AGE-2004) Co-Authored-By: Claude Code --- src/server/responses/pinned-helper-refusal.ts | 10 +++++++++ src/server/responses/request-sidecar-auth.ts | 6 ++--- src/server/responses/sidecar-execution.ts | 7 ++++-- .../server/agentradar-account-pin-e2e.test.ts | 4 ++-- tests/server/pinned-helper-refusal.test.ts | 22 +++++++++++++++++++ 5 files changed, 42 insertions(+), 7 deletions(-) create mode 100644 src/server/responses/pinned-helper-refusal.ts create mode 100644 tests/server/pinned-helper-refusal.test.ts diff --git a/src/server/responses/pinned-helper-refusal.ts b/src/server/responses/pinned-helper-refusal.ts new file mode 100644 index 00000000000..6db5d4ed51a --- /dev/null +++ b/src/server/responses/pinned-helper-refusal.ts @@ -0,0 +1,10 @@ +import { formatErrorResponse } from "../../bridge"; + +// AGE-2004: what an agent sees when its model pin blocks a helper model. Names the refused case, why, and the one next step. +const NOW = "Now: resend without it, or ask the account owner to turn on Fall back to other AI accounts."; +const refusal = (what: string, helper: string) => formatErrorResponse(400, "invalid_request_error", + `Request refused, nothing was sent: ${what}. This agent's model pin cannot use helper models, so no ${helper} was allowed to run. ${NOW}`); + +export const refuseImageOnPin = () => refusal("it contains an image and the pinned model cannot read images (resend without the image, describe it in words)", "vision helper"); +export const refuseWebSearchOnPin = () => refusal("it asks for the web_search tool and the pin is not a Claude account (resend without the web_search tool)", "search helper"); +export const refuseMediaBridgeOnPin = () => refusal("it needs the image or video bridge (image_gen/video_gen) (resend without image or video generation)", "image or video bridge"); diff --git a/src/server/responses/request-sidecar-auth.ts b/src/server/responses/request-sidecar-auth.ts index e9bd8d7ac11..131c97d4493 100644 --- a/src/server/responses/request-sidecar-auth.ts +++ b/src/server/responses/request-sidecar-auth.ts @@ -11,7 +11,7 @@ import { requiresVisionPreprocessing, stripImagesInPlace, } from "../../vision"; -import { formatErrorResponse } from "../../bridge"; +import { refuseImageOnPin, refuseWebSearchOnPin } from "./pinned-helper-refusal"; import { shouldResolveOpenAiWebSearchSidecar } from "../../web-search"; import { shouldResolveOpenAiPassthroughWebSearchBridge } from "../../web-search/passthrough-bridge"; import { @@ -65,7 +65,7 @@ export async function prepareResponsesSidecarAuth( && !exactAnthropicSourceReplay && (shouldResolveOpenAiWebSearchSidecar(config, parsed, isPassthrough) || shouldResolveOpenAiPassthroughWebSearchBridge(route.provider, parsed, isPassthrough)); - if (options.agentRadarAccount && (needsOpenAiVision || needsOpenAiSearch)) return formatErrorResponse(400, "invalid_request_error", "AgentRadar pinned requests cannot use helper models (vision, image or video bridge, or web search outside a Claude pin)"); + if (options.agentRadarAccount && (needsOpenAiVision || needsOpenAiSearch)) return needsOpenAiVision ? refuseImageOnPin() : refuseWebSearchOnPin(); if (needsOpenAiVision || needsOpenAiSearch) { try { const candidates = listOpenAiForwardSidecarCandidates(config); @@ -134,7 +134,7 @@ export async function prepareResponsesSidecarAuth( : planVisionSidecar(config, route.provider, route.modelId, parsed, openAiSidecar, { admission: options.admission, codexAuthPolicy: options.codexAuthPolicy, providerName: route.providerName, }); - if (options.agentRadarAccount && visionPlan) return formatErrorResponse(400, "invalid_request_error", "AgentRadar pinned requests cannot use helper models (vision, image or video bridge, or web search outside a Claude pin)"); + if (options.agentRadarAccount && visionPlan) return refuseImageOnPin(); const recordSidecarOutcome = openAiSidecar?.recordOutcome; let visionMutatedRequest = false; if (visionPlan) { diff --git a/src/server/responses/sidecar-execution.ts b/src/server/responses/sidecar-execution.ts index 4cca928cf4b..1ca62c71a30 100644 --- a/src/server/responses/sidecar-execution.ts +++ b/src/server/responses/sidecar-execution.ts @@ -5,6 +5,7 @@ import type { ResponsesSidecarAuth } from "./request-sidecar-auth"; import type { ResponsesEffects } from "./response-effects"; import type { ResponsesSendBudget } from "./request-send-budget"; import { formatErrorResponse } from "../../bridge"; +import { refuseMediaBridgeOnPin, refuseWebSearchOnPin } from "./pinned-helper-refusal"; import { planWebSearch, buildWebSearchTool, runWithWebSearch } from "../../web-search"; import { planImageBridge, @@ -161,8 +162,10 @@ export async function executeResponsesSidecars( : undefined; const imgPlan = canPlanSidecars ? await planImageBridge(config, parsed, route.provider) : undefined; const vidPlan = canPlanSidecars ? await planVideoBridge(config, parsed, route.provider) : undefined; - if (options.agentRadarAccount && ((wsPlan && !(options.agentRadarAccount.provider === "claude" && wsPlan.backend === "anthropic")) - || imgPlan || vidPlan)) return formatErrorResponse(400, "invalid_request_error", "AgentRadar pinned requests cannot use helper models (vision, image or video bridge, or web search outside a Claude pin)"); + if (options.agentRadarAccount) { + if (wsPlan && !(options.agentRadarAccount.provider === "claude" && wsPlan.backend === "anthropic")) return refuseWebSearchOnPin(); + if (imgPlan || vidPlan) return refuseMediaBridgeOnPin(); + } const canRunWebSearch = !!wsPlan && !transportState.adapter.runTurn; const rotateSidecarProviderOn429 = async ( retryAfter: string | null, diff --git a/tests/server/agentradar-account-pin-e2e.test.ts b/tests/server/agentradar-account-pin-e2e.test.ts index 04a7b96bdca..81df506d6b1 100644 --- a/tests/server/agentradar-account-pin-e2e.test.ts +++ b/tests/server/agentradar-account-pin-e2e.test.ts @@ -207,7 +207,7 @@ test("an AgentRadar account pin serves exactly its own stored account (pin.check assert.equal(r.status, 200, r.text); assert.ok(inference(r).length >= 2 && !inference(r).at(-1)!.image, `no vision describe planned: ${JSON.stringify(r.upstream)}`); r = await call(ocx, "/v1/messages", blindImage, { "anthropic-version": "2023-06-01", "x-api-key": "unused", ...pin("claude", "A") }); - assert.equal(r.status, 400, `${r.text}\n${JSON.stringify(r.upstream)}`); assert.deepEqual(inference(r), []); + assert.equal(r.status, 400, `${r.text}\n${JSON.stringify(r.upstream)}`); assert.match(r.text, /contains an image.*no vision helper was allowed to run/); assert.deepEqual(inference(r), []); // Surfaces that do not honour a pin refuse it instead of serving the active account. r = await call(ocx, "/v1/responses", { model: "anthropic/claude-stub", input: "hi" }, pin("claude", "A")); assert.equal(r.status, 400, r.text); assert.match(r.text, /only honoured on/); assert.deepEqual(inference(r), []); @@ -222,7 +222,7 @@ test("an AgentRadar account pin serves exactly its own stored account (pin.check assert.deepEqual([...new Set(tokens(r, "/v1/messages"))], ["Bearer atA"], JSON.stringify(r.upstream)); // Grok and Codex have no helper that can run on their pin: still refused. r = await call(ocx, "/v1/chat/completions", { model: "xai/grok-stub", messages: [{ role: "user", content: "hi" }], tools: [{ type: "web_search" }] }, pin("grok", "gA")); - assert.equal(r.status, 400, r.text); assert.match(r.text, /cannot use helper models/); assert.deepEqual(inference(r), []); + assert.equal(r.status, 400, r.text); assert.match(r.text, /web_search tool.*no search helper was allowed to run/); assert.deepEqual(inference(r), []); assert.equal((await accounts(ocx, "anthropic")).activeAccountId, "B", "pins never move the active account"); // Claude 429 on the pinned account: returned as is, cooldown recorded, no switch to B. diff --git a/tests/server/pinned-helper-refusal.test.ts b/tests/server/pinned-helper-refusal.test.ts new file mode 100644 index 00000000000..60b779a6bb3 --- /dev/null +++ b/tests/server/pinned-helper-refusal.test.ts @@ -0,0 +1,22 @@ +import { expect, test } from "bun:test"; +import { refuseImageOnPin, refuseMediaBridgeOnPin, refuseWebSearchOnPin } from "../../src/server/responses/pinned-helper-refusal"; + +// AGE-2004: each refused helper case says what was refused, that the pin blocks helpers, and the one next step. +const cases = [ + ["image on a text-only model", refuseImageOnPin, "it contains an image", "vision helper", "resend without the image"], + ["web_search on a non-Claude pin", refuseWebSearchOnPin, "it asks for the web_search tool", "search helper", "resend without the web_search tool"], + ["image or video bridge", refuseMediaBridgeOnPin, "it needs the image or video bridge", "image or video bridge", "resend without image or video generation"], +] as const; + +for (const [name, refuse, what, helper, cta] of cases) { + test(`pinned refusal: ${name}`, async () => { + const res = refuse(); + expect(res.status).toBe(400); + const text = (await res.json()).error.message as string; + expect(text).toContain("Request refused, nothing was sent"); + expect(text).toContain(what); + expect(text).toContain(`cannot use helper models, so no ${helper} was allowed to run`); + expect(text).toContain(cta); + expect(text).toContain("ask the account owner to turn on Fall back to other AI accounts"); + }); +}