@namzu/sdk 0.4.2 → 0.4.4

package/src/runtime/query/iteration/phases/advisory.test.ts

@@ -0,0 +1,412 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 6 follow-up):
+ *
+ *   This file pins the live mutation boundary that `src/advisory/*` tests
+ *   intentionally do NOT cover: the advisory phase IS where advisories
+ *   inject user messages into the run via `ctx.runMgr.pushMessage(...)`
+ *   (Codex #6). A regression that drops the `pushMessage` call — silently
+ *   dropping all advisor output — would pass `src/advisory` tests,
+ *   typecheck, and lint. This file is the only thing that catches it.
+ *
+ *   - **Early-return paths** (no side effects):
+ *     - No `advisoryCtx` on the iteration ctx → returns immediately.
+ *     - `advisoryCtx.checkBudget()` denies → returns; NO pushMessage.
+ *     - Evaluator fires no triggers → returns; NO pushMessage.
+ *     - Trigger fires but advisor not found in registry → warn log +
+ *       return; NO pushMessage.
+ *     - Executor throws → warn log + return; NO pushMessage (partial
+ *       work NOT persisted).
+ *   - **Happy path** — trigger fires + advisor resolves + executor
+ *     succeeds:
+ *     - Calls `executor.consult(advisor, request, callCtx)` exactly once.
+ *     - Calls `evaluator.recordFiring(trigger.id, iteration)`.
+ *     - Calls `advisoryCtx.recordCall(...)` with the full call record.
+ *     - Calls `runMgr.pushMessage(createUserMessage(wrapped))` exactly
+ *       once.
+ *     - The wrapped message includes `<advisory-result advisor="..."
+ *       trigger="...">` + the advice text + closing tag.
+ *     - When the result carries `warnings`, they appear under a
+ *       "Warnings:" section.
+ *     - When the result carries `decisions`, they appear under a
+ *       "Decisions:" section AND each decision is pushed to
+ *       `workingStateManager.addDecision` (if a workingStateManager is
+ *       present on ctx).
+ *   - **Trigger selection**: only the first trigger from
+ *     `evaluator.evaluate(state)[0]` is used per iteration; other fired
+ *     triggers are discarded this round.
+ *   - **Question resolution**: `trigger.questionTemplate` is used when
+ *     set; otherwise the phase uses a default
+ *     "Iteration N: Review the current progress..." string.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisoryContext } from '../../../../advisory/context.js'
+import type {
+	AdvisorDefinition,
+	AdvisoryResult,
+	AdvisoryTrigger,
+} from '../../../../types/advisory/index.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import type { Logger } from '../../../../utils/logger.js'
+
+import { runAdvisoryPhase } from './advisory.js'
+import type { IterationContext } from './context.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
+}
+
+interface MockAdvisoryCtxOptions {
+	budgetAllowed?: boolean
+	firedTriggers?: AdvisoryTrigger[]
+	advisor?: AdvisorDefinition
+	consultResult?: AdvisoryResult
+	consultThrows?: Error
+}
+
+function makeAdvisoryCtx(options: MockAdvisoryCtxOptions = {}) {
+	const {
+		budgetAllowed = true,
+		firedTriggers = [],
+		advisor,
+		consultResult = { advice: 'do the thing' },
+		consultThrows,
+	} = options
+
+	const consult = vi.fn(async () => {
+		if (consultThrows) throw consultThrows
+		return {
+			result: consultResult,
+			usage: {
+				promptTokens: 0,
+				completionTokens: 0,
+				totalTokens: 0,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			cost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+			durationMs: 1,
+		}
+	})
+	const evaluate = vi.fn(() => firedTriggers)
+	const recordFiring = vi.fn()
+	const resolve = vi.fn(() => advisor)
+	const checkBudget = vi.fn(() => ({
+		allowed: budgetAllowed,
+		reason: budgetAllowed ? undefined : 'exhausted',
+	}))
+	const recordCall = vi.fn()
+
+	return {
+		ctx: {
+			registry: { resolve },
+			executor: { consult },
+			evaluator: { evaluate, recordFiring },
+			checkBudget,
+			recordCall,
+			callHistory: [],
+		} as unknown as AdvisoryContext,
+		mocks: { consult, evaluate, recordFiring, resolve, checkBudget, recordCall },
+	}
+}
+
+interface MockCtxOptions {
+	advisoryCtx?: AdvisoryContext
+	withWorkingState?: boolean
+}
+
+function makeCtx(options: MockCtxOptions = {}): {
+	ctx: IterationContext
+	pushMessage: ReturnType<typeof vi.fn>
+	addDecision: ReturnType<typeof vi.fn>
+} {
+	const pushMessage = vi.fn()
+	const addDecision = vi.fn()
+
+	const ctx = {
+		advisoryCtx: options.advisoryCtx,
+		runConfig: { tokenBudget: 100_000, costLimitUsd: undefined },
+		tools: {
+			get: vi.fn(() => undefined),
+			toLLMTools: vi.fn(() => []),
+		},
+		runMgr: {
+			id: 'run_1' as RunId,
+			messages: [],
+			tokenUsage: {
+				promptTokens: 0,
+				completionTokens: 0,
+				totalTokens: 0,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			costInfo: {
+				inputCostPer1M: 0,
+				outputCostPer1M: 0,
+				totalCost: 0,
+				cacheDiscount: 0,
+			},
+			pushMessage,
+		},
+		log: makeLogger(),
+		workingStateManager: options.withWorkingState
+			? {
+					getState: vi.fn(() => ({
+						task: '',
+						plan: [],
+						files: new Map(),
+						decisions: [],
+						failures: [],
+						discoveries: [],
+						environment: [],
+						toolResults: [],
+						userRequirements: [],
+						assistantNotes: [],
+					})),
+					addDecision,
+				}
+			: undefined,
+	} as unknown as IterationContext
+
+	return { ctx, pushMessage, addDecision }
+}
+
+const response = {
+	id: 'r',
+	model: 'm',
+	message: { role: 'assistant' as const, content: 'text' },
+	usage: {
+		promptTokens: 0,
+		completionTokens: 0,
+		totalTokens: 0,
+		cachedTokens: 0,
+		cacheWriteTokens: 0,
+	},
+	finishReason: 'stop' as const,
+}
+
+const advisor: AdvisorDefinition = {
+	id: 'adv',
+	name: 'Advisor',
+	provider: {} as never,
+	model: 'opus',
+}
+
+const trigger: AdvisoryTrigger = {
+	id: 'trig',
+	condition: { type: 'on_iteration', everyN: 1 },
+	advisorId: 'adv',
+}
+
+describe('runAdvisoryPhase — early-return paths (no pushMessage)', () => {
+	it('returns immediately when advisoryCtx is absent', async () => {
+		const { ctx, pushMessage } = makeCtx()
+		await runAdvisoryPhase(ctx, 1, response)
+		expect(pushMessage).not.toHaveBeenCalled()
+	})
+
+	it('returns when budget is denied', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({ budgetAllowed: false })
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+		await runAdvisoryPhase(ctx, 1, response)
+		expect(mocks.checkBudget).toHaveBeenCalled()
+		expect(mocks.evaluate).not.toHaveBeenCalled()
+		expect(pushMessage).not.toHaveBeenCalled()
+	})
+
+	it('returns when evaluator fires no triggers', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({ firedTriggers: [] })
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+		await runAdvisoryPhase(ctx, 1, response)
+		expect(mocks.evaluate).toHaveBeenCalled()
+		expect(mocks.resolve).not.toHaveBeenCalled()
+		expect(pushMessage).not.toHaveBeenCalled()
+	})
+
+	it('returns (warn) when trigger fires but advisor is not resolved', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor: undefined,
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+		await runAdvisoryPhase(ctx, 1, response)
+		expect(mocks.resolve).toHaveBeenCalledWith('adv')
+		expect(mocks.consult).not.toHaveBeenCalled()
+		expect(pushMessage).not.toHaveBeenCalled()
+	})
+
+	it('returns when executor.consult throws — does NOT pushMessage partial work', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultThrows: new Error('provider timeout'),
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+		await runAdvisoryPhase(ctx, 1, response)
+		expect(mocks.consult).toHaveBeenCalled()
+		expect(mocks.recordFiring).not.toHaveBeenCalled()
+		expect(mocks.recordCall).not.toHaveBeenCalled()
+		expect(pushMessage).not.toHaveBeenCalled()
+	})
+})
+
+describe('runAdvisoryPhase — happy path', () => {
+	it('calls executor + recordFiring + recordCall + pushMessage exactly once', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultResult: { advice: 'do the thing' },
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 3, response)
+
+		expect(mocks.consult).toHaveBeenCalledTimes(1)
+		expect(mocks.recordFiring).toHaveBeenCalledWith('trig', 3)
+		expect(mocks.recordCall).toHaveBeenCalledTimes(1)
+		expect(pushMessage).toHaveBeenCalledTimes(1)
+	})
+
+	it('pushMessage wraps advice in <advisory-result> envelope with role user', async () => {
+		const { ctx: advCtx } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultResult: { advice: 'specific advice text' },
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 1, response)
+
+		const pushed = pushMessage.mock.calls[0]?.[0] as { role: string; content: string }
+		expect(pushed.role).toBe('user')
+		expect(pushed.content).toContain('<advisory-result advisor="Advisor" trigger="trig">')
+		expect(pushed.content).toContain('specific advice text')
+		expect(pushed.content).toContain('</advisory-result>')
+	})
+
+	it('includes Warnings section when the result carries warnings', async () => {
+		const { ctx: advCtx } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultResult: {
+				advice: 'proceed',
+				warnings: ['slow response', 'retry likely'],
+			},
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 1, response)
+
+		const pushed = pushMessage.mock.calls[0]?.[0] as { content: string }
+		expect(pushed.content).toContain('Warnings:')
+		expect(pushed.content).toContain('- slow response')
+		expect(pushed.content).toContain('- retry likely')
+	})
+
+	it('includes Decisions section + pushes each decision to workingStateManager', async () => {
+		const { ctx: advCtx } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultResult: {
+				advice: 'go',
+				decisions: ['use sqlite', 'skip migration'],
+			},
+		})
+		const { ctx, pushMessage, addDecision } = makeCtx({
+			advisoryCtx: advCtx,
+			withWorkingState: true,
+		})
+
+		await runAdvisoryPhase(ctx, 1, response)
+
+		const pushed = pushMessage.mock.calls[0]?.[0] as { content: string }
+		expect(pushed.content).toContain('Decisions:')
+		expect(pushed.content).toContain('- use sqlite')
+		expect(pushed.content).toContain('- skip migration')
+
+		expect(addDecision).toHaveBeenCalledTimes(2)
+		expect(addDecision).toHaveBeenCalledWith('use sqlite')
+		expect(addDecision).toHaveBeenCalledWith('skip migration')
+	})
+
+	it('does NOT attempt to addDecision when no workingStateManager is present', async () => {
+		const { ctx: advCtx } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+			consultResult: {
+				advice: 'go',
+				decisions: ['a'],
+			},
+		})
+		const { ctx, pushMessage } = makeCtx({ advisoryCtx: advCtx, withWorkingState: false })
+
+		await runAdvisoryPhase(ctx, 1, response)
+		// pushMessage still carries the Decisions section in content
+		expect((pushMessage.mock.calls[0]?.[0] as { content: string }).content).toContain('- a')
+	})
+})
+
+describe('runAdvisoryPhase — trigger selection + question', () => {
+	it('uses only the first fired trigger per iteration', async () => {
+		const other: AdvisoryTrigger = {
+			id: 'other',
+			condition: { type: 'on_iteration', everyN: 1 },
+			advisorId: 'adv',
+		}
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [trigger, other],
+			advisor,
+		})
+		const { ctx } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 1, response)
+
+		expect(mocks.recordFiring).toHaveBeenCalledTimes(1)
+		expect(mocks.recordFiring).toHaveBeenCalledWith('trig', 1)
+	})
+
+	it('uses trigger.questionTemplate when present', async () => {
+		const custom: AdvisoryTrigger = {
+			...trigger,
+			questionTemplate: 'Custom question',
+		}
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [custom],
+			advisor,
+		})
+		const { ctx } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 7, response)
+		const consultArgs = mocks.consult.mock.calls[0] as unknown as [
+			unknown,
+			{ question: string },
+			unknown,
+		]
+		expect(consultArgs?.[1].question).toBe('Custom question')
+	})
+
+	it('falls back to the default "Iteration N: ..." question when no template', async () => {
+		const { ctx: advCtx, mocks } = makeAdvisoryCtx({
+			firedTriggers: [trigger],
+			advisor,
+		})
+		const { ctx } = makeCtx({ advisoryCtx: advCtx })
+
+		await runAdvisoryPhase(ctx, 7, response)
+		const consultArgs = mocks.consult.mock.calls[0] as unknown as [
+			unknown,
+			{ question: string },
+			unknown,
+		]
+		expect(consultArgs?.[1].question).toContain('Iteration 7')
+	})
+})

package/src/test-setup.ts

@@ -0,0 +1,24 @@
+/**
+ * Vitest `setupFiles` entry for `@namzu/sdk`.
+ *
+ * Silences the root logger for the entire test run. Tests that assert on
+ * log output use their own mocked Logger instances (constructed via the
+ * `makeLogger()` helpers colocated with each test) — those are not
+ * affected by the root-level silence.
+ *
+ * The only thing this suppresses is the stderr spam produced by
+ * production code paths that fall through to `getRootLogger()` — e.g.
+ * `ToolRegistry.execute`'s zod-validation and thrown-error branches,
+ * `ConnectorToolRouter.getTools`' per-instance error catch, the
+ * AgentBus listener-throw handler, and every connector's `connect()`
+ * info log. GitHub Actions annotates any `[ERROR]` stderr line as a
+ * workflow error; silencing the root logger during tests keeps the CI
+ * log clean.
+ *
+ * This is test-only configuration. It runs before every test file and
+ * does not affect consumers.
+ */
+
+import { configureLogger } from './utils/logger.js'
+
+configureLogger({ level: 'silent' })

package/src/types/bus/index.ts

@@ -1,6 +1,8 @@
-import type { RunId } from '../ids/index.js'
+import type { CredentialId, LockId, RunId, SandboxId, TenantId } from '../ids/index.js'
 
-export type LockId = `lock_${string}`
+export type { LockId } from '../ids/index.js'
+
+export type ProviderCallId = `pcall_${string}`
 
 export type CircuitBreakerState = 'closed' | 'open' | 'half_open'
 
@@ -35,6 +37,15 @@ export type OwnershipClaimResult =
 	| { claimed: true; ownership: FileOwnership }
 	| { claimed: false; currentOwner: RunId; filePath: string }
 
+export interface ProviderCallUsage {
+	readonly inputTokens?: number
+	readonly outputTokens?: number
+	readonly totalTokens?: number
+	readonly costUsd?: number
+}
+
+export type SandboxDecisionAction = 'allow' | 'deny'
+
 export type AgentBusEvent =
 	| { type: 'lock_acquired'; lockId: LockId; filePath: string; owner: RunId }
 	| { type: 'lock_released'; lockId: LockId; filePath: string; owner: RunId }
@@ -49,5 +60,46 @@ export type AgentBusEvent =
 	| { type: 'breaker_half_open'; agentRunId: RunId }
 	| { type: 'breaker_probe_success'; agentRunId: RunId }
 	| { type: 'breaker_probe_failure'; agentRunId: RunId }
+	| {
+			type: 'provider_call_start'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+	  }
+	| {
+			type: 'provider_call_completed'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+			durationMs: number
+			usage?: ProviderCallUsage
+	  }
+	| {
+			type: 'provider_call_failed'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+			durationMs: number
+			error: string
+	  }
+	| {
+			type: 'vault_lookup'
+			vaultId: string
+			credentialId?: CredentialId
+			tenantId?: TenantId
+			found: boolean
+			runId?: RunId
+	  }
+	| {
+			type: 'sandbox_decision'
+			sandboxId: SandboxId
+			action: SandboxDecisionAction
+			resource: string
+			ruleId?: string
+			runId?: RunId
+	  }
 
 export type AgentBusEventListener = (event: AgentBusEvent) => void

package/src/types/doctor/check.ts

@@ -0,0 +1,53 @@
+export type DoctorStatus = 'pass' | 'fail' | 'inconclusive' | 'warn'
+
+export type DoctorCategory =
+	| 'sandbox'
+	| 'providers'
+	| 'vault'
+	| 'telemetry'
+	| 'runtime'
+	| 'plugins'
+	| 'custom'
+
+export interface DoctorCheckContext {
+	readonly cwd: string
+	readonly env: Readonly<Record<string, string | undefined>>
+	readonly projectRoot: string | null
+}
+
+export interface DoctorCheckResult {
+	readonly status: DoctorStatus
+	readonly message?: string
+	readonly remediation?: string
+	readonly durationMs?: number
+}
+
+export interface DoctorCheck {
+	readonly id: string
+	readonly category: DoctorCategory
+	readonly run: (ctx: DoctorCheckContext) => Promise<DoctorCheckResult>
+	readonly fix?: (ctx: DoctorCheckContext) => Promise<DoctorCheckResult>
+}
+
+export interface DoctorCheckRecord {
+	readonly id: string
+	readonly category: DoctorCategory
+	readonly status: DoctorStatus
+	readonly message?: string
+	readonly remediation?: string
+	readonly durationMs: number
+}
+
+export interface DoctorReport {
+	readonly version: string
+	readonly timestamp: string
+	readonly checks: readonly DoctorCheckRecord[]
+	readonly summary: {
+		readonly pass: number
+		readonly fail: number
+		readonly inconclusive: number
+		readonly warn: number
+		readonly total: number
+	}
+	readonly exit: 0 | 1 | 2 | 70
+}

package/src/types/doctor/index.ts

@@ -0,0 +1,9 @@
+export type {
+	DoctorCategory,
+	DoctorCheck,
+	DoctorCheckContext,
+	DoctorCheckRecord,
+	DoctorCheckResult,
+	DoctorReport,
+	DoctorStatus,
+} from './check.js'

package/src/types/probe/event-kind.ts

@@ -0,0 +1,8 @@
+import type { AgentBusEvent } from '../bus/index.js'
+import type { RunEvent } from '../run/events.js'
+
+export type ProbeEventKind = RunEvent['type'] | AgentBusEvent['type']
+
+export type VetoableEventKind = 'tool_executing'
+
+export type ProbeEvent = RunEvent | AgentBusEvent

package/src/types/probe/event-of.ts

@@ -0,0 +1,3 @@
+import type { ProbeEvent, ProbeEventKind } from './event-kind.js'
+
+export type ProbeEventOf<K extends ProbeEventKind> = Extract<ProbeEvent, { type: K }>

package/src/types/probe/index.ts

@@ -0,0 +1,11 @@
+export type { ProbeEvent, ProbeEventKind, VetoableEventKind } from './event-kind.js'
+export type { ProbeEventOf } from './event-of.js'
+export type {
+	ProbeContext,
+	ProbeHandler,
+	ProbeOptions,
+	Unsubscribe,
+	VetoDecision,
+	VetoHandler,
+	VetoOutcome,
+} from './registry.js'

package/src/types/probe/registry.ts

@@ -0,0 +1,36 @@
+import type { RunId } from '../ids/index.js'
+import type { ProbeEventKind, VetoableEventKind } from './event-kind.js'
+import type { ProbeEventOf } from './event-of.js'
+
+export type Unsubscribe = () => void
+
+export interface ProbeContext {
+	readonly runId?: RunId
+	readonly isReplay: boolean
+}
+
+export type ProbeHandler<K extends ProbeEventKind> = (
+	event: ProbeEventOf<K>,
+	ctx: ProbeContext,
+) => void
+
+export type VetoDecision = 'allow' | 'deny' | { readonly action: 'deny'; readonly reason: string }
+
+export type VetoHandler<K extends VetoableEventKind> = (
+	event: ProbeEventOf<K>,
+	ctx: ProbeContext,
+) => VetoDecision
+
+export interface VetoOutcome {
+	readonly action: 'allow' | 'deny'
+	readonly probeName?: string
+	readonly reason?: string
+}
+
+export interface ProbeOptions<K extends ProbeEventKind = ProbeEventKind> {
+	readonly where?: (event: ProbeEventOf<K>) => boolean
+	readonly priority?: number
+	readonly name?: string
+	readonly otel?: boolean
+	readonly override?: boolean
+}

package/src/utils/logger.ts

@@ -1,4 +1,4 @@
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
 
 export type LogContext = Record<string, unknown>
 
@@ -7,6 +7,11 @@ const LOG_LEVELS: Record<LogLevel, number> = {
 	info: 1,
 	warn: 2,
 	error: 3,
+	// `silent` sits above every emit level so the `level < minLevelNum`
+	// guard in `log()` always short-circuits when configured. Used by
+	// test harnesses to suppress unmocked `getRootLogger()` stderr
+	// writes; see packages/sdk/src/test-setup.ts.
+	silent: 4,
 }
 
 export interface Logger {