From df78c83b4946e50ec5e39eca238375e8605c0ac7 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 01:46:15 +0000 Subject: [PATCH 1/5] Add agent workflow and robot handoff APIs Co-authored-by: Yang Cao --- README.md | 48 +++++- docs/API_REFERENCE.md | 25 +++ printers.example.yaml | 8 + src/bambu_server/agent_workflow.py | 166 ++++++++++++++++++++ src/bambu_server/artifacts.py | 242 +++++++++++++++++++++++++++++ src/bambu_server/config.py | 24 +++ src/bambu_server/dispatch.py | 22 ++- src/bambu_server/main.py | 204 +++++++++++++++++++++++- src/bambu_server/vision.py | 53 +++++++ tests/test_artifacts.py | 25 +++ tests/test_submission_api.py | 16 ++ 11 files changed, 821 insertions(+), 12 deletions(-) create mode 100644 src/bambu_server/agent_workflow.py create mode 100644 src/bambu_server/vision.py diff --git a/README.md b/README.md index 19acd36..5a7b58c 100644 --- a/README.md +++ b/README.md @@ -112,8 +112,42 @@ Submission pipeline routes: | POST | `/submissions/{submission_id}/approve` | Record sign-off on a queued job | | POST | `/submissions/{submission_id}/cancel` | Withdraw a waiting job from the queue | | DELETE | `/submissions/{submission_id}` | Delete a finished job's record (retention) | - -No `/control/*` routes exist, and no route dispatches a print. +| GET | `/submissions/{submission_id}/objects` | Per-object bed-mm centres, bounds, transforms, and labelled-G-code cross-checks | +| GET | `/events` | Pollable `job.started`, `job.finished`, and `job.failed` feed | +| GET/POST | `/printers/{id}/robot-calibration` | Stored bed-mm → robot-frame transform; never moves a robot | +| GET | `/submissions/{submission_id}/pickup-targets` | Finished-job arm-frame targets and cool-down readiness | + +With `dispatch.enabled: false`, no `/control/*` routes exist and no route +dispatches a print. + +## Agent workflow + +An orchestration agent can submit an already-sliced artifact, inspect +`/submissions/{id}/objects`, and wait on `GET /events` (using its last +`next_after` value) or an operator-configured `agent_workflow.event_webhook_urls` +target such as the dashboard's `/api/ingest/events`. Event payloads include the +submission, printer, timestamp, and parsed object placements. + +After `job.finished`, the agent requests `/submissions/{id}/pickup-targets`. +The response is only planning data: it is ready only when the monitor's cached +bed temperature is at or below `agent_workflow.pickup_safe_bed_c`, and only +after a person has stored a 4×4 affine transform using +`POST /printers/{id}/robot-calibration`. This service never opens a robot +connection or issues motion. + +`agent_workflow.vision_enabled` enables an optional, dependency-light advisory +comparison of an existing claimed control snapshot against an +operator-captured `.jpg` empty-bed reference. It returns +`clear` only for an exact reference match and otherwise conservatively returns +`occupied` or `unknown`. It is intentionally **not** a `start_print` plate +check: the lab safety contract requires a person to confirm an empty plate, so +an AI agent cannot use vision to set `plate_confirmed_empty` or start a print. +H2D camera support remains dependent on the backend camera implementation; if +the claimed snapshot route cannot produce a frame, this check cannot run. + +End-to-end: submit → validate → human approves → agent may inspect objects → +person claims and confirms the plate → explicit `start_print` → wait for event +→ cool down → fetch pickup targets → send those data to the robot planner. The status envelope uses `equipment_kind: other` because the authoritative contract does not yet define a `3d_printer` kind. `details.device_type` carries @@ -236,7 +270,7 @@ version). Slicing runs inline in the request. ### Control plane Off unless `dispatch.enabled` is set. When on, each printer gets STATUS_SPEC -v1.1 claims and three verbs under `/printers/{id}/control/`: +v1.1 claims and four verbs under `/printers/{id}/control/`: | Route | What it does | |---|---| @@ -300,10 +334,10 @@ built-in defaults, because a guessed limit is a fabricated machine fact. The gcode scan is explicitly a **heuristic**, and the passing detail says so. It is not a proof of safety. -Material matching is not a dispatch mapping: per-filament slot selection, -per-slot temperature checks, sufficient quantity, and revalidation at dispatch -remain prerequisites for the future control plane. The current approval flag -does not establish those guarantees or enable printer execution. +Material matching is not a dispatch mapping: the person starting the job +explicitly selects every filament slot, and the gateway rechecks slot material, +per-slot temperature windows, and current printer state at dispatch. Approval +alone does not establish those guarantees or start a printer. ### What is read from an artifact diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 8d81064..a5772e3 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -76,3 +76,28 @@ 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 workflow data + +`GET /submissions/{id}/objects` returns parsed per-object bed coordinates: +model-name/id, centre XY, min/max bounds, rotation where represented, plate +index, and an extrusion-only labelled-G-code bounds cross-check where available. +It returns no invented positions for unlabeled or unsupported artifacts. + +`GET /events?after=` is a bounded, pollable lifecycle feed with +`job.started`, `job.finished`, and `job.failed` events. Configure +`agent_workflow.event_webhook_urls` to also POST the same JSON event to the +dashboard ingest endpoint or another operator-approved receiver; delivery is +best effort and cannot change printer state. + +`POST /printers/{id}/robot-calibration` stores a 4×4 affine bed-mm to robot-frame +matrix and `GET /submissions/{id}/pickup-targets` converts finished-job object +centres using it. The latter includes cached bed temperature and is only +`ready` below `agent_workflow.pickup_safe_bed_c`. Neither endpoint talks to a +robot or creates a motion. + +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. It cannot be supplied to `start_print`; +the required human plate confirmation remains unchanged. diff --git a/printers.example.yaml b/printers.example.yaml index 79ed2a3..1f1e04d 100644 --- a/printers.example.yaml +++ b/printers.example.yaml @@ -29,6 +29,14 @@ dispatch: 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 + vision_enabled: false # advisory snapshot comparison only + empty_bed_reference_directory: null # operator-captured .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: diff --git a/src/bambu_server/agent_workflow.py b/src/bambu_server/agent_workflow.py new file mode 100644 index 0000000..dbbf1fe --- /dev/null +++ b/src/bambu_server/agent_workflow.py @@ -0,0 +1,166 @@ +"""Agent-facing, data-only workflow helpers. + +No type in this module reaches a printer or a robot. It persists calibration +and event records locally; callers decide whether to forward events elsewhere. +""" + +from __future__ import annotations + +import asyncio +import json +import logging +from collections import deque +from datetime import UTC, datetime +from pathlib import Path +from typing import Literal +from urllib.request import Request, urlopen + +from pydantic import BaseModel, Field, model_validator + +from .artifacts import ObjectPosition + +logger = logging.getLogger(__name__) + + +class GatewayEvent(BaseModel): + event_id: str + type: Literal["job.started", "job.finished", "job.failed"] + submission_id: str + printer_id: str + occurred_at: datetime + object_positions: tuple[ObjectPosition, ...] = () + + +class EventPage(BaseModel): + events: list[GatewayEvent] + next_after: str | None = None + + +class BedToRobotCalibration(BaseModel): + """Rigid 2D placement transform from bed millimetres to arm coordinates.""" + + printer_id: str + arm_frame: str = Field(min_length=1, max_length=120) + # Homogeneous row-major 4x4 matrix. Coordinates are (x, y, z, 1). + matrix: tuple[float, ...] = Field(min_length=16, max_length=16) + updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC)) + + @model_validator(mode="after") + def affine_last_row(self) -> BedToRobotCalibration: + if tuple(self.matrix[12:]) != (0.0, 0.0, 0.0, 1.0): + raise ValueError("matrix must be an affine 4x4 transform with last row [0,0,0,1]") + return self + + +class PickupTarget(BaseModel): + object_id: str + name: str | None + arm_frame: str + x: float + y: float + z: float + rotation_deg: float | None = None + + +class PickupPlan(BaseModel): + submission_id: str + printer_id: str + ready: bool + reason: str + bed_temperature_c: float | None = None + safe_bed_temperature_c: float + targets: list[PickupTarget] = Field(default_factory=list) + + +class CalibrationStore: + def __init__(self, root: Path) -> None: + self._path = root / "bed_to_robot_calibrations.json" + self._values: dict[str, BedToRobotCalibration] = {} + self._lock = asyncio.Lock() + + def load(self) -> None: + if not self._path.is_file(): + return + try: + values = json.loads(self._path.read_text(encoding="utf-8")) + self._values = { + value["printer_id"]: BedToRobotCalibration.model_validate(value) + for value in values if isinstance(value, dict) + } + except (OSError, ValueError, json.JSONDecodeError): + logger.warning("Ignoring unreadable robot calibration store") + + def get(self, printer_id: str) -> BedToRobotCalibration | None: + return self._values.get(printer_id) + + async def set(self, calibration: BedToRobotCalibration) -> BedToRobotCalibration: + async with self._lock: + self._values[calibration.printer_id] = calibration + payload = [value.model_dump(mode="json") for value in self._values.values()] + await asyncio.to_thread(self._write, payload) + return calibration + + def _write(self, payload: list[dict[str, object]]) -> None: + self._path.parent.mkdir(parents=True, exist_ok=True) + temporary = self._path.with_suffix(".tmp") + temporary.write_text(json.dumps(payload, indent=2), encoding="utf-8") + temporary.replace(self._path) + + +class EventHub: + """Bounded event feed with best-effort asynchronous JSON webhook delivery.""" + + def __init__(self, *, webhook_urls: list[str], max_events: int = 1000) -> None: + self._events: deque[GatewayEvent] = deque(maxlen=max_events) + self._webhook_urls = webhook_urls + self._next = 0 + + def page(self, after: str | None, limit: int) -> EventPage: + events = list(self._events) + if after: + events = [event for event in events if event.event_id > after] + events = events[:limit] + return EventPage(events=events, next_after=events[-1].event_id if events else after) + + async def publish( + self, event_type: Literal["job.started", "job.finished", "job.failed"], *, + submission_id: str, printer_id: str, object_positions: tuple[ObjectPosition, ...] = (), + ) -> GatewayEvent: + self._next += 1 + event = GatewayEvent( + event_id=f"{self._next:020d}", + type=event_type, + submission_id=submission_id, + printer_id=printer_id, + occurred_at=datetime.now(UTC), + object_positions=object_positions, + ) + self._events.append(event) + for url in self._webhook_urls: + asyncio.create_task(self._deliver(url, event)) + return event + + async def _deliver(self, url: str, event: GatewayEvent) -> None: + def send() -> None: + request = Request( + url, data=event.model_dump_json().encode(), method="POST", + headers={"Content-Type": "application/json"}, + ) + with urlopen(request, timeout=5): # noqa: S310 - configured operator endpoint + pass + try: + await asyncio.to_thread(send) + except OSError: + logger.warning("Could not deliver gateway event to configured webhook") + + +def transform_target(position: ObjectPosition, calibration: BedToRobotCalibration) -> PickupTarget: + m = calibration.matrix + x, y, z = position.center_x_mm, position.center_y_mm, 0.0 + return PickupTarget( + object_id=position.object_id, name=position.name, arm_frame=calibration.arm_frame, + x=round(m[0] * x + m[1] * y + m[2] * z + m[3], 3), + y=round(m[4] * x + m[5] * y + m[6] * z + m[7], 3), + z=round(m[8] * x + m[9] * y + m[10] * z + m[11], 3), + rotation_deg=position.rotation_deg, + ) diff --git a/src/bambu_server/artifacts.py b/src/bambu_server/artifacts.py index c380995..1edc733 100644 --- a/src/bambu_server/artifacts.py +++ b/src/bambu_server/artifacts.py @@ -174,6 +174,34 @@ class ArtifactFacts(BaseModel): notes: tuple[str, ...] = Field(default_factory=tuple) +class ObjectBounds(BaseModel): + """Axis-aligned XY bounds in the printer's bed coordinate system.""" + + min_x_mm: float + min_y_mm: float + max_x_mm: float + max_y_mm: float + + +class ObjectPosition(BaseModel): + """One independently addressable model or labelled toolpath region. + + ``gcode_bounds`` is an extrusion-only observation, when the slicer emitted + object labels. It is intentionally a cross-check rather than a replacement + for the model transform: purge lines and travel moves are not object shape. + """ + + object_id: str + name: str | None = None + center_x_mm: float + center_y_mm: float + bounds: ObjectBounds + rotation_deg: float | None = None + plate_index: int | None = None + source: Literal["model_transform", "gcode_label"] + gcode_bounds: ObjectBounds | None = None + + class _Scan: """Accumulates observations over one pass of a gcode stream.""" @@ -739,3 +767,217 @@ def inspect_artifact(path: Path, *, scan_max_bytes: int) -> ArtifactFacts: if kind == "gcode": return _inspect_gcode(path, scan_max_bytes=scan_max_bytes) return _inspect_3mf(path, scan_max_bytes=scan_max_bytes) + + +# -- Per-object placement ------------------------------------------------- + +_OBJECT_LABEL_RE = re.compile(r"^;\s*(?:OBJECT|MESH|PRINTING_OBJECT)\s*[:=]\s*(.+)$", re.I) +_EXCLUDE_OBJECT_RE = re.compile( + r"^EXCLUDE_OBJECT_DEFINE\s+NAME=([^\s]+).*?CENTER=([-.\d]+),([-.\d]+)", re.I +) +_E_RE = re.compile(r"(?:^|\s)E(-?\d+(?:\.\d+)?)", re.I) + + +def _bounds(values: list[tuple[float, float]]) -> ObjectBounds | None: + if not values: + return None + xs, ys = zip(*values, strict=True) + return ObjectBounds( + min_x_mm=round(min(xs), 3), + min_y_mm=round(min(ys), 3), + max_x_mm=round(max(xs), 3), + max_y_mm=round(max(ys), 3), + ) + + +def _labelled_gcode_positions(data: bytes, *, plate_index: int | None) -> list[ObjectPosition]: + """Extract slicer object labels and their extrusion-only XY footprints. + + This deliberately accepts several common comment spellings. Unlabelled + gcode cannot safely be divided into objects and returns no invented parts. + """ + + points: dict[str, list[tuple[float, float]]] = {} + names: dict[str, str] = {} + current: str | None = None + x = y = None + e = None + absolute_e = True + for raw in data.decode("latin-1", errors="replace").splitlines(): + label = _OBJECT_LABEL_RE.match(raw.strip()) + if label: + name = label.group(1).strip() + if name and name.lower() not in {"noname", "unknown"}: + current = name + points.setdefault(current, []) + names[current] = name + continue + defined = _EXCLUDE_OBJECT_RE.match(raw.strip()) + if defined: + name, cx, cy = defined.groups() + current = name + points.setdefault(name, []).append((float(cx), float(cy))) + names[name] = name + continue + body = raw.split(";", 1)[0].strip() + word = body.split(maxsplit=1)[0].upper() if body else "" + if word == "M82": + absolute_e = True + continue + if word == "M83": + absolute_e = False + continue + if word not in {"G0", "G1"}: + continue + values = {axis: float(value) for axis, value in _AXIS_RE.findall(body.upper())} + x, y = values.get("X", x), values.get("Y", y) + extruder = _E_RE.search(body) + is_extruding = False + if extruder: + next_e = float(extruder.group(1)) + is_extruding = next_e > (e if e is not None else 0.0) if absolute_e else next_e > 0 + e = next_e if absolute_e else (e or 0.0) + next_e + if current and is_extruding and x is not None and y is not None: + points[current].append((x, y)) + + result: list[ObjectPosition] = [] + for index, (key, object_points) in enumerate(points.items(), start=1): + bounds = _bounds(object_points) + if bounds is None: + continue + result.append(ObjectPosition( + object_id=f"gcode-{index}", + name=names.get(key), + center_x_mm=round((bounds.min_x_mm + bounds.max_x_mm) / 2, 3), + center_y_mm=round((bounds.min_y_mm + bounds.max_y_mm) / 2, 3), + bounds=bounds, + plate_index=plate_index, + source="gcode_label", + gcode_bounds=bounds, + )) + return result + + +def _model_positions( + data: bytes, *, plate_index: int | None, object_plates: dict[str, int] | None = None +) -> list[ObjectPosition]: + """Read standard 3MF build-item transforms and object vertex bounds. + + The 3MF transform has nine linear values followed by translation. The + implementation handles ordinary mesh resources; unsupported components are + omitted rather than guessed. + """ + + root = _parse_xml(data) + if root is None: + return [] + meshes: dict[str, list[tuple[float, float, float]]] = {} + names: dict[str, str] = {} + for element in root.iter(): + if _local_name(element.tag) != "object" or not element.get("id"): + continue + object_id = element.get("id") or "" + name = element.get("name") or element.get("partnumber") + if name: + names[object_id] = name + vertices: list[tuple[float, float, float]] = [] + for vertex in element.iter(): + if _local_name(vertex.tag) != "vertex": + continue + try: + vertices.append((float(vertex.get("x", "")), float(vertex.get("y", "")), float(vertex.get("z", "0")))) + except ValueError: + continue + if vertices: + meshes[object_id] = vertices + result: list[ObjectPosition] = [] + for item in root.iter(): + if _local_name(item.tag) != "item" or not item.get("objectid"): + continue + object_id = item.get("objectid") or "" + vertices = meshes.get(object_id) + if not vertices: + continue + try: + transform = [float(value) for value in (item.get("transform") or "").split()] + except ValueError: + continue + if not transform: + transform = [1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0] + if len(transform) != 12: + continue + a, b, _c, d, e, _f, _g, _h, _i, tx, ty, _tz = transform + transformed = [(a * vx + d * vy + tx, b * vx + e * vy + ty) for vx, vy, _vz in vertices] + bounds = _bounds(transformed) + if bounds is None: + continue + rotation = round(__import__("math").degrees(__import__("math").atan2(b, a)), 3) + result.append(ObjectPosition( + object_id=f"3mf-{object_id}", + name=names.get(object_id), + center_x_mm=round((bounds.min_x_mm + bounds.max_x_mm) / 2, 3), + center_y_mm=round((bounds.min_y_mm + bounds.max_y_mm) / 2, 3), + bounds=bounds, + rotation_deg=rotation, + plate_index=(object_plates or {}).get(object_id, plate_index), + source="model_transform", + )) + return result + + +def _model_setting_plates(data: bytes) -> dict[str, int]: + """Map Bambu project object IDs to their declared plate, when present.""" + + root = _parse_xml(data) + if root is None: + return {} + plates: dict[str, int] = {} + for plate in root.iter(): + if _local_name(plate.tag) != "plate": + continue + try: + index = int(plate.get("index", "")) + except ValueError: + continue + for object_ in plate.iter(): + if _local_name(object_.tag) == "object" and object_.get("id"): + plates[object_.get("id") or ""] = index + return plates + + +def inspect_object_positions(path: Path, *, scan_max_bytes: int) -> tuple[ObjectPosition, ...]: + """Return object positions from a submitted artifact without printer I/O.""" + + if path.suffix.lower() == ".gcode": + data = path.read_bytes() + if len(data) > scan_max_bytes: + return () + return tuple(_labelled_gcode_positions(data, plate_index=None)) + if path.suffix.lower() != ".3mf": + raise ArtifactError(f"unsupported artifact extension {path.suffix!r}") + with zipfile.ZipFile(path) as archive: + names = archive.namelist() + plate_names = sorted(name for name in names if _PLATE_GCODE_RE.match(name)) + plate_index = _plate_index(plate_names[0]) if plate_names else None + model = _read_member(archive, "3D/3dmodel.model", budget=_MAX_CONFIG_BYTES) + settings = _read_member(archive, "Metadata/model_settings.config", budget=_MAX_CONFIG_BYTES) + positions = ( + _model_positions( + model, + plate_index=plate_index, + object_plates=_model_setting_plates(settings) if settings else None, + ) + if model else [] + ) + if plate_names: + gcode = _read_member(archive, plate_names[0], budget=scan_max_bytes) + labelled = _labelled_gcode_positions(gcode or b"", plate_index=plate_index) + by_name = {entry.name: entry for entry in labelled if entry.name} + positions = [ + entry.model_copy(update={"gcode_bounds": by_name[entry.name].bounds}) + if entry.name in by_name else entry + for entry in positions + ] + if not positions: + positions = labelled + return tuple(positions) diff --git a/src/bambu_server/config.py b/src/bambu_server/config.py index 1e3f730..76441a7 100644 --- a/src/bambu_server/config.py +++ b/src/bambu_server/config.py @@ -174,6 +174,24 @@ class DispatchSettings(BaseModel): timelapse: bool = False +class AgentWorkflowSettings(BaseModel): + """Optional data integrations for orchestration agents; all are off by default.""" + + #: Operator-configured HTTPS endpoints, e.g. the dashboard event ingest + #: route. Failed delivery is logged without a body and never affects a job. + event_webhook_urls: list[str] = Field(default_factory=list) + event_buffer_size: int = Field(default=1000, ge=10, le=10000) + #: Temperature at or below which the pickup endpoint calls a finished bed + #: ready. It is advice for a robot planner, never a robot command. + pickup_safe_bed_c: float = Field(default=45.0, gt=0) + #: Vision remains advisory under the lab safety rules. It cannot satisfy + #: the human plate-clear confirmation required by start_print. + vision_enabled: bool = False + #: A directory containing operator-captured empty-bed references named + #: ``.jpg``. No reference produces ``unknown``, never ``clear``. + empty_bed_reference_directory: Path | None = None + + class SlicerSettings(BaseModel): """Bambu Studio CLI slicing of an uploaded ``.stl``. @@ -216,6 +234,7 @@ class Settings(BaseModel): cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:8000"]) submissions: SubmissionSettings = Field(default_factory=SubmissionSettings) dispatch: DispatchSettings = Field(default_factory=DispatchSettings) + agent_workflow: AgentWorkflowSettings = Field(default_factory=AgentWorkflowSettings) slicer: SlicerSettings = Field(default_factory=SlicerSettings) @model_validator(mode="after") @@ -292,4 +311,9 @@ def load_settings(path: str | Path | None = None) -> Settings: ).resolve() if not settings.slicer.work_dir.is_absolute(): settings.slicer.work_dir = (resolved.parent / settings.slicer.work_dir).resolve() + references = settings.agent_workflow.empty_bed_reference_directory + if references is not None and not references.is_absolute(): + settings.agent_workflow.empty_bed_reference_directory = ( + resolved.parent / references + ).resolve() return settings diff --git a/src/bambu_server/dispatch.py b/src/bambu_server/dispatch.py index 159a5d8..ebfecd4 100644 --- a/src/bambu_server/dispatch.py +++ b/src/bambu_server/dispatch.py @@ -26,6 +26,7 @@ import logging import re import secrets +from collections.abc import Awaitable, Callable from dataclasses import dataclass, field from datetime import UTC, datetime, timedelta from pathlib import Path @@ -249,6 +250,7 @@ def __init__( monitors: dict[str, PrinterMonitor], backends: dict[str, PrinterBackend], poll_interval_s: float, + event_sink: Callable[[str, SubmissionJob], Awaitable[None]] | None = None, ) -> None: self.settings = settings self.gate = ControlGate(settings) @@ -258,6 +260,7 @@ def __init__( self._poll_s = max(0.01, poll_interval_s) self._printers = {printer_id: _PrinterControl() for printer_id in monitors} self._snapshots: dict[str, _Snapshot] = {} + self._event_sink = event_sink # -- lifecycle --------------------------------------------------------- @@ -310,6 +313,18 @@ def plate_snapshot_path(self, job: SubmissionJob) -> Path | None: path = self._store.root / f"{job.submission_id}.plate.jpg" return path if path.is_file() else None + def snapshot_image(self, token: str, *, printer_id: str) -> bytes | None: + """Return a retained control snapshot for advisory local analysis.""" + + snapshot = self._snapshots.get(token) + if snapshot is None or snapshot.printer_id != printer_id or not snapshot.path.is_file(): + return None + return snapshot.path.read_bytes() + + async def _emit(self, event_type: str, job: SubmissionJob) -> None: + if self._event_sink is not None: + await self._event_sink(event_type, job) + def _control(self, printer_id: str) -> _PrinterControl: control = self._printers.get(printer_id) if control is None: @@ -568,6 +583,7 @@ async def _await_running( job = await self._store.update_dispatch( job, to_state="running", note=note, observed_running_at=datetime.now(UTC) ) + await self._emit("job.started", job) control.watcher = asyncio.create_task(self._watch_running(job.submission_id)) return job control.active_job = None @@ -596,21 +612,23 @@ async def _watch_running(self, submission_id: str) -> None: gcode_state = (print_job.state if print_job and print_job.state else "").upper() now = datetime.now(UTC) if gcode_state == "FINISH": - await self._store.update_dispatch( + job = await self._store.update_dispatch( job, to_state="finished", note="printer reports the job finished", observed_finished_at=now, ) + await self._emit("job.finished", job) else: note = "printer left the running state without finishing" if gcode_state: note += f" (state {gcode_state.lower()})" if status.last_error: note += f"; printer error {status.last_error.code}" - await self._store.update_dispatch( + job = await self._store.update_dispatch( job, to_state="failed", note=note, observed_finished_at=now ) + await self._emit("job.failed", job) return except InvalidTransition: logger.exception("Could not record the outcome of %s", submission_id) diff --git a/src/bambu_server/main.py b/src/bambu_server/main.py index 67be0f5..8312edb 100644 --- a/src/bambu_server/main.py +++ b/src/bambu_server/main.py @@ -45,7 +45,15 @@ from sdl_lab_contract.claims import ClaimRejection, ClaimRequest, ClaimResponse from . import __version__ -from .artifacts import ARTIFACT_EXTENSIONS +from .agent_workflow import ( + BedToRobotCalibration, + CalibrationStore, + EventHub, + EventPage, + PickupPlan, + transform_target, +) +from .artifacts import ARTIFACT_EXTENSIONS, ObjectPosition, inspect_object_positions from .backend import BambuLabsBackend, PrinterBackend from .camera import CameraUnavailable, CameraViewer from .claims import ClaimConflict, ClaimLost @@ -92,6 +100,7 @@ run_validation, safe_display_name, ) +from .vision import BedAssessment, ReferenceDigestDetector #: Header carrying the claim token on control routes (STATUS_SPEC §5). CLAIM_HEADER = "X-Claim-Token" @@ -174,6 +183,7 @@ def create_app( dispatchers: dict[str, Dispatcher] = {} slicers: dict[str, BambuStudioSlicer] = {} cameras: dict[str, CameraViewer] = {} + workflows: dict[str, object] = {} control_enabled = bool(settings and settings.dispatch.enabled) @asynccontextmanager @@ -185,6 +195,35 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: await asyncio.to_thread(store.load) stores["default"] = store app.state.submissions = store + calibration = CalibrationStore(store.root) + await asyncio.to_thread(calibration.load) + hub = EventHub( + webhook_urls=active_settings.agent_workflow.event_webhook_urls, + max_events=active_settings.agent_workflow.event_buffer_size, + ) + workflows.update( + calibration=calibration, + events=hub, + detector=ReferenceDigestDetector( + active_settings.agent_workflow.empty_bed_reference_directory + ), + ) + + async def publish_job_event(event_type: str, job: SubmissionJob) -> None: + try: + positions = await asyncio.to_thread( + inspect_object_positions, + store.artifact_path(job), + scan_max_bytes=store.settings.scan_max_bytes, + ) + except (OSError, ValueError): + positions = () + await hub.publish( + event_type, + submission_id=job.submission_id, + printer_id=job.target_machine, + object_positions=positions, + ) backends: dict[str, PrinterBackend] = {} for definition in active_settings.printers: credentials = resolve_credentials(definition) @@ -203,6 +242,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: monitors=monitors, backends=backends, poll_interval_s=active_settings.poll_interval_seconds, + event_sink=publish_job_event, ) dispatchers["default"] = dispatcher cameras["default"] = CameraViewer(backends) @@ -221,6 +261,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: stores.clear() dispatchers.clear() slicers.clear() + workflows.clear() app = FastAPI( title="AC Bambu Printer Gateway", @@ -229,8 +270,9 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: "Monitoring-only MQTT gateway for Bambu Lab printers. Each configured " "printer is exposed through the AC lab equipment status spec v1.2. " "Profiles expose typed AMS inventory, color-label provenance, and remaining " - "filament estimates. Submission, validation, queuing and approval only store " - "gateway records; dispatch is unavailable. Use the authenticated /bambu/ " + "filament estimates. Dispatch can be enabled locally for claimed, human-confirmed " + "starts. Agent workflow routes expose artifact positions, lifecycle events, and " + "robot pickup data only. Use the authenticated /bambu/ " "edge path for browser access. No credentials or raw MQTT payloads are exposed." ), docs_url=None, @@ -287,6 +329,18 @@ def get_slicer() -> BambuStudioSlicer: raise HTTPException(status_code=503, detail="slicer unavailable") return slicer + def get_calibration() -> CalibrationStore: + value = workflows.get("calibration") + if not isinstance(value, CalibrationStore): + raise HTTPException(status_code=503, detail="calibration store unavailable") + return value + + def get_events() -> EventHub: + value = workflows.get("events") + if not isinstance(value, EventHub): + raise HTTPException(status_code=503, detail="event feed unavailable") + return value + @app.get("/", response_model=GatewayInfo, tags=["gateway"]) async def gateway_info() -> GatewayInfo: return GatewayInfo( @@ -705,6 +759,109 @@ async def read_submission( raise HTTPException(status_code=404, detail="unknown submission") return job + @app.get("/submissions/{submission_id}/objects", tags=["agent-workflow"]) + async def submission_objects( + store: Annotated[SubmissionStore, Depends(get_store)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> list[ObjectPosition]: + """Object centres and bounds in bed millimetres.""" + + job = store.get(submission_id) + if job is None: + raise HTTPException(status_code=404, detail="unknown submission") + try: + return await asyncio.to_thread( + inspect_object_positions, store.artifact_path(job), + scan_max_bytes=store.settings.scan_max_bytes, + ) + except (OSError, ValueError) as exc: + raise HTTPException(status_code=422, detail="object positions unavailable") from exc + + @app.get("/events", response_model=EventPage, tags=["agent-workflow"]) + async def workflow_events( + events: Annotated[EventHub, Depends(get_events)], + after: Annotated[str | None, Query(max_length=40)] = None, + limit: Annotated[int, Query(ge=1, le=500)] = 100, + ) -> EventPage: + """Poll lifecycle events; configured webhooks are delivered independently.""" + + return events.page(after, limit) + + @app.get( + "/printers/{printer_id}/robot-calibration", + response_model=BedToRobotCalibration, + tags=["agent-workflow"], + ) + async def get_robot_calibration( + monitor: Annotated[PrinterMonitor, Depends(get_monitor)], + calibration: Annotated[CalibrationStore, Depends(get_calibration)], + ) -> BedToRobotCalibration: + value = calibration.get(monitor.definition.id) + if value is None: + raise HTTPException(status_code=404, detail="no robot calibration configured") + return value + + @app.post( + "/printers/{printer_id}/robot-calibration", + response_model=BedToRobotCalibration, + tags=["agent-workflow"], + ) + async def set_robot_calibration( + monitor: Annotated[PrinterMonitor, Depends(get_monitor)], + calibration: Annotated[CalibrationStore, Depends(get_calibration)], + request: BedToRobotCalibration, + ) -> BedToRobotCalibration: + """Store only a transform; this endpoint never contacts or moves a robot.""" + + if request.printer_id != monitor.definition.id: + raise HTTPException(status_code=422, detail="printer_id must match the URL") + return await calibration.set(request.model_copy(update={"updated_at": datetime.now(UTC)})) + + @app.get( + "/submissions/{submission_id}/pickup-targets", + response_model=PickupPlan, + tags=["agent-workflow"], + ) + async def pickup_targets( + store: Annotated[SubmissionStore, Depends(get_store)], + calibration: Annotated[CalibrationStore, Depends(get_calibration)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> PickupPlan: + job = store.get(submission_id) + if job is None: + raise HTTPException(status_code=404, detail="unknown submission") + safe = app.state.settings.agent_workflow.pickup_safe_bed_c + if job.state != "finished": + return PickupPlan( + submission_id=job.submission_id, printer_id=job.target_machine, ready=False, + reason="job is not finished", safe_bed_temperature_c=safe, + ) + monitor = monitors[job.target_machine] + metric = monitor.status().metrics.get("bed_temperature") + bed = float(metric.value) if metric and isinstance(metric.value, (int, float)) else None + transform = calibration.get(job.target_machine) + if transform is None: + return PickupPlan( + submission_id=job.submission_id, printer_id=job.target_machine, ready=False, + reason="no robot calibration configured", bed_temperature_c=bed, + safe_bed_temperature_c=safe, + ) + positions = await asyncio.to_thread( + inspect_object_positions, store.artifact_path(job), + scan_max_bytes=store.settings.scan_max_bytes, + ) + cool = bed is not None and bed <= safe + return PickupPlan( + submission_id=job.submission_id, printer_id=job.target_machine, + ready=cool and bool(positions), + reason="ready for robot planning" if cool and positions else ( + "bed temperature is unavailable or above the pickup limit" + if not cool else "no object positions found" + ), + bed_temperature_c=bed, safe_bed_temperature_c=safe, + targets=[transform_target(position, transform) for position in positions], + ) + @app.post( "/submissions/{submission_id}/approve", response_model=SubmissionJob, @@ -813,10 +970,51 @@ def get_camera() -> CameraViewer: if control_enabled: _register_control_routes(app, get_monitor, get_actor, get_dispatcher) _register_camera_route(app, get_monitor, get_camera) + if settings and settings.agent_workflow.vision_enabled: + _register_advisory_bed_check(app, get_monitor, get_dispatcher, workflows) return app +def _register_advisory_bed_check( + app: FastAPI, + get_monitor: Callable[..., PrinterMonitor], + get_dispatcher: Callable[[], Dispatcher], + workflows: dict[str, object], +) -> None: + """Assess a previously captured control snapshot without printer I/O. + + This route is intentionally advisory. It cannot be passed to + ``start_print`` and does not relax the required human confirmation. + """ + + class BedCheckRequest(BaseModel): + snapshot_token: str = Field(min_length=1, max_length=64) + + @app.post( + "/printers/{printer_id}/bed-check", + response_model=BedAssessment, + tags=["agent-workflow"], + ) + async def advisory_bed_check( + monitor: Annotated[PrinterMonitor, Depends(get_monitor)], + dispatcher: Annotated[Dispatcher, Depends(get_dispatcher)], + request: BedCheckRequest, + ) -> BedAssessment: + detector = workflows.get("detector") + if not isinstance(detector, ReferenceDigestDetector): + raise HTTPException(status_code=503, detail="bed detector unavailable") + image = dispatcher.snapshot_image(request.snapshot_token, printer_id=monitor.definition.id) + if image is None: + raise HTTPException(status_code=404, detail="snapshot token is unknown or expired") + return await asyncio.to_thread( + detector.assess, + printer_id=monitor.definition.id, + snapshot_token=request.snapshot_token, + image=image, + ) + + def _register_camera_route( app: FastAPI, get_monitor: Callable[..., PrinterMonitor], diff --git a/src/bambu_server/vision.py b/src/bambu_server/vision.py new file mode 100644 index 0000000..5f35728 --- /dev/null +++ b/src/bambu_server/vision.py @@ -0,0 +1,53 @@ +"""Dependency-light, swappable advisory empty-bed assessment.""" + +from __future__ import annotations + +import hashlib +from datetime import UTC, datetime +from pathlib import Path +from typing import Literal, Protocol + +from pydantic import BaseModel + + +class BedAssessment(BaseModel): + printer_id: str + snapshot_token: str + assessed_at: datetime + state: Literal["clear", "occupied", "unknown"] + confidence: float + detections: list[str] + advisory: Literal[True] = True + note: str = "Advisory only; a person must still confirm the plate before start_print." + + +class BedDetector(Protocol): + def assess(self, *, printer_id: str, snapshot_token: str, image: bytes) -> BedAssessment: ... + + +class ReferenceDigestDetector: + """Exact digest reference detector with an intentionally conservative verdict. + + It has no computer-vision dependency and establishes the plugin contract. + Deployments needing tolerance for lighting/camera changes can replace it + with a detector implementing :class:`BedDetector`. + """ + + def __init__(self, references: Path | None) -> None: + self._references = references + + def assess(self, *, printer_id: str, snapshot_token: str, image: bytes) -> BedAssessment: + reference = self._references / f"{printer_id}.jpg" if self._references else None + now = datetime.now(UTC) + if reference is None or not reference.is_file(): + return BedAssessment( + printer_id=printer_id, snapshot_token=snapshot_token, assessed_at=now, + state="unknown", confidence=0.0, detections=["no_empty_bed_reference"], + ) + same = hashlib.sha256(image).digest() == hashlib.sha256(reference.read_bytes()).digest() + return BedAssessment( + printer_id=printer_id, snapshot_token=snapshot_token, assessed_at=now, + state="clear" if same else "occupied", + confidence=1.0 if same else 0.8, + detections=[] if same else ["reference_mismatch"], + ) diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py index 39558b5..cb91267 100644 --- a/tests/test_artifacts.py +++ b/tests/test_artifacts.py @@ -10,6 +10,7 @@ from bambu_server.artifacts import ( ArtifactError, inspect_artifact, + inspect_object_positions, parse_duration_minutes, ) @@ -215,3 +216,27 @@ def test_unsupported_extension_is_an_error(tmp_path: Path) -> None: path.write_bytes(b"solid\n") with pytest.raises(ArtifactError): _inspect(path) + + +def test_3mf_model_transform_positions_are_reported_and_cross_checked(tmp_path: Path) -> None: + path = write_3mf(tmp_path / "objects.3mf", plate_gcode=( + SAMPLE_GCODE + + "; OBJECT: widget\nG1 X20 Y30 E10\nG1 X40 Y50 E12\n" + )) + model = """ + + + + """ + with zipfile.ZipFile(path, "a") as archive: + archive.writestr("3D/3dmodel.model", model) + + objects = inspect_object_positions(path, scan_max_bytes=SCAN_BUDGET) + + assert len(objects) == 1 + assert objects[0].name == "widget" + assert objects[0].center_x_mm == 35 + assert objects[0].center_y_mm == 50 + assert objects[0].bounds.min_x_mm == 30 + assert objects[0].gcode_bounds is not None + assert objects[0].gcode_bounds.min_x_mm == 20 diff --git a/tests/test_submission_api.py b/tests/test_submission_api.py index e2d3a5d..0492abe 100644 --- a/tests/test_submission_api.py +++ b/tests/test_submission_api.py @@ -193,6 +193,22 @@ def test_an_unknown_submission_is_404(client: TestClient) -> None: assert client.get("/submissions/" + "0" * 32).status_code == 404 +def test_object_and_robot_calibration_endpoints(client: TestClient) -> None: + created = _upload(client).json() + assert client.get(f"/submissions/{created['submission_id']}/objects").json() == [] + + calibration = { + "printer_id": "bambu_test_01", + "arm_frame": "robot_base", + "matrix": [1, 0, 0, 100, 0, 1, 0, 200, 0, 0, 1, 10, 0, 0, 0, 1], + } + response = client.post("/printers/bambu_test_01/robot-calibration", json=calibration) + assert response.status_code == 200 + assert response.json()["arm_frame"] == "robot_base" + assert client.get("/printers/bambu_test_01/robot-calibration").status_code == 200 + assert client.get("/events").json() == {"events": [], "next_after": None} + + def test_approval_records_sign_off_and_sets_dispatch_ready(client: TestClient) -> None: created = _upload(client).json() From 622c2e4c1a3445466831049a8a62ce10fd035352 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 01:46:57 +0000 Subject: [PATCH 2/5] Emit failed lifecycle events for dispatch failures Co-authored-by: Yang Cao --- src/bambu_server/dispatch.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/bambu_server/dispatch.py b/src/bambu_server/dispatch.py index ebfecd4..e94ed39 100644 --- a/src/bambu_server/dispatch.py +++ b/src/bambu_server/dispatch.py @@ -526,9 +526,11 @@ async def start_print( upload = await asyncio.to_thread(backend.upload_file, path, remote_name) except PrinterCommandError as exc: control.active_job = None - return await self._store.update_dispatch( + job = await self._store.update_dispatch( job, to_state="failed", note=f"upload failed: {exc}; nothing was started" ) + await self._emit("job.failed", job) + return job job = await self._store.update_dispatch(job, upload_verified_bytes=upload.byte_size) command = StartPrintCommand( @@ -552,9 +554,11 @@ async def start_print( f"start command not confirmed by the broker: {exc}; the file is on the " "printer but no start was confirmed -- check the printer" ) - return await self._store.update_dispatch( + job = await self._store.update_dispatch( job, to_state="failed", note=note, uncertainty=note ) + await self._emit("job.failed", job) + return job job = await self._store.update_dispatch(job, command_published_at=datetime.now(UTC)) return await self._await_running(job, monitor, backend, control) @@ -592,9 +596,11 @@ async def _await_running( f"within {int(self.settings.confirm_timeout_s)} s; its real state is unknown -- " "look at the printer before doing anything else" ) - return await self._store.update_dispatch( + job = await self._store.update_dispatch( job, to_state="failed", note=note, uncertainty=note ) + await self._emit("job.failed", job) + return job async def _watch_running(self, submission_id: str) -> None: job = self._store.get(submission_id) From 63736244f252acf179d57ad9051c627fd3fe4148 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 02:02:49 +0000 Subject: [PATCH 3/5] Keep dispatch running when event delivery fails Co-authored-by: Yang Cao --- src/bambu_server/agent_workflow.py | 9 ++++-- src/bambu_server/dispatch.py | 12 +++++++- tests/test_agent_workflow.py | 23 +++++++++++++++ tests/test_dispatch.py | 46 ++++++++++++++++++++++++++++++ 4 files changed, 86 insertions(+), 4 deletions(-) create mode 100644 tests/test_agent_workflow.py diff --git a/src/bambu_server/agent_workflow.py b/src/bambu_server/agent_workflow.py index dbbf1fe..6b0d71c 100644 --- a/src/bambu_server/agent_workflow.py +++ b/src/bambu_server/agent_workflow.py @@ -114,6 +114,7 @@ def __init__(self, *, webhook_urls: list[str], max_events: int = 1000) -> None: self._events: deque[GatewayEvent] = deque(maxlen=max_events) self._webhook_urls = webhook_urls self._next = 0 + self._deliveries: set[asyncio.Task[None]] = set() def page(self, after: str | None, limit: int) -> EventPage: events = list(self._events) @@ -137,7 +138,9 @@ async def publish( ) self._events.append(event) for url in self._webhook_urls: - asyncio.create_task(self._deliver(url, event)) + task = asyncio.create_task(self._deliver(url, event)) + self._deliveries.add(task) + task.add_done_callback(self._deliveries.discard) return event async def _deliver(self, url: str, event: GatewayEvent) -> None: @@ -150,8 +153,8 @@ def send() -> None: pass try: await asyncio.to_thread(send) - except OSError: - logger.warning("Could not deliver gateway event to configured webhook") + except Exception: + logger.exception("Could not deliver gateway event to configured webhook") def transform_target(position: ObjectPosition, calibration: BedToRobotCalibration) -> PickupTarget: diff --git a/src/bambu_server/dispatch.py b/src/bambu_server/dispatch.py index e94ed39..09eb22d 100644 --- a/src/bambu_server/dispatch.py +++ b/src/bambu_server/dispatch.py @@ -322,8 +322,18 @@ def snapshot_image(self, token: str, *, printer_id: str) -> bytes | None: return snapshot.path.read_bytes() async def _emit(self, event_type: str, job: SubmissionJob) -> None: - if self._event_sink is not None: + """Best-effort notification. A sink failure never changes dispatch.""" + + if self._event_sink is None: + return + try: await self._event_sink(event_type, job) + except Exception: + logger.exception( + "Job event %s for %s was not emitted; dispatch continues", + event_type, + job.submission_id, + ) def _control(self, printer_id: str) -> _PrinterControl: control = self._printers.get(printer_id) diff --git a/tests/test_agent_workflow.py b/tests/test_agent_workflow.py new file mode 100644 index 0000000..e6c58a8 --- /dev/null +++ b/tests/test_agent_workflow.py @@ -0,0 +1,23 @@ +"""Data-only agent workflow behavior. No printer or robot is contacted.""" + +from __future__ import annotations + +import asyncio + +from bambu_server.agent_workflow import EventHub + + +async def test_webhook_delivery_failure_does_not_fail_publication(monkeypatch) -> None: + def fail(*args, **kwargs): + raise RuntimeError("receiver rejected the event") + + monkeypatch.setattr("bambu_server.agent_workflow.urlopen", fail) + hub = EventHub(webhook_urls=["https://events.example/ingest"]) + + event = await hub.publish( + "job.finished", submission_id="a" * 32, printer_id="bambu_test_01" + ) + + await asyncio.gather(*tuple(hub._deliveries)) + assert event.type == "job.finished" + assert [item.submission_id for item in hub.page(None, 10).events] == ["a" * 32] diff --git a/tests/test_dispatch.py b/tests/test_dispatch.py index ee6455a..f6d8ab2 100644 --- a/tests/test_dispatch.py +++ b/tests/test_dispatch.py @@ -558,6 +558,52 @@ def test_verified_identities_are_required_by_default( # -- honest failures ------------------------------------------------------------- +def test_a_failing_event_sink_does_not_skip_the_completion_watcher( + control_client: TestClient, control_backend: FakeBackend, tmp_path: Path, monkeypatch +) -> None: + """Notification is best effort: its failure must not leave a running job unwatched.""" + + async def fail(self, *args, **kwargs): + raise RuntimeError("event bus unavailable") + + monkeypatch.setattr("bambu_server.agent_workflow.EventHub.publish", fail) + job_id = _approved_job(control_client, tmp_path) + headers = {"X-Claim-Token": _claim(control_client)} + response = control_client.post( + f"{BASE}/control/start_print", headers=headers, json=_start_body(job_id) + ) + assert response.status_code == 200, response.text + assert response.json()["state"] == "running" + + control_backend.reading = replace(control_backend.reading, gcode_state="FINISH") + state = "running" + for _ in range(40): + state = control_client.get(f"/submissions/{job_id}").json()["state"] + if state == "finished": + break + time.sleep(0.1) + assert state == "finished" + + +def test_a_failing_event_sink_still_returns_a_failed_dispatch( + control_client: TestClient, control_backend: FakeBackend, tmp_path: Path, monkeypatch +) -> None: + async def fail(self, *args, **kwargs): + raise RuntimeError("event bus unavailable") + + monkeypatch.setattr("bambu_server.agent_workflow.EventHub.publish", fail) + job_id = _approved_job(control_client, tmp_path) + control_backend.fail_upload = True + response = control_client.post( + f"{BASE}/control/start_print", + headers={"X-Claim-Token": _claim(control_client)}, + json=_start_body(job_id), + ) + assert response.status_code == 200, response.text + assert response.json()["state"] == "failed" + assert control_backend.start_commands == [] + + def test_a_failed_upload_starts_nothing( control_client: TestClient, control_backend: FakeBackend, tmp_path: Path ) -> None: From 1cd32f5632e771558cbebe108e3c59c3f19cffa8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 02:40:33 +0000 Subject: [PATCH 4/5] Add durable result bundles, central-ingest outbox and A1 agent mode - Keep terminal jobs and artifacts by default; cancel keeps the artifact unless submissions.cancel_deletes_artifact is set. - Write a schema-versioned result bundle per submission atomically at its terminal state, served by GET /submissions/{id}/result; stream the exact artifact with its sha256 as ETag from GET /submissions/{id}/artifact. - Add an on-disk outbox and worker that POST bundles to the central ingest with a bearer token, follow filing status, back off, and resume after a restart; jobs stay local_only without a project or configured ingest. - Persist event ids across restarts with a gateway.restarted marker, add events for every terminal state and job.cooled, and carry state, updated_at, schema version and gateway id in each event. - Drop robot calibration and the arm-frame transform: object positions are reported in bed coordinates only, preferring the slicer's plate_N.json. - Add admin-controlled agent mode for the Bambu A1 only, with an audited switch and the agent_camera plate check; refuse H2D camera snapshots. Co-authored-by: Yang Cao --- src/bambu_server/agent_mode.py | 216 ++++++++ src/bambu_server/agent_workflow.py | 256 ++++++---- src/bambu_server/artifacts.py | 163 +++++-- src/bambu_server/backend.py | 11 + src/bambu_server/camera.py | 5 + src/bambu_server/config.py | 78 ++- src/bambu_server/dispatch.py | 167 +++++-- src/bambu_server/main.py | 643 +++++++++++++++++++----- src/bambu_server/records.py | 760 +++++++++++++++++++++++++++++ src/bambu_server/submissions.py | 128 +++-- src/bambu_server/vision.py | 5 +- tests/conftest.py | 9 +- tests/test_agent_mode.py | 423 ++++++++++++++++ tests/test_api.py | 10 +- tests/test_artifacts.py | 86 +++- tests/test_records.py | 549 +++++++++++++++++++++ tests/test_submission_api.py | 22 +- tests/test_submissions.py | 61 ++- 18 files changed, 3223 insertions(+), 369 deletions(-) create mode 100644 src/bambu_server/agent_mode.py create mode 100644 src/bambu_server/records.py create mode 100644 tests/test_agent_mode.py create mode 100644 tests/test_records.py diff --git a/src/bambu_server/agent_mode.py b/src/bambu_server/agent_mode.py new file mode 100644 index 0000000..96c8f44 --- /dev/null +++ b/src/bambu_server/agent_mode.py @@ -0,0 +1,216 @@ +"""Agent mode: an admin-controlled switch letting agents run a printer end to end. + +Approved by Yang on 2026-11-02 for the Bambu A1 (``bambu_a1_01``) only. With the +switch on, an agent may submit, approve and start jobs on that printer and +decide for itself, from a claimed camera snapshot, that the plate is empty +(``plate_check_method: agent_camera``). With it off -- the default -- or on any +other printer, agent submissions, approvals and starts are refused, and the +human-in-the-loop path is unchanged. + +Three facts decide it: + +* **eligibility** is static configuration (``agent_mode_eligible`` on the + printer), and the config validator only accepts it on a Bambu A1; +* the **switch** is runtime state persisted under the submissions directory, + flipped only by an edge-verified identity holding an admin role, with every + flip appended to an audit log (who, role, when, reason, previous value); +* an **agent caller** is a request whose edge-verified role is an agent role, or + that declares itself with ``X-Agent-Id``. A verified identity is always + recorded alongside the declared agent id. +""" + +from __future__ import annotations + +import asyncio +import json +import logging +import os +import re +from datetime import UTC, datetime +from pathlib import Path + +from pydantic import BaseModel, Field + +from .identity import Actor + +logger = logging.getLogger(__name__) + +#: Header an agent sends to identify itself (an opaque agent id). +AGENT_HEADER = "X-Agent-Id" + +_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]") +_A1_MODEL_RE = re.compile(r"^(?:bambu(?:\s+lab)?\s+)?a1$", re.IGNORECASE) + + +def model_is_agent_mode_capable(model: str | None) -> bool: + """Only the Bambu A1 is approved for agent mode (not the A1 mini, not others).""" + + return bool(model and _A1_MODEL_RE.match(model.strip())) + + +class AgentCaller(BaseModel): + """Whether a request comes from an agent, and which one.""" + + is_agent: bool = False + agent_id: str | None = None + + +def agent_caller(actor: Actor, headers: object, *, agent_roles: list[str]) -> AgentCaller: + getter = getattr(headers, "get", None) + raw = getter(AGENT_HEADER) if getter else None + declared = _CONTROL_CHARS.sub("", str(raw)).strip()[:120] if raw else "" + by_role = bool(actor.verified and actor.role and actor.role in agent_roles) + if not declared and not by_role: + return AgentCaller() + return AgentCaller(is_agent=True, agent_id=declared or actor.user) + + +class AgentModeState(BaseModel): + printer_id: str + enabled: bool = False + changed_by: str | None = None + changed_by_role: str | None = None + changed_at: datetime | None = None + reason: str | None = None + + +class AgentModeAudit(BaseModel): + printer_id: str + enabled: bool + previous: bool + changed_by: str + changed_by_role: str | None = None + changed_at: datetime + reason: str + + +class AgentModeView(AgentModeState): + eligible: bool + audit: list[AgentModeAudit] = Field(default_factory=list) + + +class AgentModeStore: + """Persisted switch state plus an append-only audit log.""" + + def __init__(self, root: Path) -> None: + self._state_path = root / "agent_mode.json" + self._audit_path = root / "agent_mode_audit.jsonl" + self._states: dict[str, AgentModeState] = {} + self._lock = asyncio.Lock() + + def load(self) -> None: + if not self._state_path.is_file(): + return + try: + payload = json.loads(self._state_path.read_text(encoding="utf-8")) + for value in payload if isinstance(payload, list) else []: + state = AgentModeState.model_validate(value) + self._states[state.printer_id] = state + except (OSError, ValueError): + # Fail closed: an unreadable switch file means every switch is off. + logger.warning("Unreadable agent mode state; agent mode is off everywhere") + self._states = {} + + def get(self, printer_id: str) -> AgentModeState: + return self._states.get(printer_id) or AgentModeState(printer_id=printer_id) + + def audit(self, printer_id: str, limit: int = 20) -> list[AgentModeAudit]: + if not self._audit_path.is_file(): + return [] + entries: list[AgentModeAudit] = [] + with self._audit_path.open("r", encoding="utf-8") as handle: + for line in handle: + try: + entry = AgentModeAudit.model_validate_json(line) + except ValueError: + continue + if entry.printer_id == printer_id: + entries.append(entry) + return entries[-limit:][::-1] + + async def set( + self, printer_id: str, *, enabled: bool, changed_by: str, role: str | None, reason: str + ) -> AgentModeState: + async with self._lock: + previous = self.get(printer_id) + now = datetime.now(UTC) + entry = AgentModeAudit( + printer_id=printer_id, enabled=enabled, previous=previous.enabled, + changed_by=changed_by, changed_by_role=role, changed_at=now, reason=reason, + ) + state = AgentModeState( + printer_id=printer_id, enabled=enabled, changed_by=changed_by, + changed_by_role=role, changed_at=now, reason=reason, + ) + states = {**self._states, printer_id: state} + # The audit line is written first: a flip that is not audited must + # not take effect. + await asyncio.to_thread(self._write, entry, list(states.values())) + self._states = states + logger.info( + "Agent mode on %s set to %s by %s (%s)", + printer_id, "on" if enabled else "off", changed_by, role or "no role", + ) + return state + + def _write(self, entry: AgentModeAudit, states: list[AgentModeState]) -> None: + self._audit_path.parent.mkdir(parents=True, exist_ok=True) + with self._audit_path.open("a", encoding="utf-8") as handle: + handle.write(entry.model_dump_json() + "\n") + handle.flush() + os.fsync(handle.fileno()) + temporary = self._state_path.with_name(f"{self._state_path.name}.tmp") + temporary.write_text( + json.dumps([s.model_dump(mode="json") for s in states], indent=2), encoding="utf-8" + ) + os.replace(temporary, self._state_path) + + +class AgentModeRefusal(Exception): + def __init__(self, status: int, body: dict[str, object]) -> None: + super().__init__(str(body.get("detail"))) + self.status = status + self.body = body + + +class AgentModeGate: + """The one predicate every agent submission, approval and start goes through.""" + + def __init__(self, store: AgentModeStore, eligible: set[str]) -> None: + self.store = store + self.eligible = eligible + + def view(self, printer_id: str) -> AgentModeView: + state = self.store.get(printer_id) + return AgentModeView( + **state.model_dump(), + eligible=printer_id in self.eligible, + audit=self.store.audit(printer_id), + ) + + def summary(self, printer_id: str) -> dict[str, object]: + state = self.store.get(printer_id) + eligible = printer_id in self.eligible + return { + "eligible": eligible, + "enabled": eligible and state.enabled, + "changed_by": state.changed_by, + "changed_at": state.changed_at.isoformat() if state.changed_at else None, + "reason": state.reason, + } + + def require(self, printer_id: str, action: str) -> None: + if printer_id not in self.eligible: + raise AgentModeRefusal(403, { + "detail": f"agent {action} is not available for {printer_id}: agent mode is " + "approved for the Bambu A1 only; a person must do this here", + "agent_mode": "not_eligible", + "printer_id": printer_id, + }) + if not self.store.get(printer_id).enabled: + raise AgentModeRefusal(403, { + "detail": f"agent {action} is refused: agent mode is off for {printer_id}; " + "an admin must switch it on first", + "agent_mode": "off", + "printer_id": printer_id, + }) diff --git a/src/bambu_server/agent_workflow.py b/src/bambu_server/agent_workflow.py index 6b0d71c..824ac2c 100644 --- a/src/bambu_server/agent_workflow.py +++ b/src/bambu_server/agent_workflow.py @@ -1,121 +1,165 @@ """Agent-facing, data-only workflow helpers. -No type in this module reaches a printer or a robot. It persists calibration -and event records locally; callers decide whether to forward events elsewhere. +Nothing here reaches a printer or a robot. Object positions are reported in the +printer's bed frame (millimetres, see :class:`~bambu_server.artifacts.ObjectPosition`); +transforming them into an arm's frame is the arm agent's job, not the gateway's. """ from __future__ import annotations import asyncio -import json import logging +import uuid from collections import deque from datetime import UTC, datetime from pathlib import Path from typing import Literal from urllib.request import Request, urlopen -from pydantic import BaseModel, Field, model_validator +from pydantic import BaseModel, Field from .artifacts import ObjectPosition logger = logging.getLogger(__name__) +#: Version of the event envelope below. Bumped only for incompatible changes; +#: new optional fields do not bump it. +EVENT_SCHEMA_VERSION = 1 -class GatewayEvent(BaseModel): - event_id: str - type: Literal["job.started", "job.finished", "job.failed"] - submission_id: str - printer_id: str - occurred_at: datetime - object_positions: tuple[ObjectPosition, ...] = () +EventType = Literal[ + "job.started", + "job.finished", + "job.failed", + "job.rejected", + "job.cancelled", + "job.cooled", + "gateway.restarted", +] +#: Terminal job state to the event announcing it. +TERMINAL_EVENT_TYPES: dict[str, EventType] = { + "finished": "job.finished", + "failed": "job.failed", + "rejected": "job.rejected", + "cancelled": "job.cancelled", +} -class EventPage(BaseModel): - events: list[GatewayEvent] - next_after: str | None = None +class PickupReadiness(BaseModel): + """Whether a finished plate has cooled enough to be picked up. -class BedToRobotCalibration(BaseModel): - """Rigid 2D placement transform from bed millimetres to arm coordinates.""" + Read from the monitor's cached telemetry. Advice for the arm agent, never a + command to anything. + """ - printer_id: str - arm_frame: str = Field(min_length=1, max_length=120) - # Homogeneous row-major 4x4 matrix. Coordinates are (x, y, z, 1). - matrix: tuple[float, ...] = Field(min_length=16, max_length=16) - updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC)) + bed_temperature_c: float | None = None + safe_bed_temperature_c: float + cooled: bool + observed_at: datetime - @model_validator(mode="after") - def affine_last_row(self) -> BedToRobotCalibration: - if tuple(self.matrix[12:]) != (0.0, 0.0, 0.0, 1.0): - raise ValueError("matrix must be an affine 4x4 transform with last row [0,0,0,1]") - return self +def pickup_readiness(status: object, safe_bed_c: float) -> PickupReadiness: + """Readiness from a cached status envelope; ``cooled`` is False when unknown.""" -class PickupTarget(BaseModel): - object_id: str - name: str | None - arm_frame: str - x: float - y: float - z: float - rotation_deg: float | None = None + metric = (getattr(status, "metrics", None) or {}).get("bed_temperature") + value = getattr(metric, "value", None) + bed = ( + float(value) + if isinstance(value, (int, float)) and not isinstance(value, bool) + else None + ) + return PickupReadiness( + bed_temperature_c=bed, + safe_bed_temperature_c=safe_bed_c, + cooled=bed is not None and bed <= safe_bed_c, + observed_at=datetime.now(UTC), + ) -class PickupPlan(BaseModel): - submission_id: str - printer_id: str - ready: bool - reason: str - bed_temperature_c: float | None = None - safe_bed_temperature_c: float - targets: list[PickupTarget] = Field(default_factory=list) +class GatewayEvent(BaseModel): + """One lifecycle event, as served by ``GET /events`` and POSTed to webhooks. + ``event_id`` is a zero-padded decimal string that keeps increasing across + restarts, so ``after=`` paging survives one; a + ``gateway.restarted`` event with a fresh ``boot_id`` marks each restart. + """ + + schema_version: int = EVENT_SCHEMA_VERSION + event_id: str + type: EventType + occurred_at: datetime + gateway_id: str + boot_id: str + submission_id: str | None = None + printer_id: str | None = None + state: str | None = None + updated_at: datetime | None = None + eln_project: str | None = None + #: True for a ``job.failed`` the gateway recorded at startup because a + #: restart interrupted the job's dispatch. + recovered_after_restart: bool = False + note: str | None = None + #: Bed-frame placements from the sliced file (``job.started``, terminal + #: events and ``job.cooled``). + object_positions: tuple[ObjectPosition, ...] = () + #: Present on ``job.finished`` and ``job.cooled``. + pickup: PickupReadiness | None = None -class CalibrationStore: - def __init__(self, root: Path) -> None: - self._path = root / "bed_to_robot_calibrations.json" - self._values: dict[str, BedToRobotCalibration] = {} - self._lock = asyncio.Lock() - def load(self) -> None: - if not self._path.is_file(): - return - try: - values = json.loads(self._path.read_text(encoding="utf-8")) - self._values = { - value["printer_id"]: BedToRobotCalibration.model_validate(value) - for value in values if isinstance(value, dict) - } - except (OSError, ValueError, json.JSONDecodeError): - logger.warning("Ignoring unreadable robot calibration store") - - def get(self, printer_id: str) -> BedToRobotCalibration | None: - return self._values.get(printer_id) - - async def set(self, calibration: BedToRobotCalibration) -> BedToRobotCalibration: - async with self._lock: - self._values[calibration.printer_id] = calibration - payload = [value.model_dump(mode="json") for value in self._values.values()] - await asyncio.to_thread(self._write, payload) - return calibration - - def _write(self, payload: list[dict[str, object]]) -> None: - self._path.parent.mkdir(parents=True, exist_ok=True) - temporary = self._path.with_suffix(".tmp") - temporary.write_text(json.dumps(payload, indent=2), encoding="utf-8") - temporary.replace(self._path) +class EventPage(BaseModel): + events: list[GatewayEvent] + next_after: str | None = None class EventHub: - """Bounded event feed with best-effort asynchronous JSON webhook delivery.""" - - def __init__(self, *, webhook_urls: list[str], max_events: int = 1000) -> None: + """Durable, bounded event feed with best-effort webhook delivery. + + Events are appended to a JSON-lines log so their ids keep increasing across + restarts; the newest ``max_events`` are served. A failure to persist or + deliver an event is logged and never raised to the caller. + """ + + def __init__( + self, + *, + webhook_urls: list[str], + max_events: int = 1000, + log_path: Path | None = None, + gateway_id: str = "bambu_gateway", + ) -> None: self._events: deque[GatewayEvent] = deque(maxlen=max_events) self._webhook_urls = webhook_urls + self._max_events = max_events + self._log_path = log_path + self._log_lines = 0 self._next = 0 + self.gateway_id = gateway_id + self.boot_id = uuid.uuid4().hex self._deliveries: set[asyncio.Task[None]] = set() + def load(self) -> None: + """Restore recent events and the id counter from the log.""" + + if self._log_path is None or not self._log_path.is_file(): + return + highest = 0 + lines = 0 + try: + with self._log_path.open("r", encoding="utf-8") as handle: + for line in handle: + lines += 1 + try: + event = GatewayEvent.model_validate_json(line) + except ValueError: + continue + self._events.append(event) + if event.event_id.isdigit(): + highest = max(highest, int(event.event_id)) + except OSError: + logger.warning("Could not read the event log; event ids restart from it") + self._next = highest + self._log_lines = lines + def page(self, after: str | None, limit: int) -> EventPage: events = list(self._events) if after: @@ -123,26 +167,46 @@ def page(self, after: str | None, limit: int) -> EventPage: events = events[:limit] return EventPage(events=events, next_after=events[-1].event_id if events else after) - async def publish( - self, event_type: Literal["job.started", "job.finished", "job.failed"], *, - submission_id: str, printer_id: str, object_positions: tuple[ObjectPosition, ...] = (), - ) -> GatewayEvent: + async def publish(self, event_type: EventType, **fields: object) -> GatewayEvent: self._next += 1 event = GatewayEvent( event_id=f"{self._next:020d}", type=event_type, - submission_id=submission_id, - printer_id=printer_id, occurred_at=datetime.now(UTC), - object_positions=object_positions, + gateway_id=self.gateway_id, + boot_id=self.boot_id, + **fields, ) self._events.append(event) + try: + await asyncio.to_thread(self._append, event) + except Exception: + logger.exception("Could not persist event %s", event.event_id) for url in self._webhook_urls: task = asyncio.create_task(self._deliver(url, event)) self._deliveries.add(task) task.add_done_callback(self._deliveries.discard) return event + def _append(self, event: GatewayEvent) -> None: + if self._log_path is None: + return + self._log_path.parent.mkdir(parents=True, exist_ok=True) + with self._log_path.open("a", encoding="utf-8") as handle: + handle.write(event.model_dump_json() + "\n") + self._log_lines += 1 + if self._log_lines > 2 * self._max_events: + self._compact() + + def _compact(self) -> None: + assert self._log_path is not None + temporary = self._log_path.with_suffix(".tmp") + with temporary.open("w", encoding="utf-8") as handle: + for event in self._events: + handle.write(event.model_dump_json() + "\n") + temporary.replace(self._log_path) + self._log_lines = len(self._events) + async def _deliver(self, url: str, event: GatewayEvent) -> None: def send() -> None: request = Request( @@ -157,13 +221,17 @@ def send() -> None: logger.exception("Could not deliver gateway event to configured webhook") -def transform_target(position: ObjectPosition, calibration: BedToRobotCalibration) -> PickupTarget: - m = calibration.matrix - x, y, z = position.center_x_mm, position.center_y_mm, 0.0 - return PickupTarget( - object_id=position.object_id, name=position.name, arm_frame=calibration.arm_frame, - x=round(m[0] * x + m[1] * y + m[2] * z + m[3], 3), - y=round(m[4] * x + m[5] * y + m[6] * z + m[7], 3), - z=round(m[8] * x + m[9] * y + m[10] * z + m[11], 3), - rotation_deg=position.rotation_deg, - ) +class PickupInfo(BaseModel): + """A finished job's objects in bed coordinates, and whether the bed is cool. + + No robot frame: the arm agent applies its own calibration. + """ + + submission_id: str + printer_id: str + state: str + ready: bool + reason: str + bed_size_mm: tuple[float, float] | None = None + pickup: PickupReadiness + objects: list[ObjectPosition] = Field(default_factory=list) diff --git a/src/bambu_server/artifacts.py b/src/bambu_server/artifacts.py index 1edc733..0029707 100644 --- a/src/bambu_server/artifacts.py +++ b/src/bambu_server/artifacts.py @@ -26,6 +26,7 @@ from __future__ import annotations import json +import math import re import zipfile from pathlib import Path @@ -175,7 +176,7 @@ class ArtifactFacts(BaseModel): class ObjectBounds(BaseModel): - """Axis-aligned XY bounds in the printer's bed coordinate system.""" + """Axis-aligned XY bounds in bed coordinates (see :class:`ObjectPosition`).""" min_x_mm: float min_y_mm: float @@ -183,12 +184,25 @@ class ObjectBounds(BaseModel): max_y_mm: float -class ObjectPosition(BaseModel): - """One independently addressable model or labelled toolpath region. +ObjectSource = Literal["slicer_plate_json", "gcode_label", "model_transform"] + - ``gcode_bounds`` is an extrusion-only observation, when the slicer emitted - object labels. It is intentionally a cross-check rather than a replacement - for the model transform: purge lines and travel moves are not object shape. +class ObjectPosition(BaseModel): + """Where one sliced object sits on the build plate. + + Coordinates are the printer's own bed frame, in millimetres, exactly as the + sliced toolpath addresses it: origin at the front-left corner of the + printable area, +X to the right and +Y toward the back as seen from the + front of the printer, Z up from the plate surface. They are not transformed + into any robot frame; the agent driving the arm owns that calibration. + + ``source`` says where the placement came from, best first: + ``slicer_plate_json`` (the slicer's own per-object bounding box for the + plate), ``gcode_label`` (extrusion inside the slicer's object labels), or + ``model_transform`` (3MF build item transform; plate 1 only, because later + plates are offset in the project's layout). ``gcode_bounds`` is the + extrusion-only footprint of the matching G-code label when one exists, as an + independent cross-check: purge lines and travel moves are not counted. """ object_id: str @@ -198,7 +212,7 @@ class ObjectPosition(BaseModel): bounds: ObjectBounds rotation_deg: float | None = None plate_index: int | None = None - source: Literal["model_transform", "gcode_label"] + source: ObjectSource gcode_bounds: ObjectBounds | None = None @@ -772,9 +786,11 @@ def inspect_artifact(path: Path, *, scan_max_bytes: int) -> ArtifactFacts: # -- Per-object placement ------------------------------------------------- _OBJECT_LABEL_RE = re.compile(r"^;\s*(?:OBJECT|MESH|PRINTING_OBJECT)\s*[:=]\s*(.+)$", re.I) -_EXCLUDE_OBJECT_RE = re.compile( - r"^EXCLUDE_OBJECT_DEFINE\s+NAME=([^\s]+).*?CENTER=([-.\d]+),([-.\d]+)", re.I -) +# Bambu Studio brackets each object's toolpath with these comments. +_BAMBU_START_RE = re.compile(r"^;\s*start printing object, unique label id:\s*(\d+)", re.I) +_BAMBU_STOP_RE = re.compile(r"^;\s*stop printing object", re.I) +_EXCLUDE_START_RE = re.compile(r"^EXCLUDE_OBJECT_START\s+NAME=(\S+)", re.I) +_EXCLUDE_END_RE = re.compile(r"^EXCLUDE_OBJECT_END\b", re.I) _E_RE = re.compile(r"(?:^|\s)E(-?\d+(?:\.\d+)?)", re.I) @@ -798,13 +814,23 @@ def _labelled_gcode_positions(data: bytes, *, plate_index: int | None) -> list[O """ points: dict[str, list[tuple[float, float]]] = {} - names: dict[str, str] = {} + names: dict[str, str | None] = {} current: str | None = None x = y = None e = None absolute_e = True for raw in data.decode("latin-1", errors="replace").splitlines(): - label = _OBJECT_LABEL_RE.match(raw.strip()) + line = raw.strip() + if _BAMBU_STOP_RE.match(line) or _EXCLUDE_END_RE.match(line): + current = None + continue + bambu = _BAMBU_START_RE.match(line) + if bambu: + current = bambu.group(1) + points.setdefault(current, []) + names.setdefault(current, None) + continue + label = _OBJECT_LABEL_RE.match(line) or _EXCLUDE_START_RE.match(line) if label: name = label.group(1).strip() if name and name.lower() not in {"noname", "unknown"}: @@ -812,13 +838,6 @@ def _labelled_gcode_positions(data: bytes, *, plate_index: int | None) -> list[O points.setdefault(current, []) names[current] = name continue - defined = _EXCLUDE_OBJECT_RE.match(raw.strip()) - if defined: - name, cx, cy = defined.groups() - current = name - points.setdefault(name, []).append((float(cx), float(cy))) - names[name] = name - continue body = raw.split(";", 1)[0].strip() word = body.split(maxsplit=1)[0].upper() if body else "" if word == "M82": @@ -830,6 +849,7 @@ def _labelled_gcode_positions(data: bytes, *, plate_index: int | None) -> list[O if word not in {"G0", "G1"}: continue values = {axis: float(value) for axis, value in _AXIS_RE.findall(body.upper())} + start_x, start_y = x, y x, y = values.get("X", x), values.get("Y", y) extruder = _E_RE.search(body) is_extruding = False @@ -838,15 +858,19 @@ def _labelled_gcode_positions(data: bytes, *, plate_index: int | None) -> list[O is_extruding = next_e > (e if e is not None else 0.0) if absolute_e else next_e > 0 e = next_e if absolute_e else (e or 0.0) + next_e if current and is_extruding and x is not None and y is not None: + # An extruding move lays plastic along the whole segment, so both + # of its ends belong to the footprint. + if start_x is not None and start_y is not None: + points[current].append((start_x, start_y)) points[current].append((x, y)) result: list[ObjectPosition] = [] - for index, (key, object_points) in enumerate(points.items(), start=1): + for key, object_points in points.items(): bounds = _bounds(object_points) if bounds is None: continue result.append(ObjectPosition( - object_id=f"gcode-{index}", + object_id=key if names.get(key) is None else f"gcode-{key}", name=names.get(key), center_x_mm=round((bounds.min_x_mm + bounds.max_x_mm) / 2, 3), center_y_mm=round((bounds.min_y_mm + bounds.max_y_mm) / 2, 3), @@ -911,7 +935,7 @@ def _model_positions( bounds = _bounds(transformed) if bounds is None: continue - rotation = round(__import__("math").degrees(__import__("math").atan2(b, a)), 3) + rotation = round(math.degrees(math.atan2(b, a)), 3) result.append(ObjectPosition( object_id=f"3mf-{object_id}", name=names.get(object_id), @@ -945,8 +969,72 @@ def _model_setting_plates(data: bytes) -> dict[str, int]: return plates +def _plate_json_positions(data: bytes, *, plate_index: int | None) -> list[ObjectPosition]: + """Read Bambu Studio's ``Metadata/plate_N.json`` per-object bounding boxes. + + The slicer writes these in bed coordinates for the plate it sliced, as + ``bbox_objects: [{"id", "name", "bbox": [min_x, min_y, max_x, max_y]}]``. + """ + + try: + payload = json.loads(data.decode("utf-8", errors="replace")) + except (json.JSONDecodeError, UnicodeDecodeError): + return [] + entries = payload.get("bbox_objects") if isinstance(payload, dict) else None + if not isinstance(entries, list): + return [] + result: list[ObjectPosition] = [] + for index, entry in enumerate(entries, start=1): + if not isinstance(entry, dict): + continue + box = entry.get("bbox") + if not (isinstance(box, list) and len(box) == 4): + continue + try: + min_x, min_y, max_x, max_y = (float(value) for value in box) + except (TypeError, ValueError): + continue + if max_x < min_x or max_y < min_y: + continue + bounds = _bounds([(min_x, min_y), (max_x, max_y)]) + if bounds is None: # pragma: no cover - two points always bound + continue + name = entry.get("name") + raw_id = entry.get("id") + result.append(ObjectPosition( + object_id=str(raw_id) if raw_id is not None else f"plate-object-{index}", + name=str(name) if name else None, + center_x_mm=round((bounds.min_x_mm + bounds.max_x_mm) / 2, 3), + center_y_mm=round((bounds.min_y_mm + bounds.max_y_mm) / 2, 3), + bounds=bounds, + plate_index=plate_index, + source="slicer_plate_json", + )) + return result + + +def _with_gcode_cross_check( + positions: list[ObjectPosition], labelled: list[ObjectPosition] +) -> list[ObjectPosition]: + by_id = {entry.object_id: entry for entry in labelled} + by_name = {entry.name: entry for entry in labelled if entry.name} + checked = [] + for entry in positions: + match = by_id.get(entry.object_id) or (by_name.get(entry.name) if entry.name else None) + checked.append( + entry.model_copy(update={"gcode_bounds": match.bounds}) if match else entry + ) + return checked + + def inspect_object_positions(path: Path, *, scan_max_bytes: int) -> tuple[ObjectPosition, ...]: - """Return object positions from a submitted artifact without printer I/O.""" + """Return object positions, in bed coordinates, from a submitted artifact. + + Reads the stored file only; never contacts a printer. Returns an empty + tuple rather than inventing positions when the file does not say where its + objects are. For a multi-plate 3MF, only the inspected (first sliced) plate + is reported, matching :func:`inspect_artifact`. + """ if path.suffix.lower() == ".gcode": data = path.read_bytes() @@ -959,6 +1047,22 @@ def inspect_object_positions(path: Path, *, scan_max_bytes: int) -> tuple[Object names = archive.namelist() plate_names = sorted(name for name in names if _PLATE_GCODE_RE.match(name)) plate_index = _plate_index(plate_names[0]) if plate_names else None + labelled: list[ObjectPosition] = [] + if plate_names: + gcode = _read_member(archive, plate_names[0], budget=scan_max_bytes) + labelled = _labelled_gcode_positions(gcode or b"", plate_index=plate_index) + + if plate_index is not None: + plate_json = _read_member( + archive, f"Metadata/plate_{plate_index}.json", budget=_MAX_CONFIG_BYTES + ) + positions = _plate_json_positions(plate_json, plate_index=plate_index) if plate_json else [] + if positions: + return tuple(_with_gcode_cross_check(positions, labelled)) + if labelled: + return tuple(labelled) + if plate_index not in (None, 1): + return () model = _read_member(archive, "3D/3dmodel.model", budget=_MAX_CONFIG_BYTES) settings = _read_member(archive, "Metadata/model_settings.config", budget=_MAX_CONFIG_BYTES) positions = ( @@ -969,15 +1073,4 @@ def inspect_object_positions(path: Path, *, scan_max_bytes: int) -> tuple[Object ) if model else [] ) - if plate_names: - gcode = _read_member(archive, plate_names[0], budget=scan_max_bytes) - labelled = _labelled_gcode_positions(gcode or b"", plate_index=plate_index) - by_name = {entry.name: entry for entry in labelled if entry.name} - positions = [ - entry.model_copy(update={"gcode_bounds": by_name[entry.name].bounds}) - if entry.name in by_name else entry - for entry in positions - ] - if not positions: - positions = labelled - return tuple(positions) + return tuple(_with_gcode_cross_check(positions, labelled)) diff --git a/src/bambu_server/backend.py b/src/bambu_server/backend.py index 6a700ea..ba95c26 100644 --- a/src/bambu_server/backend.py +++ b/src/bambu_server/backend.py @@ -31,6 +31,17 @@ #: The printer's chamber-camera service (P1 series: authenticated JPEG frames). _CAMERA_PORT = 6000 +#: Models whose camera is not the port-6000 JPEG service this backend reads. +#: The H2D streams over RTSP instead; snapshots for it are not supported yet. +_UNSUPPORTED_CAMERA_MODELS = frozenset({"h2d"}) + + +def camera_snapshot_supported(model: str | None) -> bool: + """False for a model known not to serve the port-6000 camera protocol.""" + + name = (model or "").strip().lower() + return not any(unsupported in name for unsupported in _UNSUPPORTED_CAMERA_MODELS) + #: Models with no chamber temperature sensor. Their firmware still reports a #: fixed ``chamber_temper`` (5 C on the P1S and A1), which is a placeholder, not #: a reading. Matched exactly against the operator-declared ``model``; an diff --git a/src/bambu_server/camera.py b/src/bambu_server/camera.py index a25260d..5c4908c 100644 --- a/src/bambu_server/camera.py +++ b/src/bambu_server/camera.py @@ -46,8 +46,11 @@ def __init__( *, min_interval_s: float = DEFAULT_MIN_INTERVAL_S, timeout_s: float = 5.0, + unsupported: frozenset[str] = frozenset(), ) -> None: self._backends = backends + #: Printers whose camera protocol is not supported (the H2D); never read. + self._unsupported = unsupported self._min_interval_s = min_interval_s self._timeout_s = timeout_s self._locks: dict[str, asyncio.Lock] = {} @@ -55,6 +58,8 @@ def __init__( self._latest: dict[str, tuple[float, CameraFrame | str]] = {} async def frame(self, printer_id: str) -> CameraFrame: + if printer_id in self._unsupported: + raise CameraUnavailable("this printer's camera is not supported yet") lock = self._locks.setdefault(printer_id, asyncio.Lock()) async with lock: cached = self._latest.get(printer_id) diff --git a/src/bambu_server/config.py b/src/bambu_server/config.py index 76441a7..bddc486 100644 --- a/src/bambu_server/config.py +++ b/src/bambu_server/config.py @@ -117,12 +117,25 @@ class PrinterDefinition(BaseModel): model: str | None = Field(default=None, max_length=120) env_prefix: str = Field(pattern=r"^[A-Z][A-Z0-9_]*$") profile: MachineProfileConfig = Field(default_factory=MachineProfileConfig) + #: Whether an admin may switch agent mode on for this printer at runtime. + #: Approved 2026-11-02 for the Bambu A1 only; refused on any other model. + agent_mode_eligible: bool = False @field_validator("id", "name", "model", "env_prefix", mode="before") @classmethod def strip_text(cls, value: Any) -> Any: return value.strip() if isinstance(value, str) else value + @model_validator(mode="after") + def agent_mode_only_on_a1(self) -> PrinterDefinition: + from .agent_mode import model_is_agent_mode_capable + + if self.agent_mode_eligible and not model_is_agent_mode_capable(self.model): + raise ValueError( + f"agent_mode_eligible is approved for Bambu A1 printers only, not {self.model!r}" + ) + return self + class SubmissionSettings(BaseModel): """Submission intake limits and storage location. @@ -138,10 +151,14 @@ class SubmissionSettings(BaseModel): # enough to trust a motion-derived bounding box, so plate fit is reported # as not applicable rather than computed from a partial scan. scan_max_bytes: int = Field(default=64 * 1024 * 1024, ge=64 * 1024) - #: Age after which a *terminal* job's record is swept at startup. Jobs that - #: are still in play are never swept however old they are: a job stuck in - #: `validating` is a signal, not litter. Set to null to keep everything. - retain_terminal_days: float | None = Field(default=30.0, gt=0) + #: Age after which a *terminal* job's record is swept at startup. Off by + #: default: job records and their artifacts are the lab's print records. + #: Jobs still in play are never swept however old they are. Result bundles + #: under ``results/`` are never swept. + retain_terminal_days: float | None = Field(default=None, gt=0) + #: Delete the stored artifact when a waiting job is cancelled. Off by + #: default so a withdrawn job can still be inspected and downloaded. + cancel_deletes_artifact: bool = False class DispatchSettings(BaseModel): @@ -167,6 +184,13 @@ class DispatchSettings(BaseModel): #: the job in flight before the dispatch is recorded as failed. Covers the #: P1S's file-prepare phase; a bed-leveling pass happens *after* PREPARE. confirm_timeout_s: float = Field(default=180.0, ge=10, le=1800) + #: Edge roles allowed to flip a printer's agent mode switch. + agent_mode_admin_roles: list[str] = Field(default_factory=lambda: ["admin"]) + #: Edge roles whose callers are treated as agents (as is any request with + #: an ``X-Agent-Id`` header). + agent_roles: list[str] = Field(default_factory=lambda: ["agent"]) + #: An ``agent_camera`` decision must rest on a frame at most this old. + agent_snapshot_max_age_s: float = Field(default=120.0, ge=5, le=300) #: Printer-side pre-print steps, forwarded in the start command. bed_leveling: bool = True flow_calibration: bool = False @@ -181,9 +205,12 @@ class AgentWorkflowSettings(BaseModel): #: route. Failed delivery is logged without a body and never affects a job. event_webhook_urls: list[str] = Field(default_factory=list) event_buffer_size: int = Field(default=1000, ge=10, le=10000) - #: Temperature at or below which the pickup endpoint calls a finished bed - #: ready. It is advice for a robot planner, never a robot command. + #: Temperature at or below which a finished bed counts as cooled for + #: pickup. Advice for the arm agent, never a robot command. pickup_safe_bed_c: float = Field(default=45.0, gt=0) + #: How long after ``job.finished`` to keep watching the cached bed + #: temperature for ``job.cooled``. Not resumed after a restart. + cooldown_watch_timeout_s: float = Field(default=4 * 3600.0, ge=1, le=86400) #: Vision remains advisory under the lab safety rules. It cannot satisfy #: the human plate-clear confirmation required by start_print. vision_enabled: bool = False @@ -192,6 +219,27 @@ class AgentWorkflowSettings(BaseModel): empty_bed_reference_directory: Path | None = None +class ResultsSettings(BaseModel): + """Durable result bundles and the optional central-ingest outbox. + + Devices never write to the ELN directly: bundles go only to the central + dashboard's ``/api/ingest/*``, which holds the ELN credentials. Without an + ingest URL and token every job stays ``local_only``. + """ + + #: Identifies this gateway in result bundles and events. + gateway_id: str = Field(default="bambu_gateway", pattern=r"^[a-z][a-z0-9_]*$") + #: Central ingest endpoint, e.g. ``https:///api/ingest/print-results``. + #: ``BAMBU_RESULTS_URL`` overrides it; the bearer token is only ever read + #: from ``BAMBU_RESULTS_TOKEN``. + ingest_url: str | None = Field(default=None, pattern=r"^https?://") + poll_interval_s: float = Field(default=60.0, ge=0.05, le=86400) + retry_initial_s: float = Field(default=10.0, ge=0.05, le=3600) + retry_max_s: float = Field(default=1800.0, ge=0.05, le=86400) + request_timeout_s: float = Field(default=10.0, ge=0.5, le=120) + worker_tick_s: float = Field(default=2.0, ge=0.05, le=60) + + class SlicerSettings(BaseModel): """Bambu Studio CLI slicing of an uploaded ``.stl``. @@ -235,6 +283,7 @@ class Settings(BaseModel): submissions: SubmissionSettings = Field(default_factory=SubmissionSettings) dispatch: DispatchSettings = Field(default_factory=DispatchSettings) agent_workflow: AgentWorkflowSettings = Field(default_factory=AgentWorkflowSettings) + results: ResultsSettings = Field(default_factory=ResultsSettings) slicer: SlicerSettings = Field(default_factory=SlicerSettings) @model_validator(mode="after") @@ -272,6 +321,23 @@ def resolve_edge_secret() -> str | None: return (os.getenv(EDGE_SECRET_ENV) or "").strip() or None +RESULTS_URL_ENV = "BAMBU_RESULTS_URL" +RESULTS_TOKEN_ENV = "BAMBU_RESULTS_TOKEN" + + +def resolve_results_ingest(settings: ResultsSettings) -> tuple[str | None, str | None]: + """The central ingest URL and bearer token, or ``None`` for either. + + The token is a credential and is read from the environment only. + """ + + url = (os.getenv(RESULTS_URL_ENV) or "").strip() or settings.ingest_url + if url and not url.startswith(("http://", "https://")): + raise ValueError(f"{RESULTS_URL_ENV} must be an http(s) URL") + token = (os.getenv(RESULTS_TOKEN_ENV) or "").strip() or None + return (url.rstrip("/") if url else None), token + + def resolve_credentials(printer: PrinterDefinition) -> PrinterCredentials: names = { "host": f"{printer.env_prefix}_HOST", diff --git a/src/bambu_server/dispatch.py b/src/bambu_server/dispatch.py index 09eb22d..f454140 100644 --- a/src/bambu_server/dispatch.py +++ b/src/bambu_server/dispatch.py @@ -26,7 +26,6 @@ import logging import re import secrets -from collections.abc import Awaitable, Callable from dataclasses import dataclass, field from datetime import UTC, datetime, timedelta from pathlib import Path @@ -34,8 +33,14 @@ from pydantic import BaseModel, Field +from .agent_mode import AgentCaller, AgentModeGate, AgentModeRefusal from .artifacts import ArtifactError, ArtifactFacts, inspect_artifact -from .backend import PrinterBackend, PrinterCommandError, StartPrintCommand +from .backend import ( + PrinterBackend, + PrinterCommandError, + StartPrintCommand, + camera_snapshot_supported, +) from .claims import ClaimRegistry from .config import DispatchSettings from .identity import Actor @@ -80,6 +85,8 @@ class StartPrintRequest(BaseModel): snapshot_token: str | None = Field(default=None, max_length=64) ams_mapping: list[TrayAssignment] = Field(min_length=1, max_length=16) dispatched_by: str | None = Field(default=None, min_length=1, max_length=120) + #: Why the deciding agent judged the plate empty (``agent_camera`` only). + plate_check_rationale: str | None = Field(default=None, max_length=1000) class StopPrintRequest(BaseModel): @@ -250,7 +257,7 @@ def __init__( monitors: dict[str, PrinterMonitor], backends: dict[str, PrinterBackend], poll_interval_s: float, - event_sink: Callable[[str, SubmissionJob], Awaitable[None]] | None = None, + agent_mode: AgentModeGate | None = None, ) -> None: self.settings = settings self.gate = ControlGate(settings) @@ -260,7 +267,7 @@ def __init__( self._poll_s = max(0.01, poll_interval_s) self._printers = {printer_id: _PrinterControl() for printer_id in monitors} self._snapshots: dict[str, _Snapshot] = {} - self._event_sink = event_sink + self._agent_mode = agent_mode # -- lifecycle --------------------------------------------------------- @@ -321,20 +328,6 @@ def snapshot_image(self, token: str, *, printer_id: str) -> bytes | None: return None return snapshot.path.read_bytes() - async def _emit(self, event_type: str, job: SubmissionJob) -> None: - """Best-effort notification. A sink failure never changes dispatch.""" - - if self._event_sink is None: - return - try: - await self._event_sink(event_type, job) - except Exception: - logger.exception( - "Job event %s for %s was not emitted; dispatch continues", - event_type, - job.submission_id, - ) - def _control(self, printer_id: str) -> _PrinterControl: control = self._printers.get(printer_id) if control is None: @@ -358,6 +351,16 @@ async def _capture(self, printer_id: str) -> tuple[_Snapshot, bytes]: """Read one frame under the claim the caller already checked, and keep it.""" control = self._control(printer_id) + model = self._monitors[printer_id].definition.model + if not camera_snapshot_supported(model): + raise ControlRefusal( + 501, + { + "detail": f"camera snapshots are not supported for the {model} yet " + "(its camera is not the P1/A1 port-6000 service); check the plate in person", + "camera_supported": False, + }, + ) try: image = await asyncio.to_thread(self._backends[printer_id].snapshot) except PrinterCommandError as exc: @@ -398,11 +401,14 @@ async def start_print( *, actor: Actor, claim_token: str | None, + agent: AgentCaller | None = None, ) -> SubmissionJob: control = self._control(printer_id) self.require_claim(printer_id, claim_token) monitor = self._monitors[printer_id] backend = self._backends[printer_id] + agent = agent or AgentCaller() + self._check_agent_start(printer_id, request, agent) async with control.lock: job = self._store.get(request.submission_id) @@ -508,14 +514,19 @@ async def start_print( }, ) mapping = check_tray_mapping(request.ams_mapping, facts, profile) + # Re-checked under the lock: the switch may have been turned off + # while this request waited. + self._check_agent_start(printer_id, request, agent) plate_check, snapshot_token = await self._plate_check( - request, control=control, printer_id=printer_id, who=who, verified=verified + request, control=control, printer_id=printer_id, who=who, verified=verified, + agent=agent, ) remote_name = remote_filename(job) record = DispatchRecord( dispatched_by=who, dispatched_by_verified=verified, + dispatched_by_agent=agent.agent_id if agent.is_agent else None, requested_at=datetime.now(UTC), plate_check=plate_check, ams_mapping=mapping, @@ -539,7 +550,6 @@ async def start_print( job = await self._store.update_dispatch( job, to_state="failed", note=f"upload failed: {exc}; nothing was started" ) - await self._emit("job.failed", job) return job job = await self._store.update_dispatch(job, upload_verified_bytes=upload.byte_size) @@ -567,7 +577,6 @@ async def start_print( job = await self._store.update_dispatch( job, to_state="failed", note=note, uncertainty=note ) - await self._emit("job.failed", job) return job job = await self._store.update_dispatch(job, command_published_at=datetime.now(UTC)) @@ -597,7 +606,6 @@ async def _await_running( job = await self._store.update_dispatch( job, to_state="running", note=note, observed_running_at=datetime.now(UTC) ) - await self._emit("job.started", job) control.watcher = asyncio.create_task(self._watch_running(job.submission_id)) return job control.active_job = None @@ -609,7 +617,6 @@ async def _await_running( job = await self._store.update_dispatch( job, to_state="failed", note=note, uncertainty=note ) - await self._emit("job.failed", job) return job async def _watch_running(self, submission_id: str) -> None: @@ -634,7 +641,6 @@ async def _watch_running(self, submission_id: str) -> None: note="printer reports the job finished", observed_finished_at=now, ) - await self._emit("job.finished", job) else: note = "printer left the running state without finishing" if gcode_state: @@ -644,7 +650,6 @@ async def _watch_running(self, submission_id: str) -> None: job = await self._store.update_dispatch( job, to_state="failed", note=note, observed_finished_at=now ) - await self._emit("job.failed", job) return except InvalidTransition: logger.exception("Could not record the outcome of %s", submission_id) @@ -722,17 +727,46 @@ async def _plate_check( printer_id: str, who: str, verified: bool, + agent: AgentCaller, ) -> tuple[PlateCheck, str | None]: - """The person's plate confirmation, and the token of the frame recorded with it. + """The plate confirmation, and the token of the frame recorded with it. A camera confirmation with no snapshot token (approved 2026-10-21) has the gateway capture the frame itself, now, under this claim: the person looked at the live camera view, and the record keeps the frame from the moment they pressed start. If the camera cannot deliver one, nothing - starts. + starts. An ``agent_camera`` decision never gets a frame captured for it: + the agent must name the snapshot it actually looked at. """ now = datetime.now(UTC) + if request.plate_check_method == "agent_camera": + if not request.snapshot_token: + raise ControlRefusal( + 412, + { + "detail": "an agent_camera plate check needs the snapshot_token of " + "the frame the agent judged empty", + "snapshot_missing": True, + }, + ) + snap = self._claimed_snapshot( + request.snapshot_token, control=control, printer_id=printer_id, now=now, + max_age_s=self.settings.agent_snapshot_max_age_s, + ) + rationale = (request.plate_check_rationale or "").strip() or None + plate_check = PlateCheck( + confirmed_by=who, + confirmed_by_verified=verified, + method="agent_camera", + confirmed_at=now, + snapshot_sha256=snap.sha256, + snapshot_captured_at=snap.captured_at, + decided_by="agent", + agent_id=agent.agent_id, + rationale=rationale, + ) + return plate_check, snap.token if request.plate_check_method == "in_person": plate_check = PlateCheck( confirmed_by=who, @@ -762,7 +796,32 @@ async def _plate_check( snapshot_captured_at=snap.captured_at, ) return plate_check, snap.token - snap = self._snapshots.get(request.snapshot_token) + snap = self._claimed_snapshot( + request.snapshot_token, control=control, printer_id=printer_id, now=now, + max_age_s=SNAPSHOT_MAX_AGE_S, + ) + plate_check = PlateCheck( + confirmed_by=who, + confirmed_by_verified=verified, + method="printer_camera", + confirmed_at=now, + snapshot_sha256=snap.sha256, + snapshot_captured_at=snap.captured_at, + ) + return plate_check, snap.token + + def _claimed_snapshot( + self, + token: str, + *, + control: _PrinterControl, + printer_id: str, + now: datetime, + max_age_s: float, + ) -> _Snapshot: + """A snapshot of this printer, taken under the current claim, fresh enough.""" + + snap = self._snapshots.get(token) holder = control.claims.holder() if ( snap is None @@ -777,24 +836,54 @@ async def _plate_check( }, ) age = (now - snap.captured_at).total_seconds() - if age > SNAPSHOT_MAX_AGE_S: + if age > max_age_s: raise ControlRefusal( 412, { "detail": "the camera snapshot is too old; take a new one", "snapshot_age_s": round(age, 1), - "snapshot_max_age_s": SNAPSHOT_MAX_AGE_S, + "snapshot_max_age_s": max_age_s, + }, + ) + return snap + + def _check_agent_start( + self, printer_id: str, request: StartPrintRequest, agent: AgentCaller + ) -> None: + """Agents start only in agent mode, and only on their own camera decision. + + The human path is untouched: a person's request is never subject to + agent mode, and only an agent may use ``agent_camera``. + """ + + if not agent.is_agent: + if request.plate_check_method == "agent_camera": + raise ControlRefusal( + 403, + { + "detail": "agent_camera is an agent's plate check; a person confirms " + "the plate in_person or by printer_camera", + "agent_mode": "not_an_agent", + }, + ) + return + if self._agent_mode is None: + raise ControlRefusal( + 403, {"detail": "agent starts are not available", "agent_mode": "not_eligible"} + ) + try: + self._agent_mode.require(printer_id, "start") + except AgentModeRefusal as exc: + raise ControlRefusal(exc.status, exc.body) from exc + if request.plate_check_method != "agent_camera": + raise ControlRefusal( + 412, + { + "detail": "an agent must check the plate itself: use plate_check_method " + "agent_camera with the snapshot_token it judged empty", + "plate_check_method": request.plate_check_method, }, ) - plate_check = PlateCheck( - confirmed_by=who, - confirmed_by_verified=verified, - method="printer_camera", - confirmed_at=now, - snapshot_sha256=snap.sha256, - snapshot_captured_at=snap.captured_at, - ) - return plate_check, snap.token async def _keep_snapshot(self, token: str, job: SubmissionJob) -> None: snap = self._snapshots.pop(token, None) diff --git a/src/bambu_server/main.py b/src/bambu_server/main.py index 8312edb..1a6c354 100644 --- a/src/bambu_server/main.py +++ b/src/bambu_server/main.py @@ -15,6 +15,7 @@ """ import asyncio +import contextlib import hashlib import logging import uuid @@ -23,7 +24,7 @@ from datetime import UTC, datetime from pathlib import Path as PathLib from pathlib import PurePosixPath -from typing import Annotated +from typing import Annotated, Literal from fastapi import ( Depends, @@ -45,16 +46,17 @@ from sdl_lab_contract.claims import ClaimRejection, ClaimRequest, ClaimResponse from . import __version__ -from .agent_workflow import ( - BedToRobotCalibration, - CalibrationStore, - EventHub, - EventPage, - PickupPlan, - transform_target, +from .agent_mode import ( + AgentCaller, + AgentModeGate, + AgentModeRefusal, + AgentModeStore, + AgentModeView, + agent_caller, ) -from .artifacts import ARTIFACT_EXTENSIONS, ObjectPosition, inspect_object_positions -from .backend import BambuLabsBackend, PrinterBackend +from .agent_workflow import EventHub, EventPage, PickupInfo +from .artifacts import ARTIFACT_EXTENSIONS, ObjectPosition +from .backend import BambuLabsBackend, PrinterBackend, camera_snapshot_supported from .camera import CameraUnavailable, CameraViewer from .claims import ClaimConflict, ClaimLost from .config import ( @@ -64,6 +66,7 @@ load_settings, resolve_credentials, resolve_edge_secret, + resolve_results_ingest, ) from .dispatch import ( ControlRefusal, @@ -88,7 +91,22 @@ from .monitor import PrinterMonitor from .profiles import MachineProfile from .queueing import QueueView, build_queue_view +from .records import ( + OUTBOX_STATES, + OutboxConflict, + OutboxEntry, + OutboxStore, + OutboxWorker, + RecordKeeper, + ResultBundle, + ResultStore, + Transport, + urllib_transport, +) from .slicer import BambuStudioSlicer, SliceRequest, SlicerError, SlicerUnavailable +from .submissions import ( + TERMINAL_STATES as TERMINAL_JOB_STATES, +) from .submissions import ( ArtifactTooLarge, InvalidTransition, @@ -97,6 +115,7 @@ SubmissionError, SubmissionJob, SubmissionStore, + clean_text, run_validation, safe_display_name, ) @@ -136,6 +155,30 @@ class ApprovalRequest(BaseModel): #: Optional: ignored when the edge supplies a verified identity, and #: required only when it does not. approved_by: str | None = Field(default=None, min_length=1, max_length=120) + #: Optional ELN project for the finished record; replaces one chosen at + #: submission. Filing happens only through the central server's ingest. + eln_project: str | None = Field(default=None, min_length=1, max_length=120) + + +class IngestRequest(BaseModel): + """Queue a terminal job's record for filing through the central server.""" + + eln_project: str = Field(min_length=1, max_length=120) + #: Ignored when the edge supplies a verified identity. + requested_by: str | None = Field(default=None, min_length=1, max_length=120) + + +class AgentModeRequest(BaseModel): + """An admin's decision to switch agent mode, with the reason for the audit log.""" + + enabled: bool + reason: str = Field(min_length=3, max_length=500) + + +class OutboxView(BaseModel): + ingest_configured: bool + counts: dict[str, int] + entries: list[OutboxEntry] class CancellationRequest(BaseModel): @@ -169,6 +212,7 @@ def create_app( *, settings: Settings | None = None, backend_factory: BackendFactory = BambuLabsBackend, + results_transport: Transport = urllib_transport, ) -> FastAPI: monitors: dict[str, PrinterMonitor] = {} # One-slot holder rather than a module global: `create_app` may be called @@ -195,35 +239,31 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: await asyncio.to_thread(store.load) stores["default"] = store app.state.submissions = store - calibration = CalibrationStore(store.root) - await asyncio.to_thread(calibration.load) + results_settings = active_settings.results hub = EventHub( webhook_urls=active_settings.agent_workflow.event_webhook_urls, max_events=active_settings.agent_workflow.event_buffer_size, + log_path=store.root / "events.jsonl", + gateway_id=results_settings.gateway_id, ) + await asyncio.to_thread(hub.load) + results = ResultStore(store.root) + outbox = OutboxStore(store.root) + await asyncio.to_thread(outbox.load) + ingest_url, ingest_token = resolve_results_ingest(results_settings) + if ingest_url and not ingest_token: + logger.warning( + "A results ingest URL is configured without BAMBU_RESULTS_TOKEN; " + "records stay local_only until the token is set" + ) workflows.update( - calibration=calibration, events=hub, + results=results, + outbox=outbox, detector=ReferenceDigestDetector( active_settings.agent_workflow.empty_bed_reference_directory ), ) - - async def publish_job_event(event_type: str, job: SubmissionJob) -> None: - try: - positions = await asyncio.to_thread( - inspect_object_positions, - store.artifact_path(job), - scan_max_bytes=store.settings.scan_max_bytes, - ) - except (OSError, ValueError): - positions = () - await hub.publish( - event_type, - submission_id=job.submission_id, - printer_id=job.target_machine, - object_positions=positions, - ) backends: dict[str, PrinterBackend] = {} for definition in active_settings.printers: credentials = resolve_credentials(definition) @@ -236,24 +276,73 @@ async def publish_job_event(event_type: str, job: SubmissionJob) -> None: stale_after_seconds=active_settings.stale_after_seconds, ) monitors[definition.id] = monitor + agent_store = AgentModeStore(store.root) + await asyncio.to_thread(agent_store.load) + agent_gate = AgentModeGate( + agent_store, + {p.id for p in active_settings.printers if p.agent_mode_eligible}, + ) + workflows["agent_mode"] = agent_gate dispatcher = Dispatcher( settings=active_settings.dispatch, store=store, monitors=monitors, backends=backends, poll_interval_s=active_settings.poll_interval_seconds, - event_sink=publish_job_event, + agent_mode=agent_gate, ) dispatchers["default"] = dispatcher - cameras["default"] = CameraViewer(backends) + cameras["default"] = CameraViewer( + backends, + unsupported=frozenset( + p.id for p in active_settings.printers if not camera_snapshot_supported(p.model) + ), + ) slicers["default"] = BambuStudioSlicer(active_settings.slicer) + keeper = RecordKeeper( + store=store, + results=results, + outbox=outbox, + events=hub, + monitors=monitors, + gateway_id=results_settings.gateway_id, + gateway_version=__version__, + pickup_safe_bed_c=active_settings.agent_workflow.pickup_safe_bed_c, + ingest_configured=bool(ingest_url and ingest_token), + cooldown_poll_s=active_settings.poll_interval_seconds, + cooldown_timeout_s=active_settings.agent_workflow.cooldown_watch_timeout_s, + ) + workflows["keeper"] = keeper + store.add_listener(keeper.notify) + worker_task: asyncio.Task[None] | None = None try: + await keeper.start() + if ingest_url and ingest_token: + worker = OutboxWorker( + outbox=outbox, + results=results, + url=ingest_url, + token=ingest_token, + gateway_id=results_settings.gateway_id, + poll_interval_s=results_settings.poll_interval_s, + retry_initial_s=results_settings.retry_initial_s, + retry_max_s=results_settings.retry_max_s, + request_timeout_s=results_settings.request_timeout_s, + transport=results_transport, + ) + workflows["worker"] = worker + worker_task = asyncio.create_task(worker.run(results_settings.worker_tick_s)) for monitor in monitors.values(): await monitor.start() if active_settings.dispatch.enabled: await dispatcher.start() yield finally: + if worker_task is not None: + worker_task.cancel() + with contextlib.suppress(asyncio.CancelledError): + await worker_task + await keeper.stop() await dispatcher.stop() for monitor in reversed(list(monitors.values())): await monitor.stop() @@ -270,9 +359,12 @@ async def publish_job_event(event_type: str, job: SubmissionJob) -> None: "Monitoring-only MQTT gateway for Bambu Lab printers. Each configured " "printer is exposed through the AC lab equipment status spec v1.2. " "Profiles expose typed AMS inventory, color-label provenance, and remaining " - "filament estimates. Dispatch can be enabled locally for claimed, human-confirmed " - "starts. Agent workflow routes expose artifact positions, lifecycle events, and " - "robot pickup data only. Use the authenticated /bambu/ " + "filament estimates. Dispatch can be enabled locally for claimed starts after a " + "plate-clear check (a person, or an agent where a printer opts in). Every job " + "keeps a durable, schema-versioned result bundle and its exact artifact; " + "filing to the ELN happens only through the central server's ingest. Agent " + "workflow routes expose bed-frame object positions, lifecycle events and " + "cool-down readiness; they never move a robot. Use the authenticated /bambu/ " "edge path for browser access. No credentials or raw MQTT payloads are exposed." ), docs_url=None, @@ -329,10 +421,42 @@ def get_slicer() -> BambuStudioSlicer: raise HTTPException(status_code=503, detail="slicer unavailable") return slicer - def get_calibration() -> CalibrationStore: - value = workflows.get("calibration") - if not isinstance(value, CalibrationStore): - raise HTTPException(status_code=503, detail="calibration store unavailable") + def get_agent_gate() -> AgentModeGate: + value = workflows.get("agent_mode") + if not isinstance(value, AgentModeGate): # pragma: no cover - outside lifespan + raise HTTPException(status_code=503, detail="agent mode unavailable") + return value + + def get_agent( + request: Request, actor: Annotated[Actor, Depends(get_actor)] + ) -> AgentCaller: + roles = app.state.settings.dispatch.agent_roles + return agent_caller(actor, request.headers, agent_roles=roles) + + def require_agent_mode(printer_id: str, agent: AgentCaller, action: str) -> None: + if not agent.is_agent: + return + try: + get_agent_gate().require(printer_id, action) + except AgentModeRefusal as exc: + raise HTTPException(status_code=exc.status, detail=exc.body) from exc + + def get_keeper() -> RecordKeeper: + value = workflows.get("keeper") + if not isinstance(value, RecordKeeper): # pragma: no cover - outside lifespan + raise HTTPException(status_code=503, detail="record keeper unavailable") + return value + + def get_results() -> ResultStore: + value = workflows.get("results") + if not isinstance(value, ResultStore): # pragma: no cover - outside lifespan + raise HTTPException(status_code=503, detail="result store unavailable") + return value + + def get_outbox() -> OutboxStore: + value = workflows.get("outbox") + if not isinstance(value, OutboxStore): # pragma: no cover - outside lifespan + raise HTTPException(status_code=503, detail="outbox unavailable") return value def get_events() -> EventHub: @@ -406,8 +530,36 @@ async def gateway_status() -> EquipmentStatus: device_time=datetime.now(UTC), components=components, allowed_actions=[], - details={"monitoring_only": not control_enabled, "printer_count": len(monitors)}, + details={ + "monitoring_only": not control_enabled, + "printer_count": len(monitors), + "agent_mode": _agent_mode_summaries(), + **_outbox_details(), + }, + ) + + def _agent_mode_summaries() -> dict[str, object]: + gate = workflows.get("agent_mode") + if not isinstance(gate, AgentModeGate): + return {} + return {printer_id: gate.summary(printer_id) for printer_id in monitors} + + def _outbox_details() -> dict[str, object]: + outbox = workflows.get("outbox") + keeper = workflows.get("keeper") + counts = ( + outbox.counts() if isinstance(outbox, OutboxStore) + else dict.fromkeys(OUTBOX_STATES, 0) ) + return { + "results_ingest_configured": bool( + isinstance(keeper, RecordKeeper) and keeper.ingest_configured + ), + "results_outbox": counts, + "results_pending": counts["pending"] + counts["delivered"], + "results_filing": counts["filing"], + "results_held": counts["held"], + } @app.get("/whoami", response_model=Whoami, tags=["gateway"]) async def whoami(actor: Annotated[Actor, Depends(get_actor)]) -> Whoami: @@ -472,15 +624,22 @@ async def printer_status( With dispatch enabled, ``allowed_actions`` is computed by the same gate the control routes refuse with (STATUS_SPEC §6.2) and ``details.claimed_by`` names the current claim holder. + ``details.agent_mode`` reports whether agent mode is available for this + printer and switched on, and who last flipped it, when and why. """ status = monitor.status() + printer_id = monitor.definition.id + gate = workflows.get("agent_mode") + agent_details = ( + {"agent_mode": gate.summary(printer_id)} if isinstance(gate, AgentModeGate) else {} + ) if not control_enabled: - return status + return status.model_copy(update={"details": {**status.details, **agent_details}}) dispatcher = get_dispatcher() - printer_id = monitor.definition.id holder = dispatcher.claims(printer_id).holder() details = { **status.details, + **agent_details, "monitoring_only": False, "claimed_by": holder.model_dump(mode="json") if holder else None, "build_plate": monitor.definition.profile.plate, @@ -541,27 +700,34 @@ async def create_submission( ), ], actor: Annotated[Actor, Depends(get_actor)], + agent: Annotated[AgentCaller, Depends(get_agent)], target_machine: Annotated[str, Form(max_length=120)], requested_by: Annotated[str | None, Form(max_length=120)] = None, material: Annotated[str | None, Form(max_length=60)] = None, + eln_project: Annotated[str | None, Form(max_length=120)] = None, ) -> SubmissionJob: """Accept a print artifact, validate it, and queue it if it passes. Performs no printer I/O. Validation runs inline so the caller gets the per-check verdict in the response; the file read happens on a worker thread so a large artifact does not stall the status poll loop. + ``eln_project`` optionally names the ELN project the finished record + is filed under, through the central server. An agent (``X-Agent-Id`` or + an agent edge role) may submit only to a printer in agent mode. """ # A verified identity wins over the form field: a signed-in person must # not be able to submit under someone else's name. try: - owner, owner_verified = actor_for(actor, requested_by) + owner, owner_verified = actor_for(actor, requested_by or agent.agent_id) except ValueError as exc: raise HTTPException(status_code=422, detail="requested_by is required") from exc monitor = monitors.get(target_machine) if monitor is None: raise HTTPException(status_code=404, detail="unknown target machine") + require_agent_mode(monitor.definition.id, agent, "submission") + agent_id = agent.agent_id if agent.is_agent else None extension = PurePosixPath(file.filename or "").suffix.lower() if extension == ".stl": @@ -573,6 +739,8 @@ async def create_submission( owner=owner, owner_verified=owner_verified, material=material, + eln_project=eln_project, + agent_id=agent_id, ) kind = ARTIFACT_EXTENSIONS.get(extension) if kind is None: @@ -607,11 +775,15 @@ async def chunks() -> AsyncIterator[bytes]: requested_by_verified=owner_verified, material=material, original_filename=file.filename or "", + eln_project=eln_project, + agent_id=agent_id, ) except ArtifactTooLarge as exc: raise HTTPException(status_code=413, detail=str(exc)) from exc except SubmissionError as exc: raise HTTPException(status_code=400, detail=str(exc)) from exc + except ValueError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc return await run_validation(store, job, monitor.profile()) @@ -624,6 +796,8 @@ async def _slice_and_accept( owner: str, owner_verified: bool, material: str | None, + eln_project: str | None = None, + agent_id: str | None = None, ) -> SubmissionJob: """Slice an uploaded mesh for the target machine, then intake the 3mf. @@ -706,6 +880,8 @@ async def sliced_chunks() -> AsyncIterator[bytes]: material=material, original_filename=f"{PurePosixPath(source_name).stem}.3mf", provenance=provenance, + eln_project=eln_project, + agent_id=agent_id, ) except ArtifactTooLarge as exc: raise HTTPException(status_code=413, detail=str(exc)) from exc @@ -742,8 +918,24 @@ async def list_submissions( machine: Annotated[str | None, Query(max_length=120)] = None, state: Annotated[JobState | None, Query()] = None, limit: Annotated[int, Query(ge=1, le=500)] = 100, + updated_after: Annotated[datetime | None, Query()] = None, + order: Annotated[Literal["submitted", "newest"], Query()] = "submitted", + offset: Annotated[int, Query(ge=0)] = 0, ) -> list[SubmissionJob]: - return store.list(machine=machine, state=state)[:limit] + """List jobs. + + Default order is oldest submission first. ``order=newest`` sorts by most + recent update; with ``updated_after`` and ``offset`` that pages through + changes since a client's last sync. + """ + + jobs = store.list( + machine=machine, + state=state, + updated_after=updated_after, + newest_first=order == "newest", + ) + return jobs[offset:offset + limit] @app.get( "/submissions/{submission_id}", @@ -759,23 +951,105 @@ async def read_submission( raise HTTPException(status_code=404, detail="unknown submission") return job - @app.get("/submissions/{submission_id}/objects", tags=["agent-workflow"]) + @app.get( + "/submissions/{submission_id}/artifact", + response_class=FileResponse, + responses={ + 200: {"description": "The exact stored artifact; ETag is its quoted SHA-256."}, + 304: {"description": "If-None-Match matched the artifact's SHA-256."}, + 410: {"description": "The artifact was deleted (cancel opt-in or retention)."}, + }, + tags=["submissions"], + ) + async def submission_artifact( + request: Request, + store: Annotated[SubmissionStore, Depends(get_store)], + actor: Annotated[Actor, Depends(get_actor)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> Response: + """Download the exact sliced file that was submitted (and printed). + + A read, like every other GET here: access is gated by the lab edge, and + the download is logged with the caller's identity when the edge + verified one. Reads the gateway's own disk only. + """ + + job = store.get(submission_id) + if job is None: + raise HTTPException(status_code=404, detail="unknown submission") + path = store.artifact_path(job) + if job.artifact_removed or not path.is_file(): + raise HTTPException(status_code=410, detail="the artifact is no longer stored") + etag = f'"{job.sha256}"' + if etag in [tag.strip() for tag in request.headers.get("if-none-match", "").split(",")]: + return Response(status_code=304, headers={"ETag": etag}) + logger.info( + "Artifact of %s downloaded by %s%s", + submission_id, + actor.user or "an unidentified caller", + " (verified)" if actor.verified else "", + ) + return FileResponse( + path, + media_type="model/3mf" if job.artifact_kind == "3mf" else "text/x.gcode", + filename=job.original_filename, + headers={"ETag": etag, "X-Content-SHA256": job.sha256}, + ) + + @app.get( + "/submissions/{submission_id}/result", + response_model=ResultBundle, + tags=["submissions"], + ) + async def submission_result( + store: Annotated[SubmissionStore, Depends(get_store)], + results: Annotated[ResultStore, Depends(get_results)], + keeper: Annotated[RecordKeeper, Depends(get_keeper)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> Response: + """The job's schema-versioned result bundle. + + For a terminal job, the bundle written when it reached that state + (``final: true``); it survives even ``DELETE`` of the job record. For a + job still in play, one built now (``final: false``). + """ + + stored = results.read(submission_id) + if stored is not None: + return Response(content=stored, media_type="application/json") + job = store.get(submission_id) + if job is None: + raise HTTPException(status_code=404, detail="unknown submission") + bundle = keeper.bundle( + job, objects=await keeper.positions(job), pickup=None, final=False + ) + return Response(content=bundle.model_dump_json(), media_type="application/json") + + @app.get( + "/submissions/{submission_id}/objects", + response_model=list[ObjectPosition], + tags=["agent-workflow"], + ) async def submission_objects( store: Annotated[SubmissionStore, Depends(get_store)], + keeper: Annotated[RecordKeeper, Depends(get_keeper)], submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], ) -> list[ObjectPosition]: - """Object centres and bounds in bed millimetres.""" + """Where each sliced object sits on the plate, in bed coordinates (mm). + + Origin at the front-left corner of the printable area, +X right, +Y + toward the back seen from the front, as the printer's own toolpath + addresses it; compare with ``bed_size_mm`` from the printer's profile. + No robot frame: the arm agent applies its own calibration. Empty when + the file does not say where its objects are. + """ job = store.get(submission_id) if job is None: raise HTTPException(status_code=404, detail="unknown submission") - try: - return await asyncio.to_thread( - inspect_object_positions, store.artifact_path(job), - scan_max_bytes=store.settings.scan_max_bytes, - ) - except (OSError, ValueError) as exc: - raise HTTPException(status_code=422, detail="object positions unavailable") from exc + if not keeper.artifact_stored(job): + raise HTTPException(status_code=410, detail="the artifact is no longer stored") + return list(await keeper.positions(job)) @app.get("/events", response_model=EventPage, tags=["agent-workflow"]) async def workflow_events( @@ -783,84 +1057,184 @@ async def workflow_events( after: Annotated[str | None, Query(max_length=40)] = None, limit: Annotated[int, Query(ge=1, le=500)] = 100, ) -> EventPage: - """Poll lifecycle events; configured webhooks are delivered independently.""" + """Poll lifecycle events. Ids keep increasing across restarts; a + ``gateway.restarted`` event marks each one. Webhooks get the same events.""" return events.page(after, limit) @app.get( - "/printers/{printer_id}/robot-calibration", - response_model=BedToRobotCalibration, + "/submissions/{submission_id}/pickup-targets", + response_model=PickupInfo, tags=["agent-workflow"], ) - async def get_robot_calibration( - monitor: Annotated[PrinterMonitor, Depends(get_monitor)], - calibration: Annotated[CalibrationStore, Depends(get_calibration)], - ) -> BedToRobotCalibration: - value = calibration.get(monitor.definition.id) - if value is None: - raise HTTPException(status_code=404, detail="no robot calibration configured") - return value + async def pickup_targets( + store: Annotated[SubmissionStore, Depends(get_store)], + keeper: Annotated[RecordKeeper, Depends(get_keeper)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> PickupInfo: + """A finished job's objects in bed coordinates, with cool-down readiness. - @app.post( - "/printers/{printer_id}/robot-calibration", - response_model=BedToRobotCalibration, - tags=["agent-workflow"], - ) - async def set_robot_calibration( - monitor: Annotated[PrinterMonitor, Depends(get_monitor)], - calibration: Annotated[CalibrationStore, Depends(get_calibration)], - request: BedToRobotCalibration, - ) -> BedToRobotCalibration: - """Store only a transform; this endpoint never contacts or moves a robot.""" + Reads the stored artifact and the monitor's cached bed temperature only; + never contacts a printer or a robot. ``ready`` needs a finished job, a + cooled bed and at least one known object position. + """ - if request.printer_id != monitor.definition.id: - raise HTTPException(status_code=422, detail="printer_id must match the URL") - return await calibration.set(request.model_copy(update={"updated_at": datetime.now(UTC)})) + job = store.get(submission_id) + if job is None: + raise HTTPException(status_code=404, detail="unknown submission") + pickup = keeper.readiness(job.target_machine) + if pickup is None: # pragma: no cover - a job's machine is always configured + raise HTTPException(status_code=404, detail="printer not configured") + objects = list(await keeper.positions(job)) + if job.state != "finished": + ready, reason = False, f"the job is {job.state}, not finished" + elif not pickup.cooled: + ready, reason = False, "the bed is not cool enough, or its temperature is unknown" + elif not objects: + ready, reason = False, "the sliced file does not say where its objects are" + else: + ready, reason = True, "finished and cooled" + return PickupInfo( + submission_id=job.submission_id, + printer_id=job.target_machine, + state=job.state, + ready=ready, + reason=reason, + bed_size_mm=keeper.bed_size(job.target_machine), + pickup=pickup, + objects=objects, + ) - @app.get( - "/submissions/{submission_id}/pickup-targets", - response_model=PickupPlan, - tags=["agent-workflow"], + @app.post( + "/submissions/{submission_id}/eln-ingest", + response_model=OutboxEntry, + responses={409: {"description": "Not terminal, already queued, or no ingest configured."}}, + tags=["results"], ) - async def pickup_targets( + async def queue_eln_ingest( store: Annotated[SubmissionStore, Depends(get_store)], - calibration: Annotated[CalibrationStore, Depends(get_calibration)], + outbox: Annotated[OutboxStore, Depends(get_outbox)], + keeper: Annotated[RecordKeeper, Depends(get_keeper)], + actor: Annotated[Actor, Depends(get_actor)], submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], - ) -> PickupPlan: + request: IngestRequest, + ) -> OutboxEntry: + """File a finished job's record later: pick an ELN project and queue it. + + Queues the result bundle in the on-disk outbox for the central server's + ingest, which alone writes to the ELN. A verified identity is recorded + as who queued it. Refused while central ingest is not configured. + """ + job = store.get(submission_id) if job is None: raise HTTPException(status_code=404, detail="unknown submission") - safe = app.state.settings.agent_workflow.pickup_safe_bed_c - if job.state != "finished": - return PickupPlan( - submission_id=job.submission_id, printer_id=job.target_machine, ready=False, - reason="job is not finished", safe_bed_temperature_c=safe, - ) - monitor = monitors[job.target_machine] - metric = monitor.status().metrics.get("bed_temperature") - bed = float(metric.value) if metric and isinstance(metric.value, (int, float)) else None - transform = calibration.get(job.target_machine) - if transform is None: - return PickupPlan( - submission_id=job.submission_id, printer_id=job.target_machine, ready=False, - reason="no robot calibration configured", bed_temperature_c=bed, - safe_bed_temperature_c=safe, + try: + who, verified = actor_for(actor, request.requested_by) + except ValueError as exc: + raise HTTPException(status_code=422, detail="requested_by is required") from exc + project = clean_text(request.eln_project, field="eln_project", required=True) + if not keeper.results_exists(job.submission_id) and job.state in TERMINAL_JOB_STATES: + await keeper.write_final_bundle(job) + try: + return await outbox.queue( + job, + eln_project=project or "", + queued_by=who, + verified=verified, + ingest_configured=keeper.ingest_configured, ) - positions = await asyncio.to_thread( - inspect_object_positions, store.artifact_path(job), - scan_max_bytes=store.settings.scan_max_bytes, + except OutboxConflict as exc: + raise HTTPException(status_code=409, detail=str(exc)) from exc + + @app.get( + "/submissions/{submission_id}/eln-ingest", + response_model=OutboxEntry, + tags=["results"], + ) + async def read_eln_ingest( + outbox: Annotated[OutboxStore, Depends(get_outbox)], + submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], + ) -> OutboxEntry: + entry = outbox.get(submission_id) + if entry is None: + raise HTTPException(status_code=404, detail="no outbox entry for this submission") + return entry + + @app.get("/results/outbox", response_model=OutboxView, tags=["results"]) + async def results_outbox( + outbox: Annotated[OutboxStore, Depends(get_outbox)], + keeper: Annotated[RecordKeeper, Depends(get_keeper)], + state: Annotated[str | None, Query(max_length=20)] = None, + limit: Annotated[int, Query(ge=1, le=500)] = 100, + ) -> OutboxView: + return OutboxView( + ingest_configured=keeper.ingest_configured, + counts=outbox.counts(), + entries=outbox.entries(state)[:limit], ) - cool = bed is not None and bed <= safe - return PickupPlan( - submission_id=job.submission_id, printer_id=job.target_machine, - ready=cool and bool(positions), - reason="ready for robot planning" if cool and positions else ( - "bed temperature is unavailable or above the pickup limit" - if not cool else "no object positions found" - ), - bed_temperature_c=bed, safe_bed_temperature_c=safe, - targets=[transform_target(position, transform) for position in positions], + + @app.get( + "/printers/{printer_id}/agent-mode", + response_model=AgentModeView, + tags=["agent-mode"], + ) + async def read_agent_mode( + monitor: Annotated[PrinterMonitor, Depends(get_monitor)], + gate: Annotated[AgentModeGate, Depends(get_agent_gate)], + ) -> AgentModeView: + """Whether agents may run this printer end to end, with the audit trail.""" + + return gate.view(monitor.definition.id) + + @app.post( + "/printers/{printer_id}/agent-mode", + response_model=AgentModeView, + responses={ + 403: {"description": "Not an edge-verified admin, or the caller is an agent."}, + 409: {"description": "Agent mode is not available for this printer."}, + }, + tags=["agent-mode"], + ) + async def set_agent_mode( + monitor: Annotated[PrinterMonitor, Depends(get_monitor)], + gate: Annotated[AgentModeGate, Depends(get_agent_gate)], + actor: Annotated[Actor, Depends(get_actor)], + agent: Annotated[AgentCaller, Depends(get_agent)], + request: AgentModeRequest, + ) -> AgentModeView: + """Switch agent mode on or off. Edge-verified admins only; always audited. + + Turning it off stops new agent submissions, approvals and starts at + once; a job already printing is not affected. + """ + + admin_roles = app.state.settings.dispatch.agent_mode_admin_roles + if not (actor.verified and actor.user and actor.role in admin_roles): + raise HTTPException( + status_code=403, + detail="only an edge-verified admin can switch agent mode", + ) + if agent.is_agent: + raise HTTPException( + status_code=403, detail="an agent cannot switch agent mode, even as an admin" + ) + printer_id = monitor.definition.id + if printer_id not in gate.eligible: + raise HTTPException( + status_code=409, + detail=f"agent mode is not available for {printer_id}; " + "it is approved for the Bambu A1 only", + ) + reason = clean_text(request.reason, field="reason", required=True) or "" + await gate.store.set( + printer_id, + enabled=request.enabled, + changed_by=actor.user, + role=actor.role, + reason=reason, ) + return gate.view(printer_id) @app.post( "/submissions/{submission_id}/approve", @@ -870,6 +1244,7 @@ async def pickup_targets( async def approve_submission( store: Annotated[SubmissionStore, Depends(get_store)], actor: Annotated[Actor, Depends(get_actor)], + agent: Annotated[AgentCaller, Depends(get_agent)], submission_id: Annotated[str, Path(pattern=r"^[0-9a-f]{32}$")], approval: ApprovalRequest, ) -> SubmissionJob: @@ -877,20 +1252,31 @@ async def approve_submission( This is the approval gate and nothing more: it moves no hardware, starts no print, and reaches no printer. It marks the job ``approved`` and sets - ``verdict.dispatch_ready``, which a future dispatch step would require. + ``verdict.dispatch_ready``, which dispatch requires. An agent may approve + only on a printer in agent mode. ``eln_project`` optionally sets where + the finished record is filed. """ job = store.get(submission_id) if job is None: raise HTTPException(status_code=404, detail="unknown submission") + require_agent_mode(job.target_machine, agent, "approval") try: - who, verified = actor_for(actor, approval.approved_by) + who, verified = actor_for(actor, approval.approved_by or agent.agent_id) except ValueError as exc: raise HTTPException(status_code=422, detail="approved_by is required") from exc try: - return await store.approve(job, approved_by=who, verified=verified) + return await store.approve( + job, + approved_by=who, + verified=verified, + eln_project=approval.eln_project, + agent_id=agent.agent_id if agent.is_agent else None, + ) except InvalidTransition as exc: raise HTTPException(status_code=409, detail=str(exc)) from exc + except SubmissionError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc @app.post( "/submissions/{submission_id}/cancel", @@ -968,7 +1354,7 @@ def get_camera() -> CameraViewer: return camera if control_enabled: - _register_control_routes(app, get_monitor, get_actor, get_dispatcher) + _register_control_routes(app, get_monitor, get_actor, get_dispatcher, get_agent) _register_camera_route(app, get_monitor, get_camera) if settings and settings.agent_workflow.vision_enabled: _register_advisory_bed_check(app, get_monitor, get_dispatcher, workflows) @@ -984,8 +1370,9 @@ def _register_advisory_bed_check( ) -> None: """Assess a previously captured control snapshot without printer I/O. - This route is intentionally advisory. It cannot be passed to - ``start_print`` and does not relax the required human confirmation. + Advisory input only: the result is not itself a plate check. A person + still confirms the plate, or, on a printer in agent mode, the agent makes + its own ``agent_camera`` decision and may use this as one input. """ class BedCheckRequest(BaseModel): @@ -1069,8 +1456,9 @@ def _register_control_routes( get_monitor: Callable[..., PrinterMonitor], get_actor: Callable[..., Actor], get_dispatcher: Callable[[], Dispatcher], + get_agent: Callable[..., AgentCaller], ) -> None: - """STATUS_SPEC §5 claims plus the three control verbs, per printer. + """STATUS_SPEC §5 claims plus the four control verbs, per printer. Only called when the local config enables dispatch, so a deployment that has not opted in exposes no ``/control/`` path at all. @@ -1172,21 +1560,28 @@ async def control_snapshot( async def control_start_print( monitor: Annotated[PrinterMonitor, Depends(get_monitor)], actor: Annotated[Actor, Depends(get_actor)], + agent: Annotated[AgentCaller, Depends(get_agent)], dispatcher: Annotated[Dispatcher, Depends(get_dispatcher)], request: StartPrintRequest, claim_token: Annotated[str | None, Header(alias=CLAIM_HEADER)] = None, ) -> SubmissionJob | JSONResponse: """Upload an approved job to the printer and start it. - Requires the claim, a person's statement that the build plate is - empty, an explicit tray for every filament, and every gate in - :mod:`bambu_server.dispatch`. Returns once the printer reports the job - running, or with the job ``failed`` and the uncertainty recorded. + Requires the claim, a statement that the build plate is empty, an + explicit tray for every filament, and every gate in + :mod:`bambu_server.dispatch`. A person states the plate is empty + (``in_person`` or ``printer_camera``). An agent may start only on a + printer whose agent mode an admin switched on, and must decide itself + from a fresh claimed snapshot: ``plate_check_method: agent_camera`` with + that ``snapshot_token`` and an optional ``plate_check_rationale``. + Returns once the printer reports the job running, or with the job + ``failed`` and the uncertainty recorded. """ try: return await dispatcher.start_print( - monitor.definition.id, request, actor=actor, claim_token=claim_token + monitor.definition.id, request, actor=actor, claim_token=claim_token, + agent=agent, ) except ControlRefusal as exc: return _refusal(exc) diff --git a/src/bambu_server/records.py b/src/bambu_server/records.py new file mode 100644 index 0000000..e034bf6 --- /dev/null +++ b/src/bambu_server/records.py @@ -0,0 +1,760 @@ +"""Durable print records and the optional central-ingest outbox. + +Follows the lab's OT-2 gateway pattern: + +* one schema-versioned **result bundle** per submission at + ``/results/.json``, written atomically (temp file + then ``os.replace``) when the job reaches a terminal state, and never pruned; +* an on-disk **outbox** at ``/outbox/.json`` whose + entries move ``pending -> delivered -> filing -> filed`` (or ``held``, which + needs a person), or sit at ``local_only`` when no ELN project was chosen or no + central ingest is configured; +* a **worker** that POSTs bundles to the central dashboard's ingest URL with a + bearer token and polls ``GET {url}/{device_id}/{submission_id}`` for filing + status, retrying with exponential backoff, and resuming after a restart. + +Devices never write to the ELN directly: the only destination is the central +server's ``/api/ingest/*``, which alone holds ELN credentials. Nothing here +touches a printer, and every failure is logged rather than raised into dispatch +or monitoring. +""" + +from __future__ import annotations + +import asyncio +import json +import logging +import os +from collections.abc import Callable +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from pathlib import Path +from typing import TYPE_CHECKING, Literal +from urllib.error import HTTPError +from urllib.request import Request, urlopen + +from pydantic import BaseModel, Field + +from .agent_workflow import ( + TERMINAL_EVENT_TYPES, + EventHub, + PickupReadiness, + pickup_readiness, +) +from .artifacts import ObjectPosition, inspect_object_positions +from .submissions import ( + TERMINAL_STATES, + PlateCheck, + SubmissionJob, + SubmissionStore, +) + +if TYPE_CHECKING: + from .monitor import PrinterMonitor + +logger = logging.getLogger(__name__) + +RESULT_SCHEMA_ID = "ac.bambu.print_result" +RESULT_SCHEMA_VERSION = 1 +OUTBOX_SCHEMA_VERSION = 1 +INGEST_PAYLOAD_SCHEMA_VERSION = 1 + +#: Largest response body the worker reads from the central server. +_MAX_RESPONSE_BYTES = 1 << 20 + + +# -- result bundle ------------------------------------------------------------- + + +class ArtifactRecord(BaseModel): + kind: str + original_filename: str + byte_size: int + sha256: str + #: Whether the exact file is still stored and downloadable. + stored: bool + download_path: str + + +class Timeline(BaseModel): + submitted_at: datetime + approved_at: datetime | None = None + dispatch_requested_at: datetime | None = None + command_published_at: datetime | None = None + observed_running_at: datetime | None = None + observed_finished_at: datetime | None = None + terminal_at: datetime | None = None + + +class ResultBundle(BaseModel): + """The durable record of one submission, stable for downstream filing. + + ``final`` is True for the bundle written when the job reached a terminal + state; a bundle built on request for a job still in play is not final. + ``objects`` are bed-frame placements from the sliced file and ``pickup`` is + the bed temperature readiness observed when the job finished. + """ + + schema_id: str = RESULT_SCHEMA_ID + schema_version: int = RESULT_SCHEMA_VERSION + gateway_id: str + gateway_version: str + printer_id: str + submission_id: str + state: str + final: bool + generated_at: datetime + eln_project: str | None = None + artifact: ArtifactRecord + timeline: Timeline + plate_check: PlateCheck | None = None + bed_size_mm: tuple[float, float] | None = None + objects: list[ObjectPosition] = Field(default_factory=list) + pickup: PickupReadiness | None = None + job: SubmissionJob + + +def build_bundle( + job: SubmissionJob, + *, + gateway_id: str, + gateway_version: str, + artifact_stored: bool, + objects: tuple[ObjectPosition, ...] | list[ObjectPosition], + pickup: PickupReadiness | None, + bed_size_mm: tuple[float, float] | None, + final: bool, +) -> ResultBundle: + dispatch = job.dispatch + terminal_at = next( + (step.at for step in reversed(job.history) if step.to_state in TERMINAL_STATES), None + ) + return ResultBundle( + gateway_id=gateway_id, + gateway_version=gateway_version, + printer_id=job.target_machine, + submission_id=job.submission_id, + state=job.state, + final=final, + generated_at=datetime.now(UTC), + eln_project=job.eln_project, + artifact=ArtifactRecord( + kind=job.artifact_kind, + original_filename=job.original_filename, + byte_size=job.byte_size, + sha256=job.sha256, + stored=artifact_stored, + download_path=f"/submissions/{job.submission_id}/artifact", + ), + timeline=Timeline( + submitted_at=job.created_at, + approved_at=job.approved_at, + dispatch_requested_at=dispatch.requested_at if dispatch else None, + command_published_at=dispatch.command_published_at if dispatch else None, + observed_running_at=dispatch.observed_running_at if dispatch else None, + observed_finished_at=dispatch.observed_finished_at if dispatch else None, + terminal_at=terminal_at, + ), + plate_check=dispatch.plate_check if dispatch else None, + bed_size_mm=bed_size_mm, + objects=list(objects), + pickup=pickup, + job=job, + ) + + +def _atomic_write(path: Path, payload: str) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + temporary = path.with_name(f"{path.name}.tmp") + temporary.write_text(payload, encoding="utf-8") + os.replace(temporary, path) + + +class ResultStore: + """One bundle file per submission. Never pruned, not even by ``DELETE``.""" + + def __init__(self, root: Path) -> None: + self.root = root / "results" + + def path(self, submission_id: str) -> Path: + return self.root / f"{submission_id}.json" + + def exists(self, submission_id: str) -> bool: + return self.path(submission_id).is_file() + + def read(self, submission_id: str) -> bytes | None: + try: + return self.path(submission_id).read_bytes() + except OSError: + return None + + async def write(self, bundle: ResultBundle) -> None: + await asyncio.to_thread( + _atomic_write, self.path(bundle.submission_id), bundle.model_dump_json(indent=2) + ) + + +# -- outbox ---------------------------------------------------------------------- + +OutboxState = Literal["pending", "delivered", "filing", "filed", "held", "local_only"] +OUTBOX_STATES: tuple[str, ...] = ("pending", "delivered", "filing", "filed", "held", "local_only") +_ACTIVE_STATES = frozenset({"pending", "delivered", "filing"}) + + +class OutboxEntry(BaseModel): + schema_version: int = OUTBOX_SCHEMA_VERSION + submission_id: str + device_id: str + state: OutboxState + eln_project: str | None = None + #: Why the entry is ``local_only``: ``no_eln_project`` or ``ingest_not_configured``. + local_reason: str | None = None + queued_by: str | None = None + queued_by_verified: bool = False + created_at: datetime + updated_at: datetime + #: Consecutive failed attempts; reset by any success. + attempts: int = 0 + next_attempt_at: datetime | None = None + last_error: str | None = None + delivered_at: datetime | None = None + filed_at: datetime | None = None + remote_state: str | None = None + remote_reference: str | None = None + + +class OutboxConflict(RuntimeError): + """An ingest request the outbox will not accept in the entry's state.""" + + +class OutboxStore: + def __init__(self, root: Path) -> None: + self.root = root / "outbox" + self._entries: dict[str, OutboxEntry] = {} + self._lock = asyncio.Lock() + + def load(self) -> None: + self.root.mkdir(parents=True, exist_ok=True) + for path in sorted(self.root.glob("*.json")): + try: + entry = OutboxEntry.model_validate_json(path.read_text(encoding="utf-8")) + except Exception: + logger.warning("Ignoring unreadable outbox entry %s", path.name) + continue + self._entries[entry.submission_id] = entry + + def get(self, submission_id: str) -> OutboxEntry | None: + return self._entries.get(submission_id) + + def entries(self, state: str | None = None) -> list[OutboxEntry]: + found = [e for e in self._entries.values() if state is None or e.state == state] + return sorted(found, key=lambda e: (e.updated_at, e.submission_id), reverse=True) + + def counts(self) -> dict[str, int]: + counts = dict.fromkeys(OUTBOX_STATES, 0) + for entry in self._entries.values(): + counts[entry.state] += 1 + return counts + + def due(self, now: datetime) -> list[OutboxEntry]: + return [ + entry + for entry in self._entries.values() + if entry.state in _ACTIVE_STATES + and (entry.next_attempt_at is None or entry.next_attempt_at <= now) + ] + + async def put(self, entry: OutboxEntry) -> OutboxEntry: + async with self._lock: + await asyncio.to_thread( + _atomic_write, + self.root / f"{entry.submission_id}.json", + entry.model_dump_json(indent=2), + ) + self._entries[entry.submission_id] = entry + return entry + + async def ensure_for_terminal( + self, job: SubmissionJob, *, ingest_configured: bool + ) -> OutboxEntry: + """Create the job's entry once; an existing entry is left as it is.""" + + existing = self._entries.get(job.submission_id) + if existing is not None: + return existing + now = datetime.now(UTC) + if job.eln_project and ingest_configured: + entry = OutboxEntry( + submission_id=job.submission_id, + device_id=job.target_machine, + state="pending", + eln_project=job.eln_project, + queued_by=job.approved_by or job.requested_by, + queued_by_verified=( + job.approved_by_verified if job.approved_by else job.requested_by_verified + ), + created_at=now, + updated_at=now, + next_attempt_at=now, + ) + else: + entry = OutboxEntry( + submission_id=job.submission_id, + device_id=job.target_machine, + state="local_only", + eln_project=job.eln_project, + local_reason="ingest_not_configured" if job.eln_project else "no_eln_project", + created_at=now, + updated_at=now, + ) + return await self.put(entry) + + async def queue( + self, + job: SubmissionJob, + *, + eln_project: str, + queued_by: str, + verified: bool, + ingest_configured: bool, + ) -> OutboxEntry: + """Queue a terminal job for central ingest under a chosen project.""" + + if job.state not in TERMINAL_STATES: + raise OutboxConflict( + f"only a job that has finished going anywhere can be filed; it is {job.state}" + ) + if not ingest_configured: + raise OutboxConflict( + "central ingest is not configured on this gateway; the record stays local_only" + ) + existing = self._entries.get(job.submission_id) + if existing is not None and existing.state in {"pending", "delivered", "filing", "filed"}: + raise OutboxConflict(f"this job's record is already {existing.state}") + now = datetime.now(UTC) + entry = OutboxEntry( + submission_id=job.submission_id, + device_id=job.target_machine, + state="pending", + eln_project=eln_project, + queued_by=queued_by, + queued_by_verified=verified, + created_at=existing.created_at if existing else now, + updated_at=now, + next_attempt_at=now, + ) + return await self.put(entry) + + +# -- worker ---------------------------------------------------------------------- + +#: ``(method, url, headers, body, timeout_s) -> (status, response body)``. +#: Raises ``OSError`` when no HTTP response was received. +Transport = Callable[[str, str, dict[str, str], bytes | None, float], tuple[int, bytes]] + + +def urllib_transport( + method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float +) -> tuple[int, bytes]: + request = Request(url, data=body, method=method, headers=headers) + try: + with urlopen(request, timeout=timeout) as response: # noqa: S310 - operator URL + return response.status, response.read(_MAX_RESPONSE_BYTES) + except HTTPError as exc: + return exc.code, exc.read(_MAX_RESPONSE_BYTES) if exc.fp else b"" + + +def _retryable(status: int) -> bool: + return status in (408, 425, 429) or status >= 500 + + +def _remote_fields(body: bytes) -> tuple[str | None, str | None, str | None]: + """``(state, reference, detail)`` from a central server JSON response.""" + + try: + data = json.loads(body.decode("utf-8", errors="replace")) if body else {} + except (json.JSONDecodeError, UnicodeDecodeError): + return None, None, None + if not isinstance(data, dict): + return None, None, None + state = data.get("state") or data.get("status") + reference = data.get("eln_entry_url") or data.get("reference") or data.get("entry_url") + detail = data.get("detail") or data.get("reason") + return ( + str(state).strip().lower() if state else None, + str(reference)[:500] if reference else None, + str(detail)[:500] if detail else None, + ) + + +class OutboxWorker: + """Delivers pending bundles and follows their filing until a final state.""" + + def __init__( + self, + *, + outbox: OutboxStore, + results: ResultStore, + url: str, + token: str, + gateway_id: str, + poll_interval_s: float, + retry_initial_s: float, + retry_max_s: float, + request_timeout_s: float, + transport: Transport = urllib_transport, + ) -> None: + self._outbox = outbox + self._results = results + self._url = url + self._token = token + self._gateway_id = gateway_id + self._poll_s = poll_interval_s + self._retry_initial_s = retry_initial_s + self._retry_max_s = retry_max_s + self._timeout_s = request_timeout_s + self._transport = transport + + async def run(self, tick_s: float) -> None: + while True: + try: + await self.tick() + except Exception: + logger.exception("Results outbox tick failed; retrying") + await asyncio.sleep(tick_s) + + async def tick(self, now: datetime | None = None) -> None: + for entry in self._outbox.due(now or datetime.now(UTC)): + try: + await self._advance(entry) + except Exception: + logger.exception("Outbox entry %s could not advance", entry.submission_id) + + def _headers(self, *, json_body: bool) -> dict[str, str]: + headers = {"Authorization": f"Bearer {self._token}", "Accept": "application/json"} + if json_body: + headers["Content-Type"] = "application/json" + return headers + + async def _call(self, method: str, url: str, body: bytes | None) -> tuple[int, bytes]: + return await asyncio.to_thread( + self._transport, method, url, self._headers(json_body=body is not None), + body, self._timeout_s, + ) + + async def _advance(self, entry: OutboxEntry) -> None: + if entry.state == "pending": + await self._deliver(entry) + else: + await self._poll(entry) + + async def _deliver(self, entry: OutboxEntry) -> None: + bundle = self._results.read(entry.submission_id) + if bundle is None: + await self._failed(entry, "the result bundle is not on disk yet") + return + payload = { + "schema_version": INGEST_PAYLOAD_SCHEMA_VERSION, + "device_id": entry.device_id, + "gateway_id": self._gateway_id, + "id": entry.submission_id, + "eln_project": entry.eln_project, + "bundle": json.loads(bundle), + } + try: + status, body = await self._call("POST", self._url, json.dumps(payload).encode()) + except OSError as exc: + await self._failed(entry, f"central ingest unreachable ({type(exc).__name__})") + return + if 200 <= status < 300 or status == 409: + now = datetime.now(UTC) + state, reference, detail = _remote_fields(body) + updated = entry.model_copy(update={ + "state": "delivered", "delivered_at": now, "updated_at": now, + "attempts": 0, "last_error": None, "remote_state": state, + "next_attempt_at": now + timedelta(seconds=self._poll_s), + }) + await self._outbox.put(self._apply_remote(updated, state, reference, detail)) + elif _retryable(status): + await self._failed(entry, f"central ingest answered HTTP {status}") + else: + await self._hold(entry, f"central ingest refused the bundle (HTTP {status})") + + async def _poll(self, entry: OutboxEntry) -> None: + url = f"{self._url}/{entry.device_id}/{entry.submission_id}" + try: + status, body = await self._call("GET", url, None) + except OSError as exc: + await self._failed(entry, f"central ingest unreachable ({type(exc).__name__})") + return + now = datetime.now(UTC) + if status == 404: + # The central server has no record of it: deliver it again. + await self._outbox.put(entry.model_copy(update={ + "state": "pending", "updated_at": now, "next_attempt_at": now, + "last_error": "central ingest had no record of the delivered bundle", + })) + return + if _retryable(status): + await self._failed(entry, f"filing status answered HTTP {status}") + return + if not 200 <= status < 300: + await self._hold(entry, f"filing status refused (HTTP {status})") + return + state, reference, detail = _remote_fields(body) + updated = entry.model_copy(update={ + "updated_at": now, "attempts": 0, "last_error": None, + "remote_state": state or entry.remote_state, + "next_attempt_at": now + timedelta(seconds=self._poll_s), + }) + await self._outbox.put(self._apply_remote(updated, state, reference, detail)) + + def _apply_remote( + self, entry: OutboxEntry, state: str | None, reference: str | None, detail: str | None + ) -> OutboxEntry: + update: dict[str, object] = {} + if reference: + update["remote_reference"] = reference + if state == "filing": + update["state"] = "filing" + elif state == "filed": + update.update(state="filed", filed_at=entry.updated_at, next_attempt_at=None) + elif state == "held": + update.update( + state="held", next_attempt_at=None, + last_error=detail or "held by the central server for a person to review", + ) + return entry.model_copy(update=update) if update else entry + + async def _failed(self, entry: OutboxEntry, error: str) -> None: + attempts = entry.attempts + 1 + delay = min(self._retry_max_s, self._retry_initial_s * 2 ** (attempts - 1)) + now = datetime.now(UTC) + logger.warning( + "Outbox entry %s attempt %d failed: %s", entry.submission_id, attempts, error + ) + await self._outbox.put(entry.model_copy(update={ + "attempts": attempts, "last_error": error, "updated_at": now, + "next_attempt_at": now + timedelta(seconds=delay), + })) + + async def _hold(self, entry: OutboxEntry, error: str) -> None: + logger.warning("Outbox entry %s held: %s", entry.submission_id, error) + await self._outbox.put(entry.model_copy(update={ + "state": "held", "last_error": error, "updated_at": datetime.now(UTC), + "next_attempt_at": None, + })) + + +# -- record keeper --------------------------------------------------------------- + + +@dataclass(frozen=True) +class _Work: + job: SubmissionJob + emit: bool + recovered: bool = False + + +class RecordKeeper: + """Turns job state changes into bundles, outbox entries and events. + + The submission store calls :meth:`notify` synchronously after each persisted + transition; the work happens later on this keeper's own task, so neither a + slow artifact read nor a failure here can delay or break dispatch. + """ + + def __init__( + self, + *, + store: SubmissionStore, + results: ResultStore, + outbox: OutboxStore, + events: EventHub, + monitors: dict[str, PrinterMonitor], + gateway_id: str, + gateway_version: str, + pickup_safe_bed_c: float, + ingest_configured: bool, + cooldown_poll_s: float, + cooldown_timeout_s: float, + ) -> None: + self._store = store + self._results = results + self._outbox = outbox + self._events = events + self._monitors = monitors + self._gateway_id = gateway_id + self._gateway_version = gateway_version + self._safe_bed_c = pickup_safe_bed_c + self.ingest_configured = ingest_configured + self._cooldown_poll_s = cooldown_poll_s + self._cooldown_timeout_s = cooldown_timeout_s + self._queue: asyncio.Queue[_Work] = asyncio.Queue() + self._task: asyncio.Task[None] | None = None + self._cooldowns: set[asyncio.Task[None]] = set() + + def notify(self, job: SubmissionJob) -> None: + if job.state == "running" or job.state in TERMINAL_STATES: + self._queue.put_nowait(_Work(job=job, emit=True)) + + async def start(self) -> None: + await self._safe_publish( + "gateway.restarted", note="gateway process started; event ids continue" + ) + recovered = {job.submission_id for job in self._store.recovered} + for job in self._store.recovered: + self._queue.put_nowait(_Work(job=job, emit=True, recovered=True)) + # Terminal jobs from before bundles existed get one, quietly. + for job in self._store.list(): + if ( + job.state in TERMINAL_STATES + and job.submission_id not in recovered + and not self._results.exists(job.submission_id) + ): + self._queue.put_nowait(_Work(job=job, emit=False)) + self._task = asyncio.create_task(self._run()) + + async def stop(self) -> None: + tasks = [t for t in (self._task, *self._cooldowns) if t is not None] + for task in tasks: + task.cancel() + for task in tasks: + try: + await task + except BaseException: # noqa: BLE001 - shutting down + pass + self._task = None + self._cooldowns.clear() + + async def drain(self) -> None: + """Wait until every queued change has been processed (tests, shutdown).""" + + await self._queue.join() + + async def _run(self) -> None: + while True: + work = await self._queue.get() + try: + await self._process(work) + except Exception: + logger.exception("Could not record %s", work.job.submission_id) + finally: + self._queue.task_done() + + # -- helpers used by routes too ------------------------------------------ + + def readiness(self, printer_id: str) -> PickupReadiness | None: + monitor = self._monitors.get(printer_id) + if monitor is None: + return None + return pickup_readiness(monitor.status(), self._safe_bed_c) + + def bed_size(self, printer_id: str) -> tuple[float, float] | None: + monitor = self._monitors.get(printer_id) + return monitor.definition.profile.bed_size_mm if monitor else None + + def artifact_stored(self, job: SubmissionJob) -> bool: + return not job.artifact_removed and self._store.artifact_path(job).is_file() + + async def positions(self, job: SubmissionJob) -> tuple[ObjectPosition, ...]: + if not self.artifact_stored(job): + return () + try: + return await asyncio.to_thread( + inspect_object_positions, + self._store.artifact_path(job), + scan_max_bytes=self._store.settings.scan_max_bytes, + ) + except Exception: + logger.warning("Object positions unavailable for %s", job.submission_id) + return () + + def bundle( + self, + job: SubmissionJob, + *, + objects: tuple[ObjectPosition, ...], + pickup: PickupReadiness | None, + final: bool, + ) -> ResultBundle: + return build_bundle( + job, + gateway_id=self._gateway_id, + gateway_version=self._gateway_version, + artifact_stored=self.artifact_stored(job), + objects=objects, + pickup=pickup, + bed_size_mm=self.bed_size(job.target_machine), + final=final, + ) + + def results_exists(self, submission_id: str) -> bool: + return self._results.exists(submission_id) + + async def write_final_bundle(self, job: SubmissionJob) -> None: + """Write a terminal job's bundle now, if the keeper has not yet.""" + + objects = await self.positions(job) + await self._results.write(self.bundle(job, objects=objects, pickup=None, final=True)) + + # -- processing ---------------------------------------------------------- + + async def _process(self, work: _Work) -> None: + job = work.job + objects = await self.positions(job) + if job.state == "running": + await self._safe_publish("job.started", **self._job_fields(job, objects)) + return + + pickup = self.readiness(job.target_machine) if job.state == "finished" else None + try: + await self._results.write(self.bundle(job, objects=objects, pickup=pickup, final=True)) + except Exception: + logger.exception("Could not write the result bundle for %s", job.submission_id) + try: + await self._outbox.ensure_for_terminal(job, ingest_configured=self.ingest_configured) + except Exception: + logger.exception("Could not create the outbox entry for %s", job.submission_id) + if work.emit: + await self._safe_publish( + TERMINAL_EVENT_TYPES[job.state], + recovered_after_restart=work.recovered, + pickup=pickup, + **self._job_fields(job, objects), + ) + if job.state == "finished" and work.emit and pickup is not None and not pickup.cooled: + task = asyncio.create_task(self._await_cooling(job, objects)) + self._cooldowns.add(task) + task.add_done_callback(self._cooldowns.discard) + + async def _await_cooling(self, job: SubmissionJob, objects: tuple[ObjectPosition, ...]) -> None: + """Announce ``job.cooled`` once the cached bed temperature is safe.""" + + loop = asyncio.get_running_loop() + deadline = loop.time() + self._cooldown_timeout_s + while loop.time() < deadline: + await asyncio.sleep(self._cooldown_poll_s) + pickup = self.readiness(job.target_machine) + if pickup is not None and pickup.cooled: + await self._safe_publish( + "job.cooled", pickup=pickup, **self._job_fields(job, objects) + ) + return + + def _job_fields(self, job: SubmissionJob, objects: tuple[ObjectPosition, ...]) -> dict: + return { + "submission_id": job.submission_id, + "printer_id": job.target_machine, + "state": job.state, + "updated_at": job.updated_at, + "eln_project": job.eln_project, + "note": job.history[-1].note if job.history else None, + "object_positions": objects, + } + + async def _safe_publish(self, event_type: str, **fields: object) -> None: + try: + await self._events.publish(event_type, **fields) # type: ignore[arg-type] + except Exception: + logger.exception("Event %s was not published; the job is unaffected", event_type) diff --git a/src/bambu_server/submissions.py b/src/bambu_server/submissions.py index fe323c6..ae51f4d 100644 --- a/src/bambu_server/submissions.py +++ b/src/bambu_server/submissions.py @@ -23,7 +23,7 @@ import os import re import uuid -from collections.abc import AsyncIterator +from collections.abc import AsyncIterator, Callable from datetime import UTC, datetime, timedelta from pathlib import Path from typing import Literal @@ -93,6 +93,9 @@ _CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]") +#: Called with the job as persisted after each state change. +TransitionListener = Callable[["SubmissionJob"], None] + class SubmissionError(ValueError): """The submission cannot be accepted as presented.""" @@ -195,15 +198,17 @@ def printer_index(self) -> int: return EXTERNAL_SPOOL_ID if self.external else self.ams_id * 4 + self.tray_id -PlateCheckMethod = Literal["printer_camera", "in_person"] +PlateCheckMethod = Literal["printer_camera", "in_person", "agent_camera"] class PlateCheck(BaseModel): - """The human's confirmation that the build plate is empty. + """The confirmation that the build plate is empty. - Recorded, not inferred: the gateway cannot see the plate, so the person - who can says so, and the record keeps how they looked and -- when they - looked through the printer's camera -- which frame they looked at. + Recorded, not inferred by the gateway. A person states it (in person or + from the camera); on a printer in agent mode, an agent may state it from a + claimed snapshot (``agent_camera``, approved 2026-11-02 for the Bambu A1), + and the record names the agent and its rationale. A camera check keeps the + hash of the exact frame the decision rested on. """ confirmed_by: str @@ -213,6 +218,10 @@ class PlateCheck(BaseModel): #: SHA-256 of the camera frame shown during confirmation, when one was. snapshot_sha256: str | None = None snapshot_captured_at: datetime | None = None + decided_by: Literal["person", "agent"] = "person" + #: The deciding agent's id, for an ``agent_camera`` check. + agent_id: str | None = None + rationale: str | None = Field(default=None, max_length=1000) class DispatchRecord(BaseModel): @@ -220,6 +229,8 @@ class DispatchRecord(BaseModel): dispatched_by: str dispatched_by_verified: bool + #: The agent id when an agent started the job in agent mode. + dispatched_by_agent: str | None = None requested_at: datetime plate_check: PlateCheck ams_mapping: list[TrayAssignment] @@ -247,6 +258,8 @@ class SubmissionJob(BaseModel): #: submission from a self-declared one, instead of having to know how the #: service happened to be deployed when it arrived. requested_by_verified: bool = False + #: The agent id when an agent submitted the job (agent mode only). + requested_by_agent: str | None = None material: str | None = Field(default=None, max_length=60) original_filename: str artifact_kind: ArtifactKind @@ -257,7 +270,12 @@ class SubmissionJob(BaseModel): updated_at: datetime approved_by: str | None = None approved_by_verified: bool = False + #: The agent id when an agent approved the job (agent mode only). + approved_by_agent: str | None = None approved_at: datetime | None = None + #: The ELN project the result should be filed under, via the central + #: server's ingest. ``None`` keeps the job's record local only. + eln_project: str | None = Field(default=None, max_length=120) #: True once the stored artifact has been deleted (cancellation). The job #: record outlives its file so the audit trail survives, but nothing can be #: run from it afterwards. @@ -271,7 +289,7 @@ class SubmissionJob(BaseModel): dispatch: DispatchRecord | None = None history: list[StateTransition] = Field(default_factory=list) - @field_validator("requested_by", "material") + @field_validator("requested_by", "material", "eln_project") @classmethod def clean_text(cls, value: str | None) -> str | None: if value is None: @@ -297,6 +315,26 @@ def __init__(self, settings: SubmissionSettings) -> None: self._root = settings.directory self._jobs: dict[str, SubmissionJob] = {} self._lock = asyncio.Lock() + self._listeners: list[TransitionListener] = [] + #: Jobs :meth:`load` failed because a restart interrupted their + #: dispatch, for the record keeper to report once it is running. + self.recovered: list[SubmissionJob] = [] + + def add_listener(self, listener: TransitionListener) -> None: + """Register a synchronous, non-blocking callback for each state change. + + Called after the change is persisted. A listener failure is logged and + never undoes or blocks the transition. + """ + + self._listeners.append(listener) + + def _notify(self, job: SubmissionJob) -> None: + for listener in self._listeners: + try: + listener(job) + except Exception: + logger.exception("Transition listener failed for %s", job.submission_id) @property def root(self) -> Path: @@ -376,6 +414,7 @@ def _recover_interrupted(self) -> int: (self._root / f"{updated.submission_id}.json").write_text( updated.model_dump_json(indent=2), encoding="utf-8" ) + self.recovered.append(updated) count += 1 return count @@ -412,13 +451,22 @@ def list( *, machine: str | None = None, state: str | None = None, + updated_after: datetime | None = None, + newest_first: bool = False, ) -> list[SubmissionJob]: + """Matching jobs, oldest submission first, or most recently updated first.""" + jobs = [ job for job in self._jobs.values() if (machine is None or job.target_machine == machine) and (state is None or job.state == state) + and (updated_after is None or job.updated_at > updated_after) ] + if newest_first: + return sorted( + jobs, key=lambda job: (job.updated_at, job.submission_id), reverse=True + ) return sorted(jobs, key=lambda job: (job.created_at, job.submission_id)) def queue_for(self, machine: str) -> list[SubmissionJob]: @@ -444,6 +492,8 @@ async def accept( material: str | None, original_filename: str, provenance: SliceProvenance | None = None, + eln_project: str | None = None, + agent_id: str | None = None, ) -> SubmissionJob: """Persist an uploaded artifact and register it as a ``submitted`` job.""" @@ -452,6 +502,7 @@ async def accept( raise SubmissionError(f"unsupported artifact extension {extension!r}") owner = clean_text(requested_by, field="requested_by", required=True) filament = clean_text(material, field="material", required=False) + project = clean_text(eln_project, field="eln_project", required=False) self._root.mkdir(parents=True, exist_ok=True) submission_id = uuid.uuid4().hex @@ -488,7 +539,9 @@ async def accept( target_machine=target_machine, requested_by=owner, # type: ignore[arg-type] requested_by_verified=requested_by_verified, + requested_by_agent=agent_id, material=filament, + eln_project=project, original_filename=safe_display_name(original_filename), artifact_kind=kind, byte_size=size, @@ -497,7 +550,10 @@ async def accept( created_at=now, updated_at=now, provenance=provenance, - history=[StateTransition(at=now, from_state=None, to_state="submitted")], + history=[StateTransition( + at=now, from_state=None, to_state="submitted", + note=f"submitted by agent {agent_id}" if agent_id else None, + )], ) async with self._lock: self._jobs[submission_id] = job @@ -533,9 +589,15 @@ async def record_validation( return updated async def approve( - self, job: SubmissionJob, *, approved_by: str, verified: bool = False + self, + job: SubmissionJob, + *, + approved_by: str, + verified: bool = False, + eln_project: str | None = None, + agent_id: str | None = None, ) -> SubmissionJob: - """Record the human sign-off that gates dispatch. + """Record the sign-off that gates dispatch (a person's, or an agent's in agent mode). Approval is a *record*, not an action: it moves no hardware and starts nothing. It flips ``verdict.dispatch_ready``, which is the flag a future @@ -553,21 +615,25 @@ async def approve( raise InvalidTransition( "a submission that did not pass validation cannot be approved" ) + project = clean_text(eln_project, field="eln_project", required=False) now = datetime.now(UTC) verdict = current.verdict.model_copy(update={"dispatch_ready": True}) - updated = current.model_copy( - update={ - "verdict": verdict, - "approved_by": _CONTROL_CHARS.sub("", approved_by).strip()[:120], - "approved_by_verified": verified, - "approved_at": now, - } - ) + update: dict[str, object] = { + "verdict": verdict, + "approved_by": _CONTROL_CHARS.sub("", approved_by).strip()[:120], + "approved_by_verified": verified, + "approved_by_agent": agent_id, + "approved_at": now, + } + if project is not None: + update["eln_project"] = project[:120] + updated = current.model_copy(update=update) self._jobs[updated.submission_id] = updated + agent_note = f" as agent {agent_id}" if agent_id else "" return await self._transition_locked( updated.submission_id, "approved", - f"approved by {updated.approved_by}{_verified_suffix(verified)}", + f"approved by {updated.approved_by}{_verified_suffix(verified)}{agent_note}", ) async def cancel( @@ -585,11 +651,11 @@ async def cancel( is deliberately not offered for a job that has been dispatched -- stopping a running print is a control-plane action that needs a claim. - The stored artifact is deleted, because a withdrawn job has no further - use for it and it is the submitter's data. The job record stays, so the - decision and its reason remain auditable; ``artifact_removed`` marks - that the file is gone. There is no undo -- a withdrawn job is - resubmitted, not revived. + The stored artifact is kept by default, as part of the print record; + ``submissions.cancel_deletes_artifact`` deletes it instead, and + ``artifact_removed`` then marks that the file is gone. The job record + stays either way, so the decision and its reason remain auditable. + There is no undo -- a withdrawn job is resubmitted, not revived. """ async with self._lock: @@ -600,12 +666,12 @@ async def cancel( f"{current.submission_id} is {current.state}" ) - path = self.artifact_path(current) - await asyncio.to_thread(path.unlink, True) - who = clean_text(cancelled_by, field="cancelled_by", required=True) why = clean_text(reason, field="reason", required=False) - update: dict[str, object] = {"artifact_removed": True} + update: dict[str, object] = {} + if self._settings.cancel_deletes_artifact: + await asyncio.to_thread(self.artifact_path(current).unlink, True) + update["artifact_removed"] = True if current.verdict is not None: # An approved job carries dispatch_ready; withdrawing it must # retract that, or the record would still read as cleared to run. @@ -650,8 +716,9 @@ async def begin_dispatch( current.submission_id, "dispatching", f"dispatch requested by {record.dispatched_by}" - f"{_verified_suffix(record.dispatched_by_verified)}; plate confirmed " - f"empty via {record.plate_check.method.replace('_', ' ')}", + f"{_verified_suffix(record.dispatched_by_verified)}" + f"{f' as agent {record.dispatched_by_agent}' if record.dispatched_by_agent else ''}" + f"; plate confirmed empty via {record.plate_check.method.replace('_', ' ')}", ) async def update_dispatch( @@ -738,6 +805,7 @@ async def _transition_locked( ) self._jobs[submission_id] = updated await self._persist(updated) + self._notify(updated) return updated async def _persist(self, job: SubmissionJob) -> None: diff --git a/src/bambu_server/vision.py b/src/bambu_server/vision.py index 5f35728..9983aee 100644 --- a/src/bambu_server/vision.py +++ b/src/bambu_server/vision.py @@ -18,7 +18,10 @@ class BedAssessment(BaseModel): confidence: float detections: list[str] advisory: Literal[True] = True - note: str = "Advisory only; a person must still confirm the plate before start_print." + note: str = ( + "Advisory only; not a plate check. A person confirms the plate, or an agent in " + "agent mode decides itself with plate_check_method agent_camera." + ) class BedDetector(Protocol): diff --git a/tests/conftest.py b/tests/conftest.py index 185ebd4..ffb3644 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -73,6 +73,8 @@ def write_3mf( plate_gcode: str | None = SAMPLE_GCODE, project_settings: dict[str, object] | None = None, slice_info: str | None = SLICE_INFO_XML, + model_xml: str = '', + extra_members: dict[str, str] | None = None, ) -> Path: """Build a minimal Bambu-shaped 3mf container. @@ -95,15 +97,14 @@ def write_3mf( settings.update(project_settings) with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive: - archive.writestr( - "3D/3dmodel.model", - '', - ) + archive.writestr("3D/3dmodel.model", model_xml) archive.writestr("Metadata/project_settings.config", json.dumps(settings)) if slice_info is not None: archive.writestr("Metadata/slice_info.config", slice_info) if plate_gcode is not None: archive.writestr("Metadata/plate_1.gcode", plate_gcode) + for name, body in (extra_members or {}).items(): + archive.writestr(name, body) return path diff --git a/tests/test_agent_mode.py b/tests/test_agent_mode.py new file mode 100644 index 0000000..938e34d --- /dev/null +++ b/tests/test_agent_mode.py @@ -0,0 +1,423 @@ +"""Agent mode: admin-only switch, A1-only scope, refusals, and agent_camera starts. + +Every printer is a :class:`FakeBackend`; nothing here can reach a printer. +""" + +from __future__ import annotations + +import hashlib +from collections.abc import Iterator +from datetime import timedelta +from pathlib import Path + +import pytest +from fastapi.testclient import TestClient +from pydantic import ValidationError + +from bambu_server.config import PrinterDefinition, Settings +from bambu_server.dispatch import Dispatcher +from bambu_server.main import create_app + +from .conftest import SAMPLE_GCODE, FakeBackend, write_3mf + +A1 = "bambu_a1_01" +X1 = "bambu_test_01" +EDGE = "test-edge-secret" + +ADMIN = {"X-Edge-Auth": EDGE, "X-Auth-User": "yang", "X-Auth-Role": "admin"} +OPERATOR = {"X-Edge-Auth": EDGE, "X-Auth-User": "alice", "X-Auth-Role": "operator"} +AGENT = { + "X-Edge-Auth": EDGE, + "X-Auth-User": "svc-print-agent", + "X-Auth-Role": "agent", + "X-Agent-Id": "planner-7", +} + + +def _settings(settings: Settings, monkeypatch, *, first_model: str = "X1 Carbon") -> Settings: + monkeypatch.setenv("BAMBU_EDGE_SHARED_SECRET", EDGE) + for key in ("HOST", "ACCESS_CODE", "SERIAL"): + monkeypatch.setenv(f"BAMBU_A1_01_{key}", "secret") + payload = settings.model_dump(mode="json") + payload["poll_interval_seconds"] = 0.5 + payload["stale_after_seconds"] = 5.0 + first = payload["printers"][0] + first["model"] = first_model + first["profile"]["plate"] = "textured_plate" + a1 = { + **first, + "id": A1, + "name": "Bambu A1 01", + "model": "A1", + "env_prefix": "BAMBU_A1_01", + "agent_mode_eligible": True, + "profile": {**first["profile"], "enclosure": "open"}, + } + payload["printers"].append(a1) + payload["dispatch"] = {"enabled": True, "require_verified_identity": True} + built = Settings.model_validate(payload) + built.dispatch = built.dispatch.model_copy(update={"confirm_timeout_s": 2.0}) + return built + + +@pytest.fixture +def backends(reading) -> dict[str, FakeBackend]: + made = {X1: FakeBackend(reading), A1: FakeBackend(reading)} + for backend in made.values(): + backend.refresh_timestamps = True + return made + + +@pytest.fixture +def dispatchers(monkeypatch) -> list[Dispatcher]: + created: list[Dispatcher] = [] + original = Dispatcher.__init__ + + def capture(self, *args, **kwargs): + original(self, *args, **kwargs) + created.append(self) + + monkeypatch.setattr(Dispatcher, "__init__", capture) + return created + + +@pytest.fixture +def client(settings: Settings, backends, monkeypatch, dispatchers) -> Iterator[TestClient]: + app = create_app( + settings=_settings(settings, monkeypatch), + backend_factory=lambda definition, _c: backends[definition.id], + ) + with TestClient(app) as test_client: + yield test_client + + +def _submit(client: TestClient, tmp_path: Path, printer: str, headers: dict) -> object: + body = SAMPLE_GCODE.replace("X1 Carbon", "A1") if printer == A1 else SAMPLE_GCODE + artifact = write_3mf(tmp_path / f"{printer}-{len(list(tmp_path.iterdir()))}.3mf", + plate_gcode=body) + return client.post( + "/submissions", + files={"file": ("cube.3mf", artifact.read_bytes(), "application/octet-stream")}, + data={"target_machine": printer}, + headers=headers, + ) + + +def _flip(client: TestClient, printer: str, enabled: bool, headers=ADMIN, reason="test run"): + return client.post( + f"/printers/{printer}/agent-mode", + json={"enabled": enabled, "reason": reason}, + headers=headers, + ) + + +def _claim(client: TestClient, printer: str, headers: dict, session: str = "s1") -> str: + response = client.post( + f"/printers/{printer}/control/claim", + json={"owner": "x", "session_id": session}, + headers=headers, + ) + assert response.status_code == 200, response.text + return response.json()["claim_token"] + + +def _agent_start_body(sid: str, **overrides) -> dict: + body = { + "submission_id": sid, + "plate_confirmed_empty": True, + "plate_check_method": "agent_camera", + "ams_mapping": [{"filament_id": 1, "ams_id": 0, "tray_id": 1}], + "plate_check_rationale": "plate matches the empty reference; no residue", + } + body.update(overrides) + return body + + +# -- the switch ------------------------------------------------------------------- + + +def test_only_an_edge_verified_admin_can_flip_agent_mode(client: TestClient) -> None: + assert _flip(client, A1, True, headers={}).status_code == 403 + assert _flip(client, A1, True, headers={"X-Auth-User": "yang", "X-Auth-Role": "admin"} + ).status_code == 403 # forged, no edge secret + assert _flip(client, A1, True, headers=OPERATOR).status_code == 403 + assert _flip(client, A1, True, headers={**ADMIN, "X-Agent-Id": "planner-7"}).status_code == 403 + assert client.get(f"/printers/{A1}/agent-mode").json()["enabled"] is False + assert client.post(f"/printers/{A1}/agent-mode", json={"enabled": True}, + headers=ADMIN).status_code == 422 # a reason is required + + response = _flip(client, A1, True, reason="supervised A1 trial") + assert response.status_code == 200, response.text + view = response.json() + assert view["enabled"] is True + assert view["changed_by"] == "yang" + assert view["reason"] == "supervised A1 trial" + assert view["audit"][0]["changed_by"] == "yang" + assert view["audit"][0]["changed_by_role"] == "admin" + assert view["audit"][0]["previous"] is False + + status = client.get(f"/printers/{A1}/status").json()["details"]["agent_mode"] + assert status["eligible"] is True and status["enabled"] is True + assert status["changed_by"] == "yang" + assert status["changed_at"] + assert status["reason"] == "supervised A1 trial" + gateway = client.get("/status").json()["details"]["agent_mode"] + assert gateway[A1]["enabled"] is True and gateway[X1]["eligible"] is False + + _flip(client, A1, False, reason="trial over") + audit = client.get(f"/printers/{A1}/agent-mode").json()["audit"] + assert [entry["enabled"] for entry in audit] == [False, True] + + +def test_the_switch_and_its_audit_survive_a_restart( + settings: Settings, backends, monkeypatch +) -> None: + built = _settings(settings, monkeypatch) + factory = lambda definition, _c: backends[definition.id] # noqa: E731 + with TestClient(create_app(settings=built, backend_factory=factory)) as client: + _flip(client, A1, True, reason="persist me") + with TestClient(create_app(settings=built, backend_factory=factory)) as client: + view = client.get(f"/printers/{A1}/agent-mode").json() + assert view["enabled"] is True + assert view["audit"][0]["reason"] == "persist me" + + +# -- A1-only scope ----------------------------------------------------------------- + + +def test_agent_mode_cannot_be_switched_on_for_any_other_printer(client: TestClient) -> None: + response = _flip(client, X1, True) + assert response.status_code == 409 + assert "Bambu A1 only" in response.json()["detail"] + assert client.get(f"/printers/{X1}/agent-mode").json()["eligible"] is False + + +@pytest.mark.parametrize("model", ["X1 Carbon", "P1S", "H2D", "A1 mini", None]) +def test_config_accepts_agent_mode_eligibility_on_an_a1_only(model: str | None) -> None: + with pytest.raises(ValidationError, match="Bambu A1"): + PrinterDefinition( + id="p", name="P", model=model, env_prefix="P", agent_mode_eligible=True + ) + PrinterDefinition(id="a", name="A", model="Bambu Lab A1", env_prefix="A", + agent_mode_eligible=True) + + +def test_agents_are_refused_on_other_printers_even_with_the_a1_on( + client: TestClient, tmp_path: Path, backends +) -> None: + _flip(client, A1, True) + + refused = _submit(client, tmp_path, X1, AGENT) + assert refused.status_code == 403 + assert refused.json()["detail"]["agent_mode"] == "not_eligible" + + human = _submit(client, tmp_path, X1, OPERATOR).json() + approve = client.post(f"/submissions/{human['submission_id']}/approve", json={}, + headers=AGENT) + assert approve.status_code == 403 + assert approve.json()["detail"]["agent_mode"] == "not_eligible" + + client.post(f"/submissions/{human['submission_id']}/approve", json={}, headers=OPERATOR) + token = _claim(client, X1, AGENT) + start = client.post( + f"/printers/{X1}/control/start_print", + headers={**AGENT, "X-Claim-Token": token}, + json=_agent_start_body(human["submission_id"], snapshot_token="t"), + ) + assert start.status_code == 403 + assert start.json()["agent_mode"] == "not_eligible" + assert backends[X1].uploads == [] and backends[X1].start_commands == [] + + +# -- refusals with the switch off ------------------------------------------------------ + + +def test_with_the_switch_off_agent_submission_approval_and_start_are_refused( + client: TestClient, tmp_path: Path, backends +) -> None: + refused = _submit(client, tmp_path, A1, AGENT) + assert refused.status_code == 403 + assert refused.json()["detail"]["agent_mode"] == "off" + assert "agent mode is off" in refused.json()["detail"]["detail"] + + human = _submit(client, tmp_path, A1, OPERATOR) + assert human.status_code == 201 + sid = human.json()["submission_id"] + approve = client.post(f"/submissions/{sid}/approve", json={}, headers=AGENT) + assert approve.status_code == 403 + assert approve.json()["detail"]["agent_mode"] == "off" + + client.post(f"/submissions/{sid}/approve", json={}, headers=OPERATOR) + token = _claim(client, A1, AGENT) + snap = client.post(f"/printers/{A1}/control/snapshot", + headers={**AGENT, "X-Claim-Token": token}).json() + start = client.post( + f"/printers/{A1}/control/start_print", + headers={**AGENT, "X-Claim-Token": token}, + json=_agent_start_body(sid, snapshot_token=snap["token"]), + ) + assert start.status_code == 403 + assert start.json()["agent_mode"] == "off" + assert backends[A1].uploads == [] and backends[A1].start_commands == [] + + +def test_the_human_path_is_unchanged_with_the_switch_off( + client: TestClient, tmp_path: Path, backends +) -> None: + sid = _submit(client, tmp_path, A1, OPERATOR).json()["submission_id"] + client.post(f"/submissions/{sid}/approve", json={}, headers=OPERATOR) + token = _claim(client, A1, OPERATOR) + start = client.post( + f"/printers/{A1}/control/start_print", + headers={**OPERATOR, "X-Claim-Token": token}, + json={ + "submission_id": sid, + "plate_confirmed_empty": True, + "plate_check_method": "in_person", + "ams_mapping": [{"filament_id": 1, "ams_id": 0, "tray_id": 1}], + }, + ) + assert start.status_code == 200, start.text + job = start.json() + assert job["state"] == "running" + assert job["dispatch"]["plate_check"]["decided_by"] == "person" + assert job["dispatch"]["dispatched_by_agent"] is None + + +def test_a_person_cannot_use_the_agents_plate_check( + client: TestClient, tmp_path: Path, backends +) -> None: + _flip(client, A1, True) + sid = _submit(client, tmp_path, A1, OPERATOR).json()["submission_id"] + client.post(f"/submissions/{sid}/approve", json={}, headers=OPERATOR) + token = _claim(client, A1, OPERATOR) + start = client.post( + f"/printers/{A1}/control/start_print", + headers={**OPERATOR, "X-Claim-Token": token}, + json=_agent_start_body(sid, snapshot_token="any"), + ) + assert start.status_code == 403 + assert backends[A1].start_commands == [] + + +# -- the agent flow on the A1 ------------------------------------------------------------- + + +def test_an_agent_runs_the_a1_end_to_end_on_its_own_camera_decision( + client: TestClient, tmp_path: Path, backends +) -> None: + _flip(client, A1, True, reason="supervised trial") + + created = _submit(client, tmp_path, A1, AGENT) + assert created.status_code == 201, created.text + job = created.json() + assert job["state"] == "queued" + assert job["requested_by"] == "svc-print-agent" + assert job["requested_by_verified"] is True + assert job["requested_by_agent"] == "planner-7" + sid = job["submission_id"] + + approved = client.post(f"/submissions/{sid}/approve", json={}, headers=AGENT).json() + assert approved["state"] == "approved" + assert approved["approved_by_agent"] == "planner-7" + + headers = {**AGENT, "X-Claim-Token": _claim(client, A1, AGENT)} + snap = client.post(f"/printers/{A1}/control/snapshot", headers=headers) + assert snap.status_code == 200, snap.text + snapshot = snap.json() + assert snapshot["image_base64"] and snapshot["token"] + + start = client.post( + f"/printers/{A1}/control/start_print", + headers=headers, + json=_agent_start_body(sid, snapshot_token=snapshot["token"]), + ) + assert start.status_code == 200, start.text + record = start.json()["dispatch"] + assert start.json()["state"] == "running" + check = record["plate_check"] + assert check["method"] == "agent_camera" + assert check["decided_by"] == "agent" + assert check["agent_id"] == "planner-7" + assert check["confirmed_by"] == "svc-print-agent" + assert check["rationale"] == "plate matches the empty reference; no residue" + assert check["snapshot_sha256"] == snapshot["sha256"] + assert record["dispatched_by_agent"] == "planner-7" + assert len(backends[A1].start_commands) == 1 + + evidence = client.get(f"/submissions/{sid}/plate.jpg") + assert evidence.status_code == 200 + assert hashlib.sha256(evidence.content).hexdigest() == snapshot["sha256"] + + +def test_an_agent_must_decide_from_a_fresh_snapshot_under_its_claim( + client: TestClient, tmp_path: Path, backends, dispatchers +) -> None: + _flip(client, A1, True) + sid = _submit(client, tmp_path, A1, AGENT).json()["submission_id"] + client.post(f"/submissions/{sid}/approve", json={}, headers=AGENT) + headers = {**AGENT, "X-Claim-Token": _claim(client, A1, AGENT)} + url = f"/printers/{A1}/control/start_print" + + in_person = client.post(url, headers=headers, + json=_agent_start_body(sid, plate_check_method="in_person")) + assert in_person.status_code == 412 + assert "agent_camera" in in_person.json()["detail"] + + no_token = client.post(url, headers=headers, json=_agent_start_body(sid)) + assert no_token.status_code == 412 + assert no_token.json()["snapshot_missing"] is True + + snap = client.post(f"/printers/{A1}/control/snapshot", headers=headers).json() + dispatcher = dispatchers[0] + dispatcher._snapshots[snap["token"]].captured_at -= timedelta(seconds=121) + stale = client.post(url, headers=headers, + json=_agent_start_body(sid, snapshot_token=snap["token"])) + assert stale.status_code == 412 + assert stale.json()["snapshot_max_age_s"] == 120.0 + + other = client.post(f"/printers/{X1}/control/claim", + json={"owner": "x", "session_id": "s9"}, headers=OPERATOR).json() + x1_snap = client.post(f"/printers/{X1}/control/snapshot", + headers={**OPERATOR, "X-Claim-Token": other["claim_token"]}).json() + wrong_printer = client.post(url, headers=headers, + json=_agent_start_body(sid, snapshot_token=x1_snap["token"])) + assert wrong_printer.status_code == 412 + assert backends[A1].start_commands == [] + + +def test_switching_agent_mode_off_refuses_the_next_agent_start( + client: TestClient, tmp_path: Path, backends +) -> None: + _flip(client, A1, True) + sid = _submit(client, tmp_path, A1, AGENT).json()["submission_id"] + client.post(f"/submissions/{sid}/approve", json={}, headers=AGENT) + headers = {**AGENT, "X-Claim-Token": _claim(client, A1, AGENT)} + snap = client.post(f"/printers/{A1}/control/snapshot", headers=headers).json() + + _flip(client, A1, False, reason="stop agents") + start = client.post( + f"/printers/{A1}/control/start_print", headers=headers, + json=_agent_start_body(sid, snapshot_token=snap["token"]), + ) + assert start.status_code == 403 + assert start.json()["agent_mode"] == "off" + assert backends[A1].uploads == [] + + +# -- H2D camera ----------------------------------------------------------------------------- + + +def test_h2d_camera_snapshots_are_refused_explicitly( + settings: Settings, backends, monkeypatch +) -> None: + built = _settings(settings, monkeypatch, first_model="H2D") + app = create_app(settings=built, backend_factory=lambda d, _c: backends[d.id]) + with TestClient(app) as client: + token = _claim(client, X1, OPERATOR) + response = client.post(f"/printers/{X1}/control/snapshot", + headers={**OPERATOR, "X-Claim-Token": token}) + assert response.status_code == 501 + assert "not supported" in response.json()["detail"] + assert client.get(f"/printers/{X1}/camera.jpg").status_code == 503 + assert backends[X1].snapshots == 0 diff --git a/tests/test_api.py b/tests/test_api.py index b769887..f929a78 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -68,10 +68,12 @@ def test_gateway_status_summarizes_printer_monitoring(client: TestClient) -> Non assert body["allowed_actions"] == [] assert body["components"]["bambu_test_01"]["connected"] is True assert body["components"]["bambu_test_01"]["state"] == "ready" - assert body["details"] == { - "monitoring_only": True, - "printer_count": 1, - } + details = body["details"] + assert details["monitoring_only"] is True + assert details["printer_count"] == 1 + assert details["agent_mode"]["bambu_test_01"]["enabled"] is False + assert details["results_ingest_configured"] is False + assert details["results_pending"] == 0 and details["results_filing"] == 0 def test_ready_status_is_cached_and_contains_no_secrets( diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py index cb91267..f2a1553 100644 --- a/tests/test_artifacts.py +++ b/tests/test_artifacts.py @@ -2,6 +2,7 @@ from __future__ import annotations +import json import zipfile from pathlib import Path @@ -218,25 +219,76 @@ def test_unsupported_extension_is_an_error(tmp_path: Path) -> None: _inspect(path) -def test_3mf_model_transform_positions_are_reported_and_cross_checked(tmp_path: Path) -> None: - path = write_3mf(tmp_path / "objects.3mf", plate_gcode=( - SAMPLE_GCODE - + "; OBJECT: widget\nG1 X20 Y30 E10\nG1 X40 Y50 E12\n" - )) - model = """ - - - - """ - with zipfile.ZipFile(path, "a") as archive: - archive.writestr("3D/3dmodel.model", model) +WIDGET_MODEL = """ + + + +""" + +# Bambu Studio brackets each object's toolpath with unique label ids. +BAMBU_LABELLED = SAMPLE_GCODE + ( + "; start printing object, unique label id: 101\n" + "G1 X20 Y30 F600\nG1 X40 Y50 E10\n" + "; stop printing object, unique label id: 101\n" + "G1 X200 Y200 F9000\n" # travel between objects is not part of either + "; start printing object, unique label id: 102\n" + "G1 X100 Y100 F600\nG1 X120 Y110 E12\n" + "; stop printing object, unique label id: 102\n" +) + + +def test_slicer_plate_json_gives_bed_positions_cross_checked_by_gcode(tmp_path: Path) -> None: + plate_json = json.dumps({"bbox_objects": [ + {"id": 101, "name": "bracket", "bbox": [18.0, 28.0, 42.0, 52.0]}, + {"id": 102, "name": "clip", "bbox": [98.0, 98.0, 122.0, 112.0]}, + ]}) + path = write_3mf( + tmp_path / "plate.3mf", + plate_gcode=BAMBU_LABELLED, + extra_members={"Metadata/plate_1.json": plate_json}, + ) + + objects = inspect_object_positions(path, scan_max_bytes=SCAN_BUDGET) + + assert [o.name for o in objects] == ["bracket", "clip"] + bracket = objects[0] + assert bracket.source == "slicer_plate_json" + assert bracket.plate_index == 1 + assert (bracket.center_x_mm, bracket.center_y_mm) == (30.0, 40.0) + assert bracket.bounds.max_x_mm == 42.0 + # The extrusion inside label 101 only, not the travel move to X200. + assert bracket.gcode_bounds is not None + assert (bracket.gcode_bounds.min_x_mm, bracket.gcode_bounds.max_x_mm) == (20.0, 40.0) + assert objects[1].gcode_bounds.max_y_mm == 110.0 + + +def test_bambu_gcode_labels_are_used_without_plate_json(tmp_path: Path) -> None: + path = write_3mf(tmp_path / "plate.3mf", plate_gcode=BAMBU_LABELLED) + + objects = inspect_object_positions(path, scan_max_bytes=SCAN_BUDGET) + + assert [(o.object_id, o.source) for o in objects] == [ + ("101", "gcode_label"), ("102", "gcode_label"), + ] + assert objects[0].bounds.max_x_mm == 40.0 # no travel to X200 + + +def test_model_transform_is_the_last_resort_on_plate_one(tmp_path: Path) -> None: + path = write_3mf(tmp_path / "objects.3mf", model_xml=WIDGET_MODEL) objects = inspect_object_positions(path, scan_max_bytes=SCAN_BUDGET) assert len(objects) == 1 + assert objects[0].source == "model_transform" assert objects[0].name == "widget" - assert objects[0].center_x_mm == 35 - assert objects[0].center_y_mm == 50 - assert objects[0].bounds.min_x_mm == 30 - assert objects[0].gcode_bounds is not None - assert objects[0].gcode_bounds.min_x_mm == 20 + assert (objects[0].center_x_mm, objects[0].center_y_mm) == (35.0, 50.0) + assert objects[0].rotation_deg == 0.0 + + +def test_model_transforms_are_not_trusted_for_later_plates(tmp_path: Path) -> None: + """Later plates are offset in the project layout, not in bed coordinates.""" + path = write_3mf(tmp_path / "plate2.3mf", plate_gcode=None, model_xml=WIDGET_MODEL) + with zipfile.ZipFile(path, "a") as archive: + archive.writestr("Metadata/plate_2.gcode", SAMPLE_GCODE) + + assert inspect_object_positions(path, scan_max_bytes=SCAN_BUDGET) == () diff --git a/tests/test_records.py b/tests/test_records.py new file mode 100644 index 0000000..d5f5807 --- /dev/null +++ b/tests/test_records.py @@ -0,0 +1,549 @@ +"""Durable result bundles, the central-ingest outbox, and lifecycle events. + +Everything runs against fake printers and a fake central server; nothing here +can reach a printer, a robot, the dashboard or an ELN. +""" + +from __future__ import annotations + +import asyncio +import json +import time +from collections.abc import Callable +from dataclasses import replace +from datetime import UTC, datetime, timedelta +from pathlib import Path + +import pytest +from fastapi.testclient import TestClient + +from bambu_server.config import Settings +from bambu_server.main import create_app +from bambu_server.records import OutboxEntry, OutboxStore, OutboxWorker, ResultStore +from bambu_server.submissions import ( + DispatchRecord, + PlateCheck, + SubmissionStore, + TrayAssignment, +) + +from .conftest import SAMPLE_GCODE, FakeBackend, write_3mf +from .test_dispatch import BASE, PRINTER, _claim, _control_settings, _start_body + +LABELLED = SAMPLE_GCODE + ( + "; start printing object, unique label id: 101\n" + "G1 X20 Y30 F600\nG1 X40 Y50 E10\n" + "; stop printing object, unique label id: 101\n" +) +PLATE_JSON = json.dumps( + {"bbox_objects": [{"id": 101, "name": "bracket", "bbox": [18, 28, 42, 52]}]} +) + + +def _wait_for(check: Callable[[], object], timeout: float = 6.0) -> object: + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + value = check() + if value: + return value + time.sleep(0.05) + raise AssertionError("condition not met in time") + + +def _events(client: TestClient) -> list[dict]: + return client.get("/events", params={"limit": 500}).json()["events"] + + +def _event(client: TestClient, kind: str, submission_id: str | None = None) -> dict: + def find() -> dict | None: + for event in _events(client): + if event["type"] == kind and ( + submission_id is None or event["submission_id"] == submission_id + ): + return event + return None + + return _wait_for(find) # type: ignore[return-value] + + +def _upload(client: TestClient, tmp_path: Path, *, body: str = LABELLED, **form: str) -> dict: + artifact = write_3mf( + tmp_path / f"part-{time.monotonic_ns()}.3mf", + plate_gcode=body, + extra_members={"Metadata/plate_1.json": PLATE_JSON}, + ) + response = client.post( + "/submissions", + files={"file": ("part.3mf", artifact.read_bytes(), "application/octet-stream")}, + data={"target_machine": PRINTER, "requested_by": "submitter", **form}, + ) + assert response.status_code == 201, response.text + return response.json() + + +@pytest.fixture +def control(settings: Settings, backend: FakeBackend): + backend.refresh_timestamps = True + app = create_app(settings=_control_settings(settings), backend_factory=lambda _d, _c: backend) + with TestClient(app) as client: + yield client, backend + + +# -- result bundles and terminal events ----------------------------------------- + + +def test_a_finished_print_leaves_a_final_bundle_and_a_finished_event( + control, tmp_path: Path +) -> None: + client, backend = control + job = _upload(client, tmp_path) + sid = job["submission_id"] + client.post(f"/submissions/{sid}/approve", json={"approved_by": "approver"}) + headers = {"X-Claim-Token": _claim(client)} + snap = client.post(f"{BASE}/control/snapshot", headers=headers).json() + started = client.post( + f"{BASE}/control/start_print", + headers=headers, + json=_start_body(sid, plate_check_method="printer_camera", snapshot_token=snap["token"]), + ) + assert started.json()["state"] == "running", started.text + backend.reading = replace(backend.reading, gcode_state="FINISH") + + finished = _event(client, "job.finished", sid) + assert finished["schema_version"] == 1 + assert finished["printer_id"] == PRINTER + assert finished["state"] == "finished" + assert finished["gateway_id"] == "bambu_gateway" + assert finished["updated_at"] + assert finished["object_positions"][0]["name"] == "bracket" + assert finished["object_positions"][0]["center_x_mm"] == 30.0 + assert finished["pickup"]["bed_temperature_c"] == 25.2 + assert finished["pickup"]["cooled"] is True + assert _event(client, "job.started", sid)["object_positions"] + + bundle = _wait_for(lambda: client.get(f"/submissions/{sid}/result").json().get("final") and + client.get(f"/submissions/{sid}/result").json()) + assert bundle["schema_id"] == "ac.bambu.print_result" + assert bundle["schema_version"] == 1 + assert bundle["state"] == "finished" + assert bundle["artifact"]["sha256"] == job["sha256"] + assert bundle["artifact"]["stored"] is True + assert bundle["plate_check"]["snapshot_sha256"] == snap["sha256"] + assert bundle["timeline"]["observed_running_at"] + assert bundle["timeline"]["observed_finished_at"] + assert bundle["objects"][0]["source"] == "slicer_plate_json" + assert bundle["bed_size_mm"] == [256.0, 256.0] + assert bundle["pickup"]["cooled"] is True + assert bundle["job"]["history"][-1]["to_state"] == "finished" + + pickup = client.get(f"/submissions/{sid}/pickup-targets").json() + assert pickup["ready"] is True + assert pickup["objects"][0]["bounds"]["max_x_mm"] == 42.0 + assert "arm_frame" not in json.dumps(pickup) + + +def test_a_hot_finished_bed_announces_job_cooled_when_it_cools( + control, tmp_path: Path +) -> None: + client, backend = control + sid = _upload(client, tmp_path)["submission_id"] + client.post(f"/submissions/{sid}/approve", json={"approved_by": "approver"}) + headers = {"X-Claim-Token": _claim(client)} + client.post(f"{BASE}/control/start_print", headers=headers, json=_start_body(sid)) + backend.reading = replace(backend.reading, gcode_state="FINISH", bed_temperature_c=60.0) + + finished = _event(client, "job.finished", sid) + assert finished["pickup"]["cooled"] is False + assert client.get(f"/submissions/{sid}/pickup-targets").json()["ready"] is False + + backend.reading = replace(backend.reading, bed_temperature_c=30.0) + cooled = _event(client, "job.cooled", sid) + assert cooled["pickup"]["cooled"] is True + assert cooled["object_positions"][0]["name"] == "bracket" + + +def test_rejected_and_cancelled_jobs_get_bundles_events_and_local_only_records( + client: TestClient, tmp_path: Path +) -> None: + rejected = _upload( + client, tmp_path, body=LABELLED.replace("nozzle_diameter = 0.4", "nozzle_diameter = 0.6") + ) + cancelled = _upload(client, tmp_path) + client.post(f"/submissions/{cancelled['submission_id']}/cancel", json={"cancelled_by": "op"}) + + for kind, job in (("job.rejected", rejected), ("job.cancelled", cancelled)): + event = _event(client, kind, job["submission_id"]) + assert event["state"] == kind.split(".")[1] + bundle = _wait_for( + lambda job=job: client.get(f"/submissions/{job['submission_id']}/result").json() + if client.get(f"/submissions/{job['submission_id']}/result").json()["final"] + else None + ) + assert bundle["state"] == event["state"] + entry = client.get(f"/submissions/{job['submission_id']}/eln-ingest").json() + assert entry["state"] == "local_only" + assert entry["local_reason"] == "no_eln_project" + + +def test_a_running_jobs_bundle_is_built_live_and_not_final(client: TestClient, tmp_path) -> None: + sid = _upload(client, tmp_path)["submission_id"] + bundle = client.get(f"/submissions/{sid}/result").json() + assert bundle["final"] is False + assert bundle["state"] == "queued" + assert bundle["objects"][0]["name"] == "bracket" + + +def test_the_bundle_survives_deleting_the_job_record(client: TestClient, tmp_path) -> None: + sid = _upload(client, tmp_path)["submission_id"] + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + _wait_for(lambda: client.get(f"/submissions/{sid}/result").json()["final"]) + + assert client.delete(f"/submissions/{sid}").status_code == 204 + assert client.get(f"/submissions/{sid}").status_code == 404 + assert client.get(f"/submissions/{sid}/result").json()["state"] == "cancelled" + + +# -- artifact download ------------------------------------------------------------ + + +def test_the_exact_artifact_downloads_with_its_sha256_as_etag( + client: TestClient, tmp_path: Path +) -> None: + job = _upload(client, tmp_path) + url = f"/submissions/{job['submission_id']}/artifact" + + response = client.get(url) + assert response.status_code == 200 + assert response.headers["etag"] == f'"{job["sha256"]}"' + import hashlib + + assert hashlib.sha256(response.content).hexdigest() == job["sha256"] + assert "attachment" in response.headers["content-disposition"] + + cached = client.get(url, headers={"If-None-Match": f'"{job["sha256"]}"'}) + assert cached.status_code == 304 + + +def test_a_deleted_artifact_is_gone(settings: Settings, backend: FakeBackend, tmp_path) -> None: + settings.submissions.cancel_deletes_artifact = True + app = create_app(settings=settings, backend_factory=lambda _d, _c: backend) + with TestClient(app) as client: + sid = _upload(client, tmp_path)["submission_id"] + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + assert client.get(f"/submissions/{sid}/artifact").status_code == 410 + + +# -- events across restarts --------------------------------------------------------- + + +def test_event_ids_keep_increasing_across_a_restart_with_a_marker( + settings: Settings, backend: FakeBackend, tmp_path: Path +) -> None: + app = create_app(settings=settings, backend_factory=lambda _d, _c: backend) + with TestClient(app) as client: + sid = _upload(client, tmp_path)["submission_id"] + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + before = _event(client, "job.cancelled", sid) + first_boot = before["boot_id"] + + app = create_app(settings=settings, backend_factory=lambda _d, _c: backend) + with TestClient(app) as client: + events = _events(client) + assert before["event_id"] in [e["event_id"] for e in events] + restart = [e for e in events if e["type"] == "gateway.restarted"][-1] + assert restart["event_id"] > before["event_id"] + assert restart["boot_id"] != first_boot + after = client.get("/events", params={"after": before["event_id"]}).json()["events"] + assert [e["type"] for e in after] == ["gateway.restarted"] + + +def test_a_dispatch_interrupted_by_a_restart_is_announced_as_failed( + settings: Settings, backend: FakeBackend, tmp_path: Path +) -> None: + from bambu_server.profiles import ObservedMachineState, build_profile + from bambu_server.submissions import run_validation + + async def leave_a_job_dispatching() -> str: + store = SubmissionStore(settings.submissions) + store.load() + + async def chunks(): + yield SAMPLE_GCODE.encode() + + job = await store.accept( + chunks=chunks(), extension=".gcode", target_machine=PRINTER, + requested_by="submitter", material=None, original_filename="part.gcode", + ) + profile = build_profile(settings.printers[0], ObservedMachineState(telemetry_ok=True)) + job = await run_validation(store, job, profile) + job = await store.approve(job, approved_by="approver") + now = datetime.now(UTC) + record = DispatchRecord( + dispatched_by="op", dispatched_by_verified=False, requested_at=now, + plate_check=PlateCheck( + confirmed_by="op", confirmed_by_verified=False, method="in_person", + confirmed_at=now, + ), + ams_mapping=[TrayAssignment(filament_id=1, ams_id=0, tray_id=1)], + bed_type="textured_plate", plate_index=1, remote_filename="gw_x.3mf", + ) + await store.begin_dispatch(job, record) + return job.submission_id + + sid = asyncio.run(leave_a_job_dispatching()) + app = create_app(settings=settings, backend_factory=lambda _d, _c: backend) + with TestClient(app) as client: + event = _event(client, "job.failed", sid) + assert event["recovered_after_restart"] is True + assert "restarted while dispatching" in event["note"] + bundle = _wait_for(lambda: client.get(f"/submissions/{sid}/result").json()["final"] + and client.get(f"/submissions/{sid}/result").json()) + assert bundle["state"] == "failed" + + +def test_event_and_outbox_failures_never_break_a_state_change( + client: TestClient, tmp_path: Path, monkeypatch +) -> None: + async def fail(*_args, **_kwargs): + raise RuntimeError("disk full") + + monkeypatch.setattr(OutboxStore, "ensure_for_terminal", fail) + monkeypatch.setattr(ResultStore, "write", fail) + sid = _upload(client, tmp_path)["submission_id"] + + response = client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + + assert response.status_code == 200 + assert response.json()["state"] == "cancelled" + assert _event(client, "job.cancelled", sid)["state"] == "cancelled" + + +# -- listing changes ------------------------------------------------------------------ + + +def test_submissions_can_be_paged_newest_first_since_a_time( + client: TestClient, tmp_path: Path +) -> None: + first = _upload(client, tmp_path) + second = _upload(client, tmp_path) + client.post(f"/submissions/{first['submission_id']}/approve", json={"approved_by": "op"}) + + newest = client.get("/submissions", params={"order": "newest", "limit": 1}).json() + assert [j["submission_id"] for j in newest] == [first["submission_id"]] + page_two = client.get( + "/submissions", params={"order": "newest", "limit": 1, "offset": 1} + ).json() + assert [j["submission_id"] for j in page_two] == [second["submission_id"]] + changed = client.get( + "/submissions", params={"updated_after": second["updated_at"]} + ).json() + assert [j["submission_id"] for j in changed] == [first["submission_id"]] + # The default order is unchanged: oldest submission first. + default = client.get("/submissions").json() + assert [j["submission_id"] for j in default][:2] == [ + first["submission_id"], second["submission_id"], + ] + + +# -- the outbox worker against a fake central server ---------------------------------- + + +class FakeCentral: + def __init__(self, *, post: int = 202, polls: tuple[tuple[int, str], ...] = ()) -> None: + self.post_status = post + self.polls = list(polls) + self.calls: list[tuple[str, str, dict[str, str], bytes | None]] = [] + + def __call__(self, method, url, headers, body, timeout): + self.calls.append((method, url, headers, body)) + if method == "POST": + return self.post_status, b'{"state": "delivered"}' + status, state = self.polls.pop(0) if self.polls else (200, "filed") + return status, json.dumps( + {"state": state, "eln_entry_url": "https://eln.example/entry/7"} + ).encode() + + +def _worker(tmp_path: Path, central: FakeCentral) -> tuple[OutboxWorker, OutboxStore]: + outbox = OutboxStore(tmp_path) + outbox.load() + results = ResultStore(tmp_path) + results.root.mkdir(parents=True, exist_ok=True) + results.path("a" * 32).write_text('{"schema_version": 1, "state": "finished"}') + worker = OutboxWorker( + outbox=outbox, results=results, url="https://central.example/api/ingest/print-results", + token="test-token", gateway_id="bambu_gateway", poll_interval_s=60, + retry_initial_s=10, retry_max_s=40, request_timeout_s=5, transport=central, + ) + return worker, outbox + + +async def _pending(outbox: OutboxStore) -> None: + now = datetime.now(UTC) + await outbox.put(OutboxEntry( + submission_id="a" * 32, device_id="bambu_a1_01", state="pending", + eln_project="PRJ-1", created_at=now, updated_at=now, next_attempt_at=now, + )) + + +LATER = datetime.now(UTC) + timedelta(days=1) + + +async def test_the_worker_delivers_then_follows_filing_to_filed(tmp_path: Path) -> None: + central = FakeCentral(polls=((200, "filing"), (200, "filed"))) + worker, outbox = _worker(tmp_path, central) + await _pending(outbox) + + await worker.tick(LATER) + assert outbox.get("a" * 32).state == "delivered" + method, url, headers, body = central.calls[0] + assert method == "POST" and url.endswith("/api/ingest/print-results") + assert headers["Authorization"] == "Bearer test-token" + payload = json.loads(body) + assert payload["device_id"] == "bambu_a1_01" + assert payload["id"] == "a" * 32 + assert payload["eln_project"] == "PRJ-1" + assert payload["bundle"]["state"] == "finished" + + await worker.tick(LATER) + assert outbox.get("a" * 32).state == "filing" + assert central.calls[1][1].endswith(f"/bambu_a1_01/{'a' * 32}") + await worker.tick(LATER) + entry = outbox.get("a" * 32) + assert entry.state == "filed" + assert entry.remote_reference == "https://eln.example/entry/7" + assert entry.next_attempt_at is None + + +async def test_the_worker_backs_off_exponentially_on_server_errors(tmp_path: Path) -> None: + worker, outbox = _worker(tmp_path, FakeCentral(post=503)) + await _pending(outbox) + + await worker.tick(LATER) + first = outbox.get("a" * 32) + assert first.state == "pending" and first.attempts == 1 + assert 9 <= (first.next_attempt_at - first.updated_at).total_seconds() <= 11 + await worker.tick(LATER) + second = outbox.get("a" * 32) + assert second.attempts == 2 + assert 19 <= (second.next_attempt_at - second.updated_at).total_seconds() <= 21 + assert "503" in second.last_error + + +async def test_a_refused_bundle_is_held_for_a_person(tmp_path: Path) -> None: + worker, outbox = _worker(tmp_path, FakeCentral(post=422)) + await _pending(outbox) + await worker.tick(LATER) + entry = outbox.get("a" * 32) + assert entry.state == "held" + assert entry.next_attempt_at is None + + +async def test_an_unknown_delivery_is_sent_again(tmp_path: Path) -> None: + worker, outbox = _worker(tmp_path, FakeCentral(polls=((404, ""),))) + await _pending(outbox) + await worker.tick(LATER) + await worker.tick(LATER) + assert outbox.get("a" * 32).state == "pending" + + +async def test_an_unreachable_server_is_retried(tmp_path: Path) -> None: + def down(*_args): + raise ConnectionRefusedError() + + worker, outbox = _worker(tmp_path, down) # type: ignore[arg-type] + await _pending(outbox) + await worker.tick(LATER) + entry = outbox.get("a" * 32) + assert entry.state == "pending" and entry.attempts == 1 + assert "unreachable" in entry.last_error + + +async def test_outbox_state_survives_a_restart(tmp_path: Path) -> None: + worker, outbox = _worker(tmp_path, FakeCentral()) + await _pending(outbox) + await worker.tick(LATER) + + reopened = OutboxStore(tmp_path) + reopened.load() + assert reopened.get("a" * 32).state == "delivered" + assert reopened.counts()["delivered"] == 1 + + +# -- ingest through the API ----------------------------------------------------------- + + +@pytest.fixture +def ingest(settings: Settings, backend: FakeBackend, monkeypatch): + monkeypatch.setenv("BAMBU_RESULTS_TOKEN", "test-token") + settings.results.ingest_url = "https://central.example/api/ingest/print-results" + settings.results.worker_tick_s = 0.05 + settings.results.poll_interval_s = 0.05 + central = FakeCentral(polls=((200, "filing"), (200, "filed"))) + app = create_app( + settings=settings, backend_factory=lambda _d, _c: backend, results_transport=central + ) + with TestClient(app) as client: + yield client, central + + +def test_a_job_with_an_eln_project_is_filed_through_the_central_server( + ingest, tmp_path: Path +) -> None: + client, central = ingest + assert client.get("/status").json()["details"]["results_ingest_configured"] is True + sid = _upload(client, tmp_path, eln_project="PRJ-42")["submission_id"] + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + + entry = _wait_for( + lambda: (e := client.get(f"/submissions/{sid}/eln-ingest").json()).get("state") + == "filed" and e + ) + assert entry["eln_project"] == "PRJ-42" + posted = json.loads(next(c[3] for c in central.calls if c[0] == "POST")) + assert posted["bundle"]["submission_id"] == sid + assert posted["bundle"]["eln_project"] == "PRJ-42" + assert client.get("/status").json()["details"]["results_outbox"]["filed"] == 1 + + +def test_a_finished_job_can_be_filed_later_under_a_chosen_project( + ingest, tmp_path: Path +) -> None: + client, _central = ingest + sid = _upload(client, tmp_path)["submission_id"] + queued = client.post(f"/submissions/{sid}/eln-ingest", json={"eln_project": "PRJ-7", + "requested_by": "op"}) + assert queued.status_code == 409 # not terminal yet + + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + _wait_for(lambda: client.get(f"/submissions/{sid}/eln-ingest").status_code == 200) + assert client.get(f"/submissions/{sid}/eln-ingest").json()["state"] == "local_only" + + queued = client.post( + f"/submissions/{sid}/eln-ingest", json={"eln_project": "PRJ-7", "requested_by": "op"} + ) + assert queued.status_code == 200, queued.text + assert queued.json()["queued_by"] == "op" + _wait_for( + lambda: client.get(f"/submissions/{sid}/eln-ingest").json().get("state") == "filed" + ) + again = client.post( + f"/submissions/{sid}/eln-ingest", json={"eln_project": "PRJ-7", "requested_by": "op"} + ) + assert again.status_code == 409 + + +def test_without_central_ingest_records_stay_local_only(client: TestClient, tmp_path) -> None: + sid = _upload(client, tmp_path, eln_project="PRJ-1")["submission_id"] + client.post(f"/submissions/{sid}/cancel", json={"cancelled_by": "op"}) + entry = _wait_for( + lambda: client.get(f"/submissions/{sid}/eln-ingest").status_code == 200 + and client.get(f"/submissions/{sid}/eln-ingest").json() + ) + assert entry["state"] == "local_only" + assert entry["local_reason"] == "ingest_not_configured" + refused = client.post( + f"/submissions/{sid}/eln-ingest", json={"eln_project": "PRJ-1", "requested_by": "op"} + ) + assert refused.status_code == 409 + assert "not configured" in refused.json()["detail"] diff --git a/tests/test_submission_api.py b/tests/test_submission_api.py index 0492abe..bbfa252 100644 --- a/tests/test_submission_api.py +++ b/tests/test_submission_api.py @@ -193,20 +193,17 @@ def test_an_unknown_submission_is_404(client: TestClient) -> None: assert client.get("/submissions/" + "0" * 32).status_code == 404 -def test_object_and_robot_calibration_endpoints(client: TestClient) -> None: +def test_unlabelled_gcode_reports_no_invented_objects(client: TestClient) -> None: created = _upload(client).json() assert client.get(f"/submissions/{created['submission_id']}/objects").json() == [] - calibration = { - "printer_id": "bambu_test_01", - "arm_frame": "robot_base", - "matrix": [1, 0, 0, 100, 0, 1, 0, 200, 0, 0, 1, 10, 0, 0, 0, 1], - } - response = client.post("/printers/bambu_test_01/robot-calibration", json=calibration) - assert response.status_code == 200 - assert response.json()["arm_frame"] == "robot_base" - assert client.get("/printers/bambu_test_01/robot-calibration").status_code == 200 - assert client.get("/events").json() == {"events": [], "next_after": None} + +def test_robot_calibration_is_not_part_of_the_gateway(client: TestClient) -> None: + """The arm agent owns bed-to-arm calibration; the gateway serves bed mm only.""" + paths = client.get("/openapi.json").json()["paths"] + assert not any("calibration" in path for path in paths) + pickup = client.get("/openapi.json").json()["components"]["schemas"]["PickupInfo"] + assert "arm_frame" not in str(pickup) def test_approval_records_sign_off_and_sets_dispatch_ready(client: TestClient) -> None: @@ -326,7 +323,8 @@ def test_cancelling_removes_a_job_from_the_queue(client: TestClient) -> None: assert response.status_code == 200 job = response.json() assert job["state"] == "cancelled" - assert job["artifact_removed"] is True + # Kept by default as part of the print record. + assert job["artifact_removed"] is False assert job["history"][-1]["note"] == "cancelled by lab-operator: superseded" assert client.get("/printers/bambu_test_01/queue").json()["queued"] == [] # The record survives so the withdrawal stays auditable. diff --git a/tests/test_submissions.py b/tests/test_submissions.py index 2d5d274..09fc9dd 100644 --- a/tests/test_submissions.py +++ b/tests/test_submissions.py @@ -343,9 +343,10 @@ async def test_a_blank_material_is_treated_as_absent(store: SubmissionStore) -> assert job.material is None -async def test_cancelling_a_queued_job_removes_it_and_its_artifact( +async def test_cancelling_a_queued_job_removes_it_but_keeps_its_artifact( store: SubmissionStore, profile: MachineProfile ) -> None: + """The artifact is part of the print record; deleting it is opt-in.""" job = await run_validation(store, await _accept(store), profile) path = store.artifact_path(job) assert path.exists() @@ -353,14 +354,68 @@ async def test_cancelling_a_queued_job_removes_it_and_its_artifact( cancelled = await store.cancel(job, cancelled_by="operator", reason="wrong plate") assert cancelled.state == "cancelled" - assert cancelled.artifact_removed is True - assert not path.exists() + assert cancelled.artifact_removed is False + assert path.exists() assert store.queue_for("bambu_test_01") == [] # The record outlives the file, so the withdrawal stays explicable. assert cancelled.history[-1].note == "cancelled by operator: wrong plate" assert store.get(job.submission_id) is not None +async def test_cancel_deletes_the_artifact_only_when_configured( + tmp_path: Path, profile: MachineProfile +) -> None: + store = SubmissionStore( + SubmissionSettings(directory=tmp_path / "submissions", cancel_deletes_artifact=True) + ) + store.load() + job = await run_validation(store, await _accept(store), profile) + path = store.artifact_path(job) + + cancelled = await store.cancel(job, cancelled_by="operator") + + assert cancelled.artifact_removed is True + assert not path.exists() + + +def test_terminal_records_are_kept_by_default() -> None: + settings = SubmissionSettings() + assert settings.retain_terminal_days is None + assert settings.cancel_deletes_artifact is False + + +async def test_listeners_see_each_persisted_transition_and_cannot_break_it( + store: SubmissionStore, profile: MachineProfile +) -> None: + seen: list[str] = [] + + def record(job) -> None: + seen.append(job.state) + + def explode(job) -> None: + raise RuntimeError("listener failure") + + store.add_listener(explode) + store.add_listener(record) + job = await run_validation(store, await _accept(store), profile) + + assert job.state == "queued" + assert seen == ["validating", "validated", "queued"] + + +async def test_listing_supports_updated_after_and_newest_first( + store: SubmissionStore, profile: MachineProfile +) -> None: + first = await run_validation(store, await _accept(store), profile) + second = await run_validation(store, await _accept(store), profile) + first = await store.approve(first, approved_by="operator") + + newest = store.list(newest_first=True) + assert [job.submission_id for job in newest] == [first.submission_id, second.submission_id] + changed = store.list(updated_after=second.updated_at) + assert [job.submission_id for job in changed] == [first.submission_id] + + async def test_cancelling_an_approved_job_retracts_dispatch_ready( store: SubmissionStore, profile: MachineProfile ) -> None: From a34eae38513ec8b2e4d04a4694603b7609d726d8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 02:43:35 +0000 Subject: [PATCH 5/5] Document print records, ELN ingest, bed-frame objects and A1 agent mode Record the 2026-11-02 approvals (A1-only agent mode with an audited admin switch and agent_camera; calibration owned by the arm agent) in AGENTS.md and AGENT_RULES.md, and update the README, API reference, example config and .env.example with the agent workflow, the new endpoints and the deployment env vars. Co-authored-by: Yang Cao --- .env.example | 8 ++ AGENTS.md | 14 ++- AGENT_RULES.md | 12 ++ README.md | 286 +++++++++++++++++++++++++++++++++--------- docs/API_REFERENCE.md | 102 +++++++++++---- docs/TODO.md | 13 +- printers.example.yaml | 39 +++++- 7 files changed, 388 insertions(+), 86 deletions(-) diff --git a/.env.example b/.env.example index f2d1f36..a800fbe 100644 --- a/.env.example +++ b/.env.example @@ -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:///api/ingest/print-results +#BAMBU_RESULTS_TOKEN= diff --git a/AGENTS.md b/AGENTS.md index aaf8043..37c7533 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/AGENT_RULES.md b/AGENT_RULES.md index 20c01e4..268637b 100644 --- a/AGENT_RULES.md +++ b/AGENT_RULES.md @@ -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. diff --git a/README.md b/README.md index 5a7b58c..f5df2cb 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,20 @@ expected finish times. That path writes to the gateway's own disk and never to a printer. By default the service is **monitoring-only** and exposes no control endpoints. -A deployment that sets `dispatch.enabled` gets a narrow, human-in-the-loop -control plane: claims plus four verbs (camera snapshot, chamber light, start an -approved job, stop), behind the gates described in [Control plane](#control-plane). The -third-party library's other command methods remain unreachable. Control is not -yet exposed as `lab-skills` skills; the only caller is a person on the `/ui` -page or a direct HTTP client holding a claim. +A deployment that sets `dispatch.enabled` gets a narrow control plane: claims +plus four verbs (camera snapshot, chamber light, start an approved job, stop), +behind the gates described in [Control plane](#control-plane). A person +confirms the plate is empty before every start, except on a printer whose +**agent mode** an admin has switched on — approved 2026-11-02 for the Bambu A1 +(`bambu_a1_01`) only — where an agent may decide from a claimed camera +snapshot ([Agent mode](#agent-mode-bambu-a1-only)). The third-party library's +other command methods remain unreachable. Control is not yet exposed as +`lab-skills` skills. + +Every job keeps a durable, schema-versioned **result bundle** and its exact +artifact on the gateway's disk. Filing a record in the ELN is optional and goes +only through the central dashboard's ingest ([Print records and ELN +ingest](#print-records-and-eln-ingest)); the gateway never writes to the ELN. ## Architecture @@ -106,48 +114,205 @@ Submission pipeline routes: |---|---|---| | GET | `/printers/{id}/profile` | The machine a submitter targets and is validated against | | GET | `/printers/{id}/queue` | Running job and waiting submissions, with finish times | -| POST | `/submissions` | Upload a `.3mf` / `.gcode` artifact; validated inline | -| GET | `/submissions` | List jobs (`machine`, `state`, `limit` filters) | +| POST | `/submissions` | Upload a `.3mf` / `.gcode` artifact (optional `eln_project`); validated inline | +| GET | `/submissions` | List jobs: `machine`, `state`, `limit`, plus `updated_after`, `order=newest`, `offset` | | GET | `/submissions/{submission_id}` | One job with its verdict and history | -| POST | `/submissions/{submission_id}/approve` | Record sign-off on a queued job | -| POST | `/submissions/{submission_id}/cancel` | Withdraw a waiting job from the queue | -| DELETE | `/submissions/{submission_id}` | Delete a finished job's record (retention) | -| GET | `/submissions/{submission_id}/objects` | Per-object bed-mm centres, bounds, transforms, and labelled-G-code cross-checks | -| GET | `/events` | Pollable `job.started`, `job.finished`, and `job.failed` feed | -| GET/POST | `/printers/{id}/robot-calibration` | Stored bed-mm → robot-frame transform; never moves a robot | -| GET | `/submissions/{submission_id}/pickup-targets` | Finished-job arm-frame targets and cool-down readiness | +| POST | `/submissions/{submission_id}/approve` | Record sign-off on a queued job (optional `eln_project`) | +| POST | `/submissions/{submission_id}/cancel` | Withdraw a waiting job from the queue (keeps the artifact) | +| DELETE | `/submissions/{submission_id}` | Delete a finished job's record and artifact; its result bundle stays | +| GET | `/submissions/{submission_id}/artifact` | The exact stored file; `ETag` is its quoted SHA-256, `If-None-Match` answers 304 | +| GET | `/submissions/{submission_id}/result` | The schema-versioned result bundle (`final` once terminal) | +| POST/GET | `/submissions/{submission_id}/eln-ingest` | Queue a terminal job's record for ELN filing via central / read its outbox entry | +| GET | `/results/outbox` | Outbox counts and entries | + +Agent workflow and agent mode routes: + +| Method | Path | Purpose | +|---|---|---| +| GET | `/submissions/{submission_id}/objects` | Per-object positions in bed coordinates (mm), plate index | +| GET | `/submissions/{submission_id}/pickup-targets` | Finished job's objects in bed mm, bed temperature and cooled readiness | +| GET | `/events` | Lifecycle events; ids persist across restarts (`after=` paging) | +| GET/POST | `/printers/{id}/agent-mode` | Read the agent mode switch and audit / flip it (verified admin only) | +| POST | `/printers/{id}/bed-check` | Advisory empty-bed comparison of a claimed snapshot (opt-in) | With `dispatch.enabled: false`, no `/control/*` routes exist and no route dispatches a print. ## Agent workflow -An orchestration agent can submit an already-sliced artifact, inspect -`/submissions/{id}/objects`, and wait on `GET /events` (using its last -`next_after` value) or an operator-configured `agent_workflow.event_webhook_urls` -target such as the dashboard's `/api/ingest/events`. Event payloads include the -submission, printer, timestamp, and parsed object placements. - -After `job.finished`, the agent requests `/submissions/{id}/pickup-targets`. -The response is only planning data: it is ready only when the monitor's cached -bed temperature is at or below `agent_workflow.pickup_safe_bed_c`, and only -after a person has stored a 4×4 affine transform using -`POST /printers/{id}/robot-calibration`. This service never opens a robot -connection or issues motion. - -`agent_workflow.vision_enabled` enables an optional, dependency-light advisory -comparison of an existing claimed control snapshot against an -operator-captured `.jpg` empty-bed reference. It returns -`clear` only for an exact reference match and otherwise conservatively returns -`occupied` or `unknown`. It is intentionally **not** a `start_print` plate -check: the lab safety contract requires a person to confirm an empty plate, so -an AI agent cannot use vision to set `plate_confirmed_empty` or start a print. -H2D camera support remains dependent on the backend camera implementation; if -the claimed snapshot route cannot produce a frame, this check cannot run. - -End-to-end: submit → validate → human approves → agent may inspect objects → -person claims and confirms the plate → explicit `start_print` → wait for event -→ cool down → fetch pickup targets → send those data to the robot planner. +Object positions are reported in the **printer's bed frame**, never a robot's: +millimetres, origin at the front-left corner of the printable area, +X to the +right and +Y toward the back seen from the front of the printer, Z up from the +plate, exactly as the sliced toolpath addresses the bed. Compare them with +`bed_size_mm` from `GET /printers/{id}/profile` (also in the result bundle). +The agent driving the arm owns the bed-to-arm calibration and transform; the +gateway stores none and never contacts or moves a robot. + +Positions come from the sliced file, best source first: + +1. `slicer_plate_json` — Bambu Studio's own per-object bounding boxes for the + sliced plate (`Metadata/plate_N.json`, `bbox_objects`); +2. `gcode_label` — the extruding moves inside the slicer's object labels + (`; start printing object, unique label id: N`, `EXCLUDE_OBJECT_START`, …), + travel and purge moves excluded; +3. `model_transform` — the 3MF build item transform, used for plate 1 only + because later plates are offset in the project layout. + +Each object carries `object_id`, `name`, `center_x_mm`/`center_y_mm`, +`bounds` (min/max XY), `rotation_deg` where the source has it, `plate_index` +and `source`, plus `gcode_bounds` — the labelled extrusion footprint — as an +independent cross-check. A file that does not say where its objects are yields +an empty list, never a guess. For a multi-plate 3MF only the inspected (first +sliced) plate is reported. + +**Events.** `GET /events?after=` (or the webhooks in +`agent_workflow.event_webhook_urls`) delivers `job.started`, one event per +terminal state (`job.finished`, `job.failed`, `job.rejected`, +`job.cancelled`), `job.cooled`, and `gateway.restarted`. Each event carries +`schema_version`, `event_id`, `gateway_id`, `boot_id`, `submission_id`, +`printer_id`, `state`, `updated_at`, `eln_project` and `note`. Event ids are +zero-padded decimals that keep increasing across restarts (they are kept in +`events.jsonl` beside the submissions), and every restart emits a +`gateway.restarted` marker with a new `boot_id`; a failure the gateway records +at startup because a restart interrupted a dispatch is a `job.failed` with +`recovered_after_restart: true`. + +`job.finished` includes the job's `object_positions` (bed mm) and `pickup`: +the cached bed temperature, `agent_workflow.pickup_safe_bed_c`, and `cooled`. +When the bed is still hot, the gateway keeps watching its cached temperature +(no printer I/O) and emits `job.cooled` once it is safe, for up to +`agent_workflow.cooldown_watch_timeout_s` (the watch is not resumed after a +restart; poll `pickup-targets` instead). Emission and webhook failures are +logged and never affect a job. + +**End-to-end for an agent:** + +1. `POST /submissions` (sliced `.3mf`, `target_machine`, optional `eln_project`). +2. Approval: a person approves — or, on the A1 in agent mode, the agent. +3. `POST /printers/{id}/control/claim`, then keep it alive with `heartbeat`. +4. Plate check: a person confirms (`in_person` / `printer_camera`) — or, in + agent mode, the agent takes `POST /printers/{id}/control/snapshot`, judges + the returned `image_base64` itself, and keeps the `token`. +5. `POST /printers/{id}/control/start_print` (see [Agent mode](#agent-mode-bambu-a1-only)). +6. Wait for `job.finished` (or `job.failed`) on `/events` or a webhook. +7. Wait for cool-down: `job.cooled`, or poll + `GET /submissions/{id}/pickup-targets` until `ready`. +8. Hand the bed-frame `objects` to the arm agent, which applies its own + calibration. The bundle at `/submissions/{id}/result` keeps the record. + +`agent_workflow.vision_enabled` adds an optional, dependency-light advisory +check, `POST /printers/{id}/bed-check`, that compares a claimed snapshot with an +operator-captured `.jpg` empty-bed reference. It returns `clear` +only on an exact match and otherwise `occupied` or `unknown`. Its result is not +a plate check; an agent in agent mode may use it as one input to its own +decision. + +### Agent mode (Bambu A1 only) + +Approved by Yang on 2026-11-02. With the switch on, an agent may submit, +approve and start jobs on the Bambu A1, deciding itself that the plate is empty. +Everywhere else, and on the A1 with the switch off, agents are refused and the +human-in-the-loop path is unchanged. + +- **Eligibility** is static config: `agent_mode_eligible: true` on the printer. + The config refuses it on any model but a Bambu A1 (not the A1 mini). +- **The switch** is off by default and is runtime state. Only an edge-verified + identity whose role is in `dispatch.agent_mode_admin_roles` (default + `admin`) can flip it, with `POST /printers/{id}/agent-mode + {"enabled": true|false, "reason": "..."}`; an agent cannot, even as an + admin. Every flip is appended to `agent_mode_audit.jsonl` (who, role, when, + reason, previous value) before it takes effect. `GET .../agent-mode` returns + the state and recent audit; `details.agent_mode` on `/printers/{id}/status` + and on `/status` shows it too. An unreadable switch file fails closed (off). + Turning it off refuses the next agent action at once; a running job is not + affected. +- **Who is an agent:** a request with an `X-Agent-Id` header, or whose + edge-verified role is in `dispatch.agent_roles` (default `agent`). The + verified identity and the agent id are both recorded + (`requested_by_agent`, `approved_by_agent`, `dispatch.dispatched_by_agent`). +- **Refusals** are 403 with `agent_mode: "not_eligible"` (any printer but the + A1) or `agent_mode: "off"` (switch off), for agent submissions, approvals and + starts. + +An agent's start, on the A1 with the switch on: + +```json +POST /printers/bambu_a1_01/control/start_print +X-Claim-Token: +X-Agent-Id: + +{"submission_id": "", "plate_confirmed_empty": true, + "plate_check_method": "agent_camera", "snapshot_token": "", + "plate_check_rationale": "optional: why the plate looks empty", + "ams_mapping": [{"filament_id": 1, "ams_id": 0, "tray_id": 1}]} +``` + +`agent_camera` needs a `snapshot_token` taken from that printer under the same +claim and no older than `dispatch.agent_snapshot_max_age_s` (120 s by +default); the gateway never captures a frame on the agent's behalf. An agent +must use `agent_camera`, and only an agent may. The record keeps the deciding +agent, its identity, the rationale and the frame's SHA-256; the frame is +archived as `GET /submissions/{id}/plate.jpg`. Every other gate still applies: +the claim, a cold idle printer, the declared plate, revalidation, the tray +mapping, verified identities, and one attempt per job with no retry. + +**H2D camera:** snapshots are not supported for the H2D yet — its camera is not +the P1/A1 port-6000 service this gateway reads. `control/snapshot` answers 501 +and the viewer 503 without opening a connection, so an H2D plate check is in +person only. The H2D is not eligible for agent mode in any case. + +## Print records and ELN ingest + +Records are durable by default. Terminal jobs and their artifacts are not swept +(`submissions.retain_terminal_days` is null unless set), and cancelling keeps +the artifact (`submissions.cancel_deletes_artifact: true` restores deletion). + +When a job reaches a terminal state the gateway writes one result bundle to +`/results/.json` (temp file, then `os.replace`), +and never prunes it — not even on `DELETE`. Schema `ac.bambu.print_result`, +`schema_version` 1: gateway id and version, printer id, state, `eln_project`, +the artifact (kind, filename, size, SHA-256, still stored, download path), a +timeline (submitted, approved, dispatch requested, command published, observed +running and finished, terminal), the plate check (method, who decided, agent +id, rationale, snapshot SHA-256), `bed_size_mm`, `objects` in bed mm, `pickup` +readiness at finish, and the full job record with history, verdict and facts. +`GET /submissions/{id}/result` returns it; for a job still in play it returns +one built on request with `final: false`. Terminal jobs from before this +existed get a bundle at the next startup, without an event. + +**ELN ingest is optional** and follows the lab's OT-2 gateway pattern: devices +never write to the ELN; they push only to the central server's `/api/ingest/*`, +which alone holds ELN credentials. Each terminal job gets an outbox entry in +`/outbox/.json`: + +- `local_only` — no ELN project chosen, or no central ingest configured + (`local_reason` says which); +- `pending` → `delivered` → `filing` → `filed`, or `held` (the central server + refused it or held it for a person). + +A job is queued automatically when it has an `eln_project` (from submission or +approval) and ingest is configured. To file one later, +`POST /submissions/{id}/eln-ingest {"eln_project": "..."}` on a terminal job +(refused with 409 while ingest is not configured, or once it is already +queued or filed; a `held` or `local_only` entry can be re-queued). The worker +POSTs `{schema_version, device_id, gateway_id, id, eln_project, bundle}` to the +ingest URL with `Authorization: Bearer $BAMBU_RESULTS_TOKEN`, then polls +`GET {url}/{device_id}/{submission_id}` for `{"state": "filing" | "filed" | +"held"}`; `device_id` is the printer id. Network errors, 408/425/429 and 5xx +retry with exponential backoff (`results.retry_initial_s` doubling to +`results.retry_max_s`); other 4xx hold the entry; a 404 on the status poll +delivers again. Entries are files, so the outbox resumes after a restart. +`/status` reports `results_ingest_configured`, `results_outbox` (count per +state), `results_pending` (pending plus delivered), `results_filing` and +`results_held`. Outbox and bundle failures are logged and never affect a job. + +Deployment env vars (see `.env.example`): + +| Variable | Purpose | +|---|---| +| `BAMBU_RESULTS_URL` | Central ingest URL, e.g. `https:///api/ingest/print-results`; overrides `results.ingest_url` | +| `BAMBU_RESULTS_TOKEN` | Bearer token for that ingest; required, read from the environment only | +| `BAMBU_EDGE_SHARED_SECRET` | Needed for verified identities, hence for admin flips of agent mode | The status envelope uses `equipment_kind: other` because the authoritative contract does not yet define a `3d_printer` kind. `details.device_type` carries @@ -290,8 +455,12 @@ printer without an AMS); and the request says `plate_confirmed_empty: true`, by camera or in person. A camera confirmation records a frame under this claim: the gateway captures it when start is pressed (or uses a `/control/snapshot` token sent with the request), and refuses with -502 if the camera delivers none. With `require_verified_identity` (the default) both the approver and the -person starting it must be edge-verified identities (403 otherwise). +502 if the camera delivers none. On the A1 in agent mode an agent states it +instead with `plate_check_method: agent_camera` and the token of the frame it +judged ([Agent mode](#agent-mode-bambu-a1-only)); a person cannot use that +method and an agent cannot use the others. With `require_verified_identity` +(the default) both the approver and the caller starting it must be +edge-verified identities (403 otherwise). `allowed_actions` on `/status` is computed by the same gate, so the two never disagree. @@ -437,7 +606,9 @@ words itself honestly — it distinguishes "not signed in" from "this deployment cannot tell who you are" (`identity_available`). Approval is human-in-the-loop by design: nothing auto-approves, and a submission -that did not pass validation can never be approved. +that did not pass validation can never be approved. The one exception is the +A1 in agent mode, where an agent may approve; the job then records the agent +as `approved_by_agent`. ### Behind the dashboard's login @@ -467,17 +638,18 @@ landing the visitor on the dashboard. ### Retention -Terminal records (`rejected`, `finished`, `failed`, `cancelled`) are swept at -startup once older than `submissions.retain_terminal_days` (30 by default; set -it to null to keep everything). A job that is **still in play is never swept**, -however old — one stuck in `validating` is a signal, not litter. The set of -terminal states is derived from the transition table rather than listed twice, -so a state added there cannot be missed here. +Job records and artifacts are the lab's print records, so nothing is swept by +default. Setting `submissions.retain_terminal_days` sweeps terminal records +(`rejected`, `finished`, `failed`, `cancelled`) older than that at startup. A +job that is **still in play is never swept**, however old — one stuck in +`validating` is a signal, not litter. The set of terminal states is derived +from the transition table rather than listed twice, so a state added there +cannot be missed here. Result bundles under `results/` are never swept. `DELETE /submissions/{id}` removes one finished job's record and artifact -immediately. Only a terminal job can be deleted: withdrawing one that is still -waiting is `cancel`, which leaves a record of the decision — deleting it would -erase that along with the job. +immediately; its result bundle stays. Only a terminal job can be deleted: +withdrawing one that is still waiting is `cancel`, which leaves a record of the +decision — deleting it would erase that along with the job. Sweeping happens at startup rather than on a timer so the store's on-disk and in-memory views stay identical. A record removed underneath a running process @@ -492,10 +664,10 @@ reaches no printer, and it is deliberately refused for anything past the queue stopping a running print is a control-plane action that needs a claim, and this surface has none. -Cancelling deletes the stored artifact (a withdrawn job has no further use for -it, and it is the submitter's data) and marks `artifact_removed`. The job record -stays, with the actor and reason in its history, so the withdrawal remains -auditable. There is no undo — a withdrawn job is resubmitted, not revived. An +Cancelling keeps the stored artifact by default, as part of the record; with +`submissions.cancel_deletes_artifact: true` it deletes it instead and marks +`artifact_removed`. The job record stays either way, with the actor and reason +in its history, so the withdrawal remains auditable. There is no undo — a withdrawn job is resubmitted, not revived. An approved job that is cancelled has its `dispatch_ready` retracted. ## Dashboard registration diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index a5772e3..07891bf 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -65,39 +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 workflow data - -`GET /submissions/{id}/objects` returns parsed per-object bed coordinates: -model-name/id, centre XY, min/max bounds, rotation where represented, plate -index, and an extrusion-only labelled-G-code bounds cross-check where available. -It returns no invented positions for unlabeled or unsupported artifacts. +## 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: + ""` (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`. -`GET /events?after=` is a bounded, pollable lifecycle feed with -`job.started`, `job.finished`, and `job.failed` events. Configure -`agent_workflow.event_webhook_urls` to also POST the same JSON event to the -dashboard ingest endpoint or another operator-approved receiver; delivery is -best effort and cannot change printer state. +## Agent workflow data -`POST /printers/{id}/robot-calibration` stores a 4×4 affine bed-mm to robot-frame -matrix and `GET /submissions/{id}/pickup-targets` converts finished-job object -centres using it. The latter includes cached bed temperature and is only -`ready` below `agent_workflow.pickup_safe_bed_c`. Neither endpoint talks to a -robot or creates a motion. +`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=` 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. It cannot be supplied to `start_print`; -the required human plate confirmation remains unchanged. +It performs no camera access itself, and its result is not a plate check. diff --git a/docs/TODO.md b/docs/TODO.md index 250ef1f..8189984 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -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 @@ -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 diff --git a/printers.example.yaml b/printers.example.yaml index 1f1e04d..ac83ab3 100644 --- a/printers.example.yaml +++ b/printers.example.yaml @@ -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:///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. @@ -24,6 +37,12 @@ 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 @@ -33,7 +52,8 @@ dispatch: agent_workflow: event_webhook_urls: [] # e.g. [https://dashboard/api/ingest/events] event_buffer_size: 1000 - pickup_safe_bed_c: 45 + 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 .jpg files @@ -77,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]