@namzu/sdk 5.1.0 → 6.0.0

package/src/provider/strict-schema.ts

@@ -0,0 +1,182 @@
+/**
+ * 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. Each entry names what to write instead.
+ *
+ * MEASURED against the live API, not read off a page. The first version of this
+ * list was derived from documentation and was wrong in both directions: it
+ * refused `minLength`/`maxLength`, which the wire accepts, and it permitted
+ * `prefixItems`, which the wire rejects. A deny-list nobody probed is a guess
+ * with a confident tone, and this one would have refused working tools while
+ * still letting a broken one through.
+ *
+ * The probe lives in the live contract test; run it against a new model before
+ * trusting this list on that model.
+ */
+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_ARRAY_BOUNDS = 'array 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`/`maxLength` are NOT here. The first version of this list put
+	// them here on documentation alone, and measurement says the wire accepts
+	// both — so the list was refusing tools that would have worked. A deny-list
+	// derived from prose and never probed is a guess with a confident tone.
+	// `minItems` is NOT a flat denial — see MIN_ITEMS_ALLOWED below. The wire
+	// accepts 0 and 1 and refuses everything above, naming the value in the
+	// error, so a blanket entry here would refuse `.nonempty()` on a schema the
+	// wire would have taken.
+	['maxItems', NO_ARRAY_BOUNDS],
+	['uniqueItems', NO_ARRAY_BOUNDS],
+	// The other direction of the same mistake: this was missing, and it is the
+	// one that interacts with the dialect conversion. A tuple becomes
+	// `prefixItems` for the 2020-12 wire — and strict rejects `prefixItems`
+	// outright, so a tool that is BOTH strict AND tuple-shaped cannot be
+	// expressed at all. Better to say that at registration than to convert a
+	// schema into a different rejection.
+	['prefixItems', 'strict arrays take one `items` schema; a tuple cannot be expressed'],
+	['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'],
+])
+
+/**
+ * The only `minItems` values the strict subset admits.
+ *
+ * Measured: `minItems: 0` and `minItems: 1` are accepted, `minItems: 2` comes
+ * back *"For 'array' type, 'minItems' values other than 0 or 1 are not
+ * supported"*. So the constraint is on the VALUE, not the keyword, and that is
+ * the whole difference between refusing a required-non-empty array — the
+ * ordinary spelling of `z.array(...).nonempty()` — and letting it through.
+ */
+const MIN_ITEMS_ALLOWED = new Set([0, 1])
+
+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
+		}
+		// A tuple in the OTHER spelling. This check runs at registration, on the
+		// schema as rendered — which is draft-07, where a tuple is `items: [a,
+		// b]` — while the wire sees the 2020-12 `prefixItems` the driver
+		// converts it to. So a `prefixItems` entry alone never fires on the
+		// path that produces tuples, and the entry added to catch this case was
+		// dead for exactly the case it was added for.
+		//
+		// Both spellings mean the same thing and strict admits neither, so this
+		// names the tuple rather than the dialect it happens to be written in.
+		if (keyword === 'items' && Array.isArray(value)) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'strict arrays take one `items` schema; a tuple cannot be expressed',
+			})
+			continue
+		}
+		if (keyword === 'minItems' && typeof value === 'number' && !MIN_ITEMS_ALLOWED.has(value)) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'strict accepts `minItems` of 0 or 1 only; enforce a larger bound at execution',
+			})
+			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,23 @@ 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'
+// A tool has one schema; what changes per provider is the DIALECT the wire
+// parses, which is the wire's property. Rendered once, converted at the driver.
+export { findDraft07Only, toSchemaDialect } from './registry/tool/dialect.js'
+export type { JsonSchemaDialect } from './registry/tool/dialect.js'
+// The renderer itself, so a driver or a contract test can ask what a tool will
+// actually put on the wire without reaching into the registry.
+export { renderToolSchema } from './registry/tool/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 +142,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 +180,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__/dialect.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { findDraft07Only, toSchemaDialect } from '../dialect.js'
+import { renderToolSchema } from '../schema.js'
+
+/**
+ * The mechanism, tested in the kernel that owns it.
+ *
+ * The drivers each have their own test proving the conversion reaches their
+ * wire. This one is about the conversion itself: what it rewrites, what it
+ * deliberately leaves alone, and the two properties the prompt cache depends
+ * on — a stable reference and a frozen result.
+ */
+
+describe('saying a schema in the dialect a wire parses', () => {
+	it('moves a tuple from `items` to `prefixItems`', () => {
+		const draft07 = {
+			type: 'object',
+			properties: {
+				range: {
+					type: 'array',
+					items: [{ type: 'integer' }, { type: 'integer' }],
+					minItems: 2,
+					maxItems: 2,
+				},
+			},
+		}
+
+		expect(toSchemaDialect(draft07, '2020-12')).toEqual({
+			type: 'object',
+			properties: {
+				range: {
+					type: 'array',
+					prefixItems: [{ type: 'integer' }, { type: 'integer' }],
+					minItems: 2,
+					maxItems: 2,
+				},
+			},
+		})
+	})
+
+	it('leaves a homogeneous array alone, where `items` means the same thing', () => {
+		// The distinction the whole conversion turns on: `items` is only a
+		// tuple when it holds an ARRAY of schemas. One schema means "every
+		// element", which both dialects spell identically.
+		const schema = { type: 'array', items: { type: 'string' } }
+
+		expect(toSchemaDialect(schema, '2020-12')).toEqual(schema)
+	})
+
+	it('turns `additionalItems` into the 2020-12 `items`', () => {
+		// `additionalItems` only ever qualified an array-form `items` — it says
+		// what the elements AFTER the tuple look like. 2020-12 gave that job to
+		// `items` once `prefixItems` holds the positional schemas.
+		const converted = toSchemaDialect(
+			{
+				type: 'array',
+				items: [{ type: 'integer' }],
+				additionalItems: { type: 'string' },
+			},
+			'2020-12',
+		)
+
+		expect(converted).toEqual({
+			type: 'array',
+			prefixItems: [{ type: 'integer' }],
+			items: { type: 'string' },
+		})
+	})
+
+	it('drops `additionalItems: false`, which both dialects already imply', () => {
+		// Not a lossy shortcut: once `prefixItems` is set, a closed tuple is the
+		// default in 2020-12, so emitting `items: false` would add a byte to
+		// every request to say what was already true.
+		expect(
+			toSchemaDialect(
+				{ type: 'array', items: [{ type: 'integer' }], additionalItems: false },
+				'2020-12',
+			),
+		).toEqual({ type: 'array', prefixItems: [{ type: 'integer' }] })
+	})
+
+	it('ignores `additionalItems` with no tuple to qualify', () => {
+		// Meaningless in draft-07 too, so carrying it forward would be inventing
+		// a constraint the author did not write.
+		expect(
+			toSchemaDialect(
+				{ type: 'array', items: { type: 'string' }, additionalItems: { type: 'integer' } },
+				'2020-12',
+			),
+		).toEqual({ type: 'array', items: { type: 'string' } })
+	})
+
+	it('converts a tuple nested inside another tuple', () => {
+		const converted = toSchemaDialect(
+			{ type: 'array', items: [{ type: 'array', items: [{ type: 'integer' }] }] },
+			'2020-12',
+		) as Record<string, Record<string, unknown>[]>
+
+		expect(converted.prefixItems?.[0]).toEqual({
+			type: 'array',
+			prefixItems: [{ type: 'integer' }],
+		})
+	})
+
+	it('hands back the very same object for draft-07', () => {
+		// Not an equal object — the SAME one. The tools block sits at position 0
+		// of the prompt-cache prefix, so a driver that speaks draft-07 must not
+		// pay an allocation or risk a differently-ordered copy per request.
+		const schema = { type: 'object' }
+
+		expect(toSchemaDialect(schema, 'draft-07')).toBe(schema)
+	})
+
+	it('returns the same converted object every time it is asked', () => {
+		// Same reason. Conversion runs once per schema per dialect; a fresh
+		// object each iteration would invalidate the cache for the whole run
+		// even though the bytes were equal.
+		const schema = { type: 'array', items: [{ type: 'integer' }] }
+
+		expect(toSchemaDialect(schema, '2020-12')).toBe(toSchemaDialect(schema, '2020-12'))
+	})
+
+	it('freezes what it hands out, all the way down', () => {
+		// A caller that mutates a cached schema would poison every later render,
+		// and the symptom would be a silently invalidated prompt cache rather
+		// than an error. Freezing turns that into a throw at the mutation site.
+		const converted = toSchemaDialect(
+			{ type: 'object', properties: { a: { type: 'array', items: [{ type: 'integer' }] } } },
+			'2020-12',
+		) as { properties: { a: { prefixItems: unknown[] } } }
+
+		expect(Object.isFrozen(converted)).toBe(true)
+		expect(Object.isFrozen(converted.properties.a)).toBe(true)
+		expect(Object.isFrozen(converted.properties.a.prefixItems)).toBe(true)
+	})
+})
+
+describe('finding what a 2020-12 wire will refuse', () => {
+	it('names the path to an array-form `items`', () => {
+		expect(
+			findDraft07Only({
+				type: 'object',
+				properties: { range: { type: 'array', items: [{ type: 'integer' }] } },
+			}),
+		).toEqual(['properties.range.items'])
+	})
+
+	it('names `additionalItems` too', () => {
+		expect(findDraft07Only({ additionalItems: false })).toEqual(['additionalItems'])
+	})
+
+	it('walks into arrays, indexing the branch', () => {
+		expect(
+			findDraft07Only({
+				anyOf: [{ type: 'string' }, { type: 'array', items: [{ type: 'integer' }] }],
+			}),
+		).toEqual(['anyOf[1].items'])
+	})
+
+	it('does not descend into a tuple it has already reported', () => {
+		// Reporting the tuple and then each of its positional schemas would
+		// turn one fixable finding into a list nobody reads.
+		expect(
+			findDraft07Only({ type: 'array', items: [{ type: 'integer' }, { type: 'string' }] }),
+		).toEqual(['items'])
+	})
+
+	it('says nothing about a schema that is already 2020-12', () => {
+		expect(
+			findDraft07Only({
+				type: 'array',
+				prefixItems: [{ type: 'integer' }],
+				items: { type: 'string' },
+			}),
+		).toEqual([])
+	})
+
+	it('tolerates the leaves', () => {
+		expect(findDraft07Only(null)).toEqual([])
+		expect(findDraft07Only('a string')).toEqual([])
+		expect(findDraft07Only(42)).toEqual([])
+	})
+})
+
+describe('the round trip a real tool takes', () => {
+	it('renders a Zod tuple as draft-07 and converts it clean', () => {
+		// The actual defect, end to end: this is what `read.readRange` is.
+		const rendered = renderToolSchema(
+			z.object({ readRange: z.tuple([z.number(), z.number()]).optional() }),
+		)
+
+		expect(findDraft07Only(rendered)).not.toEqual([])
+		expect(findDraft07Only(toSchemaDialect(rendered, '2020-12'))).toEqual([])
+	})
+})

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/)
+	})
+})