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.

4.3 KB
Raw Blame
// three_ws: call three.ws tools from inside a sandboxed script.
//
// Every call goes over the local bridge socket ($THREE_WS_SOCKET) to the agent
// runtime, which applies the same rules as a tool call made by the model: only
// tools the run may use, the policy tiers, and no fund-moving tool from inside
// a script (those need a preview and the user's confirmation in the chat).
//
/*
 *   import { tool, fetch } from 'three_ws';
 *   const price = await tool('token_price', { id: 'solana' });
 *   const r = await fetch('https://api.coingecko.com/api/v3/ping');
 *   console.log(r.status, await r.json());
 */
'use strict';

const net = require('node:net');

let nextId = 1;

// fetchJson's deadline when the caller passes no signal of its own. The run's
// wall-clock limit kills a stuck script eventually; this bounds one call.
const FETCH_JSON_TIMEOUT_MS = 30_000;

class BridgeError extends Error {
	constructor(code, message, detail) {
		super(`${code}: ${message}`);
		this.name = 'BridgeError';
		this.code = code;
		this.detail = detail || {};
	}
}

function call(payload, signal) {
	const socketPath = process.env.THREE_WS_SOCKET;
	if (!socketPath) {
		return Promise.reject(new BridgeError('no_bridge', 'THREE_WS_SOCKET is not set: this is not running inside a three.ws sandbox'));
	}
	if (signal?.aborted) return Promise.reject(new BridgeError('aborted', 'the call was aborted before it was sent'));
	return new Promise((resolve, reject) => {
		const conn = net.createConnection(socketPath);
		const onAbort = () => {
			conn.destroy();
			reject(new BridgeError('aborted', 'the call was aborted before the bridge answered'));
		};
		signal?.addEventListener('abort', onAbort, { once: true });
		conn.on('close', () => signal?.removeEventListener('abort', onAbort));
		let buf = '';
		conn.setEncoding('utf8');
		conn.on('connect', () => conn.write(`${JSON.stringify({ ...payload, id: nextId++ })}\n`));
		conn.on('data', (chunk) => {
			buf += chunk;
			const nl = buf.indexOf('\n');
			if (nl < 0) return;
			conn.end();
			let msg;
			try {
				msg = JSON.parse(buf.slice(0, nl));
			} catch {
				reject(new BridgeError('bad_response', 'the bridge answered with something that is not JSON'));
				return;
			}
			if (!msg.ok) {
				const err = msg.error || {};
				reject(new BridgeError(err.code || 'bridge_error', err.message || 'bridge call failed', err));
			} else resolve(msg.result);
		});
		conn.on('error', (e) => reject(new BridgeError('bridge_unreachable', e.message)));
		conn.on('end', () => {
			if (!buf.includes('\n')) reject(new BridgeError('bridge_closed', 'the bridge closed the connection without answering'));
		});
	});
}

/** Call a tool the run is allowed to use and resolve to its result. */
function tool(name, args) {
	return call({ op: 'tool', name, args: args || {} });
}

/** The tools this run may call: [{ name, description, tier }]. */
function tools() {
	return call({ op: 'tools' });
}

/**
 * HTTP through the bridge. Only hosts on the run's allowlist are reachable.
 * `init.signal` aborts the call, e.g. `{ signal: AbortSignal.timeout(5000) }`.
 */
async function fetch(url, init) {
	const opts = init || {};
	let body = opts.body;
	const headers = { ...(opts.headers || {}) };
	if (opts.json !== undefined) {
		body = JSON.stringify(opts.json);
		headers['content-type'] = 'application/json';
	}
	const bodyB64 = body == null ? null : Buffer.from(typeof body === 'string' ? body : body).toString('base64');
	const raw = await call({ op: 'fetch', url, method: opts.method || 'GET', headers, body_base64: bodyB64 }, opts.signal);
	const bytes = Buffer.from(raw.body_base64 || '', 'base64');
	return {
		status: raw.status,
		ok: raw.status >= 200 && raw.status < 300,
		url: raw.url,
		headers: raw.headers || {},
		bytes: async () => bytes,
		text: async () => bytes.toString('utf8'),
		json: async () => JSON.parse(bytes.toString('utf8')),
	};
}

/**
 * fetch() that rejects on a non-2xx status and resolves to the parsed JSON body.
 * Bounded by FETCH_JSON_TIMEOUT_MS unless `init.signal` says otherwise.
 */
async function fetchJson(url, init) {
	const r = await fetch(url, { signal: AbortSignal.timeout(FETCH_JSON_TIMEOUT_MS), ...init });
	if (!r.ok) throw new BridgeError('http_error', `${url} answered ${r.status}`, { status: r.status });
	return r.json();
}

module.exports = { tool, tools, fetch, fetchJson, BridgeError };