@namzu/sdk 46.0.0 → 48.1.0

package/src/types/agent/reactive.ts

@@ -1,142 +1,5 @@
-import type { CompactionConfig } from '../../config/runtime.js'
-import type { QueryParams } from '../../runtime/query/index.js'
-import type { SteeringChannel } from '../../runtime/query/steering.js'
-import type { AdvisoryConfig } from '../advisory/index.js'
-import type { AuthorizationGateConfig } from '../authorization/index.js'
-import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index.js'
-import type { ResumeHandler } from '../hitl/index.js'
-import type { AgentPersona } from '../persona/index.js'
-import type { LLMProvider } from '../provider/index.js'
-import type { SandboxProvider } from '../sandbox/index.js'
-import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../session/index.js'
-import type { Skill } from '../skills/index.js'
-import type { StructuredOutputConfig } from '../structured-output/index.js'
-import type { ToolRegistryContract } from '../tool/index.js'
-import type { RepairToolCall } from '../tool/repair.js'
-import type { BaseAgentConfig, BaseAgentResult } from './base.js'
-import type { WorkingMemoryProvider } from './working-memory.js'
-
-export interface ReactiveAgentConfig extends BaseAgentConfig {
-	systemPrompt?: string
-	/** Provider-hosted search for this turn; the selected driver must support it. */
-	webSearch?: { mode: 'live' | 'cached' }
-
-	persona?: AgentPersona
-
-	/**
-	 * Channel a host uses to hand guidance to this turn's current turn.
-	 *
-	 * Present here for the same reason it is on `SupervisorAgentConfig`, and
-	 * the reason that file gives twice already: a capability the kernel
-	 * honours in `drainQuery` and not on the surface hosts actually
-	 * construct is a capability nobody can reach. This is the archetype most
-	 * hosts run, and it was the one that could not be steered at all.
-	 */
-	steering?: SteeringChannel
-
-	skills?: Skill[]
-
-	basePrompt?: string
-	provider: LLMProvider
-	tools: ToolRegistryContract
-
-	advisory?: AdvisoryConfig
-
-	/**
-	 * Optional capability-aware deny/allow gate for child tool calls.
-	 * Mirrors the same field on `SupervisorAgentConfig`; when omitted,
-	 * `drainQuery` falls back to its `autoApproveHandler` default
-	 * (every tool call auto-approves, no policy applied). Hosts that
-	 * trust their sandbox should still pass at least
-	 * `{ enabled: true, denyDangerousPatterns: true, ... }` so the
-	 * canonical brick patterns hard-deny instead of executing
-	 * silently.
-	 */
-
-	authorizationGate?: AuthorizationGateConfig
-
-	/**
-	 * Optional ephemeral sandbox provider. When set, drainQuery creates
-	 * a sandbox via `provider.create()` before the iteration loop and
-	 * routes filesystem / shell tool calls through it; on turn end the
-	 * SDK calls `sandbox.destroy()`. Hosts that want a per-task
-	 * container shared across supervisor + every child specialist run
-	 * pass the SAME provider instance to all of them — caching layered
-	 * on top of the provider keeps the underlying container alive.
-	 */
-	sandboxProvider?: SandboxProvider
-	/** See {@link QueryParams.sandboxTeardownTimeoutMs}. */
-	sandboxTeardownTimeoutMs?: number
-	/** See {@link QueryParams.outsideRootAccess}. Default `'refuse'`. */
-	outsideRootAccess?: 'refuse' | 'review'
-	/** See {@link QueryParams.sandboxEscape}. Default `'refuse'`. */
-	sandboxEscape?: 'refuse' | 'review'
-
-	/**
-	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
-	 * (no `WorkingStateManager`, compaction early-returns). Mirrors the field
-	 * on `SupervisorAgentConfig` so a child specialist can share the
-	 * supervisor's compaction settings.
-	 */
-	compactionConfig?: CompactionConfig
-
-	/**
-	 * Optional neutral working-memory seam — same contract as the field on
-	 * `SupervisorAgentConfig`. Absent ⇒ no block injected. A child specialist
-	 * sharing the supervisor's output dir passes the same provider.
-	 */
-	workingMemoryProvider?: WorkingMemoryProvider
-
-	/**
-	 * Loop-control and resilience seams, forwarded verbatim to `query()`.
-	 *
-	 * These existed on `QueryParams` and stopped there. `ReactiveAgent` is
-	 * the entry point most consumers actually use — it is what
-	 * `AgentManager` spawns and what the estate's own applications call —
-	 * and it forwarded none of them. So a per-tool deadline, a provider
-	 * retry policy, a guardrail, a stop condition: all of it was reachable
-	 * only by dropping down to `query()` and rebuilding the turn wiring by
-	 * hand. Features that a consumer cannot reach are features that do not
-	 * exist for them.
-	 *
-	 * Every field is optional and absent means exactly what it meant
-	 * before, so no existing agent changes behavior.
-	 */
-	resumeHandler?: ResumeHandler
-	retry?: QueryParams['retry']
-	toolTimeoutMs?: number
-	toolRetryBackoff?: QueryParams['toolRetryBackoff']
-	maxToolConcurrency?: number
-	maxToolOutputChars?: number
-	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']
-	/**
-	 * Cap on the RICH channel of a single tool result, in base64 characters.
-	 * `0` or absent disables it. Separate from {@link maxToolOutputChars}:
-	 * that one bounds characters the model reads, this one bounds the image
-	 * payload beside them, which no text budget ever touched.
-	 */
-	maxToolContentBytes?: number
-	repairToolCall?: RepairToolCall
-	stopWhen?: StopCondition
-	onStepFinish?: (step: StepResult) => void
-	prepareStep?: PrepareStepChain
-	/**
-	 * Refuse the next model call before it is made. See {@link BeforeStep}.
-	 * A throw fails CLOSED, opposite to `prepareStep` beside it.
-	 */
-	beforeStep?: BeforeStep
-
-	structuredOutput?: StructuredOutputConfig
-	inputGuardrails?: readonly InputGuardrailSpec[]
-	outputGuardrails?: readonly OutputGuardrailSpec[]
-
-	/**
-	 * Span this turn should hang off, when it is a delegated one. Absent for
-	 * a top-level turn, which correctly starts its own root trace.
-	 */
-	parentSpan?: import('@opentelemetry/api').Span
-}
-
-export interface ReactiveAgentResult extends BaseAgentResult {
-	toolCallCount: number
-}
+/** @deprecated Use QueryAgentConfig and QueryAgentResult for the generic query shell. */
+export type {
+	QueryAgentConfig as ReactiveAgentConfig,
+	QueryAgentResult as ReactiveAgentResult,
+} from './query.js'

package/src/types/agent/router.ts

@@ -28,6 +28,7 @@ export interface RouteDefinition {
 	matchPatterns?: string[]
 }
 
+/** @deprecated Configuration for the router example; define application routing as needed. */
 export interface RouterAgentConfig extends BaseAgentConfig {
 	routes: RouteDefinition[]
 	provider: LLMProvider
@@ -37,6 +38,7 @@ export interface RouterAgentConfig extends BaseAgentConfig {
 	maxRoutingRetries?: number
 }
 
+/** @deprecated Result of the router example. */
 export interface RouterAgentResult extends BaseAgentResult {
 	selectedRoute: string
 	routingDecision: RoutingDecision

package/src/types/agent/scheduler.ts

@@ -3,8 +3,9 @@ import type { TaskId } from '../ids/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { CancelCause } from '../session/cancel-cause.js'
 import type { ChildSessionLifecycleEvent, SessionEventListener } from '../session/events.js'
+import type { WorkspaceRef } from '../workspace/ref.js'
 import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
-import type { AgentTaskState } from './task.js'
+import type { AgentTaskState, ChildWorkspaceRequest } from './task.js'
 
 export interface TaskHandle {
 	readonly taskId: TaskId
@@ -13,6 +14,8 @@ export interface TaskHandle {
 	readonly result?: BaseAgentResult
 	readonly createdAt: number
 	readonly completedAt?: number
+	/** The workspace assigned to an explicitly isolated child, when admitted. */
+	readonly workspace?: WorkspaceRef
 }
 
 /**
@@ -29,6 +32,8 @@ export interface TaskHandle {
 export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
 
 export interface CreateTaskOptions {
+	/** Per-task filesystem choice, forwarded to the local manager at admission. */
+	readonly workspace?: ChildWorkspaceRequest
 	/**
 	 * Revalidate host authority at actual admission, including after a capacity wait.
 	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.

package/src/types/agent/supervisor.ts

@@ -1,5 +1,6 @@
 import type { CompactionConfig } from '../../config/runtime.js'
 import type { SteeringChannel } from '../../runtime/query/steering.js'
+import type { Toolset } from '../../toolsets/types.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { AuthorizationGateConfig } from '../authorization/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
@@ -8,13 +9,13 @@ import type { TaskRouterConfig } from '../router/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
 import type { StructuredOutputConfig } from '../structured-output/index.js'
-import type { ToolRegistryContract } from '../tool/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
 import type { AgentManagerContract } from './manager.js'
 import type { SiblingFailurePolicy, TaskScheduler } from './scheduler.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
+/** @deprecated Configuration for the supervisor example; hosts own their orchestration. */
 export interface SupervisorAgentConfig extends BaseAgentConfig {
 	provider: LLMProvider
 
@@ -59,7 +60,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	onPlanApproved?: () => Promise<void> | void
 	agentManager?: AgentManagerContract
-	tools?: ToolRegistryContract
+	/** Every tool this turn may see comes from one of these — see `toolsets/types.ts`. */
+	toolsets?: readonly Toolset[]
 
 	systemPrompt: string
 
@@ -234,6 +236,7 @@ export interface AgentTaskResult {
 	taskIndex: number
 }
 
+/** @deprecated Result of the supervisor example. */
 export interface SupervisorAgentResult extends BaseAgentResult {
 	taskResults: AgentTaskResult[]
 	completedTasks: number

package/src/types/agent/task.ts

@@ -1,6 +1,6 @@
 import type { SessionTokenBudget } from '../../store/budget/index.js'
 import type { ActorRef } from '../../types/session/actor.js'
-import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
+import type { WorkspaceBackendKind, WorkspaceRef } from '../../types/workspace/ref.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { SessionId, TaskId, TenantId, TurnId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
@@ -19,6 +19,19 @@ export type AgentTaskState =
 	| 'rejected'
 	| 'input-required'
 
+/** Per-spawn filesystem choice. Omission preserves the manager's existing behavior. */
+export type ChildWorkspaceRequest =
+	| { readonly mode: 'shared' }
+	| {
+			readonly mode: 'isolated'
+			readonly backend: 'git-worktree'
+			readonly baseRef?: string
+			/** Relative directory within the checkout where this child starts. */
+			readonly subdirectory?: string
+			/** The existing SDK behavior is `dispose`; CLI delegates select `retain`. */
+			readonly retention?: 'dispose' | 'retain'
+	  }
+
 export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 	return state === 'completed' || state === 'failed' || state === 'canceled' || state === 'rejected'
 }
@@ -206,6 +219,8 @@ export interface AgentTask {
 	pendingMessages: Message[]
 	createdAt: number
 	completedAt?: number
+	/** Populated after an explicitly isolated spawn is admitted. */
+	workspace?: WorkspaceRef
 
 	evictAfter?: number
 
@@ -219,6 +234,8 @@ export interface AgentTask {
  * WorkspaceRef triple atomically on every spawn.
  */
 export interface SendMessageOptions {
+	/** Explicit child filesystem policy; omitted preserves legacy backend behavior. */
+	readonly workspace?: ChildWorkspaceRequest
 	/**
 	 * Revalidate host authority before admission, including after a capacity wait.
 	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.
@@ -287,6 +304,9 @@ export interface SendMessageOptions {
 }
 
 export interface AgentManagerConfig {
+	/** When neither task workspace field is set, use the registered backend (legacy) or share cwd. */
+	workspaceDefault?: 'registered' | 'shared'
+
 	/** Reject a full parent immediately (default), or retain bounded pending task handles. */
 	capacityBehavior?: 'reject' | 'queue'
 

package/src/types/authorization/index.ts

@@ -27,6 +27,12 @@ export type AuthorizationRule =
 	| { type: 'allow_by_category'; categories: string[] }
 	| { type: 'allow_by_name'; toolNames: string[] }
 	| { type: 'deny_by_name'; toolNames: string[] }
+	| {
+			/** Match the owning toolset's host-assigned source id, never tool input or MCP metadata. */
+			type: 'by_source'
+			sources: string[]
+			decision: GateDecision
+	  }
 	| {
 			/**
 			 * Match a regular expression against the tool's NAME, the
@@ -169,6 +175,11 @@ const DenyByNameSchema = z.object({
 	type: z.literal('deny_by_name'),
 	toolNames: z.array(z.string()),
 })
+const BySourceSchema = z.object({
+	type: z.literal('by_source'),
+	sources: z.array(z.string().min(1)).min(1),
+	decision: z.enum(['allow', 'deny', 'review']),
+})
 const CustomPatternSchema = z.object({
 	type: z.literal('custom_pattern'),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
@@ -212,6 +223,7 @@ export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowByCategorySchema,
 	AllowByNameSchema,
 	DenyByNameSchema,
+	BySourceSchema,
 	CustomPatternSchema,
 	ArgumentPatternSchema,
 	AllowByTierSchema,

package/src/types/connector/mcp.ts

@@ -178,6 +178,14 @@ export interface MCPJsonRpcMessage {
 	error?: MCPJsonRpcError
 }
 
+/** A validated, bounded update from one MCP tool call. */
+export interface MCPProgressUpdate {
+	readonly progress: number
+	readonly total?: number
+	/** Server text with terminal controls removed, limited to 512 UTF-8 bytes. */
+	readonly message?: string
+}
+
 /** Authority for one MCP JSON-RPC request. */
 export interface MCPRequestOptions {
 	/**
@@ -187,6 +195,12 @@ export interface MCPRequestOptions {
 	 * waiting, not that an already-started remote side effect was rolled back.
 	 */
 	readonly signal?: AbortSignal
+	/**
+	 * Receive progress for this `tools/call` only. The client adds a unique
+	 * `_meta.progressToken` when this is supplied and stops delivery as soon as
+	 * the request completes, fails or is cancelled. Other methods ignore it.
+	 */
+	readonly onProgress?: (update: MCPProgressUpdate) => void
 	/**
 	 * Extra headers for this one request, merged over the transport's static
 	 * config headers (a collision resolves to this value) and under this same
@@ -276,6 +290,14 @@ export interface MCPToolDefinition {
 	 */
 	outputSchema?: MCPValueJsonSchema
 	annotations?: MCPToolAnnotations
+	/**
+	 * Server-defined data on the tool's own listing entry, carried opaquely:
+	 * this client acts on none of it. `mcpToolToToolDefinition` lands it in
+	 * `ToolDefinition.metadata` alongside the annotations that have no other
+	 * typed home, so a host reading either does not have to reach past this
+	 * client's own parsed shape back to the raw listing.
+	 */
+	_meta?: Record<string, unknown>
 }
 
 /**
@@ -409,6 +431,24 @@ export interface MCPInitializeResult {
 	protocolVersion: string
 	capabilities: MCPServerCapabilities
 	serverInfo: { name: string; version?: string }
+	/**
+	 * The server's own account of how to use it, read off the `initialize`
+	 * response verbatim. Only a legacy handshake carries one — the modern
+	 * era has no `initialize` round trip, so a modern connection's result
+	 * never populates this field (see `completeModernConnection` in
+	 * `client.ts`, which synthesises the rest of this shape from a discover
+	 * result that has no `instructions` concept at all).
+	 *
+	 * This is observability data, not steering: nothing in the SDK folds it
+	 * into an agent's instruction set automatically. It is server-authored,
+	 * remote-party text, and namzu already keeps that class of text out of
+	 * instruction/system position (see `connector/mcp/prompt-adapter.ts`
+	 * and `frameServerResult` in `connector/mcp/adapter.ts`, which frame
+	 * server-supplied prompts and tool results as untrusted data rather
+	 * than instructions). A host may display or log this field; it should
+	 * not read it into a prompt without the same untrusted framing.
+	 */
+	instructions?: string
 }
 
 export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
@@ -461,6 +501,12 @@ export interface MCPClientState {
 	status: MCPConnectionStatus
 	serverInfo?: { name: string; version?: string }
 	serverCapabilities?: MCPServerCapabilities
+	/**
+	 * The server's `initialize` instructions, captured verbatim. See
+	 * {@link MCPInitializeResult.instructions} — legacy handshakes only,
+	 * observability only, never auto-folded into an agent's instructions.
+	 */
+	serverInstructions?: string
 	connectedAt?: number
 	error?: string
 }

package/src/types/errors/index.ts

@@ -20,6 +20,21 @@ import { ProviderError, classifyProviderError } from '../provider/errors.js'
 export type NamzuErrorCode =
 	/** The turn was set up wrong — missing model, contradictory options. Retrying cannot help. */
 	| 'invalid_config'
+	/**
+	 * A caller's cached prior messages disagree with this session's log. A
+	 * message carrying an id disagrees when the log recorded it under that id
+	 * with different content (`'edited'`) or never recorded that id at all
+	 * (`'foreign'`); `details.messageId` names it. A message with no id
+	 * disagrees when the caller's whole no-id cache does not align as a
+	 * contiguous run ending the log's own fold — the shape a host's cache
+	 * always has when it is exactly the fold plus new messages appended after
+	 * it — yet some of it still matches the fold by value out of place
+	 * (`'unaligned'`; no `messageId`, since none of it carries one). Retrying
+	 * with the same messages cannot help; the host must pass only its new
+	 * messages, or re-read history from the session instead of reusing a
+	 * cached copy.
+	 */
+	| 'stale_cached_history'
 	/** The upstream model call failed. `details.providerCode` narrows it. */
 	| 'provider_error'
 	/** A tool could not be executed or resolved. */

package/src/types/hitl/index.ts

@@ -135,6 +135,19 @@ export interface ToolCallSummary {
 	 * approve it on their own. A `deny` rule still refuses it outright.
 	 */
 	escalation?: ToolCallEscalation
+	/**
+	 * The tool itself declared that this exact call always needs a person's
+	 * approval (`ToolDefinition.requiresApproval`), regardless of the host's
+	 * rules or the turn's mode.
+	 *
+	 * Computed once, when the batch is prepared for review, the same way
+	 * {@link isDestructive} is — so it survives a gate `allow` rule (the
+	 * decision is forced back to `review` before the rule can settle
+	 * anything) and is asked about, or refused unattended, in every mode,
+	 * like {@link escalation}. No grant, skill grant or `accept-edits`
+	 * exemption covers it, and a `deny` rule still wins.
+	 */
+	requiresApproval?: true
 	/**
 	 * Present when a skill loaded earlier in this turn pre-approved this call
 	 * through its `allowed-tools`, and nothing stronger stands in the way.
@@ -165,6 +178,30 @@ export interface ToolCallEscalation {
 	 * `confirmedEscalations`.
 	 */
 	sandboxEscape?: true
+	/**
+	 * Why a command's own program name — where `programPositions` (the SDK's
+	 * shared resolver for where a command line actually execs a program;
+	 * `packages/sdk/src/authorization/program.ts`) says one is actually
+	 * exec'd, after unwrapping any `sudo`/`env`/`nice`/`timeout`/…
+	 * re-exec chain, and independently for each `find -exec` clause — is not
+	 * knowable ahead of running it: the word itself is decided at runtime
+	 * (`$(echo rm) -rf x`, `env $(echo git) push`, `"$HOME"/bin/tool`), an
+	 * option on a wrapper this does not recognise stood in the way, the
+	 * position is inherently unreadable (`eval`/`source`/`.`, an `xargs`
+	 * program that is a shell or a `{}` placeholder), or an earlier command
+	 * set `PATH`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `BASH_ENV`, `ENV` or `IFS`
+	 * so even a literal name here cannot be trusted to resolve to what its
+	 * text says.
+	 *
+	 * No rule can be trusted to have matched a program whose name never
+	 * appears as such anywhere in the call's own text: `git push.*` does not
+	 * see `$(echo git) push`, and neither `env $(echo git) push` nor
+	 * `timeout 5 $(echo git) push` puts the program right after the wrapper's
+	 * own name. Present only for a tool that declares `commandArgument`.
+	 * Argument-level expansion alone does not set this — only a position
+	 * where a program name is actually decided.
+	 */
+	unknownProgram?: string
 }
 
 export interface ToolModification {
@@ -175,8 +212,28 @@ export interface ToolModification {
 
 export interface UserQuestionOption {
 	id: string
+	/**
+	 * The label as shown and as the answer quotes it. `ask_user_question`
+	 * takes out of it a recommendation marker the model wrote out of habit:
+	 * "(Recommended)" on any option, and "(Önerilen)", "(Empfohlen)", … on
+	 * a recommended option, when every option whose label ends in a
+	 * parenthesised group is recommended, did not end in "(Recommended)", and
+	 * ends in that same one. A group that differs between options, or is left
+	 * before "(Recommended)" ("Cloud (AWS) (Recommended)" → "Cloud (AWS)"),
+	 * is kept. The recommendation is `recommended`, so a host never has to
+	 * parse a label to find it. Apart from surrounding spaces and
+	 * "(Recommended)", an option that is not recommended keeps its label as
+	 * written.
+	 */
 	label: string
 	description?: string
+	/**
+	 * The model recommends this option: it set `recommended: true` on it, or
+	 * left the flag out and ended the label in "(Recommended)". A host marks
+	 * it (a badge, an emphasis) rather than relying on the label to say so.
+	 * Absent, not `false`, on every other option.
+	 */
+	recommended?: boolean
 }
 
 /**