mcp-3d-printer-server 1.2.20 → 1.2.21

package/dist/printers/generic-base.d.ts

@@ -3,6 +3,14 @@ import { PrinterImplementation } from "../types.js";
 import { type ConfirmHardware } from "../safety/confirmation.js";
 import { type PrintSafetyOptions } from "../safety/expected-peaks.js";
 import { type Heater } from "../safety/gcode-thermal.js";
+import type { CounterpartProgress, FilamentSlot, PrinterIdentity } from "../counterpart/contract.js";
+/** A camera snapshot URL as the firmware configures it, before resolution against the printer host. */
+export interface SnapshotCandidate {
+    url: string;
+    source: string;
+    /** True when the firmware's own settings name this URL; false for a conventional fallback. */
+    configured: boolean;
+}
 /** Normalized adapter state used by the print and heating preflight. */
 export interface GenericPrinterState {
     /** Adapter-reported state text. */
@@ -21,18 +29,56 @@ export interface HeaterComponent {
 }
 /** Download timeout for remote-start inspection; the shared client times out at 10 s. */
 export declare const REMOTE_DOWNLOAD_TIMEOUT_MS = 120000;
-/**
- * Shared print and heating gate for non-Bambu adapters. Public mutations
- * validate every input before connecting, inspect the exact bytes that are
- * uploaded, check fresh adapter state, ask a human (MCP elicitation), recheck
- * state and only then dispatch. Heater-off and cancel are never gated.
- */
 export declare abstract class GenericPrinterImplementation extends PrinterImplementation {
     private readonly confirm?;
     protected abstract readonly printerLabel: string;
     /** True when rawUploadFile(print=true) starts the uploaded bytes atomically. */
     protected readonly uploadStartsPrint: boolean;
+    /**
+     * The last job this server instance inspected and started, per printer.
+     * Cleared by cancel and by a report that the job ended, so a later job
+     * reusing the name is never resumed on this record.
+     */
+    private readonly checkedJobs;
     constructor(apiClient: AxiosInstance, confirm?: ConfirmHardware | undefined);
+    /** Normalized progress for counterpart_print_progress; throws when the printer cannot be read. */
+    abstract counterpartProgress(host: string, port: string, apiKey: string): Promise<CounterpartProgress>;
+    /** Progress that also retires the resume record once the printer reports the job ended. */
+    observedProgress(host: string, port: string, apiKey: string): Promise<CounterpartProgress>;
+    /** Optional identity fields; failures are ignored by the caller. */
+    counterpartIdentity(_host: string, _port: string, _apiKey: string): Promise<PrinterIdentity>;
+    /** Snapshot URLs from the firmware's own settings, in preference order. */
+    snapshotCandidates(_host: string, _port: string, _apiKey: string): Promise<SnapshotCandidate[]>;
+    /** The single extruder slot; adapters with a spool manager override this. */
+    counterpartFilaments(_host: string, _port: string, _apiKey: string): Promise<FilamentSlot[]>;
+    /** Whether progress reports carry layer numbers on this firmware. */
+    reportsLayers(_host: string, _port: string, _apiKey: string): Promise<boolean>;
+    supportsPauseResume(_host: string, _port: string, _apiKey: string): Promise<boolean>;
+    protected rawPauseJob?(host: string, port: string, apiKey: string): Promise<unknown>;
+    protected rawResumeJob?(host: string, port: string, apiKey: string): Promise<unknown>;
+    /** Pause is never gated, like cancel and heater-off. */
+    pauseJob(host: string, port: string, apiKey: string): Promise<{
+        status: string;
+        action: "pause";
+        message: string;
+    }>;
+    /**
+     * Resume reheats and moves the printer, so it is gated like a print start:
+     * only the job this server instance inspected and started, only while the
+     * printer freshly reports that job paused, with its bytes re-read and
+     * compared where the firmware can download them, and after human
+     * confirmation (unless the server opted out). A stop or heater-off request
+     * in the meantime cancels it.
+     */
+    resumeJob(host: string, port: string, apiKey: string): Promise<{
+        status: string;
+        action: "resume";
+        message: string;
+        jobName: string;
+        bytesVerified: boolean;
+    }>;
+    private assertPausedJob;
+    private remoteSha256;
     protected abstract rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
     protected abstract rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
     protected abstract rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;

package/dist/printers/generic-base.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { PrinterImplementation } from "../types.js";
 import { cancelPendingPrinterOperations, withPrinterOperation } from "../safety/artifact.js";
 import { MAX_PRINT_FILE_BYTES } from "../safety/archive.js";
@@ -10,18 +10,140 @@ import { assertExpectedPeaks, validateExpectedPeaks } from "../safety/expected-p
 import { assertInspectableGcodeName, finiteTemperature, genericCeilings, inspectGcodeFile, validateGenericTemperature, } from "../safety/gcode-thermal.js";
 /** Download timeout for remote-start inspection; the shared client times out at 10 s. */
 export const REMOTE_DOWNLOAD_TIMEOUT_MS = 120000;
-/**
- * Shared print and heating gate for non-Bambu adapters. Public mutations
- * validate every input before connecting, inspect the exact bytes that are
- * uploaded, check fresh adapter state, ask a human (MCP elicitation), recheck
- * state and only then dispatch. Heater-off and cancel are never gated.
- */
+const checkedJob = (name, inspection) => ({ name, sha256: inspection.sha256, peaks: inspection.peaks, materials: inspection.materials, seenRunning: false });
+const RUNNING_STATES = new Set(["preparing", "printing", "paused"]);
+/** Reports after which the checked job can no longer be resumed. */
+const ENDED_STATES = new Set(["idle", "finished", "cancelled", "failed"]);
 export class GenericPrinterImplementation extends PrinterImplementation {
     constructor(apiClient, confirm) {
         super(apiClient);
         this.confirm = confirm;
         /** True when rawUploadFile(print=true) starts the uploaded bytes atomically. */
         this.uploadStartsPrint = false;
+        /**
+         * The last job this server instance inspected and started, per printer.
+         * Cleared by cancel and by a report that the job ended, so a later job
+         * reusing the name is never resumed on this record.
+         */
+        this.checkedJobs = new Map();
+    }
+    /** Progress that also retires the resume record once the printer reports the job ended. */
+    async observedProgress(host, port, apiKey) {
+        const progress = await this.counterpartProgress(host, port, apiKey);
+        const key = this.operationKey(host, port);
+        const checked = this.checkedJobs.get(key);
+        if (checked && RUNNING_STATES.has(progress.state) && progress.job?.name === checked.name)
+            checked.seenRunning = true;
+        else if (checked?.seenRunning && (ENDED_STATES.has(progress.state) || (RUNNING_STATES.has(progress.state) && progress.job?.name !== undefined))) {
+            this.checkedJobs.delete(key);
+        }
+        return progress;
+    }
+    /** Optional identity fields; failures are ignored by the caller. */
+    async counterpartIdentity(_host, _port, _apiKey) {
+        return {};
+    }
+    /** Snapshot URLs from the firmware's own settings, in preference order. */
+    async snapshotCandidates(_host, _port, _apiKey) {
+        return [];
+    }
+    /** The single extruder slot; adapters with a spool manager override this. */
+    async counterpartFilaments(_host, _port, _apiKey) {
+        return [{ id: "ext", source: "unknown" }];
+    }
+    /** Whether progress reports carry layer numbers on this firmware. */
+    async reportsLayers(_host, _port, _apiKey) {
+        return false;
+    }
+    async supportsPauseResume(_host, _port, _apiKey) {
+        return this.rawPauseJob !== undefined && this.rawResumeJob !== undefined;
+    }
+    /** Pause is never gated, like cancel and heater-off. */
+    async pauseJob(host, port, apiKey) {
+        if (!(await this.supportsPauseResume(host, port, apiKey)) || !this.rawPauseJob) {
+            throw new Error(`Unsupported: ${this.printerLabel} has no verified pause route in this server.`);
+        }
+        await this.rawPauseJob(host, port, apiKey);
+        return { status: "success", action: "pause", message: `Pause command sent to ${this.printerLabel} (${host}:${port}).` };
+    }
+    /**
+     * Resume reheats and moves the printer, so it is gated like a print start:
+     * only the job this server instance inspected and started, only while the
+     * printer freshly reports that job paused, with its bytes re-read and
+     * compared where the firmware can download them, and after human
+     * confirmation (unless the server opted out). A stop or heater-off request
+     * in the meantime cancels it.
+     */
+    async resumeJob(host, port, apiKey) {
+        if (!(await this.supportsPauseResume(host, port, apiKey)) || !this.rawResumeJob) {
+            throw new Error(`Unsupported: ${this.printerLabel} has no verified resume route in this server.`);
+        }
+        const key = this.operationKey(host, port);
+        return withPrinterOperation(host, key, async (assertActive) => {
+            const checked = this.checkedJobs.get(key);
+            if (!checked) {
+                throw new Error(`Print safety: resume_print only resumes a job this server instance inspected and started on ${this.printerLabel}; nothing was sent. ` +
+                    "Check the paused job at the printer and resume it there.");
+            }
+            await this.assertPausedJob(host, port, apiKey, checked.name);
+            let bytesVerified = false;
+            if (this.downloadRemoteFile) {
+                const sha256 = await this.remoteSha256(host, port, apiKey, checked.name).catch(() => {
+                    throw new Error(`Print safety: could not re-read ${checked.name} from ${this.printerLabel} to confirm it is the inspected file; nothing was sent. Resume it at the printer.`);
+                });
+                if (sha256 !== checked.sha256) {
+                    this.checkedJobs.delete(key);
+                    throw new Error(`Print safety: ${checked.name} on ${this.printerLabel} is no longer the file this server inspected (SHA-256 changed); nothing was sent.`);
+                }
+                bytesVerified = true;
+            }
+            assertActive();
+            await requireHumanConfirmation(this.confirm, `Resume ${checked.name} on ${this.printerLabel} (${host}:${port})? It reheats to its targets (peak nozzle ${checked.peaks.nozzle}°C, ` +
+                `bed ${checked.peaks.bed}°C, chamber ${checked.peaks.chamber}°C) and moves. Materials: ${checked.materials.length ? checked.materials.join(", ") : "none declared"}. ` +
+                `File SHA-256: ${checked.sha256}${bytesVerified ? " (re-read from the printer)" : " (this firmware cannot re-read the file; matched by name)"}. ` +
+                "Confirm the nozzle path is clear and the filament is still loaded.", "generic");
+            assertActive();
+            // Someone may have resumed or stopped it at the printer while the prompt was open.
+            await this.assertPausedJob(host, port, apiKey, checked.name);
+            // A progress read during the prompt may have retired this record (the job ended, and a new one
+            // could now be paused under the same name); only the record that was confirmed may be resumed.
+            if (this.checkedJobs.get(key) !== checked) {
+                throw new Error(`Print safety: ${checked.name} ended on ${this.printerLabel} while the confirmation was open; nothing was sent.`);
+            }
+            assertActive();
+            await this.rawResumeJob(host, port, apiKey);
+            return {
+                status: "success",
+                action: "resume",
+                message: `Resume command sent to ${this.printerLabel} (${host}:${port}) for ${checked.name}.`,
+                jobName: checked.name,
+                bytesVerified,
+            };
+        });
+    }
+    async assertPausedJob(host, port, apiKey, name) {
+        const progress = await this.observedProgress(host, port, apiKey);
+        if (progress.state === "paused" && progress.job?.stage === "Pausing") {
+            // OctoPrint accepts a resume while still pausing and then drops it.
+            throw new Error(`Print safety: ${this.printerLabel} is still pausing; nothing was sent. Resume once it reports paused.`);
+        }
+        if (progress.state !== "paused") {
+            throw new Error(`Print safety: ${this.printerLabel} reports '${progress.state}', not a paused job; nothing was sent.`);
+        }
+        if (progress.job?.name !== name) {
+            throw new Error(`Print safety: the paused job (${progress.job?.name ?? "unknown"}) does not match the job this server started (${name}); nothing was sent.`);
+        }
+    }
+    async remoteSha256(host, port, apiKey, name) {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), "printer-resume-"));
+        try {
+            const destination = path.join(directory, "job.gcode");
+            await this.downloadRemoteFile(host, port, apiKey, name, destination);
+            return createHash("sha256").update(await fs.readFile(destination)).digest("hex");
+        }
+        finally {
+            await fs.rm(directory, { recursive: true, force: true });
+        }
     }
     /** Adapter-specific upload acknowledgement for the upload-then-start route. */
     uploadSucceeded(_data) {
@@ -45,6 +167,8 @@ export class GenericPrinterImplementation extends PrinterImplementation {
     }
     async cancelJob(host, port, apiKey) {
         cancelPendingPrinterOperations(host, this.operationKey(host, port));
+        // A cancelled job is never resumed, even if a later job reuses its name.
+        this.checkedJobs.delete(this.operationKey(host, port));
         return this.rawCancelJob(host, port, apiKey);
     }
     async setTemperature(host, port, apiKey, component, temperature, options = {}) {
@@ -166,6 +290,7 @@ export class GenericPrinterImplementation extends PrinterImplementation {
             status: "success",
             printRequested: true,
             remotePath: remoteName,
+            jobName: remoteName,
             sha256: inspection.sha256,
             materials: inspection.materials,
             peakTemperatures: inspection.peaks,
@@ -184,6 +309,7 @@ export class GenericPrinterImplementation extends PrinterImplementation {
             if (!this.uploadStartedPrint(response)) {
                 throw new Error(`${this.printerLabel} stored ${remoteName} but reports that it did not start printing it.`);
             }
+            this.checkedJobs.set(this.operationKey(host, port), checkedJob(remoteName, inspection));
             return { ...summary, response };
         }
         const upload = await this.rawUploadFile(host, port, apiKey, snapshot, remoteName, false);
@@ -196,6 +322,7 @@ export class GenericPrinterImplementation extends PrinterImplementation {
         this.assertBedClearance(dispatch, initial.finishedJob);
         assertActive();
         const response = await this.rawStartJob(host, port, apiKey, remoteName);
+        this.checkedJobs.set(this.operationKey(host, port), checkedJob(remoteName, inspection));
         return { ...summary, upload, response };
     }
     printPrompt(host, port, remoteName, inspection, state) {

package/dist/printers/klipper.d.ts

@@ -1,6 +1,37 @@
-import { GenericPrinterImplementation, type GenericPrinterState } from "./generic-base.js";
+import { GenericPrinterImplementation, type GenericPrinterState, type SnapshotCandidate } from "./generic-base.js";
+import type { CounterpartProgress, FilamentSlot, PrinterIdentity } from "../counterpart/contract.js";
+export declare const MACRO_TIMEOUT_MS = 60000;
 export declare class KlipperImplementation extends GenericPrinterImplementation {
-    protected readonly printerLabel = "Klipper/Moonraker";
+    protected readonly printerLabel: string;
+    /** Slicer estimates by host:port:filename, so a poll does not re-read file metadata. */
+    private readonly estimates;
+    /**
+     * One object query; remaining time is the file's slicer estimate minus
+     * print_duration. https://moonraker.readthedocs.io/en/latest/external_api/printer/
+     * and .../external_api/file_manager/ (estimated_time, seconds).
+     */
+    counterpartProgress(host: string, port: string, apiKey: string): Promise<CounterpartProgress>;
+    private estimatedTime;
+    reportsLayers(): Promise<boolean>;
+    /**
+     * GET /server/webcams/list: enabled webcams' snapshot_url, which may be a
+     * path relative to the host. https://moonraker.readthedocs.io/en/latest/external_api/webcams/
+     */
+    snapshotCandidates(host: string, port: string, apiKey: string): Promise<SnapshotCandidate[]>;
+    /**
+     * Spoolman through Moonraker: GET /server/spoolman/spool_id, then the proxy
+     * for /v1/spool/<id>. https://moonraker.readthedocs.io/en/latest/external_api/integrations/
+     * Spoolman color_hex has no '#'. Without Spoolman (404, null id) the slot is unknown.
+     */
+    counterpartFilaments(host: string, port: string, apiKey: string): Promise<FilamentSlot[]>;
+    counterpartIdentity(host: string, port: string, apiKey: string): Promise<PrinterIdentity>;
+    /**
+     * POST /printer/print/pause and /printer/print/resume (Moonraker printer API).
+     * Moonraker answers after the PAUSE/RESUME macro finishes (parking, retract),
+     * which can exceed the shared 10 s client timeout.
+     */
+    protected rawPauseJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawResumeJob(host: string, port: string, apiKey: string): Promise<any>;
     protected authHeaders(apiKey: string): Record<string, unknown>;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;

package/dist/printers/klipper.js

@@ -1,6 +1,12 @@
 import fs from "fs";
 import FormData from "form-data";
+import { isAxiosError } from "axios";
 import { GenericPrinterImplementation } from "./generic-base.js";
+import { finiteNumber, nonEmptyText } from "../counterpart/contract.js";
+import { mapMoonraker } from "../counterpart/progress.js";
+const PROGRESS_QUERY = "print_stats&virtual_sdcard&display_status&extruder&heater_bed&webhooks";
+const ESTIMATE_TTL_MS = 10 * 60000;
+export const MACRO_TIMEOUT_MS = 60000;
 function encodePath(filename) {
     return filename.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
 }
@@ -8,6 +14,106 @@ export class KlipperImplementation extends GenericPrinterImplementation {
     constructor() {
         super(...arguments);
         this.printerLabel = "Klipper/Moonraker";
+        /** Slicer estimates by host:port:filename, so a poll does not re-read file metadata. */
+        this.estimates = new Map();
+    }
+    /**
+     * One object query; remaining time is the file's slicer estimate minus
+     * print_duration. https://moonraker.readthedocs.io/en/latest/external_api/printer/
+     * and .../external_api/file_manager/ (estimated_time, seconds).
+     */
+    async counterpartProgress(host, port, apiKey) {
+        const data = (await this.apiClient.get(`http://${host}:${port}/printer/objects/query?${PROGRESS_QUERY}`, this.authHeaders(apiKey))).data;
+        const observedAt = new Date().toISOString();
+        const status = data?.result?.status;
+        if (!status || typeof status !== "object")
+            throw new Error("Moonraker returned no printer object status.");
+        const stats = status.print_stats ?? {};
+        const filename = nonEmptyText(stats.filename);
+        const estimate = filename && (stats.state === "printing" || stats.state === "paused")
+            ? await this.estimatedTime(host, port, apiKey, filename)
+            : undefined;
+        return mapMoonraker(status, estimate, observedAt);
+    }
+    async estimatedTime(host, port, apiKey, filename) {
+        const key = `${host}:${port}:${filename}`;
+        const cached = this.estimates.get(key);
+        if (cached && Date.now() - cached.at < ESTIMATE_TTL_MS)
+            return cached.value;
+        let value;
+        try {
+            const metadata = (await this.apiClient.get(`http://${host}:${port}/server/files/metadata?filename=${encodeURIComponent(filename)}`, this.authHeaders(apiKey))).data;
+            const estimate = finiteNumber(metadata?.result?.estimated_time ?? metadata?.estimated_time);
+            value = estimate !== undefined && estimate > 0 ? estimate : undefined;
+        }
+        catch {
+            value = undefined;
+        }
+        if (this.estimates.size > 64)
+            this.estimates.clear();
+        this.estimates.set(key, { value, at: Date.now() });
+        return value;
+    }
+    async reportsLayers() {
+        return true;
+    }
+    /**
+     * GET /server/webcams/list: enabled webcams' snapshot_url, which may be a
+     * path relative to the host. https://moonraker.readthedocs.io/en/latest/external_api/webcams/
+     */
+    async snapshotCandidates(host, port, apiKey) {
+        const data = (await this.apiClient.get(`http://${host}:${port}/server/webcams/list`, this.authHeaders(apiKey))).data;
+        const webcams = Array.isArray(data?.result?.webcams) ? data.result.webcams : [];
+        return webcams
+            .filter((webcam) => webcam?.enabled !== false && nonEmptyText(webcam?.snapshot_url))
+            .map((webcam) => ({ url: String(webcam.snapshot_url).trim(), source: "moonraker-webcam", configured: true }));
+    }
+    /**
+     * Spoolman through Moonraker: GET /server/spoolman/spool_id, then the proxy
+     * for /v1/spool/<id>. https://moonraker.readthedocs.io/en/latest/external_api/integrations/
+     * Spoolman color_hex has no '#'. Without Spoolman (404, null id) the slot is unknown.
+     */
+    async counterpartFilaments(host, port, apiKey) {
+        const unknown = [{ id: "ext", source: "unknown" }];
+        let spoolId;
+        try {
+            const active = (await this.apiClient.get(`http://${host}:${port}/server/spoolman/spool_id`, this.authHeaders(apiKey))).data;
+            spoolId = finiteNumber(active?.result?.spool_id);
+        }
+        catch (error) {
+            if (isAxiosError(error) && error.response)
+                return unknown;
+            throw error;
+        }
+        if (spoolId === undefined)
+            return unknown;
+        const proxied = (await this.apiClient.post(`http://${host}:${port}/server/spoolman/proxy`, { request_method: "GET", path: `/v1/spool/${spoolId}` }, this.authHeaders(apiKey))).data;
+        // v1 responses return the spool directly; use_v2_response wraps it in {response, error}.
+        const spool = proxied?.result?.response ?? proxied?.result;
+        const filament = spool?.filament ?? {};
+        const hex = nonEmptyText(filament.color_hex)?.replace(/^#/, "");
+        return [{
+                id: "ext",
+                material: nonEmptyText(filament.material),
+                color: hex && /^[0-9a-f]{6}$/i.test(hex) ? `#${hex.toUpperCase()}` : undefined,
+                name: nonEmptyText(filament.name),
+                source: "spoolman",
+            }];
+    }
+    async counterpartIdentity(host, port, apiKey) {
+        const info = (await this.apiClient.get(`http://${host}:${port}/printer/info`, this.authHeaders(apiKey))).data;
+        return { name: nonEmptyText(info?.result?.hostname) };
+    }
+    /**
+     * POST /printer/print/pause and /printer/print/resume (Moonraker printer API).
+     * Moonraker answers after the PAUSE/RESUME macro finishes (parking, retract),
+     * which can exceed the shared 10 s client timeout.
+     */
+    async rawPauseJob(host, port, apiKey) {
+        return (await this.apiClient.post(`http://${host}:${port}/printer/print/pause`, null, { ...this.authHeaders(apiKey), timeout: MACRO_TIMEOUT_MS })).data;
+    }
+    async rawResumeJob(host, port, apiKey) {
+        return (await this.apiClient.post(`http://${host}:${port}/printer/print/resume`, null, { ...this.authHeaders(apiKey), timeout: MACRO_TIMEOUT_MS })).data;
     }
     authHeaders(apiKey) {
         return apiKey ? { headers: { "X-Api-Key": apiKey } } : {};

package/dist/printers/octoprint.d.ts

@@ -1,7 +1,29 @@
-import { GenericPrinterImplementation, type GenericPrinterState, type HeaterComponent } from "./generic-base.js";
+import { GenericPrinterImplementation, type GenericPrinterState, type HeaterComponent, type SnapshotCandidate } from "./generic-base.js";
+import type { CounterpartProgress, PrinterIdentity } from "../counterpart/contract.js";
 export declare class OctoPrintImplementation extends GenericPrinterImplementation {
     protected readonly printerLabel = "OctoPrint";
     protected readonly uploadStartsPrint = true;
+    /**
+     * GET /api/job plus GET /api/printer (temperatures; 409 when not
+     * operational). An Operational job with no progress reads the file's print
+     * history so a cancelled job is reported as cancelled.
+     * https://docs.octoprint.org/en/master/api/job.html
+     */
+    counterpartProgress(host: string, port: string, apiKey: string): Promise<CounterpartProgress>;
+    /**
+     * Snapshot URL from GET /api/settings: the bundled Classic Webcam plugin's
+     * plugins.classicwebcam.snapshot on 1.9+, webcam.snapshotUrl on 1.8 and
+     * earlier (1.9+ still fills it through its compatibility layer), then the
+     * OctoPi convention http://host/webcam/?action=snapshot.
+     * Source: OctoPrint src/octoprint/server/api/settings.py and
+     * src/octoprint/plugins/classicwebcam/__init__.py; checked on 1.8.7 and 1.11.2.
+     */
+    snapshotCandidates(host: string, port: string, apiKey: string): Promise<SnapshotCandidate[]>;
+    counterpartIdentity(host: string, port: string, apiKey: string): Promise<PrinterIdentity>;
+    /** POST /api/job {command:"pause", action:"pause"|"resume"}; 204 on success, 409 without an active job. */
+    protected rawPauseJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawResumeJob(host: string, port: string, apiKey: string): Promise<any>;
+    private jobCommand;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;

package/dist/printers/octoprint.js

@@ -2,6 +2,8 @@ import fs from "fs";
 import FormData from "form-data";
 import { isAxiosError } from "axios";
 import { GenericPrinterImplementation } from "./generic-base.js";
+import { nonEmptyText } from "../counterpart/contract.js";
+import { mapOctoPrint } from "../counterpart/progress.js";
 const BLOCKING_FLAGS = ["printing", "paused", "pausing", "cancelling", "resuming", "finishing", "error", "closedOrError"];
 function encodePath(filename) {
     return filename.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
@@ -13,6 +15,85 @@ export class OctoPrintImplementation extends GenericPrinterImplementation {
         // POST /api/files/local with print=true uploads and starts the same bytes.
         this.uploadStartsPrint = true;
     }
+    /**
+     * GET /api/job plus GET /api/printer (temperatures; 409 when not
+     * operational). An Operational job with no progress reads the file's print
+     * history so a cancelled job is reported as cancelled.
+     * https://docs.octoprint.org/en/master/api/job.html
+     */
+    async counterpartProgress(host, port, apiKey) {
+        const base = `http://${host}:${port}`;
+        const headers = { "X-Api-Key": apiKey };
+        const job = (await this.apiClient.get(`${base}/api/job`, { headers })).data;
+        let printer;
+        try {
+            printer = (await this.apiClient.get(`${base}/api/printer`, { headers })).data;
+        }
+        catch (error) {
+            if (!(isAxiosError(error) && error.response?.status === 409))
+                throw error;
+        }
+        const observedAt = new Date().toISOString();
+        let lastPrint;
+        const file = job?.job?.file;
+        if (String(job?.state ?? "").toLowerCase() === "operational" && typeof file?.path === "string" && file.path &&
+            (job?.progress?.completion === null || job?.progress?.completion === undefined)) {
+            const origin = file.origin === "sdcard" ? "sdcard" : "local";
+            lastPrint = await this.apiClient.get(`${base}/api/files/${origin}/${encodePath(file.path)}`, { headers })
+                .then((response) => response.data?.prints?.last)
+                .catch(() => undefined);
+        }
+        return mapOctoPrint({ job, printer, lastPrint }, observedAt);
+    }
+    /**
+     * Snapshot URL from GET /api/settings: the bundled Classic Webcam plugin's
+     * plugins.classicwebcam.snapshot on 1.9+, webcam.snapshotUrl on 1.8 and
+     * earlier (1.9+ still fills it through its compatibility layer), then the
+     * OctoPi convention http://host/webcam/?action=snapshot.
+     * Source: OctoPrint src/octoprint/server/api/settings.py and
+     * src/octoprint/plugins/classicwebcam/__init__.py; checked on 1.8.7 and 1.11.2.
+     */
+    async snapshotCandidates(host, port, apiKey) {
+        const settings = (await this.apiClient.get(`http://${host}:${port}/api/settings`, { headers: { "X-Api-Key": apiKey } })).data;
+        const candidates = [];
+        if (settings?.webcam?.webcamEnabled !== false) {
+            const configured = [
+                settings?.plugins?.classicwebcam?.snapshot,
+                settings?.webcam?.snapshotUrl,
+                ...(Array.isArray(settings?.webcam?.webcams) ? settings.webcam.webcams.map((webcam) => webcam?.compat?.snapshot) : []),
+            ];
+            for (const url of configured) {
+                const text = nonEmptyText(url);
+                if (text)
+                    candidates.push({ url: text, source: "octoprint-settings", configured: true });
+            }
+        }
+        candidates.push({ url: `http://${host}/webcam/?action=snapshot`, source: "octoprint-fallback", configured: false });
+        return candidates;
+    }
+    async counterpartIdentity(host, port, apiKey) {
+        const headers = { "X-Api-Key": apiKey };
+        const [profiles, settings] = await Promise.all([
+            this.apiClient.get(`http://${host}:${port}/api/printerprofiles`, { headers }).then((r) => r.data).catch(() => undefined),
+            this.apiClient.get(`http://${host}:${port}/api/settings`, { headers }).then((r) => r.data).catch(() => undefined),
+        ]);
+        const all = Object.values(profiles?.profiles ?? {});
+        const profile = all.find((entry) => entry?.current) ?? all.find((entry) => entry?.default);
+        return { model: nonEmptyText(profile?.model), name: nonEmptyText(settings?.appearance?.name) ?? nonEmptyText(profile?.name) };
+    }
+    /** POST /api/job {command:"pause", action:"pause"|"resume"}; 204 on success, 409 without an active job. */
+    async rawPauseJob(host, port, apiKey) {
+        return this.jobCommand(host, port, apiKey, { command: "pause", action: "pause" });
+    }
+    async rawResumeJob(host, port, apiKey) {
+        return this.jobCommand(host, port, apiKey, { command: "pause", action: "resume" });
+    }
+    async jobCommand(host, port, apiKey, body) {
+        const response = await this.apiClient.post(`http://${host}:${port}/api/job`, body, {
+            headers: { "X-Api-Key": apiKey, "Content-Type": "application/json" },
+        });
+        return response.data;
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/api/printer`;
         const response = await this.apiClient.get(url, {

package/dist/printers/prusa.d.ts

@@ -1,4 +1,5 @@
 import { GenericPrinterImplementation, type GenericPrinterState, type HeaterComponent } from "./generic-base.js";
+import type { CounterpartProgress, PrinterIdentity } from "../counterpart/contract.js";
 export declare class PrusaImplementation extends GenericPrinterImplementation {
     protected readonly printerLabel = "Prusa";
     private buildAuthHeaders;
@@ -9,6 +10,18 @@ export declare class PrusaImplementation extends GenericPrinterImplementation {
     private isFallbackStatus;
     private getWithFallback;
     private postWithFallback;
+    /**
+     * PrusaLink GET /api/v1/status, plus GET /api/v1/job for the file name
+     * (204 when there is no job). Older firmware without /api/v1 uses the
+     * OctoPrint-compatible /api/job and /api/printer.
+     * https://github.com/prusa3d/Prusa-Link-Web/blob/master/spec/openapi.yaml
+     */
+    counterpartProgress(host: string, port: string, apiKey: string): Promise<CounterpartProgress>;
+    counterpartIdentity(host: string, port: string, apiKey: string): Promise<PrinterIdentity>;
+    /** PUT /api/v1/job/{id}/pause; the OctoPrint-compatible POST /api/job on older firmware. */
+    protected rawPauseJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawResumeJob(host: string, port: string, apiKey: string): Promise<any>;
+    private jobControl;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;

package/dist/printers/prusa.js

@@ -1,5 +1,7 @@
 import { isAxiosError } from "axios";
 import { GenericPrinterImplementation } from "./generic-base.js";
+import { finiteNumber, nonEmptyText } from "../counterpart/contract.js";
+import { mapOctoPrint, mapPrusaLink } from "../counterpart/progress.js";
 import fs from "fs";
 import FormData from "form-data";
 const PRUSALINK_READY_STATES = new Set(["IDLE", "READY", "FINISHED", "STOPPED"]);
@@ -96,6 +98,63 @@ export class PrusaImplementation extends GenericPrinterImplementation {
         }
         throw lastError ?? new Error("No compatible Prusa POST endpoint found.");
     }
+    /**
+     * PrusaLink GET /api/v1/status, plus GET /api/v1/job for the file name
+     * (204 when there is no job). Older firmware without /api/v1 uses the
+     * OctoPrint-compatible /api/job and /api/printer.
+     * https://github.com/prusa3d/Prusa-Link-Web/blob/master/spec/openapi.yaml
+     */
+    async counterpartProgress(host, port, apiKey) {
+        const baseUrl = this.buildBaseUrl(host, port);
+        const headers = this.buildAuthHeaders(apiKey);
+        let status;
+        try {
+            status = (await this.apiClient.get(`${baseUrl}/api/v1/status`, { headers })).data;
+        }
+        catch (error) {
+            if (!this.isFallbackStatus(error))
+                throw error;
+            const job = (await this.apiClient.get(`${baseUrl}/api/job`, { headers })).data;
+            const printer = await this.apiClient.get(`${baseUrl}/api/printer`, { headers }).then((r) => r.data).catch(() => undefined);
+            return mapOctoPrint({ job, printer }, new Date().toISOString());
+        }
+        const observedAt = new Date().toISOString();
+        let job;
+        if (status?.job && finiteNumber(status.job.id) !== undefined) {
+            const response = await this.apiClient.get(`${baseUrl}/api/v1/job`, { headers }).catch(() => undefined);
+            job = response?.status === 200 ? response.data : undefined;
+        }
+        return mapPrusaLink(status, job, observedAt);
+    }
+    async counterpartIdentity(host, port, apiKey) {
+        const info = (await this.apiClient.get(`${this.buildBaseUrl(host, port)}/api/v1/info`, { headers: this.buildAuthHeaders(apiKey) })).data;
+        return { name: nonEmptyText(info?.name) ?? nonEmptyText(info?.hostname), serial: nonEmptyText(info?.serial) };
+    }
+    /** PUT /api/v1/job/{id}/pause; the OctoPrint-compatible POST /api/job on older firmware. */
+    async rawPauseJob(host, port, apiKey) {
+        return this.jobControl(host, port, apiKey, "pause");
+    }
+    async rawResumeJob(host, port, apiKey) {
+        return this.jobControl(host, port, apiKey, "resume");
+    }
+    async jobControl(host, port, apiKey, action) {
+        const baseUrl = this.buildBaseUrl(host, port);
+        const headers = this.buildAuthHeaders(apiKey);
+        let id;
+        try {
+            id = finiteNumber((await this.apiClient.get(`${baseUrl}/api/v1/status`, { headers })).data?.job?.id);
+        }
+        catch (error) {
+            if (!this.isFallbackStatus(error))
+                throw error;
+            const response = await this.apiClient.post(`${baseUrl}/api/job`, { command: "pause", action }, { headers });
+            return response.data;
+        }
+        if (id === undefined)
+            throw new Error(`PrusaLink reports no current job to ${action}; nothing was sent.`);
+        const response = await this.apiClient.put(`${baseUrl}/api/v1/job/${id}/${action}`, undefined, { headers });
+        return response.data;
+    }
     async getStatus(host, port, apiKey) {
         const response = await this.getWithFallback(host, port, apiKey, [
             "/api/v1/status",