@namzu/sdk 14.0.7 → 15.1.0

package/src/probe/registry.test.ts

@@ -1,523 +0,0 @@
-/**
- * These tests pin the probe CONTRACT, not an internal implementation
- * detail. If the semantics change, change the published documentation
- * first: `docs/sdk/architecture/safety.md`, "Which Way a Gate Fails".
- *
- * They used to point at a session design document that has since been
- * frozen and removed, so the instruction to update it first could not be
- * followed — which is how the fail-open veto kept its ratified status
- * with no surviving argument for it. A contract reference has to name
- * something a reader can still open.
- */
-
-import { describe, expect, it, vi } from 'vitest'
-
-import type { Logger } from '../utils/logger.js'
-
-import { buildProbeContext } from './context.js'
-import { ProbeNameCollisionError } from './errors.js'
-import { createProbeRegistry } from './registry.js'
-
-function makeLogger(): Logger {
-	const self = {
-		info: vi.fn(),
-		warn: vi.fn(),
-		error: vi.fn(),
-		debug: vi.fn(),
-		child: vi.fn(),
-	} as unknown as Logger
-	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
-	return self
-}
-
-describe('ProbeRegistry — typed dispatch', () => {
-	it('fires a typed probe when the event kind matches', () => {
-		const reg = createProbeRegistry()
-		const seen: string[] = []
-		reg.on('tool_executing', (event) => {
-			seen.push(event.toolName)
-		})
-		reg.dispatch(
-			{
-				type: 'tool_executing',
-				runId: 'run_1' as never,
-				toolName: 'fs.read',
-				input: {},
-			} as never,
-			buildProbeContext(),
-		)
-		expect(seen).toEqual(['fs.read'])
-	})
-
-	it('does not fire a typed probe for a different event kind', () => {
-		const reg = createProbeRegistry()
-		const handler = vi.fn()
-		reg.on('tool_executing', handler)
-		reg.dispatch(
-			{ type: 'tool_completed', runId: 'r' as never, toolName: 't', result: 'ok' } as never,
-			buildProbeContext(),
-		)
-		expect(handler).not.toHaveBeenCalled()
-	})
-
-	it('supports array-of-kinds registration', () => {
-		const reg = createProbeRegistry()
-		const seen: string[] = []
-		reg.on(['tool_executing', 'tool_completed'], (event) => {
-			seen.push(event.type)
-		})
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		reg.dispatch(
-			{ type: 'tool_completed', runId: 'r' as never, toolName: 't', result: 'ok' } as never,
-			buildProbeContext(),
-		)
-		expect(seen).toEqual(['tool_executing', 'tool_completed'])
-	})
-
-	it('applies the where filter before the handler', () => {
-		const reg = createProbeRegistry()
-		const handler = vi.fn()
-		reg.on('tool_executing', handler, {
-			where: (event) => event.toolName === 'fs.write',
-		})
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.read', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(handler).not.toHaveBeenCalled()
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.write', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(handler).toHaveBeenCalledTimes(1)
-	})
-})
-
-describe('ProbeRegistry — ordering', () => {
-	it('fires probes in ascending priority; ties break by registration order', () => {
-		const reg = createProbeRegistry()
-		const order: string[] = []
-		reg.on('tool_executing', () => order.push('a'), { priority: 10, name: 'a' })
-		reg.on('tool_executing', () => order.push('b'), { priority: 5, name: 'b' })
-		reg.on('tool_executing', () => order.push('c'), { priority: 10, name: 'c' })
-		reg.on('tool_executing', () => order.push('d'), { priority: 0, name: 'd' })
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(order).toEqual(['d', 'b', 'a', 'c'])
-	})
-
-	it('typed probes fire BEFORE the between-tier callback; catch-all fires AFTER', () => {
-		const reg = createProbeRegistry()
-		const order: string[] = []
-		reg.on('tool_executing', () => order.push('typed'))
-		reg.onAny(() => order.push('any'))
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-			() => order.push('between'),
-		)
-		expect(order).toEqual(['typed', 'between', 'any'])
-	})
-})
-
-describe('ProbeRegistry — name collision + override', () => {
-	it('throws ProbeNameCollisionError on duplicate name without override', () => {
-		const reg = createProbeRegistry()
-		reg.on('tool_executing', () => {}, { name: 'dup' })
-		expect(() => reg.on('tool_executing', () => {}, { name: 'dup' })).toThrow(
-			ProbeNameCollisionError,
-		)
-	})
-
-	it('allows replacing when override: true', () => {
-		const reg = createProbeRegistry()
-		const first = vi.fn()
-		const second = vi.fn()
-		reg.on('tool_executing', first, { name: 'x' })
-		reg.on('tool_executing', second, { name: 'x', override: true })
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(first).not.toHaveBeenCalled()
-		expect(second).toHaveBeenCalledTimes(1)
-	})
-
-	it('unsubscribes the previous entry on override so the name can be reused', () => {
-		const reg = createProbeRegistry()
-		reg.on('tool_executing', () => {}, { name: 'x' })
-		reg.on('tool_executing', () => {}, { name: 'x', override: true })
-		expect(() => reg.on('tool_executing', () => {}, { name: 'x' })).toThrow(ProbeNameCollisionError)
-	})
-})
-
-describe('ProbeRegistry — throw isolation', () => {
-	it('a throwing probe does not suppress later probes', () => {
-		const reg = createProbeRegistry()
-		reg.setLogger(makeLogger())
-		const seen: string[] = []
-		reg.on(
-			'tool_executing',
-			() => {
-				throw new Error('boom')
-			},
-			{ priority: 0, name: 'bad' },
-		)
-		reg.on('tool_executing', () => seen.push('ran'), { priority: 10, name: 'good' })
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(seen).toEqual(['ran'])
-	})
-
-	it('a throwing probe does not suppress the between-tier callback or the catch-all', () => {
-		const reg = createProbeRegistry()
-		reg.setLogger(makeLogger())
-		const order: string[] = []
-		reg.on(
-			'tool_executing',
-			() => {
-				throw new Error('boom')
-			},
-			{ name: 'bad' },
-		)
-		reg.onAny(() => order.push('any'))
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-			() => order.push('between'),
-		)
-		expect(order).toEqual(['between', 'any'])
-	})
-})
-
-describe('ProbeRegistry — frozen event boundary', () => {
-	it('freezes the event before fan-out so probes cannot mutate it', () => {
-		const reg = createProbeRegistry()
-		reg.on('tool_executing', (event) => {
-			expect(() => {
-				;(event as { toolName: string }).toolName = 'mutated'
-			}).toThrow()
-		})
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-	})
-
-	it('later probes see the original event value, not a mutation from an earlier probe', () => {
-		const reg = createProbeRegistry()
-		reg.setLogger(makeLogger())
-		const tampered: string[] = []
-		reg.on(
-			'tool_executing',
-			(event) => {
-				try {
-					;(event as { toolName: string }).toolName = 'mutated'
-				} catch {
-					// expected — frozen
-				}
-			},
-			{ priority: 0 },
-		)
-		reg.on(
-			'tool_executing',
-			(event) => {
-				tampered.push(event.toolName)
-			},
-			{ priority: 10 },
-		)
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'original', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(tampered).toEqual(['original'])
-	})
-})
-
-describe('ProbeRegistry — unsubscribe', () => {
-	it('unsub removes the probe from subsequent dispatches', () => {
-		const reg = createProbeRegistry()
-		const handler = vi.fn()
-		const unsub = reg.on('tool_executing', handler)
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		unsub()
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(handler).toHaveBeenCalledTimes(1)
-	})
-
-	it('unsub on an array-kind probe removes it from every kind it was registered for', () => {
-		const reg = createProbeRegistry()
-		const handler = vi.fn()
-		const unsub = reg.on(['tool_executing', 'tool_completed'], handler)
-		unsub()
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		reg.dispatch(
-			{ type: 'tool_completed', runId: 'r' as never, toolName: 't', result: 'ok' } as never,
-			buildProbeContext(),
-		)
-		expect(handler).not.toHaveBeenCalled()
-	})
-})
-
-describe('ProbeRegistry — catch-all', () => {
-	it('onAny receives every event regardless of kind', () => {
-		const reg = createProbeRegistry()
-		const seen: string[] = []
-		reg.onAny((event) => seen.push(event.type))
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		reg.dispatch(
-			{ type: 'lock_acquired', lockId: 'lock_1' as never, filePath: '/x', owner: 'r' as never },
-			buildProbeContext(),
-		)
-		expect(seen).toEqual(['tool_executing', 'lock_acquired'])
-	})
-})
-
-describe('ProbeRegistry — ctx.isReplay', () => {
-	it('defaults to false when unset', () => {
-		const reg = createProbeRegistry()
-		let seenReplay: boolean | undefined
-		reg.on('tool_executing', (_event, ctx) => {
-			seenReplay = ctx.isReplay
-		})
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(seenReplay).toBe(false)
-	})
-
-	it('carries isReplay:true when the event is from a replayed run', () => {
-		const reg = createProbeRegistry()
-		let seenReplay: boolean | undefined
-		reg.on('tool_executing', (_event, ctx) => {
-			seenReplay = ctx.isReplay
-		})
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext({ isReplay: true }),
-		)
-		expect(seenReplay).toBe(true)
-	})
-})
-
-describe('ProbeRegistry — veto API', () => {
-	it('returns allow when no veto handlers registered', () => {
-		const reg = createProbeRegistry()
-		const outcome = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(outcome.action).toBe('allow')
-		expect(outcome.probeName).toBeUndefined()
-	})
-
-	it('returns deny when a veto handler returns "deny"', () => {
-		const reg = createProbeRegistry()
-		reg.veto('tool_executing', () => 'deny', { name: 'fs-guard' })
-		const outcome = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.write', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(outcome.action).toBe('deny')
-		expect(outcome.probeName).toBe('fs-guard')
-	})
-
-	it('returns deny + reason when handler returns { action: "deny", reason }', () => {
-		const reg = createProbeRegistry()
-		reg.veto('tool_executing', () => ({ action: 'deny', reason: 'outside workspace' }), {
-			name: 'sandbox',
-		})
-		const outcome = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.write', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(outcome.action).toBe('deny')
-		expect(outcome.probeName).toBe('sandbox')
-		expect(outcome.reason).toBe('outside workspace')
-	})
-
-	it('first-deny-wins by ascending priority; subsequent veto handlers still run for audit', () => {
-		const reg = createProbeRegistry()
-		const audit: string[] = []
-		reg.veto(
-			'tool_executing',
-			() => {
-				audit.push('high-priority-allow')
-				return 'allow'
-			},
-			{ priority: 0, name: 'p0-allow' },
-		)
-		reg.veto(
-			'tool_executing',
-			() => {
-				audit.push('mid-priority-deny')
-				return { action: 'deny', reason: 'first' }
-			},
-			{ priority: 5, name: 'p5-deny' },
-		)
-		reg.veto(
-			'tool_executing',
-			() => {
-				audit.push('low-priority-deny')
-				return { action: 'deny', reason: 'second' }
-			},
-			{ priority: 10, name: 'p10-deny' },
-		)
-
-		const outcome = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(outcome.action).toBe('deny')
-		expect(outcome.probeName).toBe('p5-deny')
-		expect(outcome.reason).toBe('first')
-		expect(audit).toEqual(['high-priority-allow', 'mid-priority-deny', 'low-priority-deny'])
-	})
-
-	it('a throwing veto handler denies — it did not say yes', () => {
-		// This asserted `allow`, with no rationale recorded for why. The
-		// result was that the SAME policy inverted its security posture
-		// depending on which surface it was written on: a content guardrail
-		// that throws blocks the run (and says so in its own comment —
-		// "safety is unknown"), while a tool veto that threw waved the tool
-		// through. Nobody chose that asymmetry, which is how it survived.
-		//
-		// The exposure this trades against is real and is the same one the
-		// guardrail already accepted: a buggy veto can refuse every call.
-		// The refusal names the probe, so it is diagnosable; a wrongly
-		// permitted destructive call is not recoverable at all.
-		const reg = createProbeRegistry()
-		reg.setLogger(makeLogger())
-		const audit: string[] = []
-		reg.veto(
-			'tool_executing',
-			() => {
-				audit.push('throw')
-				throw new Error('boom')
-			},
-			{ priority: 0, name: 'bad' },
-		)
-		reg.veto(
-			'tool_executing',
-			() => {
-				audit.push('allow')
-				return 'allow'
-			},
-			{ priority: 5, name: 'good' },
-		)
-
-		const outcome = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(outcome.action).toBe('deny')
-		expect(outcome.probeName).toBe('bad')
-		expect(outcome.reason).toContain('threw while deciding')
-		// Short-circuits: once a decision is missing there is nothing a
-		// later allow can add, and running on would spend handlers to reach
-		// the same answer.
-		expect(audit).toEqual(['throw'])
-	})
-
-	it('still skips a throwing OBSERVER, which was never asked a question', () => {
-		// The asymmetry that IS deliberate. An observer has no answer to
-		// withhold, so taking a run down because a metrics handler crashed
-		// would be the same mistake pointing the other way.
-		const reg = createProbeRegistry()
-		reg.setLogger(makeLogger())
-		const seen: string[] = []
-		reg.on('tool_executing', () => {
-			throw new Error('boom')
-		})
-		reg.on('tool_executing', () => {
-			seen.push('second')
-		})
-
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(seen).toEqual(['second'])
-	})
-
-	it('observe-tier dispatch is independent — veto registration does not fire on dispatch', () => {
-		const reg = createProbeRegistry()
-		const vetoCalls: number[] = []
-		reg.veto(
-			'tool_executing',
-			() => {
-				vetoCalls.push(1)
-				return 'deny'
-			},
-			{ name: 'v' },
-		)
-		reg.dispatch(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(vetoCalls).toEqual([])
-	})
-
-	it('honors where filter on veto registrations', () => {
-		const reg = createProbeRegistry()
-		reg.veto('tool_executing', () => 'deny', {
-			name: 'writes-only',
-			where: (event) => event.toolName.startsWith('fs.write'),
-		})
-
-		const allow = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.read', input: {} } as never,
-			buildProbeContext(),
-		)
-		const deny = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 'fs.write.x', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(allow.action).toBe('allow')
-		expect(deny.action).toBe('deny')
-	})
-
-	it('unsubscribing a veto handler removes it from subsequent queries', () => {
-		const reg = createProbeRegistry()
-		const unsub = reg.veto('tool_executing', () => 'deny', { name: 'g' })
-		const denied = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(denied.action).toBe('deny')
-		unsub()
-		const allowed = reg.queryVeto(
-			{ type: 'tool_executing', runId: 'r' as never, toolName: 't', input: {} } as never,
-			buildProbeContext(),
-		)
-		expect(allowed.action).toBe('allow')
-	})
-
-	it('name collision applies across observe + veto tiers', () => {
-		const reg = createProbeRegistry()
-		reg.on('tool_executing', () => {}, { name: 'shared' })
-		expect(() => reg.veto('tool_executing', () => 'allow', { name: 'shared' })).toThrow(
-			ProbeNameCollisionError,
-		)
-	})
-})

package/src/provider/__tests__/errors.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import {
-	ProviderRequestError,
-	bodySaysContextOverflow,
-	classifyProviderHttpStatus,
-	isCallerAbortError,
-	isProviderRequestError,
-	parseRetryAfterMs,
-	providerVendorError,
-} from '../errors.js'
-
-describe('provider error taxonomy', () => {
-	it('classifies only context-specific limit messages as context overflow', () => {
-		expect(bodySaysContextOverflow('input token count exceeds the maximum for this model')).toBe(
-			true,
-		)
-		expect(bodySaysContextOverflow('tool count exceeds the maximum allowed')).toBe(false)
-		expect(bodySaysContextOverflow('reduce the tool list length')).toBe(false)
-	})
-
-	it('does not treat a generic HTTP 413 as model context overflow', () => {
-		expect(classifyProviderHttpStatus(413, 'request body too large at reverse proxy')).toBe(
-			'bad_request',
-		)
-		expect(classifyProviderHttpStatus(413, 'prompt is too long for requested model')).toBe(
-			'context_overflow',
-		)
-	})
-
-	it('parses both Retry-After forms and rejects stale or invalid values', () => {
-		expect(parseRetryAfterMs('2', 0)).toBe(2000)
-		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:05 GMT', 1000)).toBe(4000)
-		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:01 GMT', 1000)).toBeUndefined()
-		expect(parseRetryAfterMs('later', 0)).toBeUndefined()
-	})
-
-	it('drops the vendor object and its non-enumerable cause entirely', () => {
-		const secret = 'sk-FAKE-DO-NOT-LOG'
-		const vendor = new Error(`invalid api key ${secret}`, {
-			cause: new Error(`response body ${secret}`),
-		})
-		Object.assign(vendor, { status: 401 })
-
-		const classified = providerVendorError({
-			providerId: 'test-provider',
-			error: vendor,
-		})
-
-		expect(classified).toMatchObject({
-			name: 'ProviderRequestError',
-			kind: 'auth',
-			status: 401,
-			providerId: 'test-provider',
-		})
-		expect(classified.message).not.toContain(secret)
-		expect('cause' in classified).toBe(false)
-	})
-
-	it('recognizes a caller abort only when that signal actually aborted', () => {
-		const controller = new AbortController()
-		const sdkAbort = Object.assign(new Error('request aborted'), {
-			name: 'APIUserAbortError',
-		})
-
-		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(false)
-		controller.abort(new Error('user stopped'))
-		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(true)
-		expect(isCallerAbortError(controller.signal.reason, controller.signal)).toBe(true)
-	})
-
-	it('requires the complete structural contract when SDK copies differ', () => {
-		const classified = new ProviderRequestError({
-			kind: 'server',
-			providerId: 'test-provider',
-		})
-		expect(isProviderRequestError(classified)).toBe(true)
-
-		const impostor = Object.assign(new Error('not classified'), {
-			name: 'ProviderRequestError',
-			kind: 'anything',
-		})
-		expect(isProviderRequestError(impostor)).toBe(false)
-	})
-})