@namzu/sdk 52.3.0 → 52.4.0

package/dist/types/tool/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAqwCA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAgyCA,cAAc,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "52.3.0",
+  "version": "52.4.0",
   "description": "Open-source AI kernel for TypeScript: runs an agent the way an operating system runs a process, with an identity and a budget, scheduled tool calls and checkpointed turns.",
   "license": "FSL-1.1-MIT",
   "engines": {
@@ -64,6 +64,7 @@
     "@types/brace-expansion": "^1.1.2",
     "@types/node": "^22.19.17",
     "@types/turndown": "^5.0.6",
+    "@types/ws": "8.18.1",
     "@vitest/coverage-v8": "^4.1.11",
     "fast-check": "^4.7.0",
     "jsonschema": "^1.5.0",
@@ -80,7 +81,8 @@
     "minimatch": "^9.0.9",
     "pica": "^10.0.3",
     "quickjs-emscripten-core": "0.32.0",
-    "turndown": "^7.2.4"
+    "turndown": "^7.2.4",
+    "ws": "8.21.3"
   },
   "scripts": {
     "build": "tsc --build",

package/src/connector/web/guarded-fetch.ts

@@ -101,6 +101,9 @@ export function isPrivateAddress(address: string): boolean {
 		if (a === 192 && b === 168) return true // private
 		if (a === 169 && b === 254) return true // link-local, incl. cloud metadata
 		if (a === 0) return true // "this network"
+		if (a === 100 && b >= 64 && b <= 127) return true // shared address space (CGNAT), 100.64.0.0/10
+		if (a === 198 && (b === 18 || b === 19)) return true // benchmarking, 198.18.0.0/15
+		if (a === 192 && b === 0 && parts[2] === 0) return true // IETF protocol assignments, 192.0.0.0/24
 		if (a >= 224) return true // multicast and reserved
 		return false
 	}
@@ -123,8 +126,35 @@ export function isPrivateAddress(address: string): boolean {
 			const low = Number.parseInt(mapped[2], 16)
 			return isPrivateAddress(`${high >>> 8}.${high & 0xff}.${low >>> 8}.${low & 0xff}`)
 		}
+		const hextets = expandHextets(canonical)
+		const embedded = (index: number): string => {
+			const high = hextets[index] ?? 0
+			const low = hextets[index + 1] ?? 0
+			return `${high >>> 8}.${high & 0xff}.${low >>> 8}.${low & 0xff}`
+		}
+		const zeros = (from: number, to: number): boolean =>
+			hextets.slice(from, to).every((hextet) => hextet === 0)
+		// IPv4-compatible, ::/96 (deprecated): `::7f00:1` is 127.0.0.1 for a
+		// stack that still honours it, and nothing public is addressed this way.
+		if (zeros(0, 6)) return true
+		// IPv4-translated, ::ffff:0:0/96 (SIIT): the IPv4 address is the last 32 bits.
+		if (zeros(0, 4) && hextets[4] === 0xffff && hextets[5] === 0)
+			return isPrivateAddress(embedded(6))
+		// NAT64 well-known prefix, 64:ff9b::/96: a translator turns it into the
+		// IPv4 address in the last 32 bits, so `64:ff9b::7f00:1` reaches
+		// 127.0.0.1 through it. Refused only when that address is private: a
+		// public one is what the prefix is for on an IPv6-only network.
+		if (hextets[0] === 0x64 && hextets[1] === 0xff9b && zeros(2, 6)) {
+			return isPrivateAddress(embedded(6))
+		}
+		// NAT64 local-use prefix, 64:ff9b:1::/48 (RFC 8215): a site's own
+		// translator, so the embedded address cannot be read from a fixed place.
+		if (hextets[0] === 0x64 && hextets[1] === 0xff9b && hextets[2] === 1) return true
+		// 6to4, 2002::/16: the IPv4 address is the next 32 bits.
+		if (hextets[0] === 0x2002) return isPrivateAddress(embedded(1))
 		const firstHextet = Number.parseInt(canonical.split(':', 1)[0] ?? '0', 16)
 		if ((firstHextet & 0xffc0) === 0xfe80) return true // link-local fe80::/10
+		if ((firstHextet & 0xffc0) === 0xfec0) return true // site-local fec0::/10 (deprecated)
 		if ((firstHextet & 0xfe00) === 0xfc00) return true // unique-local fc00::/7
 		if ((firstHextet & 0xff00) === 0xff00) return true // multicast ff00::/8
 		return false
@@ -132,6 +162,17 @@ export function isPrivateAddress(address: string): boolean {
 	return false
 }
 
+/** A canonical IPv6 address (as `new URL` writes it, no dots) as its eight 16-bit groups. */
+function expandHextets(canonical: string): number[] {
+	const [head = '', tail] = canonical.split('::')
+	const front = head === '' ? [] : head.split(':')
+	const back = tail === undefined || tail === '' ? [] : tail.split(':')
+	const fill = tail === undefined ? 0 : 8 - front.length - back.length
+	return [...front, ...new Array<string>(Math.max(0, fill)).fill('0'), ...back].map((group) =>
+		Number.parseInt(group, 16),
+	)
+}
+
 export class GuardedFetchProvider implements WebFetchProvider {
 	private readonly timeoutMs: number
 	private readonly maxBytes: number

package/src/process/kill-tree.ts

@@ -1,5 +1,4 @@
 import { execFileSync } from 'node:child_process'
-import type { spawn } from 'node:child_process'
 
 /**
  * Git Bash children that the Windows process tree cannot reach.
@@ -83,7 +82,10 @@ function taskkillPath(): string {
  * already-dead tree that second call is a deliberate no-op, the same as the
  * POSIX SIGKILL that follows a SIGTERM which already worked.
  */
-export function killTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
+export function killTree(
+	child: { readonly pid?: number | undefined },
+	signal: NodeJS.Signals,
+): void {
 	if (!child.pid) return
 	try {
 		if (process.platform === 'win32') {

package/src/public-runtime.ts

@@ -1587,7 +1587,7 @@ export type {
 	LoggerOptions,
 	MutableLogSinkCounters,
 } from './utils/log/types.js'
-export type { JobProcess } from './runtime/jobs/registry.js'
+export type { JobChild, JobHost, JobPipe, JobProcess, JobSource } from './runtime/jobs/registry.js'
 export { WORKING_STATE_MIME } from './connector/mcp/adapter.js'
 
 export {

package/src/public-tools.ts

@@ -92,9 +92,12 @@ export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './tools/builtins
 export {
 	MONITOR_CANNOT_DETACH,
 	MONITOR_TOOL_NAME,
+	MONITOR_WEBSOCKET_WEB_OFF,
 	MonitorTool,
+	createMonitorTool,
 	getMonitorTools,
 } from './tools/builtins/monitor.js'
+export type { MonitorToolOptions } from './tools/builtins/monitor.js'
 export { GlobTool } from './tools/builtins/glob.js'
 export { GrepTool } from './tools/builtins/grep.js'
 // Reads, lists and stops what `bash run_in_background` starts. Ships in

package/src/runtime/jobs/registry.ts

@@ -9,6 +9,7 @@ import type {
 	BackgroundJobOutputWaitOptions,
 	BackgroundJobOutputWaitResult,
 } from '../../types/job/index.js'
+import type { MonitorWebSocketTarget } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { oneMetadataLine } from '../system-events.js'
 import { createBackgroundJobId } from './job-id.js'
@@ -19,6 +20,7 @@ import {
 	expiryNotice,
 	tooMuchOutputNotice,
 } from './monitor-stream.js'
+import { connectWebSocketSource, webSocketJobCommand } from './websocket-source.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -82,6 +84,15 @@ export interface BackgroundJob {
 	 * runs and when the command ended on its own.
 	 */
 	readonly stopReason?: 'expired' | 'too_much_output' | 'stopped'
+	/**
+	 * What the monitor's source is, when it is not a command: `websocket` for a
+	 * monitor of a WebSocket connection, whose `command` is then
+	 * `websocket <url>` and which has no exit code of a process.
+	 */
+	readonly transport?: 'websocket'
+	/** The close code and reason the server ended a WebSocket connection with, if it did. */
+	readonly closeCode?: number
+	readonly closeReason?: string
 }
 
 /**
@@ -97,6 +108,8 @@ export interface MonitorEvent {
 	readonly kind: 'output' | 'notice'
 	readonly text: string
 	readonly at: number
+	/** Set when the source is a WebSocket connection, whose text the server wrote. */
+	readonly transport?: 'websocket'
 }
 
 export interface BackgroundJobOutput {
@@ -118,6 +131,60 @@ export interface BackgroundJobOutput {
 	readonly error?: string
 }
 
+/**
+ * What a `spawn` that is not a child process hands the registry: the few
+ * members of {@link JobChild} and how to stop it. A {@link JobProcess} is one
+ * too, so a `spawn` may return either.
+ */
+export interface JobSource {
+	readonly child: JobChild
+	/** How to stop it, when the registry's process-group kill would not reach everything. */
+	kill?(signal: NodeJS.Signals): void
+	/** Confirm the owned tree stopped; reject instead of claiming an unconfirmed exit. */
+	terminate?(signal?: NodeJS.Signals): Promise<void>
+}
+
+/**
+ * What the registry reads of a job's process, and nothing more.
+ *
+ * A `ChildProcess` satisfies it, and so does anything else that writes bytes
+ * on two pipes and ends: a WebSocket connection held as a monitor's source is
+ * such a thing. Named so that the registry's contract is the few members it
+ * uses and not a type from `node:child_process` it would have to be cast to.
+ */
+export interface JobChild {
+	readonly pid?: number | undefined
+	readonly stdout?: JobPipe | null
+	readonly stderr?: JobPipe | null
+	once(event: 'spawn', listener: () => void): unknown
+	on(event: 'error', listener: (error: Error) => void): unknown
+	once(
+		event: 'close',
+		listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+	): unknown
+}
+
+/** A readable stream, as far as the registry reads one. */
+export interface JobPipe {
+	on(event: 'data', listener: (data: Buffer | string) => void): unknown
+}
+
+/**
+ * What a process can say to the registry besides its output, handed to the
+ * `spawn` that asked for it.
+ */
+export interface JobHost {
+	/**
+	 * Something the SOURCE has to say, delivered to a monitor's listeners as a
+	 * `notice` event and never rationed as output is. `final` ends the stream:
+	 * what is pending goes out first, and nothing the process writes after the
+	 * notice is delivered. Ignored for a job that is not a monitor.
+	 */
+	notice(text: string, options?: { readonly final?: boolean }): void
+	/** The server closed a WebSocket connection with this code and reason. */
+	connectionClosed(code: number, reason: string): void
+}
+
 /** A job's process, when something other than the registry starts it. */
 export interface JobProcess {
 	readonly child: ReturnType<typeof spawn>
@@ -138,7 +205,7 @@ export interface StartJobParams {
 	 * host in the `bash` tool's shell (`tools/command-shell.ts`). The process must be the leader of its own group and must not
 	 * expect stdin.
 	 */
-	readonly spawn?: () => JobProcess
+	readonly spawn?: (host: JobHost) => JobProcess | JobSource
 	/**
 	 * Output the process already wrote before the registry took it over, in
 	 * the order it was written. Used when a foreground command is moved to the
@@ -160,7 +227,12 @@ export interface StartJobParams {
 	 * `timeoutMs`. Both streams stay in the retained buffer, so `read` still
 	 * shows everything, stderr included.
 	 */
-	readonly monitor?: { readonly description: string; readonly timeoutMs: number }
+	readonly monitor?: {
+		readonly description: string
+		readonly timeoutMs: number
+		/** The source is a WebSocket connection and not a command; see {@link BackgroundJob.transport}. */
+		readonly transport?: 'websocket'
+	}
 }
 
 export interface BackgroundJobRegistryConfig {
@@ -241,7 +313,7 @@ export class UnknownBackgroundJobError extends Error {
 
 interface JobEntry {
 	record: BackgroundJob
-	child: ReturnType<typeof spawn>
+	child: JobChild
 	/** The spawner's own kill, when it gave one. */
 	killProcess?: (signal: NodeJS.Signals) => void
 	terminateProcess?: (signal?: NodeJS.Signals) => Promise<void>
@@ -269,6 +341,8 @@ interface MonitorState {
 	readonly timeoutMs: number
 	seq: number
 	expiryTimer?: ReturnType<typeof setTimeout>
+	/** A terminal notice went out: nothing more is delivered, from the source or from anywhere. */
+	sealed?: boolean
 }
 
 /** Whether any process of the group led by `pid` is still alive. */
@@ -343,6 +417,7 @@ export class BackgroundJobRegistry {
 			kind,
 			text,
 			at: Date.now(),
+			...(entry.record.transport ? { transport: entry.record.transport } : {}),
 		}
 		for (const listener of this.monitorListeners) {
 			try {
@@ -432,8 +507,14 @@ export class BackgroundJobRegistry {
 		// The same spawn as a foreground `bash` call, so the permission
 		// rules' reading of the line holds for the job too, and so the two
 		// cannot disagree about how a shell is started on a given platform.
-		const started = params.spawn
-			? params.spawn()
+		const host: JobHost = {
+			notice: (text, options) => this.noticeFromSource(entry, text, options?.final === true),
+			connectionClosed: (code, reason) => {
+				entry.record = { ...entry.record, closeCode: code, closeReason: reason }
+			},
+		}
+		const started: JobProcess | JobSource = params.spawn
+			? params.spawn(host)
 			: {
 					child: spawnHostShell(params.command, {
 						cwd: params.workingDirectory,
@@ -484,6 +565,7 @@ export class BackgroundJobRegistry {
 							// follows is described as what it was and not as a stop
 							// somebody asked for.
 							entry.record = { ...entry.record, stopReason: 'too_much_output' }
+							if (entry.monitor) entry.monitor.sealed = true
 							this.announceMonitorEvent(entry, 'notice', tooMuchOutputNotice(suppressed, overMs))
 							void this.kill(id).catch(() => {
 								// The retained record carries the failure (recoveryRequired).
@@ -507,6 +589,7 @@ export class BackgroundJobRegistry {
 							kind: 'monitor' as const,
 							description: monitor.description,
 							expiresAt: startedAt + monitor.timeoutMs,
+							...(params.monitor?.transport ? { transport: params.monitor.transport } : {}),
 						}
 					: {}),
 			},
@@ -673,12 +756,31 @@ export class BackgroundJobRegistry {
 		// Nothing follows a terminal notice. A command that ignores SIGTERM keeps
 		// printing until the SIGKILL, and those lines would reach the model after
 		// it was told the watch was over.
+		monitor.sealed = true
 		monitor.stream.close()
 		void this.kill(entry.record.id).catch(() => {
 			// The retained record carries the failure (recoveryRequired).
 		})
 	}
 
+	/**
+	 * A notice from the source of a monitor (a WebSocket's upgrade was refused,
+	 * its connection closed). Delivered after whatever was already complete, so
+	 * the last lines are not overtaken by the news that the stream ended.
+	 */
+	private noticeFromSource(entry: JobEntry, text: string, final: boolean): void {
+		const monitor = entry.monitor
+		if (!monitor || monitor.sealed) return
+		monitor.stream.flush()
+		// The flush can itself have stopped the monitor for too much output.
+		if (monitor.sealed) return
+		this.announceMonitorEvent(entry, 'notice', text)
+		if (final) {
+			monitor.sealed = true
+			monitor.stream.close()
+		}
+	}
+
 	/**
 	 * Resolves once the job's process exists, or once it could not be
 	 * created (`error` then says why). Lets a caller report a start that
@@ -949,9 +1051,10 @@ export class BackgroundJobRegistry {
 		// out, and nothing the dying process prints afterwards does. (The expiry
 		// and output rules close it themselves, after their own notice.)
 		const closeStream = (): void => {
-			if (!stoppedBy) return
-			entry.monitor?.stream.flush()
-			entry.monitor?.stream.close()
+			if (!stoppedBy || !entry.monitor) return
+			entry.monitor.stream.flush()
+			entry.monitor.sealed = true
+			entry.monitor.stream.close()
 		}
 		if (entry.terminateProcess) {
 			entry.killRequested = true
@@ -1095,6 +1198,8 @@ export function bindOwner(
 			...(monitor ? { monitor } : {}),
 		})
 	}
+	const clampMonitorTimeout = (requested: number): number =>
+		Math.min(requested, defaults.monitorTimeoutCapMs ?? MONITOR_TIMEOUT_CAP_MS)
 	return {
 		start: (params: { command: string; workingDirectory?: string }) => launch(params),
 		// The same spawn, owner and cap as `start`, plus a deadline. The timeout
@@ -1106,14 +1211,35 @@ export function bindOwner(
 			timeoutMs: number
 			workingDirectory?: string
 		}) => {
-			const timeoutMs = Math.min(
-				params.timeoutMs,
-				defaults.monitorTimeoutCapMs ?? MONITOR_TIMEOUT_CAP_MS,
-			)
+			const timeoutMs = clampMonitorTimeout(params.timeoutMs)
 			const job = launch(params, { description: params.description, timeoutMs })
 			defaults.onMonitorStarted?.(job.id)
 			return { job, timeoutMs }
 		},
+		// A monitor whose source is a WebSocket connection the HOST process
+		// opens, whatever the sandbox spawn would have done with a command: the
+		// tool has already checked the address and the sandbox's network rule,
+		// and the socket is pinned to the addresses it checked. A separate
+		// method so a host that implements `startMonitor` for commands is not
+		// handed an input it never wrote code for.
+		startWebSocketMonitor: (params: {
+			description: string
+			timeoutMs: number
+			workingDirectory?: string
+			webSocket: MonitorWebSocketTarget
+		}) => {
+			const timeoutMs = clampMonitorTimeout(params.timeoutMs)
+			const { webSocket } = params
+			const job = registry.start({
+				owner,
+				command: webSocketJobCommand(webSocket.url),
+				workingDirectory: params.workingDirectory ?? defaults.workingDirectory ?? process.cwd(),
+				spawn: (host) => connectWebSocketSource({ target: webSocket, host }),
+				monitor: { description: params.description, timeoutMs, transport: 'websocket' },
+			})
+			defaults.onMonitorStarted?.(job.id)
+			return { job, timeoutMs }
+		},
 		// A foreground command that ran out of time, kept instead of killed.
 		// The same owner and cap as `start`; the process is the one already
 		// running, with what it has written so far.
@@ -1176,11 +1302,34 @@ export function bindOwner(
  * own, so the summary does not repeat it.
  */
 export function describeMonitorEnd(
-	job: Pick<BackgroundJob, 'description' | 'status' | 'exitCode' | 'signal' | 'error'>,
+	job: Pick<
+		BackgroundJob,
+		| 'description'
+		| 'status'
+		| 'exitCode'
+		| 'signal'
+		| 'error'
+		| 'transport'
+		| 'closeCode'
+		| 'closeReason'
+	>,
 	stats: Pick<MonitorStreamStats, 'stdoutChars'>,
 ): { status: 'completed' | 'failed' | 'killed'; summary: string } {
 	const label = `Monitor "${oneMetadataLine(job.description ?? 'unnamed')}"`
 	if (job.status === 'killed') return { status: 'killed', summary: `${label} stopped` }
+	if (job.transport === 'websocket') {
+		// A connection has no script to fail and no exit status to quote: it was
+		// closed, by the server and with a code, or it never opened.
+		if (job.closeCode === undefined)
+			return { status: 'failed', summary: `${label} connection failed` }
+		// The code only. The server's reason is text it chose, and the summary
+		// is a metadata line outside the untrusted frame; the reason reaches the
+		// model inside the frame, in the `[WebSocket closed: ...]` notice.
+		return {
+			status: job.exitCode === 0 ? 'completed' : 'failed',
+			summary: `${label} connection closed (${job.closeCode})`,
+		}
+	}
 	if (job.exitCode === 0 && job.error === undefined) {
 		return stats.stdoutChars > 0
 			? { status: 'completed', summary: `${label} stream ended` }