@namzu/sdk 34.2.0 → 35.0.0

package/src/provider/fallback.ts

@@ -67,6 +67,8 @@ export interface ServingMember {
 }
 
 export interface WithProviderFallbackOptions {
+	/** Additional live admission policy before selecting another provider. */
+	readonly canFallback?: () => boolean
 	readonly log?: Logger
 	/**
 	 * Called once per swap, with the member that serves from here on.
@@ -157,7 +159,7 @@ export interface WithProviderFallbackOptions {
  *   classifier maps a `content_policy_violation` structural code onto it, and
  *   `ProviderError` is a public type a third-party driver constructs directly.
  *   Named rather than omitted for that reason; see
- *   `docs/conventions/a-check-that-cannot-fail.md` for why an unnameable one
+ *   "a check that cannot fail" for why an unnameable one
  *   would have been left out.
  */
 const REQUEST_FAULT_CODES: ReadonlySet<string> = new Set([
@@ -409,6 +411,7 @@ export function withProviderFallback(
 				// time, instead of settling as `cancelled`. The retry decorator
 				// guards the same way and for the same reason.
 				if (isAbortError(err) || params.signal?.aborted) throw err
+				if (options.canFallback?.() === false) throw err
 
 				const next = cursor + 1
 				const to = members[next]

package/src/provider/retry.ts

@@ -41,6 +41,8 @@ export const DEFAULT_PROVIDER_RETRY: ProviderRetryConfig = {
 }
 
 export interface WithProviderRetryOptions {
+	/** Additional live admission policy, checked before scheduling a retry. */
+	readonly canRetry?: () => boolean
 	readonly config?: Partial<ProviderRetryConfig>
 	readonly log?: Logger
 	/** Seam for deterministic tests. */
@@ -113,6 +115,7 @@ export function withProviderRetry(
 				return
 			} catch (err) {
 				if (isAbortError(err) || params.signal?.aborted) throw err
+				if (options.canRetry?.() === false) throw err
 				// A driver that already classified its own failure keeps that
 				// classification — `classifyProviderError` reads its `kind`
 				// first and does not re-guess.
@@ -162,7 +165,7 @@ export function withProviderRetry(
 				//
 				// It used to fall through to the jittered backoff instead, and that
 				// is degrading where the contract says refuse
-				// (`docs/conventions/refuse-do-not-degrade.md`). The ceiling was
+				// ("refuse do not degrade"). The ceiling was
 				// read as "how long may I sleep", so a provider asking for fifteen
 				// minutes was re-asked in half a second: the one instruction the
 				// server gave was the one thing discarded, and the retries that

package/src/provider/token-budget.ts

@@ -0,0 +1,114 @@
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
+import type { TokenBudget } from '../run/token-budget.js'
+import { type TokenUsage, mergeTokenUsage } from '../types/common/index.js'
+import { ProviderError, classifyProviderError } from '../types/provider/errors.js'
+import type { LLMProvider, StreamChunk } from '../types/provider/index.js'
+import { isProviderRequestError } from './errors.js'
+
+export class TokenBudgetAdmissionError extends ProviderError {
+	constructor() {
+		super({
+			code: 'invalid_request',
+			message: 'The shared token budget has no available allowance for another model request.',
+			retryable: false,
+		})
+		this.name = 'TokenBudgetAdmissionError'
+	}
+}
+
+function rejectedBeforeGeneration(error: unknown): boolean {
+	if (isProviderRequestError(error)) {
+		return ['auth', 'throttle', 'context_overflow', 'bad_request'].includes(error.kind)
+	}
+	const classified = classifyProviderError(error)
+	const explicitRejection =
+		error instanceof ProviderError ||
+		(classified.status !== undefined &&
+			[400, 401, 403, 404, 413, 422, 429].includes(classified.status))
+	return (
+		explicitRejection &&
+		['auth', 'rate_limit', 'context_length_exceeded', 'invalid_request', 'not_found'].includes(
+			classified.code,
+		)
+	)
+}
+
+/** Account for the observed response once, including advisory/compaction calls.
+ * The marker is durable before contacting the provider. A broken or abandoned
+ * stream retains its marker: an absent receipt cannot establish zero spend.
+ * Driver-internal retries remain one request whose billing the driver reports.
+ */
+export function withTokenBudget(provider: LLMProvider, budget: TokenBudget): LLMProvider {
+	async function* chatStream(
+		params: Parameters<LLMProvider['chatStream']>[0],
+	): AsyncIterable<StreamChunk> {
+		params.signal?.throwIfAborted()
+		if (budget.remaining <= 0) throw new TokenBudgetAdmissionError()
+		const requestId = await budget.beginRequest()
+		let usage: TokenUsage | undefined
+		let completed = false
+		let outputObserved = false
+		let uncertainRetry = false
+		try {
+			for await (const chunk of provider.chatStream(params)) {
+				const recovery = chunk.retry ?? chunk.fallback
+				if (
+					recovery &&
+					![
+						'auth',
+						'rate_limit',
+						'context_length_exceeded',
+						'invalid_request',
+						'not_found',
+					].includes(recovery.code)
+				) {
+					uncertainRetry = true
+					throw new ProviderError({
+						code: 'invalid_request',
+						retryable: false,
+						message:
+							'A prior provider attempt has unresolved token usage; another attempt cannot be admitted.',
+					})
+				}
+				if (Object.keys(chunk.delta).length > 0) outputObserved = true
+				if (chunk.usage) {
+					usage = usage ? mergeTokenUsage(usage, chunk.usage) : { ...chunk.usage }
+				}
+				if (chunk.error) throw new Error(chunk.error)
+				yield chunk
+			}
+			if (usage === undefined) {
+				throw new Error(
+					'Provider ended without token usage; the budget reservation remains unresolved.',
+				)
+			}
+			await budget.finishRequest(requestId, usage)
+			completed = true
+		} catch (error) {
+			// A typed rejection before any generation differs from a lost reply.
+			// In particular a context-overflow retry must not reset or poison spend.
+			if (
+				!outputObserved &&
+				usage === undefined &&
+				!uncertainRetry &&
+				rejectedBeforeGeneration(error)
+			) {
+				await budget.finishRequest(requestId, { ...EMPTY_TOKEN_USAGE })
+				completed = true
+			}
+			throw error
+		} finally {
+			if (!completed) await budget.failRequest(requestId, usage)
+		}
+	}
+
+	// Bind optional driver methods to the driver, including methods added later.
+	// Object spread loses prototype methods and inherited capability accessors.
+	return new Proxy(provider, {
+		get(target, property) {
+			if (property === 'chatStream') return chatStream
+			const value: unknown = Reflect.get(target, property, target)
+			return typeof value === 'function' ? value.bind(target) : value
+		},
+	})
+}

package/src/public-runtime.ts

@@ -441,6 +441,14 @@ export {
 	DEFAULT_TIMEOUT_MS,
 	DEFAULT_TOKEN_BUDGET,
 	SupervisorAgent,
+	DEFAULT_RESERVED_AGENT_NAMES,
+	discoverAgentDefinitions,
+	EXPLORE_AGENT_DESCRIPTION,
+	EXPLORE_AGENT_ID,
+	EXPLORE_AGENT_PROMPT,
+	MAX_AGENT_FILE_CHARS,
+	parseAgentFile,
+	parseAgentMarkdown,
 } from './agents/index.js'
 
 // ─── registries, stores, managers, plugin, gateway ───────────────────────
@@ -529,11 +537,20 @@ export {
 } from './registry/index.js'
 
 export {
+	attachShellHooks,
+	createShellHook,
+	DEFAULT_SHELL_HOOK_TIMEOUT_MS,
 	discoverAllPluginDirs,
 	discoverPlugins,
 	loadPluginManifest,
+	MAX_SHELL_HOOK_TIMEOUT_MS,
 	PluginLifecycleManager,
 	PluginResolver,
+	runShellHook,
+	SHELL_HOOK_EVENTS,
+	SHELL_HOOKS_PLUGIN_ID,
+	shellHookMatches,
+	shellHookVerdict,
 } from './plugin/index.js'
 
 export {
@@ -919,29 +936,6 @@ export {
 	validatePrevArtifactChain,
 } from './session/intervention/index.js'
 
-export {
-	acceptLegacyContainerId,
-	/** @deprecated Use {@link acceptLegacyContainerId}. Removal is NZ-TOPIC-05. */
-	acquireMigrationLock,
-	DefaultFilesystemMigrator,
-	FilesystemMigrationError,
-	LEGACY_DEFAULT_PROJECT_PREFIX,
-	LEGACY_DEFAULT_SESSION_ID,
-	LOCK_REL_PATH,
-	loggingMigrationSink,
-	MARKER_REL_PATH,
-	MIGRATION_VERSION,
-	NOOP_FILESYSTEM_MIGRATION_SINK,
-	NOOP_MIGRATION_WARNING_SINK,
-	readMarker,
-	rejectLegacyContainerPrefix,
-	/** @deprecated Use {@link rejectLegacyContainerPrefix}. Removal is NZ-TOPIC-05. */
-	releaseMigrationLock,
-	StalePrefixError,
-	WINDOW_OPEN,
-	writeMarker,
-} from './session/migration/index.js'
-
 export {
 	ArchivalManager,
 	ArchiveNotConfiguredError,
@@ -1001,7 +995,6 @@ export { isConnectorActive } from './types/connector/core.js'
 export { CONNECTOR_SCOPE_ORDER } from './types/connector/scope.js'
 export { RoutingResponseSchema } from './types/decision/index.js'
 export { autoApproveHandler } from './types/hitl/index.js'
-export { UNKNOWN_TENANT_ID } from './types/ids/index.js'
 export { deriveChildState } from './types/invocation/index.js'
 export { assertMemoryStatus } from './types/memory/index.js'
 export {
@@ -1062,6 +1055,17 @@ export { compactNow, compactRegion } from './compaction/manual.js'
 // resume. Export the identity predicate rather than making every host copy the
 // marker string and eventually disagree with the writer.
 export { isCompactionMessage } from './compaction/summary.js'
+export {
+	DEFAULT_SALIENCE_CONFIG,
+	DEFAULT_SALIENCE_WEIGHTS,
+	buildGoal,
+	isStubbedNarration,
+	messageText,
+	planWorkingSet,
+	scoreMessages,
+} from './compaction/salience/index.js'
+export { DEFAULT_SOFT_TARGET, planSalienceWorkingSet } from './compaction/plan.js'
+export { CONSOLIDATION_TAG, consolidationEntry } from './compaction/consolidation.js'
 // The sibling state-bearing system message. A host that carries a Run's
 // conversation into a fresh query must distinguish this ledger from the fresh
 // identity/environment prompt floor without copying its private header string.
@@ -1181,13 +1185,33 @@ export type {
 // policy emits a durable event and only the run holds the emitter. The name
 // constant is exported so a host can recognise the unattended default.
 export { AUTO_APPROVE_POLICY_NAME } from './runtime/query/approval-policy.js'
+// The modes a host resolves the undecided under — prompt, auto,
+// accept-edits, plan, strict — as an `ApprovalPolicy`. See
+// `runtime/query/review-policy.ts`.
+export {
+	ACCEPT_EDITS_TOOLS,
+	PLAN_MODE_REFUSAL,
+	REVIEW_EXEMPT_WRITES,
+	REVIEW_MODES,
+	STRICT_MODE_REFUSAL,
+	batchNeedsReview,
+	createReviewHandler,
+	createReviewPolicy,
+	isReviewExempt,
+	isReviewMode,
+} from './runtime/query/review-policy.js'
 
 // The system prompt is open: a contribution registry the assembler
 // consumes, with skills as its first contributor. See `prompt/contributions.ts`.
 export {
+	CODING_AGENT_DELEGATION_DOCTRINE,
+	CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+	CODING_AGENT_WORKING_DOCTRINE,
+	PLAN_MODE_DOCTRINE,
 	PromptContributionCollisionError,
 	PromptContributionRegistry,
 	SKILLS_CONTRIBUTION_ID,
+	codingAgentDoctrineContribution,
 	skillsContribution,
 } from './prompt/index.js'
 
@@ -1297,9 +1321,6 @@ export type {
 export type { BroadcastHandoffDeps } from './session/handoff/broadcast.js'
 export type { SingleHandoffDeps } from './session/handoff/single.js'
 export type { InterventionChainLoader } from './session/intervention/prev-artifact.js'
-export type { FilesystemMigrationSink } from './session/migration/filesystem.js'
-export type { MigrationWarningSink } from './session/migration/id-prefix.js'
-export type { MigrationMarker } from './session/migration/marker.js'
 export type { ActionInput } from './tools/builtins/computer-use.js'
 export type { Project } from './types/project/entity.js'
 export type { CreatedLogger } from './utils/log/create-logger.js'
@@ -1307,3 +1328,9 @@ export type {
 	LoggerOptions,
 	MutableLogSinkCounters,
 } from './utils/log/types.js'
+export type { JobProcess } from './runtime/jobs/registry.js'
+export { WORKING_STATE_MIME } from './connector/mcp/adapter.js'
+
+export { TokenBudget, validateTokenBudgetSnapshot } from './run/token-budget.js'
+export { DiskTokenBudgetStore, openTokenBudget } from './store/run/token-budget-disk.js'
+export { validateTokenBudgetBinding } from './types/run/token-budget-store.js'

package/src/public-tools.ts

@@ -19,6 +19,7 @@ export { isWithin, resolveWithin, resolveWithinReal } from './tools/paths.js'
 // A host that surfaces its own untrusted content to a model needs the same
 // framing the kernel applies to connector prompts and delegated results.
 export { neutralizeEnvelopeDelimiter, wrapUntrusted } from './tools/untrusted-envelope.js'
+export { filterReadOnlyTools, filterToolsNamed } from './tools/roster.js'
 export type { UntrustedEnvelope } from './tools/untrusted-envelope.js'
 
 // ─── Built-in tools ──────────────────────────────────────────────────────
@@ -98,6 +99,10 @@ export {
 export { buildAdvisoryTools } from './tools/advisory/index.js'
 export { buildMemoryTools } from './tools/memory/index.js'
 export { buildCoordinatorTools } from './tools/coordinator/index.js'
+export {
+	buildAskUserQuestionTool,
+	type AskUserQuestionToolOptions,
+} from './tools/coordinator/ask-user-question.js'
 export { buildAgentTool, type AgentToolOptions } from './tools/coordinator/agent.js'
 
 // ─── RAG tool builder ────────────────────────────────────────────────────

package/src/public-types.ts

@@ -175,6 +175,21 @@ export type {
 } from './registry/index.js'
 
 export type { PluginLifecycleManagerConfig } from './plugin/lifecycle.js'
+export type {
+	AgentDefinitionRoot,
+	AgentFileDefinition,
+	DiscoverAgentDefinitionsOptions,
+	DiscoveredAgentDefinitions,
+	SkippedAgentFile,
+} from './agents/file-definitions.js'
+export type {
+	ShellHookEntry,
+	ShellHookEvent,
+	ShellHookInput,
+	ShellHookOptions,
+	ShellHookOutcome,
+	ShellHooksConfig,
+} from './plugin/shell-hook.js'
 
 export type {
 	PlanApprovalHandler,
@@ -263,6 +278,8 @@ export type {
 	PlanSlot,
 	ToolResultSlot,
 	WorkingState,
+	PinSlot,
+	WorkingStatePin,
 } from './compaction/index.js'
 export type * from './eval/index.js'
 export type * from './types/guardrail/index.js'
@@ -328,6 +345,34 @@ export type {
 } from './types/hitl/policy.js'
 
 export type {
+	GoalSources,
+	ProtectedReason,
+	SalienceConfig,
+	SalienceWeights,
+	ScoreOptions,
+	ScoredMessage,
+	WorkingSetAction,
+	WorkingSetOptions,
+	WorkingSetPlan,
+} from './compaction/salience/index.js'
+export type { ConsolidationMeta } from './compaction/consolidation.js'
+export type {
+	CompactionPlan,
+	CompactionPlanInput,
+	CompactionSkipReason,
+} from './compaction/plan.js'
+
+export type {
+	ReviewExemption,
+	ReviewMode,
+	ReviewPolicyOptions,
+	ToolReviewAnswer,
+	ToolReviewPrompt,
+	ToolReviewRequest,
+} from './runtime/query/review-policy.js'
+
+export type {
+	CodingAgentDoctrineOptions,
 	PromptContribution,
 	PromptContributionContext,
 	PromptPlacement,
@@ -373,3 +418,23 @@ export type {
 	TerminalSession,
 	TerminalSize,
 } from './sandbox/terminal.js'
+
+// Existing Topic snapshots can initialize an in-memory delegation store.
+export type { Topic, TopicStatus } from './types/topic/entity.js'
+
+export type {
+	TokenBudgetAccountSnapshot,
+	TokenBudgetRequestSnapshot,
+	TokenBudgetSnapshot,
+	TokenBudgetSummary,
+	TokenBudgetPersistence,
+} from './run/token-budget.js'
+export type {
+	TokenBudgetStore,
+	TokenBudgetScope,
+	TokenBudgetBinding,
+} from './types/run/token-budget-store.js'
+export type {
+	DiskTokenBudgetStoreConfig,
+	OpenTokenBudgetOptions,
+} from './store/run/token-budget-disk.js'

package/src/registry/command/kernel-commands.ts

@@ -53,11 +53,13 @@ export interface GoalCommandScope {
 	readonly activation?: SessionGoalActivation
 }
 
-const GOAL_USAGE = 'Usage: /goal [<objective>|clear|edit <objective>|pause|resume]'
+const GOAL_ARGUMENTS = '[status|set <objective>|<objective>|edit <objective>|pause|resume|clear]'
+const GOAL_USAGE = `Usage: /goal ${GOAL_ARGUMENTS}`
 
 type ParsedGoalCommand =
 	| { readonly kind: 'show' }
 	| { readonly kind: 'create'; readonly objective: string }
+	| { readonly kind: 'invalid-create' }
 	| { readonly kind: 'edit'; readonly objective: string }
 	| { readonly kind: 'invalid-edit' }
 	| { readonly kind: 'pause' }
@@ -68,6 +70,9 @@ function parseGoalCommand(args: readonly string[]): ParsedGoalCommand {
 	const input = args.join(' ').trim()
 	if (input.length === 0) return { kind: 'show' }
 	const control = input.toLowerCase()
+	if (control === 'status') return { kind: 'show' }
+	if (control === 'set') return { kind: 'invalid-create' }
+	if (/^set(?=\s)/iu.test(input)) return { kind: 'create', objective: input.slice(3).trim() }
 	if (control === 'clear') return { kind: 'clear' }
 	if (control === 'pause') return { kind: 'pause' }
 	if (control === 'resume') return { kind: 'resume' }
@@ -87,15 +92,15 @@ function goalCommands(goal: SessionGoal, armed: boolean): string {
 	if (goal.phase === 'paused' || goal.phase === 'blocked') {
 		return '/goal edit <objective>, /goal resume, /goal clear'
 	}
-	return '/goal <objective>, /goal clear'
+	return '/goal set <objective>, /goal clear'
 }
 
 function renderGoal(title: string, goal: SessionGoal, armed: boolean): string {
 	return [
 		title,
 		`Status: ${goal.phase}`,
-		`Automatic continuation: ${armed ? 'armed' : 'disarmed'}`,
-		`Rounds admitted: ${goal.roundsAdmitted} / ${goal.maxGoalRounds}`,
+		`Automatic continuation: ${armed ? 'enabled' : 'paused'}`,
+		`Automatic turns: ${goal.roundsAdmitted} / ${goal.maxGoalRounds}`,
 		...(goal.blockedReason
 			? [`Blocker: ${goal.blockedReason.code}: ${goal.blockedReason.message}`]
 			: []),
@@ -134,6 +139,11 @@ async function runGoalCommand(scope: GoalCommandScope | undefined, args: readonl
 							kind: 'ack' as const,
 							message: `No goal is currently set.\n${GOAL_USAGE}`,
 						}
+			case 'invalid-create':
+				return {
+					kind: 'refused' as const,
+					reason: `Setting a goal requires an objective.\n${GOAL_USAGE}`,
+				}
 			case 'invalid-edit':
 				return {
 					kind: 'refused' as const,
@@ -201,7 +211,7 @@ async function runGoalCommand(scope: GoalCommandScope | undefined, args: readonl
 					scope.activation?.arm(current)
 					return {
 						kind: 'ack' as const,
-						message: renderScopedGoal('Goal armed', current, scope),
+						message: renderScopedGoal('Goal resumed', current, scope),
 					}
 				}
 				const resumed = await scope.store.resumeGoal(
@@ -250,7 +260,7 @@ export function kernelHostCommands(options: KernelCommandOptions): HostCommandDe
 		{
 			name: 'goal',
 			description: 'Persist or inspect a completion goal for this conversation.',
-			hint: '[<objective>|clear|edit <objective>|pause|resume]',
+			hint: GOAL_ARGUMENTS,
 			handler: async ({ args }) => await runGoalCommand(options.goal, args),
 		},
 		{

package/src/registry/tool/execute.ts

@@ -5,6 +5,7 @@ import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
+import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
 import type {
 	LLMToolSchema,
 	PreparedToolExecution,
@@ -674,7 +675,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				if (mode === 'plan') {
 					const isReadOnly = isTrustedReadOnly(tool, finalInput)
 					if (!isReadOnly) {
-						const msg = `plan mode: non-read-only tool "${toolName}" blocked`
+						// The same words the review-time policy uses, so the model gets one
+						// instruction whichever door refused it.
+						const msg = `plan mode: non-read-only tool "${toolName}" blocked. ${PLAN_MODE_REFUSAL}`
 						span.setAttributes({
 							[NAMZU.TOOL_SUCCESS]: false,
 							[NAMZU.TOOL_ERROR]: msg,

package/src/run/LimitChecker.ts

@@ -49,7 +49,7 @@ export function checkLimitsDetailed(
 		// bound. Continuing here would be the check answering "the budget is
 		// satisfied" to the question "can the budget be evaluated?", which is
 		// the strongest available wrong answer — see
-		// docs/conventions/an-optional-dependency-may-not-degrade-a-check.md.
+		// "an optional dependency may not degrade a check".
 		if (state.unpricedTokens > 0) {
 			return { type: 'hard_stop', reason: 'cost_unmeasurable' }
 		}

package/src/run/drain.ts

@@ -334,7 +334,7 @@ export async function drainRuns(params: DrainRunsParams): Promise<DrainRunsResul
 	 * the check in the loop, which runs first. A branch nothing can reach is
 	 * a declaration nothing drives, so it is gone rather than covered by a
 	 * test that would have proved nothing
-	 * (`docs/conventions/declared-but-undriven.md`).
+	 * ("declared but undriven").
 	 */
 	const handle = async (entry: DurableRunEntry): Promise<void> => {
 		const claim = await claimRun(store, entry, {

package/src/run/reporter.ts

@@ -302,6 +302,21 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'background_job_exited':
+				log.info('Background job ended', {
+					'namzu.jobs.id': event.jobId,
+					'namzu.jobs.status': event.status,
+					...(event.exitCode !== undefined ? { 'namzu.jobs.exit_code': event.exitCode } : {}),
+				})
+				break
+			case 'memory_consolidated':
+				log.info('Run learnings consolidated into the memory store', {
+					'namzu.memory.id': event.memoryId,
+					'namzu.memory.decisions': event.decisions,
+					'namzu.memory.discoveries': event.discoveries,
+					'namzu.memory.failures': event.failures,
+				})
+				break
 			case 'compaction_tool_results_cleared':
 				// `info` on both branches. The relieved case is the run
 				// avoiding a summarization, which is good news worth stating;