Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

13.7 KB
Raw Blame
// The execution core: everything that happens around one program run, shared
// by the backends that run on a machine we control (local, docker) and by the
// runner inside the Cloud Run job (workers/sandbox-runner), so a script behaves
// the same everywhere.
//
//   materialize(dir, files)     write the workspace to disk
//   snapshot(dir) / changed()   find what the program created or modified
//   programFor(job, paths)      the argv for code in a language, or a terminal command
//   runProcess(opts)            spawn under resource limits, capture capped
//                               output, enforce wall time, sample CPU and memory
//   serveBridge(path, handle)   the local socket `three_ws.tool(...)` talks to
//
// Node builtins and ./paths.js only: the runner image copies this file as is.

import { spawn, spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs/promises';
import { readFileSync } from 'node:fs';
import net from 'node:net';
import path from 'node:path';

import { STATE_DIR } from './paths.js';

const CLOCK_TICKS = 100;
const SAMPLE_MS = 200;
// Output beyond this multiple of the cap is a flood: the program is killed
// instead of being allowed to spin writing into a buffer nobody reads.
const FLOOD_FACTOR = 8;
const MAX_BRIDGE_LINE = 8 * 1024 * 1024;

/** Write `[{ path, data }]` under dir. */
export async function materialize(dir, files) {
	await fs.mkdir(dir, { recursive: true });
	for (const f of files) {
		const abs = path.join(dir, f.path);
		if (!abs.startsWith(dir + path.sep)) throw new Error(`refusing to write outside the workspace: ${f.path}`);
		await fs.mkdir(path.dirname(abs), { recursive: true });
		await fs.writeFile(abs, f.data);
	}
}

/** Map of relative path → { size, hash } for every regular file under dir. Symlinks are skipped. */
export async function snapshot(dir) {
	const out = new Map();
	async function walk(abs, rel) {
		let entries;
		try {
			entries = await fs.readdir(abs, { withFileTypes: true });
		} catch (err) {
			if (err.code === 'ENOENT' || err.code === 'EACCES') return;
			throw err;
		}
		for (const ent of entries) {
			const a = path.join(abs, ent.name);
			const r = rel ? `${rel}/${ent.name}` : ent.name;
			if (ent.isDirectory()) await walk(a, r);
			else if (ent.isFile()) {
				const data = await fs.readFile(a);
				out.set(r, { size: data.length, hash: createHash('sha1').update(data).digest('hex') });
			}
		}
	}
	await walk(dir, '');
	return out;
}

/** Paths that are new or whose content changed between two snapshots, plus the ones deleted. */
export function changed(before, after) {
	const modified = [];
	for (const [p, meta] of after) {
		const prev = before.get(p);
		if (!prev || prev.hash !== meta.hash) modified.push({ path: p, size: meta.size });
	}
	const deleted = [...before.keys()].filter((p) => !after.has(p));
	return { modified, deleted };
}

/**
 * The bash program behind the `terminal` tool. The session (working directory
 * and exported variables) is restored from the workspace before the command
 * and saved back after it, so it persists across calls, executions and
 * backends: it lives in the workspace like any other file.
 * @param {string} command
 */
export function terminalScript(command) {
	return [
		'WS="$THREE_WS_WORKSPACE"',
		`mkdir -p "$WS/${STATE_DIR}"`,
		`if [ -f "$WS/${STATE_DIR}/terminal.env" ]; then . "$WS/${STATE_DIR}/terminal.env" 2>/dev/null; fi`,
		`__cwd=$(cat "$WS/${STATE_DIR}/terminal.cwd" 2>/dev/null || true)`,
		'cd "$WS/${__cwd:-.}" 2>/dev/null || cd "$WS"',
		'__three_ws_save() {',
		'  __rc=$?',
		'  case "$PWD" in "$WS") __rel=. ;; "$WS"/*) __rel="${PWD#"$WS"/}" ;; *) __rel=. ;; esac',
		`  printf '%s' "$__rel" > "$WS/${STATE_DIR}/terminal.cwd"`,
		`  export -p | grep -v -E '^(declare -x|export) (THREE_WS_[A-Z_]*|PWD|OLDPWD|SHLVL|_|HOME|PATH|PYTHONPATH|NODE_PATH|TMPDIR|MPLBACKEND|MPLCONFIGDIR|PYTHONUNBUFFERED)(=|$)' > "$WS/${STATE_DIR}/terminal.env" || true`,
		'  exit $__rc',
		'}',
		'trap __three_ws_save EXIT',
		command,
		'',
	].join('\n');
}

/** The file the program source is written to, per language. */
export const SOURCE_FILE = { python: 'main.py', javascript: 'main.mjs', bash: 'main.sh', terminal: 'terminal.sh' };

/**
 * argv for a job. `programPath` is where the source was written.
 * @param {{ kind: 'code'|'terminal', language?: string }} job
 * @param {{ programPath: string, memoryMb: number }} o
 */
export function programFor(job, { programPath, memoryMb }) {
	if (job.kind === 'terminal') return ['bash', programPath];
	switch (job.language) {
		case 'python':
			return ['python3', '-u', programPath];
		case 'javascript':
			return ['node', `--max-old-space-size=${Math.max(64, Math.floor(memoryMb * 0.75))}`, programPath];
		case 'bash':
			return ['bash', programPath];
		default:
			throw new Error(`unsupported language: ${job.language}`);
	}
}

let _prlimit;
function hasPrlimit() {
	if (_prlimit === undefined) {
		try {
			_prlimit = spawnSync('prlimit', ['--version'], { stdio: 'ignore' }).status === 0;
		} catch {
			_prlimit = false;
		}
	}
	return _prlimit;
}

/**
 * Wrap argv with kernel resource limits: CPU seconds, largest file, address
 * space (skipped for node, whose heap cap is --max-old-space-size and which
 * reserves far more address space than it uses), and optionally process count.
 */
export function withLimits(argv, { limits, nproc = null, language }) {
	const cpuSeconds = Math.ceil(limits.wallSeconds * limits.cpu) + 5;
	const asBytes = (limits.memoryMb * 2 + 512) * 1024 * 1024;
	const useAs = language !== 'javascript';
	if (hasPrlimit()) {
		const flags = [`--cpu=${cpuSeconds}`, `--fsize=${limits.fileBytes}`];
		if (useAs) flags.push(`--as=${asBytes}`);
		if (nproc) flags.push(`--nproc=${nproc}`);
		return ['prlimit', ...flags, '--', ...argv];
	}
	const lines = [`ulimit -t ${cpuSeconds} 2>/dev/null`, `ulimit -f ${Math.ceil(limits.fileBytes / 512)} 2>/dev/null`];
	if (useAs) lines.push(`ulimit -v ${Math.floor(asBytes / 1024)} 2>/dev/null`);
	if (nproc) lines.push(`ulimit -u ${nproc} 2>/dev/null`);
	return ['/bin/sh', '-c', `${lines.join('; ')}; exec "$@"`, 'sandbox', ...argv];
}

function sampleProc(pid) {
	try {
		const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
		const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
		const cpuMs = ((Number(fields[11]) + Number(fields[12])) * 1000) / CLOCK_TICKS;
		const status = readFileSync(`/proc/${pid}/status`, 'utf8');
		const hwm = /VmHWM:\s+(\d+)\s+kB/.exec(status);
		return { cpuMs, peakKb: hwm ? Number(hwm[1]) : 0 };
	} catch {
		return null;
	}
}

/** Keep the first 40% and the last 60% of a stream up to `cap` bytes. */
export class CappedBuffer {
	constructor(cap) {
		this.cap = cap;
		this.head = [];
		this.headBytes = 0;
		this.tail = Buffer.alloc(0);
		this.total = 0;
	}
	push(chunk) {
		this.total += chunk.length;
		const headRoom = Math.floor(this.cap * 0.4) - this.headBytes;
		if (headRoom > 0) {
			const take = chunk.subarray(0, headRoom);
			this.head.push(take);
			this.headBytes += take.length;
			chunk = chunk.subarray(take.length);
		}
		if (chunk.length) {
			const tailCap = this.cap - Math.floor(this.cap * 0.4);
			const joined = Buffer.concat([this.tail, chunk]);
			this.tail = joined.length > tailCap ? joined.subarray(joined.length - tailCap) : joined;
		}
	}
	result() {
		const head = Buffer.concat(this.head);
		const kept = head.length + this.tail.length;
		const truncated = this.total > kept;
		const text = truncated
			? `${head.toString()}\n[... ${this.total - kept} bytes omitted ...]\n${this.tail.toString()}`
			: Buffer.concat([head, this.tail]).toString();
		return { text, truncated, bytes: this.total };
	}
}

/**
 * Spawn a program under limits and wait for it.
 *
 * @param {object} o
 * @param {string[]} o.argv
 * @param {string} o.cwd
 * @param {Record<string,string>} o.env         the complete environment (nothing is inherited)
 * @param {object} o.limits                      from limitsFor()
 * @param {string} [o.language]
 * @param {number} [o.uid]                       drop to this uid (runner only)
 * @param {number} [o.gid]
 * @param {number} [o.nproc]
 * @param {AbortSignal} [o.signal]               kill switch
 * @returns {Promise<{ exitCode: number|null, signal: string|null, stdout: object, stderr: object,
 *   timedOut: boolean, killed: boolean, outputFlood: boolean, wallMs: number, cpuMs: number|null, peakMemoryMb: number|null }>}
 */
export function runProcess({ argv, cwd, env, limits, language, uid, gid, nproc, signal, hostLimits = true, onKill = null }) {
	// hostLimits=false: the argv is a launcher (the docker CLI) whose own limits
	// are enforced elsewhere; kernel rlimits on the launcher would only break it.
	const wrapped = hostLimits ? withLimits(argv, { limits, nproc, language }) : argv;
	const started = Date.now();
	return new Promise((resolve) => {
		const child = spawn(wrapped[0], wrapped.slice(1), {
			cwd,
			env,
			detached: true,
			stdio: ['ignore', 'pipe', 'pipe'],
			...(Number.isInteger(uid) ? { uid } : {}),
			...(Number.isInteger(gid) ? { gid } : {}),
		});
		const out = new CappedBuffer(limits.outputBytes);
		const err = new CappedBuffer(limits.outputBytes);
		let timedOut = false;
		let killed = false;
		let outputFlood = false;
		let cpuMs = null;
		let peakKb = 0;
		let done = false;

		const killTree = () => {
			if (onKill) Promise.resolve().then(onKill).catch(() => {});
			try {
				process.kill(-child.pid, 'SIGKILL');
			} catch {
				try {
					child.kill('SIGKILL');
				} catch {
					/* already gone */
				}
			}
		};
		const floodCheck = () => {
			if (!outputFlood && out.total + err.total > limits.outputBytes * FLOOD_FACTOR) {
				outputFlood = true;
				killTree();
			}
		};
		child.stdout.on('data', (c) => {
			out.push(c);
			floodCheck();
		});
		child.stderr.on('data', (c) => {
			err.push(c);
			floodCheck();
		});

		const wallTimer = setTimeout(() => {
			timedOut = true;
			killTree();
		}, limits.wallSeconds * 1000);
		const sampler = setInterval(() => {
			const s = child.pid ? sampleProc(child.pid) : null;
			if (s) {
				cpuMs = s.cpuMs;
				peakKb = Math.max(peakKb, s.peakKb);
			}
		}, SAMPLE_MS);
		const onAbort = () => {
			killed = true;
			killTree();
		};
		signal?.addEventListener('abort', onAbort, { once: true });

		const finish = (exitCode, sig, spawnError) => {
			if (done) return;
			done = true;
			clearTimeout(wallTimer);
			clearInterval(sampler);
			signal?.removeEventListener('abort', onAbort);
			if (spawnError) err.push(Buffer.from(`failed to start ${argv[0]}: ${spawnError.message}\n`));
			resolve({
				exitCode: spawnError ? 127 : exitCode,
				signal: sig,
				stdout: out.result(),
				stderr: err.result(),
				timedOut,
				killed,
				outputFlood,
				wallMs: Date.now() - started,
				cpuMs: cpuMs == null ? null : Math.round(cpuMs),
				peakMemoryMb: peakKb ? Math.round(peakKb / 1024) : null,
			});
		};
		child.on('error', (e) => finish(null, null, e));
		child.on('close', (code, sig) => finish(code, sig, null));
	});
}

/**
 * Speak the bridge protocol on one duplex stream: one JSON object per line in
 * each direction; requests carry an `id` the response echoes, so a client may
 * keep several calls in flight on one connection. Used for the local unix
 * socket and for a socket forwarded over ssh.
 * @param {import('node:stream').Duplex} conn
 * @param {(msg: object) => Promise<object>} handle  resolves to the response body
 */
export function handleBridgeStream(conn, handle) {
	let buf = '';
	conn.setEncoding?.('utf8');
	const send = (obj) => {
		if (!conn.destroyed) conn.write(`${JSON.stringify(obj)}\n`);
	};
	conn.on('data', (chunk) => {
		buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
		if (buf.length > MAX_BRIDGE_LINE) {
			buf = '';
			send({ ok: false, error: { code: 'too_large', message: 'bridge request larger than 8 MB' } });
			conn.end();
			return;
		}
		let nl;
		while ((nl = buf.indexOf('\n')) >= 0) {
			const line = buf.slice(0, nl);
			buf = buf.slice(nl + 1);
			if (!line.trim()) continue;
			let msg;
			try {
				msg = JSON.parse(line);
			} catch {
				send({ ok: false, error: { code: 'bad_json', message: 'bridge request is not JSON' } });
				continue;
			}
			Promise.resolve()
				.then(() => handle(msg))
				.catch((e) => ({ ok: false, error: { code: e?.code || 'bridge_error', message: String(e?.message || e).slice(0, 500) } }))
				.then((body) => send({ id: msg.id ?? null, ...body }));
		}
	});
	conn.on('error', () => {});
}

/**
 * Serve the bridge on a unix socket (see handleBridgeStream for the protocol).
 * @param {string} socketPath
 * @param {(msg: object) => Promise<object>} handle
 */
export async function serveBridge(socketPath, handle) {
	await fs.rm(socketPath, { force: true });
	const server = net.createServer((conn) => handleBridgeStream(conn, handle));
	await new Promise((resolve, reject) => {
		server.once('error', reject);
		server.listen(socketPath, resolve);
	});
	await fs.chmod(socketPath, 0o666);
	return {
		close: () =>
			new Promise((resolve) => {
				server.close(() => resolve());
				fs.rm(socketPath, { force: true }).catch(() => {});
			}),
	};
}

/**
 * The environment a sandboxed program sees. Nothing leaks in from the host:
 * no credentials, no cloud metadata variables, no API keys.
 */
export function programEnv({ workspace, socketPath, clientsDir, tmpDir, cpu, extra = {} }) {
	const threads = String(Math.max(1, cpu || 1));
	return {
		PATH: '/usr/local/bin:/usr/bin:/bin',
		HOME: workspace,
		LANG: 'C.UTF-8',
		LC_ALL: 'C.UTF-8',
		TMPDIR: tmpDir,
		THREE_WS_WORKSPACE: workspace,
		THREE_WS_SOCKET: socketPath,
		PYTHONPATH: path.join(clientsDir, 'python'),
		NODE_PATH: path.join(clientsDir, 'node'),
		PYTHONUNBUFFERED: '1',
		PYTHONDONTWRITEBYTECODE: '1',
		MPLBACKEND: 'Agg',
		MPLCONFIGDIR: path.join(tmpDir, 'mpl'),
		OPENBLAS_NUM_THREADS: threads,
		OMP_NUM_THREADS: threads,
		MKL_NUM_THREADS: threads,
		...extra,
	};
}