Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,11 @@ BAMBU_X1C_01_SERIAL=replace-me
# When it is set, the edge's injected X-Auth-User becomes the recorded submitter
# instead of a typed-in label. Leave it unset and no identity is ever trusted.
#BAMBU_EDGE_SHARED_SECRET=
#BAMBU_A1_01_HOST=192.0.2.11
#BAMBU_A1_01_ACCESS_CODE=replace-me
#BAMBU_A1_01_SERIAL=replace-me

# Optional ELN filing through the central dashboard's ingest (never the ELN
# directly). Leave unset and every job's record stays local_only.
#BAMBU_RESULTS_URL=https://<dashboard>/api/ingest/print-results
#BAMBU_RESULTS_TOKEN=
14 changes: 11 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,19 @@ claim, one shared read per printer every 2 s, off on the page until a person
turns it on, never plate-check evidence) was approved, and with it the manual
snapshot step was dropped: a camera start records its own frame under the
claim when the person presses start. Homing was considered and
deliberately not added: it moves the bed into whatever is on the plate. All printer commands go through `bambu_server.dispatch` and
deliberately not added: it moves the bed into whatever is on the plate. On
2026-11-02 Yang approved (relayed in PR #8) **agent mode for the Bambu A1
only**: an admin-controlled, audited switch, off by default, that lets an agent
submit, approve and start jobs on `bambu_a1_01`, deciding itself from a claimed
camera snapshot that the plate is empty (`agent_camera`). Every other printer,
and the A1 with the switch off, keeps the human-in-the-loop rules unchanged; see
`AGENT_RULES.md` rule 4. The same day, robot calibration was ruled out of scope:
the gateway reports object positions in bed millimetres and the arm agent owns
the transform. All printer commands go through `bambu_server.dispatch` and
the backend's control methods; nothing else may call `bambulabs_api` command
methods. Adding a verb, relaxing a gate, or letting an agent start a print
without a person needs a new explicitly approved design. Routing control
through `lab-skills` is still owed.
without a person anywhere beyond that A1 approval needs a new explicitly
approved design. Routing control through `lab-skills` is still owed.

## Working conventions

Expand Down
12 changes: 12 additions & 0 deletions AGENT_RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,18 @@ the Bambu printer gateway.
frame under the claim when they press start, refusing if it cannot.) An agent must never set `plate_confirmed_empty`, start a print, or
approve a job on its own initiative, and must never retry a failed or
uncertain dispatch -- a person checks the printer first.
**One exception, approved by Yang on 2026-11-02 (relayed in PR #8):** on the
Bambu A1 (`bambu_a1_01`, the only model config accepts
`agent_mode_eligible` on), while an edge-verified admin has switched its
agent mode on, an agent may submit, approve and start jobs and may itself
decide the plate is empty from a camera snapshot it took under its claim
(`plate_check_method: agent_camera`, frame at most
`dispatch.agent_snapshot_max_age_s` old, deciding agent and rationale
recorded, frame archived with its SHA-256). The switch is off by default,
only an admin can flip it, and every flip is audited. Nothing else changes:
on every other printer, and on the A1 with the switch off, the rule above
holds in full, and no agent ever retries a failed or uncertain dispatch.
Widening this to another printer needs a new approval.
5. Printer access codes, serial numbers, addresses, and raw MQTT payloads are
local secrets and must not be committed, returned by HTTP, or logged.
6. Tests and development defaults must not contact lab hardware.
272 changes: 239 additions & 33 deletions README.md

Large diffs are not rendered by default.

91 changes: 88 additions & 3 deletions docs/API_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,99 @@ Per printer, under `/printers/{id}/control/`: `claim`, `heartbeat`, `release`
`start_print`, `stop_print`, each requiring
`X-Claim-Token` (423 without it). `start_print` takes the approved
`submission_id`, `plate_confirmed_empty: true`, `plate_check_method`
(`printer_camera` with a `snapshot_token`, or `in_person`), and an
`ams_mapping` of `{filament_id, ams_id, tray_id}`. Refusals are 412 with a body
naming the failed gate; `allowed_actions` on `/status` mirrors them, and
(`printer_camera` with a `snapshot_token`, `in_person`, or — for an agent on a
printer in agent mode — `agent_camera`), and an `ams_mapping` of
`{filament_id, ams_id, tray_id}`. Refusals are 412 with a body naming the
failed gate; `allowed_actions` on `/status` mirrors them, and
`details.claimed_by` names the holder. `GET /submissions/{id}/plate.jpg` returns
the camera frame a start was confirmed against. Without dispatch enabled none
of these paths exist.

**Camera snapshot for a plate check.** `POST /printers/{id}/control/snapshot`
with the claim token returns `{token, printer_id, captured_at, sha256,
content_type: "image/jpeg", image_base64}`. The token is valid for that printer
and that claim session only. A person's camera start accepts it for 5 minutes;
an agent's `agent_camera` start for `dispatch.agent_snapshot_max_age_s` (120 s
by default). H2D snapshots are not supported yet: the route answers 501 without
contacting the printer, so an H2D plate check is in person.

The gateway trusts edge identity only with its configured shared edge secret.
Names supplied directly by clients are unverified labels. Dashboard links use
the authenticated edge; this does not turn the gateway's direct port into an
authenticated surface. Never send secrets or printer addresses in submissions.

## Agent mode (Bambu A1 only)

Approved 2026-11-02 for `bambu_a1_01`. An agent is a request carrying
`X-Agent-Id`, or whose edge-verified role is in `dispatch.agent_roles`
(default `agent`). Agents may submit, approve and start only on a printer with
`agent_mode_eligible: true` (config accepts it on a Bambu A1 only) whose switch
is on; otherwise 403 with `agent_mode: "not_eligible"` or `"off"`.

- `GET /printers/{id}/agent-mode` — `{printer_id, eligible, enabled,
changed_by, changed_by_role, changed_at, reason, audit: [...]}`.
- `POST /printers/{id}/agent-mode` `{"enabled": bool, "reason": "..."}` —
edge-verified identities with a role in `dispatch.agent_mode_admin_roles`
(default `admin`) only, never an agent; 409 for an ineligible printer. Each
flip is appended to the audit log before it takes effect.
- `details.agent_mode` on `/printers/{id}/status`, and per printer on
`/status`: `{eligible, enabled, changed_by, changed_at, reason}`.

An agent's start uses `plate_check_method: agent_camera`, a fresh
`snapshot_token` from this printer and claim, and optionally
`plate_check_rationale`. The dispatch record's `plate_check` then has
`decided_by: "agent"`, `agent_id`, `rationale` and `snapshot_sha256`, and the
frame is archived at `/submissions/{id}/plate.jpg`.

## Print records and ELN ingest

- `GET /submissions/{id}/artifact` streams the exact stored file with `ETag:
"<sha256>"` (304 on `If-None-Match`; 410 once deleted).
- `GET /submissions/{id}/result` returns the result bundle (`schema_id`
`ac.bambu.print_result`, `schema_version` 1, `final` once terminal). It
survives `DELETE` of the job record.
- `POST /submissions/{id}/eln-ingest` `{"eln_project": "...", "requested_by"?}`
queues a terminal job for filing through the central server's ingest; `GET`
on the same path reads its outbox entry; `GET /results/outbox` lists them.
States: `local_only`, `pending`, `delivered`, `filing`, `filed`, `held`.
- `POST /submissions` and `POST /submissions/{id}/approve` take an optional
`eln_project`.
- `GET /submissions` adds `updated_after`, `order=newest` and `offset` for
change paging; the default order is unchanged.

The gateway never writes to the ELN; only the central server does. `/status`
reports `results_ingest_configured`, `results_outbox`, `results_pending`,
`results_filing` and `results_held`.

## Agent workflow data

`GET /submissions/{id}/objects` returns where each sliced object sits on the
plate in **bed coordinates**: millimetres, origin at the front-left corner of
the printable area, +X right, +Y toward the back seen from the front, Z up, as
the printer's own toolpath addresses it (compare with the profile's
`bed_size_mm`). Each object has `object_id`, `name`, `center_x_mm`,
`center_y_mm`, `bounds`, `rotation_deg` (when known), `plate_index`, `source`
(`slicer_plate_json`, `gcode_label` or `model_transform`) and `gcode_bounds`,
the labelled-extrusion cross-check. No invented positions: an empty list when
the file does not say. There is no robot frame; the arm agent owns calibration.

`GET /submissions/{id}/pickup-targets` returns those objects with
`bed_size_mm`, `pickup: {bed_temperature_c, safe_bed_temperature_c, cooled,
observed_at}` from the monitor's cache, and `ready` (finished, cooled, and at
least one object). It never contacts a printer or a robot.

`GET /events?after=<event_id>` is a pollable lifecycle feed: `job.started`,
`job.finished`, `job.failed`, `job.rejected`, `job.cancelled`, `job.cooled`
and `gateway.restarted`, each with `schema_version`, `event_id`,
`gateway_id`, `boot_id`, `submission_id`, `printer_id`, `state`,
`updated_at`, `eln_project`, `note`, and for job events the bed-frame
`object_positions`; `job.finished` and `job.cooled` add `pickup`. Ids persist
across restarts, and a restart-recovered failure is a `job.failed` with
`recovered_after_restart: true`. Configure `agent_workflow.event_webhook_urls`
to POST the same JSON elsewhere; delivery is best effort and never affects a
job.

When both dispatch and `agent_workflow.vision_enabled` are enabled,
`POST /printers/{id}/bed-check` accepts a claimed-control `snapshot_token` and
returns an advisory empty-bed assessment based on an operator reference image.
It performs no camera access itself, and its result is not a plate check.
13 changes: 9 additions & 4 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,10 @@ Open, from the design's §10 data gaps and what the build surfaced:
It is legal only from `queued` / `approved`, never for a dispatched job —
aborting a print stays a control-plane action. Worth folding back into
`SUBMISSION_PIPELINE_DESIGN.md` §5 when that doc is next revised.
- ~~No retention policy~~ — done. Terminal records are swept at startup past
`submissions.retain_terminal_days` (30 default, null disables), and
- ~~No retention policy~~ — done, then made opt-in (2026-11-02): records are
print records, so nothing is swept unless `submissions.retain_terminal_days`
is set, cancelling keeps the artifact, and result bundles are never swept.
When set, terminal records are swept at startup past that age, and
`DELETE /submissions/{id}` removes one finished job immediately. A job still
in play is never swept however old. Sweeping at startup rather than on a
timer keeps on-disk and in-memory views identical — the divergence that
Expand Down Expand Up @@ -179,8 +181,11 @@ the HTTPS block, since only they know what else changed.

Known gap, inherited from the OT-2 embed: a write inside the framed panel
bypasses the dashboard's `control_action` audit row. Submissions are recorded in
the job store's history, so there is a trail; it is not in `equipment_events`
until the gateway pushes to `/api/ingest/events`.
the job store's history, so there is a trail. Lifecycle events can now be
pushed with `agent_workflow.event_webhook_urls` (e.g. to `/api/ingest/events`)
and result bundles through the outbox to the central ingest
(`BAMBU_RESULTS_URL`); the central side of the print-results route, and of
`GET {url}/{device_id}/{id}` filing status, still has to exist there.

## Test suite

Expand Down
45 changes: 45 additions & 0 deletions printers.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,19 @@ submissions:
scan_max_bytes: 67108864 # 64 MiB; above this only the head and tail of
# an artifact are read and plate fit is not
# reported rather than guessed from a partial scan
retain_terminal_days: null # keep print records; set a number to sweep old ones
cancel_deletes_artifact: false # cancelling keeps the artifact unless true

# Result bundles and the optional ELN ingest via the central dashboard only.
# Without an ingest URL and BAMBU_RESULTS_TOKEN (env) every job stays local_only.
results:
gateway_id: bambu_gateway
ingest_url: null # e.g. https://<dashboard>/api/ingest/print-results;
# BAMBU_RESULTS_URL overrides it
poll_interval_s: 60 # filing-status poll after delivery
retry_initial_s: 10 # backoff doubles up to retry_max_s
retry_max_s: 1800
request_timeout_s: 10

# Control plane: claims and the start/stop/snapshot verbs. Off unless enabled
# here. With it off the gateway is exactly the monitoring-only release.
Expand All @@ -24,11 +37,26 @@ dispatch:
safe_bed_c: 45 # refuse to start above these: the last job
safe_nozzle_c: 70 # has not cooled and the plate is suspect
confirm_timeout_s: 180 # how long the printer has to report RUNNING
# Agent mode (approved 2026-11-02, Bambu A1 only): who may flip a printer's
# switch, which edge roles count as agents (as does an X-Agent-Id header),
# and how fresh an agent_camera snapshot must be.
agent_mode_admin_roles: [admin]
agent_roles: [agent]
agent_snapshot_max_age_s: 120
bed_leveling: true
flow_calibration: false
vibration_calibration: false
timelapse: false

# Agent workflow integrations are data-only. They cannot move a printer or robot.
agent_workflow:
event_webhook_urls: [] # e.g. [https://dashboard/api/ingest/events]
event_buffer_size: 1000
pickup_safe_bed_c: 45 # bed temperature at which a finished plate counts as cooled
cooldown_watch_timeout_s: 14400 # how long to watch for job.cooled after job.finished
vision_enabled: false # advisory snapshot comparison only
empty_bed_reference_directory: null # operator-captured <printer_id>.jpg files

# STL slicing with an installed Bambu Studio (CLI, headless). Off unless enabled.
# `work_dir` must be writable by the service (its home is read-only under systemd).
slicer:
Expand Down Expand Up @@ -69,3 +97,20 @@ printers:
chamber_temperature_c: null
ams:
filament_forbidden: [] # e.g. [ABS, ASA] on an open-frame machine

- id: bambu_a1_01
name: Bambu A1 01
model: A1
env_prefix: BAMBU_A1_01
# Lets a verified admin switch agent mode on for this printer at runtime
# (POST /printers/bambu_a1_01/agent-mode). The switch itself starts off.
# Accepted on a Bambu A1 only; any other model fails config validation.
agent_mode_eligible: true
profile:
enclosure: open
nozzle_diameter_mm: 0.4
bed_size_mm: [256, 256]
plate: textured_plate
limits:
nozzle_temperature_c: [0, 300]
bed_temperature_c: [0, 100]
Loading
Loading