@namzu/sdk 6.2.0 → 7.0.0

package/src/types/probe/registry.ts

@@ -31,6 +31,12 @@ export interface ProbeOptions<K extends ProbeEventKind = ProbeEventKind> {
 	readonly where?: (event: ProbeEventOf<K>) => boolean
 	readonly priority?: number
 	readonly name?: string
+	/**
+	 * **Not implemented.** Setting it changes nothing; no probe emits
+	 * telemetry because of it.
+	 *
+	 * @deprecated Unimplemented. Removed in the next major.
+	 */
 	readonly otel?: boolean
 	readonly override?: boolean
 }

package/src/types/run/config.ts

@@ -18,6 +18,32 @@ export interface AgentRunConfig {
 	 * driver omits them rather than sending a request it knows will 400.
 	 */
 	thinking?: import('../provider/index.js').ThinkingConfig
+
+	/**
+	 * How much work the model should spend on each call in the run.
+	 *
+	 * A SIBLING of {@link AgentRunConfig.thinking}, not a field inside it.
+	 * On some models the two are independent controls that apply together —
+	 * effort shapes the answer while a budget sets thinking depth — so
+	 * nesting one inside the other would make that combination unsayable.
+	 *
+	 * The failure this closes is the one this codebase keeps finding: the
+	 * field existed on the provider params, a driver already read it and
+	 * wrote it to the wire, and nothing in the kernel ever set it. So a
+	 * caller could not reach it at all, and the symptom — every request
+	 * going out at the model's default — reads as "this model ignores
+	 * effort" rather than "nobody plumbed it through".
+	 *
+	 * Run-level rather than per-step, deliberately. It is a property of what
+	 * the run is FOR, and a value that moves between steps buys a different
+	 * answer shape at the cost of the prompt-cache prefix on every step that
+	 * changes it.
+	 *
+	 * A driver that cannot honour it REFUSES rather than dropping it, on the
+	 * same reasoning as `thinking`: paying for a run you believe was
+	 * high-effort and silently was not is worse than a startup error.
+	 */
+	effort?: import('../provider/index.js').ReasoningEffort
 	tokenBudget: number
 	costLimitUsd?: number
 	maxIterations?: number

package/src/utils/__tests__/abort-reason.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+
+import { abortReasonText } from '../abort.js'
+
+/**
+ * A cancellation and a deadline arrive by the same mechanism and mean opposite
+ * things to whoever reads the result. The distinction only survives if the
+ * words a caller attached travel with the abort — and only if the words the
+ * platform invents on a caller's behalf do NOT, because a fabricated
+ * explanation is worse than an honest silence.
+ */
+
+describe('a stop carries the words its caller gave it', () => {
+	it('reports a reason someone wrote', () => {
+		expect(abortReasonText(new Error('deployment window closed'))).toBe('deployment window closed')
+	})
+
+	it('reports a named deadline, which is the case this exists for', () => {
+		const reason = new Error('run budget of 30000ms exhausted')
+		expect(abortReasonText(reason)).toBe('run budget of 30000ms exhausted')
+	})
+})
+
+describe('a stop with nothing to say stays silent', () => {
+	it('says nothing for a bare abort()', () => {
+		// `abort()` with no argument fills `reason` with a DOMException named
+		// AbortError. Nobody wrote that word; it is the platform's way of
+		// saying the caller gave no reason, and rendering it would turn "we
+		// do not know" into what looks like an answer.
+		const controller = new AbortController()
+		controller.abort()
+
+		expect(controller.signal.reason).toBeInstanceOf(Error)
+		expect((controller.signal.reason as Error).name).toBe('AbortError')
+		expect(abortReasonText(controller.signal.reason)).toBeUndefined()
+	})
+
+	it('says nothing for a platform timeout', () => {
+		const timeout = new Error('The operation was aborted due to timeout')
+		timeout.name = 'TimeoutError'
+		expect(abortReasonText(timeout)).toBeUndefined()
+	})
+
+	it('says nothing for a non-Error reason', () => {
+		// The agent manager aborts a child with the bare string 'canceled'.
+		// Rendering it produces "was cancelled: canceled" — noise wearing the
+		// shape of information.
+		expect(abortReasonText('canceled')).toBeUndefined()
+		expect(abortReasonText(undefined)).toBeUndefined()
+		expect(abortReasonText({ message: 'not an Error' })).toBeUndefined()
+	})
+
+	it('says nothing for an Error whose message is empty', () => {
+		expect(abortReasonText(new Error('   '))).toBeUndefined()
+	})
+})

package/src/utils/abort.ts

@@ -1,3 +1,37 @@
+import { toErrorMessage } from './error.js'
+
+/**
+ * The words a caller attached to a stop, or nothing when there were none.
+ *
+ * A cancellation and a deadline arrive by the same mechanism and mean opposite
+ * things to whoever reads the result. "Was cancelled" tells a model that
+ * something outside it decided, and nothing about what — so a tool result
+ * could not distinguish an operator pressing stop from a budget running out
+ * from a parent abandoning a child, and every one of those wants a different
+ * next move.
+ *
+ * Two kinds of reason are deliberately reported as no reason:
+ *
+ * - `AbortError` and `TimeoutError`. `abort()` with no argument fills `reason`
+ *   with a DOMException named `AbortError`, so it is not a message anybody
+ *   wrote; it is the platform's word for "someone stopped and said nothing".
+ *   Rendering it would turn today's honest silence into a fake explanation.
+ * - Anything that is not an `Error`. The agent manager aborts a child with the
+ *   bare string `'canceled'`, which would otherwise render as "was cancelled:
+ *   canceled" — noise wearing the shape of information.
+ *
+ * Name-checked rather than checked by class, because a reason can cross a
+ * package boundary where `instanceof` stops holding across duplicate copies.
+ * That is the same answer this codebase already settled on for provider
+ * errors.
+ */
+export function abortReasonText(reason: unknown): string | undefined {
+	if (!(reason instanceof Error)) return undefined
+	if (reason.name === 'AbortError' || reason.name === 'TimeoutError') return undefined
+	const text = toErrorMessage(reason).trim()
+	return text.length > 0 ? text : undefined
+}
+
 export function createChildAbortController(parent: AbortController): AbortController {
 	const child = new AbortController()
 

package/src/verification/__tests__/rule-order-and-reason.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ToolDefinition } from '../../types/tool/index.js'
+import type { VerificationGateConfig } from '../../types/verification/index.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { VerificationGate, describeRule } from '../gate.js'
+
+/**
+ * Two things an operator has to be able to trust about a policy gate: that a
+ * rule they wrote is consulted, and that a refusal says enough to act on.
+ *
+ * Neither held. `allowReadOnlyTools` was expanded into a rule AHEAD of the
+ * operator's own, and the gate stops at the first match — so "prompt me before
+ * every read" was not rejected, not warned about, just never reached. And a
+ * denial arrived as the rule's TYPE NAME, which tells a model that a rule
+ * matched and nothing whatever about what it said.
+ */
+
+function gate(config: Partial<VerificationGateConfig>): VerificationGate {
+	return new VerificationGate(
+		{
+			enabled: true,
+			rules: [],
+			allowReadOnlyTools: false,
+			denyDangerousPatterns: false,
+			logDecisions: false,
+			...config,
+		} as VerificationGateConfig,
+		getRootLogger(),
+	)
+}
+
+/** Only the fields the gate reads. */
+function toolDef(name: string, readOnly: boolean): ToolDefinition {
+	return { name, isReadOnly: () => readOnly } as unknown as ToolDefinition
+}
+
+describe('an operator rule outranks the read-only convenience', () => {
+	it('lets a rule make a read-only tool prompt', () => {
+		// The case that was silently unreachable: `read` observes only, the
+		// convenience is on, and the operator has asked to be consulted anyway.
+		const result = gate({
+			allowReadOnlyTools: true,
+			rules: [{ type: 'deny_by_name', toolNames: ['read'] }],
+		}).evaluate({
+			toolName: 'read',
+			toolInput: { path: 'notes.txt' },
+			toolDef: toolDef('read', true),
+		})
+
+		expect(result.decision, 'the operator rule was never consulted').toBe('deny')
+	})
+
+	it('still allows a read-only tool nobody wrote a rule about', () => {
+		// The convenience keeps doing its job as a DEFAULT, which is what it
+		// always was in substance.
+		const result = gate({
+			allowReadOnlyTools: true,
+			rules: [{ type: 'deny_by_name', toolNames: ['write'] }],
+		}).evaluate({
+			toolName: 'grep',
+			toolInput: { pattern: 'x' },
+			toolDef: toolDef('grep', true),
+		})
+
+		expect(result.decision).toBe('allow')
+	})
+})
+
+describe('the safety floor still outranks everything', () => {
+	it('refuses a dangerous pattern even when a rule would allow the tool', () => {
+		// The denial goes first and stays there. An operator rule must not be
+		// able to open what it closes.
+		const result = gate({
+			denyDangerousPatterns: true,
+			rules: [{ type: 'allow_by_name', toolNames: ['bash'] }],
+		}).evaluate({
+			toolName: 'bash',
+			toolInput: { command: 'rm -rf /' },
+			toolDef: toolDef('bash', false),
+		})
+
+		expect(result.decision).toBe('deny')
+	})
+})
+
+describe('a refusal says what the rule said', () => {
+	it('names the pattern rather than the rule type', () => {
+		// "Matched rule: custom_pattern" tells a model a rule matched and
+		// nothing about it, so it rewords the same call and tries again. The
+		// pattern is what makes the retry visibly pointless.
+		const reason = describeRule({
+			type: 'custom_pattern',
+			pattern: 'git push*',
+			target: 'args',
+			decision: 'deny',
+		})
+
+		expect(reason).toContain('git push*')
+		expect(reason).toContain('denied')
+		expect(reason).not.toContain('custom_pattern')
+	})
+
+	it('says a by-name denial is about the tool, not the input', () => {
+		// The distinction that decides the next move: reworded arguments will
+		// not help, so the model should stop rather than iterate.
+		const reason = describeRule({ type: 'deny_by_name', toolNames: ['bash', 'write'] })
+
+		expect(reason).toContain('bash')
+		expect(reason).toContain('a different input will not change it')
+	})
+
+	it('says a dangerous-pattern refusal is not worth rewording', () => {
+		expect(describeRule({ type: 'deny_dangerous_patterns' })).toContain('will not help')
+	})
+
+	it('reaches the model through the gate result, not just the helper', () => {
+		const result = gate({ rules: [{ type: 'deny_by_name', toolNames: ['bash'] }] }).evaluate({
+			toolName: 'bash',
+			toolInput: { command: 'ls' },
+			toolDef: toolDef('bash', false),
+		})
+
+		expect(result.reason).toContain('bash')
+		expect(result.reason).not.toMatch(/^Matched rule:/)
+	})
+
+	it('is reachable by a caller driving the rules without the gate', async () => {
+		// `evaluateRule` is public and answers only WHETHER a rule matched. A
+		// caller holding that verdict and no describer is back to switching on
+		// the rule's type for its wording — the same defect the gate carried,
+		// one layer up. So the two travel together, and this asserts the
+		// PAIRING rather than either one alone.
+		//
+		// Asserted at this barrel rather than the package barrel on purpose.
+		// Importing `../../index.js` costs ~4s of module-graph load — measured,
+		// on an idle machine, against a default 5s test budget — so the version
+		// of this test that looked stronger was one busy CI runner away from
+		// failing for a reason that has nothing to do with verification. The
+		// package half is gated better elsewhere anyway: the public-surface
+		// baseline resolves `dist/index.d.ts` through the checker and reports a
+		// REGRESSION naming any symbol that leaves the surface.
+		const barrel = await import('../index.js')
+
+		expect(typeof barrel.evaluateRule).toBe('function')
+		expect(typeof barrel.describeRule).toBe('function')
+		expect(barrel.describeRule({ type: 'deny_by_name', toolNames: ['bash'] })).toContain('bash')
+	})
+})

package/src/verification/gate.ts

@@ -15,6 +15,47 @@ export interface ToolCallContext {
 	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 function describeRule(rule: VerificationRule): string {
+	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: never = rule
+			return `matched an unrecognised rule: ${JSON.stringify(exhaustive)}`
+		}
+	}
+}
+
 export class VerificationGate {
 	private readonly rules: VerificationRule[]
 	private readonly compiledPatterns: Map<number, RegExp>
@@ -31,14 +72,31 @@ export class VerificationGate {
 
 		const expandedRules: VerificationRule[] = []
 
+		// 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()
@@ -102,7 +160,7 @@ export class VerificationGate {
 				const result: GateEvaluationResult = {
 					decision,
 					matchedRule: rule,
-					reason: `Matched rule: ${rule.type}`,
+					reason: describeRule(rule),
 				}
 
 				if (this.logDecisions) {

package/src/verification/index.ts

@@ -1,3 +1,3 @@
-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'