@namzu/sdk 27.1.0 → 28.0.0

package/src/execution/code-runtime/types.ts

@@ -0,0 +1,116 @@
+/**
+ * Running a program the MODEL wrote.
+ *
+ * A model that can write a loop can do in one call what currently costs
+ * twenty: filter a list, retry with backoff, fan out over files. Every one
+ * of those is a control-flow shape the tool loop expresses by taking a full
+ * model turn per step, at full context size, with the whole conversation
+ * resent each time.
+ *
+ * The problem is that the program is untrusted text. It is not "code the
+ * operator installed" — it is a string the model produced, possibly under
+ * the influence of a web page it was told to summarise. So the seam is
+ * defined here in terms of what a backend must GUARANTEE rather than what
+ * it may offer, and the guarantees are the interesting part:
+ *
+ *  - **No ambient capability.** The program gets what the host passes and
+ *    nothing else: no filesystem, no network, no process, no `require`. A
+ *    backend that cannot withhold those is not a backend for this.
+ *  - **Everything it can do, it does by asking.** The only channel out is a
+ *    call back into the host, which is what makes NZ-EXEC-06's dispatch
+ *    through the run's own `ToolRegistry` possible — the program cannot
+ *    reach a tool the run did not grant, because it cannot reach anything.
+ *  - **Bounded.** Wall clock and output, both enforced by the backend
+ *    rather than requested of the program.
+ *
+ * `internal and unexported` is the task's own wording and is kept: a seam
+ * with one backend and no consumer is a guess at what a consumer needs.
+ * NZ-EXEC-06 is the consumer, and the surface joins the public API in the
+ * commit that has one.
+ */
+
+/** A call the program made back into the host. */
+export interface HostCallRequest {
+	/** Which capability, by the name the host offered. */
+	readonly name: string
+	readonly input: unknown
+}
+
+export interface HostCallResult {
+	readonly ok: boolean
+	readonly value?: unknown
+	readonly error?: string
+}
+
+/**
+ * What the host will answer.
+ *
+ * A function rather than a table, so the host decides per call. NZ-EXEC-06
+ * makes this the run's `ToolRegistry` and its permission gate, which is
+ * exactly the point: the program's reach is the run's reach, resolved at
+ * the moment of the call rather than frozen when the program started.
+ */
+export type HostCallHandler = (request: HostCallRequest) => Promise<HostCallResult>
+
+export interface RunCodeOptions {
+	/** The program. Untrusted text, from the model. */
+	readonly source: string
+	/** Names the program may call. Anything else is refused by the backend. */
+	readonly allowedCalls: readonly string[]
+	readonly onHostCall: HostCallHandler
+	/** Hard wall clock. Enforced by the backend, not asked of the program. */
+	readonly timeoutMs: number
+	/**
+	 * Cap on what the program may print.
+	 *
+	 * Enforced, and truncation is REPORTED. A program whose output was cut
+	 * silently is a model reading a partial answer as a whole one — the same
+	 * rule the tool-output cap and the background-job buffer already follow.
+	 */
+	readonly maxOutputBytes: number
+	readonly signal?: AbortSignal
+}
+
+export type CodeRunOutcome =
+	| { readonly status: 'completed'; readonly result: unknown }
+	| { readonly status: 'failed'; readonly error: string }
+	| { readonly status: 'timed-out' }
+	| { readonly status: 'cancelled' }
+
+export interface CodeRunResult {
+	readonly outcome: CodeRunOutcome
+	/** Whatever the program printed, in order. */
+	readonly output: string
+	readonly outputTruncated: boolean
+	/** Every host call it made, in order, with what it got back. */
+	readonly calls: readonly {
+		readonly name: string
+		readonly ok: boolean
+	}[]
+}
+
+/**
+ * A backend that can run one of these.
+ *
+ * One method, deliberately. A backend with a `prepare`/`run`/`dispose`
+ * lifecycle invites a caller to reuse an instance across programs, and two
+ * model-authored programs sharing a runtime share whatever the first one
+ * left in it.
+ */
+export interface CodeRuntime {
+	readonly id: string
+	run(options: RunCodeOptions): Promise<CodeRunResult>
+}
+
+/** A program that asked for a capability it was not granted. */
+export class HostCallDeniedError extends Error {
+	readonly details: { name: string; allowed: readonly string[] }
+
+	constructor(details: { name: string; allowed: readonly string[] }) {
+		super(
+			`The program called "${details.name}", which it was not granted. Available: ${details.allowed.length > 0 ? details.allowed.join(', ') : '(none)'}`,
+		)
+		this.name = 'HostCallDeniedError'
+		this.details = details
+	}
+}

package/src/execution/code-runtime/worker.ts

@@ -0,0 +1,266 @@
+import { Worker } from 'node:worker_threads'
+
+import {
+	type CodeRunResult,
+	type CodeRuntime,
+	HostCallDeniedError,
+	type RunCodeOptions,
+} from './types.js'
+
+/**
+ * A `worker_threads` backend.
+ *
+ * Chosen over `vm` because `vm` is not a sandbox and its own documentation
+ * says so: a context shares the process, so a program that reaches a
+ * constructor from the host realm is out — `this.constructor.constructor`
+ * on any leaked object is the whole escape, and it fits in a tweet. A
+ * worker is a separate V8 isolate with its own heap; escaping it means
+ * escaping V8.
+ *
+ * Chosen over a subprocess because a subprocess is a process: it inherits
+ * an environment, it can be a fork bomb, and killing it is the process-tree
+ * problem `process/kill-tree.ts` exists for. A worker is cheaper to start,
+ * cheaper to kill, and cannot outlive the process that made it.
+ *
+ * What a worker does NOT give, stated because it is the reason this is not
+ * the whole answer: a worker shares the process's filesystem and network
+ * access. It is not confined by anything the OS enforces. What confines the
+ * program here is that it is handed a scope with nothing in it — no
+ * `require`, no `process`, no `fetch` — and a single channel back to the
+ * host. That is a language-level boundary, and a language-level boundary is
+ * exactly as strong as the enumeration of what was withheld. So a host that
+ * needs an OS boundary runs this inside a sandbox that has one, and this
+ * comment is here so nobody concludes the worker was the boundary.
+ */
+
+/**
+ * The worker's own body, as source.
+ *
+ * Inlined rather than a separate file because a separate file has to be
+ * findable at runtime, and this package is consumed as `dist/` by hosts
+ * whose bundlers rewrite paths. A string has no path.
+ */
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads')
+
+// Every host call is a request/response over the port, keyed by an id so
+// several can be in flight — a program that awaits two calls at once is
+// ordinary, and a channel that could only carry one would silently
+// serialise them.
+const pending = new Map()
+let nextId = 0
+
+function hostCall(name, input) {
+	const id = ++nextId
+	return new Promise((resolve, reject) => {
+		pending.set(id, { resolve, reject })
+		parentPort.postMessage({ kind: 'call', id, name, input })
+	})
+}
+
+// Posted as it happens, NOT batched until the end. A program that printed
+// its progress and then hung has told the host where it got to, and a
+// buffer that only ships on completion loses exactly the output a timeout
+// most needs to explain itself.
+function print(...parts) {
+	parentPort.postMessage({
+		kind: 'print',
+		line: parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(p))).join(' '),
+	})
+}
+
+parentPort.on('message', (message) => {
+	if (message.kind !== 'call-result') return
+	const entry = pending.get(message.id)
+	if (!entry) return
+	pending.delete(message.id)
+	if (message.ok) entry.resolve(message.value)
+	else entry.reject(new Error(message.error))
+})
+
+async function main() {
+	// The scope the program runs in, and everything it has. Built with
+	// \`new Function\` over an explicit parameter list rather than with
+	// \`with\` or a Proxy: the parameters SHADOW the outer names, so a
+	// program writing \`require\` gets the parameter, and the parameter is
+	// undefined.
+	const names = ['call', 'print', 'require', 'process', 'module', 'exports', 'globalThis', 'fetch']
+	const values = [hostCall, print, undefined, undefined, undefined, undefined, undefined, undefined]
+	const body = new Function(...names, '"use strict";return (async () => {' + workerData.source + '\\n})()')
+	return await body(...values)
+}
+
+main().then(
+	(result) => parentPort.postMessage({ kind: 'done', result }),
+	(error) => parentPort.postMessage({ kind: 'error', error: String(error && error.message || error) }),
+)
+`
+
+export class WorkerCodeRuntime implements CodeRuntime {
+	readonly id = 'worker_threads'
+
+	async run(options: RunCodeOptions): Promise<CodeRunResult> {
+		const allowed = new Set(options.allowedCalls)
+		const calls: { name: string; ok: boolean }[] = []
+		let output = ''
+		let truncated = false
+
+		const appendOutput = (lines: readonly string[]): void => {
+			for (const line of lines) {
+				if (truncated) return
+				const next = output.length === 0 ? line : `${output}\n${line}`
+				if (Buffer.byteLength(next) > options.maxOutputBytes) {
+					// Cut at the LINE that would exceed, and say so. A cut
+					// mid-JSON produces output a reader cannot parse and cannot
+					// tell was cut.
+					truncated = true
+					return
+				}
+				output = next
+			}
+		}
+
+		const worker = new Worker(WORKER_SOURCE, {
+			eval: true,
+			workerData: { source: options.source },
+			// Nothing from the host's environment.
+			//
+			// **Unobservable today, and kept deliberately.** `process` is
+			// shadowed in the program's scope, so nothing the program can
+			// write reaches `process.env` either way — a mutation removing
+			// this line passes every test, correctly. It is defence behind the
+			// shadowing rather than beside it: the shadowing is a
+			// language-level boundary, exactly as strong as the enumeration of
+			// what was withheld, and the day that enumeration misses something
+			// this is what the leak finds. The cost is one empty object.
+			env: {},
+			// No stdio inheritance: the program prints through `print`, which
+			// is bounded. A worker writing to the host's stdout would bypass
+			// the cap and interleave with the operator's own output.
+			stdout: true,
+			stderr: true,
+		})
+
+		return await new Promise<CodeRunResult>((resolve) => {
+			let settled = false
+			const finish = (result: CodeRunResult): void => {
+				// The Promise already ignores a second `resolve`, so removing
+				// this guard changes no result — a mutation removing it
+				// survives, correctly. It is kept because it also stops a
+				// second `terminate()` and a second `clearTimeout` on a worker
+				// that has already gone, and because `finish` is called from
+				// four places whose ordering is decided by the worker: `done`
+				// then `exit` is the ordinary sequence, not an edge case.
+				if (settled) return
+				settled = true
+				clearTimeout(deadline)
+				options.signal?.removeEventListener('abort', onAbort)
+				void worker.terminate()
+				resolve(result)
+			}
+
+			const deadline = setTimeout(() => {
+				finish({ outcome: { status: 'timed-out' }, output, outputTruncated: truncated, calls })
+			}, options.timeoutMs)
+
+			const onAbort = (): void => {
+				finish({ outcome: { status: 'cancelled' }, output, outputTruncated: truncated, calls })
+			}
+			options.signal?.addEventListener('abort', onAbort, { once: true })
+			if (options.signal?.aborted) {
+				onAbort()
+				return
+			}
+
+			worker.on('message', (message: Record<string, unknown>) => {
+				if (message.kind === 'call') {
+					const name = String(message.name)
+					const id = message.id
+					if (!allowed.has(name)) {
+						// Refused HERE, not in the worker. The allow-list lives on
+						// the host side because a check inside the worker is a
+						// check the program shares a heap with.
+						calls.push({ name, ok: false })
+						worker.postMessage({
+							kind: 'call-result',
+							id,
+							ok: false,
+							error: new HostCallDeniedError({ name, allowed: options.allowedCalls }).message,
+						})
+						return
+					}
+					void options
+						.onHostCall({ name, input: message.input })
+						.then((result) => {
+							calls.push({ name, ok: result.ok })
+							worker.postMessage({
+								kind: 'call-result',
+								id,
+								ok: result.ok,
+								value: result.value,
+								error: result.error,
+							})
+						})
+						.catch((err: unknown) => {
+							calls.push({ name, ok: false })
+							worker.postMessage({
+								kind: 'call-result',
+								id,
+								ok: false,
+								error: err instanceof Error ? err.message : String(err),
+							})
+						})
+					return
+				}
+
+				if (message.kind === 'print') {
+					appendOutput([String(message.line)])
+					return
+				}
+
+				if (message.kind === 'done') {
+					finish({
+						outcome: { status: 'completed', result: message.result },
+						output,
+						outputTruncated: truncated,
+						calls,
+					})
+					return
+				}
+
+				if (message.kind === 'error') {
+					finish({
+						outcome: { status: 'failed', error: String(message.error) },
+						output,
+						outputTruncated: truncated,
+						calls,
+					})
+				}
+			})
+
+			worker.on('error', (err) => {
+				// A worker that died before reporting anything. Its output is
+				// whatever it had already sent, which is nothing — reporting an
+				// empty string here is honest rather than a loss.
+				finish({
+					outcome: { status: 'failed', error: err.message },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
+			})
+
+			worker.on('exit', (code) => {
+				// Only reached when the worker exited without a `done` or
+				// `error` message — a hard crash, or a program that called
+				// `process.exit` through something we failed to withhold.
+				finish({
+					outcome: { status: 'failed', error: `The program exited with code ${code}.` },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
+			})
+		})
+	}
+}

package/src/{connector/execution → execution}/factory.ts

@@ -1,7 +1,7 @@
-import type { BaseExecutionContext } from '../../execution/base.js'
-import { LocalExecutionContext, type LocalExecutionContextOptions } from '../../execution/local.js'
-import type { ExecutionContextConfig } from '../../types/connector/index.js'
+import type { ExecutionContextConfig } from '../types/connector/index.js'
+import type { BaseExecutionContext } from './base.js'
 import { HybridExecutionContext, type HybridExecutionContextOptions } from './hybrid.js'
+import { LocalExecutionContext, type LocalExecutionContextOptions } from './local.js'
 import { RemoteExecutionContext, type RemoteExecutionContextOptions } from './remote.js'
 
 export class ExecutionContextFactory {

package/src/{connector/execution → execution}/hybrid.ts

@@ -1,5 +1,3 @@
-import { BaseExecutionContext } from '../../execution/base.js'
-import { LocalExecutionContext } from '../../execution/local.js'
 import type {
 	CommandExecutor,
 	CommandOptions,
@@ -9,7 +7,10 @@ import type {
 	ExecutionRoutingStrategy,
 	HybridExecutionContextConfig,
 	RemoteTarget,
-} from '../../types/connector/index.js'
+} from '../types/connector/index.js'
+import type { Logger } from '../utils/logger.js'
+import { BaseExecutionContext } from './base.js'
+import { LocalExecutionContext } from './local.js'
 import { RemoteExecutionContext } from './remote.js'
 
 export interface HybridExecutionContextOptions {
@@ -23,6 +24,7 @@ export interface HybridExecutionContextOptions {
 	}
 	remotes: RemoteTarget[]
 	routingStrategy?: ExecutionRoutingStrategy
+	log?: Logger
 }
 
 export class HybridExecutionContext extends BaseExecutionContext implements CommandExecutor {
@@ -36,7 +38,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 	private roundRobinIndex = 0
 
 	constructor(options: HybridExecutionContextOptions) {
-		super()
+		super(options.log)
 		this.id = options.id
 		this.remoteTargets = options.remotes
 		this.routingStrategy = options.routingStrategy ?? 'local-first'
@@ -48,6 +50,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 			envVars: options.local.envVars,
 			capabilities: options.local.capabilities,
 			shell: options.local.shell,
+			log: options.log,
 		})
 
 		this.localCtx.on((event) => this.emit(event))
@@ -57,6 +60,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 			const remote = new RemoteExecutionContext({
 				id: remoteId,
 				target,
+				log: options.log,
 			})
 			remote.on((event) => this.emit(event))
 			this.remoteCtxs.set(remoteId, remote)
@@ -72,9 +76,11 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 		}
 		await Promise.all(initPromises)
 
-		this.log.info(
-			`Hybrid context initialized: local(${this.localCtx.getCwd()}) + ${this.remoteCtxs.size} remote(s), strategy=${this.routingStrategy}`,
-		)
+		this.log.info('Hybrid context initialized', {
+			'namzu.execution.local_cwd': this.localCtx.getCwd(),
+			'namzu.execution.remote_count': this.remoteCtxs.size,
+			'namzu.execution.routing_strategy': this.routingStrategy,
+		})
 	}
 
 	protected async doTeardown(): Promise<void> {

package/src/execution/index.ts

@@ -1,3 +1,27 @@
+/**
+ * Where a tool call actually runs.
+ *
+ * One concept sat in two directories: the base and the local backend here,
+ * the remote, hybrid and factory under `connector/execution/`, with
+ * `connector/index.ts` reaching into both to reassemble one public export
+ * group. A contributor adding a fifth backend had no principled place to
+ * put it, and either answer was defensible from where they were standing.
+ *
+ * They are all here now, and the direction was not free. Folding this down
+ * into `connector/` was the other option and it is wrong: `run/command-gate.ts`
+ * imports `LocalExecutionContext` directly, so execution is not
+ * connector-scoped — a connector is one CALLER of an execution context, not
+ * the thing that defines one. `connector/index.ts` re-exports from here so
+ * no consumer's import path changes.
+ *
+ * A sixth backend goes in this directory and is named in this file.
+ */
+
 export { BaseExecutionContext } from './base.js'
+export { ExecutionContextFactory } from './factory.js'
+export { HybridExecutionContext } from './hybrid.js'
+export type { HybridExecutionContextOptions } from './hybrid.js'
 export { LocalExecutionContext } from './local.js'
 export type { LocalExecutionContextOptions } from './local.js'
+export { RemoteExecutionContext } from './remote.js'
+export type { RemoteExecutionContextOptions } from './remote.js'

package/src/execution/local.ts

@@ -9,6 +9,7 @@ import type {
 	ExecutionCapability,
 	ExecutionEnvironment,
 } from '../types/execution/index.js'
+import type { Logger } from '../utils/logger.js'
 import { BaseExecutionContext } from './base.js'
 
 export interface LocalExecutionContextOptions {
@@ -18,6 +19,7 @@ export interface LocalExecutionContextOptions {
 	envVars?: Record<string, string>
 	capabilities?: ExecutionCapability[]
 	shell?: string
+	log?: Logger
 }
 
 export class LocalExecutionContext extends BaseExecutionContext implements CommandExecutor {
@@ -31,7 +33,7 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 	private shell: string | undefined
 
 	constructor(options: LocalExecutionContextOptions) {
-		super()
+		super(options.log)
 		this.id = options.id
 		this.cwd = resolve(options.cwd)
 		this.fsAccess = options.fsAccess ?? true
@@ -44,7 +46,7 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 		if (!existsSync(this.cwd)) {
 			throw new Error(`Working directory does not exist: ${this.cwd}`)
 		}
-		this.log.info(`Local context initialized at ${this.cwd}`)
+		this.log.info('Local context initialized', { 'namzu.execution.cwd': this.cwd })
 	}
 
 	protected async doTeardown(): Promise<void> {}

package/src/{connector/execution → execution}/remote.ts

@@ -1,4 +1,3 @@
-import { BaseExecutionContext } from '../../execution/base.js'
 import type {
 	CommandOptions,
 	CommandResult,
@@ -7,13 +6,16 @@ import type {
 	RemoteCommandHandler,
 	RemoteExecutionContextConfig,
 	RemoteTarget,
-} from '../../types/connector/index.js'
+} from '../types/connector/index.js'
+import type { Logger } from '../utils/logger.js'
+import { BaseExecutionContext } from './base.js'
 
 export interface RemoteExecutionContextOptions {
 	id: string
 	target: RemoteTarget
 	capabilities?: ExecutionCapability[]
 	commandHandler?: RemoteCommandHandler
+	log?: Logger
 }
 
 export class RemoteExecutionContext extends BaseExecutionContext {
@@ -26,7 +28,7 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 	private commandHandler: RemoteCommandHandler | undefined
 
 	constructor(options: RemoteExecutionContextOptions) {
-		super()
+		super(options.log)
 		this.id = options.id
 		this.target = options.target
 		this.capabilities = options.capabilities ?? ['network']
@@ -35,7 +37,10 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 
 	protected async doInitialize(): Promise<void> {
 		this.validateTarget(this.target)
-		this.log.info(`Remote context initialized for ${this.target.type}://${this.target.host}`)
+		this.log.info('Remote context initialized', {
+			'namzu.execution.target_type': this.target.type,
+			'namzu.execution.target_host': this.target.host,
+		})
 	}
 
 	protected async doTeardown(): Promise<void> {
@@ -56,9 +61,11 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 			contextId: this.id,
 			target: this.target,
 		})
-		this.log.info(
-			`Remote connected: ${this.target.type}://${this.target.host}:${this.target.port ?? 'default'}`,
-		)
+		this.log.info('Remote connected', {
+			'namzu.execution.target_type': this.target.type,
+			'namzu.execution.target_host': this.target.host,
+			'namzu.execution.target_port': this.target.port ?? 'default',
+		})
 	}
 
 	async disconnect(): Promise<void> {
@@ -69,7 +76,7 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 			contextId: this.id,
 			host: this.target.host,
 		})
-		this.log.info(`Remote disconnected: ${this.target.host}`)
+		this.log.info('Remote disconnected', { 'namzu.execution.target_host': this.target.host })
 	}
 
 	isConnected(): boolean {

package/src/index.ts

@@ -9,3 +9,20 @@
 export type * from './public-types.js'
 export * from './public-runtime.js'
 export * from './public-tools.js'
+
+// Work that outlives a tool call, owned by whoever started it. The shell
+// cannot be trusted to background under the sandbox's PID namespace, so the
+// kernel holds the process itself. See `runtime/jobs/registry.ts`.
+export {
+	BackgroundJobLimitError,
+	BackgroundJobRegistry,
+	UnknownBackgroundJobError,
+	bindOwner,
+} from './runtime/jobs/registry.js'
+export type {
+	BackgroundJob,
+	BackgroundJobOutput,
+	BackgroundJobRegistryConfig,
+	BackgroundJobStatus,
+	StartJobParams,
+} from './runtime/jobs/registry.js'