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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion AGENT_RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion docs/API_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
4 changes: 4 additions & 0 deletions printers.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 17 additions & 0 deletions src/bambu_server/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
from __future__ import annotations

import os
from datetime import date
from pathlib import Path
from typing import Any, Literal

Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down
18 changes: 14 additions & 4 deletions src/bambu_server/docs/AGENT_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion src/bambu_server/profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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,
)
29 changes: 29 additions & 0 deletions tests/test_position_bed.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading