@theprototype/agent 1.51.0 → 1.53.0

package/README.md

@@ -26,6 +26,10 @@ claude mcp add theprototype -- npx -y @theprototype/agent mcp
 
 and tell Claude *"join https://theprototype.app/#F0FD3"* (it calls `connect`).
 
+**A Claude Code that is already running** joins with no restart: `npx -y @theprototype/agent serve --port 8765`, then
+`claude mcp add --transport http theprototype http://127.0.0.1:8765/mcp`. It answers on this machine only, and lists the
+full tool catalog before a join (`--no-static-tools` = off); scene tools answer *not connected — join first* until `connect`.
+
 **Claude Desktop** and other MCP hosts: the server is `npx -y @theprototype/agent mcp <link>`
 over stdio. For Claude Desktop, in `claude_desktop_config.json`:
 

package/catalog.json

@@ -6,12 +6,12 @@
 		"hostTools": 21,
 		"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).\nCall list_scene before editing so you use real uuids; batch many objects into one call.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nUse screenshot to check a result when it matters, not after every step.\nWhen asked what you can do here, call what_can_you_do and say its \"say\" line.",
+	"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.",
 	"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.",
+			"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.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -66,7 +66,7 @@
 		{
 			"name": "create_objects",
 			"title": "Add objects",
-			"description": "Create one or more primitives, lights or empty groups in a single call. Ground is the y=0 plane; place objects so they rest ON it (a box of height h sits at y=h/2). Returns the new uuids.",
+			"description": "Create one or more primitives, lights or empty groups in a single call. Ground is the y=0 plane; place objects so they rest ON it (a box of height h sits at y=h/2). Returns the new uuids.\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.\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.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -236,7 +236,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.",
+			"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.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -360,7 +360,7 @@
 		{
 			"name": "delete_objects",
 			"title": "Delete objects",
-			"description": "Delete objects by uuid.",
+			"description": "Delete objects by uuid.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -385,7 +385,7 @@
 		{
 			"name": "group_objects",
 			"title": "Group objects",
-			"description": "Create a new group and move the given member objects into it. Returns the group uuid.",
+			"description": "Create a new group and move the given member objects into it. Returns the group uuid.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -414,7 +414,7 @@
 		{
 			"name": "clear_scene",
 			"title": "Clear the scene",
-			"description": "Delete ALL objects in the scene. Requires confirm:true. Use only when the user clearly asks to start over.",
+			"description": "Delete ALL objects in the scene. Requires confirm:true. Use only when the user clearly asks to start over.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -436,7 +436,7 @@
 		{
 			"name": "animate_parts",
 			"title": "Animate parts",
-			"description": "Animate a model's NAMED PARTS (child nodes from list_scene: a rotor, a door, a lid) with one clip — e.g. spin a rotor: tracks [{part: 'rotor', keys: [{t: 0, rot: [0, 0, 0]}, {t: 1, rot: [0, 360, 0]}]}], loop true. Keys are offsets from each part's rest pose (mode 'relative', the default; 'absolute' = local values). rot is Euler degrees [x, y, z]; pos metres [x, y, z]; scale a factor. The clip is saved as a .tpanim file, plays on every peer, and is one undo step.",
+			"description": "Animate a model's NAMED PARTS (child nodes from list_scene: a rotor, a door, a lid) with one clip — e.g. spin a rotor: tracks [{part: 'rotor', keys: [{t: 0, rot: [0, 0, 0]}, {t: 1, rot: [0, 360, 0]}]}], loop true. Keys are offsets from each part's rest pose (mode 'relative', the default; 'absolute' = local values). rot is Euler degrees [x, y, z]; pos metres [x, y, z]; scale a factor. The clip is saved as a .tpanim file, plays on every peer, and is one undo step.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -529,7 +529,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.",
+			"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.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -604,7 +604,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\").",
+			"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.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -653,7 +653,7 @@
 		{
 			"name": "describe_node_types",
 			"title": "Look up flow node types",
-			"description": "Look up flow node types before wiring them: per type its inputs (toHandle names + socket types), its output type and named outputs (fromHandle), its params with types and defaults, and one line on what it does. No arguments = every type name by group; group = that group with one-line docs; types = full details (up to 12). Changes nothing.",
+			"description": "Look up flow node types before wiring them: per type its inputs (toHandle names + socket types), its output type and named outputs (fromHandle), its params with types and defaults, and one line on what it does. No arguments = every type name by group; group = that group with one-line docs; types = full details (up to 12). Changes nothing.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -679,7 +679,7 @@
 		{
 			"name": "create_behaviour",
 			"title": "Add a code behaviour",
-			"description": "Create a code behaviour: game logic (rules, waves, scoring, timers, win/lose) as ONE JavaScript module, run on the session authority and replicated. Prefer it over large node graphs for game rules. Linted before it is applied; problems come back with line numbers. The result names the node id and its sockets — wire them with create_flow_nodes (an On Click / On Enter into an input; an output into HUD Text, Visibility, Announce…).\nBEHAVIOURS (create_behaviour / edit_behaviour): game logic as ONE JavaScript module, run on ONE peer (the session authority); `state` replicates to everyone.\nexport default behaviour({ name, params: {k: literal | {value, min, max, step, unit}}, state: {plain JSON}, inputs: [names], outputs: [names], on: {event(payload) {...}}, ...methods });\ninputs: a trigger wired into input \"x\" runs on.x. outputs: a state field = a value output, any other name = an event fired by this.emit(\"name\").\nA behaviour does NOT move, rotate, recolour or hide objects (no such this.*): it drives effect nodes (spin, visibility, setcolor…) via its outputs. NO per-frame hook (no onTick/update): repeat with this.after(seconds, \"method\").\nthis: params, state, kit (also bare `kit`), after(seconds, \"method\", ...args) (survives the host leaving), cancel(key), rand(), randInt(a,b), pick(list), now(), find(glob) / findAll(glob) -> {uuid, name, pos, tags}, object, log() — always as this.find(…) etc. (only `kit` and the helpers are bare). Helpers: dist(a,b), clamp, lerp.\nevents: load (runs on EVERY peer when the behaviour loads — local, state read-only: register things there), start (once, on the authority); grabRequest({piece, distance, hand, refuse}) (runs on the grabbing peer, read-only: call refuse(reason)); any kit event as \"piece.event\" or roundStart, go, won, lost, paused, resumed, menu, levelSelected, scored, collected, allCollected, spawned, despawned, emptied, damaged, healed, died, revived, stuck, grabRefused. Entity payloads have entity.is(glob), entity.hasTag(t).\nkit calls: kit.round.start/win(reason)/lose(reason), kit.score.add(n), kit.spawner.spawn({kind, template: uuid, at, count, hp, mover: {speed}}), kit.health.damage(id, n), kit.mover.chase(kind, \"nearestPlayer\"), kit.rules.set({reach, jump}), kit.pickups.register({id, score, respawn, radius}) — register pickups in on.load (every peer must know them, or touching one does nothing), never in start.\nForbidden (the load is refused): Math.random, Date / Date.now, performance.now, localStorage, document/window/globalThis, fetch, eval, setTimeout/setInterval, import. Unknown this.* members, unknown events and hook-named methods nothing calls are refused too.\nEXAMPLE (passes the lint; wire a trigger into input gemTouched, output left into a HUD Text, timeUp into a Visibility or Announce):\nexport default behaviour({\n  name: 'Countdown',\n  params: { seconds: 30 },\n  state: { left: 30, found: 0 },\n  inputs: ['gemTouched'],\n  outputs: ['left', 'found', 'timeUp'],\n  on: {\n    start() { this.state.left = this.params.seconds; this.after(1, 'tick'); },\n    gemTouched() { this.state.found += 1; }\n  },\n  tick() {\n    this.state.left -= 1;\n    if (this.state.left > 0) this.after(1, 'tick');\n    else this.emit('timeUp');\n  }\n});",
+			"description": "Create a code behaviour: game logic (rules, waves, scoring, timers, win/lose) as ONE JavaScript module, run on the session authority and replicated. Prefer it over large node graphs for game rules. Linted before it is applied; problems come back with line numbers. The result names the node id and its sockets — wire them with create_flow_nodes (an On Click / On Enter into an input; an output into HUD Text, Visibility, Announce…).\nBEHAVIOURS (create_behaviour / edit_behaviour): game logic as ONE JavaScript module, run on ONE peer (the session authority); `state` replicates to everyone.\nexport default behaviour({ name, params: {k: literal | {value, min, max, step, unit}}, state: {plain JSON}, inputs: [names], outputs: [names], on: {event(payload) {...}}, ...methods });\ninputs: a trigger wired into input \"x\" runs on.x. outputs: a state field = a value output, any other name = an event fired by this.emit(\"name\").\nA behaviour does NOT move, rotate, recolour or hide objects (no such this.*): it drives effect nodes (spin, visibility, setcolor…) via its outputs. NO per-frame hook (no onTick/update): repeat with this.after(seconds, \"method\").\nthis: params, state, kit (also bare `kit`), after(seconds, \"method\", ...args) (survives the host leaving), cancel(key), rand(), randInt(a,b), pick(list), now(), find(glob) / findAll(glob) -> {uuid, name, pos, tags}, object, log() — always as this.find(…) etc. (only `kit` and the helpers are bare). Helpers: dist(a,b), clamp, lerp.\nevents: load (runs on EVERY peer when the behaviour loads — local, state read-only: register things there), start (once, on the authority); grabRequest({piece, distance, hand, refuse}) (runs on the grabbing peer, read-only: call refuse(reason)); any kit event as \"piece.event\" or roundStart, go, won, lost, paused, resumed, menu, levelSelected, scored, collected, allCollected, spawned, despawned, emptied, damaged, healed, died, revived, stuck, grabRefused. Entity payloads have entity.is(glob), entity.hasTag(t).\nkit calls: kit.round.start/win(reason)/lose(reason), kit.score.add(n), kit.spawner.spawn({kind, template: uuid, at, count, hp, mover: {speed}}), kit.health.damage(id, n), kit.mover.chase(kind, \"nearestPlayer\"), kit.rules.set({reach, jump}), kit.pickups.register({id, score, respawn, radius}) — register pickups in on.load (every peer must know them, or touching one does nothing), never in start.\nForbidden (the load is refused): Math.random, Date / Date.now, performance.now, localStorage, document/window/globalThis, fetch, eval, setTimeout/setInterval, import. Unknown this.* members, unknown events and hook-named methods nothing calls are refused too.\nEXAMPLE (passes the lint; wire a trigger into input gemTouched, output left into a HUD Text, timeUp into a Visibility or Announce):\nexport default behaviour({\n  name: 'Countdown',\n  params: { seconds: 30 },\n  state: { left: 30, found: 0 },\n  inputs: ['gemTouched'],\n  outputs: ['left', 'found', 'timeUp'],\n  on: {\n    start() { this.state.left = this.params.seconds; this.after(1, 'tick'); },\n    gemTouched() { this.state.found += 1; }\n  },\n  tick() {\n    this.state.left -= 1;\n    if (this.state.left > 0) this.after(1, 'tick');\n    else this.emit('timeUp');\n  }\n});\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -711,7 +711,7 @@
 		{
 			"name": "edit_behaviour",
 			"title": "Edit a code behaviour",
-			"description": "Replace an existing behaviour's source (the scene summary lists them; read the current source with the name). Linted before it is applied. Same format as create_behaviour (see its description).",
+			"description": "Replace an existing behaviour's source (the scene summary lists them; read the current source with the name). Linted before it is applied. Same format as create_behaviour (see its description).\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -738,7 +738,7 @@
 		{
 			"name": "set_physics",
 			"title": "Set physics",
-			"description": "Set physics body params on objects (batch). NOTE: objects made with create_objects are STATIC unless created with physics \"dynamic\" or a mass — use this to make existing objects dynamic, to TUNE bodies, or to pin scenery (mode \"static\"). mode \"auto\" reverts to scenery defaults.",
+			"description": "Set physics body params on objects (batch). NOTE: objects made with create_objects are STATIC unless created with physics \"dynamic\" or a mass — use this to make existing objects dynamic, to TUNE bodies, or to pin scenery (mode \"static\"). mode \"auto\" reverts to scenery defaults.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -835,7 +835,7 @@
 		{
 			"name": "create_joints",
 			"title": "Add physics joints",
-			"description": "Attach object pairs with physics joints: \"fixed\" welds them rigidly, \"revolute\" hinges around an axis (optional motor spins it). Move parts to their final pose WORLD-ALIGNED (no rotation) before jointing. Without anchor a hinge sits at b's origin (its centre) and a weld midway: pass anchor [x,y,z] (world) for the real pivot, e.g. the top of a pendulum rod or a door's edge. Jointed bodies that touch (a door in its frame, a wheel in its arch) also need contacts:false, or the solver pushes them apart.",
+			"description": "Attach object pairs with physics joints: \"fixed\" welds them rigidly, \"revolute\" hinges around an axis (optional motor spins it). Move parts to their final pose WORLD-ALIGNED (no rotation) before jointing. Without anchor a hinge sits at b's origin (its centre) and a weld midway: pass anchor [x,y,z] (world) for the real pivot, e.g. the top of a pendulum rod or a door's edge. Jointed bodies that touch (a door in its frame, a wheel in its arch) also need contacts:false, or the solver pushes them apart.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -921,7 +921,7 @@
 		{
 			"name": "control_simulation",
 			"title": "Run or stop the simulation",
-			"description": "Start, stop, pause, resume or reset the physics simulation. After building a physics assembly, start the simulation so the user sees it move.",
+			"description": "Start, stop, pause, resume or reset the physics simulation. After building a physics assembly, start the simulation so the user sees it move.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -950,7 +950,7 @@
 		{
 			"name": "import_model",
 			"title": "Import 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.",
+			"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",
 				"properties": {
@@ -1014,7 +1014,7 @@
 		{
 			"name": "import_file",
 			"title": "Import 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`).",
+			"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",
 				"properties": {
@@ -1150,7 +1150,7 @@
 		{
 			"name": "install_modules",
 			"title": "Install modules",
-			"description": "Install the modules the other peers in this session run and this page lacks (status().missingModules), from the module gallery. Local to this page; omit ids to install every missing one.",
+			"description": "Install the modules the other peers in this session run and this page lacks (status().missingModules), from the module gallery. Local to this page; omit ids to install every missing one.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1187,7 +1187,7 @@
 		{
 			"name": "accept_offer",
 			"title": "Answer a question the app asks",
-			"description": "Press a button on a pending offer (see pending_offers). action = the button label; omit for the first button.",
+			"description": "Press a button on a pending offer (see pending_offers). action = the button label; omit for the first button.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1212,7 +1212,7 @@
 		{
 			"name": "what_can_you_do",
 			"title": "What can you do here",
-			"description": "Answer \"what can you do here?\": a short spoken summary of what you can build in this tab, what you cannot do, and example requests. Changes nothing.",
+			"description": "Answer \"what can you do here?\": a short spoken summary of what you can build in this tab, what you cannot do, and example requests. Changes nothing.\nYou 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.\nWhen asked what you can do here, call what_can_you_do and say its \"say\" line.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {}
@@ -1226,7 +1226,7 @@
 		{
 			"name": "connect",
 			"title": "Join a session",
-			"description": "Join a theprototype.app session. Pass the link the host shared (https://theprototype.app/#F0FD3, possibly with &invite=…) or the bare session id. An invite link joins at once; a plain link asks the host to Approve. The scene tools appear once the agent page is up; call status to see whether you are in.",
+			"description": "Join a theprototype.app session. Pass the link the host shared (https://theprototype.app/#F0FD3, possibly with &invite=…) or the bare session id. An invite link joins at once; a plain link asks the host to Approve. The scene tools appear once the agent page is up; call status to see whether you are in.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1250,7 +1250,7 @@
 		{
 			"name": "status",
 			"title": "Session status",
-			"description": "Where the agent is: connection state, whether the host has let it in, its role (viewer edits stay local), the app version, and why any tool is missing.",
+			"description": "Where the agent is: connection state, whether the host has let it in, its role (viewer edits stay local), the app version, and why any tool is missing.\nYou 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.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {}
@@ -1312,6 +1312,43 @@
 				"readOnlyHint": true,
 				"openWorldHint": false
 			}
+		},
+		{
+			"name": "join_session",
+			"title": "Join a session (asks the person)",
+			"description": "Join a theprototype.app session from a link the person gave you (https://theprototype.app/#F0FD3, possibly with &invite=…, or the bare session id). Nothing happens until the person presses Join on a card in their tab that names the host and the session; Cancel refuses. The app may then ask them what to do with the scene they have open. Answers joining, refused or cancelled; call status afterwards to see where the tab is.\nTake a screenshot after each change to check your work.",
+			"inputSchema": {
+				"type": "object",
+				"properties": {
+					"link": {
+						"type": "string",
+						"description": "the session link, invite link or session id the person gave you"
+					}
+				},
+				"required": [
+					"link"
+				]
+			},
+			"annotations": {
+				"title": "Join a session (asks the person)",
+				"readOnlyHint": false,
+				"destructiveHint": true,
+				"openWorldHint": true
+			}
+		},
+		{
+			"name": "where_are_users",
+			"title": "Where the people are",
+			"description": "Where each person in the session is and which way they look (their desktop camera, or the VR headset): position, facing as a compass yaw plus forward and right vectors, the floor under them, and ready-made spots 1.5 m and 3 m in front of them at floor level. The entry with \"you\": true is the person you act as. Use it for \"in front of me\", \"around me\", \"behind me\", \"to my left\".\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.\nFor \"in front of me\", \"here\" or \"this\", call where_are_users and build at the spots it gives, facing the person.",
+			"inputSchema": {
+				"type": "object",
+				"properties": {}
+			},
+			"annotations": {
+				"title": "Where the people are",
+				"readOnlyHint": true,
+				"openWorldHint": false
+			}
 		}
 	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@theprototype/agent",
-	"version": "1.51.0",
+	"version": "1.53.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",
@@ -39,7 +39,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"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",
+		"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 && node test/http.test.mjs",
 		"spike": "node src/spike.js",
 		"smoke": "node src/cli.js smoke",
 		"repl": "node src/cli.js repl",

package/src/catalog.js

@@ -7,7 +7,7 @@
 // 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';
+import { mapHostTools, bridgeTools, connectorOnlyTools } from './mcpTools.js';
 
 /** Bump when the catalog's SHAPE changes (not when tools change). 2 = titles + annotations. */
 export const CATALOG_FORMAT = 2;
@@ -42,7 +42,10 @@ export const TOOL_ANNOTATIONS = /** @type {Record<string, {title: string, read?:
 	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 }
+	connect: { title: 'Join a session', destructive: false, openWorld: true },
+	// 86-fix N2: the connector's join — the person confirms in the tab; joining may replace what the tab shows
+	join_session: { title: 'Join a session (asks the person)', destructive: true, openWorld: true },
+	where_are_users: { title: 'Where the people are', read: true }
 });
 
 /** a title from a tool name: `create_objects` → `Create objects` @param {string} name */
@@ -62,31 +65,93 @@ export function annotate(t) {
 	return { name: t.name, title, description: t.description, inputSchema: t.inputSchema, annotations };
 }
 
+/** every edit tool: the catalog's non-read tools @type {'EDITS'} */
+const EDITS = 'EDITS';
+
+/**
+ * 86-fix B4 — THE GUIDANCE, ONE TABLE. claude.ai drops a server's `instructions`, so every line that matters
+ * lives in the DESCRIPTION of the tools it is about (`on`); the instructions are the same lines for the
+ * clients that do read them. `when` = the tool that must exist for the line to appear at all (default: the
+ * first of `on`). `guidanceGaps` (catalog:agent --check, the unit test) fails on an instruction line no
+ * description carries.
+ * @type {{line: string, on: (string|'EDITS')[], when?: string}[]}
+ */
+export const GUIDANCE = [
+	{
+		line: '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.',
+		on: ['status', 'what_can_you_do']
+	},
+	{
+		line: '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.',
+		on: ['status', 'what_can_you_do', 'create_objects']
+	},
+	{
+		line: '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.',
+		on: ['status', 'list_scene']
+	},
+	{ line: 'Call status first: it says whether you may edit (a viewer can only look).', on: ['status'] },
+	{
+		line: 'You act as this person in their own tab: status "you" is them (their peer id, name and role); the other users are everyone else.',
+		on: ['status', 'where_are_users'],
+		when: 'join_session'
+	},
+	{ line: 'Call list_scene before editing so you use real uuids; batch many objects into one call.', on: ['list_scene', 'create_objects', 'update_objects'] },
+	{
+		line: 'For "in front of me", "here" or "this", call where_are_users and build at the spots it gives, facing the person.',
+		on: ['where_are_users', 'create_objects']
+	},
+	{ line: 'For "give me a flashlight" or another prop, make the object, then attach_to_user to the person who asked.', on: ['attach_to_user'] },
+	{
+		line: 'Motion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.',
+		on: ['create_flow_nodes', 'describe_node_types'],
+		when: 'describe_node_types'
+	},
+	{ line: 'Motion and interaction are flow nodes (create_flow_nodes).', on: ['create_flow_nodes'], when: '!describe_node_types' },
+	{ line: 'Take a screenshot after each change to check your work.', on: [EDITS], when: 'screenshot' },
+	{ line: 'When asked what you can do here, call what_can_you_do and say its "say" line.', on: ['what_can_you_do'] }
+];
+
+/** @param {{line: string, on: string[], when?: string}} g @param {Set<string>} has */
+function applies(g, has) {
+	const when = g.when ?? g.on.find((n) => n !== EDITS) ?? '';
+	return when.startsWith('!') ? has.has(g.on[0]) && !has.has(when.slice(1)) : has.has(when);
+}
+
 /**
  * The server instructions for a voice-first client (claude.ai chat, phone and voice mode). Short,
- * spoken-style, and only about tools in `names`.
+ * spoken-style, and only about tools in `names` — the GUIDANCE lines, verbatim.
  * @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');
+	return GUIDANCE.filter((g) => applies(g, has))
+		.map((g) => g.line)
+		.join('\n');
+}
+
+/**
+ * The GUIDANCE lines appended to each tool's description (86-fix B4: claude.ai reads descriptions, not
+ * instructions). A tool's own text comes first; each line once.
+ * @template {{name: string, description: string, annotations?: any}} T @param {T[]} tools @returns {T[]}
+ */
+export function withGuidance(tools) {
+	const has = new Set(tools.map((t) => t.name));
+	return tools.map((t) => {
+		const isEdit = !(t.annotations?.readOnlyHint === true);
+		const lines = GUIDANCE.filter((g) => applies(g, has) && (g.on.includes(t.name) || (isEdit && g.on.includes(EDITS)))).map((g) => g.line);
+		const own = String(t.description ?? '').trim();
+		return lines.length ? { ...t, description: [own, ...lines.filter((l) => !own.includes(l))].filter(Boolean).join('\n') } : t;
+	});
+}
+
+/**
+ * Instruction lines no tool description carries — the check `catalog:agent --check` runs (86-fix B4).
+ * @param {{instructions?: string, tools: {description: string}[]}} catalog @returns {string[]}
+ */
+export function guidanceGaps(catalog) {
+	const lines = String(catalog.instructions ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+	return lines.filter((l) => !catalog.tools.some((t) => String(t.description ?? '').includes(l)));
 }
 
 /**
@@ -99,7 +164,7 @@ 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);
+	const tools = withGuidance([...mapped.tools, ...bridgeTools('browser'), ...connectorOnlyTools()].map(annotate));
 	return {
 		format: CATALOG_FORMAT,
 		generator: {

package/src/cli.js

@@ -12,8 +12,8 @@ import { parseLink, redactLink } from './link.js';
 import { BrowserEngine } from './browserEngine.js';
 import { WireEngine } from './wireEngine.js';
 
-const BOOLEAN = new Set(['mcp', 'repl', 'smoke', 'verbose', 'compat', 'headed', 'insecure', 'no-turn', 'no-install', 'help', 'version']);
-const MODES = ['mcp', 'repl', 'smoke'];
+const BOOLEAN = new Set(['mcp', 'serve', 'static-tools', 'no-static-tools', 'repl', 'smoke', 'verbose', 'compat', 'headed', 'insecure', 'no-turn', 'no-install', 'help', 'version']);
+const MODES = ['mcp', 'serve', 'repl', 'smoke'];
 
 /** argv → flags: --flag value | --flag=value | --bool; a known boolean never eats the next word. */
 export function parseArgs(/** @type {string[]} */ argv) {
@@ -157,6 +157,7 @@ function usage() {
 			'theprototype-agent — join a theprototype.app session as a peer and build the scene',
 			'',
 			'  theprototype-agent mcp   <link>   MCP server over stdio (claude mcp add theprototype -- npx -y @theprototype/agent mcp <link>)',
+			'  theprototype-agent serve --port <n> [link]   MCP over HTTP on 127.0.0.1 (claude mcp add --transport http theprototype http://127.0.0.1:<n>/mcp)',
 			'  theprototype-agent repl  <link>   your own OpenAI-compatible model (--api-url --api-key --model)',
 			'  theprototype-agent smoke <link>   scripted create/move/delete, no model',
 			'',
@@ -171,6 +172,7 @@ function usage() {
 			'  --peer-server h:p[:insecure] | public   wire: signaling override (default: from the link)',
 			'  --turn-url <url> | --no-turn            wire: TURN credentials endpoint (default: from the link)',
 			'  --id <id>               wire: stable peer id   --approval-timeout <s>  (default 120)',
+			'  --static-tools          list the full tool catalog before a join (the default with serve; --no-static-tools = off)',
 			'  --verbose               log to stderr'
 		].join('\n')
 	);
@@ -192,10 +194,15 @@ async function main() {
 	const kind = (args.engine || 'browser') === 'wire' ? 'wire' : 'browser';
 	if (args.engine && !['browser', 'wire'].includes(args.engine)) throw new Error('--engine is browser or wire');
 
-	if (mode === 'mcp') {
+	if (mode === 'mcp' || mode === 'serve') {
 		const m = await import('./mcpServer.js');
-		const staticTools = kind === 'wire' ? (await import('./tools.js')).TOOL_SCHEMAS : undefined;
-		await m.runMcp(args, { kind, link, staticTools, makeEngine: (l, name) => makeEngine(args, l, name) });
+		const wantCatalog = mode === 'serve' ? !args['no-static-tools'] : !!args['static-tools'];
+		const staticTools = kind === 'wire' ? (await import('./tools.js')).TOOL_SCHEMAS : wantCatalog ? m.catalogHostTools() : undefined;
+		const deps = { kind, link, staticTools, makeEngine: (/** @type {string} */ l, /** @type {any} */ name) => makeEngine(args, l, name) };
+		if (mode === 'serve') {
+			const { runHttp } = await import('./httpServer.js');
+			await runHttp(args, deps);
+		} else await m.runMcp(args, deps);
 		return;
 	}
 	if (!link) throw new Error(mode + ' needs a session link: theprototype-agent ' + mode + ' https://theprototype.app/#<id>');

package/src/httpServer.js

@@ -0,0 +1,117 @@
+// `theprototype-agent serve --port <n>` (roadmap 56 C18): the same bridge as `mcp`, as streamable HTTP MCP on
+// 127.0.0.1, so a Claude Code that is already running joins with no MCP restart.
+//
+// It answers loopback only: the listener binds 127.0.0.1, and a request whose Host or Origin is another site
+// is refused, or any web page could reach it through DNS rebinding and drive this agent's session.
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { createBridgeServer, nameFromClient } from './mcpServer.js';
+
+/** import_model / import_file carry a 25 MB file as base64 */
+const MAX_BODY = 40 * 1024 * 1024;
+const LOOPBACK = /^(127\.0\.0\.1|localhost)(:\d+)?$/i;
+
+/** Is this request from this machine's own clients? @param {import('node:http').IncomingHttpHeaders} headers */
+export function loopbackRequest(headers) {
+	if (!LOOPBACK.test(String(headers.host ?? ''))) return false;
+	const origin = headers.origin;
+	if (!origin) return true; // a CLI sends none; a browser always does across origins
+	try {
+		return LOOPBACK.test(new URL(String(origin)).host);
+	} catch {
+		return false;
+	}
+}
+
+/** @param {import('node:http').IncomingMessage} req @returns {Promise<any>} */
+function readJson(req) {
+	return new Promise((resolve, reject) => {
+		/** @type {Buffer[]} */
+		const parts = [];
+		let size = 0;
+		req.on('data', (c) => {
+			size += c.length;
+			if (size > MAX_BODY) {
+				reject(Object.assign(new Error('request too large'), { status: 413 }));
+				req.destroy();
+			} else parts.push(c);
+		});
+		req.on('end', () => {
+			try {
+				resolve(JSON.parse(Buffer.concat(parts).toString('utf8')));
+			} catch {
+				reject(Object.assign(new Error('not JSON'), { status: 400 }));
+			}
+		});
+		req.on('error', reject);
+	});
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res @param {number} status @param {string} message
+ */
+function refuse(res, status, message) {
+	res.writeHead(status, { 'content-type': 'application/json' });
+	res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message }, id: null }));
+}
+
+/**
+ * The listener over a bridge. One client at a time: a new initialize (a restarted client) takes the bridge over,
+ * and the session the agent joined stays up.
+ * @param {ReturnType<typeof createBridgeServer>} bridge @param {number} port
+ * @returns {Promise<import('node:http').Server>}
+ */
+export function listenHttp(bridge, port) {
+	/** @type {StreamableHTTPServerTransport | null} */
+	let transport = null;
+	const http = createServer(async (req, res) => {
+		try {
+			if (!loopbackRequest(req.headers)) return refuse(res, 403, 'loopback clients only');
+			if (new URL(req.url ?? '/', 'http://localhost').pathname !== '/mcp') return refuse(res, 404, 'the endpoint is /mcp');
+			const body = req.method === 'POST' ? await readJson(req) : undefined;
+			if (body !== undefined && isInitializeRequest(body)) {
+				if (transport) await bridge.server.close();
+				transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+				await bridge.server.connect(transport);
+			}
+			if (!transport) return refuse(res, 400, 'initialize first');
+			await transport.handleRequest(req, res, body);
+		} catch (e) {
+			if (!res.headersSent) refuse(res, /** @type {any} */ (e).status ?? 500, String(/** @type {any} */ (e).message ?? e));
+		}
+	});
+	return new Promise((resolve, reject) => {
+		http.once('error', reject);
+		http.listen(port, '127.0.0.1', () => resolve(http));
+	});
+}
+
+/** @param {Record<string, any>} args @param {any} deps */
+export async function runHttp(args, deps) {
+	const port = Number(args.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('serve needs --port <1-65535>');
+	const log = (/** @type {string} */ m) => console.error('[agent] ' + m);
+	let name = args.name || null;
+	const bridge = createBridgeServer({
+		kind: deps.kind,
+		staticTools: deps.staticTools,
+		createEngine: (link) => deps.makeEngine(link, name || nameFromClient(bridge.server.getClientVersion())),
+		log: args.verbose ? log : () => {}
+	});
+	const http = await listenHttp(bridge, port);
+	if (deps.link) bridge.connect(deps.link).catch((/** @type {any} */ e) => log('connect failed: ' + e.message));
+	let exiting = false;
+	const exit = async (/** @type {string} */ why) => {
+		if (exiting) return;
+		exiting = true;
+		log('leaving the session (' + why + ')');
+		http.close();
+		await bridge.shutdown();
+		process.exit(0);
+	};
+	for (const sig of /** @type {const} */ (['SIGINT', 'SIGTERM', 'SIGHUP'])) process.on(sig, () => exit(sig));
+	log('MCP HTTP server ready: http://127.0.0.1:' + port + '/mcp (' + deps.kind + ' engine' + (deps.link ? '' : ', call connect to join') + ')');
+	return { bridge, http };
+}

package/src/mcpServer.js

@@ -15,7 +15,7 @@ import { readFileSync } from 'node:fs';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { bridgeTools, mapHostTools, toolSignature, textResult, resultIsError } from './mcpTools.js';
+import { bridgeTools, connectorOnlyTools, mapHostTools, toolSignature, textResult, resultIsError } from './mcpTools.js';
 import { chatTools, waitMs, ImageSpool, messageContent, withImportPath, execBridged } from './chat.js';
 import { parseLink } from './link.js';
 
@@ -42,6 +42,17 @@ const WAIT_EDIT_MAX_MS = 120000;
 /** @param {number} ms */
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * 56 C19: the host tools of the generated catalog, for a client that reads tools/list once and ignores
+ * list_changed (claude.ai's custom connector). The live list replaces them once joined.
+ * @returns {any[]}
+ */
+export function catalogHostTools() {
+	const catalog = JSON.parse(readFileSync(new URL('../catalog.json', import.meta.url), 'utf8'));
+	const skip = new Set(connectorOnlyTools().map((t) => t.name));
+	return catalog.tools.filter((/** @type {{name: string}} */ t) => !skip.has(t.name));
+}
+
 /**
  * The server, engine-agnostic (tests drive it with a fake engine over an in-memory transport).
  * @param {Object} opts
@@ -208,7 +219,7 @@ export function createBridgeServer(opts) {
 				return textResult(st, st.state === 'failed');
 			}
 			if (name === 'status' || (name === 'get_status' && opts.kind === 'wire')) return textResult(await statusInfo());
-			if (!engine) return textResult({ error: 'not connected', note: 'call connect with the session link first' }, true);
+			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 });

package/src/mcpTools.js

@@ -109,6 +109,36 @@ export function bridgeTools(engine = 'browser') {
 	return tools;
 }
 
+/** 86-fix N2: tools only the Claude connector's tab answers (its dispatcher), listed by the Worker's catalog.
+ * The agent CLI has `connect` instead (no person at the screen to ask). */
+export const JOIN_SESSION_TOOL = {
+	name: 'join_session',
+	description:
+		'Join a theprototype.app session from a link the person gave you (https://theprototype.app/#F0FD3, possibly with &invite=…, or the bare session id). ' +
+		'Nothing happens until the person presses Join on a card in their tab that names the host and the session; Cancel refuses. ' +
+		'The app may then ask them what to do with the scene they have open. Answers joining, refused or cancelled; call status afterwards to see where the tab is.',
+	inputSchema: {
+		type: 'object',
+		properties: { link: { type: 'string', description: 'the session link, invite link or session id the person gave you' } },
+		required: ['link']
+	}
+};
+
+/** 86-fix (85 S1 pulled forward): where the people are — read-only; answered by a connector tab */
+export const WHERE_ARE_USERS_TOOL = {
+	name: 'where_are_users',
+	description:
+		'Where each person in the session is and which way they look (their desktop camera, or the VR headset): position, facing as a compass yaw ' +
+		'plus forward and right vectors, the floor under them, and ready-made spots 1.5 m and 3 m in front of them at floor level. ' +
+		'The entry with "you": true is the person you act as. Use it for "in front of me", "around me", "behind me", "to my left".',
+	inputSchema: { type: 'object', properties: {} }
+};
+
+/** @returns {any[]} */
+export function connectorOnlyTools() {
+	return [JOIN_SESSION_TOOL, WHERE_ARE_USERS_TOOL];
+}
+
 /** Text content for an MCP result. @param {any} obj @param {boolean} [isError] */
 export function textResult(obj, isError) {
 	const r = { content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj) }] };