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.

6.2 KB
Raw Blame
/*
 * Agent3D embed SDK — Bridge v1
 * -----------------------------
 *   <script src="https://three.ws/embed-sdk.js"></script>
 *   const bridge = Agent3D.connect(iframeEl, {
 *     agentId,
 *     onReady,    // ({ version, capabilities, name }) => void
 *     onAction,   // (action) => void   — every protocol action the iframe emits
 *     onResize,   // (height) => void   — auto-applied to iframe unless autoResize:false
 *     onError,    // (err)    => void   — handshake timeout, blocked embed, etc.
 *     helloTimeoutMs:  8000,
 *     autoResize:      true,
 *     origin:          'https://three.ws',  // override iframe-origin detection
 *   });
 *   bridge.send({ type: 'speak', payload: { text: 'hello' } });
 *   bridge.ping().then(rttMs => …);
 *   bridge.destroy();
 *
 * Origin lockdown: connect() requires a resolvable iframe origin. Wildcard
 * targets ('*') are rejected, and inbound messages from any other origin or
 * window are dropped.
 *
 * Pre-ready queue: send() calls made before the handshake completes are
 * buffered and flushed automatically once agent:ready is received — no
 * messages are silently dropped.
 */
(function (root) {
	'use strict';
	if (root.Agent3D && root.Agent3D.connect) return;

	function connect(iframeEl, opts) {
		if (!iframeEl || iframeEl.tagName !== 'IFRAME') throw new Error('Agent3D.connect: iframe element required');
		if (!opts || !opts.agentId) throw new Error('Agent3D.connect: opts.agentId required');

		var agentId        = String(opts.agentId);
		var helloTimeoutMs = opts.helloTimeoutMs == null ? 8000 : opts.helloTimeoutMs;
		var autoResize     = opts.autoResize !== false;
		var iframeOrigin   = opts.origin || originOf(iframeEl.src);
		if (!iframeOrigin || iframeOrigin === 'null') {
			throw new Error('Agent3D.connect: iframe src must have a resolvable origin (set opts.origin explicitly for sandboxed iframes).');
		}
		if (iframeOrigin === '*') {
			throw new Error('Agent3D.connect: opts.origin cannot be "*"');
		}
		var pings          = Object.create(null);
		var nextPingId     = 1;
		var ready          = false;
		var destroyed      = false;
		var sendQueue      = [];
		var readyResolve, readyReject;
		var readyPromise   = new Promise(function (resolve, reject) { readyResolve = resolve; readyReject = reject; });

		function post(msg) {
			if (destroyed || !iframeEl.contentWindow) return;
			iframeEl.contentWindow.postMessage(msg, iframeOrigin);
		}

		function onMessage(ev) {
			if (destroyed) return;
			// Origin + window lock — drop messages from other windows or origins.
			if (ev.source !== iframeEl.contentWindow) return;
			if (ev.origin !== iframeOrigin) return;
			var msg = ev.data;
			if (!msg || typeof msg !== 'object' || msg.agentId !== agentId) return;
			switch (msg.type) {
				case 'agent:ready':
					if (!ready) {
						ready = true;
						readyResolve({ version: msg.version, capabilities: msg.capabilities || [], name: msg.name });
						if (typeof opts.onReady === 'function') {
							try { opts.onReady({ version: msg.version, capabilities: msg.capabilities || [], name: msg.name }); }
							catch (e) { console.error('[Agent3D] onReady threw', e); }
						}
						// Drain pre-ready queue — messages sent before handshake completed.
						while (sendQueue.length) post(sendQueue.shift());
					}
					return;
				case 'agent:action':
					if (typeof opts.onAction === 'function') {
						try { opts.onAction(msg.action); } catch (e) { console.error('[Agent3D] onAction threw', e); }
					}
					return;
				case 'agent:resize':
					if (autoResize && typeof msg.height === 'number' && msg.height > 0) {
						iframeEl.style.height = msg.height + 'px';
					}
					if (typeof opts.onResize === 'function') {
						try { opts.onResize(msg.height); } catch (e) { console.error('[Agent3D] onResize threw', e); }
					}
					return;
				case 'agent:pong':
					var pending = pings[msg.id];
					if (pending) { delete pings[msg.id]; pending.resolve(Date.now() - pending.t); }
					return;
				case 'agent:blocked':
					emitError(new Error('Embed blocked by agent policy'));
					return;
			}
		}

		function emitError(err) {
			if (typeof opts.onError === 'function') {
				try { opts.onError(err); } catch (e) { console.error('[Agent3D] onError threw', e); }
			}
			if (!ready) readyReject(err);
		}

		function sendHello() { post({ type: 'agent:hello', agentId: agentId, host: location.origin }); }

		window.addEventListener('message', onMessage);

		// Send hello on every load — also on first attach if the iframe was
		// already loaded before connect() ran (common when the host hydrates
		// after the iframe).
		iframeEl.addEventListener('load', sendHello);
		if (iframeEl.contentDocument && iframeEl.contentDocument.readyState === 'complete') sendHello();
		// Belt-and-braces: hosts that miss the load event still get a hello.
		setTimeout(sendHello, 50);

		var helloTimer = helloTimeoutMs > 0 ? setTimeout(function () {
			if (!ready) emitError(new Error('agent:ready not received within ' + helloTimeoutMs + 'ms'));
		}, helloTimeoutMs) : null;

		readyPromise.finally(function () { if (helloTimer) clearTimeout(helloTimer); });

		return {
			ready: readyPromise,
			origin: iframeOrigin,
			send: function (action) {
				var msg = { type: 'agent:action', agentId: agentId, action: action };
				if (!ready) { sendQueue.push(msg); return; }
				post(msg);
			},
			ping: function (timeoutMs) {
				var id = String(nextPingId++);
				return new Promise(function (resolve, reject) {
					pings[id] = { t: Date.now(), resolve: resolve };
					post({ type: 'agent:ping', agentId: agentId, id: id });
					setTimeout(function () {
						if (pings[id]) { delete pings[id]; reject(new Error('ping timeout')); }
					}, timeoutMs || 2000);
				});
			},
			destroy: function () {
				destroyed = true;
				sendQueue = [];
				window.removeEventListener('message', onMessage);
				iframeEl.removeEventListener('load', sendHello);
				if (helloTimer) clearTimeout(helloTimer);
			},
		};
	}

	function originOf(url) {
		if (!url) return '';
		try { return new URL(url, typeof location !== 'undefined' ? location.href : undefined).origin; } catch (_) { return ''; }
	}

	root.Agent3D = { connect: connect, version: '1', originOf: originOf };
})(typeof window !== 'undefined' ? window : globalThis);