@namzu/sdk 45.1.0 → 48.0.0

package/src/agents/examples/PipelineAgent.ts

@@ -0,0 +1,302 @@
+/**
+ * A developer-authored step list, and deliberately not a model-authored
+ * one.
+ *
+ * The proposal this answers is a model that emits an orchestration SCRIPT --
+ * `agent()`, `parallel()`, `pipeline()` as globals -- executed in an
+ * isolate, so that control flow between steps costs no model turns.
+ *
+ * The saving is real and this class already realises most of it: the steps
+ * below run with zero model turns between them, and `SupervisorAgent`
+ * delegates without one. What a script would add is orchestration a
+ * developer did not anticipate, invented at runtime -- which is also the
+ * case where a wrong one is hardest to review before it runs.
+ *
+ * The blocking question is the trust boundary, not the value. `bash` from
+ * a model is mediated by `packages/sandbox` because code from a model is
+ * untrusted; a model-authored script is the same input through another
+ * door, and a strictly more powerful one, since it can call back into the
+ * agent surface. Running it in-process would leave the kernel's one clear
+ * confinement boundary covering the weaker case and not the stronger. So
+ * an isolate is mandatory rather than an optimisation, and the capability
+ * costs a second execution surface to secure, audit and version.
+ *
+ * That is the bar a reopen has to clear.
+ */
+
+import { withTokenBudget } from '../../provider/token-budget.js'
+import type { SessionTokenBudget } from '../../store/budget/index.js'
+import type {
+	AgentInput,
+	AgentMetadata,
+	PipelineAgentConfig,
+	PipelineAgentResult,
+	PipelineStepResult,
+	StepContext,
+} from '../../types/agent/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
+import type { SessionEvent, SessionEventListener } from '../../types/session/events.js'
+import type { TurnSettlement } from '../../types/session/turn.js'
+import { ZERO_COST } from '../../utils/cost.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { generateMessageId } from '../../utils/id.js'
+import type { Logger } from '../../utils/logger.js'
+import { AbstractAgent } from '../AbstractAgent.js'
+import { resolveAgentBudget } from '../budget.js'
+
+/** @deprecated Example of developer-authored fixed-step orchestration. */
+export class PipelineAgent extends AbstractAgent<PipelineAgentConfig, PipelineAgentResult> {
+	readonly type = 'pipeline' as const
+
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'pipeline',
+				capabilities: {
+					supportsTools: false,
+					supportsStreaming: false,
+					supportsConcurrency: false,
+					supportsSubAgents: false,
+				},
+			},
+			log,
+		)
+	}
+
+	/**
+	 * One turn at a time per instance.
+	 *
+	 * `abortController` and `currentSessionId` are instance state, so two
+	 * overlapping turns share one abort controller — cancelling either kills
+	 * both — and the second clobbers the first's session, so a later
+	 * `cancel()` cancels the wrong children. Neither failure announces itself.
+	 * A host that wants parallelism constructs a second instance.
+	 */
+	async run(
+		input: AgentInput,
+		config: PipelineAgentConfig,
+		listener?: SessionEventListener,
+	): Promise<PipelineAgentResult> {
+		return await this.underIdempotencyKey(config.idempotencyKey, () =>
+			this.underInvocationLock(() => this.runExclusive(input, config, listener)),
+		)
+	}
+
+	private async runExclusive(
+		input: AgentInput,
+		config: PipelineAgentConfig,
+		listener?: SessionEventListener,
+	): Promise<PipelineAgentResult> {
+		if (config.sandbox) {
+			throw new Error(
+				'PipelineAgent cannot enforce a turn-level sandbox around developer-authored step callbacks. Configure confinement inside each step or use a tool-running agent.',
+			)
+		}
+		const startTime = Date.now()
+		const sessionId = this.resolveSessionId(config.sessionId)
+		const turnId = this.createTurnId()
+		this.bindTurn(sessionId, turnId, config.logger)
+		const budget = await resolveAgentBudget(input, config, { sessionId, turnId })
+		const settlement = (status: TurnSettlement['status'], iterations: number): TurnSettlement => ({
+			status,
+			iterations,
+			usage: budget.ownUsage,
+			cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+			durationMs: Date.now() - startTime,
+			resultSource: 'model',
+			abandonedTaskIds: [],
+			abandonedJobIds: [],
+		})
+		const provider = config.provider ? withTokenBudget(config.provider, budget) : undefined
+		try {
+			const stepResults: PipelineStepResult[] = []
+			const previousResults = new Map<string, unknown>()
+			let completedSteps = 0
+
+			await this.emitEvent(turnStarted(sessionId, turnId, config, budget), listener)
+
+			let currentInput: unknown = input.messages
+				.filter((m) => m.role === 'user')
+				.map((m) => m.content)
+				.filter((c): c is string => c !== null)
+				.join('\n')
+
+			for (let i = 0; i < config.steps.length; i++) {
+				const step = config.steps[i]
+				if (!step) throw new Error(`Pipeline step at index ${i} is undefined`)
+				const stepStart = Date.now()
+
+				if (this.abortController.signal.aborted) {
+					stepResults.push({
+						stepName: step.name,
+						status: 'skipped',
+						durationMs: 0,
+					})
+					continue
+				}
+
+				await this.emitEvent(
+					{ type: 'iteration_started', sessionId, turnId, iteration: i + 1 },
+					listener,
+				)
+
+				const context: StepContext = {
+					sessionId,
+					turnId,
+					stepIndex: i,
+					totalSteps: config.steps.length,
+					previousResults,
+					provider,
+					budget,
+					signal: this.abortController.signal,
+					env: config.env ?? {},
+				}
+
+				try {
+					if (step.validate && !step.validate(currentInput)) {
+						throw new Error(`Validation failed for step "${step.name}"`)
+					}
+
+					const output = await step.execute(currentInput, context)
+					previousResults.set(step.name, output)
+					currentInput = output
+					completedSteps++
+
+					stepResults.push({
+						stepName: step.name,
+						status: 'completed',
+						output,
+						durationMs: Date.now() - stepStart,
+					})
+				} catch (err) {
+					const errorMsg = toErrorMessage(err)
+
+					stepResults.push({
+						stepName: step.name,
+						status: 'failed',
+						error: errorMsg,
+						durationMs: Date.now() - stepStart,
+					})
+
+					if (step.rollback) {
+						try {
+							await step.rollback(currentInput, context)
+						} catch (rollbackErr) {
+							this.log.error('Rollback failed for a step', {
+								'namzu.pipeline.step_name': step.name,
+								'exception.message': toErrorMessage(rollbackErr),
+							})
+						}
+					}
+
+					if (!config.continueOnError) {
+						await this.emitEvent(
+							{
+								type: 'turn_failed',
+								sessionId,
+								turnId,
+								error: errorMsg,
+								budget: budget.summary(),
+								settlement: settlement('failed', i + 1),
+							},
+							listener,
+						)
+
+						return {
+							sessionId,
+							turnId,
+							status: 'failed',
+							stopReason: 'error',
+							usage: budget.ownUsage,
+							budget: budget.summary(),
+							cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+							iterations: i + 1,
+							durationMs: Date.now() - startTime,
+							messages: input.messages,
+							lastError: errorMsg,
+							stepResults,
+							completedSteps,
+							totalSteps: config.steps.length,
+						}
+					}
+				}
+			}
+
+			const finalStatus = completedSteps === config.steps.length ? 'completed' : 'failed'
+			const lastOutput = stepResults[stepResults.length - 1]?.output
+
+			const result = typeof lastOutput === 'string' ? lastOutput : JSON.stringify(lastOutput)
+
+			// A pipeline that finished with failed steps (under `continueOnError`)
+			// did not complete its turn, so it settles as `turn_failed`: the
+			// terminal verdict is the event type (spec §2.10).
+			await this.emitEvent(
+				finalStatus === 'completed'
+					? {
+							type: 'turn_completed',
+							sessionId,
+							turnId,
+							budget: budget.summary(),
+							result,
+							stopReason: 'end_turn',
+							settlement: settlement('completed', config.steps.length),
+						}
+					: {
+							type: 'turn_failed',
+							sessionId,
+							turnId,
+							budget: budget.summary(),
+							error: `${config.steps.length - completedSteps} of ${config.steps.length} pipeline steps failed`,
+							settlement: settlement('failed', config.steps.length),
+						},
+				listener,
+			)
+
+			return {
+				sessionId,
+				turnId,
+				status: finalStatus,
+				stopReason: 'end_turn',
+				usage: budget.ownUsage,
+				budget: budget.summary(),
+				cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+				iterations: config.steps.length,
+				durationMs: Date.now() - startTime,
+				messages: input.messages,
+				result,
+				stepResults,
+				completedSteps,
+				totalSteps: config.steps.length,
+			}
+		} finally {
+			budget.settle()
+			await budget.flush()
+		}
+	}
+}
+
+/**
+ * The turn a pipeline runs, announced the way `query()` announces one. The
+ * user message id names the input the steps were handed; nothing is written
+ * to a session log, because the steps are callbacks, not model calls.
+ */
+function turnStarted(
+	sessionId: SessionId,
+	turnId: TurnId,
+	config: PipelineAgentConfig,
+	budget: SessionTokenBudget,
+): SessionEvent {
+	return {
+		type: 'turn_started',
+		sessionId,
+		turnId,
+		userMessageId: generateMessageId(),
+		config: {
+			model: config.model,
+			tokenBudget: config.tokenBudget,
+			timeoutMs: config.timeoutMs,
+		},
+		...(budget.binding ? { budget: budget.binding } : {}),
+	}
+}

package/src/agents/examples/RouterAgent.ts

@@ -0,0 +1,338 @@
+import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
+import { collectChatCompletion } from '../../provider/collect-chat-completion.js'
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js'
+import { withTokenBudget } from '../../provider/token-budget.js'
+import { FallbackResolver } from '../../runtime/decision/fallback.js'
+import { DecisionParser } from '../../runtime/decision/parser.js'
+import type {
+	AgentInput,
+	AgentMetadata,
+	RouterAgentConfig,
+	RouterAgentResult,
+	RoutingDecision,
+} from '../../types/agent/index.js'
+import { type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
+import type { FallbackStrategy } from '../../types/decision/index.js'
+import { deriveChildState } from '../../types/invocation/index.js'
+import { createSystemMessage, createUserMessage } from '../../types/message/index.js'
+import type { SessionEventListener } from '../../types/session/events.js'
+import { ZERO_COST } from '../../utils/cost.js'
+import type { Logger } from '../../utils/logger.js'
+import { AbstractAgent } from '../AbstractAgent.js'
+import { resolveAgentBudget } from '../budget.js'
+
+/** @deprecated Example of developer-authored routing. */
+export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentResult> {
+	readonly type = 'router' as const
+
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'router',
+				capabilities: {
+					supportsTools: false,
+					supportsStreaming: true,
+					supportsConcurrency: false,
+					supportsSubAgents: true,
+				},
+			},
+			log,
+		)
+	}
+
+	/**
+	 * One turn at a time per instance.
+	 *
+	 * `abortController` and `currentSessionId` are instance state, so two
+	 * overlapping turns share one abort controller — cancelling either kills
+	 * both — and the second clobbers the first's session, so a later
+	 * `cancel()` cancels the wrong children. Neither failure announces itself.
+	 * A host that wants parallelism constructs a second instance.
+	 */
+	async run(
+		input: AgentInput,
+		config: RouterAgentConfig,
+		listener?: SessionEventListener,
+	): Promise<RouterAgentResult> {
+		return await this.underIdempotencyKey(config.idempotencyKey, () =>
+			this.underInvocationLock(() => this.runExclusive(input, config, listener)),
+		)
+	}
+
+	private async runExclusive(
+		input: AgentInput,
+		config: RouterAgentConfig,
+		listener?: SessionEventListener,
+	): Promise<RouterAgentResult> {
+		// Resolve before a turn id/event exists, matching query(): malformed
+		// liveness policy is a caller config error, not a failed model turn.
+		const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(config.streamIdleTimeoutMs)
+		const signal = input.signal
+			? AbortSignal.any([input.signal, this.abortController.signal])
+			: this.abortController.signal
+		const startTime = Date.now()
+		const sessionId = this.resolveSessionId(config.sessionId)
+		const turnId = this.createTurnId()
+		this.bindTurn(sessionId, turnId, config.logger)
+		const budget = await resolveAgentBudget(input, config, { sessionId, turnId })
+		const budgetConfig = { ...config, budget }
+		// No lifecycle events of its own. A `turn_*` event names a turn in a
+		// session log, and routing writes none: the delegate below runs the
+		// session's turn and emits its lifecycle, and the listener receives
+		// exactly that turn rather than a synthetic one wrapped around it.
+		try {
+			const decision = await this.route(input, budgetConfig, streamIdleTimeoutMs, signal)
+
+			let targetRoute = config.routes.find((r) => r.agentId === decision.agentId)
+
+			if (!targetRoute) {
+				const fallback = config.fallbackAgentId
+					? config.routes.find((r) => r.agentId === config.fallbackAgentId)
+					: undefined
+
+				if (!fallback) {
+					const errorMsg = `No route found for "${decision.agentId}"`
+
+					return {
+						sessionId,
+						turnId,
+						status: 'failed',
+						stopReason: 'error',
+						usage: budget.ownUsage,
+						budget: budget.summary(),
+						cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+						iterations: 1,
+						durationMs: Date.now() - startTime,
+						messages: input.messages,
+						lastError: errorMsg,
+						selectedRoute: decision.agentId,
+						routingDecision: decision,
+						delegateResult: {
+							sessionId,
+							turnId,
+							status: 'failed',
+							usage: { ...EMPTY_TOKEN_USAGE },
+							cost: { ...ZERO_COST },
+							iterations: 0,
+							durationMs: 0,
+							messages: [],
+						},
+					}
+				}
+
+				decision.agentId = fallback.agentId
+				targetRoute = fallback
+			}
+
+			if (!config.invocationState) {
+				throw new Error(
+					'RouterAgent requires invocationState with tenantId in config (session-hierarchy.md §12.1).',
+				)
+			}
+			const childInvocationState = deriveChildState(config.invocationState, this.metadata.id)
+			const allocation = Number.isFinite(budget.remaining)
+				? Math.floor(budget.remaining)
+				: config.tokenBudget || 200_000
+			const childBudget = budget.reserve(allocation)
+			await childBudget.flush()
+			let delegateResult: RouterAgentResult['delegateResult']
+			try {
+				delegateResult = await targetRoute.agent.run(
+					input,
+					{
+						...config,
+						budget: childBudget,
+						tokenBudget: allocation,
+						// The same session: the delegate runs this session's turn,
+						// it is not a child session of it.
+						sessionId,
+						depth: (config.depth ?? 0) + 1,
+						invocationState: childInvocationState,
+					},
+					listener,
+				)
+				childBudget.bindTurn(delegateResult.sessionId, delegateResult.turnId)
+				childBudget.settle(delegateResult.usage.totalTokens)
+			} finally {
+				// A thrown custom delegate supplies no final usage receipt.
+				// Its reservation stays held until an authoritative settlement.
+				await childBudget.flush()
+			}
+
+			return {
+				sessionId,
+				turnId: delegateResult.turnId,
+				status: delegateResult.status,
+				stopReason: delegateResult.stopReason,
+				usage: budget.ownUsage,
+				budget: budget.summary(),
+				cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+				iterations: delegateResult.iterations + 1,
+				durationMs: Date.now() - startTime,
+				messages: delegateResult.messages,
+				result: delegateResult.result,
+				lastError: delegateResult.lastError,
+				selectedRoute: decision.agentId,
+				routingDecision: decision,
+				delegateResult,
+			}
+		} finally {
+			budget.settle()
+			await budget.flush()
+		}
+	}
+
+	private async route(
+		input: AgentInput,
+		config: RouterAgentConfig,
+		streamIdleTimeoutMs: number,
+		signal: AbortSignal,
+	): Promise<RoutingDecision> {
+		// `this.log`, not a fresh `getRootLogger()` child — bound by `bindTurn`
+		// in `runExclusive` before this is called, so a routing warning below
+		// carries the SAME `namzu.turn.id` as the turn it is routing. The old
+		// independent construction here is the exact bug LOG-10's acceptance
+		// criterion names: a route() log line with no id at all.
+		const log = this.log
+
+		const validAgentIds = config.routes.map((r) => r.agentId)
+		const fallbackAgentId = config.fallbackAgentId ?? config.routes[0]?.agentId ?? ''
+		const minConfidence = config.minConfidence ?? 0
+		const maxRetries = config.maxRoutingRetries ?? 1
+
+		const parser = new DecisionParser(
+			{
+				validAgentIds,
+				minConfidence,
+				maxRetries,
+				fallbackAgentId,
+			},
+			log,
+		)
+
+		const fallbackStrategies: FallbackStrategy[] = []
+
+		const patternMap = new Map<string, string[]>()
+		for (const route of config.routes) {
+			if (route.matchPatterns && route.matchPatterns.length > 0) {
+				patternMap.set(route.agentId, route.matchPatterns)
+			}
+		}
+		if (patternMap.size > 0) {
+			fallbackStrategies.push({ type: 'pattern_match', patterns: patternMap })
+		}
+
+		if (config.fallbackAgentId) {
+			fallbackStrategies.push({
+				type: 'fixed',
+				agentId: config.fallbackAgentId,
+			})
+		}
+
+		fallbackStrategies.push({ type: 'first_route' })
+
+		const fallbackResolver = new FallbackResolver(fallbackStrategies, log)
+
+		const routeDescriptions = config.routes
+			.map((r) => `- ${r.agentId}: ${r.description}`)
+			.join('\n')
+
+		const prompt =
+			config.routingPrompt ??
+			`Given the user's request, select the most appropriate agent.\n\nAvailable agents:\n${routeDescriptions}\n\nRespond with JSON only: { "agentId": "<id>", "confidence": <0-1>, "reasoning": "<why>" }`
+
+		const userContent = input.messages
+			.filter((m) => m.role === 'user')
+			.map((m) => m.content)
+			.filter((c): c is string => c !== null)
+			.join('\n')
+
+		// Every routing attempt is a billed model call; a fallback after
+		// three failed parses still cost three calls.
+		let routingUsage: TokenUsage = { ...EMPTY_TOKEN_USAGE }
+		const routingProvider = withStreamIdleTimeout(
+			config.budget ? withTokenBudget(config.provider, config.budget) : config.provider,
+			{
+				idleTimeoutMs: streamIdleTimeoutMs,
+				log,
+			},
+		)
+
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			try {
+				const response = await collectChatCompletion(
+					routingProvider.chatStream({
+						model: config.model,
+						messages: [createSystemMessage(prompt), createUserMessage(userContent)],
+						temperature: 0,
+						maxTokens: 200,
+						signal,
+					}),
+				)
+
+				routingUsage = accumulateTokenUsage(routingUsage, response.usage)
+
+				const parseResult = parser.parse(response.message.content)
+
+				if (parseResult.ok && parseResult.source === 'parsed') {
+					return {
+						agentId: parseResult.decision.agentId,
+						confidence: parseResult.decision.confidence,
+						reasoning: parseResult.decision.reasoning,
+						routingSource: 'provider',
+						usage: routingUsage,
+					}
+				}
+
+				if (parseResult.ok && parseResult.source === 'fallback') {
+					log.warn('Routing attempt fell back', {
+						'namzu.router.attempt': attempt + 1,
+						'namzu.agents.reason': parseResult.reason,
+						'namzu.agents.decision': parseResult.decision,
+					})
+
+					if (attempt === maxRetries - 1) {
+						return {
+							agentId: parseResult.decision.agentId,
+							confidence: parseResult.decision.confidence,
+							reasoning: parseResult.decision.reasoning,
+							routingSource: 'fallback',
+							usage: routingUsage,
+						}
+					}
+
+					continue
+				}
+
+				if (!parseResult.ok) {
+					log.warn('Routing attempt failed to parse', {
+						'namzu.router.attempt': attempt + 1,
+						'exception.message': parseResult.error,
+					})
+					if (attempt === maxRetries - 1) {
+						break
+					}
+				}
+			} catch (err) {
+				// Provider-idle expiry aborts only the wrapper's private transport
+				// and is eligible for the router's declared fallback. A caller or
+				// agent cancellation owns this fused signal and must not be
+				// reinterpreted as permission to start a delegate.
+				if (signal.aborted) throw signal.reason
+				log.warn('Routing LLM call failed', {
+					'namzu.router.attempt': attempt + 1,
+					'exception.message': String(err),
+				})
+				if (attempt === maxRetries - 1) {
+					break
+				}
+			}
+		}
+
+		return {
+			...fallbackResolver.resolve(userContent, validAgentIds),
+			usage: routingUsage,
+		}
+	}
+}