@namzu/sdk 27.1.0 → 28.0.0

package/src/sandbox/provider/local.ts

@@ -11,6 +11,8 @@ import {
 } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { NAMZU } from '../../constants/telemetry/index.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 
 import {
 	SANDBOX_DEFAULT_TIMEOUT_MS,
@@ -19,6 +21,10 @@ import {
 	SANDBOX_SAFE_ENV_KEYS,
 	SANDBOX_TEMP_DIR_PREFIX,
 } from '../../constants/sandbox/index.js'
+// The process-tree kill lives in its own leaf now: the background job
+// registry needs the same one, and a near-copy would reproduce in the copy
+// every bug the original's comment was written to record.
+import { killTree } from '../../process/kill-tree.js'
 import type { SandboxId } from '../../types/ids/index.js'
 import type {
 	Sandbox,
@@ -34,6 +40,13 @@ import type {
 import { generateSandboxId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { assertIsolation, describeIsolation } from '../isolation.js'
+import {
+	type OpenTerminalOptions,
+	type PtyLoader,
+	type TerminalSession,
+	loadPty,
+	openTerminalWith,
+} from '../terminal.js'
 
 // ---------------------------------------------------------------------------
 // Path safety
@@ -346,21 +359,33 @@ class LocalSandbox implements Sandbox {
 		return this._status
 	}
 
+	/**
+	 * How the pty binding is loaded. Injectable so a test needs no native
+	 * build — the refusal path and the session wiring are both worth
+	 * covering, and neither should require compiling C++ on CI.
+	 */
+	private readonly ptyLoader: PtyLoader | undefined
+
 	constructor(
 		id: SandboxId,
 		rootDir: string,
 		environment: SandboxEnvironment,
 		config: SandboxCreateConfig,
 		log: Logger,
+		ptyLoader?: PtyLoader,
 	) {
+		this.ptyLoader = ptyLoader
 		this.id = id
 		this.rootDir = rootDir
 		this.environment = environment
 		this.config = config
 		this._status = 'ready'
-		this.log = log.child({ component: 'LocalSandbox', sandboxId: id })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'sandbox/provider/local', [NAMZU.SANDBOX_ID]: id })
 
-		this.log.info('Sandbox created', { rootDir, environment })
+		this.log.info('Sandbox created', {
+			'namzu.sandbox.root_dir': rootDir,
+			'namzu.execution.environment': environment,
+		})
 	}
 
 	async exec(
@@ -382,7 +407,12 @@ class LocalSandbox implements Sandbox {
 
 		const { spawnCommand, spawnArgs } = this.buildSpawnArgs(command, args)
 
-		this.log.debug('Executing command', { command, args, timeout, environment: this.environment })
+		this.log.debug('Executing command', {
+			'namzu.sandbox.command': command,
+			'namzu.sandbox.args': args,
+			'namzu.sandbox.timeout': timeout,
+			'namzu.execution.environment': this.environment,
+		})
 
 		// The caller's cancellation and this call's own deadline both have to
 		// reach `spawn`, and `spawn` takes exactly one signal.
@@ -410,6 +440,33 @@ class LocalSandbox implements Sandbox {
 		}
 	}
 
+	/**
+	 * A real pseudo-terminal, or a refusal that says what to install.
+	 *
+	 * Deliberately NOT confined the way `exec` is. `exec` wraps every
+	 * command in this class's isolation tiers (`unshare …`,
+	 * `sandbox-exec …`); a terminal is an interactive session a human is
+	 * driving, and wrapping it would put the tier's own shell between the
+	 * operator's keystrokes and the program. So this runs inside the
+	 * sandbox's ROOT DIRECTORY and nothing more — which is stated here
+	 * because a caller reading "sandbox" would otherwise assume the tier
+	 * applies, and it is exactly the assumption that makes a boundary
+	 * imaginary.
+	 *
+	 * A host that needs the tier runs its interactive program through
+	 * `exec` and accepts that it is not a terminal, or supplies a backend
+	 * whose terminals are confined by construction — a container's `exec`,
+	 * for instance, where the confinement is the container and not a
+	 * wrapper.
+	 */
+	async openTerminal(options: OpenTerminalOptions): Promise<TerminalSession> {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+		const pty = await loadPty(this.ptyLoader)
+		return openTerminalWith(pty, options, { shell: '/bin/sh', cwd: this.rootDir })
+	}
+
 	async writeFile(path: string, content: string | Buffer): Promise<void> {
 		if (this._status === 'destroyed') {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
@@ -423,7 +480,7 @@ class LocalSandbox implements Sandbox {
 		await fsWriteFile(tmpPath, content)
 		await rename(tmpPath, resolved)
 
-		this.log.debug('File written', { path: resolved })
+		this.log.debug('File written', { 'namzu.sandbox.path': resolved })
 	}
 
 	async readFile(path: string): Promise<Buffer> {
@@ -473,7 +530,7 @@ class LocalSandbox implements Sandbox {
 		this._status = 'destroyed'
 		await rm(this.rootDir, { recursive: true, force: true })
 
-		this.log.info('Sandbox destroyed', { sandboxId: this.id })
+		this.log.info('Sandbox destroyed', { 'namzu.sandbox.id': this.id })
 	}
 
 	// -----------------------------------------------------------------------
@@ -521,6 +578,12 @@ class LocalSandbox implements Sandbox {
 					env,
 					stdio: ['pipe', 'pipe', 'pipe'],
 					signal,
+					// Leader of its own process group (POSIX only — Windows has
+					// nothing to opt into here), not a member of this Node
+					// process's. That is what lets `killTree` below reach `cmd`
+					// and its descendants with one `-pid` signal instead of only
+					// the shell sitting in front of them.
+					detached: process.platform !== 'win32',
 				})
 			} catch (err) {
 				rejectPromise(err)
@@ -541,16 +604,12 @@ class LocalSandbox implements Sandbox {
 					// timeout would tell the model to retry with a longer
 					// budget for something a human just stopped.
 					timedOut = ac.signal.aborted
-					// Give process a grace period, then SIGKILL
-					if (child.pid) {
-						setTimeout(() => {
-							try {
-								child.kill('SIGKILL')
-							} catch {
-								// Process may have already exited
-							}
-						}, SANDBOX_KILL_GRACE_MS)
-					}
+					// `spawn`'s own `signal` handling already reached `child.pid`
+					// — the outermost wrapper — but that was never the process
+					// this call exists to stop. Reach the whole tree, then give
+					// it a grace period before forcing it.
+					killTree(child, 'SIGTERM')
+					setTimeout(() => killTree(child, 'SIGKILL'), SANDBOX_KILL_GRACE_MS)
 					return
 				}
 				rejectPromise(err)
@@ -586,6 +645,14 @@ export interface LocalSandboxProviderOptions {
 	 * whatever the host happens to offer.
 	 */
 	readonly requireIsolation?: readonly SandboxIsolationControl[]
+	/**
+	 * How a sandbox loads the pty binding for {@link Sandbox.openTerminal}.
+	 *
+	 * Injectable so a test needs no native build. Absent means the real
+	 * `import`, which is what a host gets — and what refuses, by name, when
+	 * the binding is not installed.
+	 */
+	readonly ptyLoader?: PtyLoader
 }
 
 export class LocalSandboxProvider implements SandboxProvider {
@@ -595,9 +662,12 @@ export class LocalSandboxProvider implements SandboxProvider {
 
 	private readonly log: Logger
 
+	private readonly ptyLoader: PtyLoader | undefined
+
 	constructor(log: Logger, options: LocalSandboxProviderOptions = {}) {
+		this.ptyLoader = options.ptyLoader
 		this.environment = detectEnvironment()
-		this.log = log.child({ component: 'LocalSandboxProvider' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'sandbox/provider/local' })
 
 		assertIsolation(this.environment, options.requireIsolation ?? [])
 
@@ -611,11 +681,14 @@ export class LocalSandboxProvider implements SandboxProvider {
 			// that reads "sandbox created" in its log has every reason to
 			// believe otherwise.
 			this.log.warn('No isolation available on this host; commands run unconfined', {
-				environment: this.environment,
-				enforced,
+				'namzu.execution.environment': this.environment,
+				'namzu.sandbox.enforced': enforced,
 			})
 		} else {
-			this.log.info('Initialized', { environment: this.environment, enforced })
+			this.log.info('Initialized', {
+				'namzu.execution.environment': this.environment,
+				'namzu.sandbox.enforced': enforced,
+			})
 		}
 	}
 
@@ -629,8 +702,8 @@ export class LocalSandboxProvider implements SandboxProvider {
 		// Canonicalize — macOS symlinks like /var → /private/var must be resolved
 		const rootDir = canonicalizePath(rawDir)
 
-		this.log.info('Creating sandbox', { sandboxId: id, rootDir })
+		this.log.info('Creating sandbox', { 'namzu.sandbox.id': id, 'namzu.sandbox.root_dir': rootDir })
 
-		return new LocalSandbox(id, rootDir, this.environment, config ?? {}, this.log)
+		return new LocalSandbox(id, rootDir, this.environment, config ?? {}, this.log, this.ptyLoader)
 	}
 }

package/src/sandbox/terminal.ts

@@ -0,0 +1,197 @@
+/**
+ * A real terminal inside the sandbox, or nothing.
+ *
+ * `exec` runs a command and hands back what it printed. That is the whole
+ * shape of it, and a large class of work does not fit: an interactive
+ * installer waiting on a prompt, a REPL, `git rebase -i`, anything that
+ * draws with escape codes, anything that asks for a password. Every one of
+ * those needs a pseudo-terminal, and a pipe is not one.
+ *
+ * **The refusal is the design.** A pseudo-terminal needs a native binding
+ * this kernel deliberately does not depend on — it would make every install
+ * build C++ for a capability most runs never use. So the terminal is
+ * optional, and where it is unavailable it is REFUSED rather than
+ * substituted with a pipe. A pipe would work: `spawn` would run, bytes
+ * would flow, and every program that calls `isatty` would take its
+ * non-interactive branch. The prompt never appears, the REPL exits
+ * immediately, the progress bar prints ten thousand lines, and nothing says
+ * why. That is the same rule `Sandbox.setNetworkPolicy` states for itself:
+ * a capability accepted and not applied is worse than one never offered,
+ * because the caller stops looking.
+ */
+
+export interface TerminalSize {
+	readonly cols: number
+	readonly rows: number
+}
+
+export interface OpenTerminalOptions {
+	/** The program to run. Defaults to the sandbox's own shell. */
+	readonly command?: string
+	readonly args?: readonly string[]
+	readonly cwd?: string
+	readonly env?: Readonly<Record<string, string>>
+	/**
+	 * The initial size.
+	 *
+	 * Required rather than defaulted, because a program that draws to the
+	 * screen asks the terminal how big it is before it draws anything, and a
+	 * default that is wrong produces a first frame nobody can read. A caller
+	 * with no window to measure passes its own choice, deliberately.
+	 */
+	readonly size: TerminalSize
+}
+
+export interface TerminalSession {
+	/** Send keystrokes. Bytes, not lines — the program decides what a line is. */
+	write(data: string): void
+	/**
+	 * Tell the program the window changed.
+	 *
+	 * A separate call rather than a settable property, because it has to
+	 * reach the child as SIGWINCH: a program redraws on the signal, not on
+	 * our bookkeeping.
+	 */
+	resize(size: TerminalSize): void
+	/** Everything the program printed, as it arrives. Returns an unsubscribe. */
+	onData(listener: (chunk: string) => void): () => void
+	/** Resolves when the program exits. */
+	readonly exited: Promise<{ exitCode: number; signal?: number }>
+	/** Stop it. */
+	kill(signal?: string): void
+}
+
+/** A terminal asked for where none can be provided. */
+export class TerminalUnavailableError extends Error {
+	readonly details: { specifier: string; reason: 'absent' | 'broken'; cause?: string }
+
+	constructor(details: { specifier: string; reason: 'absent' | 'broken'; cause?: string }) {
+		super(
+			details.reason === 'absent'
+				? `No pseudo-terminal is available: "${details.specifier}" is not installed. Install it to use a terminal session, or use exec() — which is not a terminal and does not pretend to be.`
+				: `A pseudo-terminal is installed but unusable: "${details.specifier}" failed to load (${details.cause ?? 'no detail'}). This is usually a native build that does not match this Node version.`,
+		)
+		this.name = 'TerminalUnavailableError'
+		this.details = details
+	}
+}
+
+/**
+ * The binding this looks for.
+ *
+ * Named rather than searched for: probing several candidates would make the
+ * capability's behaviour depend on which one happened to be installed, and
+ * a refusal that could not say what to install is a refusal nobody can act
+ * on.
+ */
+export const PTY_SPECIFIER = 'node-pty'
+
+/** The slice of the binding this uses. Structural, so a test needs no native build. */
+export interface PtyModule {
+	spawn(
+		file: string,
+		args: readonly string[],
+		options: {
+			name?: string
+			cols: number
+			rows: number
+			cwd?: string
+			env?: Record<string, string>
+		},
+	): PtyProcess
+}
+
+export interface PtyProcess {
+	write(data: string): void
+	resize(cols: number, rows: number): void
+	onData(listener: (data: string) => void): { dispose(): void }
+	onExit(listener: (event: { exitCode: number; signal?: number }) => void): { dispose(): void }
+	kill(signal?: string): void
+}
+
+export type PtyLoader = () => Promise<PtyModule>
+
+/**
+ * Load the binding, or say precisely why not.
+ *
+ * The two failures are kept apart because the fixes are different: `absent`
+ * is "install it", `broken` is almost always a native build compiled
+ * against a different Node version, and telling somebody to install a thing
+ * they already installed is the least useful message available.
+ */
+export async function loadPty(loader?: PtyLoader): Promise<PtyModule> {
+	const load = loader ?? (async () => (await import(PTY_SPECIFIER)) as unknown as PtyModule)
+	try {
+		const module = await load()
+		if (typeof module?.spawn !== 'function') {
+			throw new Error('the module has no spawn()')
+		}
+		return module
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		// A resolution failure and a load failure look different in the
+		// message, and that is the only signal available — the import throws
+		// the same class either way.
+		const absent = /Cannot find (module|package)|ERR_MODULE_NOT_FOUND/.test(message)
+		throw new TerminalUnavailableError({
+			specifier: PTY_SPECIFIER,
+			reason: absent ? 'absent' : 'broken',
+			cause: message,
+		})
+	}
+}
+
+/**
+ * Open a terminal, given a loaded binding.
+ *
+ * Separated from `loadPty` so the refusal and the session are testable
+ * apart: one is about a missing dependency, the other about wiring a
+ * process that exists.
+ */
+export function openTerminalWith(
+	pty: PtyModule,
+	options: OpenTerminalOptions,
+	defaults: { readonly shell: string; readonly cwd: string },
+): TerminalSession {
+	const listeners = new Set<(chunk: string) => void>()
+
+	const child = pty.spawn(options.command ?? defaults.shell, options.args ?? [], {
+		// `xterm-256color`, and this is not cosmetic: `TERM` is how a program
+		// decides which escape sequences it may emit. Leaving it unset makes
+		// well-behaved programs fall back to no colour and no cursor
+		// movement, which is a terminal that works and looks broken.
+		name: 'xterm-256color',
+		cols: options.size.cols,
+		rows: options.size.rows,
+		cwd: options.cwd ?? defaults.cwd,
+		...(options.env ? { env: { ...options.env } } : {}),
+	})
+
+	const dataSub = child.onData((chunk) => {
+		for (const listener of listeners) listener(chunk)
+	})
+
+	const exited = new Promise<{ exitCode: number; signal?: number }>((resolve) => {
+		const exitSub = child.onExit((event) => {
+			// Unsubscribed on exit, both of them. A binding that holds a
+			// listener for a dead process keeps this session's closure alive
+			// for as long as the binding lives, and a long-running host opens
+			// many of these.
+			dataSub.dispose()
+			exitSub.dispose()
+			listeners.clear()
+			resolve(event)
+		})
+	})
+
+	return {
+		write: (data) => child.write(data),
+		resize: (size) => child.resize(size.cols, size.rows),
+		onData(listener) {
+			listeners.add(listener)
+			return () => listeners.delete(listener)
+		},
+		exited,
+		kill: (signal) => child.kill(signal),
+	}
+}

package/src/{gateway → scheduler}/completion-inbox.ts

@@ -1,8 +1,9 @@
 import { wrapUntrusted } from '../tools/untrusted-envelope.js'
-import type { TaskGateway, TaskHandle } from '../types/agent/gateway.js'
+import type { TaskHandle, TaskScheduler } from '../types/agent/scheduler.js'
 import { isTerminalAgentTaskState } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
-import { getRootLogger } from '../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
 /**
  * How many unclaimed announcements may wait for an owner at once.
@@ -52,7 +53,7 @@ const UNOWNED_BUFFER_LIMIT = 32
  * Claiming is what tells the two apart: a tool that delivers a completion
  * says so, and only unclaimed completions become envelopes.
  *
- * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * It attaches through `onTaskCompleted`, which every `TaskScheduler` already
  * has, so a host gateway needs no change to take part — a host that was
  * firing completions into a listener set with no listeners now has one.
  */
@@ -81,7 +82,7 @@ export class CompletionInbox {
 	 *
 	 * `gateway.createTask` resolves one microtask before its caller can name
 	 * the task, and a worker that finishes inside that window is announced
-	 * first — `LocalTaskGateway` attaches its completion continuation before
+	 * first — `LocalTaskScheduler` attaches its completion continuation before
 	 * it returns the handle, so the ordering is guaranteed to be reachable
 	 * rather than merely possible. Dropping an unowned announcement outright
 	 * would therefore turn the leak fix into a LOST RESULT for exactly the
@@ -96,7 +97,13 @@ export class CompletionInbox {
 	private readonly arrivals = new Set<() => void>()
 	private detach?: () => void
 	/** Kept for {@link launched}: the source of truth about a task's state. */
-	private gateway?: TaskGateway
+	private gateway?: TaskScheduler
+
+	/**
+	 * `log` is optional and unresolved until it is actually needed (the
+	 * eviction-warning path in `hold()`), same reason as `LocalTaskScheduler`.
+	 */
+	constructor(private readonly log?: Logger) {}
 
 	/**
 	 * Start listening.
@@ -106,7 +113,7 @@ export class CompletionInbox {
 	 * queue every completion twice and reproduce the exact duplicate this
 	 * class exists to prevent.
 	 */
-	attach(gateway: TaskGateway): () => void {
+	attach(gateway: TaskScheduler): () => void {
 		if (this.detach) return this.detach
 		this.gateway = gateway
 		this.detach = gateway.onTaskCompleted((handle) => {
@@ -145,11 +152,14 @@ export class CompletionInbox {
 			const oldest = this.unowned.keys().next()
 			if (!oldest.done) {
 				this.unowned.delete(oldest.value)
-				getRootLogger()
-					.child({ component: 'CompletionInbox' })
+				resolveLogger(this.log)
+					.child({ [SCOPE_ATTRIBUTE]: 'scheduler/completion-inbox' })
 					.warn(
 						"Unclaimed completion buffer is full — dropped the oldest. If that task was this run's, its result is now unreachable; raise UNOWNED_BUFFER_LIMIT or launch fewer tasks per turn.",
-						{ dropped: oldest.value, limit: UNOWNED_BUFFER_LIMIT },
+						{
+							'namzu.scheduler.dropped': oldest.value,
+							'namzu.scheduler.limit': UNOWNED_BUFFER_LIMIT,
+						},
 					)
 			}
 		}
@@ -176,7 +186,7 @@ export class CompletionInbox {
 	 * announcement it already made. Asking `getTask` covers the case the
 	 * buffer cannot — an announcement evicted under load — but it rests on a
 	 * gateway still knowing about a task it has just settled, which is a
-	 * property of the implementations here rather than of the `TaskGateway`
+	 * property of the implementations here rather than of the `TaskScheduler`
 	 * contract, and `getTask`'s own docs now say so.
 	 */
 	launched(taskId: TaskId): void {