@namzu/sdk 40.0.0 → 42.0.0

package/src/types/connector/mcp.ts

@@ -40,11 +40,40 @@ export interface MCPStdioTransportConfig extends MCPTransportConfigBase {
 	cwd?: string
 }
 
+/**
+ * Anything that answers like `fetch`, restricted to the request shape the
+ * MCP HTTP transports actually send: a URL string, an optional
+ * method/headers/body, `redirect` (both transports pin this to `'manual'`
+ * so a caller cannot silently re-enable auto-following a redirect), and an
+ * abort signal.
+ *
+ * Structurally identical in spirit to `bridge/a2a/client.ts`'s `FetchLike`
+ * — the same injectable, socket-free function shape, so a test needs no
+ * socket — but the return type stays the real `Response` rather than that
+ * bridge's narrower `{ok, status, json(), text()}` duck type: both MCP
+ * transports already read `.headers` (content type, session id) and one of
+ * them reads `.body` as a stream (the SSE GET), neither of which the A2A
+ * bridge's version exposes. Re-declared here, rather than imported from the
+ * A2A bridge, so that bridge is not forced to grow fields it does not use.
+ */
+export type MCPFetchLike = (
+	input: string,
+	init?: {
+		method?: string
+		headers?: Record<string, string>
+		body?: string
+		redirect?: 'manual' | 'follow' | 'error'
+		signal?: AbortSignal
+	},
+) => Promise<Response>
+
 export interface MCPHttpSseTransportConfig extends MCPTransportConfigBase {
 	type: 'http-sse'
 	url: string
 	headers?: Record<string, string>
 	timeoutMs?: number
+	/** Injected in place of the ambient global `fetch`. Defaults to it. */
+	fetch?: MCPFetchLike
 }
 
 export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase {
@@ -52,6 +81,8 @@ export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase
 	url: string
 	headers?: Record<string, string>
 	timeoutMs?: number
+	/** Injected in place of the ambient global `fetch`. Defaults to it. */
+	fetch?: MCPFetchLike
 }
 
 export type MCPTransportUnion =
@@ -65,6 +96,79 @@ export interface MCPJsonRpcError {
 	data?: unknown
 }
 
+/**
+ * A protocol revision this client can still negotiate DOWN to when a server
+ * does not speak the current spec, newest first.
+ *
+ * Kept as a literal union (rather than just `string`) so a caller pattern
+ * matching on `McpEra` gets real exhaustiveness checking; the runtime array
+ * of the same values lives in `constants/mcp` and is typed against this.
+ */
+export type McpLegacyVersion = '2025-11-25' | '2025-06-18' | '2025-03-26' | '2024-11-05'
+
+/**
+ * A protocol revision this client speaks WITHOUT the `initialize`
+ * handshake.
+ *
+ * A modern connection is stateless: there is no handshake, no session id,
+ * and every request carries its own protocol version, client capabilities
+ * and client info in `_meta`. `connect()` probes for one before it offers
+ * the legacy handshake.
+ */
+export type McpModernVersion = '2026-07-28'
+
+/**
+ * Which family of the wire protocol a connection resolved to, and which
+ * exact revision within it.
+ *
+ * `kind` alone tells a caller which rules apply — whether `_meta` and the
+ * stateless per-request shape are in play, or the `initialize` handshake
+ * and (for 2025-06-18 and later) the `MCP-Protocol-Version` header — without
+ * re-deriving it from the version string on every read.
+ *
+ * `MCPClient.connect()` resolves this by probing for a modern peer first
+ * and falling back to the legacy `initialize` handshake, so which arm a
+ * given connection lands on is the server's answer, not a configuration.
+ */
+export type McpEra =
+	| { readonly kind: 'modern'; readonly version: McpModernVersion }
+	| { readonly kind: 'legacy'; readonly version: McpLegacyVersion }
+
+/**
+ * What a modern server answers `server/discover` with.
+ *
+ * The modern era's replacement for the `initialize` result: it names the
+ * revisions the server speaks, what it can do, and — under the reserved
+ * `_meta` key — who it is. Every field is optional on the wire as far as
+ * this client is concerned, because the one thing it MUST be able to do
+ * with a malformed answer is decline to treat it as proof of a modern peer.
+ */
+export interface MCPDiscoverResult {
+	/** Newest first is conventional but not required; this client sorts. */
+	supportedVersions?: readonly string[]
+	capabilities?: MCPServerCapabilities
+	_meta?: Record<string, unknown>
+}
+
+/**
+ * Where a resolved {@link McpEra} is remembered between connections.
+ *
+ * The spec's own guidance: a client SHOULD cache the era for the lifetime
+ * of the server process (stdio) or the origin (HTTP) and re-probe if the
+ * cached assumption later fails. Without it every connection to a legacy
+ * server pays a wasted probe round trip.
+ *
+ * An interface rather than a module-level `Map` because a process-global
+ * cache leaks between tests and would make a conformance suite depend on
+ * the order its cases happen to run in. `MCPClientConfig.eraCache` injects
+ * one; omitting it uses a process-wide default.
+ */
+export interface MCPEraCache {
+	get(key: string): McpEra | undefined
+	set(key: string, era: McpEra): void
+	delete(key: string): void
+}
+
 export interface MCPJsonRpcMessage {
 	jsonrpc: '2.0'
 	id?: string | number
@@ -83,12 +187,48 @@ export interface MCPRequestOptions {
 	 * waiting, not that an already-started remote side effect was rolled back.
 	 */
 	readonly signal?: AbortSignal
+	/**
+	 * Extra headers for this one request, merged over the transport's static
+	 * config headers (a collision resolves to this value) and under this same
+	 * call's `bearerToken`, if both are given.
+	 *
+	 * The protocol's own headers are the exception: `MCP-Protocol-Version`,
+	 * `Mcp-Method` and `Mcp-Name` mirror values inside the request this call
+	 * is sending, and a server rejects a header that disagrees with the body
+	 * it mirrors. A value given here under one of those names — matched
+	 * without regard to case — is refused and warn-logged rather than put on
+	 * the wire.
+	 *
+	 * A transport with no header concept (stdio) receives the field and does
+	 * nothing with it.
+	 */
+	readonly headers?: Readonly<Record<string, string>>
+	/**
+	 * Sent as `Authorization: Bearer <bearerToken>` on this one request.
+	 *
+	 * Overrides a configured `Authorization` header — static or supplied via
+	 * `headers` above — for this request only; it never touches a
+	 * differently-named header such as a static `X-API-Key`. Omit it and a
+	 * configured `Authorization` header is left exactly as configured.
+	 */
+	readonly bearerToken?: string
 }
 
 /** Authority for one transport write and any response body it consumes. */
 export interface MCPTransportSendOptions {
 	/** A pre-aborted signal starts no transport work. */
 	readonly signal?: AbortSignal
+	/**
+	 * Extra headers for this one send.
+	 *
+	 * An HTTP-speaking transport merges these over its static config
+	 * headers; a transport with no header concept (stdio) receives the
+	 * field and does nothing with it. Introduced so the client — which
+	 * alone knows the negotiated era — can ask for `MCP-Protocol-Version`
+	 * on a post-initialize request without the transport having to know
+	 * what a protocol version is.
+	 */
+	readonly headers?: Readonly<Record<string, string>>
 }
 
 export interface MCPTransport {
@@ -138,10 +278,38 @@ export interface MCPToolDefinition {
 	annotations?: MCPToolAnnotations
 }
 
+/**
+ * Audience/priority/freshness hints a server may attach to a content block,
+ * part of the schema since 2025-06-18. Advisory only: namzu does not act on
+ * any of these fields today, but drops none of them either — they survive
+ * into `ToolResult.data` for a host that wants to read them.
+ *
+ * Distinct from {@link MCPToolAnnotations}, which describes a TOOL
+ * (read-only, destructive, …); this describes one piece of CONTENT.
+ */
+export interface MCPContentAnnotations {
+	audience?: Array<'user' | 'assistant'>
+	priority?: number
+	lastModified?: string
+}
+
 export type MCPContentBlock =
 	| { type: 'text'; text: string }
 	| { type: 'image'; data: string; mimeType: string }
-	| { type: 'resource'; resource: { uri: string; mimeType?: string; text?: string } }
+	| {
+			type: 'resource'
+			resource: { uri: string; mimeType?: string; text?: string; blob?: string }
+			annotations?: MCPContentAnnotations
+	  }
+	/** Since 2025-03-26. Raw audio bytes, base64-encoded like `image`. */
+	| { type: 'audio'; data: string; mimeType: string }
+	/**
+	 * Since 2025-06-18. A pointer to a resource the server has NOT embedded
+	 * inline — unlike `resource`, which always carries `text` or `blob`.
+	 * Because this block carries no content at all, the adapter names it
+	 * for the model rather than fabricating text the server never sent.
+	 */
+	| { type: 'resource_link'; uri: string; name: string; description?: string; mimeType?: string }
 
 export interface MCPToolResult {
 	content: MCPContentBlock[]
@@ -160,6 +328,23 @@ export interface MCPToolResult {
 	_meta?: Record<string, unknown>
 }
 
+/**
+ * One thing the client would have to do that it never declared it could —
+ * elicit input, sample a message, list roots, or something a later spec
+ * revision defines. Only `method` is read by this client; every other field
+ * is carried opaquely so a shape it does not understand still names itself.
+ *
+ * namzu declares `clientCapabilities: {}` in every era, so MRTR rule 7 — a
+ * server MUST NOT send an `inputRequests` entry for a capability the client
+ * did not declare — means a CONFORMING server never produces one of these.
+ * The type exists for the defensive path: a non-conforming server's demand
+ * is named and refused rather than silently misread as an ordinary result.
+ */
+export interface MCPInputRequest {
+	readonly method: string
+	readonly [key: string]: unknown
+}
+
 export interface MCPResource {
 	uri: string
 	name: string
@@ -242,6 +427,25 @@ export interface MCPClientConfig {
 	 * forever — no error, no failure, just a run that stopped.
 	 */
 	requestTimeoutMs?: number
+	/**
+	 * How long `connect()`'s era probe waits for an answer before deciding
+	 * the peer speaks a legacy revision. Defaults to
+	 * `DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS`.
+	 *
+	 * Never longer than `requestTimeoutMs`: a probe is a request, and a
+	 * probe that outlived the deadline every other request is held to would
+	 * be a connect that hangs past its own timeout.
+	 */
+	eraProbeTimeoutMs?: number
+	/**
+	 * Where this client reads and records the resolved era.
+	 *
+	 * Defaults to a process-wide cache shared by every `MCPClient`, which is
+	 * the point — two clients reaching the same origin should not each pay a
+	 * probe. Inject a fresh one to isolate a test, or a longer-lived one to
+	 * scope the memory to a host rather than the process.
+	 */
+	eraCache?: MCPEraCache
 	/**
 	 * A pre-built logger. Threaded into the transport `MCPClient` constructs
 	 * internally (`createTransport`), so a caller that supplies this gets a

package/src/types/run/events.ts

@@ -812,6 +812,62 @@ type CoreRunEvent =
 			/** Approved plan edge carried while the blocking tool is still live. */
 			planId?: string
 			planStepId?: string
+			/**
+			 * How the host that delegated this child wants it GROUPED on screen —
+			 * a shared label over a set of related delegations, typically one
+			 * operator-visible piece of work several children are doing together.
+			 *
+			 * These fields are display annotations only; they do not create
+			 * dependencies, barriers, or serial execution. Nothing in the kernel
+			 * reads them: admission, ordering and concurrency come from the
+			 * scheduler and from {@link planId}/{@link planStepId}, which is the
+			 * field pair that DOES carry correlation a host may act on. A reader
+			 * who infers execution structure from a label here has inferred it
+			 * from a caption.
+			 *
+			 * Absent unless the delegating host supplied them, which is the
+			 * normal case — a host that groups nothing sends nothing, and a
+			 * consumer written before these existed reads the same event it
+			 * always did.
+			 *
+			 * They ride this event rather than staying in the delegating
+			 * process's memory for REACH: a consumer watching from outside
+			 * that process — another listener, or an SSE client — can rebuild
+			 * the same picture instead of seeing an undifferentiated list of
+			 * children.
+			 *
+			 * Reach is not durability, and this event buys only the first.
+			 * Like every delegation lifecycle event, it is handed straight to
+			 * a host's listener and never enters a run's log — which is what
+			 * the absent `seq` on this variant says, and what the `seq` doc
+			 * above spells out. A label here is therefore written nowhere by
+			 * the kernel and does not survive a restart of the host that chose
+			 * it; a host wanting the grouping to outlive its process records it
+			 * from the listener.
+			 */
+			workflow?: string
+			/**
+			 * Display group WITHIN {@link workflow} — a stage of that work, as
+			 * the delegating host labelled it. Display-only on the same terms as
+			 * {@link workflow}: it creates no dependencies, barriers or serial
+			 * execution, and two children naming the same phase are not thereby
+			 * sequenced or synchronised.
+			 */
+			phase?: string
+			/**
+			 * Longer text explaining {@link phase}, for a surface that has room
+			 * to show it. Display-only on the same terms as {@link workflow}.
+			 */
+			phaseDetail?: string
+			/**
+			 * Where {@link phase} sits in the host's intended DISPLAY order,
+			 * zero-based. Display-only on the same terms as {@link workflow}: it
+			 * orders a list on a screen and orders nothing that runs. Children in
+			 * one phase are expected to carry the same value; a consumer that
+			 * sees two disagree should keep the first rather than resequence,
+			 * because nothing here is authoritative enough to arbitrate.
+			 */
+			phaseOrder?: number
 	  }
 	| {
 			type: 'agent_completed'

package/src/types/run/store.ts

@@ -28,6 +28,7 @@ import type { RunEvidenceScope, RunTextEvidenceSource } from '../../store/eviden
  * re-keyed per call, it happens once, deliberately, as its own change.
  */
 
+import type { RunExecutionStatus } from '../common/index.js'
 import type { Message } from '../message/index.js'
 import type { AuditEvent } from './audit.js'
 import type { Run } from './entity.js'
@@ -103,6 +104,47 @@ export type ToolExecutionRecord =
 	| (CompletedToolRecord & { readonly status: 'completed' })
 	| { readonly toolUseId: string; readonly toolName: string; readonly status: 'started' }
 
+/**
+ * One delegated child run found on disk under its parent's `children/`
+ * directory, as {@link import('../../store/run/disk.js').RunDiskStore.listChildren}
+ * reports it.
+ *
+ * A DISCOVERY record, not the child's evidence: every field here comes from
+ * the child's `run.json`, and the transcript, message snapshot and report
+ * beside it stay on disk until something asks for them. {@link dir} is what
+ * that something reads from.
+ *
+ * Everything the file supplies is optional, because a `run.json` is written
+ * by the child's own terminal path and a process killed before it got there
+ * leaves a directory whose other evidence is still worth opening. An absent
+ * field is "this file did not say", never a zero or an empty string.
+ */
+export interface DelegatedChildRun {
+	/**
+	 * The child's run id, taken from the directory name.
+	 *
+	 * The location is the fact: `initRun` names the directory after the run
+	 * it binds, so a `run.json` whose `id` disagrees with its own directory
+	 * was moved or hand-edited, and the directory is the half that decides
+	 * where the evidence actually is.
+	 */
+	readonly id: string
+	/** The parent run whose `children/` directory holds this one. */
+	readonly parentRunId: string
+	/** Absolute path to the child's evidence directory. */
+	readonly dir: string
+	readonly agentId?: string
+	readonly agentName?: string
+	/** `metadata.config.model` — the model the child was configured with. */
+	readonly model?: string
+	readonly status?: RunExecutionStatus
+	readonly startedAt?: number
+	readonly endedAt?: number
+	/** `tokenUsage.totalTokens` — this child's own cumulative spend. */
+	readonly totalTokens?: number
+	readonly depth?: number
+}
+
 /** Absence proves no recorded start only when the whole selected log is complete. */
 export interface ToolExecutionSnapshot {
 	readonly complete: boolean

package/src/types/sandbox/index.ts

@@ -261,6 +261,35 @@ export interface SandboxTcpConnectOptions {
 	readonly host?: '127.0.0.1' | '::1'
 }
 
+/**
+ * What to read, and how to stop reading it. Every field is optional, so
+ * `readFile(path)` and `readFile(path, {})` mean the same thing: the whole
+ * file.
+ */
+export interface SandboxReadFileOptions {
+	/** First byte to read. Defaults to 0. */
+	readonly offset?: number
+	/**
+	 * How many bytes to read. Defaults to the rest of the file. A range
+	 * that runs past the end returns the bytes that exist, not an error —
+	 * a caller resuming from a remembered offset must be able to ask
+	 * without knowing the answer first.
+	 *
+	 * **A backend may cap how large a single range it will serve**, and
+	 * one past that cap is REFUSED rather than shortened — a caller that
+	 * asked for 4 MiB, got 1 MiB and was told nothing would read the short
+	 * answer as the end of its range. The agent-backed backends cap it at
+	 * `NAMZU_AGENT_READ_FILE_RANGE_BYTES` (1 MiB by default), because one
+	 * range is one wire frame there; a provider reading from local disk has
+	 * no such ceiling. A caller that wants more than a frame's worth in one
+	 * call iterates {@link Sandbox.readFileStream} instead, which is not
+	 * capped.
+	 */
+	readonly length?: number
+	/** Aborts the read. */
+	readonly signal?: AbortSignal
+}
+
 export interface Sandbox {
 	readonly id: SandboxId
 	readonly status: SandboxStatus
@@ -323,7 +352,46 @@ export interface Sandbox {
 	 */
 	openTcpConnection?(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>
 	writeFile(path: string, content: string | Buffer): Promise<void>
-	readFile(path: string): Promise<Buffer>
+	/**
+	 * Read a file out of the sandbox.
+	 *
+	 * `options` is optional in both directions, which is what keeps this
+	 * source-compatible: a caller may go on writing `readFile(path)`, and a
+	 * backend may go on declaring the one-parameter form and still satisfy
+	 * this signature. A backend that accepts the parameter and IGNORES
+	 * `offset`/`length` does not — returning the whole file where a slice
+	 * was asked for is a wrong answer, not a degraded one, so such a
+	 * backend must reject instead.
+	 *
+	 * @param options.offset First byte to read. Defaults to 0.
+	 * @param options.length How many bytes to read. Defaults to the rest of
+	 *   the file. A range that runs past the end returns the bytes that
+	 *   exist rather than failing.
+	 * @param options.signal Aborts the read.
+	 */
+	readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer>
+	/**
+	 * Read a file as a stream of chunks, so neither the sandbox nor this
+	 * process ever holds the whole of it.
+	 *
+	 * Optional, in the same way {@link Sandbox.openTerminal} is: a backend
+	 * that cannot read a file incrementally must OMIT this rather than
+	 * implement it by reading the file whole and chopping the result up,
+	 * which would give a caller the bounded-memory behaviour it asked for in
+	 * name only. A caller that needs the bound therefore refuses an absent
+	 * method rather than falling back to {@link Sandbox.readFile}.
+	 *
+	 * Chunk boundaries are not part of the contract — only the order and
+	 * the concatenation are. Aborting `options.signal`, or leaving the loop
+	 * early, must stop the transfer and release whatever the sandbox opened
+	 * for it.
+	 *
+	 * Hosts that drain agent-produced output files before {@link destroy}
+	 * (see {@link listFiles}) are the reason this exists: those files are
+	 * routinely tens to hundreds of megabytes, and a whole-file read of one
+	 * of them costs several times its size in the sandbox.
+	 */
+	readFileStream?(path: string, options?: SandboxReadFileOptions): AsyncIterable<Buffer>
 	/**
 	 * Recursively enumerate regular files under `rootPath`. Directories,
 	 * symlinks, sockets, and other non-regular entries are skipped.

package/src/types/tool/index.ts

@@ -469,6 +469,26 @@ export interface ToolContext {
 	 */
 	maxToolOutputChars?: number
 
+	/**
+	 * Screens the RUN asked for, applied to results this call produces.
+	 *
+	 * Worth having because a run usually does not build its registry: a host
+	 * assembles one and hands it to `runAgent`, so a registry-construction
+	 * option alone is the host's to write and the kernel's default reaches
+	 * nobody.
+	 *
+	 * The registry's own {@link ToolRegistryConfig.resultGuardrails} WIN when
+	 * the registry was built with them — including an empty array, which means
+	 * none — because a registry that stated its policy has stated it. These
+	 * apply to a registry that declared none, which is the ordinary case: a
+	 * host assembles a registry and hands it to a run it does not own.
+	 *
+	 * `undefined` means the run declared none; an empty array means the run
+	 * declared none ON PURPOSE, which is how a caller turns off a screen the
+	 * executor would otherwise install by default.
+	 */
+	toolResultGuardrails?: readonly ToolResultGuardrailSpec[]
+
 	/**
 	 * Run another tool through the same dispatch this call came through.
 	 *