Merge pull request #718 from code-yeongyu/fix/tool-schema-root-type-and-hard-error-classification

fix(ai): keep tool schemas rooted in an object and stop retrying request-shape rejections

Author: code-yeongyu

packages/ai/CHANGELOG.md

@@ -10,6 +10,10 @@
 
 ### Fixed
 
+- Kept tool parameter schemas rooted in an object type. A root `anyOf`/`oneOf`/`allOf` previously had its `type` hoisted into the branches and deleted, so OpenAI-compatible gateways rejected the request with `tools.function.parameters.type is required and must be "object"`, and the Moonshot root-union merge dropped the root's own properties entirely ([#718](https://github.com/code-yeongyu/senpi/pull/718)).
+- Sent the real parameters of root-union tool schemas to Anthropic. `convertTools` read top-level `properties` only, so plugin and MCP tools defined as a root union reached the model with no parameters at all ([#718](https://github.com/code-yeongyu/senpi/pull/718)).
+- Stopped retrying provider request-shape rejections. Gateways wrap these deterministic failures in 5xx envelopes, so they were classified transient and the identical invalid payload was replayed on the same model before fallback inherited it ([#718](https://github.com/code-yeongyu/senpi/pull/718)).
+
 ### Removed
 
 ## [2026.8.4-2] - 2026-08-04

packages/ai/src/api/anthropic-messages.ts

@@ -49,6 +49,7 @@ import {
 } from "../utils/server-fallback-receipt.ts";
 import { normalizeToolCallId } from "../utils/tool-call-id.ts";
 import { isForcedToolChoiceUnsupportedError, omitToolChoiceParam } from "../utils/tool-choice-fallback.ts";
+import { resolveRootObjectSchema } from "../utils/tool-schema-compat.ts";
 import { demotedToolCallText, demotedToolResultText } from "../utils/unavailable-tool-text.ts";
 import { sanitizeAnthropicToolPairs } from "./anthropic-tool-pairs.ts";
 import { resolveCloudflareBaseUrl } from "./cloudflare.ts";
@@ -2330,7 +2331,12 @@ function convertTools(
 
 	return tools.map((tool, index) => {
 		const strict = resolveJsonSchemaStrictSampling(tool, supportsStrictTools);
-		const schema = tool.parameters as { properties?: unknown; required?: string[] };
+		// A root union carries no top-level properties, so reading them directly
+		// would advertise the tool to the model as taking no arguments at all.
+		const schema = resolveRootObjectSchema(tool.parameters as Record<string, unknown>) as {
+			properties?: unknown;
+			required?: string[];
+		};
 		const legacyInputSchema = {
 			type: "object" as const,
 			properties: schema.properties ?? {},

packages/ai/src/changes.md

@@ -1,5 +1,49 @@
 # AI Source Changes
 
+## 2026-08-05 - Root-object tool schemas and request-shape error classification
+
+### What changed and why
+
+- `utils/tool-schema-compat.ts` no longer hoists a ROOT schema's `type` into its combiner
+  branches. A tool's root `parameters` must stay an object schema: OpenAI-compatible gateways
+  reject a typeless root with `tools.function.parameters.type is required and must be "object"`,
+  which is exactly how an Apitopia/Kimi turn died on 2026-08-04. `normalizeNode` now takes an
+  `isRoot` flag so branch-level hoisting (still correct below the root) is unchanged, and
+  `ensureRootObjectSchema` guarantees the emitted root is always `{"type":"object", ...}`.
+- `mergeRootObjectUnion` now merges the root's OWN `properties`/`required` with the branches'
+  instead of replacing them. It previously returned `{"properties":{},"type":"object"}` for a root
+  union that declared its properties at the root — silently sending a tool with zero parameters.
+  Untyped constraint-only branches (`{ required: [...] }` over root properties) are accepted, and
+  `required` keeps root entries plus only the names every branch shares.
+- Both flavors share one root guarantee: `normalizeToolParametersForMoonshot` is now the OpenAI
+  normalization plus annotation stripping, rather than a second, divergent root-merge path.
+- `api/anthropic-messages.ts` resolves a tool's root parameters through the shared
+  `resolveRootObjectSchema` before building `input_schema`. `convertTools` reads top-level
+  `properties`/`required` only, so a tool whose parameters are a root union arrived as
+  `{"properties":{},"required":[]}` — Claude was told the tool takes no arguments. senpi's own
+  `monitorSchema` was flattened in July to dodge this, but plugin and MCP tools ship root unions
+  and cannot be flattened by us, so the conversion itself has to handle them.
+- `utils/retry.ts` classifies provider request-shape rejections as NON-retryable, and
+  `NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN` is renamed `NON_RETRYABLE_PROVIDER_ERROR_PATTERN`
+  because it no longer covers only limits. Gateways wrap these deterministic rejections in 5xx
+  envelopes (`500 server_error: Invalid request: tools.function.parameters...`), so matching on
+  status text alone classified a permanent failure as transient: the identical payload was replayed
+  on the identical model until the turn died. The patterns are anchored on the
+  `tools.`/`functions.` request path so unrelated prose mentioning tools stays retryable.
+
+### Why this cannot be expressed externally
+
+- Wire-payload schema normalization runs inside the provider adapter, after extension payload
+  hooks, so no extension can repair the emitted tool schema. Retry classification is consumed by
+  the agent session's hard-error routing, which lives below any extension seam.
+
+### Expected merge conflict zones
+
+- MEDIUM: `utils/tool-schema-compat.ts` around root handling and `mergeRootObjectUnion`.
+- MEDIUM: `utils/retry.ts` in the non-retryable pattern list and its renamed constant.
+- LOW: `test/openai-completions-tool-schema-compat.test.ts`, `test/retry.test.ts`.
+
+
 ## 2026-08-03 - Hint-aware 429 retry-after propagation
 
 ### What changed and why

packages/ai/src/utils/retry.ts

@@ -4,7 +4,7 @@ function buildProviderErrorPattern(patterns: readonly string[]): RegExp {
 	return new RegExp(patterns.join("|"), "i");
 }
 
-const NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN = buildProviderErrorPattern([
+const NON_RETRYABLE_PROVIDER_ERROR_PATTERN = buildProviderErrorPattern([
 	// OpenCode Go/free-tier limits returned as 429 JSON error types by OpenCode's
 	// Zen API. These are subscription/account limits, not transient throttles.
 	"GoUsageLimitError",
@@ -28,6 +28,20 @@ const NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN = buildProviderErrorPattern([
 	// spend limit, so same-model retries can never recover it.
 	"credits_required",
 	"credits are required",
+
+	// Request-shape rejections: the provider refused the payload we built, not the
+	// work it describes. Gateways wrap these in whatever status they like — the
+	// observed Apitopia/Kimi case arrives as `500 server_error: Invalid request:
+	// tools.function.parameters.type is required and must be "object"` — so the
+	// status text alone would classify a permanent failure as transient. The same
+	// bytes are rejected on every attempt and on every fallback model, so retrying
+	// can only burn the turn. Anchored on the `tools[...]`/`functions[...]` request
+	// path so unrelated prose mentioning tools stays retryable.
+	"invalid request: tools\\.",
+	"invalid request: functions\\.",
+	"tools\\.[^ ]*function\\.parameters",
+	"tools\\.\\d+\\.function\\.parameters",
+	"invalid tool schema",
 ]);
 
 const RETRYABLE_PROVIDER_ERROR_PATTERN = buildProviderErrorPattern([
@@ -285,6 +299,6 @@ export function isProviderTimeoutError(message: AssistantMessage): boolean {
  */
 export function isRetryableErrorMessage(errorMessage: string): boolean {
 	if (!errorMessage) return false;
-	if (NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN.test(errorMessage)) return false;
+	if (NON_RETRYABLE_PROVIDER_ERROR_PATTERN.test(errorMessage)) return false;
 	return RETRYABLE_PROVIDER_ERROR_PATTERN.test(errorMessage);
 }

packages/ai/src/utils/tool-schema-compat.ts

@@ -90,19 +90,34 @@ function collapseConstUnion(node: Record<string, unknown>): void {
 	node.enum = values;
 }
 
+/**
+ * Collapse a root-level object union into one object schema.
+ *
+ * A tool's root parameters schema must be a plain `{"type":"object"}` schema:
+ * OpenAI-compatible gateways reject a root that only carries `anyOf`/`oneOf`
+ * with `tools.function.parameters.type is required and must be "object"`. The
+ * merge is intentionally lossy in the direction of permissiveness — branch
+ * exclusivity becomes advisory — but it must never lose a declared parameter,
+ * so the root's own `properties` and `required` are merged with the branches'
+ * rather than replaced by them.
+ */
 function mergeRootObjectUnion(schema: Record<string, unknown>): Record<string, unknown> | undefined {
 	const branches = Array.isArray(schema.anyOf) ? schema.anyOf : Array.isArray(schema.oneOf) ? schema.oneOf : undefined;
 	if (branches === undefined || branches.length === 0) return undefined;
+	if (schema.properties !== undefined && !isJsonObject(schema.properties)) return undefined;
+	if (schema.required !== undefined && !Array.isArray(schema.required)) return undefined;
 
 	const objectBranches: Record<string, unknown>[] = [];
 	for (const branch of branches) {
-		if (!isJsonObject(branch) || branch.type !== "object") return undefined;
+		// An untyped branch is a constraint-only variant (e.g. `{ required: [...] }`)
+		// over the root's own properties, so it merges like an object branch.
+		if (!isJsonObject(branch) || (branch.type !== "object" && branch.type !== undefined)) return undefined;
 		if (branch.properties !== undefined && !isJsonObject(branch.properties)) return undefined;
 		if (branch.required !== undefined && !Array.isArray(branch.required)) return undefined;
 		objectBranches.push(branch);
 	}
 
-	const properties: Record<string, unknown> = {};
+	const properties: Record<string, unknown> = isJsonObject(schema.properties) ? { ...schema.properties } : {};
 	for (const branch of objectBranches) {
 		if (!isJsonObject(branch.properties)) continue;
 		for (const [name, propertySchema] of Object.entries(branch.properties)) {
@@ -114,29 +129,36 @@ function mergeRootObjectUnion(schema: Record<string, unknown>): Record<string, u
 		}
 	}
 
-	const firstRequired = objectBranches[0]?.required;
-	let commonRequired = Array.isArray(firstRequired)
-		? firstRequired.filter((name): name is string => typeof name === "string")
+	// Only names required by EVERY branch stay required; a name required by one
+	// branch alone would reject payloads the union accepts. Root-level `required`
+	// applies to all branches, so it is unioned back in.
+	const rootRequired = Array.isArray(schema.required)
+		? schema.required.filter((name): name is string => typeof name === "string")
 		: [];
-	for (const branch of objectBranches.slice(1)) {
-		const branchRequired = new Set(
-			Array.isArray(branch.required)
-				? branch.required.filter((name): name is string => typeof name === "string")
-				: [],
-		);
-		commonRequired = commonRequired.filter((name) => branchRequired.has(name));
-	}
+	const branchRequiredSets = objectBranches.map(
+		(branch) =>
+			new Set(
+				Array.isArray(branch.required)
+					? branch.required.filter((name): name is string => typeof name === "string")
+					: [],
+			),
+	);
+	const firstBranchRequired = branchRequiredSets[0];
+	const commonBranchRequired = firstBranchRequired
+		? [...firstBranchRequired].filter((name) => branchRequiredSets.every((names) => names.has(name)))
+		: [];
+	const required = [...new Set([...rootRequired, ...commonBranchRequired])];
 
 	const { anyOf: _anyOf, oneOf: _oneOf, ...rest } = schema;
 	return {
 		...rest,
 		type: "object",
 		properties,
-		...(commonRequired.length > 0 ? { required: commonRequired } : {}),
+		...(required.length > 0 ? { required } : {}),
 	};
 }
 
-function normalizeNode(node: unknown): unknown {
+function normalizeNode(node: unknown, isRoot = false): unknown {
 	if (Array.isArray(node)) {
 		return node.map((child) => normalizeNode(child));
 	}
@@ -146,7 +168,9 @@ function normalizeNode(node: unknown): unknown {
 	}
 
 	const hasCombiner = COMBINER_KEYS.some((key) => Array.isArray(node[key]));
-	if (hasCombiner) {
+	// The root of a tool's parameters must keep `type: "object"`; hoisting it into
+	// the branches leaves a typeless root that gateways reject outright.
+	if (hasCombiner && !isRoot) {
 		moveTypeIntoCombinerBranches(node);
 	}
 
@@ -183,16 +207,46 @@ function normalizeNode(node: unknown): unknown {
  * for OpenAI-compatible Chat Completions backends.
  */
 export function normalizeToolParametersForOpenAICompat(schema: Record<string, unknown>): Record<string, unknown> {
-	return normalizeNode(structuredClone(schema)) as Record<string, unknown>;
+	const normalized = normalizeNode(structuredClone(schema), true) as Record<string, unknown>;
+	return ensureRootObjectSchema(normalized);
+}
+
+/**
+ * Guarantee the wire shape every OpenAI-compatible backend requires for tool
+ * parameters: a root object schema. A root union of object shapes is merged into
+ * one object schema; a root that merely lost its `type` gets it restored.
+ *
+ * A root whose branches are not object shapes is left alone: forcing
+ * `type: "object"` onto a scalar union would assert something the schema
+ * contradicts, which is worse than the missing keyword. Tool parameters are
+ * objects in practice, so this only guards against corrupting an exotic schema.
+ */
+function ensureRootObjectSchema(schema: Record<string, unknown>): Record<string, unknown> {
+	const merged = mergeRootObjectUnion(schema);
+	if (merged) return merged;
+	if (schema.type !== undefined) return schema;
+	const hasCombiner = COMBINER_KEYS.some((key) => Array.isArray(schema[key]));
+	if (hasCombiner) return schema;
+	return { ...schema, type: "object" };
 }
 
 /**
  * Moonshot-flavored JSON Schema subset: in addition to the OpenAI-compatible
  * normalization, drop non-structural annotation keywords that Moonshot rejects.
  */
 export function normalizeToolParametersForMoonshot(schema: Record<string, unknown>): Record<string, unknown> {
-	const normalized = normalizeToolParametersForOpenAICompat(schema);
-	return stripMoonshotAnnotations(mergeRootObjectUnion(normalized) ?? normalized);
+	return stripMoonshotAnnotations(normalizeToolParametersForOpenAICompat(schema));
+}
+
+/**
+ * Resolve a tool's root parameters into a single object schema, without the
+ * OpenAI-specific rewrites. Wire formats that read a tool's parameters from
+ * top-level `properties`/`required` need this: a root union carries neither, so
+ * they would otherwise describe the tool to the model as taking no arguments.
+ * Schemas that are already plain objects are returned untouched.
+ */
+export function resolveRootObjectSchema(schema: Record<string, unknown>): Record<string, unknown> {
+	return mergeRootObjectUnion(structuredClone(schema)) ?? schema;
 }
 
 function stripMoonshotAnnotations(node: unknown): Record<string, unknown> {

packages/ai/test/anthropic-root-union-tool-schema.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getModel } from "../src/compat.ts";
+import { streamAnthropic } from "../src/providers/anthropic.ts";
+import type { Context, Model } from "../src/types.ts";
+
+interface AnthropicToolPayload {
+	tools?: Array<{ name: string; input_schema: { properties?: Record<string, unknown>; required?: string[] } }>;
+}
+
+interface AnthropicMockState {
+	createParams: AnthropicToolPayload | undefined;
+}
+
+const mockState = vi.hoisted<AnthropicMockState>(() => ({ createParams: undefined }));
+
+vi.mock("@anthropic-ai/sdk", () => {
+	function createSseResponse(): Response {
+		const body = [
+			`event: message_start\ndata: ${JSON.stringify({
+				type: "message_start",
+				message: { id: "msg_test", usage: { input_tokens: 10, output_tokens: 0 } },
+			})}\n`,
+			`event: message_delta\ndata: ${JSON.stringify({
+				type: "message_delta",
+				delta: { stop_reason: "end_turn" },
+				usage: { output_tokens: 5 },
+			})}\n`,
+			`event: message_stop\ndata: ${JSON.stringify({ type: "message_stop" })}\n`,
+		].join("\n");
+
+		return new Response(body, { status: 200, headers: { "content-type": "text/event-stream" } });
+	}
+
+	class FakeAnthropic {
+		messages = {
+			create: (params: AnthropicToolPayload) => {
+				mockState.createParams = params;
+				return { asResponse: async () => createSseResponse() };
+			},
+		};
+	}
+
+	return { default: FakeAnthropic };
+});
+
+// Plugin and MCP tools ship root unions routinely and senpi cannot flatten a
+// schema it does not own. The Anthropic conversion reads top-level properties
+// only, so these arrived as {"properties":{},"required":[]}: a parameterless tool.
+const rootUnionContext: Context = {
+	messages: [{ role: "user", content: "Hello", timestamp: Date.now() }],
+	tools: [
+		{
+			name: "monitor",
+			description: "Subscribe to a command's output",
+			parameters: {
+				anyOf: [
+					{
+						type: "object",
+						properties: { command: { type: "string" }, description: { type: "string" } },
+						required: ["command", "description"],
+					},
+					{
+						type: "object",
+						properties: { bash_id: { type: "string" } },
+						required: ["bash_id"],
+					},
+				],
+			},
+		},
+	],
+};
+
+async function capturePayload(model: Model<"anthropic-messages">, context: Context): Promise<AnthropicToolPayload> {
+	await streamAnthropic({ ...model, baseUrl: "http://127.0.0.1:9" }, context, { apiKey: "fake-key" }).result();
+	if (!mockState.createParams) throw new Error("Expected payload to be captured");
+	return mockState.createParams;
+}
+
+describe("Anthropic root-union tool schemas", () => {
+	beforeEach(() => {
+		mockState.createParams = undefined;
+	});
+
+	it("sends the union's parameters instead of an empty schema", async () => {
+		const payload = await capturePayload(getModel("anthropic", "claude-fable-5"), rootUnionContext);
+
+		const schema = payload.tools?.[0]?.input_schema;
+		expect(Object.keys(schema?.properties ?? {}).sort()).toEqual(["bash_id", "command", "description"]);
+	});
+
+	it("requires only what every branch of the union requires", async () => {
+		const payload = await capturePayload(getModel("anthropic", "claude-fable-5"), rootUnionContext);
+
+		// `command` is required by one branch only, so forcing it globally would
+		// reject calls the union accepts.
+		expect(payload.tools?.[0]?.input_schema.required).toEqual([]);
+	});
+
+	it("leaves an ordinary object schema untouched", async () => {
+		const payload = await capturePayload(getModel("anthropic", "claude-fable-5"), {
+			messages: [{ role: "user", content: "Hello", timestamp: Date.now() }],
+			tools: [
+				{
+					name: "get_weather",
+					description: "Get the weather",
+					parameters: {
+						type: "object",
+						properties: { city: { type: "string" } },
+						required: ["city"],
+					},
+				},
+			],
+		});
+
+		expect(payload.tools?.[0]?.input_schema.properties).toEqual({ city: { type: "string" } });
+		expect(payload.tools?.[0]?.input_schema.required).toEqual(["city"]);
+	});
+});