mcp-3d-printer-server 1.2.24 → 1.2.26

package/dist/printers/bambu.js

@@ -1,5 +1,6 @@
 import { PrinterImplementation } from "../types.js";
 import { createHash } from "node:crypto";
+import { createReadStream, readFileSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -7,13 +8,58 @@ import { Client as FTPClient } from "basic-ftp";
 import { BambuClient, PushAllCommand } from "bambu-node";
 import { MAX_PRINT_FILE_BYTES, readSafe3mfArchive } from "../safety/archive.js";
 import { inspectPrintFile } from "../safety/print-file.js";
-import { normalizeModel, validateTemperature } from "../safety/limits.js";
-import { manualHeatingRequirements, publishBambuCommand, readFreshPrinterStatus, unchippedNozzles, validatePrinterState, } from "../safety/printer-state.js";
+import { isDualNozzleModel, normalizeModel, validateTemperature } from "../safety/limits.js";
+import { describeAmsTrayRange, externalTrayForNozzle } from "../ams-mapping.js";
+import { manualHeatingRequirements, publishBambuCommand, readFreshPrinterStatus, validatePrinterState, } from "../safety/printer-state.js";
 import { cancelPendingPrinterOperations, normalizedRemotePath, uniquePrintName, withPrinterOperation, withPrintSnapshot, } from "../safety/artifact.js";
-import { requireHumanConfirmation } from "../safety/confirmation.js";
 import { installBambuNodeRejectionGuard } from "./bambu-node-guard.js";
+import { requireHumanConfirmation } from "../safety/confirmation.js";
 import { assertExpectedPeaks, validateExpectedPeaks } from "../safety/expected-peaks.js";
+import { controlReply, refusedControlMessage } from "../control-reply.js";
 const COMMAND_SETTLE_MS = 300;
+/**
+ * Pause, Resume or Stop exactly as Bambu Studio sends them (MachineObject::command_task_*), with this server's own
+ * 32-bit sequence id, so the printer's answer to this one control can be told apart from any other report.
+ */
+function studioControl(command) {
+    const sequenceId = String(20000 + (Date.now() % 1000000));
+    return { command, sequenceId, send: (printer) => printer.publish({ print: { command, param: "", sequence_id: sequenceId } }) };
+}
+/** How long a control on the direct local network waits for the printer's answer (BAMBU_CONTROL_REPLY_MS, 0-30000). */
+function controlReplyMs() {
+    const configured = Number(process.env.BAMBU_CONTROL_REPLY_MS);
+    return Number.isFinite(configured) && configured >= 0 ? Math.min(configured, 30000) : 5000;
+}
+/**
+ * The printer's answer to one control on its report topic (bambu-node re-emits every message as rawMessage).
+ * Started before the publish so a fast answer is not missed; undefined when none arrives in time.
+ */
+function watchControlReply(printer, command, sequenceId, ms) {
+    const emitter = printer;
+    if (ms <= 0 || typeof emitter?.on !== "function" || typeof emitter?.off !== "function")
+        return Promise.resolve(undefined);
+    return new Promise(resolve => {
+        let timer;
+        const onMessage = (_topic, payload) => {
+            const reply = controlReply(String(payload), command, sequenceId);
+            if (reply)
+                finish(reply);
+        };
+        const finish = (reply) => { clearTimeout(timer); emitter.off("rawMessage", onMessage); resolve(reply); };
+        timer = setTimeout(() => finish(undefined), ms);
+        emitter.on("rawMessage", onMessage);
+    });
+}
+/** Send one direct control and judge it by the printer's answer; a printer not in Developer Mode refuses unsigned ones. */
+async function sendDirectControl(printer, command) {
+    const control = studioControl(command);
+    const answered = watchControlReply(printer, command, control.sequenceId, controlReplyMs());
+    await control.send(printer);
+    const reply = await answered;
+    if (reply && !reply.accepted)
+        throw new Error(refusedControlMessage(command, "the local network", reply.errCode, true));
+    return reply;
+}
 /** HMS 0500-0500-0001-0007: firmware 01.08.05+ rejected an unsigned MQTT command. */
 const COMMAND_VERIFICATION_HMS = { attr: 0x05000500, code: 0x00010007 };
 const COMMAND_REJECTED_MESSAGE = "The printer rejected the print command (HMS 0500-0500-0001-0007, \"MQTT command verification failed\"). " +
@@ -31,16 +77,10 @@ function dispatchCheckMs() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function validateTrayValue(value, label) {
-    if (!Number.isInteger(value) ||
-        value < -1 ||
-        (value > 15 && value < 128) ||
-        value > 254) {
-        throw new Error(`${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${String(value)}`);
-    }
-}
 class BambuClientStore {
-    constructor() {
+    /** Sees every merged report, so a resume record notices a job ending even when nobody polls. */
+    constructor(onReport) {
+        this.onReport = onReport;
         this.printers = new Map();
         this.initialConnectionPromises = new Map();
     }
@@ -62,6 +102,14 @@ class BambuClientStore {
             serialNumber: serial,
             accessToken: token,
         });
+        printer.on("printer:dataUpdate", (data) => {
+            if (!data || !this.onReport)
+                return;
+            try {
+                this.onReport(host, serial, data);
+            }
+            catch { /* an observer never breaks report handling */ }
+        });
         printer.on("client:connect", () => {
             this.printers.set(key, printer);
             this.initialConnectionPromises.delete(key);
@@ -102,29 +150,176 @@ class BambuClientStore {
         this.initialConnectionPromises.clear();
     }
 }
+/**
+ * Where each printer's resume record is kept so a restart of this server (a deploy, a crash, a reboot) during a
+ * pause can still resume the job it started: BAMBU_RESUME_STATE_DIR, else mcp-3d-printer-server/resume in the
+ * config home (bambu-printer-mcp keeps its own). Resume runs every check on a reloaded record: a fresh paused
+ * report naming this exact job, the re-read bytes or its unique name, and a person for an unverified file.
+ */
+export function defaultResumeStateDir(env = process.env) {
+    if (env.BAMBU_RESUME_STATE_DIR)
+        return env.BAMBU_RESUME_STATE_DIR;
+    const configHome = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+    return path.join(configHome, "mcp-3d-printer-server", "resume");
+}
+function isCheckedJob(value) {
+    return Boolean(value) && typeof value === "object" && /^[a-f0-9]{64}$/.test(value.sha256 ?? "") &&
+        typeof value.remotePath === "string" && value.remotePath !== "" && typeof value.model === "string" &&
+        Boolean(value.requirements) && typeof value.requirements === "object" && Array.isArray(value.materials) &&
+        typeof value.seenRunning === "boolean" && typeof value.uploadedHere === "boolean" &&
+        [value.maxNozzleTemperature, value.maxBedTemperature, value.maxChamberTemperature].every(Number.isFinite);
+}
+/**
+ * The resume record of each printer (keyed host and serial). With a folder, every change is written to that
+ * printer's own file (private, replaced atomically) and the file is read the first time the printer is asked
+ * about, so a new server process knows the job the previous one started. Without one it lives in memory only.
+ */
+class ResumeRecords {
+    constructor(dir) {
+        this.dir = dir;
+        this.jobs = new Map();
+        this.read = new Set();
+    }
+    get(key) {
+        if (!this.read.has(key)) {
+            this.read.add(key);
+            const saved = this.dir ? this.readFile(key) : undefined;
+            if (saved)
+                this.jobs.set(key, saved);
+        }
+        return this.jobs.get(key);
+    }
+    set(key, job) {
+        this.read.add(key);
+        this.jobs.set(key, job);
+        this.save(key);
+    }
+    delete(key) {
+        this.read.add(key);
+        const had = this.jobs.delete(key);
+        this.save(key);
+        return had;
+    }
+    /** Write this printer's record as it is now (or remove its file). A failed write never stops a print or a control. */
+    save(key) {
+        if (!this.dir)
+            return;
+        const file = this.file(key);
+        const job = this.jobs.get(key);
+        try {
+            if (!job) {
+                rmSync(file, { force: true });
+                return;
+            }
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            const temporary = `${file}.${process.pid}.tmp`;
+            writeFileSync(temporary, JSON.stringify({ version: 1, key, job }), { mode: 0o600 });
+            renameSync(temporary, file);
+        }
+        catch (error) {
+            console.error(`Could not save the resume record for ${key.replace("\n", " ")}: ${error.message}. Resume still works until this server restarts.`);
+        }
+    }
+    file(key) {
+        return path.join(this.dir, `${createHash("sha256").update(key).digest("hex").slice(0, 32)}.json`);
+    }
+    readFile(key) {
+        try {
+            const saved = JSON.parse(readFileSync(this.file(key), "utf8"));
+            return saved?.version === 1 && saved.key === key && isCheckedJob(saved.job) ? saved.job : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+const ACTIVE_JOB_STATES = new Set(["PREPARE", "SLICING", "RUNNING", "PAUSE"]);
+/** Reports after which a started job can no longer be resumed. */
+const ENDED_JOB_STATES = new Set(["FINISH", "FAILED", "IDLE"]);
+const jobStem = (value) => path.posix.basename(value.replace(/\\/g, "/")).replace(/(?:\.gcode)?\.3mf$|\.gcode$/i, "");
+const reportedJobNames = (raw) => [raw.gcode_file, raw.subtask_name].filter((value) => typeof value === "string" && value.trim() !== "");
+/** Whether a report names the job stored at remotePath (subtask_name for projects, gcode_file for raw G-code). */
+function reportsJob(raw, remotePath) {
+    return reportedJobNames(raw).some((value) => jobStem(value) === jobStem(remotePath));
+}
+/** What a resume needs to know about a started file (filePath, the inspected snapshot). */
+export async function checkedFile(inspection, filePath) {
+    const used = inspection.usedFilamentPositions.map((position) => inspection.materials[position]).filter(Boolean);
+    let plate;
+    const plateNumber = /^Metadata\/plate_(\d+)\.gcode$/i.exec(inspection.plateInternalPath ?? "");
+    if (plateNumber && /\.3mf$/i.test(filePath)) {
+        const entry = (await readSafe3mfArchive(filePath)).zip.file(inspection.plateInternalPath);
+        if (entry)
+            plate = { index: Number(plateNumber[1]), sha256: createHash("sha256").update(await entry.async("nodebuffer")).digest("hex") };
+    }
+    return {
+        sha256: inspection.sha256, ...(plate ? { plate } : {}), model: inspection.model,
+        maxNozzleTemperature: inspection.maxNozzleTemperature, maxBedTemperature: inspection.maxBedTemperature,
+        maxChamberTemperature: inspection.maxChamberTemperature,
+        materials: [...new Set(used.length ? used : inspection.materials)],
+    };
+}
+/**
+ * Where a printer keeps the plate G-code it extracted from a project to print
+ * it: a P1S removes the uploaded 3MF once it starts and keeps
+ * cache/<name>_plate_<n>.gcode, byte-identical to the 3MF's plate G-code.
+ */
+function extractedPlatePath(remotePath, index) {
+    const directory = path.posix.dirname(remotePath);
+    const stem = path.posix.basename(remotePath).replace(/(?:\.gcode)?\.3mf$/i, "");
+    return `${directory === "." ? "" : `${directory}/`}${stem}_plate_${index}.gcode`;
+}
+/** The job name the printer reports: subtask_name, else the G-code file's basename. */
+function reportedJobName(raw) {
+    const subtask = typeof raw.subtask_name === "string" ? raw.subtask_name.trim() : "";
+    if (subtask)
+        return subtask;
+    return typeof raw.gcode_file === "string" ? path.posix.basename(raw.gcode_file.replace(/\\/g, "/").replace(/^\d+:/, "")) || undefined : undefined;
+}
 export class BambuImplementation extends PrinterImplementation {
-    constructor(apiClient, confirm) {
+    /** confirm: a person (MCP elicitation), asked only to resume a job whose file could not be re-read. */
+    constructor(apiClient, confirm, options = {}) {
         super(apiClient);
         this.confirm = confirm;
-        this.printerStore = new BambuClientStore();
-    }
-    async confirmHardwareAction(message, physicalCheck = false) {
-        await requireHumanConfirmation(this.confirm, message, "bambu", physicalCheck);
-    }
-    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;
-    }
-    async confirmPrintPreflight(serial, status, inspection) {
-        const finishedJob = this.finishedJobIdentity(status);
-        const unchipped = unchippedNozzles(status?.raw);
-        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.` +
-            (unchipped.length ? ` Printer ${unchipped.length === 1 ? `nozzle ${unchipped[0]} reports` : `nozzles ${unchipped.join(" and ")} report`} no identity chip, ` +
-                `so ${unchipped.length === 1 ? "its" : "their"} diameter and type are the printer's configured settings; confirm they match the installed ${unchipped.length === 1 ? "hotend" : "hotends"}.` : ""));
-        return finishedJob;
+        this.checkedJobs = new ResumeRecords(options.resumeStateDir);
+        this.printerStore = new BambuClientStore((host, serial, report) => this.observeReport(host, serial, report));
+    }
+    /**
+     * Internal handoff from a successful inspected transport; never an MCP tool.
+     * uploadedHere is false for FULU's BambuNetwork routes, where Bambu's plug-in
+     * put the file on the printer at a path this server has not verified: a
+     * resume then re-reads it if it can and otherwise asks a person.
+     */
+    recordCheckedJob(host, serial, remotePath, requirements, file, uploadedHere = true) {
+        if (!/^[a-f0-9]{64}$/.test(file?.sha256 ?? ""))
+            throw new Error("A started job needs the SHA-256 of its inspected bytes.");
+        this.checkedJobs.set(`${host}\n${serial}`, {
+            ...structuredClone(file), remotePath, requirements: structuredClone(requirements), seenRunning: false, uploadedHere,
+        });
+    }
+    /** Retire a record that never started (the dispatch was refused or failed). */
+    forgetCheckedJob(host, serial, remotePath) {
+        const key = `${host}\n${serial}`;
+        if (this.checkedJobs.get(key)?.remotePath === remotePath)
+            this.checkedJobs.delete(key);
+    }
+    /** Feed one merged report to the resume record (the client store calls it for every report). */
+    observeReport(host, serial, raw) {
+        const key = `${host}\n${serial}`;
+        const checked = this.checkedJobs.get(key);
+        if (!checked || !raw || typeof raw.gcode_state !== "string")
+            return;
+        const state = raw.gcode_state.toUpperCase();
+        if (ACTIVE_JOB_STATES.has(state) && reportsJob(raw, checked.remotePath)) {
+            if (!checked.seenRunning) {
+                checked.seenRunning = true;
+                this.checkedJobs.save(key);
+            }
+            return;
+        }
+        if (checked.seenRunning && (ENDED_JOB_STATES.has(state) || (ACTIVE_JOB_STATES.has(state) && reportedJobNames(raw).length > 0))) {
+            this.checkedJobs.delete(key);
+        }
     }
     async getPrinter(host, serial, token) {
         return this.printerStore.getPrinter(host, serial, token);
@@ -160,10 +355,41 @@ export class BambuImplementation extends PrinterImplementation {
             throw new Error(`Selected inspected plate ${expectedEntryName} is not present in 3MF. Re-slice that plate.`);
         }
         const gcodeBuffer = await selectedEntry.async("nodebuffer");
+        // The slicer's project filament list length, from the G-code header
+        // (`; filament_colour = #FFFFFF;#FF911A80;...`), scanning only its first 32 KB.
+        let projectFilamentCount = 1;
+        const head = gcodeBuffer.subarray(0, 32 * 1024).toString("utf8");
+        const colourLine = head.match(/;\s*filament_colour\s*=\s*([^\n\r]+)/i);
+        if (colourLine) {
+            projectFilamentCount = colourLine[1].split(";").filter((entry) => entry.trim()).length;
+        }
+        else {
+            const idsLine = head.match(/;\s*filament_ids\s*=\s*([^\n\r]+)/i);
+            if (idsLine)
+                projectFilamentCount = idsLine[1].split(";").filter((entry) => entry.trim()).length;
+        }
+        // The positions the selected plate consumes, from Metadata/plate_<n>.json filament_ids.
+        let usedFilamentPositions = [];
+        const plateJsonEntry = zip.file(selectedEntry.name.replace(/\.gcode$/i, ".json"));
+        if (plateJsonEntry) {
+            try {
+                const json = JSON.parse(await plateJsonEntry.async("string"));
+                if (Array.isArray(json.filament_ids)) {
+                    usedFilamentPositions = json.filament_ids.filter((n) => Number.isInteger(n));
+                }
+            }
+            catch {
+                // A malformed plate_N.json leaves ams_mapping as the way to map trays.
+            }
+        }
+        if (usedFilamentPositions.length === 0)
+            usedFilamentPositions = [0];
         return {
             plateFileName: path.posix.basename(selectedEntry.name),
             plateInternalPath: selectedEntry.name,
             md5: createHash("md5").update(gcodeBuffer).digest("hex"),
+            projectFilamentCount,
+            usedFilamentPositions,
         };
     }
     async getStatus(host, port, apiKey) {
@@ -244,35 +470,15 @@ export class BambuImplementation extends PrinterImplementation {
         if (options.md5 !== undefined && options.md5 !== md5) {
             throw new Error("Provided checksum does not match the inspected plate G-code.");
         }
-        for (const value of options.amsMapping ?? [])
-            validateTrayValue(value, "ams_mapping");
-        const useAMS = options.useAMS !== false;
-        let checkedMapping;
-        if (useAMS) {
-            checkedMapping = (options.amsMapping ?? []).slice();
-        }
-        else {
-            checkedMapping = Array(inspection.materials.length).fill(-1);
-            inspection.usedFilamentPositions.forEach((position) => { checkedMapping[position] = 254; });
-        }
-        for (const position of inspection.usedFilamentPositions) {
-            if (checkedMapping[position] === undefined || checkedMapping[position] < 0) {
-                throw new Error(`Missing physical filament mapping for project filament ${position}. ` +
-                    "Pass ams_mapping with a tray for every used project filament, or use_ams:false for the external spool.");
-            }
-        }
-        // Wire mapping: position = project filament, value = absolute tray. Never
-        // truncate a checked mapping; pad to the historical five entries.
-        const amsMapping = options.amsMapping && options.amsMapping.length > 0
-            ? Array.from({ length: Math.max(5, options.amsMapping.length) }, (_, i) => i < options.amsMapping.length ? options.amsMapping[i] : -1)
-            : [-1, -1, -1, -1, 0];
+        const { baseMapping, amsMapping, useAMS } = this.checkedAmsMapping(model, options, inspection, projectMetadata);
+        const checkedMapping = baseMapping;
         const requirements = { ...inspection, amsMapping: checkedMapping, useAMS };
+        const resumeFile = await checkedFile(inspection, options.filePath);
         const initialStatus = await this.getSafetyStatus(host, serial, token);
         validatePrinterState(initialStatus, requirements);
-        await this.confirmPrintPreflight(serial, initialStatus, inspection);
-        // Recheck after the human response: the printer may have changed meanwhile.
-        const confirmedStatus = await this.getSafetyStatus(host, serial, token);
-        validatePrinterState(confirmedStatus, requirements);
+        // Recheck before the upload: the printer may have changed meanwhile.
+        const recheckedStatus = await this.getSafetyStatus(host, serial, token);
+        validatePrinterState(recheckedStatus, requirements);
         assertActive();
         const remoteFileName = uniquePrintName(options.filePath);
         const remoteProjectPath = `cache/${remoteFileName}`;
@@ -282,12 +488,14 @@ export class BambuImplementation extends PrinterImplementation {
         validatePrinterState(dispatchStatus, requirements);
         const printer = await this.getPrinter(host, serial, token);
         assertActive();
+        const subtaskName = remoteFileName.replace(/\.3mf$/i, "");
         const projectFileCmd = {
             print: {
                 command: "project_file",
                 param: projectMetadata.plateInternalPath,
                 url: `file:///sdcard/${remoteProjectPath}`,
-                subtask_name: options.projectName,
+                // The printer reports this back as subtask_name, which identifies the checked job for resume.
+                subtask_name: subtaskName,
                 md5,
                 flow_cali: options.flowCalibration ?? true,
                 layer_inspect: options.layerInspect ?? true,
@@ -306,8 +514,9 @@ export class BambuImplementation extends PrinterImplementation {
         };
         const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
         await printer.publish(projectFileCmd);
+        this.recordCheckedJob(host, serial, remoteProjectPath, requirements, resumeFile);
         await sleep(COMMAND_SETTLE_MS);
-        const dispatch = await watcher.settled();
+        const dispatch = await this.settleRecorded(watcher, host, serial, remoteProjectPath);
         return {
             status: "success",
             dispatch,
@@ -316,6 +525,7 @@ export class BambuImplementation extends PrinterImplementation {
                 : `Uploaded the checked 3MF and sent the print command for ${options.projectName}; the printer has not reported starting yet. ` +
                     "Check get_printer_status before assuming it is printing.",
             remoteProjectPath,
+            subtaskName,
             plateFile: projectMetadata.plateFileName,
             platePath: projectMetadata.plateInternalPath,
             md5,
@@ -328,6 +538,66 @@ export class BambuImplementation extends PrinterImplementation {
             },
         };
     }
+    /**
+     * The project-level tray mapping for a checked print, built as
+     * bambu-printer-mcp builds it: position = project filament, value = absolute
+     * tray (0-15 AMS, 128+ AMS-HT, 254 external; 255 the right/main external
+     * spool on dual-nozzle printers, -1 unused). ams_mapping is taken as given;
+     * ams_slots supplies one tray per used filament and is expanded against the
+     * plate's filament_ids; use_ams:false maps every used filament to the
+     * external spool of its nozzle. Every used position must end up mapped.
+     * The wire form pads to the historical five entries.
+     */
+    checkedAmsMapping(model, options, inspection, projectMetadata) {
+        const dualNozzle = isDualNozzleModel(model);
+        const externalTrays = dualNozzle ? [254, 255] : [254];
+        const useAMS = options.useAMS !== false;
+        const validate = (value, label) => {
+            if (!Number.isInteger(value) || value < -1 ||
+                (value > 15 && value < 128) || value > (dualNozzle ? 255 : 254)) {
+                throw new Error(`${label} values must be integers in ${describeAmsTrayRange({ dualNozzle })}; got ${String(value)}`);
+            }
+        };
+        let baseMapping;
+        if (options.amsMapping && options.amsMapping.length > 0) {
+            for (const value of options.amsMapping)
+                validate(value, "ams_mapping");
+            baseMapping = options.amsMapping.slice();
+        }
+        else if (options.amsSlots && options.amsSlots.length > 0) {
+            for (const value of options.amsSlots)
+                validate(value, "ams_slots");
+            const positions = projectMetadata.usedFilamentPositions;
+            if (options.amsSlots.length !== positions.length) {
+                throw new Error(`ams_slots length ${options.amsSlots.length} does not match used filament count ${positions.length} ` +
+                    `(plate uses positions ${JSON.stringify(positions)}). Provide one tray per used filament, or use ams_mapping for a raw project-level array.`);
+            }
+            baseMapping = Array(Math.max(projectMetadata.projectFilamentCount, ...positions.map((p) => p + 1))).fill(-1);
+            positions.forEach((position, index) => { baseMapping[position] = options.amsSlots[index]; });
+        }
+        else {
+            if (useAMS) {
+                throw new Error("AMS printing requires ams_slots or ams_mapping for this sliced file. " +
+                    `Plate uses project filament positions ${JSON.stringify(inspection.usedFilamentPositions)}; pass one tray per used filament (for example ams_slots: [0]), or use_ams:false for the external spool.`);
+            }
+            const positions = inspection.usedFilamentPositions;
+            baseMapping = Array(Math.max(inspection.materials.length, projectMetadata.projectFilamentCount, ...positions.map((p) => p + 1), 1)).fill(-1);
+            for (const position of positions) {
+                baseMapping[position] = externalTrayForNozzle(inspection.filamentNozzleIndices?.[position], dualNozzle);
+            }
+        }
+        for (const position of inspection.usedFilamentPositions) {
+            if (baseMapping[position] === undefined || baseMapping[position] < 0) {
+                throw new Error(`Missing physical filament mapping for project filament ${position}. ` +
+                    "Pass ams_slots (one tray per used filament) or ams_mapping with a tray for every used project filament, or use_ams:false for the external spool.");
+            }
+            if (!useAMS && !externalTrays.includes(baseMapping[position])) {
+                throw new Error(`External-spool printing requires external spool mapping (${externalTrays.join(" or ")}).`);
+            }
+        }
+        const amsMapping = Array.from({ length: Math.max(5, baseMapping.length, projectMetadata.projectFilamentCount) }, (_, index) => (index < baseMapping.length ? baseMapping[index] : -1));
+        return { baseMapping, amsMapping, useAMS };
+    }
     /**
      * A published print command is not proof the printer took it. Listen to the
      * reports the printer pushes anyway (no extra pushall polling on weak P1
@@ -407,19 +677,156 @@ export class BambuImplementation extends PrinterImplementation {
             },
         };
     }
-    /** Stop is never gated or queued behind pending checked operations. */
-    async cancelJob(host, port, apiKey) {
+    /** A refused or unconfirmed-then-failed dispatch leaves no job to resume. */
+    async settleRecorded(watcher, host, serial, remotePath) {
+        try {
+            return await watcher.settled();
+        }
+        catch (error) {
+            this.forgetCheckedJob(host, serial, remotePath);
+            throw error;
+        }
+    }
+    /**
+     * Stop is never gated or queued behind pending checked operations, and it
+     * retires the resume record. dispatch sends it over the route that printed
+     * (FULU's BambuNetwork); without one it goes over LAN MQTT.
+     */
+    async cancelJob(host, port, apiKey, dispatch) {
         const [serial, token] = this.extractBambuCredentials(apiKey);
         cancelPendingPrinterOperations(host, serial);
-        const printer = await this.getPrinter(host, serial, token);
+        this.checkedJobs.delete(`${host}\n${serial}`);
         try {
-            await publishBambuCommand(printer, "print", "stop");
-            return { status: "success", message: "Cancel command sent successfully." };
+            if (dispatch)
+                return await dispatch();
+            const printer = await this.getPrinter(host, serial, token);
+            const reply = await sendDirectControl(printer, "stop");
+            return { status: "success", confirmed: Boolean(reply), message: reply ? "The printer accepted Stop." : "Cancel command sent successfully." };
         }
         catch (error) {
             throw new Error(`Failed to cancel print: ${error.message}`);
         }
     }
+    /** Pause is never gated. */
+    async pauseJob(host, port, apiKey, dispatch) {
+        const [serial, token] = this.extractBambuCredentials(apiKey);
+        try {
+            if (dispatch) {
+                const result = await dispatch();
+                return { status: "success", message: "Pause command sent successfully.", ...result, action: "pause" };
+            }
+            const printer = await this.getPrinter(host, serial, token);
+            const reply = await sendDirectControl(printer, "pause");
+            if (!reply)
+                await sleep(COMMAND_SETTLE_MS);
+            return { status: "success", action: "pause", confirmed: Boolean(reply), message: reply ? "The printer accepted Pause." : "Pause command sent successfully." };
+        }
+        catch (error) {
+            throw new Error(`Failed to pause print: ${error.message}`);
+        }
+    }
+    /**
+     * Resume reheats and moves the printer, so it is gated like a print start:
+     * only the job this server inspected and started, while a fresh report shows
+     * it paused, with its bytes re-read over FTPS and compared. Only a file that
+     * could not be re-read, and that this server did not upload itself, asks a
+     * person. The record must still be current at every check.
+     */
+    async resumeJob(host, port, apiKey, dispatch) {
+        const [serial, token] = this.extractBambuCredentials(apiKey);
+        return withPrinterOperation(host, serial, async (assertActive) => {
+            const key = `${host}\n${serial}`;
+            const checked = this.checkedJobs.get(key);
+            if (!checked)
+                throw new Error("Resume requires a job inspected and started by this server instance. Verify other jobs on the printer before resuming them there.");
+            let jobName = path.posix.basename(checked.remotePath);
+            const pausedJob = async () => {
+                assertActive();
+                const status = await this.getSafetyStatus(host, serial, token);
+                this.observeReport(host, serial, status.raw);
+                if (this.checkedJobs.get(key) !== checked) {
+                    throw new Error(`${jobName} is no longer the job this server started: it was cancelled, it ended, or another job took its place. Nothing was sent; check the printer and resume it there.`);
+                }
+                validatePrinterState(status, { ...checked.requirements, requireIdle: false });
+                if (status.raw.gcode_state !== "PAUSE")
+                    throw new Error("Resume requires a freshly reported paused job.");
+                if (!reportsJob(status.raw, checked.remotePath))
+                    throw new Error("Paused job identity does not match this server's inspected artifact.");
+                jobName = reportedJobName(status.raw) ?? jobName;
+                assertActive();
+            };
+            await pausedJob();
+            const reread = await this.rereadJob(host, token, checked);
+            if ("changed" in reread) {
+                if (this.checkedJobs.get(key) === checked)
+                    this.checkedJobs.delete(key);
+                throw new Error(`${jobName} on the printer is no longer the file this server inspected (SHA-256 of ${reread.changed} changed). Nothing was sent, and this job can no longer be resumed from here.`);
+            }
+            const unread = "unread" in reread ? reread.unread : undefined;
+            if (unread !== undefined && checked.uploadedHere) {
+                throw new Error(`Could not re-read ${jobName} from the printer over FTPS to confirm it is the inspected file (${unread}). Nothing was sent; resume it at the printer.`);
+            }
+            const bytesVerified = "verified" in reread;
+            assertActive();
+            if (!bytesVerified) {
+                // Bambu's plug-in placed this file and it cannot be handed back, so only a person can tell it is still the inspected job.
+                await requireHumanConfirmation(this.confirm, `Resume ${jobName} on ${checked.model.toUpperCase()} (${serial})? Bambu's plug-in placed the file and it could not be re-read over FTPS (${unread}), so it is matched by its unique name only. ` +
+                    `It reheats to its targets (peak nozzle ${checked.maxNozzleTemperature}°C, bed ${checked.maxBedTemperature}°C, chamber ${checked.maxChamberTemperature}°C) and moves. ` +
+                    `Materials: ${checked.materials.length ? checked.materials.join(", ") : "none declared"}. Inspected file SHA-256: ${checked.sha256}. ` +
+                    "Confirm the nozzle path is clear and the filament is still loaded.");
+            }
+            // The job may have been resumed, stopped or replaced at the printer during the re-read or the prompt.
+            await pausedJob();
+            if (dispatch) {
+                const result = await dispatch(assertActive, pausedJob);
+                return { status: "success", message: `Resume command sent for ${jobName}.`, ...result, action: "resume", jobName, bytesVerified };
+            }
+            const printer = await this.getPrinter(host, serial, token);
+            assertActive();
+            const reply = await sendDirectControl(printer, "resume");
+            if (!reply)
+                await sleep(COMMAND_SETTLE_MS);
+            return { status: "success", action: "resume", confirmed: Boolean(reply), message: reply ? `The printer accepted Resume for ${jobName}.` : `Resume command sent for ${jobName}.`, jobName, bytesVerified };
+        });
+    }
+    /**
+     * Re-read a started job's bytes over FTPS: the uploaded file, else the plate
+     * G-code the printer extracted from the project to print it. The first file
+     * that can be read decides; a mismatch is reported as changed.
+     */
+    async rereadJob(host, token, checked) {
+        const candidates = [{ remote: checked.remotePath, sha256: checked.sha256 }];
+        if (checked.plate)
+            candidates.push({ remote: extractedPlatePath(checked.remotePath, checked.plate.index), sha256: checked.plate.sha256 });
+        const failures = [];
+        for (const candidate of candidates) {
+            let sha256;
+            try {
+                sha256 = await this.remoteSha256(host, token, candidate.remote);
+            }
+            catch (error) {
+                failures.push(`${candidate.remote}: ${error.message}`);
+                continue;
+            }
+            return sha256 === candidate.sha256 ? { verified: candidate.remote } : { changed: candidate.remote };
+        }
+        return { unread: failures.join("; ") };
+    }
+    /** SHA-256 of a printer file, streamed from an FTPS download into a private directory. */
+    async remoteSha256(host, token, remotePath) {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bambu-resume-check-"));
+        try {
+            const localPath = path.join(directory, "job");
+            await this.ftpDownload(host, token, remotePath.replace(/^\/+/, ""), localPath);
+            const hash = createHash("sha256");
+            for await (const chunk of createReadStream(localPath))
+                hash.update(chunk);
+            return hash.digest("hex");
+        }
+        finally {
+            await fs.rm(directory, { recursive: true, force: true });
+        }
+    }
     async setTemperature(host, port, apiKey, component, temperature, options = {}) {
         const normalizedComponent = String(component).toLowerCase();
         const heater = normalizedComponent === "bed" ? "bed" :
@@ -453,8 +860,6 @@ export class BambuImplementation extends PrinterImplementation {
                     ? manualHeatingRequirements(current, model, nozzleDiameter, material)
                     : { model: model, nozzleDiameters: [] });
                 validateHeatingStatus(await this.getSafetyStatus(host, serial, token));
-                await this.confirmHardwareAction(`Heat ${heater} on ${model.toUpperCase()} (${serial}) to ${targetTemperature}°C?` +
-                    (material && heater === "nozzle" ? ` Declared material: ${material}. Confirm the physical spool label.` : ""));
                 assertActive();
                 validateHeatingStatus(await this.getSafetyStatus(host, serial, token));
             }
@@ -545,20 +950,21 @@ export class BambuImplementation extends PrinterImplementation {
         }
         const initialStatus = await this.getSafetyStatus(host, serial, token);
         this.validateLoadedGcodeState(initialStatus, inspection);
-        await this.confirmPrintPreflight(serial, initialStatus, inspection);
-        const confirmedStatus = await this.getSafetyStatus(host, serial, token);
-        this.validateLoadedGcodeState(confirmedStatus, inspection);
+        const recheckedStatus = await this.getSafetyStatus(host, serial, token);
+        this.validateLoadedGcodeState(recheckedStatus, inspection);
         assertActive();
         // Start a uniquely named copy of the inspected bytes, never a name that can change.
         const remotePath = path.posix.join(path.posix.dirname(filename), uniquePrintName(filename));
         await this.ftpUpload(host, token, filePath, `/${remotePath}`);
         const dispatchStatus = await this.getSafetyStatus(host, serial, token);
-        this.validateLoadedGcodeState(dispatchStatus, inspection);
+        const requirements = this.validateLoadedGcodeState(dispatchStatus, inspection);
+        const resumeFile = await checkedFile(inspection, filePath);
         const printer = await this.getPrinter(host, serial, token);
         assertActive();
         const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
         await publishBambuCommand(printer, "print", "gcode_file", { param: remotePath });
-        const dispatch = await watcher.settled();
+        this.recordCheckedJob(host, serial, remotePath, requirements, resumeFile);
+        const dispatch = await this.settleRecorded(watcher, host, serial, remotePath);
         return {
             status: "success",
             uploaded: true,