diff --git a/AGENT_RULES.md b/AGENT_RULES.md index 1edf585..9a09d75 100644 --- a/AGENT_RULES.md +++ b/AGENT_RULES.md @@ -19,7 +19,12 @@ the Bambu printer gateway. the claim, an idle printer in no error state with no job in flight, an edge-verified caller -- an agent also needs the A1's agent mode on -- and the caller's statement `bed_path_clear: true` that no robot arm, hand or object - is in the bed's travel or above the plate. The caller names a position, + is in the bed's travel or above the plate. An agent may base that statement + on the operator's standing declaration (`bed_positions.arm_clear`, published + on the printer profile; Yang declared on 2026-11-05 that the arm is always + clear of the bed, reaching over the plate only while its agent holds the + A1's claim), on the arm's reported state, or on a person's statement for + that move. The caller names a position, never a coordinate; a refused or undelivered move is never retried and is never "fixed" by homing. Any other verb, a relaxed gate, or integration with `lab-skills` plan execution needs a new, explicitly approved design. diff --git a/README.md b/README.md index b11d545..0a8fede 100644 --- a/README.md +++ b/README.md @@ -522,6 +522,25 @@ agent mode on. Each move emits a `bed.moved` event. The printer does not report bed position, so confirm it with a snapshot; a refused or undelivered move (502) is never retried. Config accepts `bed_positions` on an A1 only. +An operator who knows the arm stays clear of the bed can record that once +instead of confirming it before every move: + +```yaml +bed_positions: + inspect_y_mm: 128 + pickup_y_mm: 250 + arm_clear: + declared_by: yang + declared_on: 2026-11-05 + statement: >- + The robot arm is always clear of the A1's bed travel; it reaches over + the plate only while its agent holds the A1's claim. +``` + +`GET /printers/{id}/profile` publishes `bed_positions`, declaration included, +so agents can rely on it for `bed_path_clear` (`AGENTIC_LAB_DESIGN.md` §1.3). +Delete `arm_clear` to withdraw it; agents then confirm per move again. + `start_print` is refused (412, a body naming the failed gate) unless the printer is observable, idle, not in a failed state and cold (`safe_bed_c`, `safe_nozzle_c`); a build plate is declared and matches the plate the job was diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index b324017..879a137 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -131,7 +131,13 @@ no `bed_positions` (every printer but the A1); 403 for an unverified caller, or an agent while agent mode is off; 422 when `bed_path_clear` is not `true` or the position is unknown; 502 when the command was not delivered (never retry). The printer does not report bed position, so confirm with a snapshot. A -delivered move emits `bed.moved`. +delivered move emits `bed.moved`. `GET /printers/{id}/profile` publishes +`bed_positions` (`inspect_y_mm`, `pickup_y_mm`, `feed_mm_min`, `arm_clear`; +`null` on printers without the verb). `arm_clear` is the operator's standing +declaration `{declared_by, declared_on, statement}` that the arm stays clear of +the bed's travel (it enters only while its agent holds the printer's claim); +when present, an agent may rely on it for `bed_path_clear`. `null` means none +was made: confirm the arm per move instead. **Camera snapshot for a plate check.** `POST /printers/{id}/control/snapshot` with the claim token returns `{token, printer_id, captured_at, sha256, diff --git a/printers.example.yaml b/printers.example.yaml index f2c0d8c..38b81d7 100644 --- a/printers.example.yaml +++ b/printers.example.yaml @@ -126,6 +126,10 @@ printers: # bed_positions: # inspect_y_mm: 128 # pickup_y_mm: 250 + # arm_clear: # optional standing arm-clear declaration + # declared_by: yang + # declared_on: 2026-11-05 + # statement: "The arm is always clear of the A1's bed travel; it reaches over the plate only while its agent holds the A1's claim." profile: enclosure: open nozzle_diameter_mm: 0.4 diff --git a/src/bambu_server/config.py b/src/bambu_server/config.py index d358383..c94ba7d 100644 --- a/src/bambu_server/config.py +++ b/src/bambu_server/config.py @@ -3,6 +3,7 @@ from __future__ import annotations import os +from datetime import date from pathlib import Path from typing import Any, Literal @@ -111,6 +112,20 @@ def validate_bed(cls, value: tuple[float, float] | None) -> tuple[float, float] BedPlate = Literal["cool_plate", "eng_plate", "hot_plate", "textured_plate", "supertack_plate"] +class ArmClearDeclaration(BaseModel): + """An operator's standing statement that the robot arm stays clear of the bed. + + Published on the printer's profile so an agent can rely on it for + ``position_bed``'s ``bed_path_clear`` instead of asking before every move + (``AGENTIC_LAB_DESIGN.md`` §1.3, *Bambu A1 bed positioning*). Removing it + from the config withdraws it. + """ + + declared_by: str = Field(min_length=1, max_length=120) + declared_on: date + statement: str = Field(min_length=1, max_length=500) + + class BedPositions(BaseModel): """Named Y positions the ``position_bed`` verb may park a bed-slinger at. @@ -125,6 +140,8 @@ class BedPositions(BaseModel): #: Feed rate of the move, mm/min. 3000 (50 mm/s) is gentler than the #: A1's own end-gcode park move (3600). feed_mm_min: int = Field(default=3000, ge=300, le=6000) + #: The operator's standing arm-clear declaration, when one was made. + arm_clear: ArmClearDeclaration | None = None def y_for(self, position: str) -> float: return self.inspect_y_mm if position == "inspect" else self.pickup_y_mm diff --git a/src/bambu_server/docs/AGENT_GUIDE.md b/src/bambu_server/docs/AGENT_GUIDE.md index 514efd0..5e28acd 100644 --- a/src/bambu_server/docs/AGENT_GUIDE.md +++ b/src/bambu_server/docs/AGENT_GUIDE.md @@ -171,10 +171,20 @@ position, never a coordinate. The response gives `position`, the configured `note`. - **Before you send it:** `bed_path_clear: true` states that the robot arm is - parked clear of the bed's travel and nothing stands above the plate. Send it - only after confirming that from the arm's own reported state, or from a - person's statement for that specific move. If you cannot confirm it, do not - move the bed. The A1 camera shows the bed, not the arm. + clear of the bed's travel and nothing stands above the plate. Confirm it + from one of: the operator's standing declaration on the printer profile + (`GET /printers/bambu_a1_01/profile`, `bed_positions.arm_clear`; on this + deployment Yang declared on 2026-11-05 that the arm is always clear of the + bed), the arm's own reported state, or a person's statement for that + specific move. Name the basis in `reason`, e.g. `"plate check; standing + arm-clear declaration 2026-11-05"`. If `arm_clear` is `null` and you have + neither of the others, do not move the bed. The A1 camera shows the bed, + not the arm. +- **The standing declaration has one condition:** the arm may enter the bed's + travel (to take parts off) only while its agent holds the A1's claim, so no + bed move can start mid-pickup. An arm agent must claim `bambu_a1_01` before + reaching over the plate and release it once the arm is clear again. If you + see the claim held by someone else, do not move the bed. - **Gates:** the claim (423); an idle printer reporting no error and no gateway job in flight (412, and `position_bed` is missing from `allowed_actions`); an edge-verified identity (403); for an agent, A1 agent diff --git a/src/bambu_server/profiles.py b/src/bambu_server/profiles.py index 9b15bc9..ed7702f 100644 --- a/src/bambu_server/profiles.py +++ b/src/bambu_server/profiles.py @@ -21,7 +21,7 @@ from pydantic import BaseModel, Field from .backend import EXTERNAL_SPOOL_ID -from .config import AmsPolicy, MachineLimits, PrinterDefinition, TrayColorLabel +from .config import AmsPolicy, BedPositions, MachineLimits, PrinterDefinition, TrayColorLabel from .filament_colors import ColorSource, tray_color_label if TYPE_CHECKING: # pragma: no cover - typing only @@ -120,6 +120,9 @@ class MachineProfile(BaseModel): chamber_temperature_c: float | None = None limits: MachineLimits = Field(default_factory=MachineLimits) ams: AmsPolicy = Field(default_factory=AmsPolicy) + #: Named positions for ``position_bed`` (Bambu A1 only) and the operator's + #: standing arm-clear declaration, when made; None where the verb is absent. + bed_positions: BedPositions | None = None observed: ObservedMachineState = Field(default_factory=ObservedMachineState) warnings: list[str] = Field(default_factory=list) @@ -186,6 +189,7 @@ def build_profile( chamber_temperature_c=declared.chamber_temperature_c, limits=declared.limits, ams=declared.ams, + bed_positions=definition.bed_positions, observed=observed, warnings=warnings, ) diff --git a/tests/test_position_bed.py b/tests/test_position_bed.py index 87d0ddd..2554468 100644 --- a/tests/test_position_bed.py +++ b/tests/test_position_bed.py @@ -230,3 +230,32 @@ def test_the_backend_sends_a_y_only_absolute_move() -> None: with pytest.raises(PrinterCommandError): backend.move_bed_y(*bad) assert len(sent) == 1 + + +def test_the_profile_publishes_positions_and_the_arm_clear_declaration( + settings: Settings, backends: dict[str, FakeBackend], monkeypatch +) -> None: + built = _settings(settings, monkeypatch) + payload = built.model_dump(mode="json") + a1 = next(p for p in payload["printers"] if p["id"] == A1) + a1["bed_positions"]["arm_clear"] = { + "declared_by": "yang", "declared_on": "2026-11-05", + "statement": "The arm is always clear of the A1's bed travel.", + } + app = create_app( + settings=Settings.model_validate(payload), + backend_factory=lambda definition, _c: backends[definition.id], + ) + with TestClient(app) as test_client: + profile = test_client.get(f"/printers/{A1}/profile").json() + other = test_client.get(f"/printers/{X1}/profile").json() + positions = profile["bed_positions"] + assert (positions["inspect_y_mm"], positions["pickup_y_mm"]) == (128, 250) + assert positions["arm_clear"]["declared_by"] == "yang" + assert positions["arm_clear"]["declared_on"] == "2026-11-05" + assert other["bed_positions"] is None + + +def test_without_a_declaration_the_profile_says_none(client: TestClient) -> None: + positions = client.get(f"/printers/{A1}/profile").json()["bed_positions"] + assert positions["arm_clear"] is None