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

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 301abfbddc2a05c29fabc9f655031e554eab1d04 at 2026-07-26T00:32:29.039Z. Source: https://github.com/ecto/vcad

package/index.mjs

@@ -10367,6 +10367,20 @@ async function airgapFluxDensity(spec) {
     return null;
   }
 }
+async function airgapSolve(spec) {
+  const wasm3 = await loadEcadWasm();
+  if (!wasm3)
+    return null;
+  try {
+    const fn = wasm3.ecadAirgapSolve;
+    if (typeof fn !== "function")
+      return null;
+    return fn(JSON.stringify(spec));
+  } catch (e) {
+    console.warn("[ECAD] airgapSolve failed:", e);
+    return null;
+  }
+}
 async function generateNetlist(sheet) {
   const wasm3 = await loadEcadWasm();
   if (!wasm3)
@@ -11229,6 +11243,7 @@ __export(dist_exports, {
   PhysicsEnv: () => PhysicsEnv,
   SolidCache: () => SolidCache,
   airgapFluxDensity: () => airgapFluxDensity,
+  airgapSolve: () => airgapSolve,
   applyForwardKinematics: () => applyForwardKinematics,
   buildMoleculeReceipt: () => buildReceipt2,
   buildPartDocument: () => buildPartDocument,
@@ -40898,6 +40913,26 @@ var init_CHANGELOG = __esm({
             "sheet_metal_create"
           ]
         },
+        {
+          id: "2026-07-25-shell-and-booleans-on-filleted-solids",
+          version: "0.9.4",
+          date: "2026-07-25",
+          category: "fix",
+          title: "Shelling and cutting a filleted solid no longer leaks",
+          summary: "Hollowing a filleted part scattered its cavity and a pocket cut collapsed the neighboring blends flat; both are now exact and watertight, and the kernel is reproducible run to run.",
+          features: [
+            "kernel",
+            "fillet",
+            "shell",
+            "booleans",
+            "tessellation"
+          ],
+          mcpTools: [
+            "create_cad_loon",
+            "inspect_cad",
+            "export_cad"
+          ]
+        },
         {
           id: "2026-07-25-router-window-repair-commit-parity",
           version: "0.9.4",
@@ -41079,6 +41114,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",
@@ -41147,6 +41204,22 @@ var init_CHANGELOG = __esm({
             "quote_manufacturing"
           ]
         },
+        {
+          id: "2026-07-25-calc-motor-tooth-saturation",
+          version: "0.9.4",
+          date: "2026-07-25",
+          category: "fix",
+          title: "calc_motor sees saturating stator teeth",
+          summary: "calc_motor's MEC model treated iron as linear and silently over-predicted Kt on machines whose teeth saturate; it now reports tooth flux, warns past the knee, and can solve the saturating network.",
+          features: [
+            "motor",
+            "magnetics",
+            "simulation"
+          ],
+          mcpTools: [
+            "calc_motor"
+          ]
+        },
         {
           id: "2026-07-24-visionos-app",
           version: "0.9.4",
@@ -64103,6 +64176,7 @@ async function calcMotor(args) {
   let bGap = num2(args.airgap_flux_tesla);
   let bGapSource = "supplied";
   let magnetSpec;
+  let solution = null;
   let fringing;
   if (!Number.isFinite(bGap)) {
     const m = args.magnet ?? {};
@@ -64116,15 +64190,55 @@ async function calcMotor(args) {
       gapAreaMm2: mnum(m.gap_area_mm2, 1),
       ironMuRel: typeof m.iron_mu_rel === "number" ? m.iron_mu_rel : null,
       ironPathMm: mnum(m.iron_path_mm, 0),
-      ironAreaMm2: mnum(m.iron_area_mm2, 1)
-    };
-    const computed = await airgapFluxDensity(magnetSpec);
-    if (computed == null) {
-      return fail2(
-        "air-gap flux is required: pass airgap_flux_tesla, or `magnet` params (ECAD WASM must be available to compute B_gap)."
-      );
+      ironAreaMm2: mnum(m.iron_area_mm2, 1),
+      ironJsT: typeof m.iron_js_t === "number" ? m.iron_js_t : null
+    };
+    if (m.slots !== void 0) {
+      const slots = num2(m.slots);
+      if (!(slots > 0)) return fail2("magnet.slots must be > 0");
+      const meanR = Number.isFinite(num2(m.mean_radius_mm)) ? num2(m.mean_radius_mm) : (innerR + outerR) / 2;
+      const pitch = 2 * Math.PI * meanR / slots;
+      let toothW = num2(m.tooth_width_mm);
+      if (!Number.isFinite(toothW)) {
+        const frac = num2(m.tooth_fraction);
+        if (!Number.isFinite(frac)) {
+          return fail2("magnet.slots requires magnet.tooth_width_mm or magnet.tooth_fraction");
+        }
+        if (!(frac > 0 && frac <= 1)) return fail2("magnet.tooth_fraction must be in (0, 1]");
+        toothW = frac * pitch;
+      }
+      if (!(toothW > 0)) return fail2("magnet.tooth_width_mm must be > 0");
+      magnetSpec.teeth = {
+        slots,
+        toothWidthMm: toothW,
+        meanRadiusMm: meanR,
+        toothPathMm: mnum(m.tooth_path_mm, 0)
+      };
+    }
+    solution = await airgapSolve(magnetSpec);
+    if (solution == null) {
+      const computed = await airgapFluxDensity(magnetSpec);
+      if (computed == null) {
+        return fail2(
+          "air-gap flux is required: pass airgap_flux_tesla, or `magnet` params (ECAD WASM must be available to compute B_gap)."
+        );
+      }
+      const t2 = magnetSpec.teeth;
+      const k = t2 ? Math.max(1, 2 * Math.PI * t2.meanRadiusMm / t2.slots / t2.toothWidthMm) : null;
+      solution = {
+        bGapTesla: computed,
+        bToothTesla: k == null ? null : computed * k,
+        bIronTesla: null,
+        toothConcentration: k,
+        nonlinear: false,
+        iterations: 0,
+        converged: true,
+        warnings: k != null && computed * k > SILICON_STEEL_KNEE_T ? [
+          `tooth flux density ${(computed * k).toFixed(2)} T exceeds the ${SILICON_STEEL_KNEE_T.toFixed(2)} T knee \u2014 the LINEAR iron model over-predicts B_gap and Kt here; pass magnet.iron_js_t to solve the saturating network`
+        ] : []
+      };
     }
-    bGap = computed;
+    bGap = solution.bGapTesla;
     bGapSource = "computed";
     if (m.pole_width_mm !== void 0) {
       const poleW = num2(m.pole_width_mm);
@@ -64196,6 +64310,24 @@ async function calcMotor(args) {
         })
       );
     }
+    if (solution?.bToothTesla != null && magnetSpec.teeth) {
+      claims.push(
+        emClaim(
+          "tooth_flux_density",
+          r4(solution.bToothTesla),
+          "T",
+          solution.nonlinear ? "mec-saturating-iron" : "mec-tooth-concentration",
+          {
+            ...mecInputs,
+            slots: magnetSpec.teeth.slots,
+            tooth_width_mm: r4(magnetSpec.teeth.toothWidthMm),
+            mean_radius_mm: r4(magnetSpec.teeth.meanRadiusMm),
+            tooth_concentration: r4(solution.toothConcentration ?? 1),
+            ...magnetSpec.ironJsT != null ? { iron_js_t: magnetSpec.ironJsT } : {}
+          }
+        )
+      );
+    }
   }
   return {
     content: [
@@ -64211,6 +64343,16 @@ async function calcMotor(args) {
             fringing_derate: r4(fringing.derate),
             fringing_note: "Carter-like first-order derate: B under the pole drops by w/(w+2g) as flux fringes ~one gap length past each pole edge. Kt/Ke and the curve use the DERATED flux. Honest for pole width \u2273 2\xD7 gap; below that treat it as a lower bound."
           } : {},
+          ...solution?.bToothTesla != null ? {
+            tooth_flux_tesla: r4(solution.bToothTesla),
+            tooth_concentration: r4(solution.toothConcentration ?? 1),
+            // Fringing redistributes flux under the pole; it does not remove
+            // it, so the tooth carries the RAW gap flux either way.
+            tooth_note: "B_tooth = raw B_gap \xB7 (tooth pitch / tooth width) \u2014 the gap flux of a whole tooth pitch funnels into one tooth body. Compare against your steel's knee (~1.5-1.7 T for M19-class silicon steel)."
+          } : {},
+          ...solution?.bIronTesla != null ? { yoke_flux_tesla: r4(solution.bIronTesla) } : {},
+          ...solution?.nonlinear ? { iron_model: "saturating (arctangent B-H)" } : {},
+          ...solution && solution.warnings.length > 0 ? { warnings: solution.warnings } : {},
           winding_factor: windingFactor,
           kt_nm_per_a: r4(perf.ktNmPerA),
           ke_v_s_per_rad: r4(perf.keVSPerRad),
@@ -64221,7 +64363,7 @@ async function calcMotor(args) {
             speed_rad_s: r4(p.speedRadS),
             torque_nm: r4(p.torqueNm)
           })),
-          note: fringing ? "First-order steady-state estimate (no slotting/saturation/losses; pole-edge fringing derated via magnet.pole_width_mm)." : "First-order steady-state estimate (no slotting/fringing/saturation/losses; pass magnet.pole_width_mm to derate for fringing).",
+          note: "First-order steady-state estimate (no slotting, no losses)" + (fringing ? "; pole-edge fringing derated via magnet.pole_width_mm" : "; pass magnet.pole_width_mm to derate for fringing") + (solution?.nonlinear ? "; iron solved with its saturating B-H law" : "; iron is LINEAR, so Kt is OPTIMISTIC on a machine whose teeth saturate \u2014 " + (solution?.bToothTesla != null ? "see tooth_flux_tesla, and pass magnet.iron_js_t to solve the saturating network" : "pass magnet.slots + tooth_width_mm to see the tooth field")) + ".",
           claims
         })
       }
@@ -65693,7 +65835,7 @@ async function fixDrc(args) {
   };
   return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
-var PCB_LAYER_SET, COPPER_LAYERS, COPPER_LAYER_SET, POSITION_TOLERANCE, PIN_SEP, pinKey, createSchematicSchema, docInputProperties, placeComponentsSchema, routeNetsSchema, runDrcSchema, runErcSchema, critiqueRouteSchema, routeDiffPairSchema, lengthMatchTracesSchema, exportGerberSchema, validateForFabSchema, fabPrepSchema, exportKicadSchema, addCoilSchema, boardFromSolidSchema, addCoilArraySchema, windingLayoutSchema, calcImpedanceSchema, sizeImpedanceSchema, sizePdnSchema, calcCoilSchema, sizeCoilSchema, calcRfSchema, COIL_GEOMETRY, MU0, RAIL_PIN_NAMES, PIN_TYPES, CHIP_SIZE_CODES, CONNECTIVITY_GUARD_MAX_NETS, POWER_NET_RE, DRC_CATEGORY, DRC_DELTA_SAMPLE_CAP, DRC_DELTA_FULL_BOARD_MAX, LINT_CRYSTAL_MAX_MM, LINT_DECAP_MAX_MM, LINT_CONNECTOR_EDGE_MAX_MM, LINT_HIGH_CURRENT_SEP_MIN_MM, LINT_GROUND_NET_RE, LINT_SUPPLY_NET_RE, SENSITIVE_NET_RE, HIGH_CURRENT_CLASS_RE, refPrefix, dist2d, round2, sumSq, round33, vec2Schema, setBoardOutlineSchema, FOOTPRINT_FAMILIES, listFootprintsSchema, searchFootprintsSchema, getPadPositionsSchema, getFootprintSchema, ROTATION_CONVENTION, describePcbSchema, DESCRIBE_NET_NAME_CAP, addTraceSchema, addViaSchema, OZ_TO_MM, setStackupSchema, setPlacementSchema, addZoneSchema, deleteElementProps, deleteZoneSchema, deleteTraceSchema, deleteViaSchema, COPPER_KINDS, GET_COPPER_CAP, getCopperSchema, TIE_POSITION_TOL, addNetTieSchema, deleteNetTieSchema, undoSchema, setDesignRulesSchema, sizeTraceForCurrentSchema, addViaArraySchema, MAX_VIA_ARRAY, addMotorWindingSchema, calcMotorSchema, sig6, BEARING_FRICTION_MNM, checkSelfStartSchema, solidFromBoardSchema, FR4_DENSITY_KG_M3, COPPER_DENSITY_KG_M3, DEFAULT_COPPER_THICKNESS_MM, loopArea, MOUNTING_FP_RE, KEEPOUT_ECHO_CAP, INLINE_DOC_ECHO_CAP, searchElectronicPartsSchema, resolvePartSchema, findAlternativesSchema, verifySubstitutionSchema, buildReceiptSchema, verifyReceiptSchema, FIX_EPS, FIX_DRC_NEVER, fixDrcSchema, toolDefs20;
+var PCB_LAYER_SET, COPPER_LAYERS, COPPER_LAYER_SET, POSITION_TOLERANCE, PIN_SEP, pinKey, createSchematicSchema, docInputProperties, placeComponentsSchema, routeNetsSchema, runDrcSchema, runErcSchema, critiqueRouteSchema, routeDiffPairSchema, lengthMatchTracesSchema, exportGerberSchema, validateForFabSchema, fabPrepSchema, exportKicadSchema, addCoilSchema, boardFromSolidSchema, addCoilArraySchema, windingLayoutSchema, calcImpedanceSchema, sizeImpedanceSchema, sizePdnSchema, calcCoilSchema, sizeCoilSchema, calcRfSchema, COIL_GEOMETRY, MU0, RAIL_PIN_NAMES, PIN_TYPES, CHIP_SIZE_CODES, CONNECTIVITY_GUARD_MAX_NETS, POWER_NET_RE, DRC_CATEGORY, DRC_DELTA_SAMPLE_CAP, DRC_DELTA_FULL_BOARD_MAX, LINT_CRYSTAL_MAX_MM, LINT_DECAP_MAX_MM, LINT_CONNECTOR_EDGE_MAX_MM, LINT_HIGH_CURRENT_SEP_MIN_MM, LINT_GROUND_NET_RE, LINT_SUPPLY_NET_RE, SENSITIVE_NET_RE, HIGH_CURRENT_CLASS_RE, refPrefix, dist2d, round2, sumSq, round33, vec2Schema, setBoardOutlineSchema, FOOTPRINT_FAMILIES, listFootprintsSchema, searchFootprintsSchema, getPadPositionsSchema, getFootprintSchema, ROTATION_CONVENTION, describePcbSchema, DESCRIBE_NET_NAME_CAP, addTraceSchema, addViaSchema, OZ_TO_MM, setStackupSchema, setPlacementSchema, addZoneSchema, deleteElementProps, deleteZoneSchema, deleteTraceSchema, deleteViaSchema, COPPER_KINDS, GET_COPPER_CAP, getCopperSchema, TIE_POSITION_TOL, addNetTieSchema, deleteNetTieSchema, undoSchema, setDesignRulesSchema, sizeTraceForCurrentSchema, addViaArraySchema, MAX_VIA_ARRAY, addMotorWindingSchema, calcMotorSchema, SILICON_STEEL_KNEE_T, sig6, BEARING_FRICTION_MNM, checkSelfStartSchema, solidFromBoardSchema, FR4_DENSITY_KG_M3, COPPER_DENSITY_KG_M3, DEFAULT_COPPER_THICKNESS_MM, loopArea, MOUNTING_FP_RE, KEEPOUT_ECHO_CAP, INLINE_DOC_ECHO_CAP, searchElectronicPartsSchema, resolvePartSchema, findAlternativesSchema, verifySubstitutionSchema, buildReceiptSchema, verifyReceiptSchema, FIX_EPS, FIX_DRC_NEVER, fixDrcSchema, toolDefs20;
 var init_ecad2 = __esm({
   "src/tools/ecad.ts"() {
     "use strict";
@@ -67105,7 +67247,7 @@ var init_ecad2 = __esm({
         },
         magnet: {
           type: "object",
-          description: "PM mode: optional magnet/geometry to compute B_gap when airgap_flux_tesla is omitted (NdFeB defaults). Fields: remanence_tesla, magnet_thickness_mm, airgap_mm, recoil_mu_rel, magnet_area_mm2, gap_area_mm2, iron_mu_rel. Add pole_width_mm (magnet pole face width across the fringing direction) to also apply the first-order Carter-like fringing derate w/(w+2g) \u2014 the tool then reports raw AND derated B and uses the derated value for Kt."
+          description: "PM mode: optional magnet/geometry to compute B_gap when airgap_flux_tesla is omitted (NdFeB defaults). Fields: remanence_tesla, magnet_thickness_mm, airgap_mm, recoil_mu_rel, magnet_area_mm2, gap_area_mm2, iron_mu_rel. Add pole_width_mm (magnet pole face width across the fringing direction) to also apply the first-order Carter-like fringing derate w/(w+2g) \u2014 the tool then reports raw AND derated B and uses the derated value for Kt. SATURATION: the MEC iron is LINEAR unless you say otherwise, so it over-predicts Kt on a machine whose teeth saturate. Pass slots + (tooth_width_mm or tooth_fraction) to make the teeth visible \u2014 the tool then reports tooth_flux_density (B_gap \xB7 pitch/width, routinely 2x B_gap) and warns when it passes the ~1.5 T silicon-steel knee. Add iron_js_t (saturation polarization, silicon steel \u2248 2.0 T) with iron_mu_rel to actually SOLVE the saturating network instead of merely warning; tooth_path_mm puts the teeth in the reluctance loop."
         },
         phase_current_a: { type: "number", description: "Induction mode (required): phase current, A RMS (balanced 3-phase drive)." },
         electrical_freq_hz: { type: "number", description: "Induction mode (required): electrical drive frequency, Hz." },
@@ -67124,6 +67266,7 @@ var init_ecad2 = __esm({
       },
       required: ["pole_pairs", "turns_per_phase"]
     };
+    SILICON_STEEL_KNEE_T = 1.5;
     sig6 = (v) => v === 0 || !Number.isFinite(v) ? v : Number(v.toPrecision(6));
     BEARING_FRICTION_MNM = {
       "608-2RS": {
@@ -74088,6 +74231,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 +74284,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 +74308,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 +74377,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 +74418,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 +74454,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 +74515,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 +74524,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 +74592,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 +74625,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 +74643,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 +74654,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 +74685,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 +74740,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 +74770,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 +74809,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 +74820,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 +74828,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 +74836,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 +74852,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 +78139,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 +78990,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.28") {
+        return "0.9.4-main.28";
       }
       try {
         const req = createRequire2(import.meta.url);
@@ -78737,8 +79000,8 @@ var init_server3 = __esm({
         return "0.0.0";
       }
     })();
-    BUILD_SHA = "178040b8a9aaccb709684c5b95e4fb42a00ae9e2";
-    BUILD_TIME = "2026-07-25T23:14:00.956Z";
+    BUILD_SHA = "301abfbddc2a05c29fabc9f655031e554eab1d04";
+    BUILD_TIME = "2026-07-26T00:32:29.039Z";
     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.28",
   "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": "301abfbddc2a05c29fabc9f655031e554eab1d04",
+    "builtAt": "2026-07-26T00:32:29.039Z"
   }
 }