@roj-ai/sdk 0.1.36 → 0.2.1

package/src/bun-platform/shell.ts

@@ -0,0 +1,362 @@
+/**
+ * Bun/Node ShellRunner — spawns one command line and buffers what it prints.
+ *
+ * Confinement is `paths`: bubblewrap mounts exactly the paths the caller
+ * granted, at the location the caller says the command sees them.
+ */
+
+import type { ChildProcess } from 'node:child_process'
+import { resolve } from 'node:path'
+import type { ProcessRunner, ShellGrant, ShellLimits, ShellRunner, ShellRunOptions, ShellRunResult } from '../platform/index.js'
+import { createBunProcessRunner } from './process.js'
+
+/** Maximum output size per stream in bytes (1 MB) */
+const MAX_OUTPUT_BYTES = 1_048_576
+
+/** Default cap on what a confined command may write (200 MB). */
+const DEFAULT_FILE_SIZE_BYTES = 209_715_200
+
+/** Default process cap. Namespace-local only on Linux 5.14+; older kernels count per host uid. */
+const DEFAULT_PROCESSES = 64
+
+/** POSIX counts `ulimit -f` in 512-byte blocks; a shell counting 1024 caps at twice the request. */
+const FILE_SIZE_BLOCK_BYTES = 512
+
+/** Marks a limit the shell refused, so the host hears about it and the agent's stderr stays clean */
+const LIMIT_NOTICE_PREFIX = 'roj-shell: limit unavailable:'
+
+const reportedLimits = new Set<string>()
+
+/** Grace period before SIGKILL after SIGTERM (ms) */
+const GRACEFUL_KILL_DELAY_MS = 5000
+
+/** Host environment a command inherits; everything else stays out of it. */
+const SAFE_ENV_VARS = ['PATH', 'HOME', 'USER', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ']
+
+function getSafeEnv(): Record<string, string> {
+	return Object.fromEntries(
+		SAFE_ENV_VARS
+			.filter(key => process.env[key])
+			.map(key => [key, process.env[key]!]),
+	)
+}
+
+/** A command the host could not run, carrying whatever it managed to observe. */
+class ShellRunFailure extends Error {
+	constructor(message: string, readonly details: Record<string, unknown>) {
+		super(message)
+		this.name = 'ShellRunFailure'
+	}
+}
+
+export interface BwrapOptions {
+	/** Command line to run inside the sandbox. */
+	command: string
+	/** Working directory, as the command sees it. */
+	cwd: string
+	/** What the command may reach; mounted in the order given. */
+	grants?: readonly ShellGrant[]
+	/** Allow network access (default: false) */
+	network?: boolean
+}
+
+export function buildBwrapArgs(opts: BwrapOptions): string[] {
+	const args: string[] = [
+		'--ro-bind',
+		'/',
+		'/',
+		'--dev',
+		'/dev',
+		'--proc',
+		'/proc',
+		'--tmpfs',
+		'/tmp',
+	]
+
+	// Overrides --ro-bind / / for these paths, keeping user home dirs and root out of reach
+	args.push('--tmpfs', '/home')
+	args.push('--tmpfs', '/root')
+
+	for (const grant of opts.grants ?? []) {
+		args.push(grant.mode === 'ro' ? '--ro-bind' : '--bind', resolve(grant.source ?? grant.path), grant.path)
+	}
+
+	args.push('--unshare-all')
+
+	if (opts.network) {
+		args.push('--share-net')
+	}
+
+	args.push('--die-with-parent')
+
+	// Set working directory inside the namespace
+	args.push('--chdir', opts.cwd)
+
+	args.push('/bin/sh', '-c', opts.command)
+
+	return args
+}
+
+/**
+ * Resource limits for a confined command, one statement at a time: dash fails a single
+ * `ulimit` call carrying several flags, and spells the process cap `-p`, not `-u`.
+ * `-v` and `-t` stay unset; the shell port documents why.
+ */
+export function buildLimitPrefix(limits: ShellLimits = {}): string {
+	const fileSizeBytes = limits.fileSizeBytes === undefined ? DEFAULT_FILE_SIZE_BYTES : limits.fileSizeBytes
+	const processes = limits.processes === undefined ? DEFAULT_PROCESSES : limits.processes
+	const statements: [string, string][] = []
+	if (fileSizeBytes !== null) {
+		statements.push(['file size', `ulimit -f ${Math.ceil(fileSizeBytes / FILE_SIZE_BLOCK_BYTES)}`])
+	}
+	if (processes !== null) {
+		statements.push(['process count', `{ ulimit -u ${processes} 2>/dev/null || ulimit -p ${processes} 2>/dev/null; }`])
+	}
+	return statements
+		.map(([name, attempt]) => `${attempt} || echo '${LIMIT_NOTICE_PREFIX} ${name}' >&2`)
+		.join('\n')
+}
+
+/** Every limit turned off leaves no prefix, and the command must not gain a blank first line. */
+function prefixCommand(prefix: string, command: string): string {
+	return prefix === '' ? command : `${prefix}\n${command}`
+}
+
+/** Split the notices the prefix wrote from the command's own stderr. */
+export function splitLimitNotices(stderr: string): { stderr: string; unavailable: string[] } {
+	const unavailable: string[] = []
+	const lines = stderr.split('\n')
+	let index = 0
+	while (index < lines.length && lines[index].startsWith(LIMIT_NOTICE_PREFIX)) {
+		unavailable.push(lines[index].slice(LIMIT_NOTICE_PREFIX.length).trim())
+		index++
+	}
+	return { stderr: lines.slice(index).join('\n'), unavailable }
+}
+
+function reportUnavailableLimits(names: string[], warn: (message: string) => void): void {
+	for (const name of names) {
+		if (reportedLimits.has(name)) continue
+		reportedLimits.add(name)
+		warn(`shell: this shell applies no ${name} limit; commands run without it`)
+	}
+}
+
+/** Host directory the bwrap process itself starts from; the namespace has its own cwd. */
+function hostStartDir(options: ShellRunOptions): string | undefined {
+	const first = options.grants?.[0]
+	return first ? first.source ?? first.path : undefined
+}
+
+function runCommand(
+	processRunner: ProcessRunner,
+	options: ShellRunOptions,
+	warn: (message: string) => void,
+): Promise<ShellRunResult> {
+	// The grants are the confinement request: without them the command runs unconfined.
+	const confined = options.grants !== undefined
+	const startTime = Date.now()
+
+	return new Promise<ShellRunResult>((settleResult, failResult) => {
+		let stdout = ''
+		let stderr = ''
+		let timedOut = false
+		let processClosed = false
+		let processError: Error | undefined
+		let exitCode: number | null = null
+		let exitSignal: NodeJS.Signals | null = null
+		let stdinSettled = options.stdin === undefined
+		let stdinError: Error | undefined
+		let settled = false
+
+		const env = { ...getSafeEnv(), ...options.env }
+
+		let child: ChildProcess
+		if (confined) {
+			// The prefix runs in the command's own shell: wrap it in a subshell and it limits nothing.
+			const bwrapArgs = buildBwrapArgs({
+				command: prefixCommand(buildLimitPrefix(options.limits), options.command),
+				cwd: options.cwd,
+				grants: options.grants,
+				network: options.network,
+			})
+			child = processRunner.spawn('bwrap', bwrapArgs, {
+				cwd: hostStartDir(options),
+				env,
+				detached: true,
+			})
+		} else {
+			const shell = options.shell ?? (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh')
+			const shellFlag = process.platform === 'win32' ? '/c' : '-c'
+
+			child = processRunner.spawn(shell, [shellFlag, options.command], {
+				cwd: options.cwd,
+				env,
+				detached: true,
+			})
+		}
+
+		// Collect stdout with size cap
+		let stdoutBytes = 0
+		let stdoutTruncated = false
+		child.stdout?.on('data', (data: Buffer) => {
+			if (stdoutTruncated) return
+			const remaining = MAX_OUTPUT_BYTES - stdoutBytes
+			if (data.length > remaining) {
+				stdout += data.toString('utf-8', 0, remaining)
+				stdoutBytes = MAX_OUTPUT_BYTES
+				stdoutTruncated = true
+				stdout += '\n[stdout truncated at 1 MB]'
+			} else {
+				stdout += data.toString()
+				stdoutBytes += data.length
+			}
+		})
+
+		// Collect stderr with size cap
+		let stderrBytes = 0
+		let stderrTruncated = false
+		child.stderr?.on('data', (data: Buffer) => {
+			if (stderrTruncated) return
+			const remaining = MAX_OUTPUT_BYTES - stderrBytes
+			if (data.length > remaining) {
+				stderr += data.toString('utf-8', 0, remaining)
+				stderrBytes = MAX_OUTPUT_BYTES
+				stderrTruncated = true
+				stderr += '\n[stderr truncated at 1 MB]'
+			} else {
+				stderr += data.toString()
+				stderrBytes += data.length
+			}
+		})
+
+		// Timeout handler — SIGTERM first, then SIGKILL after grace period
+		let killTimeoutId: ReturnType<typeof setTimeout> | undefined
+		const clearTimers = () => {
+			clearTimeout(timeoutId)
+			if (killTimeoutId) clearTimeout(killTimeoutId)
+		}
+		const finishExecution = () => {
+			if (settled) return
+			if (!processClosed) return
+
+			const durationMs = Date.now() - startTime
+			if (processError) {
+				settled = true
+				clearTimers()
+				failResult(new ShellRunFailure(`Failed to execute command: ${processError.message}`, { durationMs }))
+				return
+			}
+
+			if (!stdinSettled) return
+
+			settled = true
+			clearTimers()
+			const notices = splitLimitNotices(stderr)
+			reportUnavailableLimits(notices.unavailable, warn)
+			const commandStderr = notices.stderr.trim()
+			if (stdinError) {
+				failResult(new ShellRunFailure(`Failed to deliver command stdin: ${stdinError.message}`, {
+					stdout: stdout.trim(),
+					stderr: commandStderr,
+					durationMs,
+					exitCode: exitCode ?? -1,
+					signal: exitSignal ?? undefined,
+					timedOut,
+				}))
+				return
+			}
+
+			settleResult({
+				stdout: stdout.trim(),
+				stderr: commandStderr,
+				exitCode: exitCode ?? -1,
+				signal: exitSignal ?? undefined,
+				timedOut,
+				truncated: stdoutTruncated || stderrTruncated,
+			})
+		}
+		const timeoutId = setTimeout(() => {
+			timedOut = true
+			try {
+				process.kill(-child.pid!, 'SIGTERM')
+			} catch {
+				child.kill('SIGTERM')
+			}
+			killTimeoutId = setTimeout(() => {
+				try {
+					process.kill(-child.pid!, 'SIGKILL')
+				} catch {
+					try {
+						child.kill('SIGKILL')
+					} catch { /* already dead */ }
+				}
+			}, GRACEFUL_KILL_DELAY_MS)
+		}, options.timeoutMs)
+
+		// Process exit
+		child.on('close', (code, signal) => {
+			processClosed = true
+			exitCode = code
+			exitSignal = signal
+			if (options.stdin !== undefined && !stdinSettled) {
+				if (child.stdin?.writableFinished) {
+					stdinSettled = true
+				} else {
+					stdinError = new Error('child process closed before accepting all stdin input')
+					stdinSettled = true
+				}
+			}
+			finishExecution()
+		})
+
+		// Process error
+		child.on('error', (error) => {
+			processError = error
+			finishExecution()
+		})
+
+		// A failed stdin write must not be hidden by a successful process exit.
+		if (options.stdin !== undefined) {
+			if (!child.stdin) {
+				stdinError = new Error('child process stdin is unavailable')
+				stdinSettled = true
+			} else {
+				child.stdin.once('finish', () => {
+					if (stdinSettled) return
+					stdinSettled = true
+					finishExecution()
+				})
+				child.stdin.on('error', (error) => {
+					if (stdinSettled) return
+					stdinError = error
+					stdinSettled = true
+					finishExecution()
+				})
+				child.stdin.once('close', () => {
+					if (stdinSettled) return
+					stdinError = new Error('child process stdin closed before accepting all input')
+					stdinSettled = true
+					finishExecution()
+				})
+				child.stdin.end(options.stdin)
+			}
+		} else {
+			// Keep late pipe errors contained when no input delivery was requested.
+			child.stdin?.on('error', () => {})
+			child.stdin?.end()
+		}
+		finishExecution()
+	})
+}
+
+export function createBunShellRunner(
+	processRunner: ProcessRunner = createBunProcessRunner(),
+	/** Where a limit this shell refused is reported; the command's own stderr never carries it. */
+	warn: (message: string) => void = (message) => console.warn(message),
+): ShellRunner {
+	return {
+		confinement: 'paths',
+		run: (options) => runCommand(processRunner, options, warn),
+	}
+}

package/src/config.ts

@@ -4,6 +4,7 @@
 
 import { resolve } from 'node:path'
 import type { MockInferenceHandler } from './core/llm/mock.js'
+import type { ArchiveLimitOverrides } from './lib/archive/index.js'
 import type { LogLevel } from './lib/logger/logger.js'
 
 /**
@@ -33,6 +34,27 @@ export interface Config {
 	/** Max concurrent vision LLM calls when classifying uploaded images. Default 10. */
 	imageClassifierConcurrency?: number
 
+	/**
+	 * Hosts that `upload-from-url` and `inject-resource` may reach even though
+	 * they land in a range the fetch guard blocks (loopback, RFC1918,
+	 * link-local) — e.g. an internal object store. Absent blocks all of them.
+	 *
+	 * Entries are `host` or `host:port` (`[::1]` / `[::1]:9000` for IPv6). A
+	 * bare host opens every port on it, so pin the port unless you mean that.
+	 */
+	remoteFetchAllowedHosts?: readonly string[]
+
+	/** Aggregate limits across every ZIP nested in one attachment upload. */
+	uploadArchiveLimits?: ArchiveLimitOverrides
+	/** Per-archive limits for resource ZIP injection. */
+	resourceArchiveLimits?: ArchiveLimitOverrides
+	/**
+	 * Resident session idle timeout. Zero or absent disables runtime eviction.
+	 * `loadConfig()` leaves this unset unless SESSION_IDLE_TIMEOUT_MS is given —
+	 * each runtime picks its own default (standalone-server uses 10 minutes).
+	 */
+	sessionIdleTimeoutMs?: number
+
 	/**
 	 * Identity of the application embedding this SDK. Reported via `/status`
 	 * so platform health-checks can surface "what's actually running" in debug
@@ -65,6 +87,7 @@ export interface Config {
  * Load configuration from environment variables.
  */
 export const loadConfig = (): Config => {
+	const sessionIdleTimeout = process.env.SESSION_IDLE_TIMEOUT_MS
 	return {
 		port: parseInt(process.env.PORT ?? '2486', 10),
 		host: process.env.HOST ?? '0.0.0.0',
@@ -78,6 +101,15 @@ export const loadConfig = (): Config => {
 		imageClassifierConcurrency: process.env.IMAGE_CLASSIFIER_CONCURRENCY
 			? parseInt(process.env.IMAGE_CLASSIFIER_CONCURRENCY, 10)
 			: undefined,
+		remoteFetchAllowedHosts: hostListFromEnv('REMOTE_FETCH_ALLOWED_HOSTS'),
+		uploadArchiveLimits: archiveLimitsFromEnv('UPLOAD_ARCHIVE'),
+		resourceArchiveLimits: archiveLimitsFromEnv('RESOURCE_ARCHIVE'),
+		// Left undefined when unset: loadConfig() is a public export, so baking a
+		// default here silently switches eviction on for every embedder that calls it
+		// (sandbox-runtime among them). Runtimes that want eviction opt in themselves.
+		sessionIdleTimeoutMs: sessionIdleTimeout === undefined
+			? undefined
+			: sessionIdleTimeout.trim() === '' ? Number.NaN : Number(sessionIdleTimeout),
 		logLevel: (process.env.LOG_LEVEL ?? 'info') as LogLevel,
 		logFormat: (process.env.LOG_FORMAT ?? 'console') as 'console' | 'json',
 		workerUrl: process.env.WORKER_URL,
@@ -118,5 +150,103 @@ export const validateConfig = (config: Config): string[] => {
 		errors.push(`Invalid persistence type: ${config.persistence}`)
 	}
 
+	for (const host of config.remoteFetchAllowedHosts ?? []) {
+		// An entry the guard cannot parse silently never matches, leaving the fetch blocked.
+		if (parseAllowedHostEntry(host) === null) {
+			errors.push(`Invalid remoteFetchAllowedHosts entry: ${host}`)
+		}
+	}
+
+	validateArchiveLimitOverrides('uploadArchiveLimits', config.uploadArchiveLimits, errors)
+	validateArchiveLimitOverrides('resourceArchiveLimits', config.resourceArchiveLimits, errors)
+	if (config.sessionIdleTimeoutMs !== undefined && (!Number.isSafeInteger(config.sessionIdleTimeoutMs) || config.sessionIdleTimeoutMs < 0)) {
+		errors.push(`Invalid sessionIdleTimeoutMs: ${config.sessionIdleTimeoutMs}`)
+	}
+
 	return errors
 }
+
+/** One parsed `remoteFetchAllowedHosts` entry. `port` absent means the host is open on every port. */
+export interface AllowedHostEntry {
+	host: string
+	port?: number
+}
+
+/**
+ * Parse one `remoteFetchAllowedHosts` entry into the form the fetch guard matches.
+ *
+ * The guard compares against `URL.hostname`, so the entry is normalised the same
+ * way here — lowercased, IPv6 brackets dropped, trailing root dots stripped.
+ * Returns null for anything that could never match, which `validateConfig`
+ * reports rather than leaving as a silently dead entry.
+ */
+export const parseAllowedHostEntry = (raw: string): AllowedHostEntry | null => {
+	const entry = raw.trim().toLowerCase()
+	if (entry === '' || /[\s/]/.test(entry)) return null
+
+	const normalizeHostPart = (value: string): string | null => {
+		const host = value.replace(/\.+$/, '')
+		return host === '' || host.includes('[') || host.includes(']') ? null : host
+	}
+	const parsePort = (value: string): number | null => {
+		if (!/^\d{1,5}$/.test(value)) return null
+		const port = Number(value)
+		return port >= 1 && port <= 65535 ? port : null
+	}
+
+	if (entry.startsWith('[')) {
+		const close = entry.indexOf(']')
+		if (close === -1) return null
+		const host = normalizeHostPart(entry.slice(1, close))
+		const rest = entry.slice(close + 1)
+		if (host === null) return null
+		if (rest === '') return { host }
+		if (!rest.startsWith(':')) return null
+		const port = parsePort(rest.slice(1))
+		return port === null ? null : { host, port }
+	}
+
+	// An unbracketed IPv6 literal has several colons and carries no port.
+	const colon = entry.lastIndexOf(':')
+	if (colon !== -1 && entry.indexOf(':') === colon) {
+		const host = normalizeHostPart(entry.slice(0, colon))
+		const port = parsePort(entry.slice(colon + 1))
+		return host === null || port === null ? null : { host, port }
+	}
+
+	const host = normalizeHostPart(entry)
+	return host === null ? null : { host }
+}
+
+/** Split a comma-separated env var into entries, or undefined when it holds none. */
+function hostListFromEnv(name: string): readonly string[] | undefined {
+	const raw = process.env[name]
+	if (raw === undefined) return undefined
+	const hosts = raw.split(',').map(entry => entry.trim()).filter(entry => entry !== '')
+	return hosts.length > 0 ? hosts : undefined
+}
+
+function archiveLimitsFromEnv(prefix: 'UPLOAD_ARCHIVE' | 'RESOURCE_ARCHIVE'): ArchiveLimitOverrides | undefined {
+	const maxEntries = process.env[`${prefix}_MAX_ENTRIES`]
+	const maxTotalUncompressedSize = process.env[`${prefix}_MAX_UNCOMPRESSED_BYTES`]
+	if (maxEntries === undefined && maxTotalUncompressedSize === undefined) return undefined
+	return {
+		maxEntries: maxEntries === undefined ? undefined : parseInt(maxEntries, 10),
+		maxTotalUncompressedSize: maxTotalUncompressedSize === undefined
+			? undefined
+			: parseInt(maxTotalUncompressedSize, 10),
+	}
+}
+
+function validateArchiveLimitOverrides(
+	name: 'uploadArchiveLimits' | 'resourceArchiveLimits',
+	limits: ArchiveLimitOverrides | undefined,
+	errors: string[],
+): void {
+	if (!limits) return
+	for (const [field, value] of Object.entries(limits)) {
+		if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+			errors.push(`Invalid ${name}.${field}: ${value}`)
+		}
+	}
+}