@namzu/sdk 6.2.0 → 8.0.0

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__/argument-pattern.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ToolDefinition } from '../../types/tool/index.js'
+import type { VerificationGateConfig, VerificationRule } from '../../types/verification/index.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { VerificationGate } from '../gate.js'
+
+/**
+ * Every pattern rule an operator could write was one of two wrong things.
+ *
+ * `custom_pattern` carries no tool scope, so a rule written about `bash`
+ * decided `edit` calls as well. And `target: 'args'` tests
+ * `JSON.stringify(toolInput)`, so the subject is the JSON TEXT of the whole
+ * argument object — meaning the natural, anchored thing to write
+ * (`^git push.*$`) can never match, and the rule silently decides nothing.
+ * Pinning the tool cost the anchor; anchoring cost the tool scope.
+ */
+
+function gate(rules: VerificationGateConfig['rules']): VerificationGate {
+	return new VerificationGate(
+		{
+			enabled: true,
+			rules,
+			allowReadOnlyTools: false,
+			denyDangerousPatterns: false,
+			logDecisions: false,
+		} as VerificationGateConfig,
+		getRootLogger(),
+	)
+}
+
+/** Only the fields the gate reads. */
+function toolDef(name: string): ToolDefinition {
+	return { name, isReadOnly: () => false } as unknown as ToolDefinition
+}
+
+const PUSH_RULE: VerificationRule = {
+	type: 'argument_pattern',
+	toolNames: ['bash'],
+	argument: 'command',
+	pattern: '^git push',
+	decision: 'deny',
+}
+
+function evaluate(
+	rules: VerificationGateConfig['rules'],
+	toolName: string,
+	toolInput: unknown,
+): ReturnType<VerificationGate['evaluate']> {
+	return gate(rules).evaluate({ toolName, toolInput, toolDef: toolDef(toolName) })
+}
+
+describe('a rule can name one tool and one argument at once', () => {
+	it('denies the call it was written about', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' })
+		expect(result.decision).toBe('deny')
+	})
+
+	it('anchors against the value, which is what the old rule could not do', () => {
+		// The whole defect in one assertion: this same pattern under
+		// `custom_pattern` with `target: 'args'` is tested against
+		// `{"command":"git push origin main"}`, where `^git push` cannot match
+		// because the string does not start there.
+		const viaOldRule = evaluate(
+			[{ type: 'custom_pattern', pattern: '^git push', target: 'args', decision: 'deny' }],
+			'bash',
+			{ command: 'git push origin main' },
+		)
+		expect(viaOldRule.decision, 'the old rule silently decided nothing').not.toBe('deny')
+
+		expect(evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' }).decision).toBe('deny')
+	})
+
+	it('leaves a different tool alone', () => {
+		// The other half: a rule about `bash` used to decide `edit` too,
+		// because the pattern was matched against a serialisation that has no
+		// idea which tool produced it.
+		const result = evaluate([PUSH_RULE], 'edit', { command: 'git push origin main' })
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('leaves a different argument alone', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { description: 'git push origin main' })
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('says which argument decided, so a model knows whether to reword', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' })
+
+		expect(result.reason).toContain('command')
+		expect(result.reason).toContain('^git push')
+		expect(result.reason).toContain('bash')
+	})
+})
+
+describe('what it deliberately does not decide', () => {
+	it('decides nothing when the argument is absent', () => {
+		const result = evaluate([PUSH_RULE], 'bash', {})
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('decides nothing about a structured argument', () => {
+		// No string a pattern could match says anything true about an object,
+		// and serialising it to try would put this rule back where
+		// `custom_pattern` already is. An operator who needs to refuse a tool
+		// over the SHAPE of its input wants deny_by_name.
+		const rule: VerificationRule = { ...PUSH_RULE, argument: 'env', pattern: 'PROD' }
+		const result = evaluate([rule], 'bash', { env: { NODE_ENV: 'PROD' } })
+
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('reads a number or a boolean rather than skipping it', () => {
+		// These render unambiguously, so skipping them would be a fail-open
+		// with no upside: a rule about a numeric argument is a rule someone
+		// can reasonably write.
+		const rule: VerificationRule = {
+			type: 'argument_pattern',
+			toolNames: ['sleep'],
+			argument: 'seconds',
+			pattern: '^[0-9]{4,}$',
+			decision: 'deny',
+		}
+
+		expect(evaluate([rule], 'sleep', { seconds: 86400 }).decision).toBe('deny')
+		expect(evaluate([rule], 'sleep', { seconds: 5 }).decision).not.toBe('deny')
+	})
+})
+
+describe('a rule that cannot be compiled decides nothing at all', () => {
+	it('does not widen into a rule about the whole tool', () => {
+		// The failure this forbids: a typo'd regex turning "deny bash when its
+		// command matches X" into "deny bash" — a far larger authorization than
+		// anybody wrote, granted by a mistake nobody would notice.
+		//
+		// What actually secures it is the missing-pattern check at the top of
+		// `evaluateRule`, which returns before the tool name is consulted. The
+		// gate's construction order (compile first, only then record the names)
+		// is defence in depth and NOT the mechanism: reversing those two lines
+		// fails nothing, which was measured rather than assumed. So this test
+		// pins the OUTCOME and the comment in the gate says which line to keep.
+		const broken: VerificationRule = { ...PUSH_RULE, pattern: '([unclosed' }
+		const result = evaluate([broken], 'bash', { command: 'ls' })
+
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('is secured by the pattern check, not by the construction order', () => {
+		// The honest version of the mutation: remove the check that actually
+		// holds and this fails. A rule whose pattern never compiled has no
+		// pattern to test, so it must decide nothing even for a tool it names.
+		const broken: VerificationRule = { ...PUSH_RULE, pattern: '([unclosed' }
+
+		expect(evaluate([broken], 'bash', { command: 'git push origin main' }).decision).not.toBe(
+			'deny',
+		)
+	})
+})

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,55 @@ 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 'argument_pattern': {
+			// Names the argument, not just the pattern. That is what tells a
+			// model whether a different value could get through — which is the
+			// difference between rewording once and rewording forever.
+			const verb = rule.decision === 'deny' ? 'denied' : 'allowed'
+			return `${verb} because the \`${rule.argument}\` argument matched ${rule.pattern} (this rule applies to ${rule.toolNames.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 +80,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()
@@ -68,6 +134,43 @@ export class VerificationGate {
 				}
 			}
 
+			if (rule.type === 'argument_pattern') {
+				// Needs BOTH, because it is the rule that names both.
+				//
+				// The name set is recorded only after the pattern compiles, so
+				// a rule with a typo'd regex leaves neither half behind. That
+				// ordering is defence in depth and NOT what makes the guarantee
+				// — `evaluateRule` returns null on a missing compiled pattern
+				// before it ever looks at the name set, so reversing these two
+				// lines changes no behaviour. Measured: reversing them fails no
+				// test, and the test that looks like it covers this is really
+				// covering the check in `evaluateRule`.
+				//
+				// Written down because the alternative is someone later reading
+				// the order as load-bearing and preserving it for the wrong
+				// reason, or removing the real check believing this one covers
+				// it.
+				if (rule.pattern.length > MAX_CUSTOM_PATTERN_LENGTH) {
+					this.log.warn('Argument pattern exceeds max length, skipping', {
+						index: i,
+						length: rule.pattern.length,
+						maxLength: MAX_CUSTOM_PATTERN_LENGTH,
+					})
+					continue
+				}
+				try {
+					const compiled = new RegExp(rule.pattern)
+					this.compiledPatterns.set(i, compiled)
+					this.nameSets.set(i, new Set(rule.toolNames))
+				} catch (err) {
+					this.log.warn('Invalid argument pattern regex, skipping', {
+						index: i,
+						pattern: rule.pattern,
+						error: err instanceof Error ? err.message : String(err),
+					})
+				}
+			}
+
 			if (rule.type === 'allow_by_name') {
 				this.nameSets.set(i, new Set(rule.toolNames))
 			}
@@ -102,7 +205,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'

package/src/verification/rules.ts

@@ -63,6 +63,34 @@ export function evaluateRule(
 			return compiledPattern.test(target) ? rule.decision : null
 		}
 
+		case 'argument_pattern': {
+			if (!compiledPattern) return null
+			if (!nameSet?.has(toolName)) return null
+
+			if (typeof toolInput !== 'object' || toolInput === null) return null
+			const value = (toolInput as Record<string, unknown>)[rule.argument]
+
+			// The subject is the argument's own value, which is the whole point
+			// — `^git push` here means what a reader expects, where the same
+			// pattern against the serialised object could never match.
+			//
+			// Numbers and booleans are rendered rather than skipped, because
+			// `String(4000)` is unambiguous and anchorable. Objects and arrays
+			// are NOT: no string a pattern could match says anything true about
+			// a structured value, and serialising one would put us back where
+			// `custom_pattern` already is. A rule about the shape of an input
+			// is a rule about the tool, and `deny_by_name` is where it belongs.
+			const subject =
+				typeof value === 'string'
+					? value
+					: typeof value === 'number' || typeof value === 'boolean'
+						? String(value)
+						: undefined
+			if (subject === undefined) return null
+
+			return compiledPattern.test(subject) ? rule.decision : null
+		}
+
 		case 'allow_by_tier': {
 			if (toolDef?.tier && rule.tiers.includes(toolDef.tier)) {
 				return 'allow'