bambu-printer-mcp 1.1.27 → 1.1.28

package/dist/index.js

@@ -11,7 +11,7 @@ import { createServer as createHttpServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { STLManipulator, SLICER_TYPES, normalizeSlicerType, } from "./stl/stl-manipulator.js";
 import { BambuNetworkBridge } from "./bambu-network-bridge.js";
-import { assertBambuNativeAvailable, validateBambuNativeMetadata, buildBambuNativeFanCommand, buildBambuNativeTemperatureCommand, printWithBambuNative, sendCommandWithBambuNative, uploadWithBambuNative, } from "./bambu-native.js";
+import { assertBambuNativeAvailable, bambuNativeControlsAvailable, bambuNativeUnavailableReason, interruptNativeOperations, validateBambuNativeMetadata, buildBambuNativeFanCommand, buildBambuNativeTemperatureCommand, printWithBambuNative, sendCommandWithBambuNative, uploadWithBambuNative, } from "./bambu-native.js";
 import { importFileViaBambuConnect } from "./bambu-connect.js";
 import { BlenderMcpBridge } from "./blender-mcp-bridge.js";
 import { hasAmsMappingInput, normalizeAmsMappingObject, normalizeBridgeAmsTrayValue } from "./ams-mapping.js";
@@ -90,6 +90,20 @@ function resolveNozzleType(value) {
     }
     return normalized;
 }
+/** BambuStudio's nozzle_volume_type value for each tool argument value. */
+const NOZZLE_VOLUME_TYPES = { standard: "Standard", high_flow: "High Flow" };
+const VALID_NOZZLE_VOLUME_TYPES = Object.keys(NOZZLE_VOLUME_TYPES);
+/** The installed nozzle's flow type. Bambu machine presets assume Standard; the print gate compares this with the printer. */
+function resolveNozzleVolumeType(value) {
+    const raw = value === undefined || value === null || value === "" ? process.env.BAMBU_NOZZLE_VOLUME_TYPE?.trim() : value;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const normalized = String(raw).trim().toLowerCase().replace(/[\s-]+/g, "_");
+    if (!VALID_NOZZLE_VOLUME_TYPES.includes(normalized)) {
+        throw new Error(`Invalid nozzle volume type "${raw}". Valid types: ${VALID_NOZZLE_VOLUME_TYPES.join(", ")}`);
+    }
+    return NOZZLE_VOLUME_TYPES[normalized];
+}
 const VALID_BAMBUSTUDIO_CLI_BED_TYPES = ["textured_plate", "cool_plate", "engineering_plate", "hot_plate"];
 // Map model IDs to BambuStudio --load-machine preset names
 const BAMBU_MODEL_PRESETS = {
@@ -1040,6 +1054,7 @@ class BambuPrinterMCPServer {
             skipModifiedGcodes: true,
             bedType: bedType ? resolveBambuStudioCliBedType(bedType) : undefined,
             nozzleType: resolveNozzleType(args?.nozzle_type),
+            nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
         };
         threeMFPath = await this.stlManipulator.sliceSTL(threeMFPath, slicerType, slicerPath, slicerProfile || undefined, undefined, printPreset, autoSliceOptions);
         console.error("Auto-sliced to: " + threeMFPath);
@@ -1326,12 +1341,14 @@ class BambuPrinterMCPServer {
         return this.print3mfViaBambuNetwork({ ...args, bambu_model: model, connection_type: "lan", bambu_network_method: "start_local_print" }, host, bambuSerial, bambuToken, { onUpdate, signal });
     }
     async uploadFileViaBambuNative(args, host, bambuSerial, bambuToken, onUpdate, signal) {
-        assertBambuNativeAvailable();
         if (args.print)
             throw new Error("Native upload never starts printing; use print_3mf.");
+        // Resolve and enforce the model first, as the print path does, so a
+        // non-X2D request is never told to install the native helper.
         const model = await this.resolveBambuModel(args.bambu_model);
         if (model !== "x2d")
             throw new Error("connection_mode=bambu_native is restricted to X2D.");
+        assertBambuNativeAvailable();
         const unsupported = ["use_ams", "ams_mapping", "ams_mapping2", "ams_mapping_info", "nozzle_mapping", "nozzles_info",
             "bed_leveling", "flow_calibration", "vibration_calibration", "layer_inspect", "timelapse"];
         for (const key of unsupported) {
@@ -1841,6 +1858,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Bambu-compatible slicing: the hotend nozzle material installed on the printer (default: BAMBU_NOZZLE_TYPE, else the model preset's stock nozzle, usually stainless_steel). Printing compares it with the printer's reported nozzle."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Bambu-compatible slicing: the flow type of the nozzle installed on the printer (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard). high_flow uses the presets' High Flow values, such as the filament's High Flow max volumetric speed, and is refused if the machine preset has no High Flow variant. Printing compares it with the printer's reported nozzle flow."
+                                },
                                 use_printer_filaments: { type: "boolean", description: "When true, and no explicit slicer profile or load_filaments override is provided, use the printer's current or first loaded AMS filament as the slicer filament profile." },
                                 host: { type: "string", description: "Hostname or IP of the printer (default: value from env)" },
                                 bambu_serial: { type: "string", description: "Serial number (default: value from env)" },
@@ -1896,6 +1918,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Bambu-compatible slicing: the hotend nozzle material installed on the printer (default: BAMBU_NOZZLE_TYPE, else the model preset's stock nozzle, usually stainless_steel). Printing compares it with the printer's reported nozzle."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Bambu-compatible slicing: the flow type of the nozzle installed on the printer (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard). high_flow uses the presets' High Flow values, such as the filament's High Flow max volumetric speed, and is refused if the machine preset has no High Flow variant. Printing compares it with the printer's reported nozzle flow."
+                                },
                                 use_printer_filaments: { type: "boolean", description: "When true, and no explicit slicer profile or load_filaments override is provided, use the printer's current or first loaded AMS filament as the slicer filament profile. Template 3MF process settings can still be used at the same time." },
                                 uptodate: { type: "boolean", description: "Refresh 3MF preset configs to match the latest BambuStudio version. Use when slicing downloaded or older 3MF files to prevent stale-config failures." },
                                 repetitions: { type: "number", description: "Print N identical copies of the model. Each copy gets its own plate placement. Example: 3 prints three copies." },
@@ -2002,6 +2029,7 @@ class BambuPrinterMCPServer {
                                 password: { type: "string", description: "Printer password/access code override for LAN/local bridge methods." },
                                 bed_type: { type: "string", enum: ["textured_plate", "cool_plate", "engineering_plate", "hot_plate", "supertack_plate"], description: "Bed plate type currently installed (default: textured_plate)." },
                                 nozzle_type: { type: "string", enum: [...VALID_NOZZLE_TYPES], description: "Installed nozzle material, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_TYPE, else the preset's stock nozzle)." },
+                                nozzle_volume_type: { type: "string", enum: [...VALID_NOZZLE_VOLUME_TYPES], description: "Installed nozzle flow type, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard)." },
                                 plate_index: { type: "number", description: "Zero-based plate index to print from the sliced 3MF; converted to FULU's one-based PrintParams plate_index." },
                                 project_name: { type: "string", description: "Optional project name sent in FULU PrintParams; defaults to the 3MF filename without extension." },
                                 preset_name: { type: "string", description: "Optional preset name sent in FULU PrintParams; defaults to project plus one-based plate index." },
@@ -2265,7 +2293,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "reread_ams_rfid",
-                        description: "Trigger a Bambu AMS RFID re-read for one AMS slot. X2D on macOS uses the native official plug-in route. This can move AMS filament; use only when the printer is idle and unloaded.",
+                        description: "Trigger a Bambu AMS RFID re-read for one AMS slot. X2D on macOS, or Linux with the native helper installed, uses the native official plug-in route. This can move AMS filament; use only when the printer is idle and unloaded.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2298,7 +2326,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "set_fan_speed",
-                        description: "Set a Bambu printer fan speed percentage. X2D on macOS uses the installed Bambu networking plug-in without UI automation; other models use MQTT.",
+                        description: "Set a Bambu printer fan speed percentage. X2D on macOS, or Linux with the native helper installed, uses Bambu's networking plug-in without UI automation; other models use MQTT.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2357,7 +2385,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "set_ams_drying",
-                        description: "Start or stop the AMS filament drying cycle. X2D on macOS uses the native official plug-in route and supports AMS-HT id 128.",
+                        description: "Start or stop the AMS filament drying cycle. X2D on macOS, or Linux with the native helper installed, uses the native official plug-in route and supports AMS-HT id 128.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2429,6 +2457,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Installed nozzle material, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_TYPE, else the preset's stock nozzle)."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Installed nozzle flow type, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard)."
+                                },
                                 host: { type: "string", description: "Hostname or IP of the printer (default: value from env)" },
                                 bambu_serial: { type: "string", description: "Serial number (default: value from env)" },
                                 bambu_token: { type: "string", description: "Access token (default: value from env)" },
@@ -2618,9 +2651,42 @@ class BambuPrinterMCPServer {
             const host = String(args?.host || DEFAULT_HOST);
             const bambuSerial = String(args?.bambu_serial || DEFAULT_BAMBU_SERIAL);
             const bambuToken = String(args?.bambu_token || DEFAULT_BAMBU_TOKEN);
-            const nativeControls = process.platform === "darwin" &&
-                (bambuSerial.trim().toUpperCase().startsWith("20P") ||
-                    (DEFAULT_BAMBU_MODEL === "x2d" && bambuSerial === DEFAULT_BAMBU_SERIAL));
+            const x2dTarget = bambuSerial.trim().toUpperCase().startsWith("20P") ||
+                (DEFAULT_BAMBU_MODEL === "x2d" && bambuSerial === DEFAULT_BAMBU_SERIAL);
+            // Resolved lazily: the Linux availability check reads files, and most
+            // tools (status, slicing, STL) never need it.
+            // One resolution per request; null means native X2D controls are usable.
+            let nativeUnavailable;
+            const nativeUnavailableReason = () => (nativeUnavailable ?? (nativeUnavailable = x2dTarget ? bambuNativeUnavailableReason() ?? null : "The selected printer is not an X2D."));
+            const nativeControls = () => nativeUnavailableReason() === null;
+            // Linux sent X2D stop and heater-off over MQTT before the native route
+            // existed. Send them over both routes there: a stuck helper must not
+            // delay an emergency control, and a repeated stop or heater-off is
+            // harmless. The immediate MQTT send can precede the exit of an older
+            // print or heating helper that then still dispatches, so MQTT is sent
+            // again once every older helper for this printer has exited, and only
+            // that send counts. Either counted route succeeding is success. macOS
+            // stays native-only.
+            const linuxEmergency = (native, mqtt) => async () => {
+                if (process.platform !== "linux")
+                    return native();
+                const [nativeResult, immediateResult, mqttResult] = await Promise.allSettled([
+                    native(),
+                    mqtt(),
+                    interruptNativeOperations(bambuSerial).then(() => mqtt()),
+                ]);
+                const reason = (result) => result.status === "rejected" ? (result.reason instanceof Error ? result.reason.message : String(result.reason)) : undefined;
+                if (nativeResult.status === "rejected" && mqttResult.status === "rejected") {
+                    throw new Error(`native route: ${reason(nativeResult)}; MQTT route: ${reason(mqttResult)}`);
+                }
+                const state = (result) => result.status === "fulfilled" ? "sent" : "failed";
+                return {
+                    status: "success",
+                    routes: { native: state(nativeResult), mqtt: state(mqttResult), mqtt_immediate: state(immediateResult) },
+                    ...(reason(nativeResult) ? { native_error: reason(nativeResult) } : {}),
+                    ...(reason(mqttResult) ? { mqtt_error: reason(mqttResult) } : {}),
+                };
+            };
             const requestedTemplateDir = typeof args?.template_dir === "string" && args.template_dir.trim().length > 0
                 ? String(args.template_dir)
                 : undefined;
@@ -2822,19 +2888,19 @@ class BambuPrinterMCPServer {
                         break;
                     }
                     case "cancel_print":
-                        result = await this.bambu.cancelJob(host, bambuSerial, bambuToken, nativeControls
-                            ? () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
-                                messageJson: JSON.stringify({ print: { command: "stop", param: "", sequence_id: String(Date.now()) } }), qos: 1 })
+                        result = await this.bambu.cancelJob(host, bambuSerial, bambuToken, nativeControls()
+                            ? linuxEmergency(() => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
+                                messageJson: JSON.stringify({ print: { command: "stop", param: "", sequence_id: String(Date.now()) } }), qos: 1 }), () => this.bambu.sendStopOverMqtt(host, bambuSerial, bambuToken))
                             : undefined);
                         break;
                     case "pause_print":
-                        result = await this.bambu.pauseJob(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.pauseJob(host, bambuSerial, bambuToken, nativeControls()
                             ? () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "pause", param: "", sequence_id: String(Date.now()) } }), qos: 1 })
                             : undefined);
                         break;
                     case "resume_print":
-                        result = await this.bambu.resumeJob(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.resumeJob(host, bambuSerial, bambuToken, nativeControls()
                             ? (assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "resume", param: "", sequence_id: String(Date.now()) } }), qos: 1 }, { signal: extra.signal, assertActive, beforeDispatch })
                             : undefined);
@@ -2843,8 +2909,9 @@ class BambuPrinterMCPServer {
                         if (!args?.message_json) {
                             throw new Error("Missing required parameter: message_json");
                         }
-                        if (!nativeControls) {
-                            throw new Error("x2d_native_control is restricted to a selected X2D printer on macOS.");
+                        if (!nativeControls()) {
+                            throw new Error("x2d_native_control is restricted to a selected X2D printer on macOS, or on Linux with the native helper installed. " +
+                                nativeUnavailableReason());
                         }
                         const messageJson = validateBambuNativeMetadata(String(args.message_json));
                         result = await sendNativeCommand({
@@ -2858,7 +2925,7 @@ class BambuPrinterMCPServer {
                         break;
                     }
                     case "clear_hms_errors":
-                        result = await this.bambu.clearHmsErrors(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.clearHmsErrors(host, bambuSerial, bambuToken, nativeControls()
                             ? (assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "clean_print_error", param: "", sequence_id: String(Date.now()) } }), qos: 1 }, { signal: extra.signal, assertActive, beforeDispatch })
                             : undefined);
@@ -2867,7 +2934,7 @@ class BambuPrinterMCPServer {
                         if (!args?.mode) {
                             throw new Error("Missing required parameter: mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const normalized = String(args.mode).trim().toLowerCase();
                             const mode = normalized === "silent" ? 1
                                 : normalized === "standard" ? 2
@@ -2894,7 +2961,7 @@ class BambuPrinterMCPServer {
                         if (!args?.mode) {
                             throw new Error("Missing required parameter: mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const mode = String(args.mode).trim().toLowerCase();
                             if (mode !== "cooling" && mode !== "heating") {
                                 throw new Error("Airduct mode must be one of: cooling, heating.");
@@ -2921,7 +2988,7 @@ class BambuPrinterMCPServer {
                         if (args?.ams_id === undefined || args?.slot_id === undefined) {
                             throw new Error("Missing required parameters: ams_id and slot_id");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const amsId = Number(args.ams_id);
                             const slotId = Number(args.slot_id);
                             if ((!Number.isInteger(amsId) || (amsId < 0 || amsId > 3)) && amsId !== 128) {
@@ -2958,9 +3025,14 @@ class BambuPrinterMCPServer {
                         const heaterModel = args.temperature === 0
                             ? String(args.bambu_model || DEFAULT_BAMBU_MODEL).trim().toLowerCase()
                             : await this.resolveBambuModel(args.bambu_model);
-                        result = await this.bambu.setTemperature(host, bambuSerial, bambuToken, String(args.component), args.temperature, heaterModel || undefined, args?.material !== undefined ? String(args.material) : undefined, Number(args?.nozzle_diameter ?? DEFAULT_NOZZLE_DIAMETER), (args.temperature === 0 ? nativeControls : heaterModel === "x2d" && process.platform === "darwin")
-                            ? (heater, target, assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
-                                messageJson: buildBambuNativeTemperatureCommand(heater, target).messageJson }, { signal: extra.signal, assertActive, beforeDispatch })
+                        result = await this.bambu.setTemperature(host, bambuSerial, bambuToken, String(args.component), args.temperature, heaterModel || undefined, args?.material !== undefined ? String(args.material) : undefined, Number(args?.nozzle_diameter ?? DEFAULT_NOZZLE_DIAMETER), (args.temperature === 0 ? nativeControls() : heaterModel === "x2d" && bambuNativeControlsAvailable())
+                            ? (heater, target, assertActive, beforeDispatch) => {
+                                const native = () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
+                                    messageJson: buildBambuNativeTemperatureCommand(heater, target).messageJson }, { signal: extra.signal, assertActive, beforeDispatch });
+                                return target === 0
+                                    ? linuxEmergency(native, () => this.bambu.sendHeaterOffOverMqtt(host, bambuSerial, bambuToken, heater))()
+                                    : native();
+                            }
                             : undefined);
                         break;
                     }
@@ -2968,7 +3040,7 @@ class BambuPrinterMCPServer {
                         if (!args?.fan || args?.speed === undefined) {
                             throw new Error("Missing required parameters: fan and speed");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const status = await this.bambu.getStatus(host, bambuSerial, bambuToken);
                             const printerState = String(status?.raw?.gcode_state ?? status?.raw?.print?.gcode_state ?? status?.gcode_state ?? status?.status ?? "").toUpperCase();
                             if (printerState === "RUNNING" && args?.confirm_during_print !== true) {
@@ -2996,7 +3068,7 @@ class BambuPrinterMCPServer {
                         if (!args?.light || !args?.mode) {
                             throw new Error("Missing required parameters: light and mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const light = String(args.light).trim();
                             const mode = String(args.mode).trim().toLowerCase();
                             if (light !== "chamber_light" && light !== "chamber_light2") {
@@ -3031,7 +3103,7 @@ class BambuPrinterMCPServer {
                         if (!Array.isArray(args?.object_ids)) {
                             throw new Error("Missing required parameter: object_ids");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const objectIds = args.object_ids.map((id) => Number(id));
                             if (objectIds.length === 0 || objectIds.some((id) => !Number.isInteger(id) || id < 0)) {
                                 throw new Error("object_ids must contain one or more non-negative integers.");
@@ -3054,7 +3126,7 @@ class BambuPrinterMCPServer {
                         if (!args?.action || args?.ams_id === undefined) {
                             throw new Error("Missing required parameters: action and ams_id");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const action = String(args.action).trim().toLowerCase();
                             const amsId = Number(args.ams_id);
                             if (action !== "start" && action !== "stop") {
@@ -3164,6 +3236,7 @@ class BambuPrinterMCPServer {
                             sliceBambuOptions.filamentColours = parseFilamentColours(String(args.filament_colours));
                         sliceBambuOptions.bedType = resolveBambuStudioCliBedType(args?.bed_type);
                         sliceBambuOptions.nozzleType = resolveNozzleType(args?.nozzle_type);
+                        sliceBambuOptions.nozzleVolumeType = resolveNozzleVolumeType(args?.nozzle_volume_type);
                         if (args?.enable_timelapse !== undefined)
                             sliceBambuOptions.enableTimelapse = Boolean(args.enable_timelapse);
                         if (args?.allow_mix_temp !== undefined)
@@ -3244,6 +3317,7 @@ class BambuPrinterMCPServer {
                             sliceBambuOptions.filamentColours = parseFilamentColours(String(args.filament_colours));
                         sliceBambuOptions.bedType = resolveBambuStudioCliBedType(args?.bed_type);
                         sliceBambuOptions.nozzleType = resolveNozzleType(args?.nozzle_type);
+                        sliceBambuOptions.nozzleVolumeType = resolveNozzleVolumeType(args?.nozzle_volume_type);
                         if (args?.enable_timelapse !== undefined)
                             sliceBambuOptions.enableTimelapse = Boolean(args.enable_timelapse);
                         if (args?.allow_mix_temp !== undefined)
@@ -3347,6 +3421,7 @@ class BambuPrinterMCPServer {
                                 skipModifiedGcodes: true,
                                 bedType: printBedType,
                                 nozzleType: resolveNozzleType(args?.nozzle_type),
+                                nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
                             };
                             if (!explicitSlicerProfile) {
                                 try {

package/dist/printers/bambu.d.ts

@@ -26,6 +26,13 @@ interface BambuPrintOptionsInternal {
     amsSlots?: number[];
     md5?: string;
 }
+/** What the human confirmed in confirmPrintPreflight, checked again before dispatch. */
+export type PrintPreflight = {
+    finishedJob?: string;
+    serial: string;
+    model: string;
+    notices: string[];
+};
 export declare class BambuImplementation {
     private readonly confirm?;
     private printerStore;
@@ -34,8 +41,14 @@ export declare class BambuImplementation {
     constructor(confirm?: ((message: string) => Promise<boolean>) | undefined);
     confirmHardwareAction(message: string, physicalCheck?: boolean): Promise<void>;
     private finishedJobIdentity;
-    confirmPrintPreflight(serial: string, status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): Promise<string | undefined>;
-    assertBedClearance(status: any, confirmedFinishedJob: string | undefined): void;
+    /**
+     * The human print confirmation. Its result goes to assertBedClearance at
+     * every later state check of the same print, which stops the print if the
+     * situation the human confirmed has changed.
+     */
+    confirmPrintPreflight(serial: string, status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): Promise<PrintPreflight>;
+    /** Stop a print whose confirmed situation changed: a newly finished job, or a hidden HMS notice the preflight did not name. */
+    assertBedClearance(status: any, preflight: PrintPreflight): void;
     private getPrinter;
     /** Internal handoff from a successful inspected transport; never exposed as an MCP tool. */
     recordCheckedJob(host: string, serial: string, remotePath: string, requirements: PrinterStateRequirements): void;
@@ -47,6 +60,10 @@ export declare class BambuImplementation {
     print3mf(host: string, serial: string, token: string, options: BambuPrintOptionsInternal): Promise<any>;
     private print3mfPrepared;
     cancelJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any>;
+    /** Raw MQTT stop for routes that already ran the shared cancellation steps. */
+    sendStopOverMqtt(host: string, serial: string, token: string): Promise<any>;
+    /** Raw MQTT heater-off; switching off needs no material or model declaration. */
+    sendHeaterOffOverMqtt(host: string, serial: string, token: string, heater: "bed" | "nozzle"): Promise<any>;
     pauseJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any>;
     resumeJob(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any>;
     clearHmsErrors(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any>;
@@ -54,6 +71,16 @@ export declare class BambuImplementation {
     setAirductMode(host: string, serial: string, token: string, mode: string): Promise<any>;
     rereadAmsRfid(host: string, serial: string, token: string, amsId: number, slotId: number): Promise<any>;
     setTemperature(host: string, serial: string, token: string, component: string, temperature: unknown, bambuModel?: string, material?: string, nozzleDiameter?: number, dispatch?: (heater: "bed" | "nozzle", target: number, assertActive: () => void, beforeDispatch?: () => Promise<void>) => Promise<any>): Promise<{
+        routes: any;
+        native_error: any;
+        mqtt_error: any;
+        status: string;
+        message: string;
+        command: string;
+    } | {
+        routes?: undefined;
+        native_error?: undefined;
+        mqtt_error?: undefined;
         status: string;
         message: string;
         command: string;

package/dist/printers/bambu.js

@@ -8,7 +8,7 @@ import { Readable } from "node:stream";
 import { readSafe3mfArchive } from "../safety/archive.js";
 import { inspectPrintFile } from "../safety/print-file.js";
 import { normalizeModel, validateTemperature } from "../safety/limits.js";
-import { validatePrinterState, manualHeatingRequirements } from "../safety/printer-state.js";
+import { describeHmsKey, hiddenHmsKeys, hiddenHmsNotices, reportedHmsKey, validatePrinterState, manualHeatingRequirements } from "../safety/printer-state.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName, normalizedRemotePath, cancelPendingPrinterOperations } from "../safety/artifact.js";
 import { Client as FTPClient } from "basic-ftp";
 import { BambuPrinter } from "bambu-js";
@@ -69,7 +69,7 @@ const MODEL_ID_TO_NAME = {
 const H2_MODEL_NAMES = new Set(["h2", "h2c", "h2d", "h2dpro", "h2d pro", "h2s", "x2d"]);
 export function assertDirectPrintSupported(model, serial) {
     if (model?.trim().toLowerCase() === "x2d" || serial?.trim().toUpperCase().startsWith("20P")) {
-        throw new Error("X2D direct printing is not supported through legacy MQTT/FTPS. Use the macOS native eMMC route via print_3mf. " +
+        throw new Error("X2D direct printing is not supported through legacy MQTT/FTPS. Use the native eMMC route via print_3mf (macOS, or Linux with the native helper installed). " +
             "X2D status and slicing remain available on all supported platforms.");
     }
 }
@@ -392,21 +392,37 @@ export class BambuImplementation {
     finishedJobIdentity(status) {
         return status.raw.gcode_state === "FINISH" ? JSON.stringify([status.raw.gcode_file, status.raw.subtask_name, status.raw.task_id, status.raw.subtask_id]) : undefined;
     }
+    /**
+     * The human print confirmation. Its result goes to assertBedClearance at
+     * every later state check of the same print, which stops the print if the
+     * situation the human confirmed has changed.
+     */
     async confirmPrintPreflight(serial, status, inspection) {
         const finishedJob = this.finishedJobIdentity(status);
         const cleared = this.clearedErrors.get(serial);
+        const notices = hiddenHmsNotices(status?.raw, serial, inspection.model);
         await this.confirmHardwareAction(`Start a checked print on ${inspection.model.toUpperCase()} (${serial})? Nozzles: ${inspection.nozzleDiameters.join(", ")} mm. ` +
             `Materials: ${inspection.materials.join(", ")}. Peak targets: nozzle ${inspection.maxNozzleTemperature}°C, bed ${inspection.maxBedTemperature}°C, chamber ${inspection.maxChamberTemperature}°C. ` +
             `File SHA-256: ${inspection.sha256}. Confirm the physical spool labels and that the build plate is clear.` +
             (finishedJob !== undefined ? " The printer reports FINISH: remove the previous part and debris before confirming." : "") +
-            (cleared ? ` Previously cleared hardware codes: ${cleared.join(", ")}. Confirm their physical causes have been resolved.` : ""), finishedJob !== undefined || !!cleared);
-        return finishedJob;
+            (cleared ? ` Previously cleared hardware codes: ${cleared.map(describeHmsKey).join(", ")}. Confirm their physical causes have been resolved.` : "") +
+            (notices.length ? ` The printer also reports ${notices.join(", ")}, which Bambu lists for this model without text and never shows as a fault; ` +
+                `${notices.length === 1 ? "it does" : "they do"} not block printing.` : ""), finishedJob !== undefined || !!cleared);
+        return { finishedJob, serial, model: inspection.model, notices };
     }
-    assertBedClearance(status, confirmedFinishedJob) {
+    /** Stop a print whose confirmed situation changed: a newly finished job, or a hidden HMS notice the preflight did not name. */
+    assertBedClearance(status, preflight) {
         const current = this.finishedJobIdentity(status);
-        if (current !== undefined && current !== confirmedFinishedJob) {
+        if (current !== undefined && current !== preflight.finishedJob) {
             throw new Error("Printer reports a newly finished job. Confirm that its part and debris have been removed before retrying the print.");
         }
+        // An X2D raises its hidden camera notice about 15 seconds after boot, so it
+        // can appear after the human confirmed. Never pass a notice nobody was told about.
+        const unnamed = hiddenHmsNotices(status?.raw, preflight.serial, preflight.model).filter(notice => !preflight.notices.includes(notice));
+        if (unnamed.length) {
+            throw new Error(`Printer reported ${unnamed.join(", ")} after the print confirmation. ` +
+                "Bambu hides it and it does not block printing, but it was not named when you confirmed; start the print again to review it.");
+        }
     }
     async getPrinter(host, serial, token) {
         return this.printerStore.getPrinter(host, serial, token);
@@ -822,6 +838,19 @@ export class BambuImplementation {
             throw new Error(`Failed to cancel print: ${error.message}`);
         }
     }
+    /** Raw MQTT stop for routes that already ran the shared cancellation steps. */
+    async sendStopOverMqtt(host, serial, token) {
+        const printer = await this.getPrinter(host, serial, token);
+        await invokeWithoutAck(printer, new UpdateStateCommand({ state: "stop" }));
+        return { status: "success", message: "Cancel command sent over MQTT." };
+    }
+    /** Raw MQTT heater-off; switching off needs no material or model declaration. */
+    async sendHeaterOffOverMqtt(host, serial, token, heater) {
+        const printer = await this.getPrinter(host, serial, token);
+        const gcode = `${heater === "bed" ? "M140" : "M104"} S0`;
+        await invokeWithoutAck(printer, new GCodeLineCommand({ gcodes: [gcode] }));
+        return { status: "success", message: `Heater-off sent over MQTT for ${heater}.`, command: gcode };
+    }
     async pauseJob(host, serial, token, dispatch) {
         const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
         try {
@@ -867,10 +896,12 @@ export class BambuImplementation {
             const codesFor = (status) => {
                 if (!Array.isArray(status.raw?.hms) || status.raw?.print_error === undefined)
                     throw new Error("Fresh error codes are required before clearing hardware errors.");
-                return [`print_error:${status.raw.print_error}`, ...status.raw.hms.map((entry) => `hms:${entry.attr}:${entry.code}`)].sort();
+                // Hidden notices never block and survive clean_print_error, so they are not errors to clear or re-acknowledge.
+                const hidden = new Set(hiddenHmsKeys(status.raw, serial, String(status.model ?? "")));
+                return [`print_error:${status.raw.print_error}`, ...status.raw.hms.map(reportedHmsKey).filter((key) => !hidden.has(key))].sort();
             };
             const codes = codesFor(await this.getSafetyStatus(host, serial, token));
-            await this.confirmHardwareAction(`Clear reported hardware errors on ${serial}: ${codes.join(", ")}? Inspect the printer and resolve the physical cause first. Confirm only after removing obstructions and correcting the fault.`, true);
+            await this.confirmHardwareAction(`Clear reported hardware errors on ${serial}: ${codes.map(describeHmsKey).join(", ")}? Inspect the printer and resolve the physical cause first. Confirm only after removing obstructions and correcting the fault.`, true);
             const beforeDispatch = async () => {
                 assertActive();
                 const current = codesFor(await this.getSafetyStatus(host, serial, token));
@@ -1001,11 +1032,13 @@ export class BambuImplementation {
             }
             const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
             assertActive();
-            if (dispatch)
-                await dispatch(heater, targetTemperature, assertActive, beforeDispatch);
-            else
+            const dispatched = dispatch ? await dispatch(heater, targetTemperature, assertActive, beforeDispatch) : undefined;
+            if (!dispatch)
                 await invokeWithoutAck(printer, new GCodeLineCommand({ gcodes: [gcode] }));
-            return { status: "success", message: `Temperature command sent for ${normalizedComponent}.`, command: gcode };
+            // Keep route details from a dual-route Linux heater-off.
+            const routeDetails = dispatched && typeof dispatched === "object" && "routes" in dispatched
+                ? { routes: dispatched.routes, native_error: dispatched.native_error, mqtt_error: dispatched.mqtt_error } : {};
+            return { status: "success", message: `Temperature command sent for ${normalizedComponent}.`, command: gcode, ...routeDetails };
         };
         if (targetTemperature === 0) {
             cancelPendingPrinterOperations(host, serial);

package/dist/safety/hidden-hms.d.ts

@@ -0,0 +1,32 @@
+export declare const HIDDEN_HMS_SOURCE: {
+    readonly studioTag: "v02.08.02.61";
+    readonly studioCommit: "926a7192574bcb9b3a732e1ec59a46d79cb45466";
+    /** Per table: Bambu's device_hms version and the SHA-256 of the English file used. */
+    readonly tables: {
+        readonly "093": {
+            readonly version: 202508191204;
+            readonly sha256: "7801fd6c355854b62ecb62ee32727b4e5dcca908841dbcfd5e5de45b3dfd1c25";
+        };
+        readonly "094": {
+            readonly version: 202503231214;
+            readonly sha256: "047c15e2140738ec08258b74536e6cb996cddf0c586c5c39e2318e54125a9e76";
+        };
+        readonly "20P": {
+            readonly version: 202511162200;
+            readonly sha256: "e4f067d027b9bcbb9bbf6cb90f41f11130cf4d83dffd3dee101db7826dc808c3";
+        };
+        readonly "22E": {
+            readonly version: 202510142200;
+            readonly sha256: "87426021aea2bd4e8d721e46e1c86808fd7c6fc06f52baf6d952ead9e8d14d1e";
+        };
+        readonly "239": {
+            readonly version: 202506171403;
+            readonly sha256: "c1d23d5302756d57df5cb9bc795d95fc54ef1db7565dca1f04b69a024886426a";
+        };
+        readonly "31B": {
+            readonly version: 202511162200;
+            readonly sha256: "dcf63657bff5451f0715ea3c032efe482279bc8cbc28cb9b8ae51c7354826574";
+        };
+    };
+};
+export declare const HIDDEN_HMS: Readonly<Record<string, readonly string[]>>;