@namzu/sdk 40.0.0 → 41.0.0

package/src/sandbox/provider/local.ts

@@ -4,6 +4,7 @@ import {
 	readFile as fsReadFile,
 	writeFile as fsWriteFile,
 	mkdir,
+	open,
 	readdir,
 	rename,
 	rm,
@@ -38,6 +39,7 @@ import type {
 	SandboxFileEntry,
 	SandboxIsolationControl,
 	SandboxProvider,
+	SandboxReadFileOptions,
 	SandboxSpawnOptions,
 	SandboxStatus,
 	SandboxWalkFilesOptions,
@@ -742,13 +744,54 @@ class LocalSandbox implements Sandbox {
 		this.log.debug('File written', { 'namzu.sandbox.path': resolved })
 	}
 
-	async readFile(path: string): Promise<Buffer> {
+	/**
+	 * `options.offset`/`options.length` are HONOURED, not ignored.
+	 *
+	 * {@link Sandbox.readFile} is explicit that a backend which takes the
+	 * parameter and answers with the whole file has given a WRONG answer
+	 * rather than a degraded one, and must reject instead. On a local
+	 * filesystem there is nothing to reject: a slice is one positional read,
+	 * so this serves it.
+	 *
+	 * A range that runs past the end returns the bytes that exist, because a
+	 * caller resuming from a remembered offset cannot know the answer before
+	 * it asks.
+	 *
+	 * `options.signal` cannot be handed to a positional read — `FileHandle`
+	 * takes none — so it is checked on both sides of one bounded slice
+	 * instead. That honours the contract's "aborts the read" as far as a
+	 * local disk allows: an abort is never answered with data.
+	 */
+	async readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer> {
 		if (this._status === 'destroyed') {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
 		}
 
 		const resolved = await resolveWithinAnyReal(this.roots, path)
-		return fsReadFile(resolved)
+		const { offset, length, signal } = options ?? {}
+		signal?.throwIfAborted()
+		if (offset === undefined && length === undefined) {
+			return await fsReadFile(resolved, signal ? { signal } : undefined)
+		}
+		if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0)) {
+			throw new Error('readFile: offset must be a non-negative safe integer')
+		}
+		if (length !== undefined && (!Number.isSafeInteger(length) || length < 0)) {
+			throw new Error('readFile: length must be a non-negative safe integer')
+		}
+		const handle = await open(resolved, 'r')
+		try {
+			const from = offset ?? 0
+			const remaining = Math.max(0, (await handle.stat()).size - from)
+			const want = Math.min(length ?? remaining, remaining)
+			if (want === 0) return Buffer.alloc(0)
+			const buf = Buffer.allocUnsafe(want)
+			const { bytesRead } = await handle.read(buf, 0, want, from)
+			signal?.throwIfAborted()
+			return buf.subarray(0, bytesRead)
+		} finally {
+			await handle.close().catch(() => undefined)
+		}
 	}
 
 	async listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]> {

package/src/scheduler/local.ts

@@ -114,6 +114,14 @@ export class LocalTaskScheduler implements TaskScheduler {
 				beforeStart: options.beforeStart,
 				...(options.planId ? { planId: options.planId } : {}),
 				...(options.planStepId ? { planStepId: options.planStepId } : {}),
+				// Display grouping travels with the spawn so the manager can put it
+				// on `agent_pending`. Spread conditionally, like the plan edge
+				// above: a host that groups nothing must not be made to look like
+				// one that grouped everything under an empty label.
+				...(options.workflow ? { workflow: options.workflow } : {}),
+				...(options.phase ? { phase: options.phase } : {}),
+				...(options.phaseDetail ? { phaseDetail: options.phaseDetail } : {}),
+				...(options.phaseOrder !== undefined ? { phaseOrder: options.phaseOrder } : {}),
 				input: {
 					messages: [createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,

package/src/store/run/disk.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import { appendFile, mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
+import type { RunExecutionStatus } from '../../types/common/index.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
 import type { Message } from '../../types/message/index.js'
 import type {
@@ -12,6 +13,7 @@ import type {
 } from '../../types/run/index.js'
 import type {
 	CompletedToolRecord,
+	DelegatedChildRun,
 	ReadRunEventsOptions,
 	RunMessageSnapshot,
 	RunStore,
@@ -432,6 +434,86 @@ export class RunDiskStore implements RunStore {
 		}
 	}
 
+	/**
+	 * Every delegated child run saved under one parent, oldest first.
+	 *
+	 * The sibling of {@link RunDiskStore.listRuns}, and deliberately not a fix
+	 * to it. `addToIndex` returns early for any run with a `parentRunId`, which
+	 * is what keeps delegated children out of `index.json` and therefore out of
+	 * a host's conversation listing — a child is not a conversation anyone
+	 * resumes, and putting one there would offer to continue work whose parent
+	 * turn is long over. That guard stays. This walks the `children/` directory
+	 * instead, so the evidence a child already wrote is reachable by something
+	 * that came looking for it, without any of it becoming resumable.
+	 *
+	 * READ-ONLY, and that matters more here than for most reads: binding a
+	 * {@link RunDiskStore} to a run CREATES its directory, so discovery had to
+	 * be a free walk or it would mint the very directories it claims to find.
+	 * Nothing here writes, moves or prunes.
+	 *
+	 * Tolerant of half-written evidence, the same way the transcript reader
+	 * next door is. A child directory with no `run.json` — a run killed before
+	 * its terminal write — is SKIPPED rather than reported with invented
+	 * fields, and so is one whose `run.json` is not readable JSON. What is
+	 * skipped is the listing row, not the directory: a caller that knows the
+	 * run id can still read the transcript beside it.
+	 *
+	 * Oldest first, by `startedAt`, so the order matches the order the parent
+	 * launched them. A child whose `run.json` never recorded a start sorts
+	 * first; there is no later moment to claim for it.
+	 *
+	 * `baseDir` is the runs directory the parent was written under — the same
+	 * {@link RunStoreConfig.baseDir} the child's store had, which is why one
+	 * parent's children can be spread across several of them when a host gives
+	 * each child its own session directory.
+	 */
+	static async listChildren(
+		baseDir: string,
+		parentRunId: string,
+	): Promise<readonly DelegatedChildRun[]> {
+		asRunId(parentRunId)
+		const childrenDir = join(baseDir, parentRunId, 'children')
+		let names: string[]
+		try {
+			names = await readdir(childrenDir)
+		} catch (err) {
+			if (isFileNotFound(err) || isNotADirectory(err)) return []
+			throw err
+		}
+
+		const children: DelegatedChildRun[] = []
+		for (const name of names) {
+			const dir = join(childrenDir, name)
+			let meta: unknown
+			try {
+				meta = JSON.parse(await readFile(join(dir, 'run.json'), 'utf-8'))
+			} catch (err) {
+				// ENOTDIR covers a stray file sitting beside the child directories.
+				if (isFileNotFound(err) || isNotADirectory(err) || err instanceof SyntaxError) continue
+				throw err
+			}
+			if (meta === null || typeof meta !== 'object') continue
+			const record = meta as Record<string, unknown>
+			const metadata = asRecord(record.metadata)
+			const config = asRecord(metadata?.config)
+			const usage = asRecord(record.tokenUsage)
+			children.push({
+				id: name,
+				parentRunId,
+				dir,
+				...(typeof metadata?.agentId === 'string' ? { agentId: metadata.agentId } : {}),
+				...(typeof metadata?.agentName === 'string' ? { agentName: metadata.agentName } : {}),
+				...(typeof config?.model === 'string' ? { model: config.model } : {}),
+				...(isRunExecutionStatus(record.status) ? { status: record.status } : {}),
+				...(typeof record.startedAt === 'number' ? { startedAt: record.startedAt } : {}),
+				...(typeof record.endedAt === 'number' ? { endedAt: record.endedAt } : {}),
+				...(typeof usage?.totalTokens === 'number' ? { totalTokens: usage.totalTokens } : {}),
+				...(typeof record.depth === 'number' ? { depth: record.depth } : {}),
+			})
+		}
+		return children.sort((left, right) => (left.startedAt ?? 0) - (right.startedAt ?? 0))
+	}
+
 	async addToIndex(run: Run): Promise<void> {
 		if (run.parentRunId) return
 
@@ -798,6 +880,32 @@ function parseCheckpoint(content: string, file: string): IterationCheckpoint {
 	return record as IterationCheckpoint
 }
 
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === 'object' && value !== null
+		? (value as Record<string, unknown>)
+		: undefined
+}
+
+const RUN_EXECUTION_STATUSES: readonly RunExecutionStatus[] = [
+	'idle',
+	'pending',
+	'running',
+	'completed',
+	'failed',
+	'cancelled',
+]
+
+function isRunExecutionStatus(value: unknown): value is RunExecutionStatus {
+	return typeof value === 'string' && RUN_EXECUTION_STATUSES.includes(value as RunExecutionStatus)
+}
+
+/** A path component that is a file where a directory was expected. */
+function isNotADirectory(err: unknown): boolean {
+	return (
+		typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOTDIR'
+	)
+}
+
 function isFileNotFound(err: unknown): boolean {
 	return typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOENT'
 }

package/src/types/agent/scheduler.ts

@@ -58,6 +58,27 @@ export interface CreateTaskOptions {
 	readonly planId?: string
 	readonly planStepId?: string
 
+	/**
+	 * Display grouping for the delegated child, carried onto its
+	 * `agent_pending` event so a consumer watching from outside this process
+	 * can group the child the way this caller meant. Reach, not durability:
+	 * that event goes straight to a host's listener and enters no run's log,
+	 * so nothing here is persisted by the kernel. See the `agent_pending`
+	 * variant in `types/run/events.ts` for the full contract.
+	 *
+	 * These fields are display annotations only; they do not create
+	 * dependencies, barriers, or serial execution. The kernel reads none of
+	 * them — a caller wanting correlation a host may act on has
+	 * {@link planId} and {@link planStepId} for that.
+	 */
+	readonly workflow?: string
+	/** Stage within {@link workflow}. Display-only on the same terms. */
+	readonly phase?: string
+	/** Longer text explaining {@link phase}. Display-only on the same terms. */
+	readonly phaseDetail?: string
+	/** Zero-based DISPLAY order for {@link phase}. Display-only on the same terms. */
+	readonly phaseOrder?: number
+
 	agentId: string
 
 	/**

package/src/types/agent/task.ts

@@ -158,6 +158,27 @@ export interface SendMessageOptions {
 	readonly planId?: string
 	readonly planStepId?: string
 
+	/**
+	 * Display grouping for the delegated child, carried onto its
+	 * `agent_pending` event so a consumer watching from outside this process
+	 * can group the child the way this caller meant. Reach, not durability:
+	 * that event goes straight to a host's listener and enters no run's log,
+	 * so nothing here is persisted by the kernel. See the `agent_pending`
+	 * variant in `types/run/events.ts` for the full contract.
+	 *
+	 * These fields are display annotations only; they do not create
+	 * dependencies, barriers, or serial execution. The kernel reads none of
+	 * them — a caller wanting correlation a host may act on has
+	 * {@link planId} and {@link planStepId} for that.
+	 */
+	readonly workflow?: string
+	/** Stage within {@link workflow}. Display-only on the same terms. */
+	readonly phase?: string
+	/** Longer text explaining {@link phase}. Display-only on the same terms. */
+	readonly phaseDetail?: string
+	/** Zero-based DISPLAY order for {@link phase}. Display-only on the same terms. */
+	readonly phaseOrder?: number
+
 	agentId: string
 
 	input: AgentInput

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