@namzu/sdk 46.0.0 → 48.0.0

package/src/advisory/registry.ts

@@ -1,6 +1,22 @@
 import { BaseRegistry } from '../registry/BaseRegistry.js'
+import { RegistryCollisionError } from '../registry/collision.js'
 import type { AdvisorDefinition } from '../types/advisory/index.js'
 
+/** Two advisors claiming one id. */
+export class AdvisorCollisionError extends RegistryCollisionError {
+	readonly advisorId: string
+
+	constructor(advisorId: string) {
+		super(
+			'AdvisorRegistry',
+			advisorId,
+			`Advisor "${advisorId}" is already registered. Two advisors picked the same id, or the same advisor was registered twice — pick a different id, or find the second registration.`,
+		)
+		this.name = 'AdvisorCollisionError'
+		this.advisorId = advisorId
+	}
+}
+
 export class AdvisorRegistry extends BaseRegistry<AdvisorDefinition> {
 	private readonly defaultId: string | undefined
 
@@ -12,6 +28,23 @@ export class AdvisorRegistry extends BaseRegistry<AdvisorDefinition> {
 		this.defaultId = defaultId
 	}
 
+	/**
+	 * A second advisor claiming an id an earlier one already holds used to
+	 * overwrite in total silence (see
+	 * `gaps/critic-registry-collision-idiom-inconsistency.md`). Every SDK
+	 * registry now throws on a duplicate id by default (see
+	 * `registry/collision.ts`), and this one had no exception to name, so it
+	 * converges too: two advisors sharing an id is a configuration mistake,
+	 * not a supersession, and the loser vanishing silently is exactly the
+	 * failure this now refuses instead of logging.
+	 */
+	override register(id: string, advisor: AdvisorDefinition): void {
+		if (this.has(id)) {
+			throw new AdvisorCollisionError(id)
+		}
+		super.register(id, advisor)
+	}
+
 	/**
 	 * Resolves the advisor for a given request.
 	 *

package/src/agents/AGENTS.md

@@ -13,12 +13,19 @@ folklore.
 
 ## What lives here
 
-Orchestration primitives, all **developer-authored**.
+The `Agent` contract, `runAgent`/`query` entry points, and an optional
+`QueryAgent` adapter are SDK infrastructure. Applications own their agent
+identity and orchestration. The CLI's delegated agent lives in
+`packages/cli/src/integrations/subagents/NamzuCliAgent.ts`.
 
-- **`PipelineAgent.ts`** — a fixed step list the developer wrote. The steps
+`examples/` holds developer-authored orchestration patterns. Their former
+exports remain as deprecated compatibility names; they do not define a closed
+list of agent kinds.
+
+- **`examples/PipelineAgent.ts`** — a fixed step list the developer wrote. The steps
   run with **zero model turns between them**: the control flow is code, and
   the model is called only where a step calls it.
-- **`SupervisorAgent.ts`** — delegation driven by the model emitting
+- **`examples/SupervisorAgent.ts`** — delegation driven by the model emitting
   `create_task` tool calls. Note what this already does: **N `create_task`
   blocks in one assistant turn run concurrently**, so fan-out costs one turn
   for N children, not N turns. The mechanism, checked rather than assumed:
@@ -82,10 +89,10 @@ first one got lost.
 
 ## Working here
 
-- An agent's capabilities are **declared** on its metadata and honoured by the
-  runtime. Adding a capability means declaring it and driving it in the same
-  change; a declared capability nothing reads is the
-  `declared-but-undriven` defect this repo has a convention page about.
+- `AgentCapabilities` is descriptive metadata. The manager does not enforce
+  its booleans. A host enforces tool access, subagent admission and concurrency
+  through its toolsets, authorization gate, manager and per-instance locking.
+  Do not treat a declared capability as permission or claim it is a runtime gate.
 - `AbstractAgent` takes an injected `Logger`. Do not reach for
   `getRootLogger()` here — see the log-standard gate,
   which counts every call site.

package/src/agents/PipelineAgent.ts

@@ -1,303 +1,2 @@
-/**
- * A developer-authored step list, and deliberately not a model-authored
- * one.
- *
- * This distinction has been attributed to a `packages/sdk/src/agents/
- * AGENTS.md` that does not exist, so it is written here instead. The
- * proposal it 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'
-
-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 } : {}),
-	}
-}
+/** @deprecated Example agent. Define application agents with the SDK Agent contract. */
+export { PipelineAgent } from './examples/PipelineAgent.js'

package/src/agents/QueryAgent.ts

@@ -0,0 +1,269 @@
+import { drainQuery } from '../runtime/query/index.js'
+import type {
+	AgentInvocationScope,
+	AgentMetadata,
+	ManagedAgentInput,
+	QueryAgentConfig,
+	QueryAgentResult,
+} from '../types/agent/index.js'
+import type { AssistantMessage } from '../types/message/index.js'
+import type { TurnConfig } from '../types/session/config.js'
+import type { SessionEventListener } from '../types/session/events.js'
+import type { Logger } from '../utils/logger.js'
+import { AbstractAgent } from './AbstractAgent.js'
+import { pickRoutedOptions } from './forward-options.js'
+
+/** Every config field has one destination, or a deliberately explicit transform. */
+const configRoutes = {
+	model: 'turn',
+	tokenBudget: 'turn',
+	budget: 'query',
+	timeoutMs: 'turn',
+	streamIdleTimeoutMs: 'turn',
+	maxRequestRichContentBytes: 'turn',
+	attachmentResolveTimeoutMs: 'query',
+	maxIterations: 'turn',
+	temperature: 'turn',
+	maxResponseTokens: 'turn',
+	costLimitUsd: 'turn',
+	permissionMode: 'turn',
+	pruneKeepLast: 'turn',
+	paths: 'query',
+	sessionLog: 'query',
+	checkpointStore: 'query',
+	sandbox: 'turn',
+	inboundMessages: 'query',
+	projectInstructionContext: 'query',
+	allowedTools: 'special',
+	toolResultGuardrails: 'query',
+	deniedTools: 'special',
+	persona: 'query',
+	logger: 'special',
+	env: 'turn',
+	thinking: 'turn',
+	effort: 'turn',
+	idempotencyKey: 'special',
+	projectId: 'special',
+	topicId: 'special',
+	sessionId: 'special',
+	tenantId: 'special',
+	parentSessionId: 'query',
+	parentTurnId: 'query',
+	depth: 'query',
+	contextLevel: 'query',
+	invocationState: 'query',
+	parentSpan: 'query',
+	resumeHandler: 'query',
+	reviewAllowedCalls: 'query',
+	systemPrompt: 'query',
+	webSearch: 'turn',
+	steering: 'query',
+	skills: 'query',
+	basePrompt: 'query',
+	provider: 'query',
+	toolsets: 'query',
+	advisory: 'query',
+	authorizationGate: 'query',
+	sandboxProvider: 'query',
+	sandboxTeardownTimeoutMs: 'query',
+	outsideRootAccess: 'query',
+	sandboxEscape: 'query',
+	compactionConfig: 'query',
+	workingMemoryProvider: 'query',
+	retry: 'query',
+	toolTimeoutMs: 'query',
+	toolRetryBackoff: 'query',
+	maxToolConcurrency: 'query',
+	maxToolOutputChars: 'query',
+	retainedToolPreviewChars: 'query',
+	maxToolContentBytes: 'query',
+	repairToolCall: 'query',
+	stopWhen: 'query',
+	onStepFinish: 'query',
+	prepareStep: 'query',
+	beforeStep: 'query',
+	structuredOutput: 'query',
+	inputGuardrails: 'query',
+	outputGuardrails: 'query',
+} as const satisfies { readonly [K in keyof QueryAgentConfig]: 'query' | 'turn' | 'special' }
+
+type RoutedKeys<TDestination extends 'query' | 'turn'> = {
+	[K in keyof typeof configRoutes]: (typeof configRoutes)[K] extends TDestination ? K : never
+}[keyof typeof configRoutes]
+
+type QueryFields = Pick<Parameters<typeof drainQuery>[0], RoutedKeys<'query'>>
+type TurnFields = Pick<TurnConfig, RoutedKeys<'turn'>>
+
+const SCOPE_FIELDS = ['sessionId', 'topicId', 'projectId', 'tenantId'] as const
+
+function invocationScope(input: ManagedAgentInput, config: QueryAgentConfig): AgentInvocationScope {
+	if (input.managedScope !== undefined) {
+		const scope = input.managedScope
+		if (
+			typeof scope !== 'object' ||
+			scope === null ||
+			Array.isArray(scope) ||
+			scope.kind !== 'managed'
+		) {
+			throw new Error('QueryAgent requires a managed invocation scope.')
+		}
+		const missing = SCOPE_FIELDS.filter(
+			(field) => typeof scope[field] !== 'string' || scope[field].trim().length === 0,
+		)
+		if (missing.length > 0) {
+			throw new Error(`QueryAgent: input.managedScope is missing: ${missing.join(', ')}.`)
+		}
+		const conflicts = SCOPE_FIELDS.filter(
+			(field) => config[field] !== undefined && config[field] !== scope[field],
+		)
+		if (conflicts.length > 0) {
+			throw new Error(
+				`QueryAgent: input.managedScope conflicts with legacy config fields: ${conflicts.join(', ')}.`,
+			)
+		}
+		return scope
+	}
+	if (!config.sessionId || !config.topicId || !config.projectId || !config.tenantId) {
+		throw new Error(
+			'QueryAgent requires sessionId, topicId, projectId, and tenantId in input.managedScope or legacy config.',
+		)
+	}
+	const invalid = SCOPE_FIELDS.filter((field) => {
+		const value = config[field]
+		return typeof value !== 'string' || value.trim().length === 0
+	})
+	if (invalid.length > 0) {
+		throw new Error(`QueryAgent: legacy config has invalid scope fields: ${invalid.join(', ')}.`)
+	}
+	return {
+		kind: 'managed',
+		sessionId: config.sessionId,
+		topicId: config.topicId,
+		projectId: config.projectId,
+		tenantId: config.tenantId,
+	}
+}
+
+export class QueryAgent extends AbstractAgent<QueryAgentConfig, QueryAgentResult> {
+	readonly type: string
+
+	constructor(metadata: Omit<AgentMetadata, 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: metadata.type,
+				capabilities: {
+					supportsTools: true,
+					supportsStreaming: true,
+					supportsConcurrency: false,
+					supportsSubAgents: false,
+				},
+			},
+			log,
+		)
+		this.type = metadata.type
+	}
+
+	/**
+	 * 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: ManagedAgentInput,
+		config: QueryAgentConfig,
+		listener?: SessionEventListener,
+	): Promise<QueryAgentResult> {
+		// Resolve before deduplication: an invalid or conflicting scope must never
+		// receive another caller's in-flight result under the same raw key.
+		const scope = invocationScope(input, config)
+		const scopedKey = config.idempotencyKey
+			? JSON.stringify([
+					scope.kind,
+					scope.tenantId,
+					scope.projectId,
+					scope.topicId,
+					scope.sessionId,
+					config.idempotencyKey,
+				])
+			: undefined
+		return await this.underIdempotencyKey(scopedKey, () =>
+			this.underInvocationLock(() => this.runExclusive(input, config, scope, listener)),
+		)
+	}
+
+	private async runExclusive(
+		input: ManagedAgentInput,
+		config: QueryAgentConfig,
+		scope: AgentInvocationScope,
+		listener?: SessionEventListener,
+	): Promise<QueryAgentResult> {
+		const startTime = Date.now()
+		const turnId = this.createTurnId()
+		this.bindTurn(scope.sessionId, turnId, config.logger)
+		const queryFields: QueryFields = pickRoutedOptions(config, configRoutes, 'query')
+		const turnFields: TurnFields = pickRoutedOptions(config, configRoutes, 'turn')
+
+		const turn = await drainQuery(
+			{
+				...queryFields,
+				...(input.attachmentStore ? { attachmentStore: input.attachmentStore } : {}),
+				...(config.allowedTools ? { allowedTools: [...config.allowedTools] } : {}),
+				...(config.deniedTools ? { deniedTools: [...config.deniedTools] } : {}),
+				turnConfig: {
+					...turnFields,
+					logger: this.log,
+				},
+				agentId: this.metadata.id,
+				agentName: this.metadata.name,
+				workingDirectory: input.workingDirectory,
+				sessionId: scope.sessionId,
+				topicId: scope.topicId,
+				projectId: scope.projectId,
+				tenantId: scope.tenantId,
+				turnId,
+				messages: input.messages,
+				signal: input.signal,
+				taskStore: input.taskStore,
+				runtimeToolOverrides: input.runtimeToolOverrides,
+				runtimeContext: input.runtimeContext,
+			},
+			listener,
+		)
+
+		let toolCallCount = 0
+		for (const msg of turn.messages) {
+			if (msg.role === 'assistant') {
+				const assistantMsg = msg as AssistantMessage
+				if (assistantMsg.toolCalls) {
+					toolCallCount += assistantMsg.toolCalls.length
+				}
+			}
+		}
+
+		return {
+			sessionId: turn.sessionId,
+			turnId: turn.id,
+			status: turn.status,
+			stopReason: turn.stopReason,
+			usage: turn.tokenUsage,
+			...(turn.budget ? { budget: turn.budget } : {}),
+			cost: turn.costInfo,
+			iterations: turn.currentIteration,
+			durationMs: Date.now() - startTime,
+			messages: turn.messages,
+			result: turn.result,
+			structuredOutput: turn.structuredOutput,
+			lastError: turn.lastError,
+			toolCallCount,
+		}
+	}
+
+	override async cancel(): Promise<void> {
+		this.abortController.abort()
+	}
+}