mcp-3d-printer-server 1.2.25 → 1.2.27

package/src/counterpart/route.ts

@@ -0,0 +1,82 @@
+/** counterpart_print_route: how this server reaches the printer for prints and controls (PRD §8.4). */
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * lan: the local network through FULU's BambuNetwork bridge (or the configured X2D native or Bambu Connect mode).
+ * cloud: Bambu Cloud through FULU's bridge.
+ * developer: the local network straight to the printer (lan_mqtt_ftps), for a printer in LAN Only + Developer Mode.
+ */
+export type PrintRoute = "lan" | "cloud" | "developer";
+export const PRINT_ROUTES: readonly PrintRoute[] = ["lan", "cloud", "developer"];
+export interface Connection { mode: string; type: string }
+
+/** One connection a person can choose, as counterpart_print_route reports it. */
+export interface RouteOption {
+  id: PrintRoute;
+  label: string;
+  available: boolean;
+  /** Why it can't be chosen here, when it can't. */
+  reason?: string;
+  /** What Pause, Resume and Stop do on this connection. */
+  controls: string;
+}
+
+/** Modes that are their own local-network route and stay as configured. */
+const OWN_LOCAL_MODES = new Set(["bambu_native", "bambu_connect"]);
+
+export function routeOf(connection: Connection): PrintRoute {
+  if (connection.mode === "bambu_network") return connection.type === "cloud" ? "cloud" : "lan";
+  if (connection.mode === "lan_mqtt_ftps") return "developer";
+  return "lan";
+}
+
+/** Every connection, and whether this server can use it (bridgeConfigured: BAMBU_NETWORK_BRIDGE_COMMAND is set). */
+export function routeOptions(current: Connection, bridgeConfigured: boolean): RouteOption[] {
+  const signedControls = "Uses the configured authenticated connection for Print, Pause, Resume and Stop.";
+  const needsBridge = "Needs FULU's BambuNetwork bridge (BAMBU_NETWORK_BRIDGE_COMMAND).";
+  const ownLocal = OWN_LOCAL_MODES.has(current.mode);
+  return [
+    { id: "lan", label: "Local network", available: bridgeConfigured || ownLocal, ...(bridgeConfigured || ownLocal ? {} : { reason: needsBridge }), controls: signedControls },
+    { id: "cloud", label: "Bambu Cloud", available: bridgeConfigured, ...(bridgeConfigured ? {} : { reason: needsBridge }), controls: signedControls },
+    { id: "developer", label: "Local network, Developer Mode", available: true,
+      controls: "Pause, Resume and Stop go straight to the printer. Turn on LAN Only and Developer Mode on the printer first; Bambu Cloud and Bambu Handy then stop working for it." },
+  ];
+}
+
+/**
+ * The configured defaults for a route. Cloud and the local network use FULU's BambuNetwork; an X2D native or
+ * Bambu Connect setup keeps its own mode for the local network. Developer Mode is the direct LAN route.
+ */
+export function connectionForRoute(route: PrintRoute, current: Connection, bridgeConfigured = true): Connection {
+  const option = routeOptions(current, bridgeConfigured).find(item => item.id === route);
+  if (!option?.available) throw new Error(`The ${option?.label ?? route} connection isn't available here. ${option?.reason ?? ""}`.trim());
+  if (route === "cloud") return { mode: "bambu_network", type: "cloud" };
+  if (route === "developer") return { mode: "lan_mqtt_ftps", type: "lan" };
+  return OWN_LOCAL_MODES.has(current.mode) ? current : { mode: "bambu_network", type: "lan" };
+}
+
+/** Set KEY=value lines in a dotenv file, keeping every other line and the file's permissions. */
+export function writeEnvValues(file: string, values: Record<string, string>): void {
+  const original = fs.readFileSync(file, "utf8");
+  const lines = original.split("\n");
+  for (const [key, value] of Object.entries(values)) {
+    const pattern = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`);
+    let found = false;
+    for (let index = lines.length - 1; index >= 0; index--) {
+      if (!pattern.test(lines[index]!)) continue;
+      if (!found) { lines[index] = `${key}=${value}`; found = true; }
+      // dotenv lets a later line win: keep one line per key, the one written here.
+      else lines.splice(index, 1);
+    }
+    if (!found) {
+      if (lines.length && lines[lines.length - 1] === "") lines.splice(lines.length - 1, 0, `${key}=${value}`);
+      else lines.push(`${key}=${value}`);
+    }
+  }
+  const mode = fs.statSync(file).mode & 0o777;
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.tmp`);
+  fs.writeFileSync(temporary, lines.join("\n"), { mode });
+  fs.chmodSync(temporary, mode);
+  fs.renameSync(temporary, file);
+}

package/src/counterpart/service.ts

@@ -7,7 +7,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { isAxiosError, type AxiosInstance } from "axios";
 import type { PrinterImplementation } from "../types.js";
-import { GenericPrinterImplementation, type SnapshotCandidate } from "../printers/generic-base.js";
+import { GenericPrinterImplementation, type SnapshotCandidate, type CameraCandidate } from "../printers/generic-base.js";
+import {CameraStreams, cameraNativeAvailable, type FrameOptions} from "./camera-stream.js";
+import {openHttpCameraSource} from "./camera-sources.js";
+import {cameraNumber} from "./camera-tools.js";
 import { BambuImplementation } from "../printers/bambu.js";
 import {
   COUNTERPART_CONTRACT,
@@ -23,6 +26,27 @@ import {
   type PrinterKind,
 } from "./contract.js";
 import { mapBambu } from "./progress.js";
+import {
+  counterpartSlots,
+  externalSpools,
+  normalizePrinterFilamentInventory,
+  type FilamentProfileSource,
+  type PrinterFilamentInventory,
+} from "../printers/bambu-filaments.js";
+
+/**
+ * The Bambu print-control dispatch for the configured connection (FULU's
+ * BambuNetwork); undefined keeps LAN MQTT. Resume's dispatch receives the
+ * checks to repeat before it sends.
+ */
+export type BambuControlRoute = (command: "stop" | "pause" | "resume") =>
+  ((assertActive?: () => void, beforeDispatch?: () => Promise<void>) => Promise<any>) | undefined;
+
+/** Bambu inventory hints: the model and nozzle select model-specific filament profiles. */
+export interface BambuFilamentOptions {
+  bambuModel?: string;
+  nozzleDiameter?: string;
+}
 
 export const DEFAULT_SNAPSHOT_TIMEOUT_MS = 8_000;
 const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024;
@@ -57,12 +81,17 @@ function overrideSnapshotUrl(): string | undefined {
 }
 
 export class CounterpartService {
+  private readonly streams = new CameraStreams();
+  private readonly generations = new Map<string, number>();
+  private closed = false;
   constructor(
     private readonly implementation: (type: string) => PrinterImplementation,
     private readonly http: AxiosInstance,
     private readonly server: { name: string; version: string },
     /** The slicer filament profile for a slot's material (undefined: the configured default). */
-    private readonly filamentProfile?: (material: string | undefined) => Promise<string | undefined>
+    private readonly filamentProfile?: (material: string | undefined) => Promise<string | undefined>,
+    /** The slicer whose BBL/filament profiles resolve Bambu trays by tray_info_idx. */
+    private readonly bambuProfileSource: () => FilamentProfileSource = () => ({})
   ) {}
 
   private generic(target: PrinterTarget): GenericPrinterImplementation | undefined {
@@ -99,10 +128,10 @@ export class CounterpartService {
       const status = await this.bambu(target).getStatus(target.host, target.port, target.apiKey).catch(() => undefined);
       const model = typeof status?.model === "string" && status.model !== "Unknown" ? status.model : process.env.BAMBU_MODEL?.trim();
       identity = { model: model || undefined, serial: typeof status?.serial === "string" && status.serial ? status.serial : undefined };
-      // This server has no Bambu camera, pause or resume path; bambu-printer-mcp does.
+      // This server has no Bambu camera path; bambu-printer-mcp does.
       capabilities = {
-        progress: true, layers: true, camera: overrideSnapshotUrl() ? "http-snapshot" : "none", filaments: "none",
-        pause: false, resume: false, cancel: true, print3mf: true, gcode: true,
+        progress: true, layers: true, camera: overrideSnapshotUrl() ? "http-snapshot" : "none", filaments: "ams",
+        pause: true, resume: true, cancel: true, print3mf: true, gcode: true,
       };
     } else {
       const { host, port, apiKey } = target;
@@ -117,6 +146,9 @@ export class CounterpartService {
         pause: pauseResume, resume: pauseResume, cancel: true, print3mf: false, gcode: true,
       };
     }
+    const streamCandidates = await this.cameraCandidates(target).catch(() => []);
+    capabilities.cameraStream = await cameraNativeAvailable() && streamCandidates.length > 0 &&
+      (capabilities.camera !== "none" || streamCandidates.some(candidate => candidate.configured));
     return compact({
       contract: COUNTERPART_CONTRACT,
       server: this.server,
@@ -141,11 +173,31 @@ export class CounterpartService {
     return "none";
   }
 
-  async filaments(target: PrinterTarget): Promise<{ slots: FilamentSlot[] }> {
-    const generic = this.generic(target);
-    if (!generic) {
-      throw new Error("Unsupported: Bambu AMS and external-spool inventory is read by bambu-printer-mcp's get_printer_filaments.");
+  /**
+   * bambu-printer-mcp's get_printer_filaments for Bambu: the live AMS inventory
+   * from MQTT. The first push from an idle printer can be sparse (model and
+   * modules); AMS data follows, so an empty live inventory is read once more.
+   */
+  async bambuFilaments(target: PrinterTarget, options: BambuFilamentOptions = {}): Promise<PrinterFilamentInventory & { slots: FilamentSlot[] }> {
+    const bambu = this.bambu(target);
+    const source = this.bambuProfileSource();
+    const read = async () => {
+      const status = await bambu.getStatus(target.host, target.port, target.apiKey);
+      if (status?.connected === false) throw new Error(`Could not read the printer's filament: ${status?.error ?? "not connected"}`);
+      return { status, inventory: normalizePrinterFilamentInventory(status, source, options.bambuModel, options.nozzleDiameter) };
+    };
+    let { status, inventory } = await read();
+    if (inventory.trays.length === 0) {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+      ({ status, inventory } = await read());
     }
+    const external = externalSpools(status, source, options.bambuModel, options.nozzleDiameter);
+    return { slots: counterpartSlots(inventory, external), ...inventory };
+  }
+
+  async filaments(target: PrinterTarget, options: BambuFilamentOptions = {}): Promise<{ slots: FilamentSlot[] }> {
+    const generic = this.generic(target);
+    if (!generic) return this.bambuFilaments(target, options);
     const slots = await generic.counterpartFilaments(target.host, target.port, target.apiKey);
     const profiled = await Promise.all(slots.map(async (slot) => {
       const profile = await this.filamentProfile?.(slot.material).catch(() => undefined);
@@ -154,15 +206,19 @@ export class CounterpartService {
     return compact({ slots: profiled });
   }
 
-  async pause(target: PrinterTarget) {
+  /** Bambu: over the route that printed (route), else LAN MQTT. */
+  async pause(target: PrinterTarget, route?: BambuControlRoute) {
     const generic = this.generic(target);
-    if (!generic) throw new Error("Unsupported: pause_print for Bambu printers is provided by bambu-printer-mcp.");
+    if (!generic) return this.bambu(target).pauseJob(target.host, target.port, target.apiKey, route?.("pause"));
     return generic.pauseJob(target.host, target.port, target.apiKey);
   }
 
-  async resume(target: PrinterTarget) {
+  async resume(target: PrinterTarget, route?: BambuControlRoute) {
     const generic = this.generic(target);
-    if (!generic) throw new Error("Unsupported: resume_print for Bambu printers is provided by bambu-printer-mcp.");
+    if (!generic) {
+      const dispatch = route?.("resume");
+      return this.bambu(target).resumeJob(target.host, target.port, target.apiKey, dispatch);
+    }
     return generic.resumeJob(target.host, target.port, target.apiKey);
   }
 
@@ -172,6 +228,14 @@ export class CounterpartService {
     if (options.savePath !== undefined && (!path.isAbsolute(options.savePath) || options.savePath.includes("\0"))) {
       throw new Error("Invalid save_path: expected an absolute file path.");
     }
+    const active = this.streams.get(this.cameraKey(target));
+    if (active && !active.stopped) {
+      const jpeg = await active.latest(Math.min(timeoutMs, 10000));
+      if (!jpeg) throw new Error("The active camera stream has not produced a frame.");
+      if (options.savePath) await fs.writeFile(options.savePath, jpeg);
+      return compact({status: "success", format: "image/jpeg", sizeBytes: jpeg.length, base64: jpeg.toString("base64"),
+        savedTo: options.savePath, capturedAt: new Date().toISOString(), source: active.transport}) as CameraSnapshotResult;
+    }
     const deadline = Date.now() + timeoutMs;
     const override = overrideSnapshotUrl();
     let candidates: SnapshotCandidate[];
@@ -207,6 +271,78 @@ export class CounterpartService {
     throw new Error(`No camera snapshot within ${timeoutMs} ms. Tried ${failures.length ? failures.join("; ") : "no URL before the deadline"}.`);
   }
 
+  private cameraKey(target: PrinterTarget): string {
+    return JSON.stringify([kindOf(target.type), target.host, target.port, target.type.toLowerCase() === "bambu" ? target.apiKey.split(":")[0] : ""]);
+  }
+
+  private async cameraCandidates(target: PrinterTarget): Promise<CameraCandidate[]> {
+    const override = overrideSnapshotUrl();
+    const candidates: CameraCandidate[] = override ? [{url: override, source: "env-override", configured: true, transport: "http-snapshot"}]
+      : await this.generic(target)?.cameraCandidates(target.host, target.port, target.apiKey) ?? [];
+    // Choose one configured camera; unsupported formats cannot select another camera.
+    const candidate = candidates[0];
+    if (!candidate) return [];
+    try {
+      let supportedURL = true;
+      try { this.resolve(candidate.url, target); } catch { supportedURL = false; }
+      if (!supportedURL || candidate.unsupportedStream || /\.m3u8(?:[?#]|$)/i.test(candidate.url)) {
+        if (!candidate.snapshotUrl) return [];
+        this.resolve(candidate.snapshotUrl, target);
+        return [{...candidate, url: candidate.snapshotUrl, transport: "http-snapshot"}];
+      }
+      this.resolve(candidate.url, target);
+      if (candidate.snapshotUrl) this.resolve(candidate.snapshotUrl, target);
+      return [candidate];
+    } catch { return []; }
+  }
+
+  async cameraStreamStart(target: PrinterTarget, options: {fps?: number; idleTimeoutMs?: number} = {}) {
+    const fps = cameraNumber(options.fps, 1, 0.2, 2, "fps");
+    const idleTimeoutMs = cameraNumber(options.idleTimeoutMs, 30000, 5000, 120000, "idle_timeout_ms", true);
+    const key = this.cameraKey(target), generation = this.generations.get(key) ?? 0;
+    if (!await cameraNativeAvailable()) return {status: "not-supported", reason: "runtime"};
+    if (this.closed || generation !== (this.generations.get(key) ?? 0)) throw new Error("Camera stream start was cancelled.");
+    const existing = this.streams.get(key);
+    if (existing && !existing.stopped) {
+      existing.touch(idleTimeoutMs);
+      return {status: "running", transport: existing.transport, fps: existing.fps, startedAt: existing.startedAt};
+    }
+    const candidates = await this.cameraCandidates(target);
+    if (this.closed || generation !== (this.generations.get(key) ?? 0)) throw new Error("Camera stream start was cancelled.");
+    if (!candidates.length) throw new Error("No camera is configured for this printer. Existing snapshot configuration is used for streaming.");
+    const candidate = candidates[0];
+    const urls = (raw: string) => this.resolve(raw, target).map(url => ({url, headers: this.cameraHeaders(url, target)}));
+    const plan = {urls: urls(candidate.url), snapshots: candidate.snapshotUrl ? urls(candidate.snapshotUrl) : undefined, mode: candidate.transport};
+    const {stream, status} = this.streams.start(key, {transport: "http", fps, idleTimeoutMs, skipFirstFrame: false,
+      open: handlers => openHttpCameraSource(this.http, plan, fps, handlers)});
+    return {status, transport: stream.transport, fps: stream.fps, startedAt: stream.startedAt};
+  }
+
+  async cameraStreamFrame(target: PrinterTarget, options: FrameOptions = {}) {
+    const sinceSeq = cameraNumber(options.sinceSeq, 0, 0, Number.MAX_SAFE_INTEGER, "since_seq", true);
+    const waitMs = cameraNumber(options.waitMs, 0, 0, 10000, "wait_ms", true);
+    const minChange = cameraNumber(options.minChange, 0.02, 0, 1, "min_change");
+    const maxWidth = options.maxWidth === undefined ? undefined : cameraNumber(options.maxWidth, 300, 1, 4096, "max_width", true);
+    const maxBytes = options.maxBytes === undefined ? undefined : cameraNumber(options.maxBytes, 42000, 4096, 5000000, "max_bytes", true);
+    if (options.changedOnly !== undefined && typeof options.changedOnly !== "boolean") throw new Error("changed_only must be a boolean");
+    return this.streams.get(this.cameraKey(target))?.frame({...options, sinceSeq, waitMs, minChange, maxWidth, maxBytes}) ?? {status: "stopped", seq: 0};
+  }
+
+  cameraStreamStop(target: PrinterTarget) {
+    const key = this.cameraKey(target);
+    this.generations.set(key, (this.generations.get(key) ?? 0) + 1);
+    this.streams.stop(key);
+    return {status: "stopped"};
+  }
+
+  close(): void { this.closed = true; this.streams.stopAll(); }
+
+  private cameraHeaders(url: string, target: PrinterTarget): Record<string, string> {
+    const host = target.host.includes(":") && !target.host.startsWith("[") ? `[${target.host}]` : target.host;
+    const sameOrigin = new URL(url).origin === new URL(`http://${host}:${target.port}`).origin;
+    return sameOrigin && target.apiKey && target.type.toLowerCase() !== "bambu" ? {"X-Api-Key": target.apiKey} : {};
+  }
+
   /**
    * Snapshot URLs are written from the printer host's point of view: relative
    * paths and loopback hosts mean the printer itself.
@@ -233,10 +369,8 @@ export class CounterpartService {
   }
 
   private async fetchJpeg(url: string, target: PrinterTarget, timeout: number): Promise<Buffer> {
-    const parsed = new URL(url);
     // The API key goes only to the printer's own API origin, never to another host.
-    const sameOrigin = parsed.origin === new URL(`http://${target.host}:${target.port}`).origin;
-    const headers: Record<string, string> = sameOrigin && target.apiKey && target.type.toLowerCase() !== "bambu" ? { "X-Api-Key": target.apiKey } : {};
+    const headers = this.cameraHeaders(url, target);
     const response = await this.http.get(url, {
       headers,
       responseType: "arraybuffer",

package/src/design-guidance.ts

@@ -0,0 +1,188 @@
+/**
+ * Manufacturing guidance for agents that design printable models: David Montgomery's FDM design
+ * prompt pack (3 November 2026), verbatim. Served as MCP prompts and a resource; the other printer
+ * MCP (bambu-printer-mcp / mcp-3D-printer-server) serves the same text. Clients choose when to
+ * attach each piece.
+ */
+
+export interface DesignPrompt { name: string; title: string; description: string; text: string }
+
+export const FDM_CORE = `Design the finished object the user wants, with the manufacturing plan as part of the design. Preserve its function, fit, and visual identity. Use your design ability freely to make that outcome practical through geometry, orientation, materials, color placement, supports, and assembly.
+
+Use the actual printer and material context: nozzle arrangement and filament routing, build volume, nozzle and line widths, layer profile, cooling, available filaments, and relevant successful prints or calibration. Missing information is unknown, not a capability the printer automatically has. Use reasonable, labeled assumptions for reversible choices; ask only when an unknown materially changes the result.
+
+Before committing to detailed geometry, choose a plausible way to manufacture and assemble it. For a consequential tradeoff, compare the strongest one-piece approach with a meaningfully different orientation or split. Simple parts do not need a design tournament. Judge total effort to obtain a good finished object: printing, consumed filament, likely rework, support cleanup, assembly, and extra hardware. Respect the user's priorities instead of applying fixed numerical weights.
+
+Keep assembled orientation and print orientation distinct. Preserve critical dimensions and mating surfaces. Account for measurement uncertainty and fit clearance separately; a scan or printed measuring tool does not establish its own accuracy. Use the smallest useful fit sample when uncertainty could otherwise waste a substantial print.
+
+Evaluate printability locally. Distinguish a progressively supported overhang, a bridge anchored at both ends, and a disconnected island. State overhang angles from vertical: 0 degrees is a vertical wall; 90 degrees is a horizontal underside. Convert conventions before setting slicer angles. Use relevant measured capability ahead of generic rules. A 45-degree threshold is not a universal support requirement, and a steep surface is not automatically unprintable. Judge bridge length along the actual unsupported extrusion path, with its anchors, cooling, material, and required underside quality. A feature that survives printing may still miss a cosmetic or dimensional requirement.
+
+Resolve a difficult region with the least disruptive effective change: a better orientation, local geometry, suitable process settings, accessible support, a deliberate breakaway feature, or a split. Supports are an ordinary manufacturing option. Preserve attractive curves and useful complexity when modest support or cleanup achieves them. Check support removal and tool access, especially inside cavities. Avoid changing the whole object to solve a local problem.
+
+Choose layer orientation, material, walls, and joints for the actual loads and environment. Check the load path, flexing features, fastener access, and installation sequence. A reduction in supports or color changes must not silently weaken the part or defeat its fit.
+
+On a shared-nozzle multicolor setup, reason about filament transitions across layers, including support-interface material. Total color count alone is a poor cost estimate. Consider color placement, shallow inlays, separately printed accents, and part orientation while preserving the requested appearance. Separate bodies on one layer-printed plate can still cause repeated swaps. Use the slicer's actual schedule and estimates when available; do not invent a fixed cost per color change.
+
+Use assembly when its benefit is worth the user's additional work. Design alignment, clearance, engagement, and assembly access deliberately. Glue is a valid planned joining method for suitable materials and loads; make joints self-locating and give them useful bonding area. Use mechanical retention when loads, repeated flexing, or serviceability call for it. State needed glue, hardware, tools, and assembly effort plainly. Avoid adding parts when a modest support or a simple one-piece print is the better result.
+
+Verify the chosen geometry in its actual print orientation and inspect the slice when tools permit. Check critical fits, missing or floating features, toolpaths, supports, color assignments, total time, and material consumption. Treat a slicer prediction as a prediction, not a physical test. Fix consequential problems and re-slice relevant changes. Stop when the design meets the brief and no remaining improvement justifies its cost.
+
+Keep the user-facing result short: the recommended design, why its manufacturing approach makes sense, how it prints and assembles, and any consequential unresolved assumption. Distinguish measured dimensions, slicer estimates, and untested predictions. Keep detailed analysis in the working process.`;
+
+export const FDM_MULTICOLOR = `Apply this guidance when multiple colors or support materials share a print.
+
+Preserve the requested visual pattern. Evaluate its colors in build coordinates and across layers before committing to color geometry. On a shared nozzle, a small accent spanning many layers can create more transitions than a large region confined to a few layers. Count the slicer's actual transitions when available, including swaps back to a prior filament and support-interface swaps; color count and colored volume are only screening clues. On printers with multiple nozzles, evaluate each shared melt path; AMS slots are not independent nozzles.
+
+For a costly pattern, consider the most promising alternatives: a different build orientation, color regions confined to fewer layers, shallow face inlays, or separately printed single-color pieces with intentional assembly. A vertical stripe in use may become a low-change feature in a different print orientation. Judge each option against load direction, surface quality, support burden, and the user's exact visual requirements. Finer layers can help an overhang while adding color-change layers; evaluate local adaptive layers and re-slice the combined plan.
+
+Separating color bodies does not by itself eliminate swaps. Check plate scheduling. Single-color plates can remove repeated color changes; by-layer printing of different-color objects together usually cannot. Use sequential object printing only when supported and its clearance constraints are satisfied. Batch copies only when the user wants them.
+
+Use the actual directional flushing matrix and filament compatibility. Purging clears previous material; priming restores consistent extrusion. Track those separately when the slicer does. Flushing into compatible infill or supports may reduce discarded material, but it does not remove switching time, has finite capacity, and can affect appearance or strength. Do not add unnecessary infill or objects merely to hide waste.
+
+Compare the same requested quantity and finish. Report total filament and time across all plates, plus purge, tower, and support quantities only where available without double counting. Unknown metrics remain unknown. Recommend the original multicolor approach when the user values its seamless result enough to justify its cost.`;
+
+export const FDM_ASSEMBLY = `Apply this guidance when a split, insert, or joint may materially improve the result.
+
+Compare assembly against the best practical one-piece approach, including reasonable supports. A split earns its place by improving important surfaces, layer strength, fit, color efficiency, support access, repairability, or bed fit enough to justify handling and joining the pieces. Prefer a one-piece solution when its support cleanup is easier than assembly and the alternatives meet the other important requirements comparably well. Respect an explicit one-piece or no-glue requirement.
+
+Put boundaries where they are structurally sensible and visually deliberate. Use shoulders, keys, overlapping faces, tabs, or pins to locate parts and resist sliding or rotation as appropriate. Include fit clearance, lead-ins, adhesive space where needed, and a feasible insertion path. Check the assembled geometry and the order of operations, not only the separated pieces. Avoid joints whose screws, clamps, or mating faces become inaccessible during assembly.
+
+For suitable lightly loaded rigid details, a locating pocket plus a compatible adhesive can be the simplest reliable solution. For a loaded clamp, a joint under peel or repeated bending, or a serviceable assembly, consider fasteners or mechanically captured geometry. Do not assume a tiny glued butt joint can carry the same load as an intact printed section. Select adhesive from evidence for the actual materials and conditions; superglue is an option, not a universal material property.
+
+State the practical consequence directly: which parts print in which orientations and colors, how they locate, how they are retained, which supplies are needed, and the estimated hands-on work. Keep hands-on time separate from adhesive cure time. Check a small joint sample only when its uncertain fit or strength would change the design decision.`;
+
+export const FDM_AFTER_SLICE = `Review this slice against the user's brief and the selected manufacturing plan. Use the returned slice, geometry, profile, and calibration evidence; do not assume missing metrics are zero.
+
+Check that the actual toolpaths preserve critical features, fit, connected material, intended colors, and load-bearing sections. Inspect consequential first layers, bridges, islands, supported undersides, and removal access. Compare expected total print time, total material across all plates, and manual work with the best credible alternative. Keep purge, prime-tower, support, and model quantities distinct only when the data provides a non-overlapping breakdown.
+
+If the plan is unexpectedly costly or fragile, identify the dominant cause and make the smallest change that preserves the brief. Re-slice after a relevant geometry, orientation, material, or process change. Do not optimize a minor imperfection at the expense of function or appearance, and do not invent a redesign simply to produce criticism.
+
+Return a concise decision: keep, revise, or validate one specific uncertainty. Include the decisive evidence and the exact next action. A clean slice supports a printability prediction; it does not verify physical fit, strength, or bridge quality.`;
+
+export const FDM_CAPABILITY_GUIDANCE = `# Bridges and overhangs: useful capability without arbitrary bans
+
+Load this reference only when the feature matters to the manufacturing decision. These are proposed planning bands, not manufacturer guarantees, support-generation settings, or automatic acceptance/rejection rules.
+
+## Scope and terminology
+
+The provisional baseline is an ordinary modern Bambu P-series-class FDM setup, a 0.4 mm nozzle, a suitable PLA profile, normal planar toolpaths, and effective part cooling. Actual printer/material/profile evidence takes priority. Do not transfer the same expectations unchanged to PETG, flexible materials, a different layer height, or a different cooling arrangement.
+
+Angles in the proposed review bands are measured **from vertical**: a vertical wall is 0 degrees; a horizontal underside is 90 degrees. Source values retain their stated or unresolved convention as noted. Slicer controls and test models can use a different convention. Establish their convention before comparing or entering a value. For a simple planar slope, the angle from the build plate is 90 degrees minus the angle from vertical.
+
+An overhang grows sideways from material below. A conventional bridge has extruded paths anchored at both ends. A disconnected island begins with no suitable underlying material or anchorage. They require different decisions.
+
+## What the retrieved evidence establishes
+
+- Prusa's current modeling documentation gives a general 45–60 degree range depending on nozzle/settings, and describes up to 75 degrees for its specifically named Nextruder/360-degree-cooling machines. That is evidence against a universal 45-degree limit. It does not certify 75 degrees on every Bambu printer. [C1]
+- A Fab Academy 2026 hands-on comparison of Bambu P2S and H2S used matte-white PLA and reported 50 mm unsupported bridge strands without a visible problem. It also reported some drooping above 60 degrees on the overhang test. This is a useful documented result on particular geometry, not a population benchmark or proof of flat mating-surface accuracy. [C2]
+- An MIT HTMAA 2025 P1S characterization reported no noticeable defects on its longest tested bridge, 20 mm, and explicitly left the actual maximum unmeasured. A largest passing sample is not the machine's limit. [C3]
+- Bambu's PETG Basic V3.0 data sheet lists approximately 30 mm maximum bridging length and approximately 70 degrees maximum overhang; its PLA Tough+ V3.0 sheet lists 30 mm and 55 degrees. These are material-specific reference values. The retrieved sheets do not define the overhang angle convention or a bridge sag/finish acceptance criterion, so keep the angle values as reported rather than silently normalizing them. Do not assume the mechanical-specimen print conditions also describe these feature tests. [C4, C5]
+
+The material sheets provide useful 30 mm reference points; the firsthand longer prints show why a published or configured maximum should not become a universal geometric prohibition. Filament formulation matters. Avoid a rule that all PLA must outperform all PETG.
+
+## Proposed review bands
+
+These bands decide how much attention to give a feature. They never force a flat design, a split, supports, or a calibration print by themselves.
+
+| Feature on the provisional PLA setup | Working stance |
+| --- | --- |
+| Progressively supported overhang around 45–60 degrees | Keep an unsupported version as an ordinary candidate. Inspect local curvature, overlap, cooling, and required finish. |
+| Overhang around 60–70 degrees | Retain the shape as a candidate; examine local layer height, geometry, cooling, and relevant prior results more closely. Modest support is also an ordinary option. |
+| Overhang around 70 degrees or more | Require a stronger process/geometry justification to rely on a clean unsupported result. Consider a representative sample when its result would decide between substantially different plans. |
+| Conventional bridge up to about 20 mm | Treat as a plausible ordinary candidate when anchors, toolpaths, and underside requirements are suitable. |
+| Bridge roughly 20–50 mm | Keep bridging as a real design option. Pay more attention to actual unsupported path length, anchorage, width, cooling, and sag acceptance. |
+| Bridge beyond about 50 mm | Keep it in the design space; seek relevant prior evidence or a small representative test before depending on its quality for an expensive or precise part. |
+
+The 60–70-degree and 20–50-mm bands are deliberate engineering priors for this app. They are not claims that a manufacturer has validated the whole interval. A 12 mm bridge can be unacceptable for a tight sliding surface; a much longer one may be adequate above a noncritical cavity. Avoid turning these bands into a hidden \`max_bridge\` or \`max_overhang\` rejection threshold.
+
+## A useful geometric check
+
+For an idealized straight overhang at angle alpha from vertical, layer height h produces a lateral step:
+
+\`step = h * tan(alpha)\`
+
+Using a nominal extrusion width w, a simple projected overlap estimate is:
+
+\`overlap_fraction = max(0, 1 - step / w)\`
+
+For a 60-degree overhang and a 0.45 mm line width:
+
+| Layer height | Lateral step | Nominal overlap |
+| --- | --- | --- |
+| 0.20 mm | 0.346 mm | About 23% |
+| 0.12 mm | 0.208 mm | About 54% |
+
+These values follow from geometry, not a printer test. The model omits bead shape, curved toolpaths, cooling, adhesion, and other effects. It explains why layer height can change the outlook; it cannot prove a print will succeed. Use the actual extrusion widths when known.
+
+Ordinary overhang-layer reasoning does not prescribe the best bridge extrusion. OrcaSlicer's documented thick-bridge mode uses a line height equal to nozzle diameter and trades a rougher surface for stronger, more reliable bridges and potentially longer spans. Inspect the actual selected mode instead of assuming bridge height equals ordinary layer height. [C6]
+
+Reducing layer height throughout a multicolor part can also increase the number of color-change layers. Prefer a local intervention when appropriate and re-slice the whole manufacturing plan to see the tradeoff.
+
+## Local interventions to consider
+
+Keep the intervention proportionate to the specific problem. Useful candidates include changing build orientation, adjusting only a hidden underside, replacing the top of a horizontal hole with a suitable printable roof while preserving its necessary clearance, using local adaptive layers, improving a bridge's anchors or extrusion direction, adding a small removable sacrificial feature, placing accessible support, or splitting at a sensible joint.
+
+Preserve roundness where a mating shaft genuinely needs it. Preserve curves where they matter visually. An unremovable support inside a duct is not a valid plan. Do not trade away layer bonding to improve cooling without considering the part's mechanical job.
+
+Treat the slicer's support-generation thresholds as policy settings, not measured capability. For example, OrcaSlicer's \`max_bridge_length\` decides which anchored spans tree supports leave unsupported. Its configured value does not establish what the machine can physically bridge. [C7]
+
+## What to learn from physical prints
+
+Record the feature and its conditions, not merely a global pass/fail label. Useful evidence includes:
+
+- Largest tested span or angle, plus known failures and untested regions.
+- Actual printer, filament identity, nozzle, layer/line profile, cooling, and build orientation.
+- Bridge direction, width, anchors, and nearby geometry.
+- Whether the criterion was survival, cosmetic quality, measured sag, fit, or load performance.
+
+A small combined coupon at onboarding can complement the printed measuring tool, but it should be optional. Later, print a targeted sample when an important unknown would otherwise put a much larger print at risk. Routine geometry should not repeatedly trigger calibration work.
+
+## Primary sources
+
+[C1] Prusa, Modeling with 3D printing in mind:
+
+https://help.prusa3d.com/article/modeling-with-3d-printing-in-mind_164135
+
+[C2] FabLab Nagoya, Fab Academy 2026 Week 05, firsthand P2S/H2S characterization:
+
+https://fabacademy.org/2026/labs/nagoya/assignments/week05/
+
+[C3] Ryan Hoffman, MIT HTMAA 2025, firsthand P1S characterization:
+
+https://fab.cba.mit.edu/classes/863.25/people/RyanHoffman/week3.html
+
+[C4] Bambu PETG Basic Technical Data Sheet V3.0:
+
+https://store.bblcdn.com/s1/default/cb94589bf7994fdcbfa833badefae9cd/Bambu_PETG_Basic_Technical_Data_Sheet.pdf
+
+[C5] Bambu PLA Tough+ Technical Data Sheet V3.0:
+
+https://store.bblcdn.com/s7/default/80a85371db2e40bda97069d283fed76c/BambuPLA_Tough_TechnicalData_Sheet_%282%29.pdf
+
+[C6] OrcaSlicer bridge settings:
+
+https://github.com/OrcaSlicer/OrcaSlicer/wiki/quality_settings_bridging
+
+[C7] OrcaSlicer advanced support settings:
+
+https://github.com/OrcaSlicer/OrcaSlicer/wiki/support_settings_advanced
+
+All sources inspected 3 November 2026.`;
+
+export const FDM_CAPABILITY_URI = "guidance://fdm/capability-guidance";
+
+export const FDM_CAPABILITY_RESOURCE = { uri: FDM_CAPABILITY_URI, name: "FDM bridge and overhang guidance", mimeType: "text/markdown",
+  description: "Planning bands and evidence for bridges and overhangs, for when one is consequential and there is no sufficiently specific measured capability available" };
+
+export const DESIGN_PROMPTS: DesignPrompt[] = [
+  { name: "fdm_design", title: "Design for FDM printing", text: FDM_CORE,
+    description: "Persistent instructions for every design or model-editing task: plan how the object prints as part of the design, using the actual printer, filaments and slice." },
+  { name: "fdm_multicolor", title: "Multicolour and support materials", text: FDM_MULTICOLOR,
+    description: "Add when several colours or support materials share a print: filament transitions, colour placement, plate scheduling and flushing." },
+  { name: "fdm_assembly", title: "Splits, inserts and joints", text: FDM_ASSEMBLY,
+    description: "Add when a split, accent insert or joint could materially improve the result." },
+  { name: "fdm_after_slice", title: "Review a slice", text: FDM_AFTER_SLICE,
+    description: "A separate review turn after a candidate has been sliced, before presenting the manufacturing recommendation: keep, revise, or validate one specific uncertainty." },
+];
+
+export const SERVER_INSTRUCTIONS = "When designing or editing a model to print, apply the fdm_design prompt. Add fdm_multicolor when several colours or support materials share a print, fdm_assembly when a split or joint could help, and fdm_after_slice as a separate review turn after a candidate has been sliced, before presenting the manufacturing recommendation. Read " + FDM_CAPABILITY_URI + " when a bridge or overhang is consequential and there is no sufficiently specific measured capability available.";

package/src/fulu-orca.ts

@@ -600,7 +600,7 @@ export async function invokeFuluBridgeRpc(options: FuluBridgeRpcOptions): Promis
   if (printMethod) {
     throw new Error(
       `Print safety: raw FULU bridge print method "${method}" is disabled because it would start an uninspected job ` +
-      "without the thermal, model, nozzle, printer-state and human-confirmation checks. Use print_3mf for a checked LAN print."
+      "without the thermal, model, nozzle and printer-state checks. Use print_3mf for a checked LAN print."
     );
   }
 
@@ -711,7 +711,7 @@ export async function inspectFuluOrcaSetup(options: FuluOrcaSetupOptions): Promi
     notes: [
       "Slicing support uses FULU OrcaSlicer-bambulab CLI output as a sliced 3MF.",
       "Bambu print start still enforces BAMBU_MODEL before generating or sending project G-code.",
-      "Raw bridge print methods are disabled; print_3mf inspects the exact plate, checks the live printer and asks for human confirmation.",
+      "Raw bridge print methods are disabled; print_3mf inspects the exact plate and checks the live printer.",
       "The FULU BambuNetwork bridge is a separate runtime from the LAN MQTT/FTPS path; use bridge probing to verify that runtime before relying on cloud behavior.",
       ...(platform === "darwin"
         ? ["FULU macOS release bundles may ship the bridge dylib and host shims before the Linux plugin .so payload is present; missing linux-plugin entries mean the slicer can still be tested, but the BambuNetwork bridge is not fully ready."]
@@ -722,3 +722,19 @@ export async function inspectFuluOrcaSetup(options: FuluOrcaSetupOptions): Promi
     ],
   };
 }
+
+/**
+ * The FULU BambuNetwork bridge command this machine's FULU install provides:
+ * FULU_BAMBU_BRIDGE_COMMAND, else the host discovered next to FULU's
+ * OrcaSlicer-bambulab (the same discovery check_fulu_orca_setup reports).
+ * print_3mf's bambu_network route and its controls fall back to it.
+ */
+export function discoveredFuluBridgeCommand(): string | undefined {
+  try {
+    const platform = normalizePlatform(undefined);
+    const slicerPath = resolveSlicerPath(undefined, platform);
+    return defaultBridgeCommand(platform, derivePluginDir(undefined, slicerPath, platform), defaultRuntimeDir(platform));
+  } catch {
+    return undefined;
+  }
+}