@namzu/sdk 0.1.4-rc.3 → 0.1.4

package/src/sandbox/provider/local.ts

@@ -0,0 +1,478 @@
+import { execSync, spawn } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import {
+	readFile as fsReadFile,
+	writeFile as fsWriteFile,
+	mkdir,
+	rename,
+	rm,
+} from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+
+import {
+	SANDBOX_DEFAULT_TIMEOUT_MS,
+	SANDBOX_KILL_GRACE_MS,
+	SANDBOX_MAX_OUTPUT_BYTES,
+	SANDBOX_SAFE_ENV_KEYS,
+	SANDBOX_TEMP_DIR_PREFIX,
+} from '../../constants/sandbox/index.js'
+import type { SandboxId } from '../../types/ids/index.js'
+import type {
+	Sandbox,
+	SandboxCreateConfig,
+	SandboxEnvironment,
+	SandboxExecOptions,
+	SandboxExecResult,
+	SandboxProvider,
+	SandboxStatus,
+} from '../../types/sandbox/index.js'
+import { generateSandboxId } from '../../utils/id.js'
+import type { Logger } from '../../utils/logger.js'
+
+// ---------------------------------------------------------------------------
+// Path safety
+// ---------------------------------------------------------------------------
+
+function assertInsideSandbox(sandboxRoot: string, targetPath: string): string {
+	const resolved = resolve(sandboxRoot, targetPath)
+	const rel = relative(sandboxRoot, resolved)
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(`Path escapes sandbox: ${targetPath}`)
+	}
+	return resolved
+}
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+function detectEnvironment(): SandboxEnvironment {
+	const { platform } = process
+
+	if (platform === 'linux') {
+		try {
+			execSync('unshare --version', { stdio: 'ignore' })
+			return 'linux-namespace'
+		} catch {
+			// unshare not available
+		}
+	}
+
+	if (platform === 'darwin') {
+		try {
+			execSync('sandbox-exec -n no-network /usr/bin/true', { stdio: 'ignore' })
+			return 'macos-seatbelt'
+		} catch {
+			// sandbox-exec not available
+		}
+	}
+
+	return 'basic'
+}
+
+// ---------------------------------------------------------------------------
+// Seatbelt profile
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a path to its canonical form so seatbelt matches correctly.
+ * macOS symlinks like /var → /private/var must be resolved before use
+ * in SBPL rules, because the kernel evaluates real paths.
+ *
+ * Reference: Anthropic sandbox-runtime normalizePathForSandbox()
+ */
+function canonicalizePath(p: string): string {
+	try {
+		return realpathSync(p)
+	} catch {
+		// Path may not exist yet — resolve manually for known macOS symlinks
+		if (p.startsWith('/var/')) return `/private${p}`
+		if (p.startsWith('/tmp/')) return `/private${p}`
+		return p
+	}
+}
+
+/**
+ * Build a macOS seatbelt (SBPL) profile for sandbox isolation.
+ *
+ * Reference: Anthropic sandbox-runtime generateSandboxProfile()
+ * Key principle: (deny default) + explicit allows. Network always denied.
+ */
+function buildSeatbeltProfile(sandboxRoot: string): string {
+	const root = canonicalizePath(sandboxRoot)
+
+	return [
+		'(version 1)',
+		'(deny default)',
+
+		// --- Process lifecycle ---
+		'(allow process-exec)',
+		'(allow process-fork)',
+		'(allow process-info* (target same-sandbox))',
+		'(allow signal (target same-sandbox))',
+
+		// --- Sandbox workspace — full read/write ---
+		`(allow file-read* (subpath "${root}"))`,
+		`(allow file-write* (subpath "${root}"))`,
+
+		// --- Root path literal — dyld needs this for path resolution ---
+		'(allow file-read* (literal "/"))',
+
+		// --- System binaries and libraries (read-only) ---
+		'(allow file-read* (subpath "/usr/lib"))',
+		'(allow file-read* (subpath "/usr/bin"))',
+		'(allow file-read* (subpath "/bin"))',
+		'(allow file-read* (subpath "/sbin"))',
+		'(allow file-read* (subpath "/usr/sbin"))',
+		'(allow file-read* (subpath "/usr/share"))',
+		'(allow file-read* (subpath "/usr/local"))',
+
+		// --- macOS system frameworks and dyld shared cache ---
+		'(allow file-read* (subpath "/System"))',
+		'(allow file-read* (subpath "/Library/Frameworks"))',
+		'(allow file-read* (subpath "/private/var/db/dyld"))',
+		'(allow file-read* (subpath "/private/var/select"))',
+
+		// --- Device files ---
+		'(allow file-read* (subpath "/dev"))',
+		'(allow file-write* (literal "/dev/null"))',
+		'(allow file-ioctl (literal "/dev/null"))',
+		'(allow file-ioctl (literal "/dev/zero"))',
+		'(allow file-ioctl (literal "/dev/random"))',
+		'(allow file-ioctl (literal "/dev/urandom"))',
+		'(allow file-ioctl (literal "/dev/tty"))',
+
+		// --- Temp directories (canonical paths) ---
+		'(allow file-read* (subpath "/private/tmp"))',
+		'(allow file-read* (subpath "/private/var/tmp"))',
+		'(allow file-write* (subpath "/private/tmp"))',
+		'(allow file-write* (subpath "/private/var/tmp"))',
+
+		// --- File metadata — needed for realpath() traversal ---
+		'(allow file-read-metadata)',
+
+		// --- System info ---
+		'(allow sysctl-read)',
+		'(allow user-preference-read)',
+
+		// --- Mach IPC — essential services only ---
+		'(allow mach-lookup',
+		'  (global-name "com.apple.logd")',
+		'  (global-name "com.apple.system.logger")',
+		'  (global-name "com.apple.system.notification_center")',
+		'  (global-name "com.apple.system.opendirectoryd.libinfo")',
+		'  (global-name "com.apple.system.opendirectoryd.membership")',
+		'  (global-name "com.apple.bsd.dirhelper")',
+		'  (global-name "com.apple.SecurityServer")',
+		'  (global-name "com.apple.securityd.xpc")',
+		'  (global-name "com.apple.coreservices.launchservicesd")',
+		'  (global-name "com.apple.fonts")',
+		'  (global-name "com.apple.FontObjectsServer")',
+		'  (global-name "com.apple.lsd.mapdb")',
+		')',
+
+		// --- POSIX IPC ---
+		'(allow ipc-posix-shm)',
+		'(allow ipc-posix-sem)',
+
+		// --- Network — deny all ---
+		'(deny network*)',
+	].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Environment building
+// ---------------------------------------------------------------------------
+
+function buildSafeEnv(
+	configEnv?: Record<string, string>,
+	optsEnv?: Record<string, string>,
+): Record<string, string> {
+	const env: Record<string, string> = {}
+
+	for (const key of SANDBOX_SAFE_ENV_KEYS) {
+		const value = process.env[key]
+		if (value !== undefined) {
+			env[key] = value
+		}
+	}
+
+	if (configEnv) {
+		Object.assign(env, configEnv)
+	}
+	if (optsEnv) {
+		Object.assign(env, optsEnv)
+	}
+
+	return env
+}
+
+// ---------------------------------------------------------------------------
+// LocalSandbox
+// ---------------------------------------------------------------------------
+
+class LocalSandbox implements Sandbox {
+	readonly id: SandboxId
+	readonly rootDir: string
+	readonly environment: SandboxEnvironment
+
+	private _status: SandboxStatus
+	private readonly config: SandboxCreateConfig
+	private readonly log: Logger
+
+	get status(): SandboxStatus {
+		return this._status
+	}
+
+	constructor(
+		id: SandboxId,
+		rootDir: string,
+		environment: SandboxEnvironment,
+		config: SandboxCreateConfig,
+		log: Logger,
+	) {
+		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.info('Sandbox created', { rootDir, environment })
+	}
+
+	async exec(
+		command: string,
+		args: string[] = [],
+		opts?: SandboxExecOptions,
+	): Promise<SandboxExecResult> {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+
+		this._status = 'busy'
+		const startTime = Date.now()
+
+		const env = buildSafeEnv(this.config.env, opts?.env)
+		const timeout = opts?.timeout ?? this.config.timeoutMs ?? SANDBOX_DEFAULT_TIMEOUT_MS
+
+		const cwd = opts?.cwd ? assertInsideSandbox(this.rootDir, opts.cwd) : this.rootDir
+
+		const { spawnCommand, spawnArgs } = this.buildSpawnArgs(command, args)
+
+		this.log.debug('Executing command', { command, args, timeout, environment: this.environment })
+
+		const ac = new AbortController()
+		const timeoutId = setTimeout(() => ac.abort(), timeout)
+
+		try {
+			const result = await this.spawnProcess(spawnCommand, spawnArgs, cwd, env, ac)
+			return { ...result, durationMs: Date.now() - startTime }
+		} finally {
+			clearTimeout(timeoutId)
+			if ((this._status as SandboxStatus) !== 'destroyed') {
+				this._status = 'ready'
+			}
+		}
+	}
+
+	async writeFile(path: string, content: string | Buffer): Promise<void> {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+
+		const resolved = assertInsideSandbox(this.rootDir, path)
+		await mkdir(dirname(resolved), { recursive: true })
+
+		// Convention 8: Atomic write (write-tmp-rename)
+		const tmpPath = `${resolved}.tmp.${Date.now()}`
+		await fsWriteFile(tmpPath, content)
+		await rename(tmpPath, resolved)
+
+		this.log.debug('File written', { path: resolved })
+	}
+
+	async readFile(path: string): Promise<Buffer> {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+
+		const resolved = assertInsideSandbox(this.rootDir, path)
+		return fsReadFile(resolved)
+	}
+
+	async destroy(): Promise<void> {
+		if (this._status === 'destroyed') {
+			return
+		}
+
+		this._status = 'destroyed'
+		await rm(this.rootDir, { recursive: true, force: true })
+
+		this.log.info('Sandbox destroyed', { sandboxId: this.id })
+	}
+
+	// -----------------------------------------------------------------------
+	// Private helpers
+	// -----------------------------------------------------------------------
+
+	private buildSpawnArgs(
+		command: string,
+		args: string[],
+	): { spawnCommand: string; spawnArgs: string[] } {
+		switch (this.environment) {
+			case 'linux-namespace':
+				return {
+					spawnCommand: 'unshare',
+					spawnArgs: ['--mount', '--pid', '--fork', '--map-root-user', '--', command, ...args],
+				}
+
+			case 'macos-seatbelt': {
+				const profile = buildSeatbeltProfile(this.rootDir)
+				return {
+					spawnCommand: 'sandbox-exec',
+					spawnArgs: ['-p', profile, '--', command, ...args],
+				}
+			}
+
+			case 'basic': {
+				const limits: string[] = []
+
+				const memoryMb = this.config.memoryLimitMb
+				if (memoryMb !== undefined) {
+					const memoryKb = memoryMb * 1024
+					limits.push(`ulimit -v ${memoryKb}`)
+				}
+
+				const maxProcs = this.config.maxProcesses
+				if (maxProcs !== undefined) {
+					limits.push(`ulimit -u ${maxProcs}`)
+				}
+
+				if (limits.length > 0) {
+					const prefix = limits.join(' && ')
+					const fullCommand = `${prefix} && ${command} ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`
+					return {
+						spawnCommand: '/bin/sh',
+						spawnArgs: ['-c', fullCommand],
+					}
+				}
+
+				return { spawnCommand: command, spawnArgs: args }
+			}
+
+			default: {
+				const _exhaustive: never = this.environment
+				throw new Error(`Unknown sandbox environment: ${_exhaustive}`)
+			}
+		}
+	}
+
+	private spawnProcess(
+		command: string,
+		args: string[],
+		cwd: string,
+		env: Record<string, string>,
+		ac: AbortController,
+	): Promise<Omit<SandboxExecResult, 'durationMs'>> {
+		return new Promise((resolvePromise, rejectPromise) => {
+			let child: ReturnType<typeof spawn>
+			try {
+				child = spawn(command, args, {
+					cwd,
+					env,
+					stdio: ['pipe', 'pipe', 'pipe'],
+					signal: ac.signal,
+				})
+			} catch (err) {
+				rejectPromise(err)
+				return
+			}
+
+			let stdout = ''
+			let stderr = ''
+			let stdoutBytes = 0
+			let stderrBytes = 0
+			let timedOut = false
+
+			child.stdout?.on('data', (chunk: Buffer) => {
+				if (stdoutBytes < SANDBOX_MAX_OUTPUT_BYTES) {
+					const remaining = SANDBOX_MAX_OUTPUT_BYTES - stdoutBytes
+					stdout += chunk.subarray(0, remaining).toString('utf-8')
+				}
+				stdoutBytes += chunk.length
+			})
+
+			child.stderr?.on('data', (chunk: Buffer) => {
+				if (stderrBytes < SANDBOX_MAX_OUTPUT_BYTES) {
+					const remaining = SANDBOX_MAX_OUTPUT_BYTES - stderrBytes
+					stderr += chunk.subarray(0, remaining).toString('utf-8')
+				}
+				stderrBytes += chunk.length
+			})
+
+			child.on('error', (err: NodeJS.ErrnoException) => {
+				if (err.code === 'ABORT_ERR' || ac.signal.aborted) {
+					timedOut = true
+					// 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)
+					}
+					return
+				}
+				rejectPromise(err)
+			})
+
+			child.on('close', (code, signal) => {
+				resolvePromise({
+					exitCode: code ?? (timedOut ? 124 : 1),
+					stdout,
+					stderr,
+					signal: signal ?? undefined,
+					timedOut,
+				})
+			})
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// LocalSandboxProvider
+// ---------------------------------------------------------------------------
+
+export class LocalSandboxProvider implements SandboxProvider {
+	readonly id = 'local'
+	readonly name = 'Local Sandbox'
+	readonly environment: SandboxEnvironment
+
+	private readonly log: Logger
+
+	constructor(log: Logger) {
+		this.environment = detectEnvironment()
+		this.log = log.child({ component: 'LocalSandboxProvider' })
+
+		this.log.info('Initialized', { environment: this.environment })
+	}
+
+	async create(config?: SandboxCreateConfig): Promise<Sandbox> {
+		const id = generateSandboxId()
+
+		// mkdtemp is in node:fs/promises but requires an async import-style usage.
+		// We use the same pattern: create a unique dir under os.tmpdir().
+		const { mkdtemp } = await import('node:fs/promises')
+		const rawDir = await mkdtemp(join(tmpdir(), SANDBOX_TEMP_DIR_PREFIX))
+		// Canonicalize — macOS symlinks like /var → /private/var must be resolved
+		const rootDir = canonicalizePath(rawDir)
+
+		this.log.info('Creating sandbox', { sandboxId: id, rootDir })
+
+		return new LocalSandbox(id, rootDir, this.environment, config ?? {}, this.log)
+	}
+}

package/src/telemetry/attributes.ts

@@ -1,7 +1,7 @@
 export { GENAI, NAMZU } from '../constants/telemetry/index.js'
 
-export function agentSessionSpanName(agentName: string): string {
-	return `namzu.agent.session ${agentName}`
+export function agentRunSpanName(agentName: string): string {
+	return `namzu.agent.run ${agentName}`
 }
 
 export function agentIterationSpanName(iteration: number): string {

package/src/telemetry/metrics.ts

@@ -3,7 +3,7 @@ import { getMeter } from '../provider/telemetry/setup.js'
 export interface PlatformMetrics {
 	recordTokenUsage(model: string, inputTokens: number, outputTokens: number): void
 	recordToolCall(toolName: string, success: boolean): void
-	recordSessionDuration(status: string, durationSec: number): void
+	recordRunDuration(status: string, durationSec: number): void
 	recordLLMLatency(model: string, durationSec: number): void
 }
 
@@ -25,8 +25,8 @@ export function createPlatformMetrics(): PlatformMetrics {
 		unit: '{call}',
 	})
 
-	const sessionDurationHistogram = meter.createHistogram('namzu.session.duration', {
-		description: 'Agent session duration',
+	const runDurationHistogram = meter.createHistogram('namzu.run.duration', {
+		description: 'Agent run duration',
 		unit: 's',
 	})
 
@@ -54,9 +54,9 @@ export function createPlatformMetrics(): PlatformMetrics {
 			})
 		},
 
-		recordSessionDuration(status: string, durationSec: number): void {
-			sessionDurationHistogram.record(durationSec, {
-				'namzu.session.status': status,
+		recordRunDuration(status: string, durationSec: number): void {
+			runDurationHistogram.record(durationSec, {
+				'namzu.run.status': status,
 			})
 		},
 

package/src/tools/builtins/bash.ts

@@ -39,6 +39,37 @@ export const BashTool = defineTool({
 			}
 		}
 
+		// Sandbox-aware: route through sandbox.exec() when available
+		if (context.sandbox) {
+			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
+				timeout: input.timeout,
+				cwd: context.workingDirectory,
+				env: context.env,
+			})
+
+			if (result.timedOut) {
+				return {
+					success: false,
+					output: '',
+					error: `Command timed out after ${input.timeout}ms`,
+				}
+			}
+
+			const output = [
+				result.stdout ? `STDOUT:\n${result.stdout}` : '',
+				result.stderr ? `STDERR:\n${result.stderr}` : '',
+			]
+				.filter(Boolean)
+				.join('\n\n')
+
+			return {
+				success: result.exitCode === 0,
+				output: output || '(no output)',
+				data: { exitCode: result.exitCode, sandboxed: true },
+				error: result.exitCode !== 0 ? `Command exited with code ${result.exitCode}` : undefined,
+			}
+		}
+
 		const { stdout, stderr } = await execAsync(input.command, {
 			cwd: context.workingDirectory,
 			timeout: input.timeout,

package/src/tools/builtins/edit.ts

@@ -0,0 +1,118 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { z } from 'zod'
+import { defineTool } from '../defineTool.js'
+
+const inputSchema = z.object({
+	path: z.string().describe('Path to the file to edit'),
+	old_string: z
+		.string()
+		.describe('The exact string to find and replace. Must be unique in the file.'),
+	new_string: z.string().describe('The replacement string'),
+	replace_all: z
+		.boolean()
+		.default(false)
+		.describe('Replace all occurrences instead of just the first unique match'),
+})
+
+type EditInput = z.infer<typeof inputSchema>
+
+export const EditTool = defineTool({
+	name: 'edit',
+	description:
+		'Makes targeted edits to a file using exact string find-and-replace. The old_string must be unique in the file unless replace_all is true. Preserves file formatting and indentation.',
+	inputSchema,
+	category: 'filesystem',
+	permissions: ['file_write'],
+	readOnly: false,
+	destructive: false,
+	concurrencySafe: false,
+
+	async execute(input: EditInput, context) {
+		if (input.old_string === input.new_string) {
+			return {
+				success: false,
+				output: '',
+				error: 'old_string and new_string are identical — no change needed',
+			}
+		}
+
+		// Sandbox-aware: route through sandbox when available
+		if (context.sandbox) {
+			const buffer = await context.sandbox.readFile(input.path)
+			const content = buffer.toString('utf-8')
+
+			const result = applyEdit(content, input)
+			if (!result.success) {
+				return { success: false, output: '', error: result.error }
+			}
+
+			await context.sandbox.writeFile(input.path, result.content)
+			return {
+				success: true,
+				output: `Edited ${input.path}: ${result.replacements} replacement(s) [sandboxed]`,
+				data: { path: input.path, replacements: result.replacements, sandboxed: true },
+			}
+		}
+
+		const filePath = resolve(context.workingDirectory, input.path)
+		const content = await readFile(filePath, 'utf-8')
+
+		const result = applyEdit(content, input)
+		if (!result.success) {
+			return { success: false, output: '', error: result.error }
+		}
+
+		await writeFile(filePath, result.content, 'utf-8')
+		return {
+			success: true,
+			output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
+			data: { path: filePath, replacements: result.replacements },
+		}
+	},
+})
+
+function applyEdit(
+	content: string,
+	input: EditInput,
+): { success: true; content: string; replacements: number } | { success: false; error: string } {
+	if (!content.includes(input.old_string)) {
+		return {
+			success: false,
+			error:
+				'old_string not found in file. Make sure the string matches exactly, including whitespace and indentation.',
+		}
+	}
+
+	if (input.replace_all) {
+		const parts = content.split(input.old_string)
+		const replacements = parts.length - 1
+		return {
+			success: true,
+			content: parts.join(input.new_string),
+			replacements,
+		}
+	}
+
+	// Uniqueness check: old_string must appear exactly once
+	const firstIndex = content.indexOf(input.old_string)
+	const secondIndex = content.indexOf(input.old_string, firstIndex + 1)
+
+	if (secondIndex !== -1) {
+		const lineNumber = content.slice(0, firstIndex).split('\n').length
+		const secondLine = content.slice(0, secondIndex).split('\n').length
+		return {
+			success: false,
+			error: `old_string is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
+		}
+	}
+
+	return {
+		success: true,
+		content:
+			content.slice(0, firstIndex) +
+			input.new_string +
+			content.slice(firstIndex + input.old_string.length),
+		replacements: 1,
+	}
+}