@vcad/mcp 0.9.4-main.26 → 0.9.4-main.27

package/README.md

@@ -6,4 +6,4 @@ vcad's MCP server as a self-contained bundle (server + BRep kernel WASM).
 { "mcpServers": { "vcad": { "command": "npx", "args": ["-y", "@vcad/mcp"] } } }
 ```
 
-Built from 178040b8a9aaccb709684c5b95e4fb42a00ae9e2 at 2026-07-25T23:14:00.956Z. Source: https://github.com/ecto/vcad
+Built from cfda229f9a317556e3c9f64a43700549cd5265ef at 2026-07-25T23:24:45.817Z. Source: https://github.com/ecto/vcad

package/index.mjs

@@ -41079,6 +41079,28 @@ var init_CHANGELOG = __esm({
             "build_receipt"
           ]
         },
+        {
+          id: "2026-07-25-gym-session-first",
+          version: "0.9.4",
+          date: "2026-07-25",
+          category: "feat",
+          title: "Sim from a session id, not a re-sent document",
+          summary: "create_robot_env and batch_create_envs now take document_id, binding the env to the live session instead of a re-sent IR copy, and observations come back keyed by joint / instance id.",
+          features: [
+            "physics",
+            "simulation",
+            "mcp"
+          ],
+          mcpTools: [
+            "create_robot_env",
+            "batch_create_envs",
+            "gym_reset",
+            "gym_observe",
+            "gym_step",
+            "batch_reset",
+            "batch_step"
+          ]
+        },
         {
           id: "2026-07-25-gerber-pad-rotation",
           version: "0.9.4",
@@ -74088,6 +74110,41 @@ function getSimulation(envId) {
 function getEnvRecord(envId) {
   return envRecords.get(envId) ?? null;
 }
+function resolveEnvDocument(args) {
+  const id = typeof args.document_id === "string" ? args.document_id : "";
+  const inline = args.document && typeof args.document === "object" ? args.document : null;
+  if (id && inline) {
+    throw new Error(
+      `Pass either \`document_id\` or \`document\`, not both \u2014 they resolve to different sessions and the inline copy may be stale. Drop \`document\` to simulate session "${id}" in place.`
+    );
+  }
+  if (!id && !inline) {
+    throw new Error(
+      "Pass `document_id` (from open_document) to simulate a resident session \u2014 or an inline `document` object for the stateless flow. Exactly one is required."
+    );
+  }
+  if (id) {
+    return { doc: getSession(id), documentId: id, source: "session" };
+  }
+  return { doc: inline, documentId: null, source: "inline" };
+}
+function labelObservation(obs, jointIds, endEffectorIds) {
+  const labeled = { ...obs, joint_ids: jointIds };
+  if (jointIds && jointIds.length === obs.joint_positions.length) {
+    labeled.joints = jointIds.map((id, i) => ({
+      id,
+      position: obs.joint_positions[i],
+      velocity: obs.joint_velocities[i]
+    }));
+  }
+  if (endEffectorIds.length === obs.end_effector_poses.length) {
+    labeled.end_effectors = endEffectorIds.map((id, i) => ({
+      id,
+      pose: obs.end_effector_poses[i]
+    }));
+  }
+  return labeled;
+}
 async function createRobotEnv(input) {
   const args = input;
   const available = await isPhysicsAvailable2();
@@ -74106,17 +74163,19 @@ async function createRobotEnv(input) {
   }
   try {
     const envId = `sim_${randomBytes4(12).toString("base64url")}`;
-    const env = await PhysicsEnv.create(args.document, {
+    const { doc, documentId: sessionId, source } = resolveEnvDocument(args);
+    const env = await PhysicsEnv.create(doc, {
       endEffectorIds: args.end_effector_ids,
       dt: args.dt,
       substeps: args.substeps,
       maxSteps: args.max_steps
     });
     simulations.set(envId, env);
-    const documentId = registerSession(args.document);
+    const documentId = sessionId ?? registerSession(doc);
     envRecords.set(envId, {
-      document: args.document,
+      document: doc,
       documentId,
+      endEffectorIds: args.end_effector_ids,
       trajectory: [],
       rewards: [],
       dones: [],
@@ -74128,7 +74187,19 @@ async function createRobotEnv(input) {
     });
     const info = {
       env_id: envId,
+      // Binding contract, spelled out because two handles come back:
+      //  · env_id      → gym_step / gym_reset / gym_observe / gym_close
+      //  · document_id → the replay viewer, get_preview_glb, and every other
+      //                  session tool (render_view, inspect_cad, update, …)
+      // On the session path document_id IS the id you passed — the env and the
+      // document you keep editing are the same session. On the inline path it
+      // is a NEW session minted from the IR you sent.
       document_id: documentId,
+      document_source: source,
+      binds: {
+        env_id: "gym_step, gym_reset, gym_observe, gym_close",
+        document_id: "replay viewer, get_preview_glb, and session tools (render_view, inspect_cad, update)"
+      },
       num_joints: env.numJoints,
       // Observation ordering contract: joint_positions[i] and
       // joint_velocities[i] refer to joint_ids[i]. Null when the loaded
@@ -74185,8 +74256,16 @@ function gymStep(input) {
         record2.dones.shift();
       }
     }
+    const labeled = {
+      ...result,
+      observation: labelObservation(
+        result.observation,
+        env.jointIds,
+        record2?.endEffectorIds ?? []
+      )
+    };
     return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      content: [{ type: "text", text: JSON.stringify(labeled, null, 2) }]
     };
   } catch (err7) {
     const message = err7 instanceof Error ? err7.message : String(err7);
@@ -74218,7 +74297,20 @@ function gymReset(input) {
       record2.resetEpoch += 1;
     }
     return {
-      content: [{ type: "text", text: JSON.stringify(observation, null, 2) }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            labelObservation(
+              observation,
+              env.jointIds,
+              record2?.endEffectorIds ?? []
+            ),
+            null,
+            2
+          )
+        }
+      ]
     };
   } catch (err7) {
     const message = err7 instanceof Error ? err7.message : String(err7);
@@ -74241,8 +74333,22 @@ function gymObserve(input) {
   }
   try {
     const observation = env.observe();
+    const record2 = envRecords.get(args.env_id);
     return {
-      content: [{ type: "text", text: JSON.stringify(observation, null, 2) }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            labelObservation(
+              observation,
+              env.jointIds,
+              record2?.endEffectorIds ?? []
+            ),
+            null,
+            2
+          )
+        }
+      ]
     };
   } catch (err7) {
     const message = err7 instanceof Error ? err7.message : String(err7);
@@ -74288,6 +74394,7 @@ async function batchCreateEnvs(input) {
   }
   try {
     const batchId = `batch_${randomBytes4(12).toString("base64url")}`;
+    const { doc, documentId, source } = resolveEnvDocument(args);
     const envOptions = {
       endEffectorIds: args.end_effector_ids,
       dt: args.dt,
@@ -74296,22 +74403,33 @@ async function batchCreateEnvs(input) {
     };
     const envPromises = Array.from(
       { length: args.n_envs },
-      () => PhysicsEnv.create(args.document, envOptions)
+      () => PhysicsEnv.create(doc, envOptions)
     );
     const envs = await Promise.all(envPromises);
     const actionDim = envs[0].actionDim;
     batchGroups.set(batchId, {
       envs,
       actionDim,
-      document: args.document,
-      options: envOptions
+      document: doc,
+      options: envOptions,
+      jointIds: envs[0].jointIds
     });
     const info = {
       batch_id: batchId,
+      // batch_step / batch_reset bind to batch_id. No document session is
+      // minted here — a batch has no viewer; `document_id` echoes the session
+      // read from, and is null on the inline path.
+      document_id: documentId,
+      document_source: source,
       n_envs: args.n_envs,
       action_dim: actionDim,
       observation_dim: envs[0].observationDim,
-      num_joints: envs[0].numJoints
+      num_joints: envs[0].numJoints,
+      // Observation ordering contract, echoed so batch callers get the same
+      // labeling the single-env path returns per observation.
+      joint_ids: envs[0].jointIds,
+      actuated_joint_ids: envs[0].actuatedJointIds,
+      end_effector_ids: args.end_effector_ids
     };
     return {
       content: [{ type: "text", text: JSON.stringify(info, null, 2) }]
@@ -74353,7 +74471,13 @@ function batchStep(input) {
       (env, i) => env.step(args.action_type, args.actions[i])
     );
     const summary = {
-      observations: results.map((r) => r.observation),
+      observations: results.map(
+        (r) => labelObservation(
+          r.observation,
+          group.jointIds,
+          group.options.endEffectorIds
+        )
+      ),
       rewards: results.map((r) => r.reward),
       dones: results.map((r) => r.done)
     };
@@ -74380,7 +74504,13 @@ function batchReset(input) {
     };
   }
   try {
-    const observations = group.envs.map((env) => env.reset());
+    const observations = group.envs.map(
+      (env) => labelObservation(
+        env.reset(),
+        group.jointIds,
+        group.options.endEffectorIds
+      )
+    );
     return {
       content: [{ type: "text", text: JSON.stringify({ observations }, null, 2) }]
     };
@@ -74392,7 +74522,7 @@ function batchReset(input) {
     };
   }
 }
-var simulations, MAX_TRAJECTORY, envRecords, batchGroups, createRobotEnvSchema, gymStepSchema, gymResetSchema, gymObserveSchema, gymCloseSchema, batchCreateEnvsSchema, batchStepSchema, batchResetSchema, toolDefs45;
+var simulations, MAX_TRAJECTORY, envRecords, batchGroups, INLINE_DOC_DESC, SESSION_DOC_DESC, createRobotEnvSchema, gymStepSchema, gymResetSchema, gymObserveSchema, gymCloseSchema, batchCreateEnvsSchema, batchStepSchema, batchResetSchema, toolDefs45;
 var init_gym = __esm({
   "src/tools/gym.ts"() {
     "use strict";
@@ -74403,12 +74533,18 @@ var init_gym = __esm({
     MAX_TRAJECTORY = 600;
     envRecords = /* @__PURE__ */ new Map();
     batchGroups = /* @__PURE__ */ new Map();
+    INLINE_DOC_DESC = "Inline Document IR describing the robot assembly, used instead of a session. Use this stateless path when no `document_id` is resident (e.g. a cold serverless instance). Exactly one of `document_id` or `document` must be given.";
+    SESSION_DOC_DESC = "Session id of the assembly to simulate (from open_document / create_cad_loon). Preferred: the env binds to this same session, so no IR round-trip is needed and the sim can never run against a stale copy.";
     createRobotEnvSchema = {
       type: "object",
       properties: {
+        document_id: {
+          type: "string",
+          description: SESSION_DOC_DESC
+        },
         document: {
           type: "object",
-          description: "vcad IR Document describing the robot assembly"
+          description: INLINE_DOC_DESC
         },
         end_effector_ids: {
           type: "array",
@@ -74428,7 +74564,7 @@ var init_gym = __esm({
           description: "Maximum episode length (default: 1000)"
         }
       },
-      required: ["document", "end_effector_ids"]
+      required: ["end_effector_ids"]
     };
     gymStepSchema = {
       type: "object",
@@ -74483,9 +74619,13 @@ var init_gym = __esm({
     batchCreateEnvsSchema = {
       type: "object",
       properties: {
+        document_id: {
+          type: "string",
+          description: SESSION_DOC_DESC
+        },
         document: {
           type: "object",
-          description: "vcad IR Document describing the robot assembly"
+          description: INLINE_DOC_DESC
         },
         n_envs: {
           type: "number",
@@ -74509,7 +74649,7 @@ var init_gym = __esm({
           description: "Maximum episode length (default: 1000)"
         }
       },
-      required: ["document", "n_envs", "end_effector_ids"]
+      required: ["n_envs", "end_effector_ids"]
     };
     batchStepSchema = {
       type: "object",
@@ -74548,7 +74688,7 @@ var init_gym = __esm({
       {
         name: "create_robot_env",
         pack: "physics",
-        description: "Create a physics simulation environment from a vcad assembly. Returns an environment ID that can be used with gym_step, gym_reset, and gym_observe. The environment provides a gym-style interface for RL training. Mounts the inline 3D viewer with a play button \u2014 gym_step rollouts replay right in the chat.",
+        description: "Create a physics simulation environment from a vcad assembly. Session-first: pass the `document_id` of the assembly already open \u2014 the env binds to that same session, so there is no IR round-trip and the sim can't run against a stale copy. Inline `document` IR is the stateless fallback; exactly one of the two is required. Returns env_id (for gym_step / gym_reset / gym_observe / gym_close) and document_id (what the replay viewer and the other session tools bind to). Mounts the inline 3D viewer with a play button \u2014 gym_step rollouts replay right in the chat.",
         inputSchema: createRobotEnvSchema,
         handler: (a) => createRobotEnv(a),
         // writesDoc: the registered session must persist durably (signed-in hosted
@@ -74559,7 +74699,7 @@ var init_gym = __esm({
       {
         name: "gym_step",
         pack: "physics",
-        description: "Step the physics simulation with an action. action_type can be 'torque' (Nm), 'position' (degrees/mm), or 'velocity' (deg/s or mm/s). Returns observation (joint positions/velocities, end effector poses), reward, and done flag.",
+        description: "Step the physics simulation with an action. action_type can be 'torque' (Nm), 'position' (degrees/mm), or 'velocity' (deg/s or mm/s). Returns observation (joint positions/velocities, end effector poses), reward, and done flag. The observation carries both the bare positional arrays and id-keyed views: `joints[i] = {id, position, velocity}` and `end_effectors[i] = {id, pose}`, so no ordering has to be remembered.",
         inputSchema: gymStepSchema,
         handler: (a) => gymStep(a),
         behavior: behavior({})
@@ -74567,7 +74707,7 @@ var init_gym = __esm({
       {
         name: "gym_reset",
         pack: "physics",
-        description: "Reset the simulation environment to its initial state. Returns the initial observation.",
+        description: "Reset the simulation environment to its initial state. Returns the initial observation, with joint values keyed by joint id (`joints`) and end effector poses keyed by instance id (`end_effectors`) alongside the bare arrays.",
         inputSchema: gymResetSchema,
         handler: (a) => gymReset(a),
         behavior: behavior({})
@@ -74575,7 +74715,7 @@ var init_gym = __esm({
       {
         name: "gym_observe",
         pack: "physics",
-        description: "Get the current observation from the simulation without stepping. Returns joint positions, velocities, and end effector poses.",
+        description: "Get the current observation from the simulation without stepping. Returns joint positions, velocities, and end effector poses \u2014 both as bare arrays and keyed by joint / instance id.",
         inputSchema: gymObserveSchema,
         handler: (a) => gymObserve(a),
         behavior: behavior({})
@@ -74591,7 +74731,7 @@ var init_gym = __esm({
       {
         name: "batch_create_envs",
         pack: "physics",
-        description: "Create N parallel simulation environments from a single robot assembly. Returns a batch_id for use with batch_step and batch_reset. Enables parallel RL training across multiple environments.",
+        description: "Create N parallel simulation environments from a single robot assembly. Session-first: pass the `document_id` of the open assembly, or inline `document` IR as the stateless fallback \u2014 exactly one is required. Returns a batch_id for use with batch_step and batch_reset. Enables parallel RL training across multiple environments.",
         inputSchema: batchCreateEnvsSchema,
         handler: (a) => batchCreateEnvs(a),
         behavior: behavior({})
@@ -77878,6 +78018,8 @@ function buildInstructions(kernelPrompt) {
     "",
     "Sessions and server restarts: a `document_id` is a handle to server-side state, NOT storage. If ANY preview goes dark, a widget stops updating, or a call fails with an unknown `document_id`, check `server_info` FIRST \u2014 a low `uptime_s` or a changed `instance_id` means the SERVER RESTARTED and the feature is fine. That is the fastest way to tell a restart from a bug, and it should be the first check for any preview-shaped complaint. On a restart every live document_id dies at once, so previously-working widgets all go dark together \u2014 that is not a renderer bug. When `server_info` reports `durable:false`, sessions are in-memory only and cannot be recovered: keep the authoring source (your `create_cad_loon` call or record of edits) so a document can be rebuilt, and snapshot long-lived work with `checkpoint_document` / `save_document`. Every tool result also carries `_meta['io.vcad/build']` with `boot_token` + `instance_id`, so a changed value flags a restart without polling.",
     "",
+    "Physics/RL workflow: `create_robot_env` (or `batch_create_envs`) \u2192 `gym_reset` \u2192 `gym_step` \u2192 `gym_close`. Both env creators are session-first like everything else: pass the `document_id` of the open assembly \u2014 never re-send its IR. `create_robot_env` binds the env to that same session, so a `document_id` env and the document you keep editing can't drift apart; inline `document` IR stays available as the stateless fallback (it mints a NEW session, returned as `document_id`) and passing both is refused. `env_id` drives gym_step/gym_reset/gym_observe/gym_close; `document_id` is what the replay viewer, `get_preview_glb`, and the other session tools bind to. Observations come back both as bare positional arrays and keyed by id (`joints[i] = {id, position, velocity}`, `end_effectors[i] = {id, pose}`) \u2014 read the keyed views and no ordering has to be remembered.",
+    "",
     "PCB workflow: `create_schematic` (declare connectivity as data via `nets`) \u2192 `place_components` \u2192 `route_nets` / `add_coil` / `add_coil_array` \u2192 `run_drc` \u2192 `validate_for_fab` \u2192 `export_gerber`. All take the `document_id` from create_schematic and mutate that session \u2014 never re-send the document. `validate_for_fab` is the single 'is this board ready?' gate (DRC + renderability + Gerber serialization + blockers, all fail-closed); `export_gerber` enforces a clean DRC by default and blocks a dirty board. `board_from_solid` turns a solid part (e.g. an enclosure or stator disc in a CAD session) into an outline polygon for `place_components`. For motors, plan the winding first with `winding_layout` (slots + poles \u2192 per-coil phase/polarity/winding-factor, as data \u2014 it touches no board), then realize it with `add_coil_array`. `run_drc` returns a summary by default (counts by rule + net-pair, worst clearance, a capped sample); pass `detail:'full'` for every violation. Surgical copper edits: `get_copper` lists existing traces/vias/zones (filtered by layer/net/bbox/kind) with the same indices `delete_trace`/`delete_via`/`delete_zone` accept \u2014 discover, then delete, without exporting the document. Where two nets must touch on purpose (wye neutral, split ground, shunt tap), declare it with `add_net_tie` \u2014 prefer a region-scoped tie (position+radius) so DRC stays honest away from the junction; `delete_net_tie` takes it back."
   ].join("\n");
   if (!kernelPrompt) return header;
@@ -78727,8 +78869,8 @@ var init_server3 = __esm({
     init_order_feed();
     init_animate();
     PKG_VERSION = (() => {
-      if ("0.9.4-main.26") {
-        return "0.9.4-main.26";
+      if ("0.9.4-main.27") {
+        return "0.9.4-main.27";
       }
       try {
         const req = createRequire2(import.meta.url);
@@ -78737,8 +78879,8 @@ var init_server3 = __esm({
         return "0.0.0";
       }
     })();
-    BUILD_SHA = "178040b8a9aaccb709684c5b95e4fb42a00ae9e2";
-    BUILD_TIME = "2026-07-25T23:14:00.956Z";
+    BUILD_SHA = "cfda229f9a317556e3c9f64a43700549cd5265ef";
+    BUILD_TIME = "2026-07-25T23:24:45.817Z";
     SHORT_SHA = BUILD_SHA === "unknown" ? "unknown" : BUILD_SHA.slice(0, 7);
     VERSION_WITH_BUILD = SHORT_SHA === "unknown" ? PKG_VERSION : `${PKG_VERSION}+${SHORT_SHA}`;
     INSTANCE_ID = randomUUID6().slice(0, 8);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vcad/mcp",
-  "version": "0.9.4-main.26",
+  "version": "0.9.4-main.27",
   "description": "vcad MCP server — parametric CAD + PCB design tools for AI agents (self-contained: bundled server + kernel WASM)",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
   },
   "homepage": "https://vcad.io",
   "vcadBuild": {
-    "sha": "178040b8a9aaccb709684c5b95e4fb42a00ae9e2",
-    "builtAt": "2026-07-25T23:14:00.956Z"
+    "sha": "cfda229f9a317556e3c9f64a43700549cd5265ef",
+    "builtAt": "2026-07-25T23:24:45.817Z"
   }
 }