Skip to content

Commit 0631ca4

Browse files
authored
fix: repair anyOf tool schemas rejected by the Kimi wire (#14)
## Related Issue No existing issue — the problem is described below. This is a reproducible bug fix with a focused diff. ## Problem Every request to a Kimi / Moonshot model fails before the model runs: ``` 400 tools.function.parameters is not a valid moonshot flavored json schema, details: <At path 'root': when using anyOf, type should be defined in anyOf items instead of the parent schema> ``` The wire validator refuses a tool schema that uses `anyOf` as a *refinement* of the node it sits on. Two rules are involved: - `type` may not appear next to `anyOf` on the same node. - No validation keyword (`properties`, `items`, `additionalProperties`, …) may appear on both a node and one of its `anyOf` branches. Both are legal standard JSON Schema, so schemas that work on every other provider are rejected here. `TaskStop` trips them: it adds a hand-written `anyOf: [{ required: ['task_id'] }, { required: ['shell_id'] }]` on top of an object schema that already declares `type` and `properties`. Because tool definitions are sent with every request, a single offending tool takes down the whole session. `normalizePythinkerToolSchema` already existed for exactly this class of provider-compatibility repair, but it only visited *nested* property schemas and deliberately skipped the root, so it never saw the offending node. ## What changed The repair lives in the provider's schema normalizer rather than in `TaskStop`, so MCP- and plugin-contributed schemas are covered by the same pass — this shape is common enough that several other clients have hit it independently. **Nested nodes — distribute.** A node's own constraints are pushed down into each `anyOf` branch, and branches that already declare a keyword keep their own (narrower) value. This is lossless: `P ∧ (B₁ ∨ B₂)` and `(P ∧ B₁) ∨ (P ∧ B₂)` accept exactly the same instances. Sibling combinators (`allOf` / `oneOf` / `not` / `if`) are left in place — the validator does not read them, so moving them would only churn the schema. **Root — fold away.** The root cannot use the branch form, because a tool's parameters must be a plain object: the wire separately requires `parameters.type == "object"`, which cannot coexist with a root `anyOf`. The two constraints are jointly unsatisfiable, so the root's `anyOf` is dropped. That only ever widens what is accepted, and a root `anyOf` is in practice a "one of these fields is required" hint that the tool re-checks at run time (`TaskStop` already returns `Missing required parameter: task_id`). Branch properties are merged into the root first, so a schema that kept its arguments inside the branches does not silently lose them. ## Verification Rather than asserting against an assumed reading of the spec, every schema was replayed through the provider's own validator: - Reproduced the original 400 against the live endpoint, then confirmed it is gone. - Replayed **all 36 built-in tool schemas and all 70 tool schemas from five connected MCP servers** through the normalizer and into the provider's validator: 106 accepted, 0 rejected. Before the change, `TaskStop` was the single failure. - Full `kosong` suite passes (1185 tests); `typecheck` clean. - Each of the two new code paths was individually disabled to confirm the new tests actually fail without it. ## Checklist - [x] I have read the [CONTRIBUTING](https://github.com/Pythoughts-labs/pythinker-code/blob/main/CONTRIBUTING.md) document. - [x] I have linked a related issue, or explained the problem above. - [x] I have added tests that prove my feature works. - [x] Ran `gen-changesets` skill, or this PR needs no changeset. - [x] Ran `gen-docs` skill, or this PR needs no doc update — no user-facing behavior or CLI surface changes. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved compatibility with Kimi and Moonshot models when tools use combined schema types. * Fixed invalid tool schema errors involving `anyOf`, `oneOf`, and `allOf` combinations. * Improved normalization of nested and object-based tool schemas while preserving metadata, constraints, references, and definitions. * Reduced duplicate schema alternatives and improved handling of required fields. * **Tests** * Added comprehensive coverage for root and nested schema normalization, cyclic definitions, and combinators. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 5ec7157 commit 0631ca4

3 files changed

Lines changed: 388 additions & 31 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pythoughts/pythinker-code": patch
3+
---
4+
5+
Fix Kimi and Moonshot models rejecting every request with an invalid tool schema error when a tool declares `anyOf` alongside its own type or properties.

‎packages/kosong/src/providers/pythinker-schema.ts‎

Lines changed: 183 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,8 @@ const NUMERIC_STRUCTURE_KEYS = new Set([
117117
* it resolves local refs, preserves combinator nodes, infers obvious
118118
* scalar/object/array types, and falls back to `string` only for nested
119119
* typeless property schemas. The root schema object is treated as a container
120-
* and is not itself normalized.
120+
* and is not itself type-normalized, with one exception: an `anyOf` at the root
121+
* is folded away, because a tool's parameters must be a plain object.
121122
*/
122123
export function normalizePythinkerToolSchema(schema: Record<string, unknown>): Record<string, unknown> {
123124
return ensurePythinkerPropertyTypes(derefJsonSchema(schema));
@@ -128,10 +129,84 @@ function ensurePythinkerPropertyTypes(schema: Record<string, unknown>): Record<s
128129
if (!isRecord(normalized)) {
129130
throw new Error('JSON Schema root must normalize to an object.');
130131
}
132+
// Fold the root's `anyOf` away before recursing; once it is gone the generic
133+
// per-node distribution below sees nothing to do at the root.
134+
foldRootAnyOf(normalized);
131135
recurseSchema(normalized);
132136
return normalized;
133137
}
134138

139+
/**
140+
* Remove an `anyOf` sitting at the root of a tool's parameter schema.
141+
*
142+
* A tool's parameters must be an object, so the root cannot use the branch form
143+
* that {@link distributeAnyOfParentKeywords} produces for every other node: the
144+
* wire requires `type: "object"` there, and rejects `type` next to `anyOf`. The
145+
* two constraints are jointly unsatisfiable, so the root's `anyOf` is dropped.
146+
*
147+
* Dropping only ever widens what the schema accepts — a root `anyOf` is almost
148+
* always a "one of these fields is required" hint, which the tool re-checks when
149+
* it runs. Branch properties are folded into the root first, so a schema that
150+
* kept its arguments inside the branches does not lose them.
151+
*/
152+
function foldRootAnyOf(root: Record<string, unknown>): void {
153+
const branches = root['anyOf'];
154+
if (!Array.isArray(branches) || !branches.every(isRecord)) {
155+
return;
156+
}
157+
delete root['anyOf'];
158+
159+
const rootProperties = root['properties'];
160+
const alternativesByName = new Map<string, unknown[]>();
161+
if (isRecord(rootProperties)) {
162+
for (const [name, property] of Object.entries(rootProperties)) {
163+
alternativesByName.set(name, [cloneJsonValue(property)]);
164+
}
165+
}
166+
for (const branch of branches) {
167+
const branchProperties = branch['properties'];
168+
if (!isRecord(branchProperties)) continue;
169+
for (const [name, property] of Object.entries(branchProperties)) {
170+
addRootPropertyAlternative(alternativesByName, name, property);
171+
}
172+
}
173+
174+
if (alternativesByName.size > 0) {
175+
const merged: Record<string, unknown> = {};
176+
for (const [name, alternatives] of alternativesByName) {
177+
merged[name] = alternatives.length === 1 ? alternatives[0] : { anyOf: alternatives };
178+
}
179+
root['properties'] = merged;
180+
}
181+
root['type'] = 'object';
182+
}
183+
184+
/**
185+
* Record one branch's schema for a merged root property.
186+
*
187+
* Root `anyOf` branches are alternatives, so two branches declaring the same
188+
* property with different schemas (e.g. `value` as a string in one branch, an
189+
* integer in another) must both stay representable — keeping only the first
190+
* one seen would silently narrow what the tool actually accepts. Identical
191+
* schemas collapse to one; differing schemas fold into an `anyOf` on the
192+
* merged property.
193+
*/
194+
function addRootPropertyAlternative(
195+
alternativesByName: Map<string, unknown[]>,
196+
name: string,
197+
property: unknown,
198+
): void {
199+
const cloned = cloneJsonValue(property);
200+
const alternatives = alternativesByName.get(name);
201+
if (!alternatives) {
202+
alternativesByName.set(name, [cloned]);
203+
return;
204+
}
205+
if (!alternatives.some((existing) => deepEqualJson(existing, cloned))) {
206+
alternatives.push(cloned);
207+
}
208+
}
209+
135210
function hasUnresolvedDefinitionRef(node: unknown, bucketKey: string): boolean {
136211
if (Array.isArray(node)) {
137212
return node.some((child) => hasUnresolvedDefinitionRef(child, bucketKey));
@@ -252,9 +327,101 @@ function recurseSchema(node: unknown): void {
252327
return;
253328
}
254329

330+
distributeAnyOfParentKeywords(node);
255331
visitChildSchemas(node, normalizeProperty);
256332
}
257333

334+
/**
335+
* Keywords that may stay on a schema node that also carries `anyOf`.
336+
*
337+
* Everything else is a validation keyword the wire validator refuses to see on
338+
* both sides of an `anyOf`. Sibling combinators are left alone because the
339+
* validator does not read them at all, so relocating them would only churn the
340+
* schema. `$defs` / `definitions` stay put because cyclic `$ref` pointers
341+
* resolve against the root, and `$ref` stays because duplicating a cyclic
342+
* reference into every branch changes its meaning.
343+
*/
344+
const ANYOF_PARENT_KEEP_KEYS = new Set([
345+
'$comment',
346+
'$defs',
347+
'$ref',
348+
'$schema',
349+
'allOf',
350+
'anyOf',
351+
'default',
352+
'definitions',
353+
'description',
354+
'else',
355+
'if',
356+
'not',
357+
'oneOf',
358+
'then',
359+
'title',
360+
]);
361+
362+
/**
363+
* Push a node's own constraints down into its `anyOf` branches.
364+
*
365+
* Pythoughts's tool validator rejects `anyOf` used as a refinement of its parent:
366+
* `type` must be declared inside the branches rather than beside them, and no
367+
* other validation keyword (`properties`, `items`, `additionalProperties`, …)
368+
* may appear on both the parent and a branch. Standard JSON Schema allows both,
369+
* so schemas that are perfectly valid elsewhere are rejected on this wire.
370+
*
371+
* Distributing is lossless: `P ∧ (B₁ ∨ B₂)` and `(P ∧ B₁) ∨ (P ∧ B₂)` accept
372+
* exactly the same instances — *if* a branch that already declares the same
373+
* keyword is merged conjunctively with the parent's value rather than simply
374+
* overriding it. `required` is the one keyword this function merges that way
375+
* (parent and branch field lists are unioned, since both are actually
376+
* required). Every other overlapping keyword still keeps the branch's own
377+
* value: a full conjunctive merge for arbitrary keywords (`properties`,
378+
* `items`, …) is out of scope for this compatibility normalizer.
379+
*/
380+
function distributeAnyOfParentKeywords(node: Record<string, unknown>): void {
381+
const branches = node['anyOf'];
382+
if (!Array.isArray(branches) || branches.length === 0 || !branches.every(isRecord)) {
383+
return;
384+
}
385+
386+
const inherited = Object.keys(node).filter((key) => !ANYOF_PARENT_KEEP_KEYS.has(key));
387+
if (inherited.length === 0) {
388+
return;
389+
}
390+
391+
for (const branch of branches) {
392+
for (const key of inherited) {
393+
if (!hasOwn(branch, key)) {
394+
branch[key] = cloneJsonValue(node[key]);
395+
} else if (key === 'required') {
396+
branch[key] = mergeRequired(node[key], branch[key]);
397+
}
398+
}
399+
}
400+
for (const key of inherited) {
401+
delete node[key];
402+
}
403+
}
404+
405+
/**
406+
* Union two `required` field lists.
407+
*
408+
* A parent's `required` and a branch's own `required` are both mandatory —
409+
* dropping the parent's list when the branch already has one would silently
410+
* accept objects missing a field the parent demanded.
411+
*/
412+
function mergeRequired(parentValue: unknown, branchValue: unknown): unknown {
413+
if (!Array.isArray(parentValue) || !Array.isArray(branchValue)) {
414+
return branchValue;
415+
}
416+
const merged = [...branchValue];
417+
for (const name of parentValue) {
418+
if (!merged.includes(name)) {
419+
merged.push(name);
420+
}
421+
}
422+
return merged;
423+
}
424+
258425
function visitChildSchemas(node: Record<string, unknown>, visit: (schema: unknown) => void): void {
259426
for (const { key, kind } of CHILD_SCHEMA_SLOTS) {
260427
const value = node[key];
@@ -466,6 +633,21 @@ function isRecord(value: unknown): value is Record<string, unknown> {
466633
return typeof value === 'object' && value !== null && !Array.isArray(value);
467634
}
468635

636+
function deepEqualJson(a: unknown, b: unknown): boolean {
637+
if (a === b) {
638+
return true;
639+
}
640+
if (Array.isArray(a) && Array.isArray(b)) {
641+
return a.length === b.length && a.every((item, index) => deepEqualJson(item, b[index]));
642+
}
643+
if (isRecord(a) && isRecord(b)) {
644+
const aKeys = Object.keys(a);
645+
const bKeys = Object.keys(b);
646+
return aKeys.length === bKeys.length && aKeys.every((key) => hasOwn(b, key) && deepEqualJson(a[key], b[key]));
647+
}
648+
return false;
649+
}
650+
469651
function hasOwn(obj: Record<string, unknown>, key: string): boolean {
470652
return Object.prototype.hasOwnProperty.call(obj, key);
471653
}

0 commit comments

Comments
 (0)