@namzu/sdk 46.0.0 → 48.0.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/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/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

@@ -276,6 +276,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 +417,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 +487,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
 }
 
 /**

package/src/types/message/index.ts

@@ -1,4 +1,4 @@
-import type { GoalId } from '../ids/index.js'
+import type { GoalId, MessageId } from '../ids/index.js'
 
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
@@ -105,7 +105,7 @@ export interface Citation {
  * An attachment whose bytes are held by a store, not by the message.
  *
  * Structural rather than an import from `store/attachment`, so this types
- * module keeps depending on nothing — the same reasoning `ToolRegistryRef`
+ * module keeps depending on nothing — the same reasoning `ToolsView`
  * gives. `store/attachment` owns the resolution and its refusals; this is
  * the shape a message may carry.
  *
@@ -144,18 +144,106 @@ export interface ToolCall {
 	 * JSON payload, while provider/runtime recovery state lives here.
 	 */
 	metadata?: {
+		/**
+		 * The streamed arguments could not be read, and `function.arguments`
+		 * was normalized to `"{}"`. Set for every unreadable call, cut off or
+		 * malformed alike: the name predates that distinction, and
+		 * {@link inputError} is what says which it was.
+		 */
 		inputTruncated?: boolean
 		/**
-		 * The partial argument buffer as it arrived, when the stream cut off
-		 * mid-JSON. `function.arguments` is normalized to `"{}"` in that
-		 * case so tool args stay clean, which leaves this as the only record
-		 * of what the model was actually saying — and a `repairToolCall`
-		 * hook has nothing to repair without it.
+		 * The argument buffer as it arrived, when it could not be read.
+		 * `function.arguments` is normalized to `"{}"` in that case so tool
+		 * args stay clean, which leaves this as the only record of what the
+		 * model was actually saying — and a `repairToolCall` hook has nothing
+		 * to repair without it.
 		 */
 		partialArguments?: string
+		/**
+		 * Why the arguments could not be read. Present with
+		 * {@link inputTruncated} on every call the runtime marked; absent on a
+		 * call marked by an older runtime, which recorded only the flag.
+		 */
+		inputError?: ToolInputError
 	}
 }
 
+/**
+ * Why a streamed tool call's arguments could not be read. See
+ * {@link ToolInputError}.
+ */
+export type ToolInputErrorReason = 'truncated' | 'malformed'
+
+/**
+ * A tool call whose streamed arguments did not parse as JSON, and why.
+ *
+ * An output limit, a content filter or a dropped stream stops a response
+ * wherever it is, so only the call the response was streaming at that moment
+ * can have been cut off: the last one, with nothing the model streamed after
+ * it. For that call the finish reason decides, never the text:
+ *
+ * - `truncated` — the response stopped before the model closed the
+ *   arguments. It reached its output limit (`finishReason: 'length'`), a
+ *   content filter stopped it (`'content_filter'`), or the stream ended
+ *   without reporting a finish reason at all.
+ * - `malformed` — the response finished normally (`'stop'` or
+ *   `'tool_calls'`) and the arguments still were not valid JSON.
+ *
+ * Every other unreadable call is `malformed`, whatever the finish reason:
+ * the model moved on to more text, reasoning or another call, so it had
+ * finished writing this one.
+ */
+export interface ToolInputError {
+	readonly reason: ToolInputErrorReason
+	/** How the response ended, as the provider reported it. Absent when the stream reported nothing. */
+	readonly finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * `'context_window'` when a `'length'` finish was the model's context
+	 * window rather than its output token limit (`StreamChunk.finishDetail`).
+	 */
+	readonly finishDetail?: 'context_window'
+	/** The JSON parser's own message. */
+	readonly parseError: string
+	/**
+	 * Zero-based character offset in the arguments where parsing failed: the
+	 * first character that cannot continue valid JSON, or their length when
+	 * the text simply ended. Found by scanning the arguments, so it is there
+	 * when {@link parseError} names no position, as for a bare `True` or
+	 * `None`.
+	 */
+	readonly offset?: number
+	/** How many characters of arguments arrived. */
+	readonly length: number
+	/**
+	 * How many characters the response streamed before this call began: its
+	 * text, its visible reasoning and the arguments of earlier tool calls.
+	 * Text a driver adds of its own is not counted. For a `truncated` call,
+	 * which nothing followed, this plus {@link length} is everything the
+	 * response streamed as text. It is not everything the response spent:
+	 * reasoning a provider does not stream (encrypted, summarised, or only
+	 * counted) uses the output limit too, and {@link outputTokens} and
+	 * {@link reasoningTokens} are what show it.
+	 */
+	readonly precedingLength: number
+	/**
+	 * The output tokens the whole response used, reasoning included, as the
+	 * provider reported them when it ended. Present on a `truncated` call when
+	 * the provider reported any.
+	 *
+	 * After an output limit it says whether the visible text accounts for the
+	 * limit: when most of the output went to reasoning, or to anything else
+	 * the stream did not carry, the call is not what filled the response, and
+	 * the model is told so rather than told to shrink the call.
+	 */
+	readonly outputTokens?: number
+	/**
+	 * Of {@link outputTokens}, the tokens the provider says went to reasoning.
+	 * Present only when the provider reports that split; absent means unknown,
+	 * not zero.
+	 */
+	readonly reasoningTokens?: number
+}
+
 export interface BaseMessage {
 	/**
 	 * Widened from `string | null` so `ToolMessage` can carry content
@@ -167,6 +255,22 @@ export interface BaseMessage {
 	content: string | null | readonly ToolResultBlock[]
 	timestamp?: number
 	cacheHint?: CacheHint
+	/**
+	 * The id of the durable `message` record this message was written as, or
+	 * a `message_replaced` record's `targetMessageId` when a guardrail,
+	 * review or structured-output override replaced its content in place.
+	 * Absent means the kernel has not recorded this exact message: a host
+	 * just constructed it, or it is a compaction's own summary (a bulk
+	 * spilled or inline array, which carries no per-message id — see
+	 * `docs/sdk/session-log.md`).
+	 *
+	 * Set by the kernel alone, never by a caller: `query()` stamps every
+	 * message it folds from the session log or records fresh, on `Turn.messages`,
+	 * on the messages `onConversationMessages` reports, and on a checkpoint's
+	 * restored messages. A caller that mints its own id here gets `conflict`
+	 * on the next turn — this log never recorded it under that name.
+	 */
+	readonly id?: MessageId
 	/**
 	 * Exempt this message from compaction and from tool-result clearing.
 	 *
@@ -248,6 +352,8 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'auto-continuation',
 	'job-exit',
 	'limit-finalization',
+	'peer-message',
+	'peer-notice',
 	'repeat-call',
 	'steering',
 	'step-context',
@@ -445,6 +551,13 @@ export type ToolResultBlock =
  */
 export type ToolResultContent = string | readonly ToolResultBlock[]
 
+/** A schema reveal bound to the source that contributed that exact tool. */
+export interface ToolRevealReceipt {
+	readonly name: string
+	readonly sourceId: string
+	readonly sourceKind: import('../toolset/index.js').ToolSourceKind
+}
+
 export interface ToolMessage extends BaseMessage {
 	role: 'tool'
 	content: ToolResultContent
@@ -460,6 +573,19 @@ export interface ToolMessage extends BaseMessage {
 	 * fired and namzu relied on prose formatting to convey failure.
 	 */
 	isError?: boolean
+	/**
+	 * Source-bound receipts for deferred schemas loaded by a successful
+	 * {@link ToolResult.reveals} (`types/tool/index.ts`). The executor writes
+	 * these onto the message it built from that result.
+	 *
+	 * This is what `ToolManager.availability` (`toolsets/manager.ts`) scans
+	 * the post-compaction history for, instead of a mutable activation map:
+	 * a deferred tool is active once a matching receipt appears after the
+	 * last compaction summary and the host still reports it ready. Persisted
+	 * like any other message field — a session log or checkpoint already
+	 * carries this too, with nothing extra to serialize.
+	 */
+	revealedTools?: readonly ToolRevealReceipt[]
 }
 
 export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
@@ -539,12 +665,14 @@ export function createToolMessage(
 	content: ToolResultContent,
 	toolCallId: string,
 	isError?: boolean,
+	revealedTools?: readonly ToolRevealReceipt[],
 ): ToolMessage {
 	return {
 		role: 'tool',
 		content,
 		toolCallId,
 		...(isError !== undefined ? { isError } : {}),
+		...(revealedTools && revealedTools.length > 0 ? { revealedTools } : {}),
 		timestamp: Date.now(),
 	}
 }