@namzu/sdk 52.2.0 → 52.4.0

package/src/tools/builtins/monitor.ts

@@ -0,0 +1,376 @@
+import { z } from 'zod'
+
+import {
+	MONITOR_TIMEOUT_DEFAULT_MS,
+	MONITOR_TIMEOUT_MAX_MS,
+	MONITOR_TIMEOUT_MIN_MS,
+	formatMonitorDuration,
+} from '../../runtime/jobs/monitor-stream.js'
+import {
+	WEBSOCKET_PROTOCOLS_MAX,
+	WebSocketRefusedError,
+	type WebSocketVetOptions,
+	vetWebSocketTarget,
+	webSocketHostname,
+	webSocketProtocolsProblem,
+	webSocketSandboxRefusal,
+	webSocketUrlProblem,
+} from '../../runtime/jobs/websocket-source.js'
+import type { MonitorWebSocketTarget } from '../../types/tool/index.js'
+import {
+	bashToolDialect,
+	hostCommandShell,
+	isWindowsBash,
+	rewriteWindowsNullRedirect,
+} from '../command-shell.js'
+import { defineTool } from '../defineTool.js'
+import {
+	DISABLE_BACKGROUND_TASKS_ENV,
+	backgroundTasksDisabled,
+	isDangerousCommand,
+} from './bash.js'
+
+/**
+ * Watch a command's output while the model keeps working.
+ *
+ * `bash run_in_background` plus `wait_for_job` answers "tell me when this
+ * finishes", and nothing answered "tell me when something happens in it": a
+ * log line, a failed check, a changed status. The only alternative was a
+ * polling loop, which spends a full context resend per look and is silent
+ * between looks. This tool starts the command as a job the registry owns and
+ * turns each line it prints on stdout into an event the model reads on its
+ * next tool result (or wakes it, when it has stopped) — see
+ * `runtime/jobs/monitor-stream.ts` for how lines become batches and why a
+ * source that prints too much is stopped.
+ *
+ * It is a different tool from `bash`, and not a flag on it, for the same
+ * reason `wait_for_job` is: the model chooses by intent. The permission story
+ * is bash's, line for line — a monitor runs a shell command — so the rules
+ * read the command the way they read `bash`'s, and it is never read-only. It
+ * has no way out of the sandbox: a watch that outlives one approved call must
+ * not run outside the boundary that call was approved under.
+ *
+ * A source can also be a WebSocket (`ws`), for services that push their events
+ * and offer no command that prints them. That one is a different thing to
+ * approve: it is not a shell line, it opens a connection FROM THE HOST to an
+ * address the model chose, and it does so outside any sandbox. So it is read
+ * by no command rule, it is always reviewed, a sandbox that blocks the network
+ * refuses it, and the address is checked and pinned (see
+ * `runtime/jobs/websocket-source.ts`). Untrusted frames reach the model the way
+ * a command's lines do: through the monitor event path, in its untrusted frame.
+ */
+
+const webSocketInput = z.object({
+	url: z
+		.string()
+		.superRefine((value, ctx) => {
+			const problem = webSocketUrlProblem(value)
+			if (problem !== undefined) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem })
+		})
+		.describe(
+			'The ws:// or wss:// URL to connect to. A query string is kept; credentials in it are refused.',
+		),
+	protocols: z
+		.array(z.string())
+		.max(WEBSOCKET_PROTOCOLS_MAX)
+		.superRefine((value, ctx) => {
+			const problem = webSocketProtocolsProblem(value)
+			if (problem !== undefined) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem })
+		})
+		.optional()
+		.describe('Subprotocol names to offer, when the service asks for one.'),
+})
+
+const inputSchema = z
+	.object({
+		description: z
+			.string()
+			.min(1)
+			.max(200)
+			.describe(
+				'What you are watching, in a few specific words. It is shown with every event ("Monitor event: <description>"), so make it identify this watch among several: "errors in deploy log", not "monitor".',
+			),
+		command: z
+			.string()
+			.min(1)
+			// Same rewrite as `bash`, for the same reason: the rules read the line a
+			// shell will run.
+			.transform((command) =>
+				isWindowsBash(hostCommandShell()) ? rewriteWindowsNullRedirect(command) : command,
+			)
+			.optional()
+			.describe(
+				'The shell command to watch. Each line it prints to stdout becomes an event. It runs until it ends or the timeout; it must not need stdin. Give this or ws, not both.',
+			),
+		ws: webSocketInput
+			.optional()
+			.describe(
+				'Watch a WebSocket instead of a command: each line of each text frame the server sends becomes an event. Give this or command, not both.',
+			),
+		timeout_ms: z
+			.preprocess(
+				(v) => (typeof v === 'string' ? Number(v) : v),
+				z
+					.number()
+					.int()
+					.min(MONITOR_TIMEOUT_MIN_MS)
+					.max(MONITOR_TIMEOUT_MAX_MS)
+					.default(MONITOR_TIMEOUT_DEFAULT_MS),
+			)
+			.describe(
+				`How long to watch, in milliseconds. Default ${MONITOR_TIMEOUT_DEFAULT_MS}. The host caps it (30 minutes by default; shorter in a single-shot run), and a larger value is lowered to that cap without an error; the result states the time actually granted.`,
+			),
+	})
+	.refine((input) => (input.command === undefined) !== (input.ws === undefined), {
+		message: 'Give exactly one of command and ws.',
+	})
+
+type MonitorInput = z.infer<typeof inputSchema>
+
+export const MONITOR_TOOL_NAME = 'monitor'
+
+/**
+ * What a sandbox without `spawnDetached` is told. The wording of `bash`'s own
+ * refusal names `run_in_background` and `timeout`, neither of which is this
+ * tool's, so it is restated here; the substance is the same and so is the
+ * rule: the watch is never run on the host to get around the sandbox.
+ */
+export const MONITOR_CANNOT_DETACH =
+	'monitor is unavailable: this sandbox cannot start a detached process, and the watch will not be run on the host to get around it. Run the command in the foreground with bash, with a timeout.'
+
+const MONITOR_DESCRIPTION =
+	'Starts a command and tells you about each line it prints to stdout, as it prints it, while you keep working. Lines that arrive within 200 ms come together as one event. Use it to watch a log, a test or deploy run, a status endpoint — anything where you must react to something happening INSIDE a long-running command. For ONE notification when something finishes, do not use this: run bash with run_in_background and wait_for_job. Every stage of a pipe must flush per line or events arrive late or never (grep --line-buffered, awk with fflush(), sed -u; `head` cannot). Make the filter match failure as well as success (crash, Traceback, Error, FAILED, Killed…): silence from a monitor is not success. Poll a remote API no faster than every 30 seconds. stderr is not an event; read it with job. A monitor that prints too much is stopped, so filter at the source. It expires after the timeout (default 5 minutes, at most 30) and you get one notice; start it again if you still need it. Stop one early with job {"action":"kill","id":"<id>"}. ' +
+	'To watch a service that PUSHES events (a CI or log stream, a change feed) give ws instead of command: { "url": "wss://…", "protocols": [...] }. Each line of each text frame becomes an event, binary frames are only counted, and the watch ends when the server closes the connection. Use it for a push stream, not for request and response. It connects from this machine, so private and local addresses are refused, and you are asked before it connects.'
+
+/** What a host can tune about the WebSocket source; for tests only, see {@link WebSocketVetOptions}. */
+export interface MonitorToolOptions {
+	readonly webSocket?: WebSocketVetOptions
+	/**
+	 * How to turn web access on, in the host's own words, appended to the
+	 * refusal a WebSocket call gets while it is off. The SDK cannot name a
+	 * switch it does not own (a CLI config key, a desktop setting), and a
+	 * refusal that only says "off" leaves the operator guessing. One short
+	 * sentence; it is shown to the model and the operator as written.
+	 */
+	readonly webAccessHint?: string
+}
+
+/** The text that says a WebSocket watch was refused because the host has web access off. */
+export const MONITOR_WEBSOCKET_WEB_OFF =
+	"WebSocket monitors follow the host's web access setting, and web access is switched off here, so no connection was opened. Watch the service with a command (for example curl or websocat through monitor) if the operator allows it."
+
+const MONITOR_WEBSOCKET_NOT_SUPPORTED =
+	'This host cannot start a WebSocket monitor, so no connection was opened. Watch the service with a command through monitor if the operator allows it.'
+
+/**
+ * The tool, built once with defaults for a host and again by a test that needs
+ * to reach a server on this machine. The options belong to whoever builds the
+ * tool; nothing a model sends can set them.
+ */
+export function createMonitorTool(options: MonitorToolOptions = {}) {
+	return defineTool({
+		name: MONITOR_TOOL_NAME,
+		description: MONITOR_DESCRIPTION,
+		inputSchema,
+		category: 'shell',
+		// Bash's, because it IS a shell command: the gate reads the line, splits
+		// chains, and applies the operator's rules to each part. A WebSocket call
+		// has no `command`, so a rule written for commands has nothing to match
+		// and cannot allow it; `requiresApproval` below is what asks.
+		commandArgument: 'command',
+		commandDialect: bashToolDialect,
+		// `network_access` too: a WebSocket call reaches the network. The gate
+		// reads a tool's `category`, not this list, to route a call, so declaring
+		// it changes no decision for a command; it says what the tool may do.
+		permissions: ['shell_execute', 'network_access'],
+		readOnly: false,
+		destructive: (input: MonitorInput) =>
+			input.command !== undefined && isDangerousCommand(input.command),
+		// A WebSocket call is the one input-aware seam the gate offers that no
+		// allow rule or mode outranks: it connects from the host, outside any
+		// sandbox, to an address the model chose. `category: 'shell'` is what the
+		// sandboxed-shell preset auto-approves, and moving the whole tool to
+		// `network` would start asking about commands that were never a question;
+		// this asks only about the connection. It is stronger than "review where
+		// the mode reviews non-read-only calls": `auto` mode and an unattended
+		// turn are asked too (or refuse when nobody can be asked), which is the
+		// point for a connection that leaves the boundary those modes rely on.
+		requiresApproval: (input: MonitorInput) => input.ws !== undefined,
+		// Starting a monitor registers a job against the owner's cap and its id
+		// is then named in later calls; two at once could race the cap, as they
+		// can for a background `bash`.
+		concurrencySafe: false,
+
+		presentCall(input) {
+			const label = typeof input.description === 'string' ? input.description : undefined
+			if (input.ws !== undefined && typeof input.ws === 'object') {
+				const ws = input.ws as { url?: unknown; protocols?: unknown }
+				if (typeof ws.url !== 'string') return undefined
+				const protocols =
+					Array.isArray(ws.protocols) && ws.protocols.length > 0
+						? ` (subprotocols: ${ws.protocols.join(', ')})`
+						: ''
+				// What will happen, said plainly, because this is what a person
+				// approves: no command line stands in for it.
+				return {
+					kind: 'generic',
+					label: `Monitor${label ? ` · ${label}` : ''} · WebSocket ${ws.url}${protocols}`,
+				}
+			}
+			if (typeof input.command !== 'string') return undefined
+			return {
+				kind: 'generic',
+				label: `Monitor · ${label ?? input.command}`,
+				facts: { kind: 'command', command: input.command, background: true },
+			}
+		},
+
+		async execute(input, context) {
+			if (input.command !== undefined && isDangerousCommand(input.command)) {
+				return {
+					success: false,
+					output: '',
+					error: `Dangerous command blocked: "${input.command}"`,
+					facts: { kind: 'failure', reason: 'blocked', subject: MONITOR_TOOL_NAME },
+				}
+			}
+			if (backgroundTasksDisabled()) {
+				return {
+					success: false,
+					output: '',
+					error: `Background jobs are switched off here (${DISABLE_BACKGROUND_TASKS_ENV}), and a monitor is one. Check in the foreground with bash instead.`,
+				}
+			}
+			// What is checked about a connection is checked before anything that
+			// speaks of commands, so a refusal names its own cause.
+			let webSocket: MonitorWebSocketTarget | undefined
+			if (input.ws !== undefined) {
+				// The operator's switch for reaching the web at all. A host that has
+				// not given this turn a web capability has not decided to let the
+				// model open connections, and a WebSocket is one.
+				if (context.web?.fetch === undefined) {
+					return {
+						success: false,
+						output: '',
+						error: options.webAccessHint
+							? `${MONITOR_WEBSOCKET_WEB_OFF} ${options.webAccessHint}`
+							: MONITOR_WEBSOCKET_WEB_OFF,
+					}
+				}
+				const hostname = webSocketHostname(input.ws.url)
+				const sandboxRefusal = webSocketSandboxRefusal(context.sandbox, hostname)
+				if (sandboxRefusal !== undefined) {
+					return { success: false, output: '', error: sandboxRefusal }
+				}
+				try {
+					const addresses = await vetWebSocketTarget(input.ws.url, options.webSocket)
+					webSocket = {
+						url: input.ws.url,
+						...(input.ws.protocols ? { protocols: input.ws.protocols } : {}),
+						addresses,
+					}
+				} catch (err) {
+					if (err instanceof WebSocketRefusedError) {
+						return { success: false, output: '', error: err.message }
+					}
+					throw err
+				}
+			} else if (context.sandbox && context.sandbox.spawnDetached === undefined) {
+				// Same rule as background bash: the executor withholds the registry
+				// from a sandbox that cannot start a detached process, and this check
+				// is for the direct caller who hands both.
+				return { success: false, output: '', error: MONITOR_CANNOT_DETACH }
+			}
+			const jobs = context.backgroundJobs
+			if (!jobs) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'monitor was requested, but this host provides no background job registry. Run the command in the foreground with bash, with a timeout.',
+				}
+			}
+			if (webSocket !== undefined && !jobs.startWebSocketMonitor) {
+				return {
+					success: false,
+					output: '',
+					error: MONITOR_WEBSOCKET_NOT_SUPPORTED,
+				}
+			}
+			if (webSocket === undefined && !jobs.startMonitor) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'This host cannot deliver monitor events, so no watch was started. Use bash with run_in_background and wait_for_job to be told when a command finishes.',
+				}
+			}
+
+			try {
+				const common = {
+					description: input.description,
+					timeoutMs: input.timeout_ms,
+					workingDirectory: context.workingDirectory,
+				}
+				const { job, timeoutMs } =
+					webSocket !== undefined
+						? (jobs.startWebSocketMonitor as NonNullable<typeof jobs.startWebSocketMonitor>)({
+								...common,
+								webSocket,
+							})
+						: (jobs.startMonitor as NonNullable<typeof jobs.startMonitor>)({
+								...common,
+								command: input.command as string,
+							})
+				// `startMonitor` returns before the process exists, and a spawn that
+				// fails reports a tick later; wait for that one event so "started" is
+				// never said of a watch that could not start.
+				const startup = await jobs.awaitStarted?.(job.id)
+				if (startup?.error !== undefined) {
+					return {
+						success: false,
+						output: '',
+						error: `${startup.error} (monitor ${job.id} did not run).`,
+						data: { jobId: job.id, monitor: true, startFailed: true },
+					}
+				}
+				if (webSocket !== undefined) {
+					return {
+						success: true,
+						output: `WebSocket monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the server closes the connection first; you get one notice at expiry — start it again if you still need the watch). Each line of each text frame the server sends reaches you as an event while you keep working; binary frames are only counted. The connection opens in the background: if it fails you are told in an event. Do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
+						data: { jobId: job.id, monitor: true, timeoutMs, transport: 'websocket' },
+					}
+				}
+				return {
+					success: true,
+					output: `Monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the command ends first; you get one notice at expiry — start it again if you still need the watch). Each line the command prints to stdout reaches you as an event while you keep working; do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
+					data: { jobId: job.id, monitor: true, timeoutMs },
+					facts: { kind: 'command', command: input.command as string, background: true },
+				}
+			} catch (err) {
+				// The per-owner cap, most likely; naming the limit is actionable.
+				return {
+					success: false,
+					output: '',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+		},
+	})
+}
+
+export const MonitorTool = createMonitorTool()
+
+/**
+ * The tool, for a host that opts in.
+ *
+ * Not in `getBuiltinTools()`: a watch needs a host that delivers events and
+ * wakes on them, and offering a tool that starts a job nobody will hear from
+ * is worse than not offering it. A function rather than a constant so a host
+ * can decide per turn, and so it reads like `getCodeAnalysisTools`, beside
+ * which a host mounts it deferred. Called with no options it returns the
+ * shared {@link MonitorTool}.
+ */
+export function getMonitorTools(options?: MonitorToolOptions): (typeof MonitorTool)[] {
+	return [options === undefined ? MonitorTool : createMonitorTool(options)]
+}

package/src/turn/reporter.ts

@@ -309,6 +309,14 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 					...(event.exitCode !== undefined ? { 'namzu.jobs.exit_code': event.exitCode } : {}),
 				})
 				break
+			case 'monitor_event':
+				log.debug('Monitor event', {
+					'namzu.jobs.id': event.jobId,
+					'namzu.monitor.event_id': event.eventId,
+					'namzu.monitor.kind': event.kind,
+					'namzu.monitor.chars': event.text.length,
+				})
+				break
 			case 'memory_consolidated':
 				log.info('Turn learnings consolidated into the memory store', {
 					'namzu.memory.id': event.memoryId,

package/src/types/sandbox/index.ts

@@ -334,6 +334,16 @@ export interface Sandbox {
 	readonly status: SandboxStatus
 	readonly rootDir: string
 	readonly environment: SandboxEnvironment
+	/**
+	 * The network policy in force right now, when the backend can say.
+	 *
+	 * Optional, and absent does NOT mean open: a caller that needs to know
+	 * whether a host is reachable (the host process opening a connection on a
+	 * turn's behalf, outside the boundary) treats absence as "not allowed" on a
+	 * tier that isolates the network. A backend that enforces
+	 * {@link setNetworkPolicy} should report what it enforces here.
+	 */
+	readonly networkPolicy?: SandboxNetworkPolicy
 	exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>
 
 	/**

package/src/types/session/events.ts

@@ -612,6 +612,28 @@ type CoreSessionEvent =
 			status: 'exited' | 'killed'
 			exitCode?: number
 			signal?: string
+			/** Present when the job was a monitor: what it watched and, if the registry stopped it, why. */
+			monitor?: {
+				description: string
+				stopReason?: 'expired' | 'too_much_output' | 'stopped'
+			}
+	  }
+	/**
+	 * A monitor this session (or the owner it runs under) started has
+	 * something to say: a batch of its stdout lines, or a notice from the
+	 * monitor itself (events suppressed, stopped, expired). The model reads it
+	 * on its next tool result; the host learns it from this, whether or not a
+	 * turn is running. `eventId` is what a host acknowledges.
+	 */
+	| {
+			type: 'monitor_event'
+			sessionId: SessionId
+			turnId?: TurnId
+			jobId: string
+			eventId: string
+			description: string
+			kind: 'output' | 'notice'
+			text: string
 	  }
 	/**
 	 * What the turn learned was written to the host's memory store: its
@@ -1229,7 +1251,7 @@ export type ChildSessionLifecycleEvent =
 	| ChildSessionIdledEvent
 
 /**
- * Discriminated union of every live session event: 62 type literals.
+ * Discriminated union of every live session event: 63 type literals.
  *
  * `type` is the sole discriminator for exhaustive switches; envelope fields
  * are additive and never take part in discrimination.
@@ -1247,21 +1269,26 @@ export type SessionEventListener = (event: SessionEvent) => void | Promise<void>
 /**
  * Event types whose volume makes durable persistence wasteful. They reach the
  * live stream and never the session log: the completed message, reasoning
- * block and tool input carry the same content once.
+ * block and tool input carry the same content once. A `monitor_event` is the
+ * same case: the text the model read is already in the transcript as the
+ * runtime-context message or tool result that carried it, and a noisy watch
+ * would write tens of megabytes an hour of raw process output a second time.
+ * `background_job_exited.monitor` is the durable record of how a watch ended.
  */
 export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEventType>([
 	'text_delta',
 	'tool_input_delta',
 	'reasoning_delta',
 	'tool_progress',
+	'monitor_event',
 ])
 
 export function isEphemeralEvent(event: { readonly type: string }): boolean {
 	return EPHEMERAL_EVENT_TYPES.has(event.type as SessionEventType)
 }
 
-/** The event types a session log records: every literal except the ephemeral four. */
+/** The event types a session log records: every literal except the ephemeral five. */
 export type PersistedSessionEventType = Exclude<
 	SessionEventType,
-	'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress'
+	'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress' | 'monitor_event'
 >

package/src/types/session/records.ts

@@ -648,6 +648,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	turn_resuming: true,
 	guardrail_triggered: true,
 	background_job_exited: true,
+	monitor_event: true,
 	memory_consolidated: true,
 	turn_completed: true,
 	turn_failed: true,
@@ -687,12 +688,12 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	child_session_idled: true,
 }
 
-/** All 62 live event type literals. */
+/** All 63 live event type literals. */
 export const SESSION_EVENT_TYPES: readonly SessionEventType[] = Object.freeze(
 	Object.keys(SESSION_EVENT_TYPE_TABLE) as SessionEventType[],
 )
 
-/** The 58 event types a session log records. */
+/** The 58 event types a session log records: all 63 but the five ephemeral ones. */
 export const PERSISTED_SESSION_EVENT_TYPES: readonly PersistedSessionEventType[] = Object.freeze(
 	SESSION_EVENT_TYPES.filter(
 		(type) => !EPHEMERAL_EVENT_TYPES.has(type),

package/src/types/tool/index.ts

@@ -105,6 +105,20 @@ export interface SkillRegistryRef {
 	names(): readonly string[]
 }
 
+/**
+ * Where a WebSocket monitor connects, already checked.
+ *
+ * `addresses` are what the caller verified are outside the host's own
+ * network; the connection is pinned to them and never resolves the name
+ * itself. A caller that did not check must not hand it a target: the registry
+ * trusts it, as it trusts a spawn it is given.
+ */
+export interface MonitorWebSocketTarget {
+	readonly url: string
+	readonly protocols?: readonly string[]
+	readonly addresses: readonly { readonly address: string; readonly family: 4 | 6 }[]
+}
+
 /**
  * The slice of the background job registry a tool is given.
  *
@@ -120,6 +134,34 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 	}
+	/**
+	 * Start a command whose stdout lines reach the model as events while it
+	 * runs, and which is stopped at `timeoutMs`. The host clamps the timeout to
+	 * its own ceiling and the clamped value comes back, so the caller reports
+	 * the deadline that will actually fire. Optional, like `adopt`: a host that
+	 * cannot deliver events must omit it, and the `monitor` tool then refuses
+	 * rather than start a watch nobody will hear from. Throws when the owner is
+	 * at its job cap.
+	 */
+	startMonitor?(params: {
+		command: string
+		description: string
+		timeoutMs: number
+		workingDirectory?: string
+	}): { job: { id: string; status: string }; timeoutMs: number }
+	/**
+	 * Start a monitor whose source is a WebSocket connection. Separate from
+	 * {@link startMonitor} so a host that implements that one for commands is
+	 * not handed an input it was not written for; a host without this method
+	 * refuses a `ws` call with a plain message. The target's addresses are
+	 * already checked; see {@link MonitorWebSocketTarget}.
+	 */
+	startWebSocketMonitor?(params: {
+		description: string
+		timeoutMs: number
+		workingDirectory?: string
+		webSocket: MonitorWebSocketTarget
+	}): { job: { id: string; status: string }; timeoutMs: number }
 	get(id: string): {
 		id: string
 		status: string
@@ -156,7 +198,15 @@ export interface BackgroundJobRegistryRef {
 		error?: string
 	}
 	kill(id: string): Promise<{ id: string; status: string }>
-	list(): readonly { id: string; command: string; status: string }[]
+	list(): readonly {
+		id: string
+		command: string
+		status: string
+		/** `monitor` for a job the `monitor` tool started. */
+		kind?: 'monitor'
+		/** What a monitor watches. */
+		description?: string
+	}[]
 	/**
 	 * Await this job's exit instead of reading it in a loop; resolves at
 	 * once for a job that has already stopped. Optional, and added after