@namzu/sdk 0.4.2 → 0.4.4

package/src/bus/breaker.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `canExecute(runId)` on an unknown runId returns true (no breaker
+ *     means no constraint).
+ *   - `recordFailure(runId)` lazily creates a breaker entry in `closed`
+ *     state for unknown runIds; `recordSuccess(runId)` is a no-op when
+ *     no entry exists.
+ *   - Consecutive failures: after `failureThreshold` calls in a row
+ *     without intervening success, `state` → `open`, `trippedAt` set,
+ *     single `breaker_tripped` event.
+ *   - In `open` state, `canExecute` returns false until `resetTimeoutMs`
+ *     has elapsed since `trippedAt`; at that point it transitions to
+ *     `half_open`, emits `breaker_half_open`, and returns true.
+ *   - In `half_open`, `canExecute` keeps returning true (the probe is
+ *     allowed more than once) until the next `recordSuccess` closes the
+ *     breaker or the next `recordFailure` re-trips it.
+ *   - `recordSuccess` in `half_open` → `closed`; emits
+ *     `breaker_probe_success` then `breaker_reset` (two events, in
+ *     that order).
+ *   - `recordFailure` in `half_open` → `open`; emits
+ *     `breaker_probe_failure` then `breaker_tripped` (two events).
+ *     The `consecutiveFailures` count carries over (not reset by the
+ *     half-open probe cycle).
+ *   - `recordSuccess` in `closed` resets `consecutiveFailures` to 0 and
+ *     updates `lastSuccessAt`; emits nothing.
+ *   - `recordSuccess` while `open`: logs a warning, does NOT change
+ *     state (behaviour is "discarded"); emits nothing.
+ *   - `recordFailure` while `open`: no additional events; state stays
+ *     open (consecutive counter does NOT advance from `recordFailure`
+ *     while open in the current implementation either — see test).
+ *   - `reset(runId)` forces the breaker to `closed` regardless of prior
+ *     state; emits `breaker_reset`; clears `consecutiveFailures` and
+ *     `trippedAt` but preserves `lastFailureAt` / `lastSuccessAt`.
+ *   - `listTripped()` returns snapshots for every breaker in `open` or
+ *     `half_open`; closed breakers are excluded.
+ *   - Breaker entries are keyed per-`RunId`; state does not leak across
+ *     runs. No per-tenant dimension (design.md §2.1 aspirational).
+ */
+
+import fc from 'fast-check'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { CircuitBreaker } from './breaker.js'
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+const THRESHOLD = 5
+const RESET_MS = 30_000
+
+describe('CircuitBreaker', () => {
+	let events: AgentBusEvent[]
+	let breaker: CircuitBreaker
+
+	beforeEach(() => {
+		events = []
+		breaker = new CircuitBreaker(makeLogger(), (e) => events.push(e), THRESHOLD, RESET_MS)
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	describe('canExecute', () => {
+		it('returns true for an unknown runId (no breaker entry yet)', () => {
+			expect(breaker.canExecute(runId(1))).toBe(true)
+		})
+	})
+
+	describe('recordFailure', () => {
+		it('lazily creates a closed breaker entry for unknown runIds', () => {
+			breaker.recordFailure(runId(1))
+			const snap = breaker.getSnapshot(runId(1))
+			expect(snap?.state).toBe('closed')
+			expect(snap?.consecutiveFailures).toBe(1)
+		})
+
+		it('trips after exactly `failureThreshold` consecutive failures', () => {
+			for (let i = 0; i < THRESHOLD - 1; i++) {
+				breaker.recordFailure(runId(1))
+			}
+			expect(breaker.getSnapshot(runId(1))?.state).toBe('closed')
+			expect(events.filter((e) => e.type === 'breaker_tripped')).toHaveLength(0)
+
+			breaker.recordFailure(runId(1))
+			expect(breaker.getSnapshot(runId(1))?.state).toBe('open')
+			const trippedEvents = events.filter((e) => e.type === 'breaker_tripped')
+			expect(trippedEvents).toHaveLength(1)
+			if (trippedEvents[0]?.type === 'breaker_tripped') {
+				expect(trippedEvents[0].consecutiveFailures).toBe(THRESHOLD)
+			}
+		})
+
+		it('trips exactly once — further failures in `open` emit no new breaker_tripped', () => {
+			for (let i = 0; i < THRESHOLD; i++) breaker.recordFailure(runId(1))
+			events.length = 0
+
+			breaker.recordFailure(runId(1))
+			breaker.recordFailure(runId(1))
+			expect(events).toEqual([])
+		})
+
+		it('property: any N ≥ threshold consecutive failures trips exactly once', () => {
+			fc.assert(
+				fc.property(fc.integer({ min: THRESHOLD, max: THRESHOLD * 4 }), (n) => {
+					const local = new CircuitBreaker(makeLogger(), () => {}, THRESHOLD, RESET_MS)
+					for (let i = 0; i < n; i++) local.recordFailure(runId(999))
+					expect(local.getSnapshot(runId(999))?.state).toBe('open')
+				}),
+				{ numRuns: 25 },
+			)
+		})
+
+		it('property: any N < threshold keeps the breaker closed', () => {
+			fc.assert(
+				fc.property(fc.integer({ min: 0, max: THRESHOLD - 1 }), (n) => {
+					const local = new CircuitBreaker(makeLogger(), () => {}, THRESHOLD, RESET_MS)
+					for (let i = 0; i < n; i++) local.recordFailure(runId(888))
+					const snap = local.getSnapshot(runId(888))
+					if (n === 0) {
+						expect(snap).toBeUndefined()
+					} else {
+						expect(snap?.state).toBe('closed')
+					}
+				}),
+				{ numRuns: 25 },
+			)
+		})
+	})
+
+	describe('recordSuccess', () => {
+		it('is a no-op on an unknown runId — no breaker entry created', () => {
+			breaker.recordSuccess(runId(42))
+			expect(breaker.getSnapshot(runId(42))).toBeUndefined()
+			expect(events).toEqual([])
+		})
+
+		it('resets consecutiveFailures to 0 without changing closed state', () => {
+			breaker.recordFailure(runId(1))
+			breaker.recordFailure(runId(1))
+			breaker.recordSuccess(runId(1))
+			const snap = breaker.getSnapshot(runId(1))
+			expect(snap?.state).toBe('closed')
+			expect(snap?.consecutiveFailures).toBe(0)
+			expect(snap?.lastSuccessAt).toBeDefined()
+		})
+
+		it('is discarded (warned, no state change) when called while breaker is open', () => {
+			for (let i = 0; i < THRESHOLD; i++) breaker.recordFailure(runId(1))
+			events.length = 0
+
+			breaker.recordSuccess(runId(1))
+			expect(breaker.getSnapshot(runId(1))?.state).toBe('open')
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('open → half_open transition', () => {
+		it('transitions to half_open after resetTimeoutMs elapsed; emits breaker_half_open', () => {
+			vi.useFakeTimers()
+			const trip = new CircuitBreaker(makeLogger(), (e) => events.push(e), THRESHOLD, RESET_MS)
+			for (let i = 0; i < THRESHOLD; i++) trip.recordFailure(runId(1))
+			events.length = 0
+
+			expect(trip.canExecute(runId(1))).toBe(false)
+
+			vi.advanceTimersByTime(RESET_MS - 1)
+			expect(trip.canExecute(runId(1))).toBe(false)
+
+			vi.advanceTimersByTime(1)
+			expect(trip.canExecute(runId(1))).toBe(true)
+			expect(trip.getSnapshot(runId(1))?.state).toBe('half_open')
+			expect(events).toEqual([{ type: 'breaker_half_open', agentRunId: runId(1) }])
+		})
+
+		it('canExecute in half_open keeps returning true until success or failure resolves', () => {
+			vi.useFakeTimers()
+			const trip = new CircuitBreaker(makeLogger(), () => {}, THRESHOLD, RESET_MS)
+			for (let i = 0; i < THRESHOLD; i++) trip.recordFailure(runId(1))
+			vi.advanceTimersByTime(RESET_MS)
+			trip.canExecute(runId(1)) // flip to half_open
+			expect(trip.canExecute(runId(1))).toBe(true)
+			expect(trip.canExecute(runId(1))).toBe(true)
+		})
+	})
+
+	describe('half_open → closed / open resolution', () => {
+		function setupHalfOpen(): CircuitBreaker {
+			vi.useFakeTimers()
+			const b = new CircuitBreaker(makeLogger(), (e) => events.push(e), THRESHOLD, RESET_MS)
+			for (let i = 0; i < THRESHOLD; i++) b.recordFailure(runId(1))
+			vi.advanceTimersByTime(RESET_MS)
+			b.canExecute(runId(1)) // flip
+			events.length = 0
+			return b
+		}
+
+		it('recordSuccess in half_open closes the breaker + emits probe_success then reset', () => {
+			const b = setupHalfOpen()
+			b.recordSuccess(runId(1))
+			expect(b.getSnapshot(runId(1))?.state).toBe('closed')
+			expect(b.getSnapshot(runId(1))?.consecutiveFailures).toBe(0)
+			expect(events).toEqual([
+				{ type: 'breaker_probe_success', agentRunId: runId(1) },
+				{ type: 'breaker_reset', agentRunId: runId(1) },
+			])
+		})
+
+		it('recordFailure in half_open re-trips + emits probe_failure then tripped', () => {
+			const b = setupHalfOpen()
+			b.recordFailure(runId(1))
+			expect(b.getSnapshot(runId(1))?.state).toBe('open')
+			expect(events).toEqual([
+				{ type: 'breaker_probe_failure', agentRunId: runId(1) },
+				{
+					type: 'breaker_tripped',
+					agentRunId: runId(1),
+					consecutiveFailures: THRESHOLD + 1,
+				},
+			])
+		})
+	})
+
+	describe('reset', () => {
+		it('forces a tripped breaker back to closed + emits breaker_reset', () => {
+			for (let i = 0; i < THRESHOLD; i++) breaker.recordFailure(runId(1))
+			events.length = 0
+
+			breaker.reset(runId(1))
+			const snap = breaker.getSnapshot(runId(1))
+			expect(snap?.state).toBe('closed')
+			expect(snap?.consecutiveFailures).toBe(0)
+			expect(snap?.trippedAt).toBeUndefined()
+			expect(events).toEqual([{ type: 'breaker_reset', agentRunId: runId(1) }])
+		})
+
+		it('is a no-op on an unknown runId (no event)', () => {
+			breaker.reset(runId(999))
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('per-runId isolation', () => {
+		it('tripping one runId does not affect another', () => {
+			for (let i = 0; i < THRESHOLD; i++) breaker.recordFailure(runId(1))
+			expect(breaker.getSnapshot(runId(1))?.state).toBe('open')
+			expect(breaker.canExecute(runId(2))).toBe(true)
+			expect(breaker.getSnapshot(runId(2))).toBeUndefined()
+		})
+	})
+
+	describe('listTripped', () => {
+		it('returns only open + half_open breakers; excludes closed', () => {
+			for (let i = 0; i < THRESHOLD; i++) breaker.recordFailure(runId(1))
+			breaker.recordFailure(runId(2))
+
+			const tripped = breaker.listTripped()
+			expect(tripped).toHaveLength(1)
+			expect(tripped[0]?.agentRunId).toBe(runId(1))
+			expect(tripped[0]?.state).toBe('open')
+		})
+	})
+})

package/src/bus/index.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `AgentBus` composes a `FileLockManager`, `EditOwnershipTracker`,
+ *     and `CircuitBreaker`; every event each of them emits is
+ *     broadcast to bus-level listeners.
+ *   - `on(listener)` returns an unsubscribe function; invoking it
+ *     removes the listener, and subsequent events skip it.
+ *   - Listeners receive events in the order they are emitted
+ *     (preserved by `Set` insertion-order iteration). Multi-listener
+ *     fan-out: every listener sees every event.
+ *   - A throwing listener does NOT cascade — other listeners still
+ *     receive the same event, and the bus logs the error via
+ *     `log.error`.
+ *   - No per-tenant routing — events are global to the bus instance
+ *     (design.md §2.1 aspirational per-tenant ordering does not
+ *     exist; see §2.7).
+ *   - `cleanupAgent(runId)` releases every lock + every ownership +
+ *     resets the breaker for that runId. Counts are logged; the
+ *     method does not return them.
+ *   - `maintenance()` expires stale locks via `locks.expireStale()`
+ *     and logs the count when non-zero.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { AgentBus } from './index.js'
+
+function makeLogger(): Logger {
+	// Recursive self-returning child — AgentBus nests FileLockManager /
+	// EditOwnershipTracker / CircuitBreaker, each of which chains a
+	// `log.child(...)` call in its constructor.
+	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
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+describe('AgentBus', () => {
+	let bus: AgentBus
+	let log: Logger
+
+	beforeEach(() => {
+		log = makeLogger()
+		bus = new AgentBus(log, { lockTimeoutMs: 60_000, lockAcquireTimeoutMs: 60 })
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	describe('listener lifecycle', () => {
+		it('broadcasts events to every registered listener', async () => {
+			const a: AgentBusEvent[] = []
+			const b: AgentBusEvent[] = []
+			bus.on((e) => a.push(e))
+			bus.on((e) => b.push(e))
+
+			await bus.locks.acquire('/tmp/f.txt', runId(1))
+
+			expect(a.length).toBeGreaterThan(0)
+			expect(b).toEqual(a)
+		})
+
+		it('unsubscribe removes the listener; later events skip it', async () => {
+			const seen: AgentBusEvent[] = []
+			const off = bus.on((e) => seen.push(e))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			const countAfterFirst = seen.length
+			expect(countAfterFirst).toBeGreaterThan(0)
+
+			off()
+			await bus.locks.acquire('/tmp/b.txt', runId(1))
+			expect(seen.length).toBe(countAfterFirst)
+		})
+
+		it('preserves emission order per listener (Set insertion-order iteration)', async () => {
+			const seen: string[] = []
+			bus.on((e) => seen.push(e.type))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			bus.ownership.release('/tmp/a.txt', runId(1))
+			bus.locks.release('/tmp/a.txt', runId(1))
+
+			expect(seen).toEqual([
+				'lock_acquired',
+				'ownership_claimed',
+				'ownership_released',
+				'lock_released',
+			])
+		})
+
+		it('a throwing listener does not cascade — other listeners still fire', async () => {
+			const good: AgentBusEvent[] = []
+			bus.on(() => {
+				throw new Error('boom')
+			})
+			bus.on((e) => good.push(e))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			expect(good.length).toBeGreaterThan(0)
+		})
+	})
+
+	describe('composed sub-components', () => {
+		it('CircuitBreaker events flow through the bus listener', () => {
+			const seen: AgentBusEvent[] = []
+			bus.on((e) => seen.push(e))
+
+			for (let i = 0; i < 5; i++) bus.breaker.recordFailure(runId(1))
+			expect(seen.filter((e) => e.type === 'breaker_tripped')).toHaveLength(1)
+		})
+
+		it('EditOwnershipTracker events flow through the bus listener', () => {
+			const seen: AgentBusEvent[] = []
+			bus.on((e) => seen.push(e))
+
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			bus.ownership.transfer('/tmp/a.txt', runId(1), runId(2))
+			bus.ownership.release('/tmp/a.txt', runId(2))
+
+			expect(seen.map((e) => e.type)).toEqual([
+				'ownership_claimed',
+				'ownership_transferred',
+				'ownership_released',
+			])
+		})
+	})
+
+	describe('cleanupAgent', () => {
+		it('releases locks + ownerships + resets breaker for the runId', async () => {
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			for (let i = 0; i < 5; i++) bus.breaker.recordFailure(runId(1))
+			expect(bus.breaker.getSnapshot(runId(1))?.state).toBe('open')
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(true)
+
+			bus.cleanupAgent(runId(1))
+
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(false)
+			expect(bus.ownership.getOwner('/tmp/a.txt')).toBeUndefined()
+			expect(bus.breaker.getSnapshot(runId(1))?.state).toBe('closed')
+		})
+
+		it('does not affect other runIds', async () => {
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			await bus.locks.acquire('/tmp/b.txt', runId(2))
+
+			bus.cleanupAgent(runId(1))
+
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(false)
+			expect(bus.locks.isLocked('/tmp/b.txt')).toBe(true)
+			expect(bus.locks.getHolder('/tmp/b.txt')).toBe(runId(2))
+		})
+	})
+
+	describe('maintenance', () => {
+		it('sweeps expired locks', async () => {
+			vi.useFakeTimers()
+			const b = new AgentBus(makeLogger(), { lockTimeoutMs: 500, lockAcquireTimeoutMs: 30 })
+			await b.locks.acquire('/tmp/a.txt', runId(1))
+			vi.advanceTimersByTime(501)
+
+			b.maintenance()
+			expect(b.locks.isLocked('/tmp/a.txt')).toBe(false)
+		})
+	})
+})

package/src/bus/index.ts

@@ -5,6 +5,8 @@ import {
 	DEFAULT_LOCK_TIMEOUT_MS,
 	DEFAULT_MAX_LOCKS_PER_AGENT,
 } from '../constants/bus/index.js'
+import { buildProbeContext } from '../probe/context.js'
+import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
 import type { AgentBusEvent, AgentBusEventListener } from '../types/bus/index.js'
 import type { RunId } from '../types/ids/index.js'
 import type { Logger } from '../utils/logger.js'
@@ -39,10 +41,17 @@ export class AgentBus {
 	private readonly listeners: Set<AgentBusEventListener> = new Set()
 	private readonly log: Logger
 	private readonly config: AgentBusConfig
+	private readonly probes: ProbeRegistry
 
-	constructor(log: Logger, config: Partial<AgentBusConfig> = {}) {
+	constructor(
+		log: Logger,
+		config: Partial<AgentBusConfig> = {},
+		probeRegistry: ProbeRegistry = defaultProbeRegistry,
+	) {
 		this.config = { ...DEFAULT_AGENT_BUS_CONFIG, ...config }
 		this.log = log.child({ component: 'AgentBus' })
+		this.probes = probeRegistry
+		this.probes.setLogger(log)
 
 		const emitFn = (event: AgentBusEvent): void => this.emit(event)
 
@@ -70,16 +79,18 @@ export class AgentBus {
 	}
 
 	private emit(event: AgentBusEvent): void {
-		for (const listener of this.listeners) {
-			try {
-				listener(event)
-			} catch (error) {
-				this.log.error('event listener threw', {
-					eventType: event.type,
-					error: error instanceof Error ? error.message : String(error),
-				})
+		this.probes.dispatch(event, buildProbeContext(), () => {
+			for (const listener of this.listeners) {
+				try {
+					listener(event)
+				} catch (error) {
+					this.log.error('event listener threw', {
+						eventType: event.type,
+						error: error instanceof Error ? error.message : String(error),
+					})
+				}
 			}
-		}
+		})
 	}
 
 	cleanupAgent(runId: RunId): void {