@namzu/sdk 6.2.0 → 7.0.0

package/dist/verification/gate.d.ts

@@ -1,11 +1,27 @@
 import type { ToolDefinition } from '../types/tool/index.js';
-import type { GateEvaluationResult, VerificationGateConfig } from '../types/verification/index.js';
+import type { GateEvaluationResult, VerificationGateConfig, VerificationRule } from '../types/verification/index.js';
 import type { Logger } from '../utils/logger.js';
 export interface ToolCallContext {
     readonly toolName: string;
     readonly toolInput: unknown;
     readonly toolDef: ToolDefinition | undefined;
 }
+/**
+ * What the rule actually said, in words a model can act on.
+ *
+ * This used to be the rule TYPE and nothing else, so a denial reached the
+ * model as "Blocked by the verification gate: Matched rule: deny_by_name" —
+ * naming the kind of rule and nothing about it. Not which tool, not which
+ * pattern, not whether a different input would fare better.
+ *
+ * The difference is behavioural rather than cosmetic. Told only that it was
+ * denied, a model rewords the same call and tries again, because nothing in
+ * the message says a retry is pointless. Told that a pattern rule denies
+ * `git push*`, it can stop, say so, and do something else. A refusal that
+ * cannot be reasoned about produces thrashing; one that can produces a route
+ * around it.
+ */
+export declare function describeRule(rule: VerificationRule): string;
 export declare class VerificationGate {
     private readonly rules;
     private readonly compiledPatterns;

package/dist/verification/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/verification/gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EACX,oBAAoB,EACpB,sBAAsB,EAEtB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGhD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;CAC5C;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM;IAsDvD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB;CAwDpD"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/verification/gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EACX,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGhD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;CAC5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAwB3D;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM;IAuEvD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB;CAwDpD"}

package/dist/verification/gate.js

@@ -1,6 +1,46 @@
 import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/verification/index.js';
 import { VerificationGateConfigSchema } from '../types/verification/index.js';
 import { evaluateRule } from './rules.js';
+/**
+ * What the rule actually said, in words a model can act on.
+ *
+ * This used to be the rule TYPE and nothing else, so a denial reached the
+ * model as "Blocked by the verification gate: Matched rule: deny_by_name" —
+ * naming the kind of rule and nothing about it. Not which tool, not which
+ * pattern, not whether a different input would fare better.
+ *
+ * The difference is behavioural rather than cosmetic. Told only that it was
+ * denied, a model rewords the same call and tries again, because nothing in
+ * the message says a retry is pointless. Told that a pattern rule denies
+ * `git push*`, it can stop, say so, and do something else. A refusal that
+ * cannot be reasoned about produces thrashing; one that can produces a route
+ * around it.
+ */
+export function describeRule(rule) {
+    switch (rule.type) {
+        case 'deny_dangerous_patterns':
+            return 'this matches a pattern the operator refuses outright; rewording it will not help';
+        case 'allow_read_only':
+            return 'allowed because this tool only observes';
+        case 'allow_by_name':
+            return `allowed by name (${rule.toolNames.join(', ')})`;
+        case 'deny_by_name':
+            return `denied by name (${rule.toolNames.join(', ')}) — this tool is refused for this run, so a different input will not change it`;
+        case 'allow_by_category':
+            return `allowed by category (${rule.categories.join(', ')})`;
+        case 'allow_by_tier':
+            return `allowed by tier (${rule.tiers.join(', ')})`;
+        case 'custom_pattern': {
+            const where = rule.target === 'both' ? 'name or arguments' : rule.target;
+            const verb = rule.decision === 'deny' ? 'denied' : 'allowed';
+            return `${verb} by a pattern rule matching the ${where}: ${rule.pattern}`;
+        }
+        default: {
+            const exhaustive = rule;
+            return `matched an unrecognised rule: ${JSON.stringify(exhaustive)}`;
+        }
+    }
+}
 export class VerificationGate {
     rules;
     compiledPatterns;
@@ -14,13 +54,29 @@ export class VerificationGate {
         this.logDecisions = parsed.logDecisions;
         this.enabled = parsed.enabled;
         const expandedRules = [];
+        // Order is the whole meaning of this list, because the first rule to
+        // match decides and nothing after it is consulted.
+        //
+        // The dangerous-pattern denial goes FIRST and stays there: it is the
+        // floor, and an operator rule must not be able to open what it closes.
+        //
+        // The read-only allowance goes LAST, and it used to go second — ahead of
+        // the operator's own rules. With first-match-wins that made a rule like
+        // "prompt me before every read" UNREACHABLE while allowReadOnlyTools was
+        // on: not rejected, not warned about, just never consulted. Someone who
+        // writes a rule and is silently ignored gets the worst outcome available
+        // — they believe a control is in force and it is not.
+        //
+        // So it becomes what it always was in substance: a DEFAULT for tools
+        // nobody wrote a rule about, rather than an override of the rules they
+        // did write. The denial above still outranks both.
         if (parsed.denyDangerousPatterns) {
             expandedRules.push({ type: 'deny_dangerous_patterns' });
         }
+        expandedRules.push(...parsed.rules);
         if (parsed.allowReadOnlyTools) {
             expandedRules.push({ type: 'allow_read_only' });
         }
-        expandedRules.push(...parsed.rules);
         this.rules = expandedRules;
         this.compiledPatterns = new Map();
         this.nameSets = new Map();
@@ -73,7 +129,7 @@ export class VerificationGate {
                 const result = {
                     decision,
                     matchedRule: rule,
-                    reason: `Matched rule: ${rule.type}`,
+                    reason: describeRule(rule),
                 };
                 if (this.logDecisions) {
                     this.log.debug('Gate decision', {

package/dist/verification/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/verification/gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/verification/gate.ts"],"names":[],"mappings":"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"}

package/dist/verification/index.d.ts

@@ -1,4 +1,4 @@
-export { VerificationGate, type ToolCallContext } from './gate.js';
+export { VerificationGate, describeRule, type ToolCallContext } from './gate.js';
 export { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.js';
 export { evaluateRule } from './rules.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/verification/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAClE,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAChF,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/dist/verification/index.js

@@ -1,4 +1,4 @@
-export { VerificationGate } from './gate.js';
+export { VerificationGate, describeRule } from './gate.js';
 export { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.js';
 export { evaluateRule } from './rules.js';
 //# sourceMappingURL=index.js.map

package/dist/verification/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAwB,MAAM,WAAW,CAAA;AAClE,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAA;AAChF,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "6.2.0",
+  "version": "7.0.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/agents/ReactiveAgent.ts

@@ -110,6 +110,11 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 					costLimitUsd: config.costLimitUsd,
 					permissionMode: config.permissionMode,
 					env: config.env,
+					// Hand-listed, so anything not named here is dropped in silence.
+					// That is how both of these came to be unreachable from every
+					// entry point except the raw kernel one.
+					...(config.thinking ? { thinking: config.thinking } : {}),
+					...(config.effort ? { effort: config.effort } : {}),
 				},
 				agentId: this.metadata.id,
 				agentName: this.metadata.name,

package/src/agents/SupervisorAgent.ts

@@ -287,6 +287,10 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					maxIterations: config.maxIterations,
 					temperature: config.temperature,
 					env: config.env,
+					// See ReactiveAgent: a hand-listed literal drops what nobody
+					// remembered to add, and reports nothing when it does.
+					...(config.thinking ? { thinking: config.thinking } : {}),
+					...(config.effort ? { effort: config.effort } : {}),
 				},
 				questionParks,
 				pendingAnswers,

package/src/agents/runAgent.ts

@@ -2,7 +2,7 @@ import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import type { ProjectId, SessionId, TenantId, ThreadId } from '../types/ids/index.js'
 import type { Message } from '../types/message/index.js'
-import type { LLMProvider } from '../types/provider/index.js'
+import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
 import type { Run, RunEventListener } from '../types/run/index.js'
 import type { Skill } from '../types/skills/index.js'
 import type { ToolRegistryContract } from '../types/tool/index.js'
@@ -83,6 +83,25 @@ export interface RunAgentOptions extends AgentIdentity {
 	timeoutMs?: number
 	temperature?: number
 
+	/**
+	 * Extended-thinking request and response-effort level, forwarded on every
+	 * model call.
+	 *
+	 * These are here because the run config below is assembled by HAND, and a
+	 * hand-listed literal silently drops whatever nobody remembered to add —
+	 * which is precisely what happened. `thinking` shipped on `AgentRunConfig`
+	 * and was reachable only from the raw kernel entry point, because this
+	 * function, `ReactiveAgent` and `SupervisorAgent` each rebuilt the object
+	 * from a fixed list. So the capability existed and the front door could not
+	 * open it.
+	 *
+	 * A live run is what found it: the unit tests passed because they drove the
+	 * kernel directly, and a real agent run through this function put no effort
+	 * on the wire at all.
+	 */
+	thinking?: ThinkingConfig
+	effort?: ReasoningEffort
+
 	/** Names the agent in traces and events. Defaults to `Agent`. */
 	name?: string
 
@@ -184,6 +203,8 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 				tokenBudget: options.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
 				timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
 				...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+				...(options.thinking ? { thinking: options.thinking } : {}),
+				...(options.effort ? { effort: options.effort } : {}),
 			},
 			// One option covers both. `drainQuery` separates the id from the
 			// display name because a fleet needs a stable key and a readable

package/src/connector/mcp/__tests__/positional-arrays.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest'
+
+import { toSchemaDialect } from '../../../registry/tool/dialect.js'
+import { renderToolSchema } from '../../../registry/tool/schema.js'
+import type { MCPJsonSchema } from '../../../types/connector/index.js'
+import { mcpJsonSchemaToZod } from '../adapter.js'
+
+/**
+ * A bridged tool's schema makes a round trip — server JSON Schema → Zod →
+ * JSON Schema on the wire — so this file asserts what comes out the FAR end,
+ * not what the Zod type is. Two failures live at that far end and neither is
+ * visible from the Zod side:
+ *
+ *  - whatever the conversion drops is dropped from what the MODEL is shown,
+ *    and a positional array was being flattened to "an array of anything";
+ *  - whatever it emits has to be a construct the receiving wire accepts, and
+ *    a rejected tool schema fails the WHOLE request rather than degrading one
+ *    tool. So a faithful conversion that cannot be sent is worse than a lossy
+ *    one that can, which is why the tuple gate is narrow rather than eager.
+ */
+
+function wire(schema: MCPJsonSchema): Record<string, unknown> {
+	const rendered = renderToolSchema(mcpJsonSchemaToZod(schema))
+	const properties = toSchemaDialect(rendered, '2020-12').properties as Record<
+		string,
+		Record<string, unknown>
+	>
+	return properties.a as Record<string, unknown>
+}
+
+const wrap = (a: Record<string, unknown>): MCPJsonSchema =>
+	({ type: 'object', properties: { a }, required: ['a'] }) as unknown as MCPJsonSchema
+
+describe('a server that pinned its positions gets a tuple', () => {
+	it('carries the draft-07 spelling through to bounded prefixItems', () => {
+		expect(
+			wire(
+				wrap({
+					type: 'array',
+					items: [{ type: 'string' }, { type: 'number' }],
+					additionalItems: false,
+					minItems: 2,
+					maxItems: 2,
+				}),
+			),
+		).toEqual({
+			type: 'array',
+			minItems: 2,
+			maxItems: 2,
+			prefixItems: [{ type: 'string' }, { type: 'number' }],
+		})
+	})
+
+	it('reaches the identical wire shape from the 2020-12 spelling', () => {
+		// The two spellings say the same thing and a server may use either.
+		// Converging them is the point: a bridged tool should not be shown
+		// differently to the model because of which dialect its author wrote.
+		expect(
+			wire(
+				wrap({
+					type: 'array',
+					prefixItems: [{ type: 'string' }, { type: 'number' }],
+					items: false,
+					minItems: 2,
+				}),
+			),
+		).toEqual({
+			type: 'array',
+			minItems: 2,
+			maxItems: 2,
+			prefixItems: [{ type: 'string' }, { type: 'number' }],
+		})
+	})
+})
+
+describe('a positional array the wire cannot carry keeps its shape in words', () => {
+	it('falls back when the server did not pin the length', () => {
+		// The inversion worth pinning: positional members do NOT constrain
+		// length. With no `minItems` the server is permitting a SHORTER array,
+		// and a tuple cannot express that — so an absent lower bound is a
+		// reason to fall back rather than a detail to round up.
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ type: 'string' }, { type: 'number' }],
+			}),
+		)
+
+		expect(result.prefixItems).toBeUndefined()
+		expect(result.description).toContain('[0] string')
+		expect(result.description).toContain('[1] number')
+	})
+
+	it('appends the shape to the description rather than replacing it', () => {
+		// The case this exists for is a server that documented its argument
+		// WELL and used a positional array. Assigning the description would
+		// have deleted its sentence to make room for ours.
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ type: 'string' }, { type: 'number' }],
+				description: 'A coordinate pair.',
+			}),
+		)
+
+		expect(result.description).toContain('A coordinate pair.')
+		expect(result.description).toContain('[0] string')
+	})
+
+	it('keeps the bounds the server did state', () => {
+		// The fallback is a ZodArray precisely so the ordinary constraint pass
+		// still carries `minItems`/`maxItems` onto it.
+		const result = wire(
+			wrap({ type: 'array', prefixItems: [{ type: 'string' }], minItems: 1, maxItems: 9 }),
+		)
+
+		expect(result.minItems).toBe(1)
+		expect(result.maxItems).toBe(9)
+	})
+
+	it('names enums and literals in the description, not just types', () => {
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ enum: ['r', 'w'] }, { const: 7 }],
+			}),
+		)
+
+		expect(result.description).toContain('"r"|"w"')
+		expect(result.description).toContain('7')
+	})
+})
+
+describe('an ordinary list is untouched', () => {
+	it('still renders as a homogeneous array', () => {
+		expect(wire(wrap({ type: 'array', items: { type: 'string' } }))).toEqual({
+			type: 'array',
+			items: { type: 'string' },
+		})
+	})
+})
+
+describe('a deep schema cannot take the process down', () => {
+	// `MAX_CONVERSION_DEPTH` promised in its own comment that a node past the
+	// ceiling is "left permissive rather than the process being taken down by
+	// a stack overflow". That was false for arrays and for unions: the counter
+	// was never passed down the array path, and even where it WAS passed
+	// correctly — the union path — nothing compared it to anything, because
+	// the only comparison lived in the object branch a pure array or union
+	// never reaches. A remote server's tool listing is untrusted input, so
+	// this was reachable denial of service.
+	const nestArrays = (depth: number): MCPJsonSchema => {
+		let inner: Record<string, unknown> = { type: 'string' }
+		for (let i = 0; i < depth; i += 1) inner = { type: 'array', items: inner }
+		return wrap(inner)
+	}
+
+	const nestUnions = (depth: number): MCPJsonSchema => {
+		let inner: Record<string, unknown> = { type: 'string' }
+		for (let i = 0; i < depth; i += 1) inner = { anyOf: [inner] }
+		return wrap(inner)
+	}
+
+	it('survives a deeply nested array', () => {
+		expect(() => mcpJsonSchemaToZod(nestArrays(5_000))).not.toThrow()
+	})
+
+	it('survives a deeply nested union', () => {
+		expect(() => mcpJsonSchemaToZod(nestUnions(5_000))).not.toThrow()
+	})
+
+	it('still converts a shallow schema faithfully', () => {
+		// The guard must not be so eager that it flattens ordinary nesting.
+		const result = wire(
+			wrap({ type: 'array', items: { type: 'array', items: { type: 'number' } } }),
+		)
+
+		expect(result).toEqual({
+			type: 'array',
+			items: { type: 'array', items: { type: 'number' } },
+		})
+	})
+})

package/src/connector/mcp/adapter.ts

@@ -93,9 +93,20 @@ function jsonSchemaPropertyToZod(prop: unknown, depth = 0): z.ZodType {
 		base = base.nullable()
 	}
 
-	const description = schema.description
-	if (typeof description === 'string' && description.length > 0) {
-		base = base.describe(description)
+	// Appended, not assigned. The conversion itself can produce a description
+	// — a positional array that could not be expressed as a tuple carries its
+	// shape here, because that prose is the only place the model learns it —
+	// and `.describe()` REPLACES. Overwriting would have silently deleted the
+	// note in exactly the case it exists for: a server that documented its
+	// argument well AND used a positional array.
+	const carried = base.description
+	const declared = schema.description
+	const parts = [
+		typeof declared === 'string' && declared.length > 0 ? declared : undefined,
+		carried,
+	].filter((part): part is string => typeof part === 'string' && part.length > 0)
+	if (parts.length > 0) {
+		base = base.describe(parts.join(' '))
 	}
 
 	if (schema.default !== undefined) {
@@ -195,6 +206,12 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 
 	const composite = (schema.anyOf ?? schema.oneOf) as unknown[] | undefined
 	if (Array.isArray(composite) && composite.length > 0) {
+		// The ceiling has to be CHECKED here, not merely counted. `depth` was
+		// threaded correctly through this branch from the start, and a
+		// 5000-deep union still overflowed the stack — because the only
+		// comparison against `MAX_CONVERSION_DEPTH` lived in `objectToZod`,
+		// which a pure union never reaches.
+		if (depth >= MAX_CONVERSION_DEPTH) return z.unknown()
 		const members = composite.map((member) => jsonSchemaPropertyToZod(member, depth + 1))
 		return members.length === 1
 			? (members[0] as z.ZodType)
@@ -229,11 +246,37 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 		case 'null':
 			return z.null()
 		case 'array': {
+			// Both the counter and the check. `depth` was never passed to the
+			// element conversion below, so the counter reset to zero on every
+			// array level — and even threaded it would not have helped, since
+			// nothing on this path compared it to anything. Measured before
+			// and after: a 5000-deep array schema took the process down with a
+			// stack overflow, which is a denial of service reachable from a
+			// remote server's tool listing.
+			if (depth >= MAX_CONVERSION_DEPTH) return z.array(z.unknown())
+
+			// A positional array has two spellings and a server may use
+			// either: draft-07 puts the member schemas in `items` with the
+			// tail rule in `additionalItems`, 2020-12 moved them to
+			// `prefixItems` with the tail rule in `items`.
+			const positional = Array.isArray(schema.prefixItems)
+				? (schema.prefixItems as unknown[])
+				: Array.isArray(schema.items)
+					? (schema.items as unknown[])
+					: undefined
+			if (positional) return positionalToZod(positional, schema, depth)
+
 			const items = schema.items
-			// A tuple (`items` as an array) is rare in tool schemas; treat it
-			// as a heterogeneous list rather than pretending to model it.
-			if (Array.isArray(items)) return z.array(z.unknown())
-			return z.array(items === undefined ? z.unknown() : jsonSchemaPropertyToZod(items))
+			return z.array(
+				// A boolean `items` is a tail RULE, not an element schema — it
+				// only has meaning next to `prefixItems`, which was handled
+				// above. Reaching it here means the server closed an array
+				// that has no positions, and an unconstrained element type is
+				// the permissive reading of that.
+				items === undefined || typeof items === 'boolean'
+					? z.unknown()
+					: jsonSchemaPropertyToZod(items, depth + 1),
+			)
 		}
 		case 'object':
 			return objectToZod(schema, depth)
@@ -242,6 +285,87 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 	}
 }
 
+/**
+ * How many positions we will express as a tuple.
+ *
+ * Not a correctness bound — a server may pin any arity it likes. It is a
+ * prompt-cost bound: every member renders its own schema into the tool
+ * definition the model is shown, and past a couple of dozen positions the
+ * thing being described is a data payload rather than a call signature. Past
+ * the cap the shape still reaches the model, in the description.
+ */
+const MAX_TUPLE_ARITY = 32
+
+/**
+ * A positional array: a tuple when the server pinned it, a described list
+ * otherwise.
+ *
+ * This used to be `z.array(z.unknown())` unconditionally, so a server that
+ * spelled out `[string, number]` had the model told "an array of anything" —
+ * the positions, their types and their order all dropped from what the model
+ * reads, not merely from what is validated locally.
+ *
+ * The reason it is not simply converted is that the schema makes a ROUND TRIP:
+ * server JSON Schema → Zod → JSON Schema on the wire. So whatever is emitted
+ * here has to be a construct the receiving wire accepts, and a construct it
+ * rejects fails the ENTIRE request rather than degrading one tool — taking
+ * down every run that offered the toolset. A faithful conversion that cannot
+ * be sent is strictly worse than a lossy one that can.
+ *
+ * Hence the narrow gate. A tuple is emitted only where the server itself
+ * pinned the arity and closed the tail, because that renders as bounded
+ * `prefixItems` — the one positional shape measured as accepted, and the same
+ * shape a first-party builtin already ships. Everything else keeps the
+ * permissive array and gains the positional shape in its description.
+ *
+ * The subtlety worth stating, because it inverts the intuition: positional
+ * `items`/`prefixItems` does not constrain LENGTH. Without `minItems` the
+ * server is permitting a SHORTER array, and a tuple cannot express that — so
+ * an absent lower bound is a reason to fall back, not a detail to round up.
+ */
+function positionalToZod(
+	positional: readonly unknown[],
+	schema: Record<string, unknown>,
+	depth: number,
+): z.ZodType {
+	// draft-07 spells the tail rule `additionalItems`; 2020-12 spells it
+	// `items`, which is only a tail rule when `prefixItems` holds the members.
+	const tail = Array.isArray(schema.items) ? schema.additionalItems : schema.items
+
+	const arity = positional.length
+	const pinnedLow = num(schema.minItems) === arity
+	const closedHigh = tail === false || num(schema.maxItems) === arity
+
+	if (arity === 0 || arity > MAX_TUPLE_ARITY || !pinnedLow || !closedHigh) {
+		// A ZodArray, deliberately: `applyConstraints` then carries the
+		// server's own `minItems`/`maxItems` onto it, so the loose case keeps
+		// whatever bounds the server did state.
+		return z.array(z.unknown()).describe(describePositional(positional))
+	}
+
+	const members = positional.map((member) => jsonSchemaPropertyToZod(member, depth + 1))
+	// Never `.rest()`. It renders a tail schema this wire has not been measured
+	// against, and the gate above has already established there is no tail.
+	return z.tuple(members as [z.ZodType, ...z.ZodType[]])
+}
+
+/** The positional shape in prose, for the cases a tuple cannot carry. */
+function describePositional(positional: readonly unknown[]): string {
+	const shape = positional
+		.map((member, index) => `[${index}] ${positionalTypeName(member)}`)
+		.join(', ')
+	return `Positional array — ${shape}.`
+}
+
+function positionalTypeName(member: unknown): string {
+	if (typeof member !== 'object' || member === null) return 'any'
+	const schema = member as Record<string, unknown>
+	if (schema.const !== undefined) return JSON.stringify(schema.const)
+	if (Array.isArray(schema.enum)) return schema.enum.map((v) => JSON.stringify(v)).join('|')
+	const type = Array.isArray(schema.type) ? schema.type.join('|') : schema.type
+	return typeof type === 'string' ? type : 'any'
+}
+
 /**
  * Flatten `allOf` members into one object schema.
  *

package/src/constants/agent/index.ts

@@ -1,6 +1,11 @@
 import type { AgentCapabilities } from '../../types/agent/base.js'
 import type { AgentManagerConfig } from '../../types/agent/task.js'
 
+/**
+ * **Nothing reads this.** No activity list is trimmed to it anywhere.
+ *
+ * @deprecated Unused. Removed in the next major.
+ */
 export const MAX_RECENT_ACTIVITIES = 5
 
 export const AGENT_MANAGER_DEFAULTS: Readonly<AgentManagerConfig> = {

package/src/constants/plugin/index.ts

@@ -44,4 +44,19 @@ export const HOOK_TIMEOUT_MS = 5_000
  * can sort itself after.
  */
 export const DEFAULT_HOOK_PRIORITY = 100
+/**
+ * **Nothing reads this.** Hooks run sequentially and always have.
+ *
+ * It reads as a concurrency cap that is in force, which is the misleading
+ * kind of dead: a reviewer sees a bound, assumes hook execution is batched
+ * at ten, and reasons about plugin behaviour that does not exist.
+ *
+ * Kept for one release rather than deleted, because it is reachable from the
+ * published typings. Do not "make it work" by batching hook execution —
+ * ordering is the contract hooks are written against, and parallelising them
+ * to justify a constant would change behaviour to match a number nobody
+ * chose deliberately.
+ *
+ * @deprecated Unused. Removed in the next major.
+ */
 export const HOOK_MAX_CONCURRENT = 10