@namzu/sdk 49.0.0 → 50.0.0

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -52,6 +52,8 @@ export type JobWaitOutcome =
 			readonly kind: 'exited'
 			readonly status: string
 			readonly exitCode?: number
+			/** Why the command never started, when it could not. */
+			readonly error?: string
 	  } & JobWaitProgress)
 	| ({
 			readonly kind: 'timeout'
@@ -142,6 +144,7 @@ export async function waitForJobWithBounds(
 				kind: 'exited',
 				status: job.status,
 				...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+				...(job.error === undefined ? {} : { error: job.error }),
 				output,
 				nextOffset: cursor,
 				droppedBytes,

package/src/tools/builtins/wait-for-job.ts

@@ -33,40 +33,69 @@ const DEFAULT_IDLE_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_IDLE_MS', 2 *
  */
 const MAX_WAIT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_MAX_MS', 60 * 60 * 1000)
 
-const inputSchema = z.object({
-	id: z.string().describe('The job id, as returned by bash with run_in_background.'),
-	from_offset: z
-		.number()
-		.int()
-		.nonnegative()
-		.optional()
-		.describe('Resume after a previous wait: pass its next_offset to receive only new output.'),
-	timeout_ms: z
-		.number()
-		.int()
-		.positive()
-		.max(MAX_WAIT_MS)
-		.optional()
-		.describe(
-			`Give up after this long even if the job keeps producing output, in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}, maximum: ${MAX_WAIT_MS}. The job is never stopped by this running out.`,
-		),
-	idle_timeout_ms: z
-		.number()
-		.int()
-		.positive()
-		.max(MAX_WAIT_MS)
-		.optional()
-		.describe(
-			`Give up if the job produces no new output for this long, in milliseconds. Default: ${DEFAULT_IDLE_TIMEOUT_MS}. Resets on every new byte of output, so a job that is still working is not cut off; only real silence ends the wait early.`,
-		),
-})
+const inputSchema = z
+	.object({
+		id: z.string().describe('The job id, as returned by bash with run_in_background.'),
+		output_contains: z
+			.string()
+			.min(1)
+			.max(4096)
+			.refine(
+				(value) =>
+					Buffer.byteLength(value) <= 4096 && Buffer.from(value).toString('utf8') === value,
+				'Use a non-empty UTF-8 literal of at most 4096 bytes.',
+			)
+			.optional()
+			.describe(
+				'Wait for this exact literal in output rather than for exit. This observes a marker; it does not prove service health or keep the turn open until the job exits.',
+			),
+		output_stream: z
+			.enum(['stdout', 'stderr', 'either'])
+			.optional()
+			.describe(
+				'Pipe to inspect with output_contains. Default either; stdout and stderr are never joined for a match.',
+			),
+		from_offset: z
+			.number()
+			.int()
+			.nonnegative()
+			.optional()
+			.describe('Resume after a previous wait: pass its next_offset to receive only new output.'),
+		timeout_ms: z
+			.number()
+			.int()
+			.positive()
+			.max(MAX_WAIT_MS)
+			.optional()
+			.describe(
+				`Give up after this long even if the job keeps producing output, in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}, maximum: ${MAX_WAIT_MS}. The job is never stopped by this running out.`,
+			),
+		idle_timeout_ms: z
+			.number()
+			.int()
+			.positive()
+			.max(MAX_WAIT_MS)
+			.optional()
+			.describe(
+				`Give up if the job produces no new output for this long, in milliseconds. Default: ${DEFAULT_IDLE_TIMEOUT_MS}. Resets on every new byte of output, so a job that is still working is not cut off; only real silence ends the wait early.`,
+			),
+	})
+	.superRefine((input, ctx) => {
+		if (input.output_stream !== undefined && input.output_contains === undefined) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['output_stream'],
+				message: 'output_stream requires output_contains.',
+			})
+		}
+	})
 
 type WaitForJobInput = z.infer<typeof inputSchema>
 
 export const WaitForJobTool = defineTool({
 	name: 'wait_for_job',
 	description:
-		'Block until a background job started by bash with run_in_background ends, and return its bounded output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. A wait that runs too long or goes quiet returns its output and next_offset without stopping the job; pass that offset as from_offset on the next wait to avoid repeats.',
+		'Wait for an owned background job to exit, or set output_contains to observe an exact output marker while it stays running. Use one wait instead of polling job read. Output markers do not prove service health or completion and never express intent to wait until exit. A bounded wait returns output and next_offset without stopping the job; pass that cursor as from_offset to exclude earlier output.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
@@ -88,7 +117,7 @@ export const WaitForJobTool = defineTool({
 		return {
 			kind: 'generic',
 			presentation: 'activity',
-			label: `Wait for background job · ${input.id ?? '(missing id)'}`,
+			label: `${input.output_contains === undefined ? 'Wait for background job' : 'Wait for job output'} · ${input.id ?? '(missing id)'}`,
 		}
 	},
 
@@ -112,6 +141,83 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		if (input.output_stream !== undefined && input.output_contains === undefined) {
+			return { success: false, output: '', error: 'output_stream requires output_contains.' }
+		}
+		if (input.output_contains !== undefined) {
+			if (!jobs.waitForOutput) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'This host cannot observe output readiness. It must implement backgroundJobs.waitForOutput; no exit wait was started.',
+				}
+			}
+			try {
+				const outcome = await jobs.waitForOutput(input.id, {
+					literal: input.output_contains,
+					stream: input.output_stream ?? 'either',
+					timeoutMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+					idleTimeoutMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+					...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
+					signal: context.abortSignal,
+				})
+				const notices = [
+					...(outcome.droppedBytes > 0
+						? [`[${outcome.droppedBytes} bytes unavailable before the retained output]`]
+						: []),
+					...(outcome.unsearchedBytes > 0
+						? [
+								`[${outcome.unsearchedBytes} retained bytes could not be searched because the channel history cap discarded them]`,
+							]
+						: []),
+					...(outcome.omittedOutputBytes > 0
+						? [`[${outcome.omittedOutputBytes} earlier bytes omitted from this bounded result]`]
+						: []),
+				]
+				const status =
+					outcome.error !== undefined
+						? `failed to start: ${outcome.error}`
+						: outcome.exitCode === undefined
+							? outcome.status
+							: `${outcome.status} with code ${outcome.exitCode}`
+				const reason =
+					outcome.kind === 'matched'
+						? `Output marker observed on ${outcome.matchedStream}. This is output evidence, not a health check or completion claim.`
+						: outcome.kind === 'exited'
+							? 'Job exited before the marker was observed.'
+							: outcome.kind === 'stopped'
+								? 'Job stop was requested before the marker was observed; shutdown may still be completing.'
+								: outcome.kind === 'aborted'
+									? 'Output observation was cancelled; this wait did not stop the job.'
+									: `Output marker was not observed before the ${outcome.cause} timeout (${outcome.elapsedMs} ms); this wait did not stop the job.`
+				return {
+					success: outcome.kind !== 'aborted',
+					output: `${reason}\n\n${notices.length > 0 ? `${notices.join('\n')}\n` : ''}${outcome.output || '(no new output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+					data: {
+						jobId: input.id,
+						outcome: outcome.kind,
+						status: outcome.status,
+						nextOffset: outcome.nextOffset,
+						droppedBytes: outcome.droppedBytes,
+						unsearchedBytes: outcome.unsearchedBytes,
+						omittedOutputBytes: outcome.omittedOutputBytes,
+						...(outcome.kind === 'matched' ? { matchedStream: outcome.matchedStream } : {}),
+						...(outcome.kind === 'timeout' ? { timedOut: outcome.cause } : {}),
+						...(outcome.kind === 'aborted' ? { abandoned: true } : {}),
+						...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
+						...(outcome.error === undefined ? {} : { error: outcome.error }),
+					},
+				}
+			} catch (err) {
+				return {
+					success: false,
+					output: '',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+		}
+
 		if (!jobs.waitForExit) {
 			return {
 				success: false,
@@ -178,9 +284,11 @@ export const WaitForJobTool = defineTool({
 		}
 
 		const status =
-			outcome.exitCode === undefined
-				? outcome.status
-				: `${outcome.status} with code ${outcome.exitCode}`
+			outcome.error !== undefined
+				? `failed to start: ${outcome.error}`
+				: outcome.exitCode === undefined
+					? outcome.status
+					: `${outcome.status} with code ${outcome.exitCode}`
 
 		return {
 			success: true,
@@ -192,6 +300,7 @@ export const WaitForJobTool = defineTool({
 				droppedBytes: outcome.droppedBytes,
 				omittedOutputBytes: outcome.omittedOutputBytes,
 				...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
+				...(outcome.error === undefined ? {} : { error: outcome.error }),
 			},
 		}
 	},

package/src/tools/builtins/write-file.ts

@@ -2,6 +2,7 @@ import { mkdir, readFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext, ToolResult } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
@@ -196,13 +197,14 @@ export const WriteFileTool = defineTool({
 function enforceReadBeforeOverwrite(
 	context: ToolContext,
 	key: string,
-): { success: false; output: ''; error: string } | null {
+): { success: false; output: ''; error: string; facts?: ToolFacts } | null {
 	if (!context.fileReadTracker) return null
 	if (context.fileReadTracker.hasRead(key)) return null
 	return {
 		success: false,
 		output: '',
 		error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
+		facts: { kind: 'failure', reason: 'already_exists', subject: key },
 	}
 }
 
@@ -210,7 +212,7 @@ function enforceFreshOverwrite(
 	context: ToolContext,
 	key: string,
 	currentContent: string,
-): { success: false; output: ''; error: string } | null {
+): { success: false; output: ''; error: string; facts?: ToolFacts } | null {
 	const unread = enforceReadBeforeOverwrite(context, key)
 	if (unread) return unread
 

package/src/tools/command-shell.ts

@@ -34,7 +34,8 @@
  * `NAMZU_BASH_SHELL=/bin/sh` restores the old shell exactly.
  */
 
-import { constants, accessSync } from 'node:fs'
+import { type ChildProcess, type SpawnOptions, spawn as nodeSpawn } from 'node:child_process'
+import { constants, accessSync, existsSync } from 'node:fs'
 import { delimiter, isAbsolute, join } from 'node:path'
 
 import type { ShellDialect } from '../types/tool/index.js'
@@ -67,12 +68,19 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 	if (override !== undefined && override !== '') {
 		// Read as bash only when it is bash; anything else gets the reading
 		// that holds for every POSIX shell.
-		const name = override.slice(override.lastIndexOf('/') + 1)
+		const name =
+			probe.platform === 'win32'
+				? override
+						.split(/[\\/]/)
+						.at(-1)
+						?.toLowerCase()
+						.replace(/\.exe$/, '')
+				: override.slice(override.lastIndexOf('/') + 1)
 		return { path: override, dialect: name === 'bash' ? 'bash' : 'sh', source: 'override' }
 	}
 	// Windows keeps Node's platform shell. Looking `bash` up on its PATH can
 	// find WSL's launcher, which runs the command in another system.
-	if (probe.platform === 'win32') return { path: undefined, dialect: 'sh', source: 'platform' }
+	if (probe.platform === 'win32') return { path: undefined, dialect: 'cmd', source: 'platform' }
 	for (const directory of (probe.env.PATH ?? '').split(delimiter)) {
 		if (directory === '' || !directory.startsWith('/')) continue
 		const candidate = join(directory, 'bash')
@@ -94,7 +102,7 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 export function findCommandShellForDialect(
 	dialect: 'bash' | 'sh',
 	probe: CommandShellProbe,
-): CommandShell | undefined {
+): (CommandShell & { readonly dialect: 'bash' | 'sh' }) | undefined {
 	if (probe.platform === 'win32') return undefined
 	const override = probe.env.NAMZU_BASH_SHELL
 	if (override) {
@@ -142,7 +150,9 @@ export function hostCommandShell(): CommandShell {
 }
 
 /** Re-check the requested executable each time a job is confirmed or fired. */
-export function installedCommandShellForDialect(dialect: 'bash' | 'sh'): CommandShell | undefined {
+export function installedCommandShellForDialect(
+	dialect: 'bash' | 'sh',
+): (CommandShell & { readonly dialect: 'bash' | 'sh' }) | undefined {
 	return findCommandShellForDialect(dialect, {
 		env: process.env,
 		platform: process.platform,
@@ -173,6 +183,123 @@ export function hostShellSpawn(
 	return { file: shell.path, args: ['-c', command], env: withoutBashStartup(env) }
 }
 
+/** Why a command could not be started, in the words a model or operator reads. */
+export function describeSpawnFailure(error: unknown, cwd?: string): string {
+	// Node reports a missing working directory as ENOENT on the shell's own
+	// path ("spawn C:\Windows\system32\cmd.exe ENOENT"), which sends the reader
+	// looking for a missing shell. Say what is actually missing.
+	if (
+		cwd !== undefined &&
+		(error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT' &&
+		!existsSync(cwd)
+	) {
+		return `Could not start the command: the working directory does not exist: ${cwd}`
+	}
+	const detail = error instanceof Error ? error.message : String(error)
+	return `Could not start the command: ${detail}`
+}
+
+/** Environment variable that carries the command line into the inner cmd. */
+const WINDOWS_COMMAND_VARIABLE = 'NAMZU_HOST_COMMAND'
+const WINDOWS_SHELL_VARIABLE = 'NAMZU_HOST_COMSPEC'
+
+/**
+ * The spawn for one command line under cmd on Windows: the outer cmd's file,
+ * its arguments and the environment that carries the command.
+ *
+ * A bare `cmd /d /s /c <command>` converts the command line to the console's
+ * OEM code page before it runs anything, so letters that page lacks arrive
+ * as their nearest ASCII look-alike (g-breve as `g`, s-cedilla as `s` on
+ * CP850) and are gone before the command writes a byte. `chcp` inside the
+ * same line is too late: the line is already converted. So the outer cmd
+ * only switches the console to UTF-8 and starts a second cmd, and the
+ * command travels in the environment, which is Unicode and never converted.
+ * The outer cmd reads it with delayed expansion (`!NAME!`), which happens
+ * after its line is parsed, so quotes, `&`, `|` and `>` in the command are
+ * inert there and reach the second cmd as the line it was given: quoting,
+ * `%` and redirection mean what they meant before, and its exit code is the
+ * command's. Neither cmd is looked up on PATH, so a `cmd.exe` in the
+ * working directory is never picked up.
+ */
+function windowsCmdSpawn(
+	command: string,
+	env: NodeJS.ProcessEnv,
+): {
+	readonly file: string
+	readonly args: readonly string[]
+	readonly env: NodeJS.ProcessEnv
+} {
+	const lookup = (name: string): string | undefined => {
+		const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase())
+		return key === undefined ? undefined : env[key]
+	}
+	const comspec =
+		lookup('ComSpec') ??
+		`${lookup('SystemRoot') ?? process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\cmd.exe`
+	return {
+		file: comspec,
+		// Passed verbatim: Node must not re-quote the line, whose outer quotes
+		// `/s` strips.
+		args: [
+			'/d',
+			'/v:on',
+			'/s',
+			'/c',
+			`"chcp 65001>nul & "!${WINDOWS_SHELL_VARIABLE}!" /d /s /c "!${WINDOWS_COMMAND_VARIABLE}!""`,
+		],
+		env: { ...env, [WINDOWS_SHELL_VARIABLE]: comspec, [WINDOWS_COMMAND_VARIABLE]: command },
+	}
+}
+
+/**
+ * Start one command on the host, in the shell {@link hostCommandShell} chose.
+ *
+ * The ONE place that knows what Windows needs: with no shell path (cmd), Node
+ * itself must run the line (`cmd.exe /d /s /c`, see `windowsCmdSpawn`);
+ * everywhere else it is `<shell> -c <command>`. The foreground `bash` tool,
+ * the background job registry and plugin hooks all spawn through here, so
+ * they cannot diverge: the registry once spawned `/bin/sh` on Windows while
+ * the foreground tool did not, and every background job died at once with no
+ * message.
+ *
+ * - On Windows the line runs under UTF-8 (see `windowsCmdSpawn`).
+ * - `detached` (own process group, for `killTree`) is POSIX only; on Windows
+ *   it opens a new console window instead.
+ * - `windowsHide` keeps a GUI host from flashing a console per command.
+ */
+export function spawnHostShell(
+	command: string,
+	options: {
+		readonly cwd: string
+		readonly env: NodeJS.ProcessEnv
+		readonly stdio?: SpawnOptions['stdio']
+		/** Default: true off Windows. */
+		readonly detached?: boolean
+		readonly shell?: CommandShell
+		/** For tests: the platform the options are shaped for. */
+		readonly platform?: NodeJS.Platform
+		/** For tests: the spawn that runs it. */
+		readonly spawnImpl?: typeof nodeSpawn
+	},
+): ChildProcess {
+	const spawnFn = options.spawnImpl ?? nodeSpawn
+	const resolved = hostShellSpawn(command, options.env, options.shell)
+	const common: SpawnOptions = {
+		cwd: options.cwd,
+		env: resolved.env,
+		detached: options.detached ?? (options.platform ?? process.platform) !== 'win32',
+		windowsHide: true,
+		...(options.stdio === undefined ? {} : { stdio: options.stdio }),
+	}
+	if (resolved.file !== undefined) return spawnFn(resolved.file, [...resolved.args], common)
+	const windows = windowsCmdSpawn(command, resolved.env)
+	return spawnFn(windows.file, [...windows.args], {
+		...common,
+		env: windows.env,
+		windowsVerbatimArguments: true,
+	})
+}
+
 export function withoutBashStartup<T extends Readonly<Record<string, string | undefined>>>(
 	env: T,
 ): T {

package/src/tools/coordinator/agent.ts

@@ -21,26 +21,16 @@ import type { TaskLaunchedCallback } from './index.js'
  * subagent tool calls are isolated — only the summary surfaces to
  * the parent.
  *
- * **How this relates to `create_task`.** This paragraph used to say the two
- * were different shapes — that `create_task` / `continue_task` /
- * `cancel_task` were a non-blocking trio driven by a `<task-notification>`
- * callback, and that the blocking `Agent` tool should be preferred. None of
- * that is true any more. `create_task` blocks and returns the worker's output
- * as its own `tool_result`, exactly like this tool; `continue_task` and
- * `cancel_task` are still defined in `./index.ts` but are deliberately not
- * registered, because a blocking launch leaves every worker terminal by the
- * time a later turn learns its id. So a reader following the old advice was
- * choosing between two tools on a distinction that no longer existed.
+ * `create_task` also returns the worker result inline by default. When a
+ * CompletionInbox is supplied it can instead launch in the background;
+ * `wait_for_task`, `continue_task` and `cancel_task` let the supervisor join,
+ * steer or stop its own launched work. Linked planning tasks and approved
+ * plan steps settle from the worker's actual outcome on either launch path.
  *
- * What actually separates them is the surface, not the timing:
- *
- * - `create_task` arrives with the rest of the coordinator surface —
- *   `agent_task_list`, and `approve_plan` / `ask_user_question` when their
- *   dependencies are wired. That is the supervisor's toolkit.
- * - This builds one tool and nothing else, for an agent whose only delegation
- *   need is "hand this to a specialist". `terminal: true` additionally lets a
- *   pure router settle on the specialist's answer instead of spending a turn
- *   at full parent context to paraphrase it.
+ * `create_task` arrives with the coordinator toolkit, including task listing
+ * and optional plan approval/question tools. This builds one delegation tool.
+ * `terminal: true` additionally lets a pure router settle on the specialist's
+ * answer instead of spending a turn restating it.
  *
  * Neither is legacy. Pick by how much of the coordinator surface you want.
  */