@namzu/sdk 49.0.0 → 50.0.0

package/src/store/session-log/structured-result.ts

@@ -0,0 +1,96 @@
+import type { SessionRecord } from '../../types/session/records.js'
+import { SessionRecordSchema } from '../../types/session/records.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
+import { cloneJsonValue } from '../../utils/json-snapshot.js'
+import {
+	STRUCTURED_RESULT_MAX_BYTES,
+	parseStructuredResultJson,
+} from '../../utils/structured-result-json.js'
+import type { SessionLog } from './core.js'
+import { SpillIntegrityError, type SpillRef, sha256Hex } from './spill.js'
+
+export interface StructuredResultReadOptions {
+	readonly signal?: AbortSignal
+}
+
+/** Internal checked hydration, also used by completed-call recovery. */
+export async function readStructuredResultSpill(
+	log: SessionLog,
+	ref: SpillRef,
+	signal?: AbortSignal,
+): Promise<{ json: string; value: unknown }> {
+	signal?.throwIfAborted()
+	if (
+		!Number.isSafeInteger(ref.bytes) ||
+		ref.bytes <= 0 ||
+		ref.bytes > STRUCTURED_RESULT_MAX_BYTES ||
+		!/^tool-results\/[a-f0-9]{64}\.txt$/.test(ref.path) ||
+		ref.manifest !== `${ref.path}.manifest.json` ||
+		!/^[a-f0-9]{64}$/.test(ref.sha256)
+	)
+		throw new SpillIntegrityError(ref.path, 'Invalid or oversized structured result reference.')
+	const json = await awaitWithAbort(
+		log.readSpill(ref, { maxBytes: STRUCTURED_RESULT_MAX_BYTES, signal }),
+		signal,
+	)
+	signal?.throwIfAborted()
+	if (
+		typeof json !== 'string' ||
+		Buffer.byteLength(json, 'utf8') !== ref.bytes ||
+		sha256Hex(json) !== ref.sha256
+	) {
+		throw new SpillIntegrityError(
+			ref.path,
+			'Structured result bytes do not match their recorded length and SHA-256.',
+		)
+	}
+	let value: unknown
+	try {
+		value = parseStructuredResultJson(json)
+	} catch (error) {
+		throw new SpillIntegrityError(ref.path, 'Structured result body is not JSON-safe.', {
+			cause: error,
+		})
+	}
+	signal?.throwIfAborted()
+	return { json, value }
+}
+
+/**
+ * Decode accepted structured output from a completed record obtained by the
+ * caller from a verified log read. This helper does not walk the chain. Raw log
+ * reads keep references; this explicit read checks the body before decoding.
+ * No schema, tool or reviewer is rerun. Undefined means no accepted JSON.
+ */
+export async function readStructuredOutput(
+	log: SessionLog,
+	record: Extract<SessionRecord, { type: 'turn_completed' }>,
+	options: StructuredResultReadOptions = {},
+): Promise<unknown> {
+	options.signal?.throwIfAborted()
+	if (record.type !== 'turn_completed' || record.sessionId !== log.sessionId) {
+		throw new TypeError('Structured output requires a completed record from this session.')
+	}
+	SessionRecordSchema.parse(record)
+	const ref = record.structuredOutputSpill
+	if (record.settlement.status !== 'completed') {
+		if (record.settlement.structuredOutput !== undefined || ref !== undefined) {
+			throw new TypeError('A cancelled turn cannot publish accepted structured output.')
+		}
+		return undefined
+	}
+	if (
+		(ref !== undefined || record.settlement.structuredOutput !== undefined) &&
+		record.settlement.resultSource !== 'structured_output'
+	) {
+		throw new TypeError('Accepted structured output requires the structured_output result source.')
+	}
+	if (ref !== undefined) {
+		const { value } = await readStructuredResultSpill(log, ref, options.signal)
+		options.signal?.throwIfAborted()
+		return value
+	}
+	return record.settlement.structuredOutput === undefined
+		? undefined
+		: cloneJsonValue(record.settlement.structuredOutput, false)
+}

package/src/store/task/disk.ts

@@ -238,6 +238,12 @@ export class DiskTaskStore implements TaskStore {
 					if (blocker && !blocker.blocks.includes(taskId)) {
 						blocker.blocks.push(taskId)
 						await records.write(this.taskPath(blockerId), blocker)
+						this.emit({
+							type: 'task.updated',
+							taskId: blockerId,
+							task: blocker,
+							timestamp: Date.now(),
+						})
 					}
 					// If blocker is missing, we still write the new task with its
 					// blockedBy reference; the dangling reference is visible to
@@ -324,17 +330,33 @@ export class DiskTaskStore implements TaskStore {
 			if (!task) return false
 
 			for (const blockerId of task.blockedBy) {
+				if (blockerId === id) continue
 				const blocker = await this.readTask(blockerId)
-				if (blocker) {
+				if (blocker?.blocks.includes(id)) {
 					blocker.blocks = blocker.blocks.filter((bid) => bid !== id)
 					await records.write(this.taskPath(blockerId), blocker)
+					// Announce each confirmed write now: a later write or unlink
+					// may fail, leaving this real graph change in place.
+					this.emit({
+						type: 'task.updated',
+						taskId: blockerId,
+						task: blocker,
+						timestamp: Date.now(),
+					})
 				}
 			}
 			for (const blockedId of task.blocks) {
+				if (blockedId === id) continue
 				const blocked = await this.readTask(blockedId)
-				if (blocked) {
+				if (blocked?.blockedBy.includes(id)) {
 					blocked.blockedBy = blocked.blockedBy.filter((bid) => bid !== id)
 					await records.write(this.taskPath(blockedId), blocked)
+					this.emit({
+						type: 'task.updated',
+						taskId: blockedId,
+						task: blocked,
+						timestamp: Date.now(),
+					})
 				}
 			}
 
@@ -368,6 +390,26 @@ export class DiskTaskStore implements TaskStore {
 	async list(filter?: { status?: TaskStatus; owner?: string; sessionId?: SessionId }): Promise<
 		Task[]
 	> {
+		return this.readList(filter, false)
+	}
+
+	/**
+	 * Read a complete list or reject an unreadable directory/record. Hosts
+	 * replacing an authoritative projection must not mistake a partial read
+	 * for task deletion. A not-yet-created directory remains an empty list.
+	 */
+	async listStrict(filter?: {
+		status?: TaskStatus
+		owner?: string
+		sessionId?: SessionId
+	}): Promise<Task[]> {
+		return this.readList(filter, true)
+	}
+
+	private async readList(
+		filter: { status?: TaskStatus; owner?: string; sessionId?: SessionId } | undefined,
+		strict: boolean,
+	): Promise<Task[]> {
 		if (filter?.sessionId !== undefined && filter.sessionId !== this.session.sessionId) return []
 		const dir = this.taskDir()
 
@@ -379,6 +421,7 @@ export class DiskTaskStore implements TaskStore {
 				'namzu.store.dir': dir,
 				'exception.message': err instanceof Error ? err.message : String(err),
 			})
+			if (strict) throw err
 			return []
 		}
 
@@ -393,6 +436,7 @@ export class DiskTaskStore implements TaskStore {
 					'namzu.store.file': file,
 					'exception.message': err instanceof Error ? err.message : String(err),
 				})
+				if (strict) throw err
 			}
 		}
 

package/src/store/task/memory.ts

@@ -68,8 +68,14 @@ export class InMemoryTaskStore implements TaskStore {
 		if (params.blockedBy) {
 			for (const blockerId of params.blockedBy) {
 				const blocker = this.tasks.get(blockerId)
-				if (blocker) {
+				if (blocker && !blocker.blocks.includes(task.id)) {
 					blocker.blocks.push(task.id)
+					this.emit({
+						type: 'task.updated',
+						taskId: blockerId,
+						task: blocker,
+						timestamp: Date.now(),
+					})
 				}
 			}
 		}
@@ -129,15 +135,19 @@ export class InMemoryTaskStore implements TaskStore {
 		if (!task) return false
 
 		for (const blockerId of task.blockedBy) {
+			if (blockerId === id) continue
 			const blocker = this.tasks.get(blockerId)
-			if (blocker) {
+			if (blocker?.blocks.includes(id)) {
 				blocker.blocks = blocker.blocks.filter((bid) => bid !== id)
+				this.emit({ type: 'task.updated', taskId: blockerId, task: blocker, timestamp: Date.now() })
 			}
 		}
 		for (const blockedId of task.blocks) {
+			if (blockedId === id) continue
 			const blocked = this.tasks.get(blockedId)
-			if (blocked) {
+			if (blocked?.blockedBy.includes(id)) {
 				blocked.blockedBy = blocked.blockedBy.filter((bid) => bid !== id)
+				this.emit({ type: 'task.updated', taskId: blockedId, task: blocked, timestamp: Date.now() })
 			}
 		}
 

package/src/tools/admit-facts.ts

@@ -0,0 +1,145 @@
+import type { ToolFacts, ToolFailureReason } from '../types/tool/presentation.js'
+
+const FAILURE_REASONS: readonly ToolFailureReason[] = [
+	'not_found',
+	'permission_denied',
+	'not_a_file',
+	'already_exists',
+	'blocked',
+	'needs_administrator',
+	'unknown_tool',
+	'timed_out',
+	'invalid_input',
+]
+
+const WRITE_OPERATIONS = ['created', 'updated', 'unchanged', 'wrote'] as const
+
+/** Bounds on what a saved record is allowed to hold. */
+const MAX_TEXT = 2_000
+const MAX_COUNT = Number.MAX_SAFE_INTEGER
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function text(value: unknown): string | undefined {
+	return typeof value === 'string' && value.length <= MAX_TEXT ? value : undefined
+}
+
+function count(value: unknown): number | undefined {
+	return typeof value === 'number' &&
+		Number.isSafeInteger(value) &&
+		value >= 0 &&
+		value <= MAX_COUNT
+		? value
+		: undefined
+}
+
+function flag(value: unknown): true | undefined {
+	return value === true ? true : undefined
+}
+
+function pick<T extends object>(entries: Record<string, unknown>): T {
+	const out: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(entries)) if (value !== undefined) out[key] = value
+	return out as T
+}
+
+/**
+ * Read a recorded `ToolFacts` back into the closed shape, or `undefined` when
+ * it is not one. A journal is read by hosts that did not write it, and an
+ * extension field must not travel on into a screen.
+ *
+ * The text of a command's streams is a live-only convenience and a saved
+ * conversation does not keep it, so it is dropped here: what remains is
+ * enough to headline the row ("Ran npm test, failed (exit 1)") and never the
+ * output itself.
+ */
+export function admitToolFacts(value: unknown): ToolFacts | undefined {
+	if (!isRecord(value)) return undefined
+	switch (value.kind) {
+		case 'command':
+			return pick<ToolFacts>({
+				kind: 'command',
+				command: text(value.command),
+				exitCode:
+					typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode)
+						? value.exitCode
+						: undefined,
+				timedOut: flag(value.timedOut),
+				signal: text(value.signal),
+				binary:
+					isRecord(value.binary) && count(value.binary.bytes) !== undefined
+						? { bytes: count(value.binary.bytes) }
+						: undefined,
+				background: flag(value.background),
+			})
+		case 'read': {
+			const path = text(value.path)
+			if (path === undefined) return undefined
+			return pick<ToolFacts>({
+				kind: 'read',
+				path,
+				binary: flag(value.binary),
+				bytes: count(value.bytes),
+				totalLines: count(value.totalLines),
+				returnedLines: count(value.returnedLines),
+				partial: flag(value.partial),
+			})
+		}
+		case 'search': {
+			const pattern = text(value.pattern)
+			if (pattern === undefined) return undefined
+			return pick<ToolFacts>({
+				kind: 'search',
+				pattern,
+				path: text(value.path),
+				matches: count(value.matches),
+				filesMatched: count(value.filesMatched),
+				filesSearched: count(value.filesSearched),
+				truncated: flag(value.truncated),
+			})
+		}
+		case 'list': {
+			const pattern = text(value.pattern)
+			if (pattern === undefined) return undefined
+			return pick<ToolFacts>({
+				kind: 'list',
+				pattern,
+				path: text(value.path),
+				count: count(value.count),
+				truncated: flag(value.truncated),
+			})
+		}
+		case 'edit':
+			return pick<ToolFacts>({
+				kind: 'edit',
+				path: text(value.path),
+				replacements: count(value.replacements),
+			})
+		case 'write': {
+			const path = text(value.path)
+			const operation = WRITE_OPERATIONS.find((candidate) => candidate === value.operation)
+			if (path === undefined || operation === undefined) return undefined
+			return pick<ToolFacts>({
+				kind: 'write',
+				path,
+				operation,
+				bytes: count(value.bytes),
+				added: count(value.added),
+				removed: count(value.removed),
+			})
+		}
+		case 'failure': {
+			const reason = FAILURE_REASONS.find((candidate) => candidate === value.reason)
+			if (reason === undefined) return undefined
+			return pick<ToolFacts>({
+				kind: 'failure',
+				reason,
+				subject: text(value.subject),
+			})
+		}
+		default:
+			return undefined
+	}
+}

package/src/tools/builtins/bash.ts

@@ -1,20 +1,23 @@
-import { spawn } from 'node:child_process'
-import { StringDecoder } from 'node:string_decoder'
 import { z } from 'zod'
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { killTree } from '../../process/kill-tree.js'
+import { genericLabel } from '../../registry/tool/presentation.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
 import {
 	type CommandShell,
 	bashToolDialect,
-	hostShellSpawn,
+	describeSpawnFailure,
 	sandboxShellSpawn,
+	spawnHostShell,
 	withoutBashStartup,
 } from '../command-shell.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
+import { createHostOutputDecoder } from '../host-output.js'
+import { looksBinary, windowText } from '../text-window.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
@@ -69,7 +72,7 @@ const inputSchema = z.object({
 		.boolean()
 		.optional()
 		.describe(
-			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; await its completion with `wait_for_job` — one call, no waiting turns. Use `job` with action "read" only for incremental output while it keeps running, or to pick up after a `wait_for_job` call times out. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
+			'Start the command as a background job and return its id immediately. For a finite build, await completion with `wait_for_job`. For a persistent server, use `wait_for_job` with output_contains and optional output_stream to observe its literal readiness marker without waiting for exit; verify health separately. Use `job` action "read" for incremental output or after a wait times out. Do NOT use `cmd &` as a substitute for a registered job: strict execution ownership can retire the allocation when the launcher exits with live descendants. An interactive application may belong to a dedicated computer only when that computer explicitly supports application lifetime; its launch result is not a registered job or proof the application has finished.',
 		),
 	dangerously_disable_sandbox: z
 		.boolean()
@@ -158,35 +161,35 @@ export function execHostShell(
 		signal?: AbortSignal
 		onOutput?: ExecHostShellProgress
 	},
-): Promise<{ stdout: string; stderr: string }> {
+): Promise<{
+	stdout: string
+	stderr: string
+	/** Bytes captured on each stream, before decoding; absent from a runner that does not count them. */
+	stdoutBytes?: number
+	stderrBytes?: number
+}> {
 	options.signal?.throwIfAborted()
 	return new Promise((resolve, reject) => {
 		// bash where the host has it, `/bin/sh` where it does not; the
 		// permission rules read the line in the matching dialect. See
 		// `../command-shell.ts`.
-		const shell = hostShellSpawn(command, options.env, options.shell)
-		const spawnOptions = {
+		const child = spawnHostShell(command, {
 			cwd: options.cwd,
-			env: shell.env,
-			// killTree's negative PID must never target the caller's own group.
-			detached: process.platform !== 'win32',
-		}
-		const child =
-			shell.file === undefined
-				? spawn(command, { ...spawnOptions, shell: true })
-				: spawn(shell.file, [...shell.args], spawnOptions)
+			env: options.env,
+			...(options.shell === undefined ? {} : { shell: options.shell }),
+		})
 		const captures = {
 			stdout: {
 				chunks: [] as Buffer[],
 				bytes: 0,
 				truncated: false,
-				decoder: new StringDecoder('utf8'),
+				decoder: createHostOutputDecoder(),
 			},
 			stderr: {
 				chunks: [] as Buffer[],
 				bytes: 0,
 				truncated: false,
-				decoder: new StringDecoder('utf8'),
+				decoder: createHostOutputDecoder(),
 			},
 		}
 		let cause: 'caller' | 'timeout' | 'maxBuffer' | undefined
@@ -235,8 +238,18 @@ export function execHostShell(
 		const onStderr = (chunk: Buffer) => capture('stderr', chunk)
 		child.stdout?.on('data', onStdout)
 		child.stderr?.on('data', onStderr)
+		let spawned = false
+		child.once('spawn', () => {
+			spawned = true
+		})
 		child.once('error', (error: NodeJS.ErrnoException) => {
-			failure ??= error
+			// Same words as a background job that cannot start.
+			failure ??= spawned
+				? error
+				: Object.assign(
+						new Error(describeSpawnFailure(error, options.cwd), { cause: error }),
+						error.code === undefined ? {} : { code: error.code },
+					)
 		})
 		child.once('close', (code, signal) => {
 			closed = true
@@ -257,13 +270,20 @@ export function execHostShell(
 			const decodeCapture = (stream: 'stdout' | 'stderr') => {
 				const state = captures[stream]
 				const bytes = Buffer.concat(state.chunks, state.bytes)
-				// Do not flush an incomplete UTF-8 character cut by our byte cap.
-				return state.truncated ? new StringDecoder('utf8').write(bytes) : bytes.toString('utf8')
+				// Do not flush an incomplete character cut by our byte cap.
+				const decoder = createHostOutputDecoder()
+				const text = decoder.write(bytes)
+				return state.truncated ? text : text + decoder.end()
 			}
 			const stdout = decodeCapture('stdout')
 			const stderr = decodeCapture('stderr')
 			if (!failure && cause === undefined && code === 0 && signal === null) {
-				resolve({ stdout, stderr })
+				resolve({
+					stdout,
+					stderr,
+					stdoutBytes: captures.stdout.bytes,
+					stderrBytes: captures.stderr.bytes,
+				})
 				return
 			}
 			const error =
@@ -281,6 +301,8 @@ export function execHostShell(
 				Object.assign(error, {
 					stdout,
 					stderr,
+					stdoutBytes: captures.stdout.bytes,
+					stderrBytes: captures.stderr.bytes,
 					stdoutTruncated: captures.stdout.truncated,
 					stderrTruncated: captures.stderr.truncated,
 					code: failure?.code ?? (cause === 'caller' ? 'ABORT_ERR' : code),
@@ -317,7 +339,7 @@ export const SANDBOX_ESCAPE_NOT_APPROVED =
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
-		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
+		'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
 	inputSchema,
 	// A command carries quotes and backslashes of its own, and a heredoc
 	// carries newlines: copied into the JSON string raw, they end it.
@@ -348,12 +370,24 @@ export const BashTool = defineTool({
 	// and diverged the moment a model asked for longer.
 	timeoutMs: MAX_BASH_TIMEOUT_MS + 30_000,
 
+	// The same one-line label every tool without an opinion gets, plus the
+	// command itself as a field so a host can headline and tooltip it whole.
+	presentCall(input) {
+		if (typeof input.command !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: genericLabel(input),
+			facts: { kind: 'command', command: input.command },
+		}
+	},
+
 	async execute(input, context) {
 		if (isDangerousCommand(input.command)) {
 			return {
 				success: false,
 				output: '',
 				error: `Dangerous command blocked: "${input.command}"`,
+				facts: { kind: 'failure', reason: 'blocked', subject: 'bash' },
 			}
 		}
 
@@ -411,10 +445,24 @@ export const BashTool = defineTool({
 					command: input.command,
 					workingDirectory: context.workingDirectory,
 				})
+				// `start` returns before the process exists, and a spawn that
+				// fails (no such shell, bad directory) reports a tick later.
+				// Wait for that one event so "Started" is never said of a job
+				// that could not start. No timer: it settles on spawn or error.
+				const startup = await context.backgroundJobs.awaitStarted?.(job.id)
+				if (startup?.error !== undefined) {
+					return {
+						success: false,
+						output: '',
+						error: `${startup.error} (job ${job.id} did not run).`,
+						data: { jobId: job.id, background: true, startFailed: true },
+					}
+				}
 				return {
 					success: true,
-					output: `Started background job ${job.id}. Await its completion with wait_for_job: {"id":"${job.id}"}. Use job with action "read" only for output while it keeps running.`,
+					output: `Started background job ${job.id}. For finite work, await completion with wait_for_job: {"id":"${job.id}"}. For a persistent server, observe its literal readiness marker with wait_for_job: {"id":"${job.id}","output_contains":"<expected marker>","output_stream":"stdout"}; this leaves it running and does not prove health. Use job with action "read" for incremental output.`,
 					data: { jobId: job.id, background: true },
+					facts: { kind: 'command', command: input.command, background: true },
 				}
 			} catch (err) {
 				// The per-owner cap, most likely. A refusal that names the limit
@@ -499,6 +547,13 @@ export const BashTool = defineTool({
 					: result.exitCode !== 0
 						? `Command exited with code ${result.exitCode}`
 						: undefined,
+				facts: commandFacts({
+					command: input.command,
+					exitCode: result.exitCode,
+					timedOut: result.timedOut,
+					stdout: result.stdout,
+					stderr: result.stderr,
+				}),
 			}
 		}
 
@@ -512,7 +567,7 @@ export const BashTool = defineTool({
 		const inherited = scrubInheritedEnv()
 
 		try {
-			const { stdout, stderr } = await execHostShell(input.command, {
+			const { stdout, stderr, stdoutBytes, stderrBytes } = await execHostShell(input.command, {
 				cwd: context.workingDirectory,
 				timeout: input.timeout,
 				env: { ...inherited.env, ...context.env },
@@ -524,11 +579,21 @@ export const BashTool = defineTool({
 				success: true,
 				output: formatShellOutput(stdout, stderr) || '(no output)',
 				data: { exitCode: 0, ...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}) },
+				facts: commandFacts({
+					command: input.command,
+					exitCode: 0,
+					stdout,
+					stderr,
+					stdoutBytes,
+					stderrBytes,
+				}),
 			}
 		} catch (err) {
 			const failure = err as NodeJS.ErrnoException & {
 				stdout?: string
 				stderr?: string
+				stdoutBytes?: number
+				stderrBytes?: number
 				stdoutTruncated?: boolean
 				stderrTruncated?: boolean
 				code?: number | string
@@ -578,11 +643,54 @@ export const BashTool = defineTool({
 					: exitCode !== undefined
 						? `Command exited with code ${exitCode}`
 						: `Command failed: ${failure.message}`,
+				facts: commandFacts({
+					command: input.command,
+					...(exitCode !== undefined ? { exitCode } : {}),
+					timedOut,
+					...(failure.signal ? { signal: failure.signal } : {}),
+					stdout: failure.stdout ?? '',
+					stderr: failure.stderr ?? '',
+					...(failure.stdoutBytes !== undefined ? { stdoutBytes: failure.stdoutBytes } : {}),
+					...(failure.stderrBytes !== undefined ? { stderrBytes: failure.stderrBytes } : {}),
+				}),
 			}
 		}
 	},
 })
 
+/**
+ * What a finished command did, as typed fields for the person's view: the exit
+ * code, each stream on its own as a head-and-tail window, and whether the
+ * output was bytes rather than text. The model's text (labels, the withheld
+ * environment note) is not an input here and is never reproduced.
+ */
+function commandFacts(input: {
+	command: string
+	exitCode?: number
+	timedOut?: boolean
+	signal?: string
+	stdout: string
+	stderr: string
+	stdoutBytes?: number
+	stderrBytes?: number
+}): ToolFacts {
+	const outBinary = looksBinary(input.stdout)
+	const errBinary = looksBinary(input.stderr)
+	const outBytes = input.stdoutBytes ?? Buffer.byteLength(input.stdout, 'utf8')
+	const errBytes = input.stderrBytes ?? Buffer.byteLength(input.stderr, 'utf8')
+	const binaryBytes = (outBinary ? outBytes : 0) + (errBinary ? errBytes : 0)
+	return {
+		kind: 'command',
+		command: input.command,
+		...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+		...(input.timedOut ? { timedOut: true } : {}),
+		...(input.signal ? { signal: input.signal } : {}),
+		...(input.stdout && !outBinary ? { stdout: windowText(input.stdout, outBytes) } : {}),
+		...(input.stderr && !errBinary ? { stderr: windowText(input.stderr, errBytes) } : {}),
+		...(outBinary || errBinary ? { binary: { bytes: binaryBytes } } : {}),
+	}
+}
+
 /**
  * The two streams, labelled, with empty ones left out.
  *