From c949c541bfa53b188a691afbc1cfcf961ab544f0 Mon Sep 17 00:00:00 2001 From: Yang Cao Date: Thu, 5 Nov 2026 05:29:20 +0000 Subject: [PATCH] feat: publish the A1 bed positions and a standing arm-clear declaration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Yang declared on 2026-11-05 that the robot arm is always clear of the A1's bed travel. `bed_positions.arm_clear` ({declared_by, declared_on, statement}) records that in the gateway config, and GET /printers/{id}/profile now publishes `bed_positions` (inspect/pickup Y, feed, declaration) so an agent can base position_bed's `bed_path_clear` on it instead of asking before every move (ac-organic-lab §1.3, amended in #105). The declaration holds while the arm reaches over the plate only under the A1's claim. Removing it from the config withdraws it. Agent guide, API reference, README, example config and AGENT_RULES.md rule 1 updated. Co-Authored-By: Claude Opus 5.5 --- AGENT_RULES.md | 7 ++++++- README.md | 19 ++++++++++++++++++ docs/API_REFERENCE.md | 8 +++++++- printers.example.yaml | 4 ++++ src/bambu_server/config.py | 17 ++++++++++++++++ src/bambu_server/docs/AGENT_GUIDE.md | 18 +++++++++++++---- src/bambu_server/profiles.py | 6 +++++- tests/test_position_bed.py | 29 ++++++++++++++++++++++++++++ 8 files changed, 101 insertions(+), 7 deletions(-) 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