bambu-printer-mcp 1.1.28 → 1.1.30

package/src/printers/bambu.ts

@@ -7,7 +7,8 @@ import os from "node:os";
 import { Readable } from "node:stream";
 import { readSafe3mfArchive } from "../safety/archive.js";
 import { inspectPrintFile, type PrintFileInspection } from "../safety/print-file.js";
-import { normalizeModel, validateTemperature } from "../safety/limits.js";
+import { isDualNozzleModel, normalizeModel, validateTemperature } from "../safety/limits.js";
+import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, describeAmsTrayRange } from "../ams-mapping.js";
 import { describeHmsKey, hiddenHmsKeys, hiddenHmsNotices, reportedHmsKey, validatePrinterState, manualHeatingRequirements, type PrinterStateRequirements } from "../safety/printer-state.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName, normalizedRemotePath, cancelPendingPrinterOperations } from "../safety/artifact.js";
 import { Client as FTPClient } from "basic-ftp";
@@ -437,6 +438,12 @@ class BambuClientStore {
     }
   }
 
+  forgetPrinter(printer: BambuClient): void {
+    for (const [key, cached] of this.printers) {
+      if (cached === printer) this.clearPrinterState(key);
+    }
+  }
+
   async disconnectAll(): Promise<void> {
     const disconnectPromises: Promise<void>[] = [];
 
@@ -747,15 +754,20 @@ export class BambuImplementation {
     // `plate_N.json.filament_ids` -- and expand to a full project-level
     // array here. `amsMapping` is the raw escape hatch (takes precedence
     // when both are supplied).
+    // Dual-nozzle printers address two external spools: 254 feeds the left/deputy
+    // nozzle and 255 the right/main nozzle (Bambu Studio VIRTUAL_TRAY_DEPUTY_ID /
+    // VIRTUAL_TRAY_MAIN_ID). Single-nozzle printers keep 254 as the only external tray.
+    const dualNozzle = isDualNozzleModel(model);
+    const externalTrays = dualNozzle ? [254, 255] : [254];
     const validateTrayValue = (v: unknown, label: string): void => {
       if (
         !Number.isInteger(v) ||
         (v as number) < -1 ||
         ((v as number) > 15 && (v as number) < 128) ||
-        (v as number) > 254
+        (v as number) > (dualNozzle ? 255 : 254)
       ) {
         throw new Error(
-          `${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${v}`
+          `${label} values must be integers in ${describeAmsTrayRange({ dualNozzle })}; got ${v}`
         );
       }
     };
@@ -794,7 +806,7 @@ export class BambuImplementation {
       );
       baseMapping = Array<number>(projectLen).fill(-1);
       positions.forEach((pos, i) => {
-        baseMapping[pos] = options.useAMS === false ? 254 : i;
+        baseMapping[pos] = options.useAMS === false ? externalTrayForNozzle(inspection.filamentNozzleIndices?.[pos], dualNozzle) : i;
       });
     }
 
@@ -805,12 +817,7 @@ export class BambuImplementation {
       amsMapping = Array.from({ length: projLen }, (_, i) =>
         i < baseMapping.length ? baseMapping[i] : -1
       );
-      amsMapping2 = amsMapping.map((v) => {
-        if (v < 0 || v === 255) return { ams_id: 255, slot_id: 255 };
-        if (v === 254) return { ams_id: 254, slot_id: 254 };
-        if (v >= 128) return { ams_id: 128, slot_id: v - 128 };
-        return { ams_id: Math.floor(v / 4), slot_id: v % 4 };
-      });
+      amsMapping2 = amsMapping.map((v) => bridgeAmsMapping2Entry(v, dualNozzle));
     } else {
       amsMapping = Array.from({ length: Math.max(5, baseMapping.length, projectMetadata.projectFilamentCount) }, (_, i) =>
         i < baseMapping.length ? baseMapping[i] : -1
@@ -822,8 +829,8 @@ export class BambuImplementation {
       if (baseMapping[position] === undefined || baseMapping[position] < 0) {
         throw new Error(`Missing physical filament mapping for project filament ${position}.`);
       }
-      if (options.useAMS === false && baseMapping[position] !== 254) {
-        throw new Error("External-spool printing requires external spool mapping (254).");
+      if (options.useAMS === false && !externalTrays.includes(baseMapping[position])) {
+        throw new Error(`External-spool printing requires external spool mapping (${externalTrays.join(" or ")}).`);
       }
     }
     const legacyContainer = options.filePath.toLowerCase().endsWith(".gcode.3mf") && !usesH2ProjectFile && !isA1;
@@ -898,7 +905,7 @@ export class BambuImplementation {
           project_id: submissionId,
           subtask_id: submissionId,
           task_id: submissionId,
-          ams_mapping: amsMapping,
+          ams_mapping: amsMapping.map(value => bridgeAmsMappingValue(value, dualNozzle)),
           ams_mapping2: amsMapping2,
         },
       };
@@ -963,18 +970,50 @@ export class BambuImplementation {
     }
   }
 
+  private async invokeEmergencyCommand(
+    printer: BambuClient,
+    command: { invoke(client: BambuClient): Promise<void> },
+    signal?: AbortSignal
+  ): Promise<void> {
+    if (!signal) return invokeWithoutAck(printer, command);
+    let onAbort: () => void;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        onAbort = () => {
+          // Force-close the actual transport: a raced publish may be queued
+          // inside MQTT.js and otherwise dispatch after a later reconnect.
+          this.printerStore.forgetPrinter(printer);
+          void printer.disconnect(true).catch(() => {
+            console.error("Failed to close an expired emergency MQTT client.");
+          });
+          reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) onAbort();
+        else command.invoke(printer).then(resolve, reject);
+      });
+    } finally {
+      signal.removeEventListener("abort", onAbort!);
+    }
+    await sleep(COMMAND_SETTLE_MS);
+  }
+
   /** Raw MQTT stop for routes that already ran the shared cancellation steps. */
-  async sendStopOverMqtt(host: string, serial: string, token: string): Promise<any> {
+  async sendStopOverMqtt(host: string, serial: string, token: string, signal?: AbortSignal): Promise<any> {
+    signal?.throwIfAborted();
     const printer = await this.getPrinter(host, serial, token);
-    await invokeWithoutAck(printer, new UpdateStateCommand({ state: "stop" }));
+    signal?.throwIfAborted();
+    await this.invokeEmergencyCommand(printer, new UpdateStateCommand({ state: "stop" }), signal);
     return { status: "success", message: "Cancel command sent over MQTT." };
   }
 
   /** Raw MQTT heater-off; switching off needs no material or model declaration. */
-  async sendHeaterOffOverMqtt(host: string, serial: string, token: string, heater: "bed" | "nozzle"): Promise<any> {
+  async sendHeaterOffOverMqtt(host: string, serial: string, token: string, heater: "bed" | "nozzle", signal?: AbortSignal): Promise<any> {
+    signal?.throwIfAborted();
     const printer = await this.getPrinter(host, serial, token);
+    signal?.throwIfAborted();
     const gcode = `${heater === "bed" ? "M140" : "M104"} S0`;
-    await invokeWithoutAck(printer, new GCodeLineCommand({ gcodes: [gcode] }));
+    await this.invokeEmergencyCommand(printer, new GCodeLineCommand({ gcodes: [gcode] }), signal);
     return { status: "success", message: `Heater-off sent over MQTT for ${heater}.`, command: gcode };
   }
 

package/src/safety/limits.ts

@@ -31,6 +31,15 @@ export const MACHINE_LIMITS: Readonly<Record<string, {nozzle: number; bed: numbe
   x2d: {nozzle:300,bed:120,chamber:65,volume:[256,256,260]},
 };
 
+/** Printers with two physical nozzles. Bambu Studio numbers the right/main nozzle 0
+ * (MAIN_EXTRUDER_ID) and the left/deputy nozzle 1 (DEPUTY_EXTRUDER_ID), and reports one
+ * virtual external-spool slot per nozzle: 255 (VIRTUAL_TRAY_MAIN_ID) and 254
+ * (VIRTUAL_TRAY_DEPUTY_ID). The single-nozzle H2S is deliberately absent. */
+export const DUAL_NOZZLE_MODELS: ReadonlySet<string> = new Set(['h2d','h2dpro','h2c','x2d']);
+export function isDualNozzleModel(model: unknown): boolean {
+  const normalized = normalizeModel(model);
+  return normalized !== undefined && DUAL_NOZZLE_MODELS.has(normalized);
+}
 export function normalizeModel(value: unknown): string | undefined {
   if (typeof value !== 'string') return undefined;
   let model = value.trim().toLowerCase().replace(/^bambu\s*(?:lab\s*)?/, '').replace(/[\s_-]/g, '');

package/src/safety/print-file.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 
 export interface PrintFileInspection {
   model: string;
@@ -16,6 +16,8 @@ export interface PrintFileInspection {
   selectsAms: boolean;
   nozzleTypes?: string[];
   nozzleFlows?: string[];
+  /** Physical nozzle index for each declared filament, composed from the selected plate headers. */
+  filamentNozzleIndices?: number[];
 }
 type Metadata = Record<string, unknown>;
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
@@ -140,6 +142,7 @@ function validateBounds(headers: Metadata[], model: string, plate: Metadata): vo
 export async function inspectPrintFile(filePath: string, options: {model:string; nozzleDiameters?:number[]; plateIndex?:number; bedType?:string}): Promise<PrintFileInspection> {
   const model=normalizeModel(options.model);
   if(!model) return fail(`unknown or missing printer model '${options.model}'`);
+  const dualNozzle=isDualNozzleModel(model);
   const plateIndex=options.plateIndex ?? 0;
   if(!Number.isInteger(plateIndex)||plateIndex<0) return fail('selected plate index must be a nonnegative integer');
   if(/\.md5$/i.test(filePath)) return fail('a checksum file is not a printable artifact');
@@ -237,6 +240,22 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
   const materials=consistent(metadataValues(metadata,['filament_type']),value=>{
     const values=list(value);return values.length && values.every(v=>!!normalizeMaterial(v))?values.map(v=>normalizeMaterial(v)!):undefined;
   },'filament material');
+  // GCode.cpp uses 1-based filament_map logical extruders and then indexes
+  // physical_extruder_map to select the physical nozzle. Only this selected
+  // plate's headers establish that binding; unsliced project defaults do not.
+  const headerMap=(key:string,count:number,low:number,high:number):number[]|undefined=>{
+    const values=metadataValues(headers,[key]);
+    if(!values.length) return undefined;
+    return consistent(values,value=>{
+      const entries=list(value);
+      return entries.length===count && entries.every(v=>NUMBER.test(v) && Number.isInteger(Number(v)) && Number(v)>=low && Number(v)<=high)
+        ? entries.map(Number):undefined;
+    },key.replace(/_/g,' '));
+  };
+  const physicalExtruderMap=headerMap('physical_extruder_map',nozzleDiameters.length,0,dualNozzle?Math.min(nozzleDiameters.length,2)-1:nozzleDiameters.length-1);
+  if(physicalExtruderMap && new Set(physicalExtruderMap).size!==physicalExtruderMap.length) fail('physical extruder map must be a complete permutation');
+  const filamentMap=headerMap('filament_map',materials.length,1,nozzleDiameters.length);
+  const filamentNozzleIndices=filamentMap && physicalExtruderMap ? filamentMap.map(logical=>physicalExtruderMap[logical-1]):undefined;
   const bedValues=metadataValues([...metadata,plate],['curr_bed_type','bed_type']);
   const bedType=bedValues.length?consistent(bedValues,normalizeBed,'bed type'):undefined;
   if(options.bedType && (!bedType || normalizeBed(options.bedType)!==bedType)) return fail('selected bed type cannot be verified or contradicts the sliced file; re-slice with the intended bed');
@@ -278,7 +297,10 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
     try {
       if(isLayerMarker(lines[index]) || /^\s*;\s*MACHINE_START_GCODE_END\s*$/i.test(lines[index])) closeStartupWindow();
       let line=stripComments(lines[index]);if(!line||line==='%') continue;
-      // The official H2C template emits this literal separator without a semicolon.
+      // Accept only the exact vendor banners in their documented model/scope.
+      // X2D emits its filament-change banner throughout a print; H2C's record
+      // separator stays inside its explicitly bounded startup block.
+      if(line==='======== X2D filament_change gcode ==========' && model==='x2d') continue;
       if(line==='========== record data ==========' && h2cStartup(index)) continue;
       line=line.replace(/^N\d+\s*/i,'').replace(/\*\d+\s*$/,'');
       if(/[{}\[\]#]/.test(line)) fail('unresolved dynamic command syntax');
@@ -355,17 +377,23 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
           heat('bed',args.get('D')!,undefined,true);continue;
         }
         const vendorWait=code==='M109' && ['a1','a1mini'].includes(model);
-        for(const key of args.keys()) if(!'SRTA'.includes(key) && !(key==='H' && vendorWait)) fail(`unsupported ${code} temperature parameter ${key}`);
+        // Bambu Studio addresses a physical nozzle on dual-nozzle machines with N<index>
+        // (X2D `M104 T1 S25 N0` multi-extruder pre-cooling and wipe-tower reheats).
+        // N selects a nozzle, never a target, so it is accepted only on those models,
+        // only for nozzle heaters, and only within the declared nozzle count.
+        const nozzleIndex=['M104','M109'].includes(code) && dualNozzle;
+        for(const key of args.keys()) if(!'SRTA'.includes(key) && !(key==='H' && vendorWait) && !(key==='N' && nozzleIndex)) fail(`unsupported ${code} temperature parameter ${key}`);
+        if(args.has('N') && (!Number.isInteger(args.get('N')) || args.get('N')!<0 || args.get('N')!>=Math.min(nozzleDiameters.length,2))) fail(`unsupported ${code} nozzle index N`);
         if(args.has('H') && (!Number.isFinite(args.get('H')) || args.get('H')!<0 || args.get('H')!>300)) fail(`unsupported ${code} wait parameter H`);
         if(!args.has('S')&&!args.has('R')) fail(`missing ${code} temperature target`);
         const component= ['M104','M109'].includes(code)?'nozzle': ['M140','M190'].includes(code)?'bed':'chamber';
         // Heater T is a physical nozzle, unlike standalone remapped T filament selection.
         // Without a verified per-filament nozzle map, apply all possible materials.
         if(args.has('T') && (!Number.isInteger(args.get('T')) || args.get('T')!<0 || args.get('T')!>=nozzleDiameters.length)) fail('physical heater target has no declared nozzle');
-        const position= args.has('T') ? undefined : active;
+        const position= args.has('T') || args.has('N') ? undefined : active;
         const commonFlush=code==='M109' && args.size===1 && args.get('S')===290 && model==='x1e' && !depositionStarted && !commonFlushUsed && boundedX1ePurge(lines,index);
         if(commonFlush) commonFlushUsed=true;
-        for(const key of ['S','R']) if(args.has(key)) heat(component,args.get(key)!,position,args.has('T') || args.has('A'),commonFlush);
+        for(const key of ['S','R']) if(args.has(key)) heat(component,args.get(key)!,position,args.has('T') || args.has('N') || args.has('A'),commonFlush);
       } else if(code==='M620' || code==='M621') {
         const args=parameters(argumentsText,model==='x2d'?'MAB':model==='h2c'?'MAN':'MA');
         if(args.has('N') && (code!=='M620' || !h2cStartup(index) || args.size!==1 || !Number.isNaN(args.get('N')!))) fail('unsupported H2C startup hotend-remap flag');
@@ -464,5 +492,5 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
   }
   if(!commandCount) return fail('selected G-code contains no printable commands');
   if(!used.size) materials.forEach((_,index)=>used.add(index));
-  return {model,nozzleDiameters,materials,usedFilamentPositions:[...used].sort((a,b)=>a-b),plateInternalPath,sha256,maxNozzleTemperature,maxBedTemperature,maxChamberTemperature,bedType,selectsAms,nozzleTypes,nozzleFlows};
+  return {model,nozzleDiameters,materials,usedFilamentPositions:[...used].sort((a,b)=>a-b),plateInternalPath,sha256,maxNozzleTemperature,maxBedTemperature,maxChamberTemperature,bedType,selectsAms,nozzleTypes,nozzleFlows,filamentNozzleIndices};
 }

package/src/safety/printer-state.ts

@@ -1,6 +1,6 @@
 import { HIDDEN_HMS } from "./hidden-hms.js";
 import { BambuClient, GetVersionCommand, PushAllCommand } from "bambu-node";
-import { normalizeMaterial, normalizeModel } from "./limits.js";
+import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
 
 const MAX_REPORT_AGE_MS = 15_000;
 const MODEL_IDS: Record<string, string> = {
@@ -103,6 +103,8 @@ export interface PrinterStateRequirements {
   nozzleDiameters: number[];
   materials?: string[];
   usedFilamentPositions?: number[];
+  /** Verified physical nozzle index for each project filament, composed from the inspected plate mappings. */
+  filamentNozzleIndices?: number[];
   amsMapping?: number[];
   useAMS?: boolean;
   requireIdle?: boolean;
@@ -280,13 +282,20 @@ function trayRange(value: unknown, label: string): number | undefined {
   if (number === undefined || number <= 0) throw new Error(`Reported filament ${label} temperature is malformed.`);
   return number;
 }
-function externalTray(raw: Record<string,any>): Record<string,any> | undefined {
+/** Dual-nozzle printers report one virtual external slot per nozzle, numbered as Bambu
+ * Studio does (VIRTUAL_TRAY_MAIN_ID 255 = right/main nozzle, VIRTUAL_TRAY_DEPUTY_ID 254 =
+ * left/deputy nozzle), so the requested tray selects its slot. Single-nozzle printers keep
+ * requiring exactly one slot 254 report, then the legacy vt_tray field. */
+function externalTray(raw: Record<string,any>, trayIndex: number, model: string): Record<string,any> | undefined {
   const slots = raw.vir_slot;
+  const dualNozzle = isDualNozzleModel(model);
   if (Array.isArray(slots)) {
-    const selected = slots.filter((slot:any) => Number(slot?.id) === 254);
-    if (slots.length === 1 && selected.length === 1) return selected[0];
+    const selected = slots.filter((slot:any) => Number(slot?.id) === trayIndex);
+    if (selected.length === 1 && (dualNozzle || slots.length === 1)) return selected[0];
+    if (dualNozzle && selected.length === 0 && slots.length > 0) throw new Error(`External spool ${trayIndex} is not in the fresh per-nozzle report; cannot verify the selected material.`);
     if (slots.length > 0) throw new Error("External spool report is ambiguous for this nozzle; cannot verify the selected material.");
   }
+  if (dualNozzle) throw new Error(`Dual-nozzle external spool ${trayIndex} requires a fresh per-nozzle vir_slot report; legacy vt_tray cannot verify the selected nozzle.`);
   return object(raw.vt_tray) ? raw.vt_tray : undefined;
 }
 function mappedTray(raw: Record<string,any>, index: number): Record<string,any> {
@@ -332,7 +341,7 @@ export function validatePrinterState(status: any, requirements: PrinterStateRequ
     }
   }
   const nozzles = requirements.nozzleDiameters.length ? reportedNozzles(raw) : [];
-  if (requirements.nozzleDiameters.length && ["h2d","h2dpro","h2c","x2d"].includes(model) &&
+  if (requirements.nozzleDiameters.length && isDualNozzleModel(model) &&
       !Array.isArray(raw.device?.nozzle?.info) && !Array.isArray(raw.nozzle_diameter)) {
     throw new Error("A scalar legacy nozzle report is ambiguous for this multi-nozzle printer; fresh per-nozzle configuration is required.");
   }
@@ -360,13 +369,27 @@ export function validatePrinterState(status: any, requirements: PrinterStateRequ
   if (requirements.verifyMaterials !== false && (requirements.materials !== undefined || requirements.nozzleDiameters.length)) {
     const materials = requirements.materials ?? [];
     const positions = requirements.usedFilamentPositions ?? materials.map((_, index) => index);
+    // 255 is the right/main nozzle external spool only on dual-nozzle printers.
+    const dualNozzle = isDualNozzleModel(model);
+    const maxTray = dualNozzle ? 255 : 254;
     if (!positions.length) throw new Error("A declared material is required for each used filament or external spool.");
     for (const position of positions) {
       const material = normalizeMaterial(materials[position]);
       if (!Number.isInteger(position) || position < 0 || !material) throw new Error(`A known declared material is required for filament position ${position}.`);
-      const trayIndex = requirements.useAMS ? requirements.amsMapping?.[position] : 254;
-      if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > 254) throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
-      const tray = trayIndex === 254 ? externalTray(raw) : mappedTray(raw,trayIndex);
+      const physicalNozzle = requirements.filamentNozzleIndices?.[position];
+      const externalForNozzle = physicalNozzle === 0 ? 255 : physicalNozzle === 1 ? 254 : undefined;
+      const trayIndex = requirements.useAMS || requirements.amsMapping !== undefined
+        ? requirements.amsMapping?.[position] : dualNozzle ? externalForNozzle : 254;
+      if (!requirements.useAMS && dualNozzle && requirements.amsMapping === undefined && externalForNozzle === undefined) {
+        throw new Error(`External spool for filament position ${position} is ambiguous; re-slice with complete filament_map and physical_extruder_map nozzle bindings or provide a verified sliced plate.`);
+      }
+      if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > maxTray) throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
+      if (!requirements.useAMS && trayIndex < 254) throw new Error("External-spool printing requires an external spool mapping; AMS trays require use_ams:true.");
+      if (dualNozzle && trayIndex >= 254) {
+        if (externalForNozzle === undefined) throw new Error(`External spool ${trayIndex} needs a verified physical nozzle binding for filament position ${position}; re-slice with complete filament_map and physical_extruder_map metadata.`);
+        if (trayIndex !== externalForNozzle) throw new Error(`External spool ${trayIndex} does not feed physical nozzle ${physicalNozzle} for filament position ${position}; use spool ${externalForNozzle}.`);
+      }
+      const tray = trayIndex >= 254 ? externalTray(raw,trayIndex,model) : mappedTray(raw,trayIndex);
       const reportedType = typeof tray?.tray_type === "string" ? tray.tray_type.trim() : "";
       if (reportedType && normalizeMaterial(reportedType) !== material) throw new Error(`Reported material ${reportedType} in slot ${trayIndex} contradicts declared ${materials[position]}.`);
       const nozzleMin = trayRange(tray?.nozzle_temp_min,"minimum");
@@ -384,7 +407,7 @@ export function manualHeatingRequirements(status: any, model: string, nozzleDiam
   if (!normalized) throw new Error("A known printer model is required for manual nozzle heating.");
   const raw = status?.raw;
   if (!object(raw)) throw new Error("A fresh printer report is required for manual nozzle heating.");
-  if (["h2d","h2dpro","h2c","x2d"].includes(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
+  if (isDualNozzleModel(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
     throw new Error("Manual heating cannot verify the active nozzle and loaded material on this multi-nozzle printer. Use a checked sliced print instead.");
   }
   const requirements: PrinterStateRequirements = {

package/src/slicer/remote-slicer.ts

@@ -0,0 +1,216 @@
+/** AFKFelix/orca-slicer-api contract at a9a28f0a7b0c6f51b9be158509e9e9677532b868. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { inspectPrintFile } from '../safety/print-file.js';
+import { normalizeMaterial, normalizeModel } from '../safety/limits.js';
+import type { BambuSliceOptions } from '../stl/stl-manipulator.js';
+
+const MAX_BYTES = 100_000_000;
+const SUPPORTED_OPTIONS = new Set([
+  'arrange', 'orient', 'loadFilaments', 'filamentColours', 'bedType',
+  'nozzleType', 'nozzleVolumeType', 'slicePlate',
+]);
+
+function configuration(): { base: string; headers: Record<string, string>; mode: string; timeout: number } {
+  let url: URL;
+  try { url = new URL(process.env.SLICER_API_URL ?? ''); }
+  catch { throw new Error('Remote slicing requires a valid trusted SLICER_API_URL.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('SLICER_API_URL must use HTTP(S) without embedded credentials, query or fragment.');
+  }
+  const mode = process.env.SLICER_API_MODE || 'sync';
+  if (!['sync', 'async'].includes(mode)) throw new Error('SLICER_API_MODE must be sync or async.');
+  const timeout = Number(process.env.SLICER_API_TIMEOUT_MS ?? 600000);
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) {
+    throw new Error('SLICER_API_TIMEOUT_MS must be an integer from 1 to 3600000.');
+  }
+  const headers: Record<string, string> = {};
+  const token = process.env.SLICER_API_TOKEN;
+  if (token) {
+    const header = process.env.SLICER_API_TOKEN_HEADER || 'Authorization';
+    if (!/^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$/.test(header) ||
+        ['host', 'content-type', 'content-length', 'connection', 'transfer-encoding'].includes(header.toLowerCase()) ||
+        /[^\x20-\x7e]/.test(token)) {
+      throw new Error('Invalid remote slicing authentication configuration.');
+    }
+    headers[header] = header.toLowerCase() === 'authorization' ? `Bearer ${token}` : token;
+  }
+  return { base: url.href.replace(/\/+$/, ''), headers, mode, timeout };
+}
+
+export function validateRemoteSliceOptions(options: BambuSliceOptions = {}): number {
+  for (const [key, value] of Object.entries(options)) {
+    if (value !== undefined && !SUPPORTED_OPTIONS.has(key)) {
+      throw new Error(`Remote slicing option ${key} is unsupported by orca-slicer-api; use a local backend for this workflow.`);
+    }
+  }
+  // Upstream evaluates multipart values by truthiness, so the string "false"
+  // becomes true. Never silently turn an explicit false into an enabled flag.
+  if (options.arrange === false || options.orient === false) {
+    throw new Error('Remote arrange=false and orient=false are unsupported by the upstream multipart API.');
+  }
+  const plate = options.slicePlate ?? 1;
+  if (!Number.isInteger(plate) || plate < 1) throw new Error('Remote slicing requires one positive plate number; slicing all plates is unsupported.');
+  return plate;
+}
+
+/** The remote API forwards this display name to Orca's --curr-bed-type. */
+function remoteBedType(value: unknown): string {
+  const names: Record<string, string> = {
+    textured_plate: 'Textured PEI Plate', textured_pei_plate: 'Textured PEI Plate',
+    cool_plate: 'Cool Plate', engineering_plate: 'Engineering Plate',
+    hot_plate: 'High Temp Plate', high_temp_plate: 'High Temp Plate',
+  };
+  const key = typeof value === 'string' ? value.trim().toLowerCase().replace(/[\s-]+/g, '_') : '';
+  if (typeof names[key] !== 'string') throw new Error('Unsupported remote bed type; use textured_plate, cool_plate, engineering_plate, or hot_plate.');
+  return names[key];
+}
+
+async function readResponse(response: Response, limit: number): Promise<Buffer> {
+  const size = Number(response.headers.get('content-length'));
+  if (size > limit) { await response.body?.cancel(); throw new Error('Remote slicing response exceeds the size limit.'); }
+  if (!response.body) throw new Error('Remote slicing returned an empty response.');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > limit) throw new Error('Remote slicing response exceeds the size limit.');
+      chunks.push(value);
+    }
+  } finally { await reader.cancel(); }
+  return Buffer.concat(chunks);
+}
+
+async function readJob(response: Response): Promise<Record<string, unknown>> {
+  try {
+    const job: unknown = JSON.parse((await readResponse(response, 65536)).toString('utf8'));
+    if (job && typeof job === 'object' && !Array.isArray(job)) return job as Record<string, unknown>;
+  } catch { /* Do not echo an untrusted response, which may contain credentials. */ }
+  throw new Error('Remote slicing returned invalid job metadata.');
+}
+
+/** Upload only locally prepared profiles, then inspect the exact downloaded 3MF. */
+export async function sliceWithOrcaApi(input: {
+  inputPath: string;
+  machinePath: string;
+  processPath: string;
+  filamentPaths: string[];
+  outputPath: string;
+  options?: BambuSliceOptions;
+  isCancelled: () => boolean;
+}): Promise<string> {
+  const options = input.options ?? {};
+  const plate = validateRemoteSliceOptions(options);
+  if (input.filamentPaths.length !== 1 || (options.filamentColours && options.filamentColours.length !== 1)) {
+    throw new Error('orca-slicer-api supports exactly one filament slot; multi-slot projects require a local slicer.');
+  }
+  const config = configuration();
+  const machine = JSON.parse(await fs.readFile(input.machinePath, 'utf8'));
+  const filament = JSON.parse(await fs.readFile(input.filamentPaths[0], 'utf8'));
+  const processProfile = JSON.parse(await fs.readFile(input.processPath, 'utf8'));
+  const bedType = remoteBedType(options.bedType ?? processProfile.curr_bed_type ?? 'textured_plate');
+  const model = normalizeModel(machine.printer_model);
+  const nozzles = Array.isArray(machine.nozzle_diameter) ? machine.nozzle_diameter.map(Number) : [];
+  const materialValues: unknown[] = Array.isArray(filament.filament_type) ? filament.filament_type : [];
+  const materials = materialValues.map(normalizeMaterial);
+  if (!model || !nozzles.length || nozzles.some((n: number) => ![0.2, 0.4, 0.6, 0.8].includes(n)) ||
+      materials.length !== 1 || !materials[0]) {
+    throw new Error('Remote slicing requires explicit model, nozzle and single-material metadata in the prepared profiles.');
+  }
+  const controller = new AbortController();
+  let timedOut = false;
+  const deadline = setTimeout(() => { timedOut = true; controller.abort(); }, config.timeout);
+  const cancelCheck = setInterval(() => { if (input.isCancelled()) controller.abort(); }, 100);
+  let requestId: string | undefined;
+  let terminalJob = false;
+  let wroteOutput = false;
+  const request = async (route: string, init: RequestInit = {}): Promise<Response> => {
+    if (input.isCancelled()) controller.abort();
+    // Do not pass multipart data to fetch after cancellation: undici may start
+    // its body producer before checking the signal and close it mid-enqueue.
+    controller.signal.throwIfAborted();
+    let response: Response;
+    try {
+      response = await fetch(config.base + route, { ...init, headers: config.headers, signal: controller.signal, redirect: 'manual' });
+    } catch { throw new Error('Remote slicing HTTP request failed; check the trusted service configuration.'); }
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`Remote slicing HTTP ${response.status}.`); }
+    return response;
+  };
+  try {
+    const ext = path.extname(input.inputPath).toLowerCase();
+    if (!['.stl', '.3mf'].includes(ext)) throw new Error('Remote slicing supports only STL or 3MF input.');
+    const bytes = await fs.readFile(input.inputPath);
+    if (bytes.length > MAX_BYTES) throw new Error('Remote slicing input exceeds the 100 MB upstream limit.');
+    const form = new FormData();
+    form.set('file', new Blob([new Uint8Array(bytes)], { type: ext === '.3mf' ? 'model/3mf' : 'model/stl' }), `model${ext}`);
+    for (const [field, filePath, type] of [
+      ['printerProfile', input.machinePath, 'machine'],
+      ['presetProfile', input.processPath, 'process'],
+      ['filamentProfile', input.filamentPaths[0], 'filament'],
+    ]) {
+      const profile = JSON.parse(await fs.readFile(filePath, 'utf8'));
+      // The remote validator requires these metadata fields even for standalone
+      // user profiles. They do not change the resolved machine/process settings.
+      const data = { ...profile, type, from: profile.from || 'User' };
+      form.set(field, new Blob([JSON.stringify(data)], { type: 'application/json' }), `${field}.json`);
+    }
+    form.set('exportType', '3mf');
+    form.set('plate', String(plate));
+    form.set('bedType', bedType);
+    form.set('resolveProfileInheritance', 'false');
+    if (options.arrange === true) form.set('arrange', 'true');
+    if (options.orient === true) form.set('orient', 'true');
+    let response = await request(config.mode === 'async' ? '/slice-async' : '/slice', { method: 'POST', body: form });
+    if (config.mode === 'async') {
+      const submitted = await readJob(response);
+      if (typeof submitted.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(submitted.requestId)) {
+        throw new Error('Remote slicing returned an invalid request ID.');
+      }
+      requestId = submitted.requestId;
+      for (;;) {
+        // Construct the documented same-service paths. Returned URLs cannot
+        // redirect authenticated requests to an arbitrary origin or route.
+        const job = await readJob(await request(`/slice-async/${requestId}`));
+        if (job.status === 'completed' || job.status === 'failed') {
+          terminalJob = true;
+          if (job.status === 'failed') throw new Error('Remote slicing job failed; inspect the service logs.');
+          break;
+        }
+        if (job.status !== 'pending' && job.status !== 'processing') throw new Error('Remote slicing returned an unknown job state.');
+        await delay(500, undefined, { signal: controller.signal });
+      }
+      response = await request(`/slice-async/${requestId}/result`);
+    }
+    const result = await readResponse(response, MAX_BYTES);
+    await fs.writeFile(input.outputPath, result, { flag: 'wx', mode: 0o600 });
+    wroteOutput = true;
+    const inspection = await inspectPrintFile(input.outputPath, {
+      model, nozzleDiameters: nozzles, plateIndex: plate - 1, bedType,
+    });
+    if (JSON.stringify(inspection.materials) !== JSON.stringify(materials)) {
+      throw new Error('Remote sliced file materials contradict the prepared filament profile.');
+    }
+    if (input.isCancelled()) throw new Error('Remote slicing cancelled.');
+    return input.outputPath;
+  } catch (error) {
+    if (wroteOutput) await fs.rm(input.outputPath, { force: true });
+    if (controller.signal.aborted) {
+      throw new Error(`Remote slicing ${timedOut ? 'timed out' : 'cancelled'}; the remote job may continue. No retry was sent.`);
+    }
+    throw error;
+  } finally {
+    // DELETE only removes finished jobs; upstream has no active-job cancellation.
+    // Cleanup never retries submission or masks a valid result / original error.
+    if (requestId && terminalJob && !controller.signal.aborted) {
+      try { await (await request(`/slice-async/${requestId}`, { method: 'DELETE' })).body?.cancel(); }
+      catch { console.error('Remote slicing finished-job cleanup failed; service retention applies.'); }
+    }
+    clearTimeout(deadline);
+    clearInterval(cancelCheck);
+  }
+}