@namzu/sdk 52.2.0 → 52.3.0

package/src/tools/builtins/monitor.ts

@@ -0,0 +1,206 @@
+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 {
+	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.
+ */
+
+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,
+		)
+		.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.',
+		),
+	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.`,
+		),
+})
+
+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>"}.'
+
+export const MonitorTool = 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.
+	commandArgument: 'command',
+	commandDialect: bashToolDialect,
+	permissions: ['shell_execute'],
+	readOnly: false,
+	destructive: (input: MonitorInput) => isDangerousCommand(input.command),
+	// 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) {
+		if (typeof input.command !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Monitor · ${typeof input.description === 'string' ? input.description : input.command}`,
+			facts: { kind: 'command', command: input.command, background: true },
+		}
+	},
+
+	async execute(input, context) {
+		if (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.`,
+			}
+		}
+		// 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.
+		if (context.sandbox && context.sandbox.spawnDetached === undefined) {
+			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 (!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 { job, timeoutMs } = jobs.startMonitor({
+				command: input.command,
+				description: input.description,
+				timeoutMs: input.timeout_ms,
+				workingDirectory: context.workingDirectory,
+			})
+			// `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 },
+				}
+			}
+			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, 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),
+			}
+		}
+	},
+})
+
+/**
+ * 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.
+ */
+export function getMonitorTools(): (typeof MonitorTool)[] {
+	return [MonitorTool]
+}

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/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

@@ -120,6 +120,21 @@ 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 }
 	get(id: string): {
 		id: string
 		status: string
@@ -156,7 +171,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