bambu-printer-mcp 1.1.94 → 1.1.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1133,8 +1133,9 @@ If the project does not match those assumptions, the tool fails fast with a stru
1133
1133
 
1134
1134
  [Counterpart](https://github.com/DMontgomery40/scan-to-make) (Scan to Make) reads printers through a small contract that this server and [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) share. Each tool declares an `outputSchema` and returns `structuredContent`, plus the same JSON as text for older clients. An error is returned as text only, because MCP clients check `structuredContent` against the schema even on errors. Other tools return an error's details in `structuredContent` (`status`, `retryable`, `suggestion`, `message`). When the printer refuses a print, the error also carries a stable `code`: `printer-command-rejected`, `printer-not-ready`, or `printer-upload-failed` when the file didn't reach the printer and no print command was sent, so a client can act on the code rather than the wording. A `print_3mf` call made with a progress token reports its LAN upload as MCP progress: `progress` is bytes sent, `total` the file's bytes, and `_meta["counterpart/stage"]` is `"upload"`, at most once per whole percent. `counterpart_printer_info` reports `capabilities.slicing` (`supports`, `copies`, `orient`), so a client can offer those choices without knowing the slicer. `counterpart_printer_info` and `counterpart_print_progress` take the usual optional `host`, `bambu_serial`, `bambu_token` and `bambu_model` (default `BAMBU_MODEL`) arguments.
1135
1135
 
1136
- - **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, displayName, serial, host}, capabilities}`. `displayName` is the model with its maker ("Bambu Lab P1S"), to show as given; it and `model` are absent when the model is unknown. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
1136
+ - **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, displayName, serial, host}, capabilities}`. `displayName` is the model with its maker ("Bambu Lab P1S"), to show as given; it and `model` are absent when the model is unknown. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `diagnostics: true` (this server has `counterpart_diagnostics`), `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
1137
1137
  - **`counterpart_self_check`** returns `{contract, server: {name, version}, ok, checks: [{name, ok, version?, message?}]}`: one check that the running server is its installed package's version, one per runtime dependency in `package.json` (it resolves from this install and loads, and the installed version meets an exact pin, `^` or `~` range), and `bambu-node patch`: every hunk of the bundled patch is in the installed bambu-node (a read-only reverse dry run, as postinstall checks), and it reads an H2D version report in memory as only the patched module can. Run it after an update; `ok` is false when any check fails. It sends nothing to the printer.
1138
+ - **`counterpart_diagnostics`** returns this server's own diagnostics for a bug report, `{package, version, files: [{name, content, truncated}], notes}`, for a client to add to its own export without knowing any log path. `files` are relative paths with UTF-8 text: `server.json` (package, version, Node.js, platform), `printers.json` (the configured printer's id, host, serial, model, connection route and whether an access code is set; firmware is not read), `settings.json` (this server's `BAMBU_*`, `SLICER_*`, `CAD_*` and similar settings), `slicer.json` (slicer type, path, profiles and the version its macOS bundle or AppImage name gives; the slicer is never run), `cad.json` (CAD runtime status), `tool-errors.log` (recent failed calls: tool and error, never arguments), `server-stderr.log` (this run's stderr, including MQTT and connection messages). The Bambu network plug-in and native helper logs are left out: other programs write them, and they can hold secrets this server cannot recognise. Optional `printer` (a serial or host) limits `printers.json` to that printer; optional `max_bytes` (default 4,194,304, at most 8,388,608) bounds the names, contents and notes together, keeping each file's newest lines. Redaction fails closed: the configured secrets and secret arguments go wherever they appear, also URL-encoded, JSON-escaped or base64; logged objects are redacted by key, and an object whose field names a secret loses its other values; settings show values only for known non-secret settings (any other only as `[set]`); and any log line that names a secret, in any spelling or encoding, is withheld whole as `[line withheld: may contain a secret]` with the lines that continue it, keeping its time and level. Serial numbers, error codes, firmware versions and whether a secret is set stay. A secret this server never held, on a line that names no secret, is the one thing it cannot recognise. A missing log is a note, never an error. It sends nothing to the printer.
1138
1139
  - **`package.json` `counterpart`**: `{contract: "counterpart/1", notes, autoUpdate}`, readable with `npm view bambu-printer-mcp counterpart` before a client downloads a version. `notes` is one sentence about that release; `autoUpdate: false` asks clients not to install it automatically.
1139
1140
  - **`counterpart_print_route`** reads or changes how prints and Stop/Pause/Resume reach the printer: `{route, mode, type, choices, savedTo}`, where `route` is `lan` (the local network, in the configured `BAMBU_DEFAULT_CONNECTION_MODE`) or `cloud` (Bambu Cloud through the [FULU bridge](docs/FULU.md)). Pass `route` to change it; the next print and control use it at once, and it is written to the `.env` in the server's working directory when one exists (`savedTo`, otherwise `null`). It is not part of the shared contract: it has no `outputSchema`, and mcp-3D-printer-server has no Bambu Cloud route.
1140
1141
  - **`counterpart_print_progress`** returns `{contract, observedAt, state, job?, temps?, activeFilament?, problems}` from the printer's MQTT reports, which this server keeps while it is connected. A held session is answered from that cache without any printer traffic, and `observedAt` is when the printer sent the report. The server asks the printer for a full report only to fill an empty cache, and at most once every five minutes after the printer has been quiet that long. A printer that sends no report within 8 seconds is `offline`.
@@ -1329,7 +1330,7 @@ For a multi-colour result, `build()` returns `project_3mf()`: a new project of n
1329
1330
 
1330
1331
  `cad_status` and `cad_setup` expose `storage.expected_download_bytes`, `expected_installed_bytes` and cached measured `installed_bytes`; the first two are fresh-install budget estimates, not remaining transfer sizes. Setup failures carry `structuredContent.code`, `message`, `suggestion` and `retryable`, so clients do not parse wording.
1331
1332
 
1332
- Runs wait for the environment's execution slot up to their own total timeout and return `queue_wait_ms`. Mark the selected result with `final: true`: each run's script-protected `cad-result.json` keeps the flag, full validation and artifact paths for recovery after restart. Check `status`, `valid` and the checks as well as `final`.
1333
+ Runs wait for the environment's execution slot up to their own total timeout and return `queue_wait_ms`. Mark the selected result with `final: true`: each run's script-protected `cad-result.json` keeps the flag, full validation and artifact paths for recovery after restart. Check `status`, `valid` and the checks as well as `final`. A solid design also declares `PURPOSE` (what it is for, what it holds, what carries the load, where its user is) and `use()` (itself as used, with the held object and the surface it meets); the run returns `purpose`, with each requirement evaluated on that assembly and the loads at each mount computed from it, and `ready`. `final: true` is recorded only when the design is ready; otherwise `final_refused` says why. Mesh mode and 3MF projects keep the earlier rule. Pass `role: "check"` for a fit-check part or reference export: every receipt records `role` (`"design"` when absent), a check run is never final, and every valid run that is not final carries `draft_reasons` saying why. See [docs/CAD.md](docs/CAD.md#purpose-and-the-design-as-used).
1333
1334
 
1334
1335
  Unchanged declared inputs reuse immutable content-hash bundles, with `snapshot_bytes_added` and `snapshot_bytes_reused` in the result. Keep the referenced `.cad-inputs` bundles with saved designs. Previews now use depth cues and feature edges to reveal windows and recesses without a heavy renderer.
1335
1336
 
@@ -23,6 +23,7 @@ export declare const CAD_TOOLS: ({
23
23
  parameters?: undefined;
24
24
  output_dir?: undefined;
25
25
  name?: undefined;
26
+ role?: undefined;
26
27
  final?: undefined;
27
28
  timeout_ms?: undefined;
28
29
  model?: undefined;
@@ -106,6 +107,7 @@ export declare const CAD_TOOLS: ({
106
107
  parameters?: undefined;
107
108
  output_dir?: undefined;
108
109
  name?: undefined;
110
+ role?: undefined;
109
111
  final?: undefined;
110
112
  timeout_ms?: undefined;
111
113
  model?: undefined;
@@ -224,6 +226,12 @@ export declare const CAD_TOOLS: ({
224
226
  maxLength: number;
225
227
  description: string;
226
228
  };
229
+ role: {
230
+ type: string;
231
+ enum: string[];
232
+ default: string;
233
+ description: string;
234
+ };
227
235
  final: {
228
236
  type: string;
229
237
  default: boolean;
@@ -317,6 +325,7 @@ export declare const CAD_TOOLS: ({
317
325
  script_path?: undefined;
318
326
  parameters?: undefined;
319
327
  output_dir?: undefined;
328
+ role?: undefined;
320
329
  final?: undefined;
321
330
  timeout_ms?: undefined;
322
331
  model?: undefined;
@@ -439,6 +448,7 @@ export declare const CAD_TOOLS: ({
439
448
  parameters?: undefined;
440
449
  output_dir?: undefined;
441
450
  name?: undefined;
451
+ role?: undefined;
442
452
  final?: undefined;
443
453
  };
444
454
  required: string[];
@@ -103,7 +103,7 @@ export const CAD_TOOLS = [
103
103
  },
104
104
  {
105
105
  name: "cad_run",
106
- description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six orthographic renders, a perspective view and a contact sheet (with next: read the perspective view before the next change), the closest approach between every pair of solids (bodies), problems, what was checked and not checked, and printed: whatever the script wrote with print(), capped at 4000 characters, so a design can report a number it computed; valid means only that the exported geometry is sound, never that the part fits, holds, moves or prints.",
106
+ description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six orthographic renders, a perspective view and a contact sheet (with next: read the perspective view before the next change), the closest approach between every pair of solids (bodies), problems, what was checked and not checked, printed: whatever the script wrote with print(), capped at 4000 characters, so a design can report a number it computed, and, in solid mode, purpose and ready: the script's PURPOSE compiled into requirements and evaluated on its use() assembly (held objects, mounts, loads computed from the geometry, facing the user). valid means only that the exported geometry is sound; final: true is recorded only when the design is ready (final_refused says why not).",
107
107
  inputSchema: {
108
108
  type: "object",
109
109
  properties: {
@@ -147,6 +147,12 @@ export const CAD_TOOLS = [
147
147
  maxLength: 64,
148
148
  description: "Plain file stem for STL, STEP, Python and parameter artifacts.",
149
149
  },
150
+ role: {
151
+ type: "string",
152
+ enum: ["design", "check"],
153
+ default: "design",
154
+ description: 'What this run is: "design" (the default) for the design itself, or "check" for a fit check part, a reference export or any other run that must never become the model. A check run is never selected as final, evaluates no PURPOSE, and its receipt says role: "check".',
155
+ },
150
156
  final: {
151
157
  type: "boolean",
152
158
  default: false,
@@ -209,6 +215,30 @@ export const CAD_TOOLS = [
209
215
  type: "string",
210
216
  description: "The script's own print() output from this run, capped at 4000 characters (build.log keeps the rest). The script's words, not a measurement by the engine.",
211
217
  },
218
+ ready: {
219
+ type: "boolean",
220
+ description: "Solid mode: the design's PURPOSE is declared and every requirement it compiles to passed on use(). final: true is recorded only when ready. Absent for mesh mode and 3MF projects.",
221
+ },
222
+ purpose: {
223
+ type: "object",
224
+ description: "Solid mode: what PURPOSE says the part is for (for, modelled_on), the product classes its words put it in, each requirement compiled from it with status pass, fail or not_modelled and what it says (held objects sit on the part, each mount touches its world surface, the exposed face of a held screen turns to the user's eye, tape stress and resting stability under the computed loads), the loads at the mounts (gravity, jolts, a hand's press), and blocked: what keeps it from ready.",
225
+ },
226
+ final_requested: { type: "boolean" },
227
+ role: {
228
+ type: "string",
229
+ enum: ["design", "check"],
230
+ description: 'The run\'s role as cad_run was given it: "design", or "check" for a check part or reference export that is never the model. Every receipt carries it.',
231
+ },
232
+ draft_reasons: {
233
+ type: "array",
234
+ items: { type: "string" },
235
+ description: "On every valid run that is not final: why not, in plain sentences (the designer did not mark it final; it is not ready, then what blocks it; or it is a check part, not the design). A client that keeps such a run as a draft shows these.",
236
+ },
237
+ final_refused: {
238
+ type: "array",
239
+ items: { type: "string" },
240
+ description: "Why final: true was not recorded, each as the step that fixes it (for example: model the dash as world:dash in use() so the tape mount can be checked). next quotes the first ones; the run is not the model until a run with final: true is ready.",
241
+ },
212
242
  three_mf: {
213
243
  type: "string",
214
244
  description: "When build() returned project_3mf(): the written 3MF project, ready for slice_stl.",
@@ -347,6 +377,7 @@ export const CAD_DESIGN_PROMPT = {
347
377
  description: "MCP-owned rules for headless build123d designs and one-call parameter revisions.",
348
378
  text: `Use code-CAD for dimensioned functional designs and parameter edits. Build in millimetres with build123d 0.13.0; the MCP owns the Python environment, execution, export, validation and rendering. Check cad_status and use cad_setup with install: true when needed. No Blender, Fusion, network or printer access is available to your script.
349
379
  A new design starts from the product, in this order. First, name two or three products a person would buy for this request (search when you are not sure what is sold) and say which one the design follows. Second, choose from the cookbook by purpose: the list below says what each example is for (cad_examples with no name returns it with each one's pattern and product). Read the example whose use is nearest the request, with cad_examples and its name, before deciding anything else, and adapt its form and pattern, never its sizes. Third, and only then, choose the mechanism (a clamp, screw, spring, hinge or snap) and read a second example for it if you need one. A mechanism chosen before the product gives a bracket with the mechanism bolted on.
380
+ Then state the purpose as data, before any geometry: a literal PURPOSE = {...} beside P (cad_run reads it from the source; parameters cannot change it). "for": what it is for in the person's words (who uses it, where, doing what); "modelled_on": the bought product; "holds": [{"body": name, "mass_g": grams}] for what it carries; "mounts": [{"body": name, "by": "tape", "rests", "screw", "clamp", "hook" or "other"}] for each surface that takes the load; "user": [x, y, z], the eye of the person who uses it, in mm in the use() frame, when it shows them something; optional "jolt_g", "press_n", "reach_mm", "material" and "faces": {"body": name, "within_deg": 25}. Its words add requirements whatever you list: a holder, hook, stand, dock, mount, rack, bracket, cradle or organizer must name what it holds and what it mounts to; anything in a vehicle takes jolts of at least 1.5 g in every direction; a phone, tablet or screen it holds must face the user's eye within 25 degrees. Then define use() beside build(): return Compound(children=[...]) of the part as it is used, Z up and gravity along -Z, with each held object at its real size and pose labelled "held:<body>" and each surface it meets as a solid slab where it really is (a dash face at its real angle, a desk's underside, a wall) labelled "world:<body>", all touching the part where they really touch. cad_run computes the loads at each mount from that geometry (gravity on the part and what it holds, the jolts, a hand pressing the held object), checks tape against 3M VHB's published stresses and that a resting part neither tips, lifts nor slides, checks that a held screen faces the user, draws renders.use (from the user's eye when given) and reports it all in purpose. final: true is recorded only when ready is true; until then the result lists final_refused. A run that is not the design itself (a part exported only for cad_check_fit, a reference, a diagnostic) is a check: pass role: "check" to every cad_run that is not the design itself, so it is never mistaken for the model (it is never final and evaluates no PURPOSE). Every valid run that is not final carries draft_reasons, saying why. When a requirement fails, change the design the way the bought products solve it (a joint that aims it, a broader pad, a wider or heavier base), never the purpose.
350
381
  The cookbook, by what each example is for:
351
382
  ${cadExampleLines()}
352
383
  Form first: build the product's shape, not a profile pushed up. Before any geometry, write the concept as the script's opening docstring, the way every cookbook example does: what it is, then "Modelled on:" the bought product you named, its mechanism, the load path, the print orientation and why. A script whose header names no product was designed from the mechanism. build123d has loft (through sections of different shape), sweep (a section along a path or a Helix), revolve, fillet, chamfer, offset and shell as well as extrude; use the one the product's surface calls for: lofted where a hand closes round it, revolved where it turns, swept where it runs like a bent rod or a thread, filleted where two surfaces meet under load. Extrude a flat profile only for something that really is a plate or a lever, or for a print-in-place mechanism or spring that must lie in the layers, and say that reason in the result. Choose the print orientation after the form: split a part, turn it or accept a modest support before flattening its design.
@@ -368,6 +368,7 @@ export class CadEngine {
368
368
  "geometry.py",
369
369
  "scan_touchup.py",
370
370
  "project3mf.py",
371
+ "purpose.py",
371
372
  "process.ts",
372
373
  "storage.ts",
373
374
  "serial.ts",
@@ -436,12 +437,18 @@ export class CadEngine {
436
437
  "inputs",
437
438
  "mode",
438
439
  "final",
440
+ "role",
439
441
  ]);
440
442
  const root = await this.allowedDirectory(args.output_dir);
441
443
  const name = plainName(args.name);
442
444
  const timeout = milliseconds(args.timeout_ms), deadline = started + timeout;
443
445
  if (args.final !== undefined && typeof args.final !== "boolean")
444
446
  throw new Error("final must be a boolean.");
447
+ // What the run is for, on every receipt: the design itself, or a check part or reference export that must
448
+ // never become the person's model (scan-to-make #790 keeps the last valid run as a draft). Absent is design.
449
+ if (args.role !== undefined && args.role !== "design" && args.role !== "check")
450
+ throw new Error('role must be "design" or "check".');
451
+ const role = args.role === "check" ? "check" : "design";
445
452
  if (root.split(path.sep).includes(".cad-inputs"))
446
453
  throw new Error("output_dir cannot be inside the reserved CAD input cache.");
447
454
  const remaining = () => {
@@ -532,9 +539,12 @@ export class CadEngine {
532
539
  }
533
540
  }
534
541
  await fs.writeFile(parameters, JSON.stringify({ ...previous, ...overrides }), { mode: 0o600 });
542
+ // Not final until the engine has found it ready: an interrupted run never reads as selected.
535
543
  await atomicJson(resultManifest, {
536
544
  status: "pending",
537
- final: args.final === true,
545
+ final: false,
546
+ ...(args.final === true ? { final_requested: true } : {}),
547
+ role,
538
548
  lineage_id: lineage,
539
549
  });
540
550
  try {
@@ -554,6 +564,7 @@ export class CadEngine {
554
564
  script,
555
565
  parameters,
556
566
  mode,
567
+ role,
557
568
  inputs: snapshots,
558
569
  };
559
570
  await fs.writeFile(request, JSON.stringify(base), { mode: 0o600 });
@@ -592,15 +603,40 @@ export class CadEngine {
592
603
  const checked = JSON.parse((await this.confined("inspect", request, job, protectedFiles, remaining(), signal, readableInputs)).stdout);
593
604
  const printed = built.stdout.trim();
594
605
  const project = await this.project3mf(job, name, snapshots);
606
+ // final is the designer's selection, and it no longer stands on its own word (scan-to-make #608): a solid
607
+ // design is selected only when the engine found it ready, its purpose evaluated on the design as used.
608
+ const blocked = Array.isArray(checked.purpose?.blocked) ? checked.purpose.blocked : [];
609
+ const refused = args.final === true && role === "check"
610
+ ? ['A check run is never the design: run the design itself with role "design" to mark it final.']
611
+ : args.final === true && checked.ready === false
612
+ ? (Array.isArray(checked.purpose?.blocked) && checked.purpose.blocked.length ? checked.purpose.blocked : ["the engine did not find this design ready"])
613
+ : undefined;
595
614
  const result = {
596
615
  ...checked,
597
616
  ...project,
598
617
  // Beside the image paths, where the next step is decided.
599
- next: "Read renders.perspective before the next cad_run or any other change: say what it shows is wrong against what you are making (the bought product you named, or the object in the photos), then fix that.",
618
+ next: refused
619
+ ? `Not selected as final, so it is not yet the model. To make it final: ${refused.slice(0, 3).join(" ")}${refused.length > 3 ? ` (and ${refused.length - 3} more in final_refused)` : ""} Then run again with final: true. Read renders.perspective and renders.use first.`
620
+ : "Read renders.perspective before the next cad_run or any other change: say what it shows is wrong against what you are making (the bought product you named, or the object in the photos), then fix that." +
621
+ (checked.purpose && checked.ready === false && Array.isArray(checked.purpose.blocked)
622
+ ? ` Not ready yet, so final: true would be refused. To make it ready: ${checked.purpose.blocked.slice(0, 3).join(" ")}`
623
+ : ""),
600
624
  // The script's own print() output: its words, not a measurement by this engine.
601
625
  ...(printed ? { printed: printed.length > 4000 ? printed.slice(0, 4000) + "\n[cut at 4000 characters; build.log has the rest]" : printed } : {}),
602
626
  status: "completed",
603
- final: args.final === true,
627
+ final: args.final === true && !refused,
628
+ ...(refused ? { final_requested: true, final_refused: refused } : {}),
629
+ role,
630
+ // Why a valid run is not the final model, in plain sentences, for a client that keeps it as a draft.
631
+ ...(checked.valid === true && !(args.final === true && !refused)
632
+ ? {
633
+ draft_reasons: role === "check"
634
+ ? ["This is a check part or reference export, not the design."]
635
+ : args.final === true
636
+ ? ["It isn't ready, so the engine didn't mark it final.", ...refused]
637
+ : ["The designer didn't mark this run final.", ...(checked.ready === false ? blocked : [])],
638
+ }
639
+ : {}),
604
640
  completed_at: new Date().toISOString(),
605
641
  lineage_id: lineage,
606
642
  result_manifest: resultManifest,
@@ -629,6 +665,7 @@ export class CadEngine {
629
665
  status: "failed",
630
666
  final: false,
631
667
  final_requested: args.final === true,
668
+ role,
632
669
  lineage_id: lineage,
633
670
  message: e instanceof Error ? e.message : String(e),
634
671
  script,
@@ -0,0 +1,163 @@
1
+ export declare const DIAGNOSTICS_DEFAULT_BYTES = 4194304;
2
+ export declare const DIAGNOSTICS_MAX_BYTES = 8388608;
3
+ export type DiagnosticsFile = {
4
+ name: string;
5
+ content: string;
6
+ truncated: boolean;
7
+ };
8
+ export type DiagnosticsResult = {
9
+ package: string;
10
+ version: string;
11
+ files: DiagnosticsFile[];
12
+ notes: string[];
13
+ };
14
+ /** A file on disk, whose tail goes in, or text the server composes. `missing` is the note when the file is absent. */
15
+ export type DiagnosticsSource = {
16
+ name: string;
17
+ file: string;
18
+ missing?: string;
19
+ } | {
20
+ name: string;
21
+ text: string;
22
+ };
23
+ export declare const DIAGNOSTICS_INPUT_PROPERTIES: {
24
+ printer: {
25
+ type: string;
26
+ description: string;
27
+ };
28
+ max_bytes: {
29
+ type: string;
30
+ minimum: number;
31
+ maximum: number;
32
+ description: string;
33
+ };
34
+ };
35
+ export declare const DIAGNOSTICS_OUTPUT_SCHEMA: {
36
+ type: "object";
37
+ properties: {
38
+ package: {
39
+ type: string;
40
+ description: string;
41
+ };
42
+ version: {
43
+ type: string;
44
+ description: string;
45
+ };
46
+ files: {
47
+ type: string;
48
+ items: {
49
+ type: string;
50
+ properties: {
51
+ name: {
52
+ type: string;
53
+ description: string;
54
+ };
55
+ content: {
56
+ type: string;
57
+ description: string;
58
+ };
59
+ truncated: {
60
+ type: string;
61
+ description: string;
62
+ };
63
+ };
64
+ required: string[];
65
+ };
66
+ };
67
+ notes: {
68
+ type: string;
69
+ items: {
70
+ type: string;
71
+ };
72
+ description: string;
73
+ };
74
+ };
75
+ required: string[];
76
+ };
77
+ /** The max_bytes a call asks for, checked. */
78
+ export declare function diagnosticsBudget(value: unknown): number;
79
+ /**
80
+ * Keeps what this server writes through console.error and console.warn (its stderr diagnostics: MQTT, connection,
81
+ * bridge and slicer messages) in memory as well. Writing to stderr is unchanged. Idempotent.
82
+ */
83
+ export declare function captureServerLog(): void;
84
+ /** Records a failed tool call: its name and error, not its arguments. */
85
+ export declare function recordToolError(tool: string, error: unknown): void;
86
+ /** Remembers the values of a tool call's secret-named arguments (access codes, API keys, tokens) for redaction. */
87
+ export declare function rememberSecretArguments(args: unknown): void;
88
+ export declare const serverLogText: () => string;
89
+ export declare const toolErrorsText: () => string;
90
+ /** For tests: forgets what was recorded. */
91
+ export declare function resetDiagnosticsMemory(): void;
92
+ /** Text with \\uXXXX, \\xXX and %XX escapes read, so "\\x70assword" and "pass%77ord" are seen as "password". */
93
+ export declare function decodeEscapes(text: string): string;
94
+ export declare function isSecretName(name: string): boolean;
95
+ /** The values of this environment's secret-named variables. */
96
+ export declare function environmentSecrets(env?: NodeJS.ProcessEnv): string[];
97
+ /** text with every known secret (configured, in this environment, or seen in tool arguments) removed in each encoded form. */
98
+ export declare function removeKnownSecrets(text: string, secrets?: Iterable<string>): string;
99
+ export declare const WITHHELD = "[line withheld: may contain a secret]";
100
+ /** The canonical phrases of REASONS, in order: all a withheld marker may name. */
101
+ export declare const WITHHELD_REASONS: string[];
102
+ /** The withheld marker for these lines: WITHHELD, naming the REASONS they mention ("claude auth login" over "auth login"). */
103
+ export declare function withheldMarker(lines: string): string;
104
+ /** Whether a line may carry a secret: a secret word anywhere in it, in any spelling or encoding. */
105
+ export declare function suspectLine(line: string): boolean;
106
+ /**
107
+ * Free text with each suspect line withheld whole, with the lines that continue it; its time and level stay. A suspect
108
+ * line that is only a name and a safe value stays, but what continues it is withheld all the same.
109
+ */
110
+ export declare function withholdSuspectLines(text: string): string;
111
+ /**
112
+ * text with every secret this module can recognise replaced, failing closed: known secret values in every encoded
113
+ * form; then the named patterns (values of secret-named keys, cookies, authorization headers, URL credentials,
114
+ * emails, JWTs, bare tokens, PEM blocks, other people's home folders); then every line that still names a secret
115
+ * withheld whole. Serial numbers, hosts, error codes and lowercase hashes stay.
116
+ */
117
+ export declare function redactText(text: string, secrets?: Iterable<string>): string;
118
+ /** The pattern rules alone (redactText without withholding lines): what each named form becomes. */
119
+ export declare function redactPatterns(text: string, secrets?: Iterable<string>): string;
120
+ /**
121
+ * A logged or composed value with its secrets removed, by its structure: a secret-named key's value goes (a bare
122
+ * measure such as tokenCount stays); an object where any field names a secret ({"name":"BAMBU_ACCESS_CODE", …})
123
+ * loses its other scalars; a string holding JSON is read and walked; any other string is redacted as text, one
124
+ * value per line, so a string that names a secret is withheld.
125
+ */
126
+ export declare function redactValue(value: unknown, secrets?: Iterable<string>, depth?: number): unknown;
127
+ /** A JSON file's text with its values redacted by structure (it stays valid JSON); other text as free text. */
128
+ export declare function redactJsonText(text: string, secrets?: Iterable<string>): string;
129
+ /** The last `bytes` of text, starting at a whole line where one starts inside it. */
130
+ export declare function tailText(text: string, bytes: number): {
131
+ text: string;
132
+ cut: boolean;
133
+ };
134
+ /**
135
+ * The bundle from sources, in their order: each file's tail, redacted. Small sources go in whole; the rest share what
136
+ * is left equally, keeping their newest lines. Names, contents and notes together stay within maxBytes.
137
+ */
138
+ export declare function buildDiagnostics(options: {
139
+ package: string;
140
+ version: string;
141
+ sources: DiagnosticsSource[];
142
+ notes?: string[];
143
+ fixedNotes?: string[];
144
+ maxBytes?: number;
145
+ secrets?: string[];
146
+ }): DiagnosticsResult;
147
+ /**
148
+ * Settings whose values are known not to be secret (paths, hosts, ports, modes, models, timeouts). Any other setting
149
+ * shows only whether it is set: commands and their arguments, URLs and anything else can carry a credential.
150
+ */
151
+ export declare const SAFE_SETTINGS: Set<string>;
152
+ /** The environment settings whose names match, sorted: a known non-secret one with its value, any other only "[set]" (or ""). */
153
+ export declare function settingsSnapshot(names: RegExp, env?: NodeJS.ProcessEnv): Record<string, string>;
154
+ /** The text of a JSON value for a bundle file. */
155
+ export declare const jsonText: (value: unknown) => string;
156
+ /** The newest `count` *.log files directly in each folder, newest first; absent folders are skipped. */
157
+ export declare function newestLogs(folders: string[], count: number, exclude?: string[]): string[];
158
+ /**
159
+ * The version of the app an executable belongs to, read without running it: a macOS bundle's Info.plist
160
+ * (CFBundleShortVersionString, else CFBundleVersion), else a version in the file's own name (AppImage). Undefined
161
+ * when neither says.
162
+ */
163
+ export declare function appVersion(executable: string | undefined): string | undefined;