@namzu/sdk 5.1.0 → 5.2.0

package/src/provider/__tests__/strict-schema.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+
+import { getBuiltinTools } from '../../tools/builtins/index.js'
+import { assertStrictSchema, findStrictSchemaViolations } from '../strict-schema.js'
+
+/**
+ * Strict tool input validates against a SUBSET of JSON Schema, and a keyword
+ * outside that subset is not degraded — the vendor rejects the entire request,
+ * so one unexpressible field in one tool takes down every tool in the call and
+ * the turn dies before producing a token.
+ *
+ * That shipped. The edit tool declared its integer-or-`"end"` field with
+ * `oneOf`, which is outside the subset while the equivalent `anyOf` is inside
+ * it, and the driver marked the tool strict without asking whether the schema
+ * it was vouching for could be said in that dialect.
+ *
+ * Measured against the live API:
+ *
+ * | body                   | result   |
+ * |------------------------|----------|
+ * | strict: true  + oneOf  | 400      |
+ * | strict: false + oneOf  | accepted |
+ * | strict: true  + anyOf  | accepted |
+ *
+ * The middle row is why nothing caught it. Neither half is wrong alone — the
+ * schema is valid JSON Schema, and turning strict on is correct policy — so no
+ * test of either one fails. Only the pairing does, and the pairing had no
+ * owner. The sweep below is that owner.
+ */
+
+describe('every tool that asks for strict validation can be expressed strictly', () => {
+	// The regression test that matters. Checking only the tool that broke
+	// would leave the next one to be found in production, which is how this
+	// one was found.
+	it.each(
+		getBuiltinTools()
+			.filter((t) => t.enforceModelInput)
+			.map((t) => [t.name, t] as const),
+	)('%s', (name, tool) => {
+		const violations = findStrictSchemaViolations(tool.modelInputSchema)
+		expect(violations, violations.map((v) => `${name}.${v.path}: ${v.remedy}`).join('\n')).toEqual(
+			[],
+		)
+	})
+
+	it('found at least one tool to check', () => {
+		// Guards the sweep itself: a filter that matches nothing passes
+		// vacuously, and a rename of `enforceModelInput` would silently turn
+		// this whole file into a no-op.
+		expect(getBuiltinTools().filter((t) => t.enforceModelInput).length).toBeGreaterThan(0)
+	})
+})
+
+describe('the violation report names the exact path', () => {
+	it('points at the keyword inside a nested property', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				insertLine: { oneOf: [{ type: 'integer' }, { const: 'end' }] },
+			},
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([
+			{
+				path: 'properties.insertLine.oneOf',
+				keyword: 'oneOf',
+				remedy: 'use `anyOf` — for disjoint branches the two are equivalent',
+			},
+		])
+	})
+
+	it('accepts the anyOf spelling of the same union', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				insertLine: { anyOf: [{ type: 'integer' }, { const: 'end' }] },
+			},
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([])
+	})
+
+	it('reports numeric and string bounds, which are also outside the subset', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				n: { type: 'integer', minimum: 0 },
+				s: { type: 'string', maxLength: 10 },
+			},
+		}
+
+		expect(
+			findStrictSchemaViolations(schema)
+				.map((v) => v.keyword)
+				.sort(),
+		).toEqual(['maxLength', 'minimum'])
+	})
+
+	it('admits additionalProperties only as false', () => {
+		expect(findStrictSchemaViolations({ additionalProperties: false })).toEqual([])
+		expect(findStrictSchemaViolations({ additionalProperties: { type: 'string' } })).toHaveLength(1)
+	})
+
+	it('walks into arrays of subschemas', () => {
+		const schema = { anyOf: [{ type: 'string' }, { not: { type: 'null' } }] }
+
+		expect(findStrictSchemaViolations(schema)[0]?.path).toBe('anyOf[1].not')
+	})
+
+	it('leaves ordinary annotations alone', () => {
+		const schema = {
+			type: 'object',
+			description: 'a tool',
+			properties: { a: { type: 'string', description: 'x', enum: ['y'] } },
+			required: ['a'],
+			additionalProperties: false,
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([])
+	})
+})
+
+describe('assertStrictSchema refuses rather than letting the request go', () => {
+	it('throws naming the tool, the path and the fix', () => {
+		expect(() => assertStrictSchema('edit', { properties: { insertLine: { oneOf: [] } } })).toThrow(
+			/edit\.properties\.insertLine\.oneOf/,
+		)
+	})
+
+	it('says nothing about a schema that is expressible', () => {
+		expect(() => assertStrictSchema('edit', { type: 'object' })).not.toThrow()
+	})
+})

package/src/provider/model-version.ts

@@ -0,0 +1,98 @@
+/**
+ * Parse a versioned model id, given the vocabulary that names one.
+ *
+ * Several vendors spell an id the same way — a product segment, a family, a
+ * major version, sometimes a minor, and sometimes an 8-digit release date:
+ *
+ * ```
+ * <product>-<family>-<major>[-<minor>][-<YYYYMMDD>]
+ * ```
+ *
+ * The SHAPE is general and lives here; the vocabulary is not, and is supplied
+ * by the driver that knows it. That split is deliberate: a driver package
+ * exists to speak one service's dialect, and the kernel has no business
+ * knowing whose ids these are.
+ *
+ * It exists at all because three drivers had each written the same matcher and
+ * all three had the same defect: the minor-version group was `\d+`, which
+ * happily swallowed the date. An id naming no minor therefore parsed as
+ * `major.<the date>` and compared as enormously NEWER than one that does, so
+ * every capability gate keyed on `minor >= n` inverted for exactly those ids —
+ * a model was told it supported features it does not.
+ *
+ * A real minor version is one to three digits; a date is exactly eight.
+ * Bounding the group is what stops it reaching across the separator, and the
+ * expression then backtracks into leaving the minor absent so the date suffix
+ * can match where it belongs.
+ */
+
+export interface ModelVersion {
+	readonly family: string
+	readonly major: number
+	/** `0` when the id names no minor — a bare major is `<major>.0`. */
+	readonly minor: number
+}
+
+/**
+ * What a driver must say to have its ids parsed.
+ *
+ * Every field is a wire value the driver already carries. Passing them in
+ * rather than hard-coding them is what keeps this module free of any one
+ * service's names.
+ */
+export interface ModelIdGrammar {
+	/** The product segment an id begins with. */
+	readonly product: string
+	/** The family segment that follows it. */
+	readonly families: readonly string[]
+	/** An optional routing segment a gateway may prepend, including its slash. */
+	readonly routingPrefix?: string
+}
+
+const quoteMeta = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+function expressionFor(grammar: ModelIdGrammar): RegExp {
+	const routing = grammar.routingPrefix ? `(?:${quoteMeta(grammar.routingPrefix)})?` : ''
+	// `.map(quoteMeta)` and not `.map(escape)`: the latter resolves to the
+	// global, deprecated `escape()`, which percent-encodes instead of escaping
+	// regex metacharacters — and would pass every test here, because no family
+	// name contains a character either function changes.
+	const families = grammar.families.map((f) => quoteMeta(f)).join('|')
+	// `\d{1,3}` on the minor, not `\d+`. That single bound is the whole fix.
+	return new RegExp(
+		`^${routing}${quoteMeta(grammar.product)}-(${families})-(\\d+)(?:[-_.](\\d{1,3}))?(?:-\\d{8})?$`,
+	)
+}
+
+/** `undefined` for anything the grammar does not describe — never a guess. */
+export function parseVersionedModelId(
+	id: string,
+	grammar: ModelIdGrammar,
+): ModelVersion | undefined {
+	const match = id.toLowerCase().match(expressionFor(grammar))
+	if (!match) return undefined
+	return {
+		family: match[1] as string,
+		major: Number(match[2]),
+		minor: match[3] === undefined ? 0 : Number(match[3]),
+	}
+}
+
+/**
+ * Whether an id names a version at or above `major.minor`.
+ *
+ * The comparison every caller was writing by hand. An id this cannot parse
+ * returns `false`: a capability gate must not open for a name it does not
+ * understand, which is the fail-safe reading and the one those callers' own
+ * comments already claimed.
+ */
+export function modelVersionAtLeast(
+	id: string,
+	grammar: ModelIdGrammar,
+	major: number,
+	minor: number,
+): boolean {
+	const version = parseVersionedModelId(id, grammar)
+	if (!version) return false
+	return version.major > major || (version.major === major && version.minor >= minor)
+}

package/src/provider/strict-schema.ts

@@ -0,0 +1,125 @@
+/**
+ * Which JSON Schema a driver may mark as strictly validated.
+ *
+ * Strict tool input is not "JSON Schema, enforced" — it is a SUBSET of JSON
+ * Schema, and a keyword outside that subset does not degrade. The vendor
+ * rejects the entire request, so one unexpressible field in one tool takes down
+ * every tool in the call and the turn dies before a single token is produced.
+ *
+ * This exists because that happened. A tool declared its integer-or-`"end"`
+ * field as `oneOf`, which is outside the subset while its synonym `anyOf` is
+ * inside it, and the driver marked the tool strict without ever asking whether
+ * the schema it was vouching for could be said in that dialect. Measured
+ * against the live API: strict + `oneOf` is a 400, strict + `anyOf` is
+ * accepted, and non-strict + `oneOf` is accepted.
+ *
+ * That last row is why nothing caught it. Neither half is wrong on its own —
+ * the schema is valid JSON Schema and the strict decision is correct policy —
+ * so no test of either one fails. Only the pairing does, and the pairing had no
+ * owner until this function.
+ *
+ * The check is cheap and runs where the pairing is made, which is the only
+ * place both facts are in hand.
+ */
+
+/**
+ * Keywords the strict subset does not accept.
+ *
+ * A deny-list rather than an allow-list, deliberately. An allow-list would have
+ * to enumerate every annotation a schema may carry — `description`, `title`,
+ * `examples`, vendor extensions — and would refuse a schema for saying
+ * something harmless. These are the constructs documented as outside the
+ * subset; each one names what to write instead.
+ */
+const NO_CONDITIONALS = 'strict mode has no conditional schemas; flatten the object'
+const NO_NUMERIC_BOUNDS = 'numeric bounds are not in the subset; enforce at execution'
+const NO_LENGTH_BOUNDS = 'length bounds are not in the subset; enforce at execution'
+
+// A Map rather than an object literal, because one of the keys is `then`: an
+// ordinary object carrying a `then` property is a thenable, and awaiting it
+// anywhere would silently call the string. The lint rule that says so is
+// right, and a Map has no such hazard.
+const UNSUPPORTED: ReadonlyMap<string, string> = new Map([
+	['oneOf', 'use `anyOf` — for disjoint branches the two are equivalent'],
+	['not', 'express the constraint positively, or validate it at execution'],
+	['if', NO_CONDITIONALS],
+	['then', NO_CONDITIONALS],
+	['else', NO_CONDITIONALS],
+	['minimum', NO_NUMERIC_BOUNDS],
+	['maximum', NO_NUMERIC_BOUNDS],
+	['exclusiveMinimum', NO_NUMERIC_BOUNDS],
+	['exclusiveMaximum', NO_NUMERIC_BOUNDS],
+	['multipleOf', NO_NUMERIC_BOUNDS],
+	['minLength', NO_LENGTH_BOUNDS],
+	['maxLength', NO_LENGTH_BOUNDS],
+	['minItems', NO_LENGTH_BOUNDS],
+	['maxItems', NO_LENGTH_BOUNDS],
+	['uniqueItems', 'array constraints are not in the subset; enforce at execution'],
+	['patternProperties', 'name the properties explicitly'],
+	['propertyNames', 'name the properties explicitly'],
+	['dependentSchemas', 'flatten the object and validate at execution'],
+	['dependentRequired', 'flatten the object and validate at execution'],
+])
+
+export interface StrictSchemaViolation {
+	/** Dotted path to the offending keyword, e.g. `properties.insertLine.oneOf`. */
+	readonly path: string
+	readonly keyword: string
+	/** What to write instead. */
+	readonly remedy: string
+}
+
+/**
+ * Every place a schema leaves the strict subset, with its exact path.
+ *
+ * The path is the point. The vendor's own error names the tool and the
+ * keyword but not where inside the schema it sits, which on a schema of any
+ * size is the difference between a glance and an afternoon.
+ */
+export function findStrictSchemaViolations(schema: unknown, path = ''): StrictSchemaViolation[] {
+	if (Array.isArray(schema)) {
+		return schema.flatMap((item, index) => findStrictSchemaViolations(item, `${path}[${index}]`))
+	}
+	if (typeof schema !== 'object' || schema === null) return []
+
+	const found: StrictSchemaViolation[] = []
+	for (const [keyword, value] of Object.entries(schema as Record<string, unknown>)) {
+		const here = path ? `${path}.${keyword}` : keyword
+		const remedy = UNSUPPORTED.get(keyword)
+		if (remedy !== undefined) {
+			found.push({ path: here, keyword, remedy })
+			continue
+		}
+		// `additionalProperties` is admitted only as `false`; any schema there
+		// is an open object, which the subset does not allow.
+		if (keyword === 'additionalProperties' && value !== false) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'strict objects must set `additionalProperties: false`',
+			})
+			continue
+		}
+		found.push(...findStrictSchemaViolations(value, here))
+	}
+	return found
+}
+
+/**
+ * Refuse a schema the driver is about to vouch for and cannot.
+ *
+ * Refusing here rather than dropping `strict` quietly: a caller who set
+ * `enforceModelInput` asked for the guarantee, and silently not providing it
+ * is the failure this repo names `refuse, do not degrade`. The alternative
+ * costs a turn and teaches nothing — the vendor's 400 arrives with the tool
+ * name and the keyword, but not the path, and not the fix.
+ */
+export function assertStrictSchema(toolName: string, schema: unknown): void {
+	const violations = findStrictSchemaViolations(schema)
+	if (violations.length === 0) return
+
+	const detail = violations.map((v) => `  ${toolName}.${v.path} — ${v.remedy}`).join('\n')
+	throw new Error(
+		`Tool "${toolName}" is marked for strict input validation, but its model-facing schema uses ${violations.length} construct(s) the strict subset does not accept. The request would be rejected whole, taking every other tool in it down as well.\n${detail}`,
+	)
+}

package/src/public-runtime.ts

@@ -70,6 +70,16 @@ export { resolveTaskModel } from './router/task-router.js'
 // Every driver accepts `thinking`; one that does not implement it must
 // refuse rather than drop it. Shared so a new driver inherits the rule.
 export { assertThinkingUnsupported } from './provider/thinking-support.js'
+// One matcher for versioned model ids. Shared because three drivers had each
+// written their own and all three read an 8-digit date suffix as the MINOR
+// version, which inverted every capability decision keyed on it. The shape
+// lives here; the vocabulary comes from the driver that knows it.
+export { modelVersionAtLeast, parseVersionedModelId } from './provider/model-version.js'
+// Strict tool input is a SUBSET of JSON Schema, and a keyword outside it makes
+// the vendor reject the whole request rather than degrade one field.
+export { assertStrictSchema, findStrictSchemaViolations } from './provider/strict-schema.js'
+export type { StrictSchemaViolation } from './provider/strict-schema.js'
+export type { ModelIdGrammar, ModelVersion } from './provider/model-version.js'
 export { drainQuery, query } from './runtime/query/index.js'
 // Mid-run guidance. A host holds the channel and the loop drains it at the
 // tool-result boundary; see the module for why that is the only legal slot.
@@ -125,6 +135,24 @@ export {
 	resolveSkillChain,
 	SkillRegistry,
 } from './skills/index.js'
+
+// ─── the agent directory ─────────────────────────────────────────────────
+//
+// Reading a conventional `agent/` directory — its instructions, tools, skills
+// and delegates — into the same options `runAgent` and `SupervisorAgent`
+// already take. A loader, not a second engine: everything it produces is an
+// ordinary option, so a caller who outgrows the convention passes overrides
+// or stops calling it and keeps everything else.
+//
+// It shipped briefly as its own package. The name was the tell — nothing fit,
+// because a directory reader that needs the kernel to be useful is a function
+// of the kernel, not a product beside it.
+export {
+	ALL_SLOTS,
+	deriveRunOptions,
+	deriveSupervisorOptions,
+	loadDirectory,
+} from './directory/index.js'
 export {
 	AdvisorRegistry,
 	AdvisoryContext,
@@ -145,6 +173,9 @@ export {
 	// The short path: provider + model + prompt. Assembles the identity and
 	// budgets `drainQuery` requires and hands the generated identity back.
 	runAgent,
+	DEFAULT_MAX_ITERATIONS,
+	DEFAULT_TIMEOUT_MS,
+	DEFAULT_TOKEN_BUDGET,
 	SupervisorAgent,
 } from './agents/index.js'
 

package/src/public-types.ts

@@ -18,6 +18,14 @@ export type * from './types/message/index.js'
 export type * from './types/common/index.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
+// The directory convention: what a loaded `agent/` directory is, and what the
+// loader reports about the files it could not use.
+export type * from './directory/types.js'
+export type {
+	DelegatePlan,
+	DeriveSupervisorInput,
+	SupervisorPlan,
+} from './directory/derive-supervisor.js'
 export type * from './types/toolset/index.js'
 export type * from './types/permission/index.js'
 export type * from './types/run/index.js'

package/src/registry/tool/__tests__/strict-registration.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import { ToolRegistry } from '../execute.js'
+
+/**
+ * A tool that asks for constrained generation and hands over a schema the
+ * constrained dialect cannot express is wrong at the moment it is DECLARED,
+ * whichever model it later meets.
+ *
+ * The first attempt at this check lived in a provider driver. That caught the
+ * bug — but per request, in one of the two drivers that mark tools strict, and
+ * only once something actually ran. The registry already refused
+ * `enforceModelInput` without a `modelInputSchema`, with a comment stating the
+ * principle exactly: "Refusing at registration puts the error where the author
+ * can fix it rather than at the first request." The rule was written down; the
+ * check was in the wrong place.
+ *
+ * So the pair is here now. One asks whether a model schema EXISTS, the other
+ * whether it can carry the guarantee the tool just requested.
+ */
+
+function tool(overrides: Partial<ToolDefinition>): ToolDefinition {
+	return {
+		name: 'sample',
+		description: 'a tool',
+		inputSchema: z.object({}),
+		execute: async () => ({ success: true, output: 'ok' }),
+		...overrides,
+	} as ToolDefinition
+}
+
+describe('a tool cannot register a schema its own guarantee cannot carry', () => {
+	it('refuses a keyword outside the strict subset, naming the path', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({
+					name: 'edit',
+					enforceModelInput: true,
+					modelInputSchema: {
+						type: 'object',
+						properties: { insertLine: { oneOf: [{ type: 'integer' }, { const: 'end' }] } },
+					},
+				}),
+			),
+		).toThrow(/edit\.properties\.insertLine\.oneOf/)
+	})
+
+	it('names the remedy, not just the offence', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({ enforceModelInput: true, modelInputSchema: { properties: { n: { minimum: 0 } } } }),
+			),
+		).toThrow(/enforce at execution/)
+	})
+
+	it('admits the same union spelled the way the subset accepts', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({
+					enforceModelInput: true,
+					modelInputSchema: {
+						type: 'object',
+						properties: { insertLine: { anyOf: [{ type: 'integer' }, { const: 'end' }] } },
+						additionalProperties: false,
+					},
+				}),
+			),
+		).not.toThrow()
+	})
+
+	it('leaves a tool that never asked for the guarantee alone', () => {
+		// Without `enforceModelInput` nothing is marked strict, so the schema is
+		// sent as ordinary JSON Schema and `oneOf` is perfectly legal there.
+		// Refusing it would break working setups for no reason.
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({ modelInputSchema: { properties: { a: { oneOf: [{ type: 'string' }] } } } }),
+			),
+		).not.toThrow()
+	})
+
+	it('still refuses enforcement with no model schema at all', () => {
+		// The check this one was added beside. Kept in the same file so a
+		// future edit sees both halves of the pair together.
+		const registry = new ToolRegistry()
+
+		expect(() => registry.register(tool({ enforceModelInput: true }))).toThrow(
+			/does not define modelInputSchema/,
+		)
+	})
+
+	it('refuses through every registration shape', () => {
+		// `register` has three overloads and only one of them was exercised
+		// above; a check on the wrong one would look like coverage.
+		const bad = tool({
+			name: 'bad',
+			enforceModelInput: true,
+			modelInputSchema: { properties: { a: { oneOf: [] } } },
+		})
+
+		expect(() => new ToolRegistry().register(bad)).toThrow(/oneOf/)
+		expect(() => new ToolRegistry().register('bad', bad)).toThrow(/oneOf/)
+		expect(() => new ToolRegistry().register([bad])).toThrow(/oneOf/)
+	})
+})

package/src/registry/tool/execute.ts

@@ -1,4 +1,5 @@
 import { SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api'
+import { assertStrictSchema } from '../../provider/strict-schema.js'
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
 import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
@@ -177,6 +178,21 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 				`Tool "${id}" enables enforceModelInput but does not define modelInputSchema. Constrained input generation requires an explicit provider-safe model schema.`,
 			)
 		}
+		// …and the schema has to be one a constrained decoder can actually be
+		// given. The check above asks whether a model schema EXISTS; this asks
+		// whether it can carry the guarantee the tool just requested.
+		//
+		// Both belong here for the reason the comment above already states.
+		// Strict validation runs against a SUBSET of JSON Schema, and a keyword
+		// outside it is not degraded — the request is rejected whole, so one
+		// unexpressible field takes down every other tool in the call. The
+		// first version of this check lived in a provider driver, which meant
+		// it fired per request, in one driver, long after the author had moved
+		// on. A tool that asks for a guarantee its own schema cannot carry is
+		// wrong at the moment it is declared, whichever model it later meets.
+		if (tool.enforceModelInput) {
+			assertStrictSchema(id, tool.modelInputSchema)
+		}
 		if (tool.tier && this.tierConfig) {
 			const validIds = this.tierConfig.tiers.map((t) => t.id)
 			if (!validIds.includes(tool.tier)) {

package/src/runtime/query/result.ts

@@ -47,6 +47,11 @@ export class ResultAssembler {
 			type: 'run_completed',
 			runId: runMgr.id,
 			result: runMgr.getRun().result ?? '',
+			// Read AFTER `markCompleted`, which is where a run that was stopped
+			// mid-flight has its reason settled. Carried on the event so a
+			// consumer can tell "answered" from "ran out of budget" without
+			// holding the `Run`.
+			...(runMgr.getRun().stopReason ? { stopReason: runMgr.getRun().stopReason } : {}),
 		})
 		yield* drainPending()
 

package/src/tools/builtins/__tests__/edit-insert-reachable.test.ts

@@ -70,12 +70,18 @@ describe('the model can emit the idiom the description recommends', () => {
 	})
 
 	it('admits only "end" as a string, so a synonym cannot be generated', () => {
-		const insert = (schema().properties as Record<string, { oneOf?: unknown[] }>).insertLine
+		const insert = (schema().properties as Record<string, { anyOf?: unknown[] }>).insertLine
 
 		// The schema is where the synonym problem is solved for a provider that
 		// constrains: `"EOF"` is not emittable because `"end"` is the only
 		// string the union admits.
-		expect(insert?.oneOf).toEqual([{ type: 'integer', minimum: 0 }, { const: 'end' }])
+		//
+		// `anyOf`, not `oneOf`: strict tool use validates against a subset of
+		// JSON Schema that excludes `oneOf`, and the vendor rejects the whole
+		// request rather than one field — so the spelling here is load-bearing,
+		// not stylistic. The two are equivalent for disjoint branches.
+		// `minimum` is gone for the same reason; the execution schema keeps it.
+		expect(insert?.anyOf).toEqual([{ type: 'integer' }, { const: 'end' }])
 	})
 })
 

package/src/tools/builtins/__tests__/edit.test.ts

@@ -39,7 +39,7 @@ describe('EditTool', () => {
 						'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
 				},
 				insertLine: {
-					oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+					anyOf: [{ type: 'integer' }, { const: 'end' }],
 					description:
 						'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
 				},

package/src/tools/builtins/edit.ts

@@ -102,12 +102,30 @@ const modelInputSchema: Record<string, unknown> = {
 		},
 		insertLine: {
 			// The union the execution schema already accepts, stated so a
-			// constrained decoder can emit it. Declaring it as `oneOf` of an
+			// constrained decoder can emit it. Stating it as a union of an
 			// integer and the literal `"end"` also makes the synonym problem
 			// structurally impossible: `"EOF"`, `"append"` and `"last"` are
 			// not emittable, because `"end"` is the only string the schema
 			// admits.
-			oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+			//
+			// `anyOf`, NOT `oneOf`. Strict tool use validates against a SUBSET
+			// of JSON Schema, and `oneOf` is not in it — the vendor rejects the
+			// whole request with `tools.N.custom: Schema type 'oneOf' is not
+			// supported`, so the tool never mounts and the turn dies before a
+			// single token. Measured against the live API: strict + `oneOf` is
+			// a 400, strict + `anyOf` is accepted, and non-strict + `oneOf` is
+			// accepted — which is why nothing caught it. Both halves were
+			// individually fine; only their combination fails, and strict is on
+			// for every model at or above the gate.
+			//
+			// The two branches are disjoint, so `anyOf` and `oneOf` mean the
+			// same thing here — nothing is loosened.
+			//
+			// `minimum` is gone for the same reason: numeric constraints are
+			// outside the strict subset too. The bound is not lost — the
+			// execution schema still enforces it, which is where a value that
+			// crosses a boundary should be checked anyway.
+			anyOf: [{ type: 'integer' }, { const: 'end' }],
 			description:
 				'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
 		},