@theprototype/agent 1.53.0 → 1.54.0

package/catalog.json

@@ -3,15 +3,24 @@
 	"format": 2,
 	"generator": {
 		"source": "tpAgent.tools() via core scripts/agent-tool-catalog.cjs, mapped by tools/agent/src/catalog.js",
-		"hostTools": 21,
+		"hostTools": 23,
 		"dropped": []
 	},
 	"instructions": "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.\nThis 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.\nIf 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.\nCall status first: it says whether you may edit (a viewer can only look).\nYou act as this person in their own tab: status \"you\" is them (their peer id, name and role); the other users are everyone else.\nCall list_scene before editing so you use real uuids; batch many objects into one call.\nFor \"in front of me\", \"here\" or \"this\", call where_are_users and build at the spots it gives, facing the person.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nTake a screenshot after each change to check your work.\nWhen asked what you can do here, call what_can_you_do and say its \"say\" line.",
+	"connectorExcluded": [
+		"accept_offer",
+		"connect",
+		"import_file",
+		"import_model",
+		"install_modules",
+		"leave",
+		"pending_offers"
+	],
 	"tools": [
 		{
 			"name": "list_scene",
 			"title": "Read the scene",
-			"description": "List every object currently in the scene with its uuid, name, type, parent, transform, material, color and (for a primitive) its shape — geometry {type, sizes such as the thickness of a wall}. Call this before editing so you use real uuids. On a big scene narrow it: brief (uuids + names only), name (a glob), type, near {position, radius}. A big flow graph shows its first page and says how to read the rest: pass {flow: \"scene\" | object uuid, page} to read one page of one graph.\nIf 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.\nCall list_scene before editing so you use real uuids; batch many objects into one call.",
+			"description": "List every object currently in the scene with its uuid, name, type, parent, transform, material, color and (for a primitive) its shape — geometry {type, sizes such as the thickness of a wall}. The transform is the AUTHORED pose: an object an effect is moving also has animated: true, and live {position, rotation, scale, visible} when this frame differs; update_objects writes the authored pose, so never copy live back into it. Call this before editing so you use real uuids. On a big scene narrow it: brief (uuids + names only), name (a glob), type, near {position, radius}. A big flow graph shows its first page and says how to read the rest: pass {flow: \"scene\" | object uuid, page} to read one page of one graph.\nIf 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.\nCall list_scene before editing so you use real uuids; batch many objects into one call.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -236,7 +245,7 @@
 		{
 			"name": "update_objects",
 			"title": "Change objects",
-			"description": "Modify existing objects by uuid: move/rotate/scale, recolor, change material, rename, show/hide, or reparent. Batch many in one call.\nCall list_scene before editing so you use real uuids; batch many objects into one call.\nTake a screenshot after each change to check your work.",
+			"description": "Modify existing objects by uuid: move/rotate/scale, recolor, change material, rename, show/hide, or reparent. Batch many in one call. On an object an effect is moving, a transform sets its authored pose (the one list_scene reports) and the effect carries on from there.\nCall list_scene before editing so you use real uuids; batch many objects into one call.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -529,7 +538,7 @@
 		{
 			"name": "create_flow_nodes",
 			"title": "Add behaviour (flow) nodes",
-			"description": "Add behavior (flow) nodes to a node graph — this is how objects get MOTION and interactivity: spin, bounce, patrol a path, pulse, blink, react to clicks. graph is \"scene\" or an object uuid (ONE graph per call). KEY RULE: a behavior node placed in an OBJECT's graph with no edges automatically drives that object — most behaviors are one node, zero edges, so usually OMIT edges. Describe nodes EITHER as text (graph lines, see the system prompt) OR as nodes/edges arrays. A call with some bad nodes still creates the good ones and returns partial:true + errors[] — resend only what errors[] names.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nTake a screenshot after each change to check your work.",
+			"description": "Add behavior (flow) nodes to a node graph — this is how objects get MOTION and interactivity: spin, bounce, patrol a path, pulse, blink, react to clicks. graph is \"scene\" or an object uuid (ONE graph per call). KEY RULE: a behavior node placed in an OBJECT's graph with no edges automatically drives that object — most behaviors are one node, zero edges, so usually OMIT edges. A script node runs every frame FROM THE BASE POSE, so object.rotation.y += 0.02 lands at base + 0.02 and stays: write object.rotation.y = base.rot[1] + elapsed * speed (base has pos, rot, scale as arrays; elapsed = seconds since Play started, time = the shared clock, seconds of the day, a large number). Particle gravity is the acceleration along world Y: negative falls, positive rises. Describe nodes EITHER as text (graph lines, see the system prompt) OR as nodes/edges arrays. A call with some bad nodes still creates the good ones and returns partial:true + errors[] — resend only what errors[] names.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -604,7 +613,7 @@
 		{
 			"name": "update_flow_nodes",
 			"title": "Change or remove flow nodes",
-			"description": "Tune or remove existing behavior nodes in one graph. Node ids and current data are in the scene summary under each object's \"flow\" (and \"sceneFlow\").\nTake a screenshot after each change to check your work.",
+			"description": "Tune or remove existing behavior nodes in one graph. Node ids and current data are in the scene summary under each object's \"flow\" (and \"sceneFlow\"). Script code runs every frame from the base pose: use object.rotation.y = base.rot[1] + elapsed * speed, not += (elapsed = seconds since Play started, time = the shared clock, seconds of the day).\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -949,7 +958,7 @@
 		},
 		{
 			"name": "import_model",
-			"title": "Import model",
+			"title": "Import a 3D model",
 			"description": "Import a self-contained GLB (binary glTF 2.0, everything embedded, ≤ 25 MB) into the scene through the app's own import pipeline (auto-optimize, LOD, budget check). Named nodes are kept as a hierarchy and returned with uuids. One undo step; syncs to every peer; provenance is recorded. Use for models built outside the app (e.g. an img2threejs rebuild exported with named pivots). Materials: standard PBR only — custom shaders do not survive glTF.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
@@ -1005,15 +1014,15 @@
 				}
 			},
 			"annotations": {
-				"title": "Import model",
+				"title": "Import a 3D model",
 				"readOnlyHint": false,
-				"destructiveHint": true,
+				"destructiveHint": false,
 				"openWorldHint": false
 			}
 		},
 		{
 			"name": "import_file",
-			"title": "Import file",
+			"title": "Import a file",
 			"description": "Bring a file made on your machine into the session: PNG / WebP images (≤ 16 MB, metadata stripped), JSON (≤ 2 MB) or a .tpanim clip. The type is read from the bytes. It lands in the Explorer (folder \"Generated\" unless `folder`), shared with every peer. Pass the generator's input as `spec` and it is saved beside the file as <name>.<generator>.json (e.g. knight.png + knight.pixling.json) so it can be regenerated. An image is also placed in the scene as a card (a plane; `place: false` to skip): `filter: \"nearest\"` keeps pixel art crisp (default when a spec is given), `frame: {w, h, col, row}` shows one frame of a sprite sheet, `facing: \"camera-y\"` turns it to face each viewer. One undo step; editors and admins only. Large files: send base64 parts with `chunk: {id, index, total}` (the bridge does this for you with `path`).\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
@@ -1141,9 +1150,9 @@
 				}
 			},
 			"annotations": {
-				"title": "Import file",
+				"title": "Import a file",
 				"readOnlyHint": false,
-				"destructiveHint": true,
+				"destructiveHint": false,
 				"openWorldHint": false
 			}
 		},
@@ -1223,6 +1232,63 @@
 				"openWorldHint": false
 			}
 		},
+		{
+			"name": "save_scene",
+			"title": "Save the scene",
+			"description": "Save the open scene as a new version in the person's Library, the same save as Ctrl+S; Version history can restore older ones. In someone else's session it saves on the host. Viewers cannot save, and a private scene cannot be saved this way.\nTake a screenshot after each change to check your work.",
+			"inputSchema": {
+				"type": "object",
+				"properties": {
+					"name": {
+						"type": "string",
+						"description": "scene name; omit to keep the open scene's name. Ignored when saving on a host."
+					},
+					"folder": {
+						"type": "string",
+						"description": "Library folder name or id; omit for the Library root. Ignored when saving on a host."
+					}
+				}
+			},
+			"annotations": {
+				"title": "Save the scene",
+				"readOnlyHint": false,
+				"destructiveHint": false,
+				"openWorldHint": false
+			}
+		},
+		{
+			"name": "generate_mesh",
+			"title": "Generate a 3D model",
+			"description": "Generate a NEW custom 3D mesh from a text description when no primitive fits (an organic prop, a detailed object, a character). SLOW (~1-3 min) and async — it returns immediately and the mesh appears in the scene when ready. Use sparingly; prefer primitives for simple/blocky shapes.\nTake a screenshot after each change to check your work.",
+			"inputSchema": {
+				"type": "object",
+				"properties": {
+					"prompt": {
+						"type": "string",
+						"description": "what to generate, e.g. \"a weathered wooden treasure chest\""
+					},
+					"name": {
+						"type": "string"
+					},
+					"position": {
+						"type": "array",
+						"items": {
+							"type": "number"
+						},
+						"description": "[x,y,z]"
+					}
+				},
+				"required": [
+					"prompt"
+				]
+			},
+			"annotations": {
+				"title": "Generate a 3D model",
+				"readOnlyHint": false,
+				"destructiveHint": false,
+				"openWorldHint": true
+			}
+		},
 		{
 			"name": "connect",
 			"title": "Join a session",
@@ -1264,7 +1330,7 @@
 		{
 			"name": "screenshot",
 			"title": "Take a picture of the scene",
-			"description": "See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone's view. view: current | top | front | iso | focus (focus needs uuid).",
+			"description": "See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone's view. view: current | top | front | iso | focus (focus needs uuid or uuids); from = an angle or {yaw, pitch}; camera = a free {position, target}. 4:3 unless aspect says otherwise (current follows the person's window). Answers with the camera it used.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1280,7 +1346,93 @@
 					},
 					"uuid": {
 						"type": "string",
-						"description": "object to frame (view focus)"
+						"description": "object to frame"
+					},
+					"uuids": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						},
+						"description": "objects to frame together"
+					},
+					"from": {
+						"description": "the angle around the subject, instead of view: front, back, left, right, top, below, iso, or {yaw, pitch} in degrees (yaw 0 = front, 90 = right; pitch 90 = from above)",
+						"anyOf": [
+							{
+								"type": "string",
+								"enum": [
+									"front",
+									"back",
+									"left",
+									"right",
+									"top",
+									"below",
+									"iso"
+								]
+							},
+							{
+								"type": "object",
+								"properties": {
+									"yaw": {
+										"type": "number"
+									},
+									"pitch": {
+										"type": "number"
+									}
+								},
+								"required": [
+									"yaw",
+									"pitch"
+								]
+							}
+						]
+					},
+					"camera": {
+						"type": "object",
+						"description": "a free camera, instead of view and from",
+						"properties": {
+							"position": {
+								"type": "array",
+								"items": {
+									"type": "number"
+								},
+								"minItems": 3,
+								"maxItems": 3,
+								"description": "[x,y,z]"
+							},
+							"target": {
+								"type": "array",
+								"items": {
+									"type": "number"
+								},
+								"minItems": 3,
+								"maxItems": 3,
+								"description": "[x,y,z]"
+							}
+						},
+						"required": [
+							"position",
+							"target"
+						]
+					},
+					"aspect": {
+						"description": "width to height: \"4:3\" (default), \"1:1\", \"16:9\" or a number. view current defaults to the person's window",
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							}
+						]
+					},
+					"zoom": {
+						"type": "number",
+						"description": "above 1 is closer, 0.1 to 10"
+					},
+					"margin": {
+						"type": "number",
+						"description": "room around the subject: 1 touches the frame, default 1.15"
 					},
 					"size": {
 						"type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@theprototype/agent",
-	"version": "1.53.0",
+	"version": "1.54.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",

package/src/browserEngine.js

@@ -357,13 +357,14 @@ export class BrowserEngine extends EventEmitter {
 						fr.readAsDataURL(/** @type {Blob} */ (r));
 					});
 				}
-				if (r && typeof r === 'object' && typeof r.data === 'string') return { data: r.data, mimeType: r.mimeType || 'image/png' };
-				return typeof r === 'string' ? { data: r, mimeType: 'image/png' } : null;
+				const camera = typeof api.lastShot === 'function' ? api.lastShot() : null;
+				if (r && typeof r === 'object' && typeof r.data === 'string') return { data: r.data, mimeType: r.mimeType || 'image/png', camera };
+				return typeof r === 'string' ? { data: r, mimeType: 'image/png', camera } : null;
 			}, opts)
 			.catch((/** @type {any} */ e) => ({ error: firstLine(e) }));
 		if (viaApi && typeof viaApi.data === 'string') {
 			const m = /^data:([^;,]+)(;base64)?,/.exec(viaApi.data);
-			return m ? { data: viaApi.data.slice(m[0].length), mimeType: m[1] } : viaApi;
+			return m ? { data: viaApi.data.slice(m[0].length), mimeType: m[1], camera: viaApi.camera } : viaApi;
 		}
 		const canvas = await this.page.evaluateHandle(() => {
 			const all = [...document.querySelectorAll('canvas')].filter((c) => c.width > 0 && c.height > 0 && c.offsetParent !== null);

package/src/catalog.js

@@ -33,6 +33,9 @@ export const TOOL_ANNOTATIONS = /** @type {Record<string, {title: string, read?:
 	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 },
+	save_scene: { title: 'Save the scene', destructive: false },
+	import_model: { title: 'Import a 3D model', destructive: false },
+	import_file: { title: 'Import a file', destructive: false },
 	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 },
@@ -157,7 +160,7 @@ export function guidanceGaps(catalog) {
 /**
  * Host tools (tpAgent.tools()'s shape) → the static catalog.
  * @param {any[]} hostTools
- * @param {{provenance?: Record<string, any>}} [opts]
+ * @param {{provenance?: Record<string, any>, connectorExcluded?: string[]}} [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 = {}) {
@@ -174,6 +177,26 @@ export function buildCatalog(hostTools, opts = {}) {
 			...(opts.provenance ?? {})
 		},
 		instructions: connectorInstructions(tools.map((t) => t.name)),
+		// mcp-fix: what the connector leaves out, on purpose (core's CONNECTOR_BLOCKED_TOOLS); the Worker checks against it
+		...(opts.connectorExcluded ? { connectorExcluded: [...opts.connectorExcluded].sort() } : {}),
 		tools
 	};
 }
+
+/**
+ * mcp-fix: the tab's list and the catalog must agree. Fails on a tool a connector tab answers that the catalog neither
+ * lists nor leaves out on purpose, and on a listed tool no connector tab can answer. `tabTools` comes from a real
+ * createConnectorAgent(); `conditional` = tools the tab offers only sometimes (status.missingTools says why).
+ * @param {{tabTools: string[], own: string[], conditional?: string[], catalogTools: string[], excluded: string[]}} facts
+ * @returns {string[]} the problems, in words
+ */
+export function connectorToolGaps(facts) {
+	const { tabTools, own, conditional = [], catalogTools, excluded } = facts;
+	const out = new Set(excluded);
+	const listed = new Set(catalogTools.filter((n) => !out.has(n)));
+	const answered = new Set([...tabTools, ...own, ...conditional].filter((n) => !out.has(n)));
+	return [
+		...[...answered].filter((n) => !listed.has(n)).map((n) => n + ': a connector tab answers it, but it is neither in the catalog nor in CONNECTOR_BLOCKED_TOOLS'),
+		...[...listed].filter((n) => !answered.has(n)).map((n) => n + ': in the catalog, but no connector tab answers it')
+	];
+}

package/src/mcpServer.js

@@ -222,10 +222,12 @@ export function createBridgeServer(opts) {
 			if (!engine) return textResult({ error: 'not connected — join first', note: 'call connect with the session link first' }, true);
 			if (name === 'screenshot' && reserved.includes('screenshot')) {
 				if (!engineReady()) return textResult({ error: 'the agent page is not up yet (' + engine.state + ')' }, true);
-				const shot = await engine.screenshot({ view: a.view, uuid: a.uuid, size: a.size });
+				const { view, uuid, uuids, from, camera, aspect, zoom, margin, size } = a;
+				const shot = await engine.screenshot({ view, uuid, uuids, from, camera, aspect, zoom, margin, size });
 				/** @type {any[]} */
 				const content = [{ type: 'image', data: shot.data, mimeType: shot.mimeType || 'image/png' }];
 				if (shot.note) content.push({ type: 'text', text: shot.note });
+				if (shot.camera) content.push({ type: 'text', text: JSON.stringify({ camera: shot.camera }) });
 				return { content };
 			}
 			if (name === 'wait_for_edit' && reserved.includes('wait_for_edit')) {

package/src/mcpTools.js

@@ -86,12 +86,32 @@ export function bridgeTools(engine = 'browser') {
 			{
 				name: 'screenshot',
 				description:
-					'See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone\'s view. view: current | top | front | iso | focus (focus needs uuid).',
+					'See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone\'s view. view: current | top | front | iso | focus (focus needs uuid or uuids); from = an angle or {yaw, pitch}; camera = a free {position, target}. 4:3 unless aspect says otherwise (current follows the person\'s window). Answers with the camera it used.',
 				inputSchema: {
 					type: 'object',
 					properties: {
 						view: { type: 'string', enum: ['current', 'top', 'front', 'iso', 'focus'] },
-						uuid: { type: 'string', description: 'object to frame (view focus)' },
+						uuid: { type: 'string', description: 'object to frame' },
+						uuids: { type: 'array', items: { type: 'string' }, description: 'objects to frame together' },
+						from: {
+							description: 'the angle around the subject, instead of view: front, back, left, right, top, below, iso, or {yaw, pitch} in degrees (yaw 0 = front, 90 = right; pitch 90 = from above)',
+							anyOf: [
+								{ type: 'string', enum: ['front', 'back', 'left', 'right', 'top', 'below', 'iso'] },
+								{ type: 'object', properties: { yaw: { type: 'number' }, pitch: { type: 'number' } }, required: ['yaw', 'pitch'] }
+							]
+						},
+						camera: {
+							type: 'object',
+							description: 'a free camera, instead of view and from',
+							properties: {
+								position: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: '[x,y,z]' },
+								target: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: '[x,y,z]' }
+							},
+							required: ['position', 'target']
+						},
+						aspect: { description: 'width to height: "4:3" (default), "1:1", "16:9" or a number. view current defaults to the person\'s window', anyOf: [{ type: 'string' }, { type: 'number' }] },
+						zoom: { type: 'number', description: 'above 1 is closer, 0.1 to 10' },
+						margin: { type: 'number', description: 'room around the subject: 1 touches the frame, default 1.15' },
 						size: { type: 'number', description: 'longest side in pixels' }
 					}
 				}