@theprototype/agent 1.48.0 → 1.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@theprototype/agent",
-	"version": "1.48.0",
+	"version": "1.50.0",
 	"description": "Let an AI agent (Claude Code, Claude Desktop, any MCP host) join a theprototype.app session from its link and build the 3D scene with you.",
 	"type": "module",
 	"license": "MIT",
@@ -28,6 +28,7 @@
 	},
 	"files": [
 		"src/",
+		"catalog.json",
 		"README.md",
 		"LICENSE"
 	],
@@ -38,7 +39,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"test": "node test/messages.test.mjs && node test/bridge.test.mjs && node test/link.test.mjs && node test/mcp.test.mjs && node test/wire.test.mjs",
+		"test": "node test/chat.test.mjs && node test/messages.test.mjs && node test/bridge.test.mjs && node test/link.test.mjs && node test/mcp.test.mjs && node test/repl.test.mjs && node test/wire.test.mjs && node test/catalog.test.mjs",
 		"spike": "node src/spike.js",
 		"smoke": "node src/cli.js smoke",
 		"repl": "node src/cli.js repl",

package/src/browserEngine.js

@@ -237,6 +237,8 @@ export class BrowserEngine extends EventEmitter {
 			const ctx = await this.browser.newContext({ ignoreHTTPSErrors: this.insecure, viewport: { width: 1280, height: 720 } });
 			await ctx.addInitScript(agentStorage, { name: this.name, compat: this.compat });
 			if (this.compat) await ctx.addInitScript(compatShim);
+			// a diagnostic / test seam: one more init script in the agent page (the e2e gives it roles this way)
+			if (process.env.TP_AGENT_INIT_SCRIPT) await ctx.addInitScript({ path: process.env.TP_AGENT_INIT_SCRIPT });
 			this.page = await ctx.newPage();
 			this.page.on('pageerror', (/** @type {any} */ e) => this.log('page error: ' + firstLine(e)));
 			if (this.verbose) this.page.on('console', (/** @type {any} */ m) => this.log('console.' + m.type() + ': ' + m.text().slice(0, 300)));
@@ -317,6 +319,16 @@ export class BrowserEngine extends EventEmitter {
 		return joinedOf(await this.status(), this.hostId);
 	}
 
+	/**
+	 * 56: a chat method of tpAgent 1.1.0 (nextMessage, abortWait, requeue, reply, ask, chatStatus, thread).
+	 * @param {string} method @param {...any} args
+	 */
+	async chat(method, ...args) {
+		const r = await this.call(method, ...args);
+		if (r && r.__missing) throw new Error('this app build has no agent chat (tpAgent 1.1.0, theprototype 1.46+): people cannot type to you here');
+		return r;
+	}
+
 	/** @param {number} ms */
 	async waitForEdit(ms) {
 		const r = await this.call('waitForEdit', ms);

package/src/catalog.js

@@ -0,0 +1,114 @@
+// Roadmap 86 T4 (+ 56 C19) — THE STATIC TOOL CATALOG, one builder for every MCP surface that must list
+// tools before a page is up: the Claude connector's Worker (claude.ai reads tools/list ONCE, at chat
+// start, and ignores list_changed) and `serve --static-tools`. Pure: no SDK, no browser.
+//
+// The host half is whatever the app's `tpAgent.tools()` answers (core `scripts/agent-tool-catalog.mjs`
+// loads the app's own modules to get it), mapped by mcpTools.js exactly as a live session maps it, plus
+// the bridge tools a tab answers itself. Nobody hand-writes a tool. The instructions (86 T3) are built
+// from the same list, so a line about a tool appears only while that tool exists.
+
+import { mapHostTools, bridgeTools } from './mcpTools.js';
+
+/** Bump when the catalog's SHAPE changes (not when tools change). 2 = titles + annotations. */
+export const CATALOG_FORMAT = 2;
+
+/**
+ * Per tool: a human title, whether it only reads, and whether an edit may overwrite or remove what is
+ * there (MCP `destructiveHint`; false = only adds). The Claude connector directory requires a title and
+ * a read-only / destructive hint on EVERY tool. Everything an agent does is undoable, but the hints say
+ * what a call does, not whether it can be taken back. A tool missing here is treated as a destructive
+ * edit (fail closed) with a title made from its name.
+ */
+export const TOOL_ANNOTATIONS = /** @type {Record<string, {title: string, read?: true, destructive?: boolean, openWorld?: true}>} */ ({
+	list_scene: { title: 'Read the scene', read: true },
+	describe_node_types: { title: 'Look up flow node types', read: true },
+	what_can_you_do: { title: 'What can you do here', read: true },
+	status: { title: 'Session status', read: true },
+	screenshot: { title: 'Take a picture of the scene', read: true },
+	wait_for_edit: { title: 'Wait for someone to edit', read: true },
+	pending_offers: { title: 'List questions the app is asking', read: true },
+	create_objects: { title: 'Add objects', destructive: false },
+	create_flow_nodes: { title: 'Add behaviour (flow) nodes', destructive: false },
+	create_behaviour: { title: 'Add a code behaviour', destructive: false },
+	create_joints: { title: 'Add physics joints', destructive: false },
+	group_objects: { title: 'Group objects', destructive: false },
+	generate_mesh: { title: 'Generate a 3D model', destructive: false, openWorld: true },
+	update_objects: { title: 'Change objects', destructive: true },
+	update_flow_nodes: { title: 'Change or remove flow nodes', destructive: true },
+	edit_behaviour: { title: 'Edit a code behaviour', destructive: true },
+	set_physics: { title: 'Set physics', destructive: true },
+	control_simulation: { title: 'Run or stop the simulation', destructive: true },
+	delete_objects: { title: 'Delete objects', destructive: true },
+	clear_scene: { title: 'Clear the scene', destructive: true },
+	install_modules: { title: 'Install modules', destructive: false, openWorld: true },
+	accept_offer: { title: 'Answer a question the app asks', destructive: true },
+	connect: { title: 'Join a session', destructive: false, openWorld: true }
+});
+
+/** a title from a tool name: `create_objects` → `Create objects` @param {string} name */
+const titleOf = (name) => (name.charAt(0).toUpperCase() + name.slice(1)).replace(/_/g, ' ');
+
+/**
+ * A catalog tool with `title` + `annotations` (MCP 2025-06-18 shapes).
+ * @param {{name: string, description: string, inputSchema: any}} t
+ */
+export function annotate(t) {
+	const a = TOOL_ANNOTATIONS[t.name];
+	const title = a?.title ?? titleOf(t.name);
+	/** @type {Record<string, any>} */
+	const annotations = { title, readOnlyHint: !!a?.read };
+	if (!a?.read) annotations.destructiveHint = a?.destructive ?? true;
+	annotations.openWorldHint = !!a?.openWorld;
+	return { name: t.name, title, description: t.description, inputSchema: t.inputSchema, annotations };
+}
+
+/**
+ * The server instructions for a voice-first client (claude.ai chat, phone and voice mode). Short,
+ * spoken-style, and only about tools in `names`.
+ * @param {string[]} names the tool names the client will see
+ * @returns {string}
+ */
+export function connectorInstructions(names) {
+	const has = new Set(names);
+	const lines = [
+		'You are building in the person\'s own open theprototype.app tab: a live, shared 3D scene. Every change shows for everyone in the session and can be undone.',
+		'This may be a VOICE conversation: answer in one or two short spoken sentences and say what changed in plain words ("Added three trees by the fire"). Never read out uuids, lists of numbers or JSON.',
+		'If a tool says the tab is closed or not connected, tell the person to open theprototype.app and press Connect Claude, then wait; do not retry in a loop.'
+	];
+	if (has.has('status')) lines.push('Call status first: it says whether you may edit (a viewer can only look).');
+	if (has.has('list_scene')) lines.push('Call list_scene before editing so you use real uuids; batch many objects into one call.');
+	if (has.has('where_are_users'))
+		lines.push('For "in front of me", "here" or "this", call where_are_users and build at the spots it gives, facing the person.');
+	if (has.has('attach_to_user')) lines.push('For "give me a flashlight" or another prop, make the object, then attach_to_user to the person who asked.');
+	if (has.has('create_flow_nodes'))
+		lines.push(
+			'Motion and interaction are flow nodes (create_flow_nodes)' + (has.has('describe_node_types') ? '; call describe_node_types before wiring edges.' : '.')
+		);
+	if (has.has('screenshot')) lines.push('Use screenshot to check a result when it matters, not after every step.');
+	if (has.has('what_can_you_do')) lines.push('When asked what you can do here, call what_can_you_do and say its "say" line.');
+	return lines.join('\n');
+}
+
+/**
+ * Host tools (tpAgent.tools()'s shape) → the static catalog.
+ * @param {any[]} hostTools
+ * @param {{provenance?: Record<string, any>}} [opts]
+ * @returns {{format: number, generator: Record<string, any>, instructions: string, tools: {name: string, title: string, description: string, inputSchema: any, annotations: Record<string, any>}[]}}
+ */
+export function buildCatalog(hostTools, opts = {}) {
+	if (!Array.isArray(hostTools) || !hostTools.length) throw new Error('the host tool list is empty');
+	const mapped = mapHostTools(hostTools);
+	// the bridge tools a page answers itself; `connect` is the agent CLI's (the Worker drops it, serve keeps it)
+	const tools = [...mapped.tools, ...bridgeTools('browser')].map(annotate);
+	return {
+		format: CATALOG_FORMAT,
+		generator: {
+			source: 'tpAgent.tools() via core scripts/agent-tool-catalog.cjs, mapped by tools/agent/src/catalog.js',
+			hostTools: hostTools.length,
+			dropped: mapped.dropped,
+			...(opts.provenance ?? {})
+		},
+		instructions: connectorInstructions(tools.map((t) => t.name)),
+		tools
+	};
+}

package/src/chat.js

@@ -0,0 +1,303 @@
+// The chat half of the bridge (roadmap 56 C2-C4, C6, C8, C11). Pure apart from the image spool's disk writes.
+//
+// An MCP host cannot be woken by a server, so a message typed in the app's AI assistant window waits in the
+// agent page's inbox until the agent PICKS IT UP: `wait_for_message` long-polls `tpAgent.nextMessage`, the
+// agent acts, `reply` streams the answer back into the window, and it waits again. The page owns every rule
+// (the sender's role, viewers refused, Stop → `cancelled`, history on a chat switch); this file shapes what
+// the model sees: the message as JSON, each image as an MCP image block AND a temp file whose path rides in
+// the JSON (so a skill that wants a file — img2threejs — can take it as its reference).
+import { mkdirSync, writeFileSync, rmSync, readFileSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, basename } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const CHAT_TOOL_NAMES = ['wait_for_message', 'reply', 'ask', 'get_thread'];
+
+/** wait_for_message: default and longest wait (seconds) */
+export const WAIT_DEFAULT_S = 240;
+export const WAIT_MAX_S = 600;
+/** import_model: the largest local GLB the bridge reads (the app's own import cap) */
+export const IMPORT_MAX_BYTES = 25 * 1024 * 1024;
+/** import_file (roadmap 66 S4b): the app's caps by kind, checked here so a wrong file never crosses the wire */
+export const IMPORT_FILE_CAPS = { image: 16 * 1024 * 1024, json: 2 * 1024 * 1024, clip: 25 * 1024 * 1024 };
+/** import_file: base64 characters per exec call (a multiple of 4, so every part but the last is whole quads) */
+export const IMPORT_CHUNK_CHARS = 4 * 1024 * 1024;
+
+/** The chat tools (browser engine only: the wire peer has no inbox). */
+export function chatTools() {
+	return [
+		{
+			name: 'wait_for_message',
+			description:
+				'Listen for the people in the session: blocks until someone types to you in the app\'s AI assistant window, then returns that message ' +
+				'(id, chatId, from, name, role, text, images with a local file path each, answers = the ask it answers). Returns null when the timeout passes ' +
+				'with no message — call it again to keep listening. Loop: wait_for_message → do the work with the scene tools → reply(final) → wait_for_message. ' +
+				'role "viewer" = that person may not change the scene: answer, but do not edit for them (edits are refused). A message in a chat you have not ' +
+				'seen carries history (its newest messages) + summary; get_thread pages further back.',
+			inputSchema: {
+				type: 'object',
+				properties: { timeoutS: { type: 'number', description: 'seconds to wait (default ' + WAIT_DEFAULT_S + ', at most ' + WAIT_MAX_S + ')' } }
+			}
+		},
+		{
+			name: 'reply',
+			description:
+				'Answer in the app\'s AI assistant window (everyone in the session sees the thread). Each call adds a paragraph to ONE streamed reply ' +
+				'(people watch it grow); final: true finishes it and ends your "working" state. Without `to` it answers the message you are working on. ' +
+				'When the user typed to you in THIS terminal instead, pass their words as `prompt` so the app shows that turn too ("via terminal"). ' +
+				'After Stop, reply answers cancelled until you send final.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					text: { type: 'string', description: 'what to say (a paragraph added to your reply)' },
+					final: { type: 'boolean', description: 'true = this reply is complete' },
+					to: { type: 'string', description: 'peer id to answer (default: the sender of the message you are working on)' },
+					chatId: { type: 'string', description: 'default: the chat of the message you are working on' },
+					prompt: { type: 'string', description: 'the user\'s own words typed in the terminal, echoed into the app before your reply' }
+				},
+				required: ['text']
+			}
+		},
+		{
+			name: 'ask',
+			description:
+				'Ask the person a question with buttons in the window ("Pine or oak?"). Their click arrives through wait_for_message as a message whose ' +
+				'`answers` is the id this returns and whose text is the option chosen.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					question: { type: 'string' },
+					options: { type: 'array', items: { type: 'string' }, description: 'button labels (at most 8)' },
+					to: { type: 'string', description: 'peer id (default: the sender of the message you are working on)' },
+					chatId: { type: 'string' }
+				},
+				required: ['question', 'options']
+			}
+		},
+		{
+			name: 'get_thread',
+			description:
+				'Read a chat in the app, oldest first: the `limit` messages before message id `before` (omit for the newest). `more` says older ones exist. ' +
+				'Use it when a message\'s history is not enough.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					chatId: { type: 'string', description: 'default: the chat you are in' },
+					before: { type: 'string', description: 'a message id; returns the messages before it' },
+					limit: { type: 'number', description: 'default 20, at most 100' }
+				}
+			}
+		}
+	];
+}
+
+/** seconds → the clamped wait in ms @param {any} s */
+export function waitMs(s) {
+	const n = Number(s);
+	const sec = Number.isFinite(n) && n > 0 ? Math.min(WAIT_MAX_S, Math.max(1, n)) : WAIT_DEFAULT_S;
+	return Math.round(sec * 1000);
+}
+
+const EXT = /** @type {Record<string, string>} */ ({ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' });
+
+/** a filename-safe id @param {any} s */
+const safe = (s) => String(s ?? 'x').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64) || 'x';
+
+/**
+ * The temp files the images go to: `<tmp>/theprototype-agent/<session>/<chatId>/<msgId>-<n>.<ext>`, the
+ * directories 0700 and the files 0600 (photos are private), removed when the bridge exits.
+ */
+export class ImageSpool {
+	/** @param {{root?: string}} [o] */
+	constructor(o = {}) {
+		this.root = o.root ?? join(tmpdir(), 'theprototype-agent', process.pid + '-' + randomBytes(4).toString('hex'));
+		this.made = false;
+	}
+
+	/**
+	 * @param {string} chatId @param {string} msgId @param {number} n @param {{mimeType: string, data: string, name?: string}} im
+	 * @returns {string} the file's path
+	 */
+	write(chatId, msgId, n, im) {
+		const dir = join(this.root, safe(chatId));
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		this.made = true;
+		const file = join(dir, safe(msgId) + '-' + n + '.' + (EXT[im.mimeType] ?? 'bin'));
+		writeFileSync(file, Buffer.from(im.data, 'base64'), { mode: 0o600 });
+		return file;
+	}
+
+	cleanup() {
+		if (!this.made) return;
+		try {
+			rmSync(this.root, { recursive: true, force: true });
+		} catch {}
+		this.made = false;
+	}
+}
+
+/**
+ * A delivered message → MCP content: the JSON (image bytes replaced by their file paths) first, then one
+ * image block per image (Claude sees them).
+ * @param {any} msg @param {ImageSpool | null} spool
+ */
+export function messageContent(msg, spool) {
+	const images = Array.isArray(msg.images) ? msg.images : [];
+	/** @type {any[]} */
+	const blocks = [];
+	/** @type {any[]} */
+	const listed = [];
+	images.forEach((/** @type {any} */ im, /** @type {number} */ i) => {
+		if (!im || typeof im.data !== 'string') return;
+		/** @type {any} */
+		const row = { mimeType: im.mimeType };
+		if (im.name) row.name = im.name;
+		if (im.w && im.h) row.size = im.w + 'x' + im.h;
+		if (spool) {
+			try {
+				row.path = spool.write(msg.chatId, msg.id, i + 1, im);
+			} catch (e) {
+				row.pathError = String(/** @type {any} */ (e).message || e).split('\n')[0];
+			}
+		}
+		listed.push(row);
+		blocks.push({ type: 'image', data: im.data, mimeType: im.mimeType });
+	});
+	const { images: _drop, ...rest } = msg;
+	/** @type {any} */
+	const out = { ...rest };
+	if (listed.length) out.images = listed;
+	if (msg.role === 'viewer') out.note = 'This person is a VIEWER: they may read and ask, but not change the scene. Edits for this request are refused — say so in your reply.';
+	if (msg.imagesDropped) out.note = (out.note ? out.note + ' ' : '') + 'They attached images; viewers cannot attach, so they were dropped.';
+	if (msg.history?.length) out.historyNote = 'You have not seen this chat in this session: history = its newest messages, summary = the whole of it; get_thread pages back.';
+	return [{ type: 'text', text: JSON.stringify(out) }, ...blocks];
+}
+
+/** the host's `import_model` schema plus the bridge's `path` (a local file) @param {any} tool */
+export function withImportPath(tool) {
+	if (!tool || tool.name !== 'import_model') return tool;
+	const schema = tool.inputSchema && typeof tool.inputSchema === 'object' ? tool.inputSchema : { type: 'object' };
+	const properties = { ...(schema.properties ?? {}) };
+	if (properties.path) return tool;
+	properties.path = {
+		type: 'string',
+		description: 'a self-contained .glb on the machine running this bridge (≤ 25 MB); the bridge reads it and sends the bytes — use instead of data/url'
+	};
+	return {
+		...tool,
+		description: tool.description + (tool.description ? ' ' : '') + 'Local files: pass `path` (the bridge reads it).',
+		inputSchema: { ...schema, properties }
+	};
+}
+
+/**
+ * `import_model` with a `path`: read the local file (≤ 25 MB, glTF binary magic), hand the page `data`.
+ * The path never reaches the page. Throws a readable error.
+ * @param {any} args @param {{read?: (p: string) => Buffer, size?: (p: string) => number, maxBytes?: number}} [io]
+ */
+export function importModelArgs(args, io = {}) {
+	if (!args || typeof args.path !== 'string' || !args.path) return args;
+	const { path, ...rest } = args;
+	if (rest.data || rest.url) throw new Error('import_model: pass one of path, data or url');
+	const max = io.maxBytes ?? IMPORT_MAX_BYTES;
+	let size;
+	try {
+		size = (io.size ?? ((p) => statSync(p).size))(path);
+	} catch (e) {
+		throw new Error('import_model: cannot read ' + path + ' (' + String(/** @type {any} */ (e).code || /** @type {any} */ (e).message) + ')');
+	}
+	if (size > max) throw new Error('import_model: ' + basename(path) + ' is ' + (size / 1048576).toFixed(1) + ' MB; the limit is ' + max / 1048576 + ' MB');
+	const buf = (io.read ?? ((p) => readFileSync(p)))(path);
+	if (buf.length < 12 || buf.toString('latin1', 0, 4) !== 'glTF')
+		throw new Error('import_model: ' + basename(path) + ' is not a binary glTF (.glb) — export a self-contained GLB (no external files)');
+	return { ...rest, data: buf.toString('base64'), name: rest.name ?? basename(path).replace(/\.glb$/i, '') };
+}
+
+/**
+ * What a local file for `import_file` is, by its first bytes (the page sniffs again and owns the rules;
+ * this is the early refusal so 16 MB of the wrong thing never crosses the wire).
+ * @param {Buffer} b @returns {'image' | 'json' | 'clip' | null}
+ */
+export function sniffImportKind(b) {
+	if (b.length >= 8 && b[0] === 0x89 && b.toString('latin1', 1, 4) === 'PNG') return 'image';
+	if (b.length >= 12 && b.toString('latin1', 0, 4) === 'RIFF' && b.toString('latin1', 8, 12) === 'WEBP') return 'image';
+	if (b.length >= 12 && b.toString('latin1', 0, 4) === 'glTF') return 'clip';
+	const head = b.toString('utf8', 0, Math.min(b.length, 64)).replace(/^\uFEFF/, '').trimStart();
+	if (head[0] === '{' || head[0] === '[') return 'json';
+	return null;
+}
+
+/**
+ * `import_file` with a `path` (and/or `spec_path`): read the local files, check kind and size, and return
+ * the exec calls to make — ONE call, or the base64 split into `chunk: {id, index, total}` parts with every
+ * other argument riding the last one (the page imports when the last part lands). Paths never reach the
+ * page. Throws a readable error. Without a path the args pass through as the only call.
+ * @param {any} args
+ * @param {{read?: (p: string) => Buffer, size?: (p: string) => number, chunkChars?: number, id?: string}} [io]
+ * @returns {any[]}
+ */
+export function importFileCalls(args, io = {}) {
+	if (!args || typeof args !== 'object') return [args];
+	const { path, spec_path: specPath, ...rest } = args;
+	const size = io.size ?? ((/** @type {string} */ p) => statSync(p).size);
+	const read = io.read ?? ((/** @type {string} */ p) => readFileSync(p));
+	/** @param {string} p @param {number} max @param {string} what */
+	const load = (p, max, what) => {
+		let n;
+		try {
+			n = size(p);
+		} catch (e) {
+			throw new Error('import_file: cannot read ' + p + ' (' + String(/** @type {any} */ (e).code || /** @type {any} */ (e).message) + ')');
+		}
+		if (n > max) throw new Error('import_file: ' + basename(p) + ' is ' + (n / 1048576).toFixed(1) + ' MB; the limit for ' + what + ' is ' + max / 1048576 + ' MB');
+		return read(p);
+	};
+	if (typeof specPath === 'string' && specPath) {
+		if (rest.spec != null) throw new Error('import_file: pass one of spec or spec_path');
+		const text = load(specPath, IMPORT_FILE_CAPS.json, 'a spec').toString('utf8').replace(/^\uFEFF/, '');
+		try {
+			rest.spec = JSON.parse(text);
+		} catch (e) {
+			throw new Error('import_file: ' + basename(specPath) + ' is not JSON (' + String(/** @type {any} */ (e).message).slice(0, 80) + ')');
+		}
+	}
+	if (typeof path !== 'string' || !path) return [rest];
+	if (rest.data || rest.chunk) throw new Error('import_file: pass one of path or data');
+	const max = Math.max(...Object.values(IMPORT_FILE_CAPS));
+	const buf = load(path, max, 'any file');
+	const kind = sniffImportKind(buf);
+	if (!kind) throw new Error('import_file: ' + basename(path) + ' is not a PNG, WebP, JSON or .tpanim file (read from its bytes)');
+	if (buf.length > IMPORT_FILE_CAPS[kind])
+		throw new Error('import_file: ' + basename(path) + ' is ' + (buf.length / 1048576).toFixed(1) + ' MB; the limit for ' + (kind === 'image' ? 'an image' : kind === 'json' ? 'a JSON file' : 'a clip') + ' is ' + IMPORT_FILE_CAPS[kind] / 1048576 + ' MB');
+	if (rest.name == null) rest.name = basename(path).replace(/\.[^.]+$/, '');
+	const data = buf.toString('base64');
+	const step = Math.max(4, Math.floor((io.chunkChars ?? IMPORT_CHUNK_CHARS) / 4) * 4);
+	if (data.length <= step) return [{ ...rest, data }];
+	const total = Math.ceil(data.length / step);
+	const id = io.id ?? 'b' + randomBytes(6).toString('hex');
+	/** @type {any[]} */
+	const calls = [];
+	for (let i = 0; i < total; i++) {
+		const part = { data: data.slice(i * step, (i + 1) * step), chunk: { id, index: i, total } };
+		calls.push(i === total - 1 ? { ...rest, ...part } : part);
+	}
+	return calls;
+}
+
+/**
+ * One scene-tool call through the engine, with the bridge's local-file arguments resolved: `import_model`
+ * reads its `path`; `import_file` reads `path`/`spec_path` and may take several exec calls (chunks) — the
+ * first error stops it, else the last result is the answer.
+ * @param {{exec: (name: string, args: any) => Promise<any>}} engine @param {string} name @param {any} args
+ */
+export async function execBridged(engine, name, args) {
+	if (name === 'import_model') return engine.exec(name, importModelArgs(args));
+	if (name !== 'import_file') return engine.exec(name, args);
+	const calls = importFileCalls(args);
+	let r;
+	for (const c of calls) {
+		r = await engine.exec(name, c);
+		if (!r || r.error || r.__missing) return r;
+	}
+	return r;
+}

package/src/llmClient.js

@@ -1,12 +1,65 @@
-// Minimal OpenAI-compatible client for the REPL (roadmap #10 B4). Non-streaming
-// (simpler in a terminal), tool-call loop. Node 20 has global fetch.
+// Minimal OpenAI-compatible client for the REPL (roadmap #10 B4 → 56 C3), tool-call loop. Node 20 has
+// global fetch. With `onDelta` it streams (SSE, `stream: true`) so the app's AI assistant window watches the
+// reply grow; an endpoint that answers a stream request with plain JSON still works.
+
+/**
+ * Read an SSE body into one assistant message, calling onDelta per content chunk.
+ * @param {any} res @param {(t: string) => void} onDelta
+ * @returns {Promise<{content: string, toolCalls: any[]}>}
+ */
+async function readStream(res, onDelta) {
+	let content = '';
+	/** index -> {id, type, function: {name, arguments}} @type {Map<number, any>} */
+	const calls = new Map();
+	const decoder = new TextDecoder();
+	let buf = '';
+	/** @param {string} line */
+	const take = (line) => {
+		const t = line.trim();
+		if (!t.startsWith('data:')) return;
+		const data = t.slice(5).trim();
+		if (!data || data === '[DONE]') return;
+		let j;
+		try {
+			j = JSON.parse(data);
+		} catch {
+			return;
+		}
+		const d = j.choices?.[0]?.delta ?? j.choices?.[0]?.message;
+		if (!d) return;
+		if (typeof d.content === 'string' && d.content) {
+			content += d.content;
+			onDelta(d.content);
+		}
+		for (const tc of d.tool_calls ?? []) {
+			const i = Number.isInteger(tc.index) ? tc.index : calls.size;
+			const c = calls.get(i) ?? { id: '', type: 'function', function: { name: '', arguments: '' } };
+			if (tc.id) c.id = tc.id;
+			if (tc.function?.name) c.function.name += tc.function.name;
+			if (tc.function?.arguments) c.function.arguments += tc.function.arguments;
+			calls.set(i, c);
+		}
+	};
+	for await (const chunk of res.body) {
+		buf += decoder.decode(chunk, { stream: true });
+		let nl;
+		while ((nl = buf.indexOf('\n')) >= 0) {
+			take(buf.slice(0, nl));
+			buf = buf.slice(nl + 1);
+		}
+	}
+	if (buf) take(buf);
+	const toolCalls = [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([i, c]) => ({ ...c, id: c.id || 'call_' + i }));
+	return { content, toolCalls };
+}
 
 /**
  * @param {Object} cfg @param {string} cfg.apiUrl @param {string} cfg.apiKey @param {string} cfg.model
  * @param {any[]} messages @param {any[]} tools
+ * @param {((t: string) => void) | undefined} [onDelta] stream, calling this per content chunk
  * @returns {Promise<{content:string, toolCalls:any[]}>}
  */
-async function chatOnce(cfg, messages, tools) {
+export async function chatOnce(cfg, messages, tools, onDelta) {
 	const base = cfg.apiUrl.replace(/\/+$/, '');
 	const res = await fetch(base + '/chat/completions', {
 		method: 'POST',
@@ -18,16 +71,20 @@ async function chatOnce(cfg, messages, tools) {
 			model: cfg.model,
 			messages,
 			tools: tools && tools.length ? tools.map((t) => ({ type: 'function', function: t })) : undefined,
-			tool_choice: tools && tools.length ? 'auto' : undefined
+			tool_choice: tools && tools.length ? 'auto' : undefined,
+			stream: onDelta ? true : undefined
 		})
 	});
 	if (!res.ok) {
 		const body = await res.text().catch(() => '');
 		throw new Error('API ' + res.status + ': ' + body.slice(0, 300));
 	}
+	if (onDelta && /text\/event-stream/i.test(res.headers.get('content-type') || '')) return readStream(res, onDelta);
 	const json = await res.json();
 	const msg = json.choices && json.choices[0] && json.choices[0].message;
-	return { content: (msg && msg.content) || '', toolCalls: (msg && msg.tool_calls) || [] };
+	const content = (msg && msg.content) || '';
+	if (onDelta && content) onDelta(content);
+	return { content, toolCalls: (msg && msg.tool_calls) || [] };
 }
 
 /**
@@ -38,17 +95,27 @@ async function chatOnce(cfg, messages, tools) {
  * @param {any[]} opts.tools
  * @param {(name:string, args:any)=>any} opts.executeTool may return a Promise
  * @param {(name:string, args:any)=>void} [opts.onTool]
+ * @param {(t: string, round: number) => void} [opts.onDelta] stream the reply (round = which model call)
+ * @param {(result: any) => boolean} [opts.stopOn] a tool result that ends the turn (56 C6: Stop → cancelled)
  * @param {number} [opts.maxIterations]
  * @returns {Promise<string>}
  */
-export async function runChat({ cfg, messages, tools, executeTool, onTool, maxIterations = 12 }) {
+export async function runChat({ cfg, messages, tools, executeTool, onTool, onDelta, stopOn, maxIterations = 12 }) {
 	let final = '';
 	for (let i = 0; i < maxIterations; i++) {
-		const { content, toolCalls } = await chatOnce(cfg, messages, tools);
+		const { content, toolCalls } = await chatOnce(cfg, messages, tools, onDelta ? (t) => onDelta(t, i) : undefined);
 		final = content;
-		if (!toolCalls.length) break;
+		if (!toolCalls.length) {
+			if (content) messages.push({ role: 'assistant', content });
+			break;
+		}
 		messages.push({ role: 'assistant', content: content || null, tool_calls: toolCalls });
+		let stopped = false;
 		for (const call of toolCalls) {
+			if (stopped) {
+				messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify({ error: 'cancelled', cancelled: true }) });
+				continue;
+			}
 			let args = {};
 			try {
 				args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
@@ -61,9 +128,14 @@ export async function runChat({ cfg, messages, tools, executeTool, onTool, maxIt
 			try {
 				result = await executeTool(call.function.name, args);
 			} catch (e) {
-				result = { error: e.message };
+				result = { error: /** @type {any} */ (e).message };
 			}
 			messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result ?? { ok: true }) });
+			if (stopOn && stopOn(result)) stopped = true;
+		}
+		if (stopped) {
+			final = '';
+			break;
 		}
 	}
 	return final;