@namzu/sdk 0.4.1 → 0.4.3

package/src/advisory/context.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 6):
+ *
+ *   - `AdvisoryContext` composes a registry + executor + evaluator +
+ *     optional budget. It is a dumb container + a call-history log.
+ *   - `recordCall(record)` appends to `callHistory` in call order.
+ *   - `getBudgetStatus()`:
+ *     - `used` = `callHistory.length`.
+ *     - `total` = `budget?.maxCallsPerRun` (undefined when no budget).
+ *     - `remaining` = total − used when total defined; undefined else.
+ *   - `checkBudget()`:
+ *     - Allowed when no budget OR remaining > 0.
+ *     - Denied with reason when remaining ≤ 0.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { AdvisoryCallRecord } from '../types/advisory/index.js'
+
+import { AdvisoryContext } from './context.js'
+import type { TriggerEvaluator } from './evaluator.js'
+import type { AdvisoryExecutor } from './executor.js'
+import type { AdvisorRegistry } from './registry.js'
+
+function stubRegistry(): AdvisorRegistry {
+	return {} as unknown as AdvisorRegistry
+}
+
+function stubExecutor(): AdvisoryExecutor {
+	return {} as unknown as AdvisoryExecutor
+}
+
+function stubEvaluator(): TriggerEvaluator {
+	return {} as unknown as TriggerEvaluator
+}
+
+function callRecord(id: string): AdvisoryCallRecord {
+	return {
+		advisorId: id,
+		request: { question: 'q' },
+		result: { advice: 'a' },
+		usage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		cost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+		durationMs: 0,
+		iteration: 0,
+		timestamp: Date.now(),
+	}
+}
+
+describe('AdvisoryContext', () => {
+	it('starts with empty callHistory', () => {
+		const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator())
+		expect(ctx.callHistory).toEqual([])
+	})
+
+	it('recordCall appends in order', () => {
+		const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator())
+		ctx.recordCall(callRecord('a'))
+		ctx.recordCall(callRecord('b'))
+		expect(ctx.callHistory.map((r) => r.advisorId)).toEqual(['a', 'b'])
+	})
+
+	describe('getBudgetStatus', () => {
+		it('no budget → total + remaining undefined; used reflects history length', () => {
+			const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator())
+			ctx.recordCall(callRecord('a'))
+			expect(ctx.getBudgetStatus()).toEqual({ used: 1, total: undefined, remaining: undefined })
+		})
+
+		it('with budget → total + remaining computed', () => {
+			const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator(), {
+				maxCallsPerRun: 3,
+			})
+			ctx.recordCall(callRecord('a'))
+			expect(ctx.getBudgetStatus()).toEqual({ used: 1, total: 3, remaining: 2 })
+		})
+	})
+
+	describe('checkBudget', () => {
+		it('allowed when no budget', () => {
+			const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator())
+			expect(ctx.checkBudget()).toEqual({ allowed: true })
+		})
+
+		it('allowed when remaining > 0', () => {
+			const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator(), {
+				maxCallsPerRun: 2,
+			})
+			ctx.recordCall(callRecord('a'))
+			expect(ctx.checkBudget()).toEqual({ allowed: true })
+		})
+
+		it('denied when remaining <= 0', () => {
+			const ctx = new AdvisoryContext(stubRegistry(), stubExecutor(), stubEvaluator(), {
+				maxCallsPerRun: 1,
+			})
+			ctx.recordCall(callRecord('a'))
+			const result = ctx.checkBudget()
+			expect(result.allowed).toBe(false)
+			expect(result.reason).toMatch(/budget exhausted/)
+		})
+	})
+})

package/src/advisory/evaluator.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 6):
+ *
+ *   - Constructor filters OUT triggers with `enabled: false` + sorts
+ *     by `priority` desc (higher first). Triggers without priority
+ *     sort at 0.
+ *   - `evaluate(state)` returns every trigger whose condition matches
+ *     AND whose cooldown has elapsed. Order reflects the sorted
+ *     trigger list.
+ *   - Budget exhausted (callCount ≥ maxCallsPerRun) → evaluate returns [].
+ *   - `recordFiring(id, iteration)` updates both `lastFiredMap` (for
+ *     cooldown) and `callCount` (for budget).
+ *   - Condition matchers:
+ *     - `on_error`: matches iff state.lastError is set; if categories
+ *       are given, requires at least one category substring match.
+ *     - `on_iteration`: `state.iteration % everyN === 0`.
+ *     - `on_context_percent`: `state.contextWindowPercent >= threshold`.
+ *     - `on_tool_category`: `state.lastToolCategory` present + in
+ *       `condition.categories`.
+ *     - `on_cost_percent`: costBudgetPercent present + ≥ threshold.
+ *     - `on_complexity`: totalToolCalls ≥ toolCallThreshold.
+ *     - `custom`: calls the predicate.
+ *   - Cooldown: trigger does NOT fire if `iteration - lastFired <
+ *     cooldownIterations`. No cooldown → always eligible.
+ *
+ *   - **Purity:** evaluate() is pure relative to the advisory phase —
+ *     it returns triggers; it does NOT inject messages or mutate
+ *     external state. The injection happens in the advisory phase
+ *     (runtime/query/iteration/phases/advisory.ts), which pushes a
+ *     user message via `runMgr.pushMessage`. That file is OUT of
+ *     scope for this test file (covered by the phase test).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisoryTrigger, TriggerEvaluationState } from '../types/advisory/index.js'
+
+import { TriggerEvaluator } from './evaluator.js'
+
+function trigger(id: string, overrides: Partial<AdvisoryTrigger> = {}): AdvisoryTrigger {
+	return {
+		id,
+		condition: { type: 'on_iteration', everyN: 1 },
+		...overrides,
+	}
+}
+
+function state(overrides: Partial<TriggerEvaluationState> = {}): TriggerEvaluationState {
+	return {
+		iteration: 1,
+		totalToolCalls: 0,
+		totalTokens: 0,
+		contextWindowPercent: 0,
+		totalCostUsd: 0,
+		costBudgetPercent: undefined,
+		lastError: undefined,
+		lastToolCategory: undefined,
+		advisoryCallCount: 0,
+		...overrides,
+	}
+}
+
+describe('TriggerEvaluator — constructor', () => {
+	it('filters out triggers with enabled: false', () => {
+		const e = new TriggerEvaluator([trigger('a'), trigger('b', { enabled: false })])
+		expect(e.evaluate(state()).map((t) => t.id)).toEqual(['a'])
+	})
+
+	it('sorts triggers by priority descending', () => {
+		const e = new TriggerEvaluator([
+			trigger('low', { priority: 1 }),
+			trigger('high', { priority: 10 }),
+			trigger('mid', { priority: 5 }),
+		])
+		expect(e.evaluate(state()).map((t) => t.id)).toEqual(['high', 'mid', 'low'])
+	})
+})
+
+describe('TriggerEvaluator — budget', () => {
+	it('returns [] when callCount >= maxCallsPerRun', () => {
+		const e = new TriggerEvaluator([trigger('a')], { maxCallsPerRun: 1 })
+		e.recordFiring('a', 1)
+		expect(e.evaluate(state({ iteration: 2 }))).toEqual([])
+	})
+
+	it('ignores budget when maxCallsPerRun is not set', () => {
+		const e = new TriggerEvaluator([trigger('a')])
+		e.recordFiring('a', 1)
+		e.recordFiring('a', 2)
+		expect(e.evaluate(state({ iteration: 3 })).length).toBeGreaterThan(0)
+	})
+})
+
+describe('TriggerEvaluator — cooldown', () => {
+	it('blocks triggers in their cooldown window', () => {
+		const e = new TriggerEvaluator([trigger('a', { cooldownIterations: 3 })])
+		e.recordFiring('a', 1)
+		expect(e.evaluate(state({ iteration: 2 })).map((t) => t.id)).toEqual([])
+		expect(e.evaluate(state({ iteration: 3 })).map((t) => t.id)).toEqual([])
+		expect(e.evaluate(state({ iteration: 4 })).map((t) => t.id)).toEqual(['a'])
+	})
+
+	it('always fires when no cooldown is configured', () => {
+		const e = new TriggerEvaluator([trigger('a')])
+		e.recordFiring('a', 1)
+		expect(e.evaluate(state({ iteration: 2 })).map((t) => t.id)).toEqual(['a'])
+	})
+})
+
+describe('TriggerEvaluator — condition matchers', () => {
+	it('on_error: requires lastError to be set', () => {
+		const e = new TriggerEvaluator([trigger('t', { condition: { type: 'on_error' } })])
+		expect(e.evaluate(state())).toEqual([])
+		expect(e.evaluate(state({ lastError: 'boom' })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('on_error with categories: at least one substring match', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', { condition: { type: 'on_error', categories: ['timeout', 'permission'] } }),
+		])
+		expect(e.evaluate(state({ lastError: 'Connection timeout' })).map((t) => t.id)).toEqual(['t'])
+		expect(e.evaluate(state({ lastError: 'Syntax error' }))).toEqual([])
+	})
+
+	it('on_iteration: iteration % everyN === 0', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', { condition: { type: 'on_iteration', everyN: 3 } }),
+		])
+		expect(e.evaluate(state({ iteration: 1 }))).toEqual([])
+		expect(e.evaluate(state({ iteration: 3 })).map((t) => t.id)).toEqual(['t'])
+		expect(e.evaluate(state({ iteration: 6 })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('on_context_percent: contextWindowPercent >= threshold', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', { condition: { type: 'on_context_percent', threshold: 80 } }),
+		])
+		expect(e.evaluate(state({ contextWindowPercent: 70 }))).toEqual([])
+		expect(e.evaluate(state({ contextWindowPercent: 80 })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('on_tool_category: lastToolCategory present + in categories list', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', {
+				condition: { type: 'on_tool_category', categories: ['network', 'filesystem'] },
+			}),
+		])
+		expect(e.evaluate(state())).toEqual([])
+		expect(e.evaluate(state({ lastToolCategory: 'other' }))).toEqual([])
+		expect(e.evaluate(state({ lastToolCategory: 'network' })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('on_cost_percent: costBudgetPercent present + >= threshold', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', { condition: { type: 'on_cost_percent', threshold: 75 } }),
+		])
+		expect(e.evaluate(state())).toEqual([]) // undefined costBudgetPercent
+		expect(e.evaluate(state({ costBudgetPercent: 50 }))).toEqual([])
+		expect(e.evaluate(state({ costBudgetPercent: 80 })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('on_complexity: totalToolCalls >= toolCallThreshold', () => {
+		const e = new TriggerEvaluator([
+			trigger('t', { condition: { type: 'on_complexity', toolCallThreshold: 10 } }),
+		])
+		expect(e.evaluate(state({ totalToolCalls: 5 }))).toEqual([])
+		expect(e.evaluate(state({ totalToolCalls: 10 })).map((t) => t.id)).toEqual(['t'])
+	})
+
+	it('custom: calls the predicate with state', () => {
+		const predicate = vi.fn(() => true)
+		const e = new TriggerEvaluator([trigger('t', { condition: { type: 'custom', predicate } })])
+		const s = state({ iteration: 42 })
+		expect(e.evaluate(s).map((t) => t.id)).toEqual(['t'])
+		expect(predicate).toHaveBeenCalledWith(s)
+	})
+})
+
+describe('TriggerEvaluator — recordFiring', () => {
+	it('updates lastFiredMap + callCount', () => {
+		const e = new TriggerEvaluator([trigger('a', { cooldownIterations: 5 })], {
+			maxCallsPerRun: 2,
+		})
+		e.recordFiring('a', 1)
+		// cooldown active: no fires in iterations 2–5
+		expect(e.evaluate(state({ iteration: 2 }))).toEqual([])
+		// cooldown lifted at 6, but budget allows one more
+		e.recordFiring('a', 6)
+		// budget exhausted
+		expect(e.evaluate(state({ iteration: 11 }))).toEqual([])
+	})
+})

package/src/advisory/executor.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 6):
+ *
+ *   - `AdvisoryExecutor.consult(advisor, request, callCtx)`:
+ *     - Builds a system prompt (see buildSystemPrompt tests).
+ *     - Builds a context message block (see buildContext tests).
+ *     - Concatenates `[system, ...context, user(question)]` and calls
+ *       `advisor.provider.chat(...)` with `toolChoice: 'none'`.
+ *     - Parses the response via a passthrough `{ advice: rawContent }`
+ *       shape (no structured parsing yet — advisor.ts line 166-168).
+ *     - Returns `{result, usage, cost, durationMs}`. `cost` is a
+ *       zero-value `CostInfo` — pricing is provider-specific and not
+ *       applied here.
+ *
+ *   - `buildSystemPrompt` priority:
+ *     1. `advisor.systemPrompt` (verbatim).
+ *     2. `advisor.persona` (via `assembleSystemPrompt`).
+ *     3. Fallback: "You are <name>, an advisory agent." + optional
+ *        domains line + "Provide concise, actionable advice..."
+ *
+ *   - `buildContext`:
+ *     - Returns [] when `request.includeContext === false`.
+ *     - Includes workingStateSummary when present.
+ *     - Includes toolCatalog names when present + non-empty.
+ *     - Includes truncated conversation context (most-recent-first
+ *       walk, bounded by `advisor.maxContextTokens * CHARS_PER_TOKEN`).
+ *     - Returns [] when no context parts were assembled.
+ *
+ *   - `truncateMessages(msgs, maxTokens)` walks right-to-left and
+ *     includes messages until the char budget is exhausted (in token
+ *     terms). Returns the included subset preserving original order.
+ *     No limit when `maxTokens` is undefined.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisorDefinition } from '../types/advisory/config.js'
+import type { AdvisoryRequest } from '../types/advisory/result.js'
+import type { Message } from '../types/message/index.js'
+import type {
+	ChatCompletionParams,
+	ChatCompletionResponse,
+	LLMProvider,
+} from '../types/provider/index.js'
+
+import { type AdvisoryCallContext, AdvisoryExecutor } from './executor.js'
+
+function mockProvider(response: Partial<ChatCompletionResponse> = {}): LLMProvider {
+	const chat = vi.fn<(p: ChatCompletionParams) => Promise<ChatCompletionResponse>>(async () => ({
+		id: 'resp_1',
+		model: 'm',
+		message: { role: 'assistant', content: 'advice text' },
+		usage: {
+			promptTokens: 100,
+			completionTokens: 50,
+			totalTokens: 150,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		finishReason: 'stop',
+		...response,
+	}))
+	return {
+		id: 'mock',
+		name: 'Mock',
+		chat,
+		chatStream: vi.fn(),
+	} as unknown as LLMProvider
+}
+
+function advisor(overrides: Partial<AdvisorDefinition> = {}): AdvisorDefinition {
+	return {
+		id: 'adv',
+		name: 'Adv',
+		provider: mockProvider(),
+		model: 'm',
+		...overrides,
+	}
+}
+
+function ctx(overrides: Partial<AdvisoryCallContext> = {}): AdvisoryCallContext {
+	return {
+		messages: [],
+		iteration: 1,
+		...overrides,
+	}
+}
+
+const req: AdvisoryRequest = { question: 'what next?' }
+
+describe('AdvisoryExecutor — consult happy path', () => {
+	it('calls provider.chat with system + question, toolChoice none', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		const a = advisor({ provider, systemPrompt: 'You are Adv.' })
+		await e.consult(a, req, ctx())
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		expect(call.model).toBe('m')
+		expect(call.toolChoice).toBe('none')
+		const roles = call.messages.map((m) => m.role)
+		expect(roles[0]).toBe('system')
+		expect(roles.at(-1)).toBe('user')
+	})
+
+	it('returns {result, usage, cost, durationMs}; cost is zero-valued', async () => {
+		const e = new AdvisoryExecutor()
+		const out = await e.consult(advisor(), req, ctx())
+		expect(out.result.advice).toBe('advice text')
+		expect(out.usage.totalTokens).toBe(150)
+		expect(out.cost).toEqual({
+			inputCostPer1M: 0,
+			outputCostPer1M: 0,
+			totalCost: 0,
+			cacheDiscount: 0,
+		})
+		expect(typeof out.durationMs).toBe('number')
+	})
+
+	it('parseResult is currently a passthrough — advice = content verbatim', async () => {
+		const provider = mockProvider({
+			message: { role: 'assistant', content: 'Raw text with **markdown**' },
+		})
+		const e = new AdvisoryExecutor()
+		const out = await e.consult(advisor({ provider }), req, ctx())
+		expect(out.result.advice).toBe('Raw text with **markdown**')
+	})
+
+	it('handles null provider content as empty string', async () => {
+		const provider = mockProvider({
+			message: { role: 'assistant', content: null },
+		})
+		const e = new AdvisoryExecutor()
+		const out = await e.consult(advisor({ provider }), req, ctx())
+		expect(out.result.advice).toBe('')
+	})
+})
+
+describe('AdvisoryExecutor — buildSystemPrompt', () => {
+	it('uses advisor.systemPrompt verbatim when set', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(advisor({ provider, systemPrompt: 'FIXED PROMPT' }), req, ctx())
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		expect(call.messages[0]?.content).toBe('FIXED PROMPT')
+	})
+
+	it('falls back to name + domains + boilerplate when no systemPrompt or persona', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(
+			advisor({ provider, name: 'Architect', domains: ['security', 'performance'] }),
+			req,
+			ctx(),
+		)
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const systemContent = call.messages[0]?.content ?? ''
+		expect(systemContent).toContain('Architect')
+		expect(systemContent).toContain('security, performance')
+		expect(systemContent).toContain('concise, actionable advice')
+	})
+
+	it('fallback without domains omits the domains line', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(advisor({ provider, name: 'Adv' }), req, ctx())
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const systemContent = call.messages[0]?.content ?? ''
+		expect(systemContent).not.toContain('domains of expertise')
+	})
+})
+
+describe('AdvisoryExecutor — buildContext', () => {
+	it('returns no context message when request.includeContext is false', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(
+			advisor({ provider }),
+			{ question: 'q', includeContext: false },
+			ctx({ workingStateSummary: 'should be ignored' }),
+		)
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		// Only system + user(question)
+		expect(call.messages).toHaveLength(2)
+	})
+
+	it('includes workingStateSummary + toolCatalog names when present', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(advisor({ provider }), req, {
+			messages: [],
+			iteration: 1,
+			workingStateSummary: 'state summary here',
+			toolCatalog: [
+				{
+					type: 'function',
+					function: { name: 'read_file', description: 'read', parameters: {} },
+				},
+				{
+					type: 'function',
+					function: { name: 'write_file', description: 'write', parameters: {} },
+				},
+			],
+		})
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const contextMsg = call.messages[1]?.content ?? ''
+		expect(contextMsg).toContain('Working State')
+		expect(contextMsg).toContain('state summary here')
+		expect(contextMsg).toContain('Available Tools')
+		expect(contextMsg).toContain('read_file, write_file')
+	})
+
+	it('includes conversation context (no truncation when no maxContextTokens)', async () => {
+		const provider = mockProvider()
+		const messages: Message[] = [
+			{ role: 'user', content: 'hi' },
+			{ role: 'assistant', content: 'hello' },
+		]
+		const e = new AdvisoryExecutor()
+		await e.consult(advisor({ provider }), req, ctx({ messages }))
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const contextMsg = call.messages[1]?.content ?? ''
+		expect(contextMsg).toContain('Conversation Context')
+		expect(contextMsg).toContain('[user]: hi')
+		expect(contextMsg).toContain('[assistant]: hello')
+	})
+
+	it('truncates conversation from the back when maxContextTokens is set', async () => {
+		const provider = mockProvider()
+		const messages: Message[] = [
+			{ role: 'user', content: 'a'.repeat(100) }, // oldest — should be dropped
+			{ role: 'user', content: 'recent' },
+		]
+		const e = new AdvisoryExecutor()
+		// maxContextTokens=5 → 5*4=20 char budget; only 'recent' (6 chars) fits.
+		await e.consult(advisor({ provider, maxContextTokens: 5 }), req, ctx({ messages }))
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const contextMsg = call.messages[1]?.content ?? ''
+		expect(contextMsg).toContain('recent')
+		expect(contextMsg).not.toContain('a'.repeat(100))
+	})
+
+	it('omits the context message entirely when there are no context parts', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(advisor({ provider }), req, ctx())
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		expect(call.messages).toHaveLength(2)
+	})
+})
+
+describe('AdvisoryExecutor — tool calls in context', () => {
+	it('represents assistant messages with tool calls as "(tool calls)" stub', async () => {
+		const provider = mockProvider()
+		const e = new AdvisoryExecutor()
+		await e.consult(
+			advisor({ provider }),
+			req,
+			ctx({
+				messages: [
+					{
+						role: 'assistant',
+						content: null,
+						toolCalls: [{ id: 't1', type: 'function', function: { name: 'x', arguments: '{}' } }],
+					},
+				],
+			}),
+		)
+		const call = vi.mocked(provider.chat).mock.calls[0]?.[0] as ChatCompletionParams
+		const contextMsg = call.messages[1]?.content ?? ''
+		expect(contextMsg).toContain('[assistant]: (tool calls)')
+	})
+})

package/src/advisory/registry.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 6):
+ *
+ *   - `AdvisorRegistry` extends the plain `Registry<AdvisorDefinition>`
+ *     (NOT `ManagedRegistry` — no warn-log, direct register via `Map.set`).
+ *   - Constructor registers every advisor immediately.
+ *   - `resolve(advisorId?, domain?)` resolution priority:
+ *     1. Explicit `advisorId` (even if unknown — returns undefined).
+ *     2. Domain match — first advisor whose `domains[]` includes the domain.
+ *     3. Explicit `defaultId`.
+ *     4. First registered advisor.
+ *     5. Undefined when nothing is registered.
+ *   - `listAll()` returns everything in insertion order.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { AdvisorDefinition } from '../types/advisory/index.js'
+import type { LLMProvider } from '../types/provider/index.js'
+
+import { AdvisorRegistry } from './registry.js'
+
+const provider = {} as LLMProvider
+
+function makeAdvisor(id: string, domains?: string[]): AdvisorDefinition {
+	return {
+		id,
+		name: id,
+		provider,
+		model: 'opus',
+		domains,
+	}
+}
+
+describe('AdvisorRegistry', () => {
+	it('registers every advisor from the constructor array', () => {
+		const r = new AdvisorRegistry([makeAdvisor('a'), makeAdvisor('b')])
+		expect(r.listAll().map((a) => a.id)).toEqual(['a', 'b'])
+	})
+
+	describe('resolve priority', () => {
+		it('returns the advisor for an explicit advisorId', () => {
+			const r = new AdvisorRegistry([makeAdvisor('a'), makeAdvisor('b')])
+			expect(r.resolve('b')?.id).toBe('b')
+		})
+
+		it('returns undefined for an explicit unknown advisorId (does NOT fall through)', () => {
+			const r = new AdvisorRegistry([makeAdvisor('a')])
+			expect(r.resolve('unknown')).toBeUndefined()
+		})
+
+		it('matches first advisor with a matching domain when no advisorId', () => {
+			const r = new AdvisorRegistry([
+				makeAdvisor('sec', ['security']),
+				makeAdvisor('perf', ['performance']),
+			])
+			expect(r.resolve(undefined, 'performance')?.id).toBe('perf')
+		})
+
+		it('falls back to defaultId when no advisorId and no matching domain', () => {
+			const r = new AdvisorRegistry([makeAdvisor('a'), makeAdvisor('b')], 'b')
+			expect(r.resolve(undefined, 'nope')?.id).toBe('b')
+		})
+
+		it('falls back to first registered advisor when no default', () => {
+			const r = new AdvisorRegistry([makeAdvisor('first'), makeAdvisor('second')])
+			expect(r.resolve(undefined, 'nope')?.id).toBe('first')
+		})
+
+		it('returns undefined on an empty registry with no context', () => {
+			const r = new AdvisorRegistry([])
+			expect(r.resolve()).toBeUndefined()
+		})
+	})
+})

package/src/agents/SupervisorAgent.ts

@@ -3,7 +3,6 @@ import { LocalTaskGateway } from '../gateway/local.js'
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import type { LaunchedTaskMeta } from '../runtime/query/iteration/phases/context.js'
-import type { ActorRef } from '../session/hierarchy/actor.js'
 import { buildCoordinatorTools } from '../tools/coordinator/index.js'
 import type { TaskGateway } from '../types/agent/gateway.js'
 import type {
@@ -16,6 +15,7 @@ import type { AgentTaskContext } from '../types/agent/task.js'
 import type { AgentId, TaskId } from '../types/ids/index.js'
 import { deriveChildState } from '../types/invocation/index.js'
 import type { RunEventListener } from '../types/run/index.js'
+import type { ActorRef } from '../types/session/actor.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { AbstractAgent } from './AbstractAgent.js'