bambu-printer-mcp 1.1.26 → 1.1.28

package/scripts/setup-bambu-native.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+// Install the optional X2D native transport on Linux: build the helper from
+// this package's source and install Bambu's networking plug-in plus the slicer
+// certificates under one private directory. Every download is pinned to an
+// exact version and SHA-256. `--check-update` reports newer plug-ins and
+// whether their PrintParams layout still matches the helper; it never installs
+// an unpinned plug-in, because a layout change would corrupt print parameters.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import JSZip from "jszip";
+// The server owns the install layout; reuse it so setup and server cannot drift.
+import {
+  BAMBU_NATIVE_CERTIFICATES, BAMBU_NATIVE_PINNED_PLUGIN, BAMBU_NATIVE_PLUGIN_LIBRARIES, BAMBU_NATIVE_SOURCE, bambuNativeHomeDir,
+  bambuNativeManagedPaths, sha256File, sha256Hex as sha256,
+} from "../dist/bambu-native.js";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BUILD_SCRIPT = path.join(PACKAGE_ROOT, "scripts/build-bambu-native.sh");
+const DOWNLOAD_TIMEOUT_MS = 300_000;
+const MAX_DOWNLOAD_BYTES = 128 * 1024 * 1024;
+
+// Bambu Studio v02.08.02.61 declares network agent 02.08.02.54 with the same
+// PrintParams layout as native/bambu-native-print.cpp. The server owns the
+// version and library checksums; this adds where to download them from.
+export const PINNED = Object.freeze({
+  studioTag: "v02.08.02.61",
+  plugin: Object.freeze({
+    version: BAMBU_NATIVE_PINNED_PLUGIN.version,
+    url: `https://public-cdn.bblmw.com/upgrade/studio/plugins/${BAMBU_NATIVE_PINNED_PLUGIN.version}/f1a94b8828/linux_${BAMBU_NATIVE_PINNED_PLUGIN.version}.zip`,
+    sha256: "a7ea8ccec85ab5a7b8959a5697f7be957d58da82e67aad1cb0ad9b3cdf5baed6",
+    // The networking plug-in opens the eMMC file tunnel through libBambuSource
+    // in its own directory; without it uploads fail with -4.
+    members: BAMBU_NATIVE_PINNED_PLUGIN.sha256,
+  }),
+  certificates: Object.freeze({
+    "slicer_base64.cer": "f504dc1c37bc9741b7a95198914e67f3f6f1d917b1e45eaa14b9e84eb7b51ec8",
+    "printer.cer": "36f2bcee347ec7adce719b5fd350099591a4d3d0ec4e039c7019890d78e152a0",
+  }),
+});
+
+const certificateUrl = (tag, name) =>
+  `https://raw.githubusercontent.com/bambulab/BambuStudio/${tag}/resources/cert/${name}`;
+const networkingHeaderUrl = (tag) =>
+  `https://raw.githubusercontent.com/bambulab/BambuStudio/${tag}/src/slic3r/Utils/bambu_networking.hpp`;
+
+
+function managedPaths(home) {
+  return bambuNativeManagedPaths({ ...process.env, BAMBU_NATIVE_HOME: home });
+}
+
+function assertSha256(buffer, expected, label) {
+  const actual = sha256(buffer);
+  if (actual !== expected) {
+    throw new Error(`${label} checksum mismatch: expected ${expected}, got ${actual}. Nothing was installed.`);
+  }
+}
+
+/** Read a response body, aborting as soon as it exceeds the limit. */
+export async function readLimited(response, limit, url) {
+  const declared = Number(response.headers.get("content-length") || 0);
+  if (declared > limit) throw new Error(`Download too large (${declared} bytes): ${url}`);
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of response.body ?? []) {
+    received += chunk.length;
+    if (received > limit) throw new Error(`Download exceeded ${limit} bytes: ${url}`);
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+async function defaultFetchBytes(url, headers = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { headers, signal: controller.signal });
+    if (!response.ok) throw new Error(`Download failed (${response.status} ${response.statusText}): ${url}`);
+    return await readLimited(response, MAX_DOWNLOAD_BYTES, url);
+  } finally {
+    // Also cancels a body left unread after an oversized response.
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+/** Write through a sibling temporary file so readers never see partial content. */
+function writeFileAtomic(target, buffer, mode) {
+  const temporary = `${target}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(temporary, buffer, { mode });
+    fs.chmodSync(temporary, mode);
+    fs.renameSync(temporary, target);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+function fileMatches(file, expected) {
+  try {
+    return fs.statSync(file).isFile() && sha256File(file) === expected;
+  } catch {
+    return false;
+  }
+}
+
+/** Extract exactly the pinned libraries from Bambu's archive, each verified. */
+export async function extractPlugin(archive, expectedMembers) {
+  const zip = await JSZip.loadAsync(archive, { checkCRC32: true });
+  const extracted = new Map();
+  for (const [name, expected] of Object.entries(expectedMembers)) {
+    // JSZip rewrites unsafe names such as "../x" to "x"; match the raw name so
+    // only a genuine top-level member is accepted.
+    const matches = Object.values(zip.files)
+      .filter(entry => !entry.dir && (entry.unsafeOriginalName ?? entry.name) === name);
+    if (matches.length !== 1) throw new Error(`Plug-in archive must contain exactly one top-level ${name}.`);
+    const member = await matches[0].async("nodebuffer");
+    assertSha256(member, expected, name);
+    extracted.set(name, member);
+  }
+  return extracted;
+}
+
+export function assertSupportedHost(platform = process.platform, arch = process.arch) {
+  if (platform !== "linux") {
+    throw new Error("This setup is for Linux. On macOS, install Bambu Studio and run `npm run build:native` in the package directory.");
+  }
+  // Bambu publishes its Linux networking plug-in for x86-64 only.
+  if (arch !== "x64") throw new Error(`Bambu's Linux networking plug-in is only published for x86-64; this host is ${arch}.`);
+}
+
+export function buildHelper(output, { runner = execFileSync } = {}) {
+  runner("/bin/sh", [BUILD_SCRIPT, "--output", output], { stdio: ["ignore", "pipe", "pipe"], timeout: 180_000 });
+}
+
+/**
+ * Load the installed plug-in and its tunnel library through the helper,
+ * offline. Missing system libraries surface here instead of on a stop command.
+ */
+export function checkPlugin(paths, { runner = execFileSync } = {}) {
+  try {
+    runner(paths.helper, ["--check-plugin"], {
+      env: { ...process.env, BAMBU_NATIVE_PLUGIN: paths.plugin }, stdio: ["ignore", "pipe", "pipe"], timeout: 60_000,
+    });
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    throw new Error(`The installed Bambu plug-in cannot be loaded on this host: ${detail}`);
+  }
+}
+
+export async function install({
+  home = bambuNativeHomeDir(),
+  pinned = PINNED,
+  fetchBytes = defaultFetchBytes,
+  build = buildHelper,
+  check = checkPlugin,
+  log = message => console.error(message),
+  platform = process.platform,
+  arch = process.arch,
+} = {}) {
+  assertSupportedHost(platform, arch);
+  const sameNames = (a, b) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+  if (!sameNames(Object.keys(pinned.certificates), BAMBU_NATIVE_CERTIFICATES) ||
+    !sameNames(Object.keys(pinned.plugin.members), BAMBU_NATIVE_PLUGIN_LIBRARIES)) {
+    throw new Error("Pinned files must match the plug-in libraries and certificates the server requires.");
+  }
+  const paths = managedPaths(home);
+  const directories = [path.dirname(paths.helper), path.dirname(paths.plugin), paths.certDir, paths.configDir];
+  // Only restrict a directory this setup creates; never change an existing one.
+  if (!fs.existsSync(home)) {
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    fs.chmodSync(home, 0o700);
+  }
+  for (const directory of directories) fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+
+  // Fetch and verify everything before replacing any installed file.
+  const pluginDirectory = path.dirname(paths.plugin);
+  let libraries = new Map();
+  if (Object.entries(pinned.plugin.members).every(([name, expected]) => fileMatches(path.join(pluginDirectory, name), expected))) {
+    log(`Plug-in ${pinned.plugin.version} already installed and verified.`);
+  } else {
+    log(`Downloading Bambu networking plug-in ${pinned.plugin.version}...`);
+    const archive = await fetchBytes(pinned.plugin.url);
+    assertSha256(archive, pinned.plugin.sha256, "Plug-in archive");
+    libraries = await extractPlugin(archive, pinned.plugin.members);
+  }
+  const certificates = [];
+  for (const [name, expected] of Object.entries(pinned.certificates)) {
+    const target = path.join(paths.certDir, name);
+    if (fileMatches(target, expected)) continue;
+    log(`Downloading ${name} from Bambu Studio ${pinned.studioTag}...`);
+    const buffer = await fetchBytes(certificateUrl(pinned.studioTag, name));
+    assertSha256(buffer, expected, name);
+    certificates.push([target, buffer]);
+  }
+
+  // Withdraw the receipt before replacing anything: until a complete, checked
+  // installation is written again, the server refuses this helper.
+  fs.rmSync(paths.receipt, { force: true });
+
+  // Rebuild every time so the helper always matches this package's source.
+  const helper = paths.helper;
+  log("Building the native helper...");
+  build(helper);
+  if (!fs.statSync(helper).isFile()) throw new Error(`Helper build did not produce ${helper}.`);
+
+  for (const [name, buffer] of libraries) writeFileAtomic(path.join(pluginDirectory, name), buffer, 0o600);
+  for (const [target, buffer] of certificates) writeFileAtomic(target, buffer, 0o600);
+  log("Checking that the plug-in loads...");
+  check(paths);
+  const receipt = {
+    pluginVersion: pinned.plugin.version,
+    pluginLibraries: pinned.plugin.members,
+    studioTag: pinned.studioTag,
+    helperSourceSha256: sha256File(BAMBU_NATIVE_SOURCE),
+    installedAt: new Date().toISOString(),
+  };
+  writeFileAtomic(paths.receipt, Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`), 0o600);
+  log(`Installed the X2D native transport in ${home}.`);
+  if (path.resolve(home) !== path.resolve(bambuNativeHomeDir())) {
+    log(`Set BAMBU_NATIVE_HOME=${home} in the MCP server's environment so it uses this installation.`);
+  }
+  return { home, helper, plugin: paths.plugin, receipt };
+}
+
+/** Report installed files against the pinned versions; never contacts the network. */
+export function verify({ home = bambuNativeHomeDir(), pinned = PINNED, check = checkPlugin } = {}) {
+  const problems = [];
+  const paths = managedPaths(home);
+  const helper = paths.helper;
+  try {
+    if ((fs.statSync(helper).mode & 0o111) === 0) problems.push(`${helper} is not executable`);
+  } catch {
+    problems.push(`${helper} is missing`);
+  }
+  for (const [name, expected] of Object.entries(pinned.plugin.members)) {
+    if (!fileMatches(path.join(path.dirname(paths.plugin), name), expected)) {
+      problems.push(`${name} is missing or not the pinned ${pinned.plugin.version}`);
+    }
+  }
+  for (const [name, expected] of Object.entries(pinned.certificates)) {
+    if (!fileMatches(path.join(paths.certDir, name), expected)) problems.push(`${name} is missing or modified`);
+  }
+  try {
+    const receipt = JSON.parse(fs.readFileSync(paths.receipt, "utf8"));
+    if (receipt.helperSourceSha256 !== sha256File(BAMBU_NATIVE_SOURCE)) {
+      problems.push("the helper was built from a different package version; rerun setup");
+    }
+  } catch {
+    problems.push("install.json is missing or unreadable");
+  }
+  if (problems.length === 0) {
+    try {
+      check(paths);
+    } catch (error) {
+      problems.push(error.message);
+    }
+  }
+  return { ok: problems.length === 0, home, pluginVersion: pinned.plugin.version, problems };
+}
+
+/**
+ * Normalize the members of `struct PrintParams` so layout-relevant changes
+ * (added, removed, reordered or retyped fields) are detected while comments
+ * and default initializers are ignored.
+ */
+export function printParamsLayout(source) {
+  const match = /struct\s+PrintParams\s*\{([\s\S]*?)\n\s*\};/.exec(source);
+  if (!match) throw new Error("struct PrintParams not found");
+  return match[1]
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/[^\n]*/g, "")
+    .split(";")
+    .map(member => member.replace(/\{[^}]*\}\s*$/, "").replace(/=[^]*$/, "").replace(/\s+/g, " ").trim())
+    .filter(Boolean);
+}
+
+export function agentVersion(header) {
+  return /#define\s+BAMBU_NETWORK_AGENT_VERSION\s+"([0-9.]+)"/.exec(header)?.[1];
+}
+
+function studioRequestVersion(tag) {
+  const match = /^v?(\d{2})\.(\d{2})\.(\d{2})\.\d{2}$/.exec(tag);
+  if (!match) throw new Error(`Unexpected Bambu Studio release tag: ${tag}`);
+  return `${match[1]}.${match[2]}.${match[3]}.00`;
+}
+
+export async function checkUpdate({ fetchBytes = defaultFetchBytes, pinned = PINNED, helperSource = fs.readFileSync(BAMBU_NATIVE_SOURCE, "utf8") } = {}) {
+  const release = JSON.parse((await fetchBytes("https://api.github.com/repos/bambulab/BambuStudio/releases/latest",
+    { Accept: "application/vnd.github+json" })).toString("utf8"));
+  const tag = String(release.tag_name || "");
+  const requestVersion = studioRequestVersion(tag);
+  const resource = JSON.parse((await fetchBytes(
+    `https://api.bambulab.com/v1/iot-service/api/slicer/resource?slicer/plugins/cloud=${requestVersion}`,
+    {
+      "X-BBL-Client-Type": "slicer",
+      "X-BBL-Client-Name": "BambuStudio",
+      "X-BBL-Client-Version": tag.replace(/^v/, ""),
+      "X-BBL-OS-Type": "linux",
+    }
+  )).toString("utf8"));
+  const offered = resource.resources?.find(entry => entry.type === "slicer/plugins/cloud");
+  if (!offered?.version || !offered?.url) throw new Error("Bambu's plug-in service returned no Linux plug-in.");
+  const header = (await fetchBytes(networkingHeaderUrl(tag))).toString("utf8");
+  const headerAgent = agentVersion(header);
+  const helperLayout = printParamsLayout(helperSource);
+  const releaseLayout = printParamsLayout(header);
+  const layoutMatches = JSON.stringify(helperLayout) === JSON.stringify(releaseLayout);
+  return {
+    pinned: { studioTag: pinned.studioTag, plugin: pinned.plugin.version },
+    latest: { studioTag: tag, plugin: offered.version, url: offered.url, headerAgentVersion: headerAgent },
+    upToDate: offered.version === pinned.plugin.version,
+    // The header describes its own agent version; a different offered plug-in
+    // is unverified even when the layout matches.
+    headerMatchesOffered: headerAgent === offered.version,
+    printParamsLayoutMatches: layoutMatches,
+    // Members present on one side only; a pure reordering shows as a mismatch with both lists empty.
+    layoutDifferences: {
+      helperOnly: helperLayout.filter(member => !releaseLayout.includes(member)),
+      releaseOnly: releaseLayout.filter(member => !helperLayout.includes(member)),
+    },
+  };
+}
+
+function usage() {
+  return [
+    "usage: bambu-printer-mcp-native-setup [--verify | --check-update] [--home DIR]",
+    "  (default)        build the helper and install the pinned plug-in and certificates",
+    "  --verify         check the installed files without network access",
+    "  --check-update   report newer Bambu plug-ins and helper layout compatibility",
+  ].join("\n");
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let mode = "install";
+  let home;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "--verify" || argument === "--check-update") {
+      if (mode !== "install") throw new Error(usage());
+      mode = argument.slice(2);
+    } else if (argument === "--home" && argv[index + 1] && !argv[index + 1].startsWith("-")) {
+      home = path.resolve(argv[++index]);
+    } else if (argument === "--help" || argument === "-h") {
+      console.log(usage());
+      return 0;
+    } else {
+      throw new Error(usage());
+    }
+  }
+  if (mode === "verify") {
+    const result = verify({ home: home ?? bambuNativeHomeDir() });
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+  if (mode === "check-update") {
+    const result = await checkUpdate();
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  const result = await install({ home: home ?? bambuNativeHomeDir() });
+  console.log(JSON.stringify({ status: "installed", ...result }, null, 2));
+  return 0;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then(code => { process.exitCode = code; }, error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/src/bambu-native.ts

@@ -1,5 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -71,30 +73,240 @@ export type BambuNativeTemperatureCommand = {
 function firstExistingExecutable(candidates: string[]): string | undefined {
   return candidates.find((candidate) => {
     try {
-      return fs.statSync(candidate).isFile() && (fs.statSync(candidate).mode & 0o111) !== 0;
+      const stat = fs.statSync(candidate);
+      return stat.isFile() && (stat.mode & 0o111) !== 0;
     } catch {
       return false;
     }
   });
 }
 
+/**
+ * Hosts for which the native helper and Bambu's networking plug-in exist.
+ * Bambu publishes its Linux plug-in for x86-64 only.
+ */
+export function isBambuNativePlatform(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch
+): boolean {
+  return platform === "darwin" || (platform === "linux" && arch === "x64");
+}
+
+/**
+ * Private directory used by `bambu-printer-mcp-native-setup` on Linux. Mirrors
+ * nativeHomeDir() in native/bambu-native-print.cpp: empty values count as unset.
+ */
+export function bambuNativeHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  if (env.BAMBU_NATIVE_HOME) return env.BAMBU_NATIVE_HOME;
+  const configHome = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+  return path.join(configHome, "bambu-printer-mcp", "bambu-native");
+}
+
+export const BAMBU_NATIVE_CERTIFICATES = ["slicer_base64.cer", "printer.cer"] as const;
+/**
+ * The networking plug-in followed by the library it loads from its own
+ * directory for the eMMC file tunnel; without it uploads fail with -4.
+ */
+export const BAMBU_NATIVE_PLUGIN_LIBRARIES = ["libbambu_networking.so", "libBambuSource.so"] as const;
+
+/**
+ * The only Linux plug-in build whose PrintParams layout matches the helper
+ * (Bambu Studio v02.08.02.61, network agent 02.08.02.54). The setup installs
+ * exactly these files and the server refuses anything else.
+ */
+export const BAMBU_NATIVE_PINNED_PLUGIN = Object.freeze({
+  version: "02.08.02.54",
+  sha256: Object.freeze({
+    "libbambu_networking.so": "bba49709c8dea14ba70251b43965646c0a5e2cde8fd133c64f764d425691bdf2",
+    "libBambuSource.so": "4e05f16fa02740fd12f0040b9efc3e70d43446c7a1a877c6a3926ef0758ca7db",
+  } as Record<(typeof BAMBU_NATIVE_PLUGIN_LIBRARIES)[number], string>),
+});
+
+/** Layout shared by the Linux setup script, the server and the helper's environment. */
+export function bambuNativeManagedPaths(env: NodeJS.ProcessEnv = process.env) {
+  const home = bambuNativeHomeDir(env);
+  return {
+    home,
+    helper: path.join(home, "bin", "bambu-native-print"),
+    plugin: path.join(home, "plugins", BAMBU_NATIVE_PLUGIN_LIBRARIES[0]),
+    certDir: path.join(home, "cert"),
+    configDir: path.join(home, "config"),
+    receipt: path.join(home, "install.json"),
+  };
+}
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const BAMBU_NATIVE_SOURCE = path.join(PACKAGE_ROOT, "native", "bambu-native-print.cpp");
+
+export function sha256Hex(data: Buffer | string): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function sha256File(file: string): string {
+  return sha256Hex(fs.readFileSync(file));
+}
+
+let nativeSourceSha256: string | undefined;
+/** The packaged helper source never changes while the server runs. */
+function packagedHelperSha256(): string {
+  nativeSourceSha256 ??= sha256File(BAMBU_NATIVE_SOURCE);
+  return nativeSourceSha256;
+}
+
+function packageVersion(): string {
+  try {
+    return String(JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version || "");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Name the setup from this server's own version, whose helper source it
+ * accepts, and its own install directory when that is not the default.
+ */
+export function bambuNativeSetupCommand(version = packageVersion(), env: NodeJS.ProcessEnv = process.env): string {
+  const home = bambuNativeHomeDir(env);
+  const defaultHome = bambuNativeHomeDir({ HOME: env.HOME });
+  const homeOption = home === defaultHome ? "" : ` --home ${JSON.stringify(home)}`;
+  return `npx -y -p bambu-printer-mcp${version ? `@${version}` : ""} bambu-printer-mcp-native-setup${homeOption}`;
+}
+
+const linuxSetupHint = () =>
+  `Run \`${bambuNativeSetupCommand()}\` to build the helper and install the pinned networking plug-in.`;
+
+type NativeInstall = { helper: string; env: Record<string, string> };
+
+const verifiedLibraries = new Map<string, string>();
+/** Hash a plug-in library once per file version; it is ~16 MB. */
+function libraryMatches(file: string, expected: string): boolean {
+  const stat = fs.statSync(file);
+  const key = `${fs.realpathSync(file)}\n${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+  let digest = verifiedLibraries.get(key);
+  if (!digest) {
+    digest = sha256File(file);
+    verifiedLibraries.set(key, digest);
+  }
+  return digest === expected;
+}
+
+function samePath(a: string, b: string): boolean {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch {
+    return path.resolve(a) === path.resolve(b);
+  }
+}
+
+function isRegularFile(file: string): boolean {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a complete native installation. On Linux the helper, the pinned
+ * plug-in and both certificates must be present before any native route is
+ * chosen, and their resolved paths are handed to the helper so server and
+ * helper can never disagree about which plug-in is loaded.
+ */
+function resolveNativeInstall(): NativeInstall {
+  if (!isBambuNativePlatform()) {
+    throw new Error("Bambu native X2D transport requires macOS or x86-64 Linux and Bambu's networking plug-in.");
+  }
+  const helper = resolveNativeHelper();
+  if (process.platform !== "linux") return { helper, env: {} };
+
+  const managed = bambuNativeManagedPaths();
+  const plugin = process.env.BAMBU_NATIVE_PLUGIN || managed.plugin;
+  const certDir = process.env.BAMBU_NATIVE_CERT_DIR || managed.certDir;
+  const configDir = process.env.BAMBU_NATIVE_CONFIG_DIR || managed.configDir;
+  const certFile = process.env.BAMBU_NATIVE_CERT_FILE || BAMBU_NATIVE_CERTIFICATES[0];
+  if (!isRegularFile(plugin)) {
+    throw new Error(`Bambu networking plug-in is not installed at ${plugin}. ${linuxSetupHint()}`);
+  }
+  for (const library of BAMBU_NATIVE_PLUGIN_LIBRARIES.slice(1)) {
+    if (!isRegularFile(path.join(path.dirname(plugin), library))) {
+      throw new Error(`Bambu networking library ${library} is missing beside ${plugin}. ${linuxSetupHint()}`);
+    }
+  }
+  // A different plug-in build can change the PrintParams layout passed by
+  // value to start_local_print. Only an explicit trusted opt-in skips this.
+  if (process.env.BAMBU_NATIVE_ALLOW_UNPINNED_PLUGIN !== "1") {
+    const files: Array<[string, string]> = [
+      [plugin, BAMBU_NATIVE_PINNED_PLUGIN.sha256[BAMBU_NATIVE_PLUGIN_LIBRARIES[0]]],
+      ...BAMBU_NATIVE_PLUGIN_LIBRARIES.slice(1).map(library =>
+        [path.join(path.dirname(plugin), library), BAMBU_NATIVE_PINNED_PLUGIN.sha256[library]] as [string, string]),
+    ];
+    for (const [file, expected] of files) {
+      if (!libraryMatches(file, expected)) {
+        throw new Error(`${file} is not the pinned Bambu plug-in ${BAMBU_NATIVE_PINNED_PLUGIN.version}. ${linuxSetupHint()}`);
+      }
+    }
+  }
+  for (const certificate of new Set([certFile, ...BAMBU_NATIVE_CERTIFICATES.slice(1)])) {
+    if (!isRegularFile(path.join(certDir, certificate))) {
+      throw new Error(`Bambu certificate ${certificate} is missing from ${certDir}. ${linuxSetupHint()}`);
+    }
+  }
+  if (samePath(helper, managed.helper)) {
+    // A setup run from another package version builds a different helper.
+    let built: unknown;
+    try {
+      built = JSON.parse(fs.readFileSync(managed.receipt, "utf8")).helperSourceSha256;
+    } catch {
+      built = undefined;
+    }
+    if (built !== packagedHelperSha256()) {
+      throw new Error(`The installed native helper was built from a different bambu-printer-mcp version. ${linuxSetupHint()}`);
+    }
+  }
+  return {
+    helper,
+    env: { BAMBU_NATIVE_PLUGIN: plugin, BAMBU_NATIVE_CERT_DIR: certDir, BAMBU_NATIVE_CONFIG_DIR: configDir },
+  };
+}
+
 export function assertBambuNativeAvailable(): void {
-  if (process.platform !== "darwin") throw new Error("Bambu native X2D transport requires macOS and the installed Bambu Studio networking plug-in.");
-  resolveNativeHelper();
+  resolveNativeInstall();
+}
+
+/**
+ * True when X2D controls should use the native route. macOS keeps its
+ * unconditional routing. Linux opts in only with a complete installation, so
+ * stop, pause and heater-off keep their MQTT route otherwise.
+ */
+export function bambuNativeControlsAvailable(): boolean {
+  return bambuNativeUnavailableReason() === undefined;
+}
+
+/** Why native X2D controls are not used on this host, or undefined when they are. */
+export function bambuNativeUnavailableReason(): string | undefined {
+  if (process.platform === "darwin") return undefined;
+  if (process.platform !== "linux") return "Native X2D controls require macOS or x86-64 Linux.";
+  try {
+    resolveNativeInstall();
+    return undefined;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
 }
 
 function resolveNativeHelper(): string {
   const configured = process.env.BAMBU_NATIVE_HELPER?.trim();
-  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  // Linux uses only the setup-managed helper, whose receipt proves it matches
+  // this package; a package-local build could be stale after an update.
   const candidates = [
     configured,
-    path.resolve(packageRoot, "native/bambu-native-print"),
+    process.platform === "linux" ? bambuNativeManagedPaths().helper : path.resolve(PACKAGE_ROOT, "native/bambu-native-print"),
   ].filter((value): value is string => Boolean(value));
   const helper = firstExistingExecutable(candidates);
   if (!helper) {
-    throw new Error(
-      "Bambu native helper is not installed. Build native/bambu-native-print with clang++ or set BAMBU_NATIVE_HELPER."
-    );
+    throw new Error(process.platform === "linux"
+      ? `Bambu native helper is not installed. ${linuxSetupHint()} Alternatively set BAMBU_NATIVE_HELPER.`
+      : "Bambu native helper is not installed. Build native/bambu-native-print with clang++ or set BAMBU_NATIVE_HELPER.");
   }
   return helper;
 }
@@ -121,7 +333,11 @@ function isEmergencyCommand(messageJson: string): boolean {
     (command?.command === "set_nozzle_temp" && command.target_temp === 0);
 }
 
-async function interruptNativeOperations(serial: string): Promise<void> {
+/**
+ * Interrupt this printer's pending print, upload and heating helpers and
+ * resolve once they have exited, so none can still dispatch afterwards.
+ */
+export async function interruptNativeOperations(serial: string): Promise<void> {
   const pending = [...activeHelpers.values()].filter(helper => helper.serial === serial && !helper.emergency);
   for (const helper of pending) helper.interrupt();
   // Send stop/heater-off only after an older helper can no longer send a
@@ -142,11 +358,10 @@ function runNativeHelper(
   if (needsAuthorization && typeof execution.beforeDispatch !== "function") {
     throw new Error("Native dispatch requires a beforeDispatch fresh-state check.");
   }
-  assertBambuNativeAvailable();
-  const helper = resolveNativeHelper();
+  const install = resolveNativeInstall();
   return new Promise((resolve, reject) => {
-    const child = spawn(helper, [mode], {
-      env,
+    const child = spawn(install.helper, [mode], {
+      env: { ...env, ...install.env },
       stdio: ["pipe", "pipe", "pipe"],
     });
     let markClosed!: () => void;
@@ -608,7 +823,7 @@ export async function probeBambuNative(host: string, token: string): Promise<Rec
     20_000
   );
   if (result.resultCode !== 0) {
-    throw new Error(`Bambu native local tunnel probe failed (${result.resultCode}).`);
+    throw new Error(`Bambu native local tunnel probe failed (${result.resultCode}): ${result.updates.join(" | ") || tail(result.stderr, 500)}`);
   }
   return { status: "ok", route: "bambu:///local", updates: result.updates };
 }