@namzu/sdk 36.0.0 → 37.0.0

package/src/types/agent/task.ts

@@ -122,6 +122,7 @@ export interface AgentTask {
 	agentId: string
 	agent: Agent<BaseAgentConfig, BaseAgentResult>
 	childAbortController: AbortController
+	/** While pending admission this is the submitting authority; admitted tasks receive child scope. */
 	context: AgentTaskContext
 	state: AgentTaskState
 	result?: BaseAgentResult
@@ -142,6 +143,12 @@ export interface AgentTask {
  * WorkspaceRef triple atomically on every spawn.
  */
 export interface SendMessageOptions {
+	/**
+	 * Revalidate host authority before admission, including after a capacity wait.
+	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.
+	 */
+	readonly beforeStart?: () => Promise<void>
+
 	/** See {@link import('./scheduler.js').CreateTaskOptions.toolScope}. Deny-only. */
 	readonly toolScope?: { readonly deny: readonly string[] }
 	/** See {@link import('./scheduler.js').CreateTaskOptions.personaOverride}. */
@@ -179,6 +186,12 @@ export interface SendMessageOptions {
 }
 
 export interface AgentManagerConfig {
+	/** Reject a full parent immediately (default), or retain bounded pending task handles. */
+	capacityBehavior?: 'reject' | 'queue'
+
+	/** Maximum tasks awaiting admission across this manager. Defaults to 128. */
+	maxPendingTasks?: number
+
 	maxDepth: number
 
 	evictionMs: number

package/src/types/computer-use/index.ts

@@ -30,6 +30,12 @@ export interface ComputerUseCapabilities {
 	readonly keyboard: boolean
 	readonly cursorPosition: boolean
 	readonly clipboard: boolean
+	/** Exact action subset when known. Refines the broad flags; absent retains their legacy interpretation. */
+	readonly supportedActions?: readonly ComputerUseAction['type'][]
+	/** Supported click buttons; absent leaves button admission to the host. */
+	readonly mouseClickButtons?: readonly MouseButton[]
+	/** Supported drag buttons; absent leaves button admission to the host. */
+	readonly mouseDragButtons?: readonly MouseButton[]
 	/**
 	 * Why every flag above is false, when a host loaded but the desktop did
 	 * not answer — a WSL process with PowerShell and no interactive Windows

package/src/types/errors/catalog.ts

@@ -157,7 +157,7 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		id: 'provider.rate_limit',
 		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
 		message: 'The provider is rate limiting this run.',
-		hint: 'Automatic retries with backoff have already been exhausted. Lower concurrency, or wait for the quota window to reset before resuming.',
+		hint: 'Respect the provider retry delay when reported. Lower concurrency, or wait for the quota window to reset before resuming.',
 	},
 	{
 		id: 'provider.context_overflow',

package/src/types/hitl/index.ts

@@ -2,7 +2,7 @@ import type { WorkingStateSnapshot } from '../../compaction/wire.js'
 import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, UserMessage } from '../message/index.js'
 import type { PlanStatus } from '../plan/index.js'
 import type { TokenBudgetBinding } from '../run/token-budget-store.js'
 
@@ -212,6 +212,16 @@ export interface IterationCheckpoint {
 	runId: RunId
 	iteration: number
 	messages: Message[]
+	/**
+	 * Current operator/goal/steering text and provenance, independent of
+	 * compacted history. Attachments are not duplicated here. Older
+	 * checkpoints omit this field and use surviving history on resume.
+	 */
+	latestUserMessage?: UserMessage
+	/** Structured host-review rejections consumed at this checkpoint, independent of compacted messages. */
+	structuredReviewAttempts?: number
+	/** Native structured-output corrections consumed independently of message history. */
+	nativeStructuredAttempts?: number
 	tokenUsage: TokenUsage
 	costInfo: CostInfo
 	/**

package/src/types/memory/index.ts

@@ -31,11 +31,19 @@ export interface MemoryContent {
 	readonly metadata?: Record<string, unknown>
 }
 
+/** Metadata and body observed together at one store read boundary. */
+export interface MemoryRecord {
+	readonly entry: MemoryIndexEntry
+	readonly content: MemoryContent
+}
+
 export interface MemorySearchParams {
 	readonly query?: string
 	readonly tags?: string[]
 	readonly status?: MemoryStatus
 	readonly limit?: number
+	/** Match at least one exact normalized word token before limiting results. Empty means no constraint. */
+	readonly requiredIdentifiers?: readonly string[]
 }
 
 export interface MemorySearchResult {
@@ -52,10 +60,17 @@ export interface CreateMemoryParams {
 	readonly metadata?: Record<string, unknown>
 }
 
+/** Change a memory's content or explicitly archive/reactivate it. */
+export interface UpdateMemoryParams extends Partial<CreateMemoryParams> {
+	readonly status?: MemoryStatus
+}
+
 export interface MemoryStore {
 	create(params: CreateMemoryParams): Promise<{ entry: MemoryIndexEntry; content: MemoryContent }>
 	get(id: MemoryId): Promise<MemoryContent | undefined>
-	update(id: MemoryId, updates: Partial<CreateMemoryParams>): Promise<MemoryIndexEntry | undefined>
+	/** Current metadata/body snapshot; supports rechecking status after search. */
+	getRecord?(id: MemoryId): Promise<MemoryRecord | undefined>
+	update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined>
 	delete(id: MemoryId): Promise<boolean>
 	list(params?: MemorySearchParams): Promise<MemorySearchResult>
 }

package/src/types/project/entity.ts

@@ -18,6 +18,7 @@ import type { ProjectId } from '../session/ids.js'
  */
 export interface ProjectConfig {
 	maxDelegationDepth: number
+	/** Maximum pending or active direct delegations; completed history does not consume capacity. */
 	maxDelegationWidth: number
 	maxInterventionDepth: number
 	sharedMemoryStores?: readonly MemoryStoreRef[]

package/src/types/provider/config.ts

@@ -121,6 +121,8 @@ export interface MockProviderConfig extends MockScript {
  * degradation is loud instead of silent.
  */
 export interface ProviderCapabilities {
+	/** Native JSON Schema response-format mapping. Absent means unsupported. */
+	supportsNativeStructuredOutput?: boolean
 	supportsTools: boolean
 	supportsStreaming: boolean
 	supportsFunctionCalling: boolean

package/src/types/provider/model.ts

@@ -14,6 +14,10 @@ export interface ModelInfo {
 	 * the answer; it must not be read as text-only.
 	 */
 	inputModalities?: readonly ModelInputModality[]
+	/** Exact selectable effort levels for this model and route. Absent means unknown; [] means unsupported. */
+	reasoningEffortLevels?: readonly import('./chat.js').ReasoningEffort[]
+	/** Published default, when established; must belong to reasoningEffortLevels when both are present. */
+	reasoningEffortDefault?: import('./chat.js').ReasoningEffort
 	/**
 	 * Tokens the model's context holds, when the driver knows.
 	 *

package/src/types/run/answer-review.ts

@@ -29,6 +29,8 @@ export type AnswerReview =
 export interface AnswerReviewContext {
 	readonly runId: RunId
 	readonly iteration: number
+	/** Run cancellation; reviewers should forward it to verification operations. */
+	readonly signal?: AbortSignal
 	/** The full history, so a reviewer can see how the answer was reached. */
 	readonly messages: readonly Message[]
 }

package/src/types/run/events.ts

@@ -101,6 +101,16 @@ interface RunEventEnvelope {
 }
 
 type CoreRunEvent =
+	| {
+			type: 'tool_calls_admitted'
+			runId: RunId
+			kind: 'initialize' | 'batch' | 'nested' | 'retry'
+			/** Newly reserved attempts; zero only for ledger initialization. */
+			count: number
+			/** Cumulative reserved attempts, including abandoned reservations. */
+			used: number
+			limit: number
+	  }
 	| { type: 'run_started'; runId: RunId; systemPrompt?: string }
 	| { type: 'iteration_started'; runId: RunId; iteration: number }
 	/**

package/src/types/run/prepare-step.ts

@@ -1,5 +1,5 @@
 import type { RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, UserMessage } from '../message/index.js'
 import type { ToolChoice } from '../provider/chat.js'
 import type { Skill } from '../skills/index.js'
 import type { StepResult } from './step.js'
@@ -21,6 +21,24 @@ export interface PrepareStepContext {
 	readonly stepNumber: number
 	/** Full history as it stands, so a decision can read what happened. */
 	readonly messages: readonly Message[]
+	/**
+	 * Latest operator, goal-round, or steering input accepted by this run,
+	 * retained even when compaction removes it from `messages`. Project
+	 * instructions and task-completion context do not replace operator intent.
+	 */
+	readonly latestUserMessage?: UserMessage
+	/** The run's cancellation signal, for bounded asynchronous preparation. */
+	readonly signal?: AbortSignal
+	/**
+	 * Estimated room for additional step context after existing messages,
+	 * earlier stages' system/skills, and a response reserve. Recomputed for
+	 * each stage and its selected model; not a billing limit or fit guarantee.
+	 * `beforeStep` observes its existing boundary before compaction runs.
+	 */
+	readonly contextBudget?: {
+		readonly remainingTokens: number
+		readonly windowTokens: number
+	}
 	/** Every completed step, in order. */
 	readonly steps: readonly StepResult[]
 

package/src/types/structured-output/index.ts

@@ -1,10 +1,10 @@
 import type { z } from 'zod'
 
 /**
- * Configuration for structured output via tool constraint.
+ * Configuration for validated output via tool constraint or native JSON Schema.
  *
  * This configuration allows an agent to produce validated, typed output by
- * presenting the output schema as a special tool that the model must call.
+ * presenting the output schema as a tool by default, or as a native response format.
  */
 export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	/**
@@ -13,6 +13,9 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	 */
 	schema: TSchema
 
+	/** Default tool constraint, or native JSON schema on an explicitly capable driver. */
+	mode?: 'tool' | 'native'
+
 	/**
 	 * Turns spent re-prompting when the model answers in prose or fails
 	 * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
@@ -21,6 +24,16 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	 * than iterating against `maxIterations`.
 	 */
 	maxRetries?: number
+
+	/** Review the JSON-decoded result before settlement. Narrow the value before use: serialization may change schema output types. Exceptions fail the run; cancellation is propagated. */
+	review?: (
+		output: unknown,
+		context: import('../run/answer-review.js').AnswerReviewContext,
+	) =>
+		| import('../run/answer-review.js').AnswerReview
+		| Promise<import('../run/answer-review.js').AnswerReview>
+	/** Corrections allowed after host rejection, separate from schema retries. Default 3; zero allows no correction. */
+	maxReviews?: number
 }
 
 /**

package/src/types/tool/index.ts

@@ -14,6 +14,8 @@ import type { ToolPresentation } from './presentation.js'
 
 export interface ToolRegistryRef {
 	searchDeferred(query: string): ToolDefinition[]
+	/** Ranked active matches, when this registry supports active-tool discovery. */
+	searchActive?(query: string): ToolDefinition[]
 	activate(names: string[]): void
 	getAvailability(name: string): ToolAvailability
 }
@@ -633,6 +635,18 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
 
+	/**
+	 * Opt-in ordering boundary in a direct model tool-call batch. Earlier
+	 * calls settle before this call starts; later calls wait for this call
+	 * to settle (including failed results). Defaults to false. Independent
+	 * calls between barriers retain their existing concurrency-safe behavior.
+	 * Nested dispatch is owned by its enclosing call, not separately queued;
+	 * mark the enclosing tool as a barrier to isolate its nested operations.
+	 * Deadlines still abandon uncooperative tools: settlement does not prove
+	 * their external effects have stopped, and does not imply success.
+	 */
+	executionBarrier?: boolean
+
 	/**
 	 * Where this tool came from, when it did not come from here.
 	 *
@@ -763,6 +777,8 @@ export interface ToolRegistryContract {
 	suspendAll(): void
 	hasSuspended(): boolean
 	searchDeferred(query: string): ToolDefinition[]
+	/** Ranked active matches, when this registry supports active-tool discovery. */
+	searchActive?(query: string): ToolDefinition[]
 	getCallableTools(toolNames?: string[]): ToolDefinition[]
 
 	/**

package/src/utils/json-snapshot.ts

@@ -0,0 +1,76 @@
+/** Clone JSON data without invoking getters or silently dropping values. */
+export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unknown {
+	const active = new WeakSet<object>()
+	const copies = new WeakMap<object, object>()
+
+	const clone = (candidate: unknown, at: string): unknown => {
+		if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+			return candidate
+		}
+		if (typeof candidate === 'number') {
+			if (!Number.isFinite(candidate) || Object.is(candidate, -0)) {
+				throw new TypeError(`${at} must be a finite JSON number`)
+			}
+			return candidate
+		}
+		if (typeof candidate !== 'object') {
+			throw new TypeError(`${at} must be a JSON value, not ${typeof candidate}`)
+		}
+		if (active.has(candidate)) throw new TypeError(`${at} contains a cycle`)
+		const existing = copies.get(candidate)
+		if (existing) return existing
+
+		active.add(candidate)
+		try {
+			if (Array.isArray(candidate)) {
+				const extra = Reflect.ownKeys(candidate).filter(
+					(key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)),
+				)
+				if (extra.length > 0) throw new TypeError(`${at} has non-JSON array properties`)
+				const result: unknown[] = new Array(candidate.length)
+				copies.set(candidate, result)
+				for (let index = 0; index < candidate.length; index++) {
+					const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index))
+					if (!descriptor) throw new TypeError(`${at}[${index}] is a sparse array hole`)
+					if (!descriptor.enumerable || !('value' in descriptor)) {
+						throw new TypeError(`${at}[${index}] must be an enumerable data property`)
+					}
+					result[index] = clone(descriptor.value, `${at}[${index}]`)
+				}
+				if (freeze) Object.freeze(result)
+				return result
+			}
+
+			const prototype = Object.getPrototypeOf(candidate)
+			if (prototype !== Object.prototype && prototype !== null) {
+				throw new TypeError(`${at} must be a plain JSON object`)
+			}
+			// JSON does not preserve prototypes. Canonicalize both admitted plain
+			// shapes to an ordinary object so a disk checkpoint round-trip compares
+			// equal to a fresh preparation of the same semantic value. Properties
+			// are still defined explicitly, so a literal "__proto__" key remains
+			// data rather than changing this object's prototype.
+			const result: Record<string, unknown> = {}
+			copies.set(candidate, result)
+			for (const key of Reflect.ownKeys(candidate)) {
+				if (typeof key !== 'string') throw new TypeError(`${at} has a symbol property`)
+				const descriptor = Object.getOwnPropertyDescriptor(candidate, key)
+				if (!descriptor?.enumerable || !('value' in descriptor)) {
+					throw new TypeError(`${at}.${key} must be an enumerable data property`)
+				}
+				Object.defineProperty(result, key, {
+					value: clone(descriptor.value, `${at}.${key}`),
+					enumerable: true,
+					writable: !freeze,
+					configurable: !freeze,
+				})
+			}
+			if (freeze) Object.freeze(result)
+			return result
+		} finally {
+			active.delete(candidate)
+		}
+	}
+
+	return clone(value, path)
+}