@namzu/sdk 0.4.1 → 0.4.3

package/src/bridge/tools/connector/definitions.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `createConnectorExecuteTool(config)` returns a `defineTool`-wrapped
+ *     tool named `connector_execute` that:
+ *     - Returns `{success: false, error: '... not found'}` when instance
+ *       is missing.
+ *     - Returns `{success: false, error: '... not connected'}` when the
+ *       instance exists but `status !== 'connected'`.
+ *     - Returns `{success: false, error: ...}` when `manager.execute`
+ *       itself reports failure; falls back to 'Connector execution
+ *       failed' when the execute error is undefined.
+ *     - On success, stringifies non-string outputs to JSON; strings pass
+ *       through as-is.
+ *     - Attaches `data: { durationMs, metadata }` on success.
+ *   - `createConnectorListTool(config)` returns a tool named
+ *     `connector_list` that:
+ *     - Emits "No connector instances configured." when none exist.
+ *     - Lists each instance with `- <id> (<connectorId>): <name> [<status>]`.
+ *   - `createConnectorTools(config)` returns the pair of tools above.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { ConnectorExecuteResult, ConnectorInstance } from '../../../types/connector/index.js'
+import type { ConnectorId, ConnectorInstanceId } from '../../../types/ids/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+
+import {
+	createConnectorExecuteTool,
+	createConnectorListTool,
+	createConnectorTools,
+} from './definitions.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID = 'ci_abc123' as ConnectorInstanceId
+
+function makeInstance(overrides: Partial<ConnectorInstance> = {}): ConnectorInstance {
+	return {
+		id: IID,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'default' },
+		status: 'connected',
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+function makeManager(overrides: Partial<ConnectorManager> = {}): ConnectorManager {
+	return {
+		getInstance: vi.fn(() => makeInstance()),
+		listInstances: vi.fn(() => [makeInstance()]),
+		execute: vi.fn<() => Promise<ConnectorExecuteResult>>(),
+		...overrides,
+	} as unknown as ConnectorManager
+}
+
+const ctx: ToolContext = {} as ToolContext
+
+describe('createConnectorExecuteTool', () => {
+	it('is named connector_execute', () => {
+		const tool = createConnectorExecuteTool({ manager: makeManager() })
+		expect(tool.name).toBe('connector_execute')
+	})
+
+	it('returns error when instance is missing', async () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => undefined),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/not found/)
+	})
+
+	it('returns error when instance status is not "connected"', async () => {
+		const manager = makeManager({
+			getInstance: vi.fn(() => makeInstance({ status: 'disconnected' })),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/not connected/)
+		expect(result.error).toMatch(/disconnected/)
+	})
+
+	it('wraps manager.execute failure; falls back to "Connector execution failed" on undefined error', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toBe('Connector execution failed')
+	})
+
+	it('carries the explicit error message when provided by manager.execute', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: false,
+			output: undefined,
+			durationMs: 1,
+			error: 'timeout',
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.error).toBe('timeout')
+	})
+
+	it('passes through string outputs as-is', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: 'hi there',
+			durationMs: 10,
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('hi there')
+	})
+
+	it('stringifies non-string outputs + attaches durationMs + metadata to data', async () => {
+		const manager = makeManager()
+		vi.mocked(manager.execute).mockResolvedValueOnce({
+			success: true,
+			output: { answer: 42 },
+			durationMs: 15,
+			metadata: { region: 'us-east-1' },
+		})
+		const tool = createConnectorExecuteTool({ manager })
+		const result = await tool.execute({ instance_id: IID, method: 'request', input: {} }, ctx)
+		expect(result.output).toBe(JSON.stringify({ answer: 42 }, null, 2))
+		expect(result.data).toEqual({ durationMs: 15, metadata: { region: 'us-east-1' } })
+	})
+})
+
+describe('createConnectorListTool', () => {
+	it('is named connector_list + read-only', () => {
+		const tool = createConnectorListTool({ manager: makeManager() })
+		expect(tool.name).toBe('connector_list')
+		expect(tool.isReadOnly?.({})).toBe(true)
+	})
+
+	it('emits "No connector instances configured." when none', async () => {
+		const manager = makeManager({
+			listInstances: vi.fn(() => []),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorListTool({ manager })
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('No connector instances configured.')
+	})
+
+	it('lists every instance with id / connectorId / name / status', async () => {
+		const manager = makeManager({
+			listInstances: vi.fn(() => [
+				makeInstance({ id: IID }),
+				makeInstance({
+					id: 'ci_def' as ConnectorInstanceId,
+					status: 'disconnected',
+				}),
+			]),
+		} as unknown as Partial<ConnectorManager>)
+		const tool = createConnectorListTool({ manager })
+		const result = await tool.execute({}, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toContain(`- ${IID} (${CID}): default [connected]`)
+		expect(result.output).toContain(`- ci_def (${CID}): default [disconnected]`)
+		expect(result.data).toBeDefined()
+	})
+})
+
+describe('createConnectorTools', () => {
+	it('returns both execute + list tools', () => {
+		const tools = createConnectorTools({ manager: makeManager() })
+		expect(tools.map((t) => t.name)).toEqual(['connector_execute', 'connector_list'])
+	})
+})

package/src/bridge/tools/connector/router.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 2):
+ *
+ *   - `new ConnectorToolRouter({ manager })` defaults strategy to
+ *     `'per-method'`.
+ *   - `getTools()` with strategy `'router'`:
+ *     - Returns `[]` when there are no connected instances.
+ *     - Returns a single `connector_execute` routing tool otherwise.
+ *   - `getTools()` with strategy `'per-method'`:
+ *     - Emits one tool per method per connected instance.
+ *     - Catches errors per-instance (logs + skips) — a broken instance
+ *       does not poison the entire tool list.
+ *   - `registerTools(registry)` delegates to `registry.register` for
+ *     every tool and returns the list of names.
+ *   - `unregisterTools(registry, names)` calls `registry.unregister`
+ *     for each name.
+ *   - `refreshTools(registry, previous)` is unregister-then-register in
+ *     one call; returns the new names list.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
+import type { ConnectorRegistry } from '../../../registry/connector/definitions.js'
+import type { ConnectorDefinition, ConnectorInstance } from '../../../types/connector/index.js'
+import type { ConnectorId, ConnectorInstanceId } from '../../../types/ids/index.js'
+import type { ToolRegistryContract } from '../../../types/tool/index.js'
+
+import { ConnectorToolRouter } from './router.js'
+
+const CID = 'conn_http' as ConnectorId
+const IID1 = 'ci_a' as ConnectorInstanceId
+const IID2 = 'ci_b' as ConnectorInstanceId
+
+function makeDefinition(): ConnectorDefinition {
+	return {
+		id: CID,
+		name: 'HTTP',
+		description: 'x',
+		connectionType: 'http',
+		configSchema: z.object({}),
+		methods: [
+			{ name: 'request', description: 'd', inputSchema: z.object({}) },
+			{ name: 'send', description: 'd', inputSchema: z.object({}) },
+		],
+	}
+}
+
+function makeInstance(id: ConnectorInstanceId): ConnectorInstance {
+	return {
+		id,
+		connectorId: CID,
+		config: { connectorId: CID, name: 'x' },
+		status: 'connected',
+		createdAt: Date.now(),
+	}
+}
+
+function makeManager(instances: ConnectorInstance[]): ConnectorManager {
+	const def = makeDefinition()
+	const registry = {
+		getOrThrow: vi.fn(() => def),
+		get: vi.fn(() => def),
+	} as unknown as ConnectorRegistry
+	return {
+		getInstance: vi.fn((id) => instances.find((i) => i.id === id)),
+		getRegistry: vi.fn(() => registry),
+		listConnectedInstances: vi.fn(() => instances),
+		listInstances: vi.fn(() => instances),
+		execute: vi.fn(),
+	} as unknown as ConnectorManager
+}
+
+function makeToolRegistry(): ToolRegistryContract {
+	return {
+		register: vi.fn(),
+		unregister: vi.fn(() => true),
+		clear: vi.fn(),
+	} as unknown as ToolRegistryContract
+}
+
+describe('ConnectorToolRouter', () => {
+	it('defaults strategy to per-method', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const tools = router.getTools()
+		expect(tools.map((t) => t.name)).toEqual([`${CID}_request`, `${CID}_send`])
+	})
+
+	it('router strategy with connected instances emits one connector_execute tool', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([makeInstance(IID1)]),
+			strategy: 'router',
+		})
+		const tools = router.getTools()
+		expect(tools).toHaveLength(1)
+		expect(tools[0]?.name).toBe('connector_execute')
+	})
+
+	it('router strategy with no connected instances returns empty array', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([]),
+			strategy: 'router',
+		})
+		expect(router.getTools()).toEqual([])
+	})
+
+	it('per-method strategy with multiple instances emits methods per-instance', () => {
+		const router = new ConnectorToolRouter({
+			manager: makeManager([makeInstance(IID1), makeInstance(IID2)]),
+		})
+		const tools = router.getTools()
+		expect(tools).toHaveLength(4) // 2 methods * 2 instances
+	})
+
+	it('per-method strategy skips a broken instance + continues with others', () => {
+		const good = makeInstance(IID1)
+		const bad = makeInstance(IID2)
+		const manager = makeManager([good, bad])
+		// make instance IID2 "not found" by overriding getInstance
+		vi.mocked(manager.getInstance).mockImplementation((id) => (id === IID1 ? good : undefined))
+		const router = new ConnectorToolRouter({ manager })
+		const tools = router.getTools()
+		// 2 from IID1; IID2 threw + got caught
+		expect(tools.map((t) => t.name)).toEqual([`${CID}_request`, `${CID}_send`])
+	})
+})
+
+describe('ConnectorToolRouter.registerTools', () => {
+	it('registers every tool and returns the names', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const reg = makeToolRegistry()
+		const names = router.registerTools(reg)
+		expect(names).toEqual([`${CID}_request`, `${CID}_send`])
+		expect(reg.register).toHaveBeenCalledTimes(2)
+	})
+})
+
+describe('ConnectorToolRouter.unregisterTools', () => {
+	it('unregisters each named tool', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([]) })
+		const reg = makeToolRegistry()
+		router.unregisterTools(reg, ['a', 'b'])
+		expect(reg.unregister).toHaveBeenCalledWith('a')
+		expect(reg.unregister).toHaveBeenCalledWith('b')
+		expect(reg.unregister).toHaveBeenCalledTimes(2)
+	})
+})
+
+describe('ConnectorToolRouter.refreshTools', () => {
+	it('unregisters previous names then registers new ones', () => {
+		const router = new ConnectorToolRouter({ manager: makeManager([makeInstance(IID1)]) })
+		const reg = makeToolRegistry()
+		const newNames = router.refreshTools(reg, [`${CID}_old_method`])
+		expect(reg.unregister).toHaveBeenCalledWith(`${CID}_old_method`)
+		expect(newNames).toEqual([`${CID}_request`, `${CID}_send`])
+		expect(reg.register).toHaveBeenCalledTimes(2)
+	})
+})

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')
+		})
+	})
+})