axiometa-cli 2.0.0__tar.gz → 2.0.2__tar.gz

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.4
 Name: axiometa-cli
-Version: 2.0.0
+Version: 2.0.2
 Summary: Axiometa hardware truths and upload methods, for your editor and your AI.
 Author-email: Axiometa <dr.dumcius@gmail.com>
 Project-URL: Homepage, https://axiometa.io
-Project-URL: Source, https://github.com/axiometa/axiometa-studio/tree/main/axiometa-cli
 Project-URL: Studio, https://studio.axiometa.io
 Keywords: hardware,ai,mcp,esp32,nrf52840,arduino,iot,cli,maker,embedded
 Classifier: Development Status :: 4 - Beta
@@ -59,7 +58,7 @@ Add `--json` to any of them. That is the form an agent wants.
 
 | | |
 |---|---|
-| `provision` | install the private toolchain |
+| `provision` | install the private toolchain (~7 GB, 15-20 min, once per machine) |
 | `devices` | what is plugged in |
 | `compile <dir> -b <board>` | build with the right target, profile and libraries |
 | `upload <dir> -b <board>` | build and put it on the board |

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/README.md

@@ -37,7 +37,7 @@ Add `--json` to any of them. That is the form an agent wants.
 
 | | |
 |---|---|
-| `provision` | install the private toolchain |
+| `provision` | install the private toolchain (~7 GB, 15-20 min, once per machine) |
 | `devices` | what is plugged in |
 | `compile <dir> -b <board>` | build with the right target, profile and libraries |
 | `upload <dir> -b <board>` | build and put it on the board |

axiometa_cli-2.0.2/axiometa_cli/agnostic.py

@@ -0,0 +1,162 @@
+"""Separate the CLI's knowledge from Studio's surface. Build-time only — nothing calls this at runtime.
+
+backend/knowledge/ is authored for Studio and is never edited for our sake, so this is the one place
+that states the seam. Two rules, and the difference between them is the whole design:
+
+  DELETE what would silently produce a broken build. A %%TOKEN%% is a hole Studio's build fills;
+  nothing fills it here, so a sketch carrying one compiles clean and then does not work. Those
+  strings go, and an entry naming the integrations relay goes whole.
+
+  RENAME Studio's own surfaces. "the Studio serial box", "the setup tab", "the Upload button" are
+  instructions to use a UI that does not exist outside the browser. The RULE around each is real —
+  print the IP because the page's console is invisible, encode the MT: payload directly or a
+  controller cannot scan it, declare the bigger partition or a Matter build overflows — so the rule
+  survives and only the surface changes.
+
+What is NOT touched: anything about the hardware. Pins, buses, addresses, libraries, init, timing,
+silicon gotchas all ship exactly as written. An earlier version of this file tried to reword those
+too and became twenty exact-string substitutions that went stale the moment anyone edited a
+sentence. A wrong noun costs nothing; a rule lost to a stale pattern costs the build.
+
+The list below is deliberately short and deliberately EXACT-STRING. No \\bStudio\\b regex: the nRF
+board package legitimately names "Seeed-Studio/Adafruit_nRF52_Arduino", and a pattern would corrupt
+an upstream vendor path.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+# In CODE a credential token becomes an obvious literal; every agent fills a YOUR_* value unprompted.
+_CREDENTIALS = {
+    "%%WIFI_SSID%%": "YOUR_WIFI_SSID",
+    "%%WIFI_PASSWORD%%": "YOUR_WIFI_PASSWORD",
+    "%%WIFI_PASS%%": "YOUR_WIFI_PASSWORD",
+}
+# A backend capability the CLI does not ship. An entry naming one is dropped whole.
+_BACKEND = ("%%RELAY_URL%%", "%%DEVICE_KEY%%")
+
+_ANY_TOKEN = re.compile(r"%%[A-Z_]+%%")
+
+# Keys whose strings are CODE (tokens get a literal). Elsewhere a token means the string is ABOUT
+# the substitution, so the string goes.
+_CODE_KEYS = {"init", "snippet", "includes", "example"}
+
+# Studio surfaces, stated as instructions. Keep the requirement, drop the UI.
+_RENAME = (
+    # The USB serial peer. `Serial` is `Serial` wherever it is plugged in.
+    ("`Serial`, the link to Studio", "`Serial`, the link to the host"),
+    ("the USB-CDC link to Studio", "the USB-CDC link to the host"),
+    ("USB-CDC link to Studio", "USB-CDC link to the host"),
+    ("the USB link to Studio", "the USB link to the host"),
+    ("Studio's serial link and every example use 115200",
+     "every example uses 115200"),
+    ("the user reads it in the Studio serial box; you read it with read_serial",
+     "the user reads it in a serial monitor; you read it with read_serial"),
+    # A button in a browser. The requirement — declare the bigger partition — is real.
+    ("so the Upload button builds a big-enough app slot", "so the build gets a big-enough app slot"),
+    # Studio tabs. The MT: payload rule is a real contract with whatever scans the QR.
+    ("The setup tab MUST encode that MT: payload directly into the QR",
+     "Whatever renders the QR MUST encode that MT: payload directly"),
+    ("Defensive: if the tab receives a URL, take its data= param before encoding.",
+     "Defensive: if what you receive is a URL, take its data= param before encoding."),
+    ("print it to serial and surface it in the Matter Setup tab",
+     "print it to serial and surface it wherever the pairing QR is shown"),
+    ("A Matter build is plain files: sketch.ino prints its pairing code over serial "
+     "(MATTER_QR: / MATTER_CODE:), browser/MatterSetup.html renders the live pairing QR from those "
+     "lines, and the walkthrough goes in reports/MatterSetup.md.",
+     "A Matter build is plain files: sketch.ino prints its pairing code over serial "
+     "(MATTER_QR: / MATTER_CODE:), and whatever surface you build reads those lines to render the "
+     "live pairing QR."),
+    ("invisible to you and to Studio", "invisible to you and to your tools"),
+    ("Studio's serial link is fixed at 115200", "the serial link is fixed at 115200"),
+    ("verbatim placeholder — Studio fills it", "fill in the network's SSID"),
+    ("Studio parses these lines to draw the pairing QR",
+     "whatever watches the serial channel draws the pairing QR from these lines"),
+    # A settings dialog that does not exist here; the substitution behind it is already stripped.
+    ("WiFi credentials are set by the user in Studio's WiFi settings and baked into the sketch when "
+     "you GENERATE it.",
+     "WiFi credentials are baked into the sketch when you GENERATE it, so ask for them first."),
+    ("A one-click Studio push is not wired yet: frame OTA as 'update from your browser', never "
+     "'Studio pushes automatically'.",
+     "Frame OTA as 'update from your browser', never as something that pushes automatically."),
+)
+
+
+def _rename(s: str) -> str:
+    for old, new in _RENAME:
+        s = s.replace(old, new)
+    return s
+
+
+def _code(s: str):
+    if any(t in s for t in _BACKEND):
+        return None
+    for tok, lit in _CREDENTIALS.items():
+        s = s.replace(tok, lit)
+    return _rename(s) if not _ANY_TOKEN.search(s) else None
+
+
+def _prose(s: str):
+    # Any %% at all: the tree writes things like "it still holds raw %%...%%", which a
+    # %%[A-Z_]+%% pattern walks straight past.
+    return None if "%%" in s else _rename(s)
+
+
+def _walk(node, code: bool = False, root: bool = False):
+    if isinstance(node, str):
+        return _code(node) if code else _prose(node)
+    if isinstance(node, list):
+        return [c for c in (_walk(v, code) for v in node) if c is not None]
+    if isinstance(node, dict):
+        # An ENTRY naming a capability we do not ship goes whole. Never the root: it contains every
+        # entry, so testing it recursively would discard the entire part.
+        if not root and any(t in json.dumps(node) for t in _BACKEND):
+            return None
+        out = {}
+        for k, v in node.items():
+            c = _walk(v, code=(k in _CODE_KEYS))
+            if c is not None:
+                out[k] = c
+        return out
+    return node
+
+
+def transform_metadata(text: str) -> str:
+    try:
+        data = json.loads(text)
+    except Exception:
+        return text
+    cleaned = _walk(data, root=True)
+    if not isinstance(cleaned, dict):
+        return text
+    return json.dumps(cleaned, indent=2, ensure_ascii=False) + "\n"
+
+
+# APPENDED to each Arduino contract. A real headless run lost a compile round-trip to
+# `uint8_t index = 0`: Arduino.h pulls in newlib's <strings.h>, which declares
+# char *index(const char*, int), and the cascading errors point at the USE sites rather than the
+# name. Same species as the min()/max() and auto-prototype rules the contract already carries — an
+# ordinary C++ name this toolchain has already spent.
+#
+# It is added HERE, not authored upstream, because backend/knowledge is Studio's and live. If it
+# ever lands there, this appender finds its own text already present and does nothing.
+_RESERVED_RULE = """
+
+Names the toolchain has already taken. `Arduino.h` pulls in newlib's `<strings.h>` and `<math.h>`, so a few ordinary-looking identifiers are already declared at global scope and redeclaring one fails the build: `index` (`char *index(const char*, int)`), `y0` / `y1` / `yn` and `j0` / `j1` / `jn` (Bessel functions), and the `B0`-`B11111111` binary constants. The error names the redeclaration, but the errors after it point at the USE sites, which reads as a type problem somewhere else entirely. Prefix or rename instead — `colorIndex`, `idx`, `currentIndex` — and never at file scope, where the clash is guaranteed."""
+
+
+def transform(relpath: str, text: str) -> str:
+    """One knowledge file, in its shipped form. metadata.json gets the structural pass (entries
+    dropped, code told apart from prose); every other text file gets the rename, because a Studio
+    surface reaches an agent just as well from a contract as from a coding note."""
+    if relpath.endswith("metadata.json"):
+        return transform_metadata(text)
+    if "%%" in text:
+        # Prose files: drop only the lines that name a token, never a whole paragraph — losing a
+        # toolchain law silently is worse than carrying one sentence that does not apply.
+        text = "\n".join(l for l in text.splitlines() if "%%" not in l) + "\n"
+    text = _rename(text)
+    if relpath.endswith("firmware/contract.md") and "already taken" not in text:
+        text = text.rstrip() + _RESERVED_RULE + "\n"
+    return text

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/cli.py

@@ -20,6 +20,7 @@ Two jobs, for someone else's AI working in someone else's repo:
       axiometa devices
       axiometa compile ./firmware -b genesis-one --parts AX22-0005
       axiometa upload  ./firmware -b genesis-one --parts AX22-0005
+      axiometa monitor                              what the board is printing
 
       axiometa mcp       the same, for clients that speak MCP
 
@@ -208,7 +209,7 @@ def cmd_compile(args):
         ui.err(f"no {sub['device_program']} (or a single {ext} file) in {src}.")
         sys.exit(2)
     # arduino-cli needs <folder>/<folder>.ino; stage so any filename in the user's repo works.
-    src = core.stage(src, entry, ext)
+    real, src = src, core.stage(src, entry, ext)
     fqbn = core.fqbn_with_options(sub, _options_arg(args.option))
     if args.print_command:
         # The escape hatch. Everything this tool knows that you could not derive is in this one
@@ -222,8 +223,9 @@ def cmd_compile(args):
     if failed:
         ui.warn("could not install: " + ", ".join(failed))
     r = core._run(toolchain.ac_cmd("compile", "--fqbn", fqbn, str(src)),
-                  on_line=lambda l: print(ui.c("  " + l, "grey")), env=toolchain.env())
-    (ui.ok if r.ok else ui.err)("compiled" if r.ok else r.detail)
+                  on_line=lambda l: print(ui.c("  " + core.unstage_paths(l, src, real), "grey")),
+                  env=toolchain.env())
+    (ui.ok if r.ok else ui.err)("compiled" if r.ok else core.unstage_paths(r.detail, src, real))
     sys.exit(0 if r.ok else 1)
 
 
@@ -268,6 +270,21 @@ def cmd_login(args):
     ui.ok(f"key saved to {toolchain.save_key(args.key)}")
 
 
+def cmd_monitor(args):
+    """Stream the serial channel. Passive by default — opening will not reset a running board."""
+    port = args.port or core.pick_port(None)
+    if not port:
+        ui.err("no serial device. Plug the board in, or pass --port.")
+        sys.exit(1)
+    ui.step(f"reading {port} at {args.baud} for {args.seconds}s"
+            + (" (resetting first)" if args.reset else ""))
+    r = core.read_serial(port, baud=args.baud, seconds=args.seconds, reset=args.reset,
+                         on_line=lambda l: print(ui.c("  " + l, "cyan")))
+    if not r.ok:
+        ui.err(r.detail)
+        sys.exit(1)
+
+
 def cmd_mcp(args):
     from . import mcp
     sys.exit(mcp.serve())
@@ -332,6 +349,13 @@ def build_parser() -> argparse.ArgumentParser:
     lg.add_argument("key", nargs="?", help="the axm_... key; omit to show the stored one")
     lg.set_defaults(func=cmd_login)
 
+    mo = sub.add_parser("monitor", help="read what the board is printing")
+    mo.add_argument("-p", "--port", help="serial port; autodetected if omitted")
+    mo.add_argument("--seconds", type=float, default=10.0)
+    mo.add_argument("--baud", type=int, default=115200)
+    mo.add_argument("--reset", action="store_true", help="restart the sketch to catch boot output")
+    mo.set_defaults(func=cmd_monitor)
+
     sub.add_parser("mcp", help="the same tools over MCP (stdio)").set_defaults(func=cmd_mcp)
     return p
 

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/core.py

@@ -289,6 +289,115 @@ def stage(source: Path, entry: Path, ext: str) -> Path:
     return staged
 
 
+NL = b"\n"
+
+
+def read_serial(port: str, baud: int = 115200, seconds: float = 5.0,
+                reset: bool = False, on_line=None) -> DeployResult:
+    """Read the board's serial output for `seconds`.
+
+    THE OPEN MUST NOT ASSERT DTR. pyserial raises DTR on open by default, and on an ESP32-S3 the USB
+    is native CDC — the ROM reads the DTR/RTS line states as a reset request, so a plain
+    Serial(port) can drop a running board into the download stub. The board then sits in "waiting for
+    download" and prints nothing, which reads as a dead sketch. Building the object unopened, setting
+    both lines low, and only then opening is what makes this observation passive.
+
+    RE-ENUMERATION IS EXPECTED, NOT AN ERROR. Native USB means the CDC device IS the firmware: any
+    reset tears the USB device down and the port disappears for a moment before coming back. A read
+    that treats a vanished port as failure reports "board died" for a board that is booting normally.
+    So a disappearance inside the window is waited out and the port reopened.
+
+    `reset` pulses RTS with DTR held LOW. That combination is a run-the-app reset; DTR HIGH with RTS
+    is what the ROM reads as enter-the-bootloader, which is the trap on the other side.
+    """
+    try:
+        import serial
+        from serial import SerialException
+    except Exception:
+        return DeployResult(False, "pyserial is not installed.", [])
+    if not port:
+        return DeployResult(False, "no serial port. Plug the board in, or pass one explicitly.", [])
+
+    def _open():
+        s = serial.Serial()
+        s.port = port
+        s.baudrate = baud
+        s.timeout = 0.2
+        s.dtr = False          # both LOW before the port exists: see above
+        s.rts = False
+        s.open()
+        return s
+
+    lines: list = []
+    deadline = time.monotonic() + max(0.5, seconds)
+    try:
+        ser = _open()
+    except SerialException as e:
+        return DeployResult(False, f"could not open {port}: {e}", [])
+
+    if reset:
+        try:
+            ser.dtr = False
+            ser.rts = True
+            time.sleep(0.1)
+            ser.rts = False
+        except Exception:
+            pass               # a port that will not take line changes still reads fine
+
+    buf = b""
+    while time.monotonic() < deadline:
+        try:
+            chunk = ser.read(256)
+        except (SerialException, OSError):
+            # The device went away — a reset re-enumerating, not a failure. Reopen until the window
+            # closes; only give up when time actually runs out.
+            try:
+                ser.close()
+            except Exception:
+                pass
+            ser = None
+            while time.monotonic() < deadline and ser is None:
+                time.sleep(0.25)
+                try:
+                    ser = _open()
+                except SerialException:
+                    ser = None
+            if ser is None:
+                break
+            continue
+        if not chunk:
+            continue
+        buf += chunk
+        while NL in buf:
+            raw, buf = buf.split(NL, 1)
+            line = raw.decode("utf-8", "replace").rstrip("\r")
+            lines.append(line)
+            if on_line:
+                on_line(line)
+    if buf:
+        lines.append(buf.decode("utf-8", "replace").rstrip("\r"))
+    try:
+        ser.close()
+    except Exception:
+        pass
+    return DeployResult(True, "\n".join(lines), [])
+
+
+def unstage_paths(text: str, staged: Path, source: Path) -> str:
+    r"""Rewrite staged paths in toolchain output back to the user's own directory.
+
+    We compile a COPY under ~/.axiometa/build/<name>/ because arduino-cli demands
+    <folder>/<folder>.ino. That is our business, not the caller's: a compiler error citing
+    ~/.axiometa/build/sketch/sketch.ino:22 sends someone hunting for a file they never wrote, in a
+    directory they did not know existed. A real first run hit exactly that — the error was correct
+    and the path was ours. Point every diagnostic back at the real source."""
+    if not text:
+        return text
+    for a, b in ((str(staged), str(source)), (staged.as_posix(), source.as_posix())):
+        text = text.replace(a, b)
+    return text
+
+
 def arduino_deploy(sketch_dir: Path, fqbn: str, port: str | None, on_line=None,
                    libraries: list | None = None) -> DeployResult:
     """Arduino: one verb, always persisted. Compile + upload with OUR arduino-cli, OUR config and OUR

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/knowledge_client.py

@@ -30,6 +30,44 @@ _DEFAULT_BACKEND = "https://cli.axiometa.io"   # axiometa-cli's own service, not
 
 _resolved: Path | None = None        # memoize within a run so we hit the network at most once
 _resolved_done = False
+_UPDATE: str | None = None           # newer version the service advertised, if any
+
+
+def _newer(latest: str | None, running: str) -> bool:
+    """True when `latest` is a higher release than what is running. Dev installs report 0.0.0+dev,
+    which compares as older than anything real — correct: a checkout should still be told."""
+    def parts(v):
+        out = []
+        for chunk in (v or "").split("+")[0].split("."):
+            digits = "".join(c for c in chunk if c.isdigit())
+            out.append(int(digits) if digits else 0)
+        return out
+    try:
+        return bool(latest) and parts(latest) > parts(running)
+    except Exception:
+        return False
+
+
+def ping() -> None:
+    """Tell the service this session started. Best effort and non-blocking in spirit: it is
+    analytics, so it must never delay or fail a tool call. No key, no network, no problem."""
+    try:
+        from . import toolchain, __version__
+        k = toolchain.key()
+        if not k:
+            return
+        req = urllib.request.Request(
+            _backend() + "/api/ping",
+            headers={"Authorization": f"Bearer {k}", "X-Axiometa-CLI": __version__})
+        urllib.request.urlopen(req, timeout=5).close()
+    except Exception:
+        pass
+
+
+def update_available() -> str | None:
+    """The newer version seen on the last fetch, or None. Read by the CLI and by list_boards, so the
+    agent learns about it from a call it was making anyway."""
+    return _UPDATE
 
 
 def _backend() -> str:
@@ -52,6 +90,10 @@ def boards_dir(force: bool = False) -> Path | None:
         req = urllib.request.Request(_backend() + "/api/knowledge/boards", headers=headers)
         with urllib.request.urlopen(req, timeout=30) as r:
             data = json.loads(r.read().decode())
+        global _UPDATE
+        from . import __version__
+        latest = data.get("cli_latest")
+        _UPDATE = latest if _newer(latest, __version__) else None
         version = str(data.get("version") or "")
         fresh = (_BOARDS.is_dir() and _STAMP.is_file()
                  and _STAMP.read_text(encoding="utf-8").strip() == version)

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/mcp.py

@@ -11,13 +11,14 @@ the protocol's place for "how to work with this server". That is why nothing has
 anyone's agent: the hardware rules ship with the tools that need them. The model on the other end
 writes the code.
 
-Eight tools, which is the whole surface — file editing and shell are the client's own job:
+Nine tools, which is the whole surface — file editing and shell are the client's own job:
 
     list_boards        what exists, and what language each speaks
     get_board          one board: pins, ports, fqbn, build options, contract, electrical fabric
     list_modules       the catalog for a board: every module, display, onboard radio
     get_module         one module: real pins, i2c address, library name+version, init, coding rules
     list_devices       what is plugged in
+    read_serial        what the running firmware is actually printing
     provision          install the toolchain (once per machine)
     compile            build for a board, with its build profile and libraries
     upload             build and flash it to the connected board
@@ -66,7 +67,9 @@ Tool contract:
   libraries get installed, and it is read from no file — pass it. `libraries` adds anything else.
 - provision installs the toolchain and must run once on a machine before its first compile.
 - Read the real compiler and flasher output and react to it. Never report success because code was
-  written."""
+  written. A clean compile and a clean upload still say nothing about whether the sketch does what
+  was asked — read_serial is how you find that out, and it is the last step of a build, not an
+  optional extra."""
 
 _BOARD_ARG = {"board_id": {"type": "string", "description": "Axiometa board id, e.g. genesis-one"}}
 _LANG_ARG = {"language": {"type": "string",
@@ -89,7 +92,8 @@ TOOLS = [
         "name": "list_boards",
         "description": "Every Axiometa board, with its silicon, port count and available languages. "
                        "Call this first: an Axiometa board is a custom board package, not a generic "
-                       "dev board, and its pins do not match anything in a stock core.",
+                       "dev board, and its pins do not match anything in a stock core. Also "
+                       "reports `provisioned`: when false, run provision before any compile.",
         "inputSchema": {"type": "object", "properties": {}},
     },
     {
@@ -136,6 +140,24 @@ TOOLS = [
                        "core, sketchbook or Python environment the user already has.",
         "inputSchema": {"type": "object", "properties": {}},
     },
+    {
+        "name": "read_serial",
+        "description": "Read the board's serial output for a few seconds and return the lines. This "
+                       "is how you observe what the firmware actually did — a compile that succeeded "
+                       "and an upload that succeeded still tell you nothing about whether the sketch "
+                       "works. Opening is passive: it will not reset a running board. Pass reset=true "
+                       "to restart the sketch and capture its boot output from the first line.",
+        "inputSchema": {"type": "object",
+                        "properties": {
+                            "port": {"type": "string",
+                                     "description": "serial port; autodetected if omitted"},
+                            "seconds": {"type": "number",
+                                        "description": "how long to listen (default 5)"},
+                            "baud": {"type": "number", "description": "default 115200"},
+                            "reset": {"type": "boolean",
+                                      "description": "restart the sketch first, to catch boot output"},
+                        }},
+    },
     {
         "name": "compile",
         "description": "Compile a directory for an Axiometa board using the private toolchain: the "
@@ -173,12 +195,26 @@ def _firmware_text(board_id: str, language: str, name: str) -> str:
     return f.read_text(encoding="utf-8") if f and f.is_file() else ""
 
 
+def _update() -> str | None:
+    from . import knowledge_client
+    core.load_boards()                      # ensures a fetch has happened this run
+    return knowledge_client.update_available()
+
+
 def t_list_boards() -> dict:
-    return {"boards": [
+    return {
+        # Answers "can I build here yet?" without running provision or eating a compile failure.
+        "provisioned": toolchain.provisioned(),
+        # And "am I current?" — the service advertises the newest release on the knowledge fetch,
+        # so an agent finds out here rather than never.
+        **({"update_available": _upd, "update_with": "pip install -U axiometa-cli"}
+           if (_upd := _update()) else {}),
+        "boards": [
         {"id": b["id"], "name": b.get("name"), "silicon": b.get("silicon"), "mcu": b.get("mcu"),
          "ports": b.get("port_count"), "logic_voltage": b.get("logic_voltage"),
          "languages": b.get("languages_available") or [], "default_language": b.get("default_language")}
-        for b in core.load_boards().values()]}
+            for b in core.load_boards().values()],
+    }
 
 
 def t_get_board(board_id: str, language: str | None = None) -> dict:
@@ -235,6 +271,15 @@ def t_list_devices() -> dict:
             "hint": detect.permission_hint() if not devs else None}
 
 
+def t_read_serial(port: str | None = None, seconds: float = 5.0, baud: int = 115200,
+                  reset: bool = False) -> dict:
+    p = port or core.pick_port(None)
+    if not p:
+        return {"ok": False, "error": "no serial device found; plug the board in or pass port"}
+    r = core.read_serial(p, baud=int(baud), seconds=float(seconds), reset=bool(reset))
+    return {"ok": r.ok, "port": p, "output": r.detail}
+
+
 def t_provision() -> dict:
     """Long-running by nature — a first run downloads a couple of gigabytes. Output is returned whole
     so the caller can read what actually happened rather than a boolean."""
@@ -302,6 +347,7 @@ _IMPL = {
     "list_modules": t_list_modules,
     "get_module": t_get_module,
     "list_devices": t_list_devices,
+    "read_serial": t_read_serial,
     "provision": t_provision,
     "compile": t_compile,
     "upload": t_upload,
@@ -322,6 +368,14 @@ def handle(msg: dict):
     rid, method, params = msg.get("id"), msg.get("method"), msg.get("params") or {}
 
     if method == "initialize":
+        # One ping per session, on a background thread so a slow or unreachable service cannot
+        # delay the handshake the client is waiting on.
+        try:
+            import threading
+            from . import knowledge_client
+            threading.Thread(target=knowledge_client.ping, daemon=True).start()
+        except Exception:
+            pass
         return _result(rid, {
             "protocolVersion": PROTOCOL_VERSION,
             "capabilities": {"tools": {}},

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/provision.py

@@ -217,6 +217,74 @@ def _inject_board_packages() -> bool:
     return ok
 
 
+# The ESP32 platform declares 18 tool dependencies because it supports every ESP32 variant Espressif
+# makes. arduino-cli installs all of them — toolsDependencies are the platform's declaration, not a
+# setting, which is why deleting one and re-running brings it straight back. So the trim happens
+# AFTER the install, once, and it is decided by the BOARDS rather than a list.
+#
+# Measured on a real install: 6.53 GB extracted, of which ~3.4 GB is for silicon that no Axiometa
+# board uses — esp-rv32 alone is 2.3 GB of RISC-V compiler for chips we do not sell.
+_ARCH_COMPILER = {"xtensa": "esp-x32", "riscv": "esp-rv32"}
+_DEBUG_TOOLS = ("xtensa-esp-elf-gdb", "riscv32-esp-elf-gdb", "openocd-esp32")
+
+
+def _prune_unused_tools(boards: dict) -> None:
+    tools_dir = toolchain.data_dir() / "packages" / "esp32" / "tools"
+    if not tools_dir.is_dir():
+        return
+    # ONLY esp32 silicons decide what the esp32 platform needs. An nRF board is ARM, served by a
+    # different package with its own tools; letting it vote here would keep the RISC-V compiler
+    # alive for a board that will never touch this toolchain.
+    have = {s for s in (str(b.get("silicon") or "").lower() for b in boards.values())
+            if s.startswith("esp32")}
+    if not have:
+        return
+    # Espressif's Xtensa parts are esp32, esp32s2, esp32s3; everything newer is RISC-V.
+    arches = {"xtensa" if s in ("esp32", "esp32s2", "esp32s3") else "riscv" for s in have}
+
+    freed, dropped = 0, []
+    for entry in sorted(p for p in tools_dir.iterdir() if p.is_dir()):
+        name = entry.name
+        why = None
+        if name in _DEBUG_TOOLS:
+            why = "debugger"
+        elif name.endswith("-libs") and name[:-5] not in have:
+            why = "unused silicon"
+        else:
+            for arch, tool in _ARCH_COMPILER.items():
+                if name == tool and arch not in arches:
+                    why = f"no {arch} board"
+        if not why:
+            continue
+        try:
+            freed += sum(f.stat().st_size for f in entry.rglob("*") if f.is_file())
+        except OSError:
+            pass
+        shutil.rmtree(entry, ignore_errors=True)
+        dropped.append(f"{name} ({why})")
+    if dropped:
+        ui.ok(f"trimmed {freed / 1e9:.1f} GB of tools these boards cannot use")
+        for d in dropped:
+            ui.hint(f"  {d}")
+
+
+def _drop_download_cache() -> None:
+    """Delete toolchain/downloads/ once everything is installed.
+
+    arduino-cli keeps every archive it fetched alongside the copy it extracted, so a finished
+    provision carries ~2 GB of zips whose contents are already on disk. Nothing reads them again: a
+    re-provision that needs one re-downloads it. A real install measured 8.63 GB with this cache and
+    6.7 GB without, which is the difference between "large" and "why is my disk full".
+    """
+    dl = toolchain.downloads_dir()
+    if not dl.is_dir():
+        return
+    freed = sum(f.stat().st_size for f in dl.rglob("*") if f.is_file())
+    shutil.rmtree(dl, ignore_errors=True)
+    if freed:
+        ui.ok(f"removed {freed / 1e9:.1f} GB of download archives (already extracted)")
+
+
 # ── libraries (into OUR sketchbook) ──────────────────────────────────────────────────────────────
 def _catalog_libraries(boards: dict) -> list:
     """Every Arduino library the CATALOG declares, resolved from part metadata across all boards.
@@ -283,6 +351,9 @@ def provision(boards: dict, targets: set | None = None, firmware: str | None = N
 
     ok = (_ensure_arduino_cli() and _install_cores() and _inject_board_packages()
           and _install_libs(boards))
+    if ok:
+        _prune_unused_tools(boards)
+    _drop_download_cache()
 
     print()
     if ok:

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/toolchain.py

@@ -122,6 +122,24 @@ def installed() -> bool:
     return arduino_cli().is_file()
 
 
+def provisioned() -> bool:
+    """Whether this machine can actually build: our arduino-cli AND the pinned core with the
+    Axiometa board definitions in it. `installed()` alone is not enough — the binary can be there
+    with no core behind it, which fails at compile time with something cryptic.
+
+    Exists so an agent can ASK. Before this the only ways to find out were to run provision (an
+    eighteen-minute-looking no-op when it is already done) or to eat a compile failure."""
+    if not installed():
+        return False
+    boards_txt = (data_dir() / "packages" / "esp32" / "hardware" / "esp32"
+                  / ESP32_CORE_VERSION / "boards.txt")
+    try:
+        return boards_txt.is_file() and "axiometa_" in boards_txt.read_text(
+            encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+
+
 # ── invocation: our binary, our config, our directories ──────────────────────────────────────────
 def ac_cmd(*args: str) -> list:
     """An arduino-cli argv pinned to OUR installation. --config-file is not optional: it is what

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli/ui.py

@@ -64,22 +64,49 @@ def hint(msg: str) -> None:
 
 
 class Spinner:
+    """Progress for a long step.
+
+    On a TTY this is a spinner. Off one — which is every agent, CI job and piped log — it prints a
+    line when it starts and then a SIZE HEARTBEAT every 30s, because the alternative is what a real
+    headless run hit: `installing esp32:esp32@3.3.6` printed once and nothing followed for twelve
+    minutes. The agent could not tell working from hung, and ended up polling the install directory
+    itself to answer "how much longer". A number that moves is the whole fix.
+
+    `watch` is a directory to measure; without one the heartbeat just reports elapsed time."""
     """Progress for the long installs. Silent when stderr is not a tty, so a captured log stays
     readable instead of filling with control characters."""
 
-    def __init__(self, label: str):
+    def __init__(self, label: str, watch=None):
         self.label = label
+        self.watch = watch
         self._stop = threading.Event()
         self._thread = None
 
     def __enter__(self):
-        if _color():
-            self._thread = threading.Thread(target=self._spin, daemon=True)
-            self._thread.start()
-        else:
-            print(f"  {self.label} ...")
+        self._thread = threading.Thread(
+            target=self._spin if _color() else self._heartbeat, daemon=True)
+        if not _color():
+            print(f"  {self.label} ...", flush=True)
+        self._thread.start()
         return self
 
+    def _size(self) -> str:
+        if not self.watch:
+            return ""
+        try:
+            n = sum(f.stat().st_size for f in self.watch.rglob("*") if f.is_file())
+            return f" — {n / 1e9:.1f} GB on disk"
+        except Exception:
+            return ""
+
+    def _heartbeat(self) -> None:
+        """Non-TTY: one line every 30s. Slow enough not to spam a log, often enough that nobody has
+        to guess whether it died."""
+        waited = 0
+        while not self._stop.wait(30):
+            waited += 30
+            print(f"    {self.label} — {waited // 60}m{waited % 60:02d}s{self._size()}", flush=True)
+
     def _spin(self) -> None:
         frames = "|/-\\"
         i = 0

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli.egg-info/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.4
 Name: axiometa-cli
-Version: 2.0.0
+Version: 2.0.2
 Summary: Axiometa hardware truths and upload methods, for your editor and your AI.
 Author-email: Axiometa <dr.dumcius@gmail.com>
 Project-URL: Homepage, https://axiometa.io
-Project-URL: Source, https://github.com/axiometa/axiometa-studio/tree/main/axiometa-cli
 Project-URL: Studio, https://studio.axiometa.io
 Keywords: hardware,ai,mcp,esp32,nrf52840,arduino,iot,cli,maker,embedded
 Classifier: Development Status :: 4 - Beta
@@ -59,7 +58,7 @@ Add `--json` to any of them. That is the form an agent wants.
 
 | | |
 |---|---|
-| `provision` | install the private toolchain |
+| `provision` | install the private toolchain (~7 GB, 15-20 min, once per machine) |
 | `devices` | what is plugged in |
 | `compile <dir> -b <board>` | build with the right target, profile and libraries |
 | `upload <dir> -b <board>` | build and put it on the board |

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/axiometa_cli.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 axiometa_cli/__init__.py
 axiometa_cli/__main__.py
+axiometa_cli/agnostic.py
 axiometa_cli/cli.py
 axiometa_cli/core.py
 axiometa_cli/detect.py

{axiometa_cli-2.0.0 → axiometa_cli-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axiometa-cli"
-version = "2.0.0"
+version = "2.0.2"
 description = "Axiometa hardware truths and upload methods, for your editor and your AI."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -24,9 +24,11 @@ classifiers = [
 # from cli.axiometa.io and cached (knowledge_client.py).
 dependencies = ["pyserial>=3.5"]
 
+# No Source link: the repository is private, so the URL 404s for anyone who checks — and someone
+# auditing a package that touches USB and downloads a toolchain is exactly who checks. A dead link
+# reads worse than no link.
 [project.urls]
 Homepage = "https://axiometa.io"
-Source = "https://github.com/axiometa/axiometa-studio/tree/main/axiometa-cli"
 Studio = "https://studio.axiometa.io"
 
 [project.scripts]