enginehall 2.0.0__py3-none-any.whl

pcba/mcp/altium_server.py

@@ -0,0 +1,1358 @@
+"""`enginehall altium mcp` — let an agent create and edit Altium projects, under supervision.
+
+A separate server from the review MCP (`enginehall mcp`), which stays read-only and six tools wide.
+This one drives Altium Designer through the Class C adapter in `pcba.adapters.altium_drive`,
+so it runs only on Windows with Altium open, and nothing on the review path imports it.
+
+Every write follows the change-plan workflow the repository uses for generated artefacts:
+
+    inspect → plan → preview → approve → apply → reinspect → verify → record
+
+- `altium_plan` validates typed operations, stores them under a plan id and returns a hash, a
+  preview (operation counts, the expected-versus-current netlist diff, an optional screenshot).
+- `altium_apply` runs a plan only when given that hash, then re-reads the result twice — Altium's
+  own compiled netlist and the engine's parser on the saved `.SchDoc` files — compares both with
+  the plan's expected nets, and appends a record to `<project folder>/.pcba/altium-changes.jsonl`.
+  The agent never trusts its own edit.
+
+Units: schematic coordinates in mils, PCB coordinates in millimetres (see `altium_ops`).
+"""
+
+from __future__ import annotations
+
+import base64
+import configparser
+import datetime as dt
+import hashlib
+import json
+import os
+import re
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable
+
+from pcba import __version__
+from pcba.adapters import altium_house, altium_ops, altium_outjob, altium_vcs
+from pcba.adapters.altium_drive import DriveError, Session, file_hashes
+from pcba.mcp.protocol import READ_ONLY, Server, tool_annotations
+from pcba.parsers.altium import netlist as engine_netlist
+from pcba.parsers.altium.records import SchDocError
+
+PCB_LENGTH_KEYS = {"x", "y", "width", "height", "hole", "w", "h", "x_origin", "y_origin", "copper", "mask", "paste",
+                   "dielectric", "overall", "standoff", "x1", "y1", "x2", "y2", "xc", "yc", "r", "diameter", "stroke",
+                   "box_left", "box_bottom", "box_right", "box_top", "x_before", "y_before", "height_before",
+                   "mid_w", "mid_h", "bottom_w", "bottom_h", "uncoupled_max"}
+# Replies of these library ops carry PCB lengths too (a footprint's model `overall`, `standoff`).
+PCB_LENGTH_OPS = ("pcb_", "footprint")
+MAX_ITEMS = 2000
+MAX_INLINE_IMAGE_BYTES = 8 * 1024 * 1024
+
+_session: Session | None = None
+_plans: dict[str, dict] = {}
+
+
+def session() -> Session:
+    global _session
+    if _session is None:
+        _session = Session()
+    return _session
+
+
+def _to_mm(units: int) -> float:
+    return round(units / altium_ops.UNITS_PER_MM, 4)
+
+
+def _convert(items: list[dict], limit: int | None = MAX_ITEMS) -> list[dict]:
+    out = []
+    for item in items[:limit]:
+        if str(item.get("name", "")).startswith(PCB_LENGTH_OPS):
+            # bool is an int in Python: flags such as "bottom" or "locked" must stay flags.
+            item = {k: (_to_mm(v) if k in PCB_LENGTH_KEYS and isinstance(v, int) and not isinstance(v, bool) else v)
+                    for k, v in item.items()}
+            if isinstance(item.get("layer"), int) and not isinstance(item["layer"], bool):
+                # The name an op takes ("top_overlay"); Altium's own label stays in layer_label.
+                item["layer_name"] = altium_ops.LAYER_BY_NUMBER.get(item["layer"], str(item["layer"]))
+        out.append(item)
+    return out
+
+
+def _reply(reply) -> dict:
+    data = reply.to_dict()
+    data["items"] = _convert(data["items"])
+    if len(reply.items) > MAX_ITEMS:
+        data["truncated"] = {"shown": MAX_ITEMS, "total": len(reply.items)}
+    return data
+
+
+# --- netlists ------------------------------------------------------------------------------
+
+
+def _altium_nets(items: list[dict]) -> dict[str, list[list[str]]]:
+    """Altium's DM netlist lists every unconnected pin as its own one-pin net; those are pins,
+    not nets, and are reported separately as `unconnected`."""
+    return {i["net"]: sorted(i["pins"]) for i in items if i.get("kind") == "net" and len(i["pins"]) > 1}
+
+
+def _altium_unconnected(items: list[dict]) -> list[list[str]]:
+    return sorted(i["pins"][0] for i in items if i.get("kind") == "net" and len(i["pins"]) == 1)
+
+
+def _normalise(nets: dict) -> dict[str, frozenset]:
+    return {name: frozenset(tuple(p) for p in pins) for name, pins in nets.items()}
+
+
+def diff_nets(expected: dict, actual: dict) -> dict:
+    """Compare two {net: [[designator, pin], ...]} maps by connectivity, then by name.
+
+    Two nets are the same when they connect the same pins. A net that matches by pins under a
+    different name is reported as `renamed`, not as missing — Altium names unlabelled nets
+    itself, and the agent cares first that the copper is right.
+    """
+    exp, act = _normalise(expected), _normalise(actual)
+    by_pins = {pins: name for name, pins in act.items()}
+    missing, renamed, wrong = [], [], []
+    matched_actual = set()
+    for name, pins in exp.items():
+        if name in act and act[name] == pins:
+            matched_actual.add(name)
+        elif pins in by_pins:
+            renamed.append({"expected": name, "actual": by_pins[pins]})
+            matched_actual.add(by_pins[pins])
+        elif name in act:
+            wrong.append({"net": name, "expected_only": sorted(pins - act[name]),
+                          "actual_only": sorted(act[name] - pins)})
+            matched_actual.add(name)
+        else:
+            missing.append({"net": name, "pins": sorted(pins)})
+    unexpected = [{"net": n, "pins": sorted(p)} for n, p in act.items() if n not in matched_actual]
+    return {
+        "match": not (missing or wrong or unexpected),
+        "missing": missing,
+        "wrong": wrong,
+        "renamed": renamed,
+        "unexpected": unexpected,
+    }
+
+
+def _engine_nets(sheets_dir: str | None) -> tuple[dict, dict]:
+    if not sheets_dir:
+        return {}, {}
+    nl = engine_netlist.extract_netlist(Path(sheets_dir))
+    data = engine_netlist.to_dict(nl)
+    return data["nets"], data
+
+
+def _netlist(project: str, sheets_dir: str | None = None, reopen: bool = False) -> dict:
+    """Both netlists of a project and their differences. Only an approved apply passes reopen:
+    reopening a stale project closes it, and closing saves its documents."""
+    netlist_op: dict[str, Any] = {"op": "project_netlist", "path": project}
+    if reopen:
+        netlist_op["reopen"] = True
+    reply = session().run([{"op": "project_open", "path": project}, netlist_op])
+    if not reply.ok:
+        return _reply(reply)
+    altium = _altium_nets(reply.items)
+    summary = next((i for i in reply.items if i.get("kind") == "summary"), {})
+    components = [i for i in reply.items if i.get("kind") == "component"]
+    violations = [{"level": i["level"], "text": i["text"], "objects": i.get("objects", [])}
+                  for i in reply.items if i.get("kind") == "violation"]
+    out = {"altium": {"nets": altium, "unconnected": _altium_unconnected(reply.items), "components": components,
+                      "summary": summary, "violations": violations}}
+    warnings = [i["text"] for i in reply.items if i.get("kind") == "warning"]
+    if warnings:
+        out["altium"]["warnings"] = warnings
+    if sheets_dir:
+        engine, data = _engine_nets(sheets_dir)
+        out["engine"] = {"nets": engine, "unconnected": data["unconnected"], "conflicts": data["conflicts"]}
+        out["engine_vs_altium"] = diff_nets(engine, altium)
+    return out
+
+
+def _fresh(project: str) -> dict | None:
+    """Make Altium compile what is on disk: close the project without saving and reopen it.
+
+    Altium compiles its in-memory documents, and scripted saves and removals do not refresh
+    them (an empty first compile, every part twice, old wiring after a redraw). This never
+    discards anything: it refuses when Altium reports an unsaved document, and it answers no
+    prompt (a prompt here means Altium's Modified flag was wrong), so the close then fails and
+    says which document Altium still holds. Returns an error payload, or None when refreshed."""
+    s = session()
+    state = s.run([{"op": "project_state", "path": project}])
+    if not state.ok:
+        return _reply(state)
+    if not any(i.get("kind") == "project" and i.get("open") for i in state.items):
+        return None  # not open: the project_open that follows compiles it from disk anyway
+    modified = [i["path"] for i in state.items if i.get("kind") == "document" and i.get("modified")]
+    modified += [i["project"] for i in state.items if i.get("kind") == "project" and i.get("modified")]
+    if modified:
+        return {"error": "Altium holds unsaved changes; save them (an approved plan with doc_save or pcb_save) or "
+                         "discard them (project_close with save 'none') before a fresh compile",
+                "modified": modified}
+    # Nothing is unsaved, so only Altium 365's server prompts may come ("Save changes to Server?" for
+    # documents saved but not committed): "Do nothing" commits nothing and discards nothing.
+    closed = s.run([{"op": "project_close", "path": project, "save": "none"}],
+                   answers=altium_ops.server_prompt_answers(altium_ops.folder_of(project), save_none=False))
+    if not closed.ok:
+        return {"error": "the project did not close without saving; Altium still holds changes", **_reply(closed)}
+    return None
+
+
+STALE_COMPILE = "no components compiled from a project with sheets"
+
+
+def tool_netlist(project: str, sheets_dir: str | None = None, fresh: bool = False) -> dict:
+    """Both netlists of a project and their differences. A read: never saves. `fresh` first makes
+    Altium compile the saved files (see `_fresh`); it refuses rather than discard anything.
+
+    Without `fresh`, a compile that came back empty for a project with sheets is retried fresh
+    once, when nothing is unsaved: measured on a project created in the session, the in-memory
+    compile returned no nets and no messages however often it ran, while the saved sheets held
+    both. With unsaved changes the empty answer stands, with the reason in `refresh_refused`."""
+    if fresh:
+        refused = _fresh(project)
+        if refused:
+            return refused
+    out = _netlist(project, sheets_dir)
+    if fresh and "altium" in out:
+        out["fresh"] = True
+        return out
+    warnings = out.get("altium", {}).get("warnings", [])
+    if any(w.startswith(STALE_COMPILE) for w in warnings):
+        refused = _fresh(project)
+        if refused:
+            out["refresh_refused"] = refused
+            return out
+        out = _netlist(project, sheets_dir)
+        if "altium" in out:
+            out["refreshed"] = True
+    return out
+
+
+# --- tools ---------------------------------------------------------------------------------
+
+
+def tool_status() -> dict:
+    s = session()
+    info = s.status()
+    if info.get("running"):
+        info["ping"] = s.ping()
+    return info
+
+
+def tool_recover(allow_restart: bool = False) -> dict:
+    s = session()
+    s.allow_restart = allow_restart
+    try:
+        return s.recover()
+    finally:
+        s.allow_restart = False
+
+
+def tool_read(ops: list[dict]) -> dict:
+    altium_ops.validate(ops)
+    if not altium_ops.is_read_only(ops):
+        bad = sorted({o["op"] for o in ops if o["op"] not in altium_ops.READ_ONLY})
+        return {"error": f"not read-only: {bad}; use altium_plan and altium_apply"}
+    if any(o["op"] == "project_netlist" and o.get("reopen") for o in ops):
+        # Reopening closes the project, and that close saves every document: not a read.
+        return {"error": "project_netlist with reopen is not a read; use altium_netlist with fresh: true"}
+    return _reply(session().run(ops))
+
+
+def _plan_hash(plan: dict) -> str:
+    keys = ("ops", "expect_nets", "project", "sheets_dir", "action", "allow_destructive")
+    canonical = json.dumps({k: plan.get(k) for k in keys}, sort_keys=True)
+    return hashlib.sha256(canonical.encode()).hexdigest()[:16]
+
+
+PLAN_ID = re.compile(r"^[0-9a-f]{10}$")
+
+
+def _plan_dir() -> Path | None:
+    """Plans are kept on disk next to the bridge exchange, so a plan survives a restarted server
+    (an approval must not be lost because the agent's client reconnected)."""
+    home = getattr(session(), "home", None)
+    return Path(home) / "plans" if home else None
+
+
+def _store_plan(plan_id: str, plan: dict) -> None:
+    _plans[plan_id] = plan
+    folder = _plan_dir()
+    if folder:
+        folder.mkdir(parents=True, exist_ok=True)
+        # Owner-only where the platform has modes; on Windows the file inherits the ACL of the
+        # drive's home. Either way the approval checks the content, not the file.
+        descriptor = os.open(folder / f"{plan_id}.json", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(plan))
+
+
+def _take_plan(plan_id: str) -> dict | None:
+    """The plan, removed from memory and disk: whatever happens next, it runs at most once."""
+    plan = _plans.pop(plan_id, None)
+    folder = _plan_dir()
+    if folder and isinstance(plan_id, str) and PLAN_ID.match(plan_id):
+        path = folder / f"{plan_id}.json"
+        if plan is None and path.is_file():
+            try:
+                plan = json.loads(path.read_text(encoding="utf-8"))
+            except ValueError:
+                plan = None
+        path.unlink(missing_ok=True)
+    return plan
+
+
+# Operations that make a design hierarchical, which the engine netlist does not model.
+HIERARCHY_OPS = {"sch_sheet_symbol", "sch_port"}
+
+
+def tool_plan(
+    ops: list[dict],
+    summary: str,
+    project: str | None = None,
+    sheets_dir: str | None = None,
+    expect_nets: dict | None = None,
+    screenshot: dict | None = None,
+    allow_destructive: bool = False,
+) -> dict:
+    """Validate and store a change plan; return its hash and a preview. Nothing is changed.
+
+    A plan that removes design content in bulk (unroute, component removal, clearing a layer or a
+    sheet) is refused unless `allow_destructive` says the reviewer means it: a full rebuild once
+    replaced a board's reviewed routing for what was a local change."""
+    altium_ops.render(ops)  # full validation, including every argument
+    risky = altium_ops.destructive(ops)
+    if risky and allow_destructive is not True:
+        return {"error": "this plan removes design content; for a local change keep the reviewed work and change "
+                         "only what must change. If the removal is intended, plan again with allow_destructive: true",
+                "destructive": risky}
+    plan = {"ops": ops, "expect_nets": expect_nets, "project": project, "sheets_dir": sheets_dir, "summary": summary,
+            "allow_destructive": bool(risky)}
+    plan_id = uuid.uuid4().hex[:10]
+    plan["hash"] = _plan_hash(plan)
+    _store_plan(plan_id, plan)
+    counts: dict[str, int] = {}
+    for op in ops:
+        counts[op["op"]] = counts.get(op["op"], 0) + 1
+    preview: dict[str, Any] = {"operations": len(ops), "by_type": counts}
+    if risky:
+        preview["destructive"] = risky
+    if expect_nets and sheets_dir and any(Path(sheets_dir).glob("*.SchDoc")):
+        current, _ = _engine_nets(sheets_dir)
+        preview["netlist_change"] = diff_nets(expect_nets, current)
+    if sheets_dir and any(op.get("op") in HIERARCHY_OPS for op in ops):
+        preview["warning"] = ("sheet symbols and ports make the design hierarchical, and the engine netlist treats "
+                              "every label as global: plan without sheets_dir to verify against Altium alone")
+    if screenshot:
+        preview["screenshot"] = tool_screenshot(**screenshot)
+    return {"plan_id": plan_id, "hash": plan["hash"], "summary": summary, "preview": preview,
+            "next": "show the preview to the reviewer, then call altium_apply with this plan_id and hash"}
+
+
+# What a tool call can raise and still be answered in band (see handle); an apply records these.
+IN_BAND = (DriveError, altium_ops.OpError, SchDocError, OSError, TypeError, ValueError, configparser.Error,
+            altium_vcs.VcsError)
+
+
+def _error_text(exc: Exception) -> str:
+    return f"{exc.code}: {exc}" if isinstance(exc, DriveError) else f"{type(exc).__name__}: {exc}"
+
+
+def _plan_action(tool: str, args: dict, summary: str, project: str | None) -> dict:
+    """A write that is not a typed operation (project creation, ECO, autoroute, outputs) is planned
+    like one: the tool validates its arguments and stores the call; altium_apply runs it."""
+    plan = {"action": {"tool": tool, "args": args}, "ops": [], "expect_nets": None, "project": project,
+            "sheets_dir": None, "summary": summary}
+    plan_id = uuid.uuid4().hex[:10]
+    plan["hash"] = _plan_hash(plan)
+    _store_plan(plan_id, plan)
+    return {"plan_id": plan_id, "hash": plan["hash"], "summary": summary,
+            "preview": {"action": tool, "arguments": args},
+            "next": "show the preview to the reviewer, then call altium_apply with this plan_id and hash"}
+
+
+def _record(project: str | None, entry: dict) -> str | None:
+    if not project:
+        return None
+    folder = Path(project).parent / ".pcba"
+    folder.mkdir(exist_ok=True)
+    path = folder / "altium-changes.jsonl"
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(entry) + "\n")
+    return str(path)
+
+
+def _readable_plan(plan: Any) -> bool:
+    """A plan read back from disk has the shape of its kind: an action plan (project creation,
+    ECO, outputs, ...) names a known action and carries no operations; an operations plan
+    carries a list of them."""
+    if not isinstance(plan, dict) or not isinstance(plan.get("ops"), list):
+        return False
+    action = plan.get("action")
+    if action:
+        return (isinstance(action, dict) and action.get("tool") in ACTIONS and isinstance(action.get("args"), dict)
+                and not plan["ops"])
+    return True
+
+
+def tool_apply(plan_id: str, approve: str) -> dict:
+    """Run an approved plan, then reinspect and verify against its expected nets."""
+    plan = _plans.get(plan_id)
+    if plan is None:
+        folder = _plan_dir()
+        stored = folder / f"{plan_id}.json" if folder and isinstance(plan_id, str) and PLAN_ID.match(plan_id) else None
+        if stored is None or not stored.is_file():
+            return {"error": f"unknown plan {plan_id}: never made, already applied, or made by another session"}
+        try:
+            plan = json.loads(stored.read_text(encoding="utf-8"))
+        except ValueError:
+            plan = None
+        if not _readable_plan(plan):
+            return {"error": f"plan {plan_id} on disk is unreadable; re-run altium_plan"}
+        if not plan.get("action"):
+            altium_ops.render(plan["ops"])  # a plan read back from disk is validated again
+    if not isinstance(approve, str) or approve != plan.get("hash"):
+        return {"error": "approval hash does not match the plan; re-run altium_plan"}
+    # The approval is checked against the plan's content, not only the hash stored with it: a
+    # plan file edited after the preview no longer produces the hash the reviewer approved, and
+    # a destructive operation must still have been allowed.
+    if _plan_hash(plan) != approve:
+        return {"error": "the stored plan changed since it was made; re-run altium_plan"}
+    if not plan.get("action"):
+        altium_ops.render(plan["ops"])
+        if altium_ops.destructive(plan["ops"]) and plan.get("allow_destructive") is not True:
+            return {"error": "the stored plan holds destructive operations it was not allowed; re-run altium_plan"}
+    # Taken before anything runs: whatever happens next, a plan runs at most once.
+    _take_plan(plan_id)
+    started = time.time()
+    entry: dict[str, Any] = {"at": dt.datetime.now().isoformat(timespec="seconds"), "plan": plan_id,
+                             "hash": plan["hash"], "summary": plan["summary"]}
+    if plan.get("action"):
+        return _apply_action(plan, entry, started)
+    entry["operations"] = len(plan["ops"])
+    try:
+        reply = session().run(plan["ops"])
+    except IN_BAND as exc:
+        _record(plan.get("project"), {**entry, "ok": False, "error": _error_text(exc),
+                                      "seconds": round(time.time() - started, 2), "verified": None})
+        raise
+    result: dict[str, Any] = {"applied": _reply(reply)}
+    changed: dict[str, int] = {}
+    for item in reply.items:
+        changed[item.get("name", "?")] = changed.get(item.get("name", "?"), 0) + 1
+    result["changed"] = changed
+    if reply.ok and plan.get("expect_nets") and plan.get("project"):
+        try:
+            result["verification"] = _verify(plan["project"], plan["expect_nets"], plan.get("sheets_dir"), reopen=True)
+        except IN_BAND as exc:
+            # The edit already ran: report and record the failed check instead of losing both.
+            result["verification"] = {"match": False, "error": _error_text(exc)}
+    result["record"] = _record(
+        plan.get("project"),
+        {
+            **entry,
+            "ok": reply.ok,
+            "error": reply.error or None,
+            "seconds": round(time.time() - started, 2),
+            "verified": (result.get("verification") or {}).get("match"),
+        },
+    )
+    return result
+
+
+def _apply_action(plan: dict, entry: dict, started: float) -> dict:
+    tool, args = plan["action"]["tool"], plan["action"]["args"]
+    entry["action"] = tool
+    try:
+        applied = ACTIONS[tool](**args)
+    except IN_BAND as exc:
+        _record(plan.get("project"), {**entry, "ok": False, "error": _error_text(exc),
+                                      "seconds": round(time.time() - started, 2)})
+        raise
+    error = applied.get("error")
+    entry.update({"ok": applied.get("ok") is True, "error": json.dumps(error) if isinstance(error, dict) else error,
+                  "seconds": round(time.time() - started, 2)})
+    for key in ("changes", "files"):
+        if isinstance(applied.get(key), list):
+            entry[key] = len(applied[key])
+    return {"applied": applied, "record": _record(plan.get("project"), entry)}
+
+
+def tool_verify(project: str, expect_nets: dict, sheets_dir: str | None = None, fresh: bool = False) -> dict:
+    """Compare the expected nets with Altium's compiled netlist and with the engine's parse.
+    `fresh` compiles what is on disk first (see `_fresh`)."""
+    if fresh:
+        refused = _fresh(project)
+        if refused:
+            return {"match": False, "error": refused}
+    out = _verify(project, expect_nets, sheets_dir)
+    if fresh:
+        out["fresh"] = True
+    return out
+
+
+def _verify(project: str, expect_nets: dict, sheets_dir: str | None = None, reopen: bool = False) -> dict:
+    nets = _netlist(project, sheets_dir, reopen=reopen)
+    if "altium" not in nets:
+        return {"match": False, "error": nets}
+    out = {"altium": diff_nets(expect_nets, nets["altium"]["nets"]),
+           "altium_unconnected": len(nets["altium"]["unconnected"]),
+           "altium_violations": nets["altium"]["summary"].get("violations"),
+           "altium_violation_kinds": _violation_kinds(nets["altium"]["violations"])}
+    if sheets_dir:
+        out["engine"] = diff_nets(expect_nets, nets["engine"]["nets"])
+    if nets["altium"].get("warnings"):
+        out["altium_warnings"] = nets["altium"]["warnings"]
+    out["match"] = out["altium"]["match"] and (out.get("engine", {"match": True})["match"])
+    return out
+
+
+def _violation_kinds(violations: list[dict]) -> dict[str, int]:
+    kinds: dict[str, int] = {}
+    for v in violations:
+        key = v["text"].split(" at ")[0].split(":")[0][:80]
+        kinds[key] = kinds.get(key, 0) + 1
+    return dict(sorted(kinds.items(), key=lambda kv: -kv[1]))
+
+
+def _strings(**values: Any) -> None:
+    for name, value in values.items():
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{name} must be a non-empty string")
+
+
+def tool_update_pcb(project: str, pcb: str) -> dict:
+    """Plan Altium's ECO from the schematics into the board; altium_apply runs it."""
+    _strings(project=project, pcb=pcb)
+    return _plan_action("altium_update_pcb", {"project": project, "pcb": pcb},
+                        f"Update {Path(pcb).name} from the schematics of {Path(project).name} (ECO)", project)
+
+
+def _run_update_pcb(project: str, pcb: str) -> dict:
+    return session().update_pcb(project, pcb)
+
+
+def tool_update_footprints(project: str, pcb: str, library: str) -> dict:
+    """Plan replacing the board's footprints from `library` in place; altium_apply runs it."""
+    _strings(project=project, pcb=pcb, library=library)
+    if not library.lower().endswith(".pcblib"):
+        raise ValueError("library must be a .PcbLib")
+    return _plan_action("altium_update_footprints", {"project": project, "pcb": pcb, "library": library},
+                        f"Update the footprints of {Path(pcb).name} from {Path(library).name}", project)
+
+
+def _run_update_footprints(project: str, pcb: str, library: str) -> dict:
+    return session().update_footprints(project, pcb, library)
+
+
+def tool_autoroute(project: str, pcb: str, timeout: float = 600.0, ripup_violations: bool = False,
+                   lock_preroutes: bool = False) -> dict:
+    """Plan a Situs Route All on the board; altium_apply runs it."""
+    _strings(project=project, pcb=pcb)
+    if not isinstance(timeout, (int, float)) or isinstance(timeout, bool) or not 10 <= timeout <= 7200:
+        raise ValueError("timeout must be between 10 and 7200 seconds")
+    for name, value in (("ripup_violations", ripup_violations), ("lock_preroutes", lock_preroutes)):
+        if not isinstance(value, bool):
+            raise ValueError(f"{name} must be true or false")
+    return _plan_action("altium_autoroute", {"project": project, "pcb": pcb, "timeout": float(timeout),
+                                             "ripup_violations": ripup_violations, "lock_preroutes": lock_preroutes},
+                        f"Autoroute every open connection on {Path(pcb).name} with Situs", project)
+
+
+def _run_autoroute(project: str, pcb: str, timeout: float, ripup_violations: bool = False,
+                   lock_preroutes: bool = False) -> dict:
+    result = session().autoroute(project, pcb, timeout=timeout, ripup_violations=ripup_violations,
+                                 lock_preroutes=lock_preroutes)
+    if result.get("ok"):
+        # Situs leaves shorts, broken nets, free angles and joins a fraction of a micron apart
+        # (#42): every autoroute answer carries the check, so none is taken as a finished route.
+        result["post_check"] = tool_route_check(project, pcb)
+    return result
+
+
+# DRC rules that say routing is incomplete or wrong, by the start of the rule's report name.
+ROUTE_RULES = {"shorts": "Short-Circuit", "unrouted": "Un-Routed Net", "net_antennae": "Net Antennae"}
+
+
+def tool_route_check(project: str, pcb: str) -> dict:
+    """What a route (Situs or by hand) left to fix: DRC shorts, unrouted nets and net antennae;
+    tracks off 0/45/90 degrees; track ends next to their joint but not on it (fix with
+    altium_snap_joins); polygons that poured nothing. Read-only."""
+    _strings(project=project, pcb=pcb)
+    drc = session().run_drc(project, pcb)
+    out: dict[str, Any] = {"pcb": pcb}
+    if drc.get("ok"):
+        for key, prefix in ROUTE_RULES.items():
+            rules = [r for r in drc.get("rules", []) if r["rule"].startswith(prefix)]
+            out[key] = {"violations": sum(r["violations"] for r in rules),
+                        "details": [d for r in rules for d in r.get("details", [])][:20]}
+        out["drc_violations"] = drc.get("violations")
+    else:
+        out["drc"] = {k: v for k, v in drc.items() if k != "rules"}
+    board = _board(pcb)
+    if isinstance(board, dict):
+        return {**out, "passed": False, "error": board}
+    _components, pads, _outline, _bodies, primitives = board
+    out["off_angle"] = [f.to_dict() for f in altium_house.check_track_angles(primitives)]
+    out["near_miss_joins"] = altium_house.near_miss_joins(primitives, pads)
+    polygons = session().run([{"op": "pcb_open", "path": pcb}, {"op": "pcb_polygons"}])
+    if not polygons.ok:
+        return {**out, "passed": False, "error": {"polygons": polygons.error}}
+    out["empty_polygons"] = [i["polygon"] for i in polygons.items
+                             if i.get("name") == "pcb_polygons" and i.get("pieces") == 0]
+    drc_clean = drc.get("ok") is True and all(out[k]["violations"] == 0 for k in ROUTE_RULES)
+    out["passed"] = (drc_clean and not out["off_angle"] and not out["near_miss_joins"]
+                     and not out.get("empty_polygons"))
+    out["note"] = ("Routing check only. near_miss_joins: plan altium_snap_joins; off_angle and shorts need "
+                   "re-routing those nets (pcb_unroute + route).")
+    return out
+
+
+def tool_snap_joins(pcb: str, project: str | None = None, tolerance: float = 0.01) -> dict:
+    """Plan snapping every near-miss track end (altium_route_check near_miss_joins) onto its joint:
+    a pad or via centre, else the other track end. Width, net and lock stay. Returns plan_id and
+    hash; altium_apply runs it."""
+    _strings(pcb=pcb)
+    if not isinstance(tolerance, (int, float)) or isinstance(tolerance, bool) or not 0 < tolerance <= 0.05:
+        raise ValueError("tolerance must be a length in mm above 0 and at most 0.05")
+    board = _board(pcb)
+    if isinstance(board, dict):
+        return board
+    _components, pads, _outline, _bodies, primitives = board
+    misses = altium_house.near_miss_joins(primitives, pads, tolerance=float(tolerance))
+    if not misses:
+        return {"misses": 0, "note": "no track end lies next to its joint; nothing to plan"}
+    ops: list[dict] = [{"op": "pcb_open", "path": pcb}]
+    for m in misses:
+        ops.append({"op": "pcb_track_end", "net": m["net"], "layer": altium_ops.LAYER_BY_NUMBER[m["layer"]],
+                    "x": m["at"][0], "y": m["at"][1], "to_x": m["snap_to"][0], "to_y": m["snap_to"][1]})
+    ops.append({"op": "pcb_save"})
+    plan = tool_plan(ops, f"Snap {len(misses)} near-miss track ends on {Path(pcb).name} onto their joints",
+                     project=project)
+    plan["misses"] = len(misses)
+    return plan
+
+
+def tool_drawing_create(project: str, path: str, template: str | None = None) -> dict:
+    """Plan adding a Draftsman document (.PCBDwf) to the project. With `template`, a drawing made
+    once in Altium (assembly views, BOM table, fabrication notes) is copied and bound to this
+    project; Draftsman redraws its board views from the project's PCB when it opens. Without
+    one, Altium creates an empty drawing. altium_outputs with `drawings` publishes it to PDF."""
+    _strings(project=project, path=path)
+    if not path.lower().endswith(".pcbdwf"):
+        raise ValueError("path must end in .PCBDwf")
+    if Path(path).parent != Path(project).parent:
+        raise ValueError("the drawing belongs next to its project (altium_outputs looks for it there)")
+    if template is not None:
+        _strings(template=template)
+        if not template.lower().endswith(".pcbdwf"):
+            raise ValueError("template must be a .PCBDwf drawing")
+    what = f"from {Path(template).name}" if template else "empty"
+    return _plan_action("altium_drawing_create", {"project": project, "path": path, "template": template},
+                        f"Add the Draftsman drawing {Path(path).name} ({what}) to {Path(project).name}", project)
+
+
+def _run_drawing_create(project: str, path: str, template: str | None = None) -> dict:
+    target = Path(path)
+    if target.exists():
+        return {"ok": False, "stage": "exists", "error": f"{target.name} exists; pick another name or remove it"}
+    if template:
+        source = Path(template)
+        if not source.is_file():
+            return {"ok": False, "stage": "template", "error": f"no template at {template}"}
+        target.write_bytes(source.read_bytes())
+    try:
+        reply = session().run([{"op": "project_open", "path": project},
+                               {"op": "doc_create", "kind": "PCBDWF", "path": path, "project": project},
+                               {"op": "project_save", "path": project}])
+    except BaseException:
+        target.unlink(missing_ok=True)  # it did not exist before this attempt (checked above)
+        raise
+    if not reply.ok:
+        target.unlink(missing_ok=True)
+    result = {"ok": reply.ok, "path": path, "from_template": bool(template), **_reply(reply)}
+    if reply.ok and not template:
+        result["note"] = ("an empty drawing: place the board assembly view, BOM table and notes in Altium once, then "
+                          "use that drawing as the template for the other boards")
+    return result
+
+
+def tool_house_rules(out: str | None = None) -> dict:
+    """The house DFM set: its status, the typed operations, and optionally a .RUL file."""
+    result = altium_house.status()
+    result["ops"] = altium_house.house_ops()
+    if out:
+        path = Path(out)
+        if path.suffix.upper() != ".RUL":
+            return {"error": "out must end in .RUL"}
+        path.write_bytes(altium_house.rul_bytes())
+        result["rul"] = str(path)
+    return result
+
+
+def _board(pcb: str) -> dict | tuple:
+    """Everything the house checks read from a board, lengths in mm (every item, never cut)."""
+    reply = session().run([{"op": "pcb_open", "path": pcb}, {"op": "pcb_components"}, {"op": "pcb_pads"},
+                           {"op": "pcb_board_outline"}, {"op": "pcb_bodies"},
+                           {"op": "pcb_primitives", "limit": 10_000_000}], timeout=300)
+    if not reply.ok:
+        return _reply(reply)
+    items = _convert(reply.items, limit=None)  # a check must see every pad, not the first MAX_ITEMS
+    by = lambda name: [i for i in items if i["name"] == name]  # noqa: E731
+    return (by("pcb_components"), by("pcb_pads"), [[i["x"], i["y"]] for i in by("pcb_board_outline")],
+            by("pcb_bodies"), [i for i in by("pcb_primitives") if i.get("kind") != "summary"])
+
+
+def tool_dfm(pcb: str) -> dict:
+    """House checks Altium's rule system cannot express, on the board as Altium has it open."""
+    board = _board(pcb)
+    if isinstance(board, dict):
+        return board
+    components, pads, outline, bodies, primitives = board
+    result = altium_house.check_fiducials(components, pads, outline or None)
+    layout = altium_house.check_layout(primitives, pads, components, bodies, outline or None)
+    result["findings"] += layout["findings"]
+    result["layout_policy"] = layout["policy"]
+    result["passed"] = result["passed"] and layout["passed"]
+    result["pcb"] = pcb
+    result["note"] = "House checks only; run altium_drc for Altium's rules. Not a manufacturability sign-off."
+    return result
+
+
+# Documents Altium keeps only in memory and lists among a project's documents: ActiveBOM's
+# virtual BOM (`<project>\ActiveBOM.VirtualBOM`) never exists on disk (#39).
+VIRTUAL_DOCUMENT_SUFFIXES = (".virtualbom",)
+
+
+def _virtual(doc: dict) -> bool:
+    return (str(doc.get("doc_kind", "")).lower() == "virtualbom"
+            or str(doc.get("path", "")).lower().endswith(VIRTUAL_DOCUMENT_SUFFIXES))
+
+
+def _hygiene(project: str) -> dict:
+    """What a project holds that does not belong in a release: documents outside its folder,
+    entries for files that do not exist, and documents Altium holds unsaved. Altium's in-memory
+    virtual documents are counted apart; they are not files."""
+    reply = session().run([{"op": "project_open", "path": project}, {"op": "project_state", "path": project}])
+    if not reply.ok:
+        return {"passed": False, "error": reply.error}
+    listed = [i for i in reply.items if i.get("name") == "project_state" and i.get("kind") == "document"]
+    docs = [d for d in listed if not _virtual(d)]
+    problems = {
+        "outside_folder": [d["path"] for d in docs if not d.get("inside")],
+        "missing_on_disk": [d["path"] for d in docs if not d.get("exists")],
+        "unsaved_in_altium": [d["path"] for d in docs if d.get("modified")],
+    }
+    result = {"passed": not any(problems.values()), "documents": len(docs), **{k: v for k, v in problems.items() if v}}
+    if len(listed) > len(docs):
+        result["virtual"] = [d["path"] for d in listed if _virtual(d)]
+    return result
+
+
+def tool_check_board(project: str, pcb: str, expect_nets: dict | None = None, sheets_dir: str | None = None) -> dict:
+    """One report for "is this board done?": Altium's DRC, the house checks, the compiled netlist
+    (and the expected nets, when given) and the project's hygiene. Every claim about a board
+    should cite this report; it is still no sign-off."""
+    _strings(project=project, pcb=pcb)
+    checks: dict[str, dict] = {}
+    drc = session().run_drc(project, pcb)
+    checks["drc"] = {"passed": drc.get("ok") is True and drc.get("violations") == 0,
+                     "violations": drc.get("violations"),
+                     "rules": [(r["rule"], r["violations"]) for r in drc.get("rules", [])]}
+    dfm = tool_dfm(pcb)
+    checks["house"] = {"passed": dfm.get("passed") is True,
+                       "findings": [f"{f['rule_id']} {f['severity']}: {f['message']}" for f in dfm.get("findings", [])]}
+    nets = _netlist(project, sheets_dir)
+    if "altium" in nets:
+        doubled = sorted(n for n, pins in nets["altium"]["nets"].items() if len({tuple(p) for p in pins}) != len(pins))
+        checks["compile"] = {"passed": not doubled and not nets["altium"].get("warnings"),
+                             "components": nets["altium"]["summary"].get("components"),
+                             "erc_violations": nets["altium"]["summary"].get("violations")}
+        if doubled:
+            checks["compile"]["nets_listing_a_pin_twice"] = doubled[:20]
+            checks["compile"]["hint"] = "Altium compiled a stale project; altium_netlist with fresh: true"
+        if nets["altium"].get("warnings"):
+            checks["compile"]["warnings"] = nets["altium"]["warnings"]
+    else:
+        checks["compile"] = {"passed": False, "error": nets}
+    if expect_nets:
+        verify = _verify(project, expect_nets, sheets_dir)
+        checks["netlist"] = {"passed": verify.get("match") is True,
+                             **{k: verify[k] for k in ("altium", "engine") if k in verify}}
+    checks["hygiene"] = _hygiene(project)
+    return {"passed": all(c["passed"] for c in checks.values()), "checks": checks, "pcb": pcb,
+            "note": "Machine checks only: DRC under the board's rules, the house checks, the compile. Not a sign-off."}
+
+
+def _interface(pcb: str, parts: list[str]) -> dict:
+    reply = session().run([{"op": "pcb_open", "path": pcb}, {"op": "pcb_board_outline"}, {"op": "pcb_components"},
+                           {"op": "pcb_pads"}])
+    if not reply.ok:
+        raise DriveError("read", f"could not read {pcb}: {reply.error}")
+    items = _convert(reply.items, limit=None)
+    outline = [(round(i["x"], 3), round(i["y"], 3)) for i in items if i["name"] == "pcb_board_outline"]
+    comps = {i["designator"]: (("bottom" if i.get("bottom") else "top"), round(i["x"], 3), round(i["y"], 3),
+                               round(i.get("rotation", 0)) % 360) for i in items if i["name"] == "pcb_components"}
+    pads = {}
+    for i in items:
+        if i["name"] == "pcb_pads" and i.get("designator") in parts:
+            pads[f"{i['designator']}-{i['pad']}"] = (round(i["x"], 3), round(i["y"], 3))
+    return {"outline": outline, "parts": {p: comps.get(p) for p in parts}, "pads": pads}
+
+
+def tool_compare_boards(boards: list[str], parts: list[str], tolerance: float = 0.001) -> dict:
+    """Whether two or more boards share one mechanical interface: the same outline, and each named
+    part (mating connectors, mounting holes) on the same side, place and rotation with every pad in
+    the same place. Variants of one board plug into the same socket; a difference is a fault."""
+    if not isinstance(boards, list) or len(boards) < 2 or not all(isinstance(b, str) and b for b in boards):
+        raise ValueError("boards must list at least two board paths")
+    if not isinstance(parts, list) or not all(isinstance(p, str) and p for p in parts):
+        raise ValueError("parts must list designators")
+    reads = {b: _interface(b, parts) for b in boards}
+    first, base = boards[0], reads[boards[0]]
+    differences = []
+
+    def close(a, b) -> bool:
+        if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+            return abs(a - b) <= tolerance
+        if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)) and len(a) == len(b):
+            return all(close(x, y) for x, y in zip(a, b))
+        return a == b
+
+    for other in boards[1:]:
+        data = reads[other]
+        if not close(sorted(base["outline"]), sorted(data["outline"])):
+            differences.append({"what": "outline", first: base["outline"], other: data["outline"]})
+        for part in parts:
+            if base["parts"][part] is None or data["parts"][part] is None:
+                differences.append({"what": part,
+                                    "missing": [b for b in (first, other) if reads[b]["parts"][part] is None],
+                                    first: base["parts"][part], other: data["parts"][part]})
+            elif not close(base["parts"][part], data["parts"][part]):
+                differences.append({"what": part, first: base["parts"][part], other: data["parts"][part]})
+        for pad in sorted(set(base["pads"]) | set(data["pads"])):
+            if not close(base["pads"].get(pad), data["pads"].get(pad)):
+                differences.append({"what": f"pad {pad}", first: base["pads"].get(pad), other: data["pads"].get(pad)})
+    return {"match": not differences, "differences": differences, "parts": parts,
+            "pads_compared": len(base["pads"]), "tolerance_mm": tolerance}
+
+
+def tool_drc(project: str, pcb: str) -> dict:
+    return session().run_drc(project, pcb)
+
+
+def tool_screenshot(kind: str, path: str, out: str) -> dict:
+    return session().screenshot(kind, path, Path(out))
+
+
+# outputs published to PDF by their own OutJobs rather than generated as files
+PUBLISHED = ("schematic_pdf", "pcb_3d", "drawings")
+
+
+def tool_outputs(project: str, outputs: list[str] | None = None, outjob: str | None = None,
+                 paper: str | None = None) -> dict:
+    """Plan generating outputs with an OutJob; altium_apply runs it and lists the files with hashes.
+
+    It is a write: it adds OutJobs to the project and saves the project file, never the design
+    documents, and it refuses while Altium holds unsaved changes in the project (outputs show saved
+    documents only). Contents are not parsed here: Gerber, drill, BOM and pick-and-place files
+    belong to gerbtrace under the product boundary.
+    """
+    _strings(project=project)
+    outputs = outputs or ["gerber", "drill", "pick_place", "bom", "step"]
+    if not isinstance(outputs, list) or not all(isinstance(o, str) for o in outputs):
+        raise ValueError("outputs must be a list of names")
+    unknown = [o for o in outputs if o not in altium_outjob.OUTPUT_TYPES and o not in PUBLISHED]
+    if unknown:
+        return {"error": f"unknown outputs {unknown}; choose from {sorted([*altium_outjob.OUTPUT_TYPES, *PUBLISHED])}"}
+    if outjob is not None:
+        _strings(outjob=outjob)
+    if "pcb_3d" in outputs:
+        found = len(list(Path(project).parent.glob("*.PcbDoc")))
+        if found != 1:
+            return {"error": f"pcb_3d needs exactly one .PcbDoc next to the project, found {found}"}
+    if "drawings" in outputs and not list(Path(project).parent.glob("*.PCBDwf")):
+        return {"error": "drawings needs Draftsman documents (.PCBDwf) next to the project, found none"}
+    if paper is not None and paper not in altium_outjob.PAPERS:
+        return {"error": f"unknown paper {paper!r}; choose from {list(altium_outjob.PAPERS)}"}
+    return _plan_action("altium_outputs", {"project": project, "outputs": outputs, "outjob": outjob, "paper": paper},
+                        f"Generate {', '.join(outputs)} for {Path(project).name}", project)
+
+
+def _run_outputs(project: str, outputs: list[str], outjob: str | None, paper: str | None = None) -> dict:
+    folder = Path(project).parent
+    state = session().run([{"op": "project_open", "path": project}, {"op": "project_state", "path": project}],
+                          timeout=60)
+    if not state.ok:
+        return _reply(state)
+    unsaved = [i.get("path") for i in state.items if i.get("kind") == "document" and i.get("modified")]
+    if unsaved:
+        return {"error": f"Altium holds unsaved changes in {unsaved}; outputs show saved documents only, so save "
+                         "or discard them first"}
+    started = time.time() - 1
+    ops = [{"op": "project_open", "path": project}]
+    files = [o for o in outputs if o not in PUBLISHED]
+    job = Path(outjob) if outjob else folder / f"{Path(project).stem}_pcba.OutJob"
+    if files or outjob:
+        if not outjob:
+            altium_outjob.write_outjob(job, files)
+        ops.append({"op": "outjob_run", "outjob": str(job), "project": project})
+    if "schematic_pdf" in outputs:
+        pdf_job = folder / f"{Path(project).stem}_pcba_pdf.OutJob"
+        altium_outjob.write_pdf_outjob(pdf_job, folder / "Schematic PDF" / f"{Path(project).stem}_Schematic.pdf", paper)
+        ops.append({"op": "outjob_run", "outjob": str(pdf_job), "project": project, "medium": "PDF"})
+    if "pcb_3d" in outputs:
+        pcbs = sorted(folder.glob("*.PcbDoc"))
+        if len(pcbs) != 1:
+            return {"error": f"pcb_3d needs exactly one .PcbDoc next to the project, found {len(pcbs)}"}
+        read = session().run([{"op": "pcb_open", "path": str(pcbs[0])}, {"op": "pcb_board_outline"}], timeout=120)
+        if not read.ok:
+            return _reply(read)
+        origin = next((i["x_origin"], i["y_origin"]) for i in read.items if "x_origin" in i)
+        outline = [(i["x"], i["y"]) for i in read.items if i.get("name") == "pcb_board_outline"]
+        if not outline:
+            return {"error": f"pcb_3d frames the board by its outline, and {pcbs[0].name} has none"}
+        job_3d = folder / f"{Path(project).stem}_pcba_3d.OutJob"
+        altium_outjob.write_3d_outjob(job_3d, folder / "3D PDF" / f"{Path(project).stem}_3D.pdf", origin, outline)
+        ops.append({"op": "outjob_run", "outjob": str(job_3d), "project": project, "medium": "PDF"})
+    if "drawings" in outputs:
+        docs = sorted(folder.glob("*.PCBDwf"))
+        if not docs:
+            return {"error": "drawings needs Draftsman documents (.PCBDwf) next to the project, found none"}
+        job_dwf = folder / f"{Path(project).stem}_pcba_dwf.OutJob"
+        altium_outjob.write_drawings_outjob(job_dwf, [(d, folder / "Drawings PDF" / f"{d.stem}.pdf") for d in docs])
+        ops += [{"op": "outjob_run", "outjob": str(job_dwf), "project": project,
+                 "medium": altium_outjob.drawing_medium(d)} for d in docs]
+    reply = session().run(ops, timeout=600)
+    if not reply.ok:
+        return _reply(reply)
+    produced = [p for p in folder.rglob("*") if p.is_file() and p.stat().st_mtime >= started
+                and ".pcba" not in p.parts and p.suffix.lower() not in (".outjob", ".prjpcb", ".pcbdoc", ".schdoc")]
+    status = folder / "Status Report.Txt"
+    return {"ok": True, "outjob": str(job), "files": file_hashes(sorted(produced)),
+            "status_report": status.read_text(encoding="utf-8", errors="replace") if status.is_file() else None}
+
+
+def tool_project_create(path: str, documents: list[str] | None = None) -> dict:
+    """Plan a new `.PrjPcb` (plain INI), opened once written; altium_apply runs it. Documents are
+    created with doc_create."""
+    _strings(path=path)
+    documents = documents or []
+    if not isinstance(documents, list) or not all(isinstance(d, str) and d for d in documents):
+        raise ValueError("documents must be a list of file names")
+    if Path(path).exists():
+        return {"error": f"{path} exists; open it with an altium_plan project_open operation"}
+    return _plan_action("altium_project_create", {"path": path, "documents": documents},
+                        f"Create the project {Path(path).name}", path)
+
+
+def _run_project_create(path: str, documents: list[str]) -> dict:
+    target = Path(path)
+    if target.exists():
+        return {"error": f"{target} exists; open it with an altium_plan project_open operation"}
+    target.parent.mkdir(parents=True, exist_ok=True)
+    parser = ["[Design]", "Version=1.0", "HierarchyMode=0", ""]
+    for i, doc in enumerate(documents, 1):
+        parser += [f"[Document{i}]", f"DocumentPath={doc}", ""]
+    target.write_text("\r\n".join(parser), encoding="utf-8", newline="")
+    reply = session().run([{"op": "project_open", "path": str(target)}])
+    return {"created": str(target), **_reply(reply)}
+
+
+# The writes that are not typed operations, run by altium_apply from an approved plan.
+def tool_vcs_status(project: str) -> dict:
+    """The Altium 365 working copy of a project, read with git (Altium need not run): branch and
+    sync state, changed files split into real changes and Altium's byte-only re-saves, and
+    project entries outside the folder or missing."""
+    _strings(project=project)
+    try:
+        return altium_vcs.status(project)
+    except altium_vcs.VcsError as exc:
+        return {"error": str(exc)}
+
+
+def tool_vcs_revert(project: str, files: list[str], allow_destructive: bool = False) -> dict:
+    """Plan restoring files of the working copy to their committed state (typically what Altium
+    only re-saved). altium_apply closes the project without saving or committing, runs git
+    checkout, and reopens it.
+
+    Only files `altium_vcs_status` classes as re-saves are restored by default: a PCB, library or
+    drawing cannot be judged byte by byte, and restoring a real change (saved but uncommitted
+    routing) loses it for good. Anything else needs `allow_destructive`."""
+    _strings(project=project)
+    if not isinstance(files, list) or not files or not all(isinstance(f, str) and f for f in files):
+        raise ValueError("files must list paths relative to the project folder (see altium_vcs_status)")
+    status = altium_vcs.status(project)
+    changed = {c["path"] for c in status["changes"] if c["status"] not in ("untracked",)}
+    unchanged = [f for f in files if f not in changed]
+    if unchanged:
+        raise ValueError(f"not changed in the working copy: {unchanged}")
+    real = [f for f in files if f not in status["resave_only"]]
+    if real and allow_destructive is not True:
+        raise ValueError(f"{real} may hold real changes (content, binary, new or deleted), not only Altium's re-saves; "
+                         "restoring them discards that work. Pass allow_destructive: true only when the user said to "
+                         "discard them")
+    return _plan_action("altium_vcs_revert", {"project": project, "files": files,
+                                              "allow_destructive": allow_destructive is True},
+                        f"Restore {len(files)} file(s) of {Path(project).name} to the committed state", project)
+
+
+def _run_vcs_revert(project: str, files: list[str], allow_destructive: bool = False) -> dict:
+    s = session()
+    state = s.run([{"op": "project_state", "path": project}])
+    if not state.ok:
+        return {"ok": False, "stage": "state", **_reply(state)}
+    unsaved = [i.get("path") for i in state.items if i.get("kind") == "document" and i.get("modified")]
+    if unsaved and not allow_destructive:
+        # Closing without saving would answer "Don't Save" for these: never on a plan that did not say so.
+        return {"ok": False, "stage": "unsaved", "modified": unsaved,
+                "error": "Altium holds unsaved changes in the project; save or discard them first, or plan the revert "
+                         "with allow_destructive"}
+    closed = s.run([{"op": "project_close", "path": project, "save": "none"}])
+    if not closed.ok:
+        return {"ok": False, "stage": "close", **_reply(closed)}
+    if not allow_destructive:
+        # Classified again now that Altium holds nothing: a file saved since the plan may hold real work.
+        try:
+            resaves = set(altium_vcs.status(project)["resave_only"])
+        except (altium_vcs.VcsError, OSError):
+            s.run([{"op": "project_open", "path": project}])  # never leave the project closed
+            raise
+        changed_since = [f for f in files if f not in resaves]
+        if changed_since:
+            reopened = s.run([{"op": "project_open", "path": project}])
+            return {"ok": False, "stage": "changed-since-plan", "changed": changed_since, "reopened": reopened.ok,
+                    "error": "these files are no longer only re-saves; nothing was restored. Read altium_vcs_status "
+                             "again and plan the revert anew"}
+    try:
+        restored = altium_vcs.restore(project, files)
+    finally:
+        reopened = s.run([{"op": "project_open", "path": project}])
+    left = [c["path"] for c in altium_vcs.changes(project) if c["path"] in files]
+    return {"ok": reopened.ok and not left, "restored": restored, "still_changed": left,
+            "answered": closed.answered, "reopened": reopened.ok}
+
+
+ACTIONS: dict[str, Callable[..., dict]] = {
+    "altium_vcs_revert": _run_vcs_revert,
+    "altium_project_create": _run_project_create,
+    "altium_update_pcb": _run_update_pcb,
+    "altium_update_footprints": _run_update_footprints,
+    "altium_autoroute": _run_autoroute,
+    "altium_outputs": _run_outputs,
+    "altium_drawing_create": _run_drawing_create,
+}
+
+
+def _schema(props: dict, required: list[str]) -> dict:
+    return {"type": "object", "properties": props, "required": required}
+
+
+OPS_HELP = (
+    "Each operation is an object with an 'op' field. Available: " + ", ".join(sorted(altium_ops.OPS)) + ". "
+    "Schematic coordinates are integer mils; PCB coordinates are millimetres."
+)
+
+TOOLS: dict[str, tuple[Callable, dict]] = {
+    "altium_status": (tool_status, {
+        "title": "Altium status",
+        "annotations": READ_ONLY,
+        "description": "Altium installation, whether it is running, bridge version and hash, and a live ping. "
+                       "Call first.",
+        "inputSchema": _schema({}, []),
+    }),
+    "altium_recover": (tool_recover, {
+        "title": "Recover Altium",
+        "annotations": tool_annotations(read_only=False, destructive=True),
+        "description": "Clear a stuck Altium script engine (closes modal dialogs, stops the debugger, verifies). "
+                       "allow_restart kills and restarts Altium as a last resort and loses unsaved work.",
+        "inputSchema": _schema({"allow_restart": {"type": "boolean"}}, []),
+    }),
+    "altium_read": (tool_read, {
+        "title": "Read Altium project",
+        "annotations": READ_ONLY,
+        "description": "Run read-only operations (project_open, project_state, project_netlist, sch_pins, "
+                       "sch_components, pcb_components, pcb_pads, pcb_primitives, pcb_polygons, pcb_bodies, "
+                       "pcb_nets, pcb_layers, pcb_rules, pcb_board_outline, doc_focus). Lengths come back in mm. "
+                       + OPS_HELP,
+        "inputSchema": _schema({"ops": {"type": "array", "items": {"type": "object"}}}, ["ops"]),
+    }),
+    "altium_project_create": (tool_project_create, {
+        "title": "Plan new project",
+        "annotations": READ_ONLY,
+        "description": "Plan creating a new Altium PCB project file (opened once written). Returns plan_id and "
+                       "hash; nothing is written until altium_apply.",
+        "inputSchema": _schema({"path": {"type": "string"},
+                                "documents": {"type": "array", "items": {"type": "string"}}}, ["path"]),
+    }),
+    "altium_plan": (tool_plan, {
+        "title": "Plan changes",
+        "annotations": READ_ONLY,
+        "description": "Validate a change plan (typed operations) and preview it; returns plan_id and hash. "
+                       "Nothing changes until altium_apply. Give expect_nets ({net: [[designator, pin], ...]}) "
+                       "and project/sheets_dir so apply can verify. " + OPS_HELP,
+        "inputSchema": _schema({
+            "ops": {"type": "array", "items": {"type": "object"}},
+            "summary": {"type": "string"},
+            "project": {"type": "string"},
+            "sheets_dir": {"type": "string"},
+            "expect_nets": {"type": "object"},
+            "screenshot": {"type": "object"},
+            "allow_destructive": {"type": "boolean", "description": "required for plans that unroute nets, remove "
+                                  "components, or clear a layer or a sheet"},
+        }, ["ops", "summary"]),
+    }),
+    "altium_apply": (tool_apply, {
+        "title": "Apply approved plan",
+        "annotations": tool_annotations(read_only=False, destructive=True, idempotent=True),
+        "description": "Apply an approved plan (plan_id + hash) from altium_plan or from a write tool "
+                       "(altium_project_create, altium_update_pcb, altium_autoroute, altium_outputs, "
+                       "altium_snap_joins, altium_drawing_create). Operation plans "
+                       "are reinspected and verified against the expected nets with both Altium's compiler and the "
+                       "engine parser. Every apply is recorded; a plan runs at most once.",
+        "inputSchema": _schema({"plan_id": {"type": "string"}, "approve": {"type": "string"}}, ["plan_id", "approve"]),
+    }),
+    "altium_verify": (tool_verify, {
+        "title": "Verify nets",
+        "annotations": READ_ONLY,
+        "description": "Compare expected nets with Altium's compiled netlist and the engine's parse of the "
+                       "saved sheets. fresh: true first makes Altium compile the saved files (close without "
+                       "saving, reopen); it refuses when Altium holds unsaved changes.",
+        "inputSchema": _schema({"project": {"type": "string"}, "expect_nets": {"type": "object"},
+                                "sheets_dir": {"type": "string"}, "fresh": {"type": "boolean"}},
+                               ["project", "expect_nets"]),
+    }),
+    "altium_netlist": (tool_netlist, {
+        "title": "Compiled netlist",
+        "annotations": READ_ONLY,
+        "description": "Altium's compiled netlist and, with sheets_dir, the engine's netlist and their differences. "
+                       "fresh: true first makes Altium compile the saved files (a stale in-memory project shows every "
+                       "part twice or old wiring); it refuses when Altium holds unsaved changes.",
+        "inputSchema": _schema({"project": {"type": "string"}, "sheets_dir": {"type": "string"},
+                                "fresh": {"type": "boolean"}}, ["project"]),
+    }),
+    "altium_update_pcb": (tool_update_pcb, {
+        "title": "Plan PCB update (ECO)",
+        "annotations": READ_ONLY,
+        "description": "Plan Altium's ECO (Import Changes) from the project's schematics into the PCB. Returns "
+                       "plan_id and hash; altium_apply runs it and returns the ECO log.",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"}}, ["project", "pcb"]),
+    }),
+    "altium_update_footprints": (tool_update_footprints, {
+        "title": "Plan footprint update",
+        "annotations": READ_ONLY,
+        "description": "Plan Altium's Update PCB With All Footprints from a footprint library: placed footprints "
+                       "from that library are replaced by its current version in place (position, side and nets "
+                       "kept) and the board is saved. Returns plan_id and hash; altium_apply runs it. Use after "
+                       "changing footprints (pads, silkscreen, STEP models); check with pcb_bodies and altium_drc.",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"},
+                                "library": {"type": "string"}}, ["project", "pcb", "library"]),
+    }),
+    "altium_autoroute": (tool_autoroute, {
+        "title": "Plan autoroute",
+        "annotations": READ_ONLY,
+        "description": "Plan routing every unrouted connection with Altium's Situs autorouter (its default strategy "
+                       "for the board). Situs follows the board's rules: set widths per net class, via style, routing "
+                       "layers, pcb_rule_corners (45 degrees), pcb_rule_priority (route power first) and "
+                       "pcb_rule_topology before running it. Returns plan_id and hash; altium_apply runs it. Locked "
+                       "tracks and vias are kept. Run altium_drc after.",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"},
+                                "timeout": {"type": "number", "description": "seconds, default 600; a dense two-layer "
+                                            "route with wide clearances can take far longer"},
+                                "ripup_violations": {"type": "boolean", "description": "Situs option: rip up what "
+                                                     "still violates a rule after routing (default false)"},
+                                "lock_preroutes": {"type": "boolean", "description": "Situs option: lock every "
+                                                   "existing track before routing (default false)"}},
+                               ["project", "pcb"]),
+    }),
+    "altium_route_check": (tool_route_check, {
+        "title": "Route check",
+        "annotations": READ_ONLY,
+        "description": "What a route left to fix, read-only: DRC shorts, unrouted nets and net antennae; tracks off "
+                       "0/45/90 deg; track ends a fraction of a micron next to their joint (near_miss_joins, fix with "
+                       "altium_snap_joins); polygons that poured nothing. altium_autoroute's answer carries it as "
+                       "post_check.",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"}}, ["project", "pcb"]),
+    }),
+    "altium_snap_joins": (tool_snap_joins, {
+        "title": "Plan snapping track ends",
+        "annotations": READ_ONLY,
+        "description": "Plan snapping near-miss track ends onto their joint (pad or via centre, else the other track "
+                       "end) with pcb_track_end; width, net and lock stay. Returns plan_id and hash; altium_apply "
+                       "runs it. Then altium_route_check again.",
+        "inputSchema": _schema({"pcb": {"type": "string"}, "project": {"type": "string"},
+                                "tolerance": {"type": "number", "description": "mm, default 0.01, at most 0.05"}},
+                               ["pcb"]),
+    }),
+    "altium_house_rules": (tool_house_rules, {
+        "title": "House DFM rules",
+        "annotations": tool_annotations(read_only=False, idempotent=True),
+        "description": "Newmatik house DFM: values and their status (required, house, proposed), the typed operations "
+                       "that set them (apply before a board's own rules), and with `out` an Altium .RUL file for "
+                       "Design > Rules > Import Rules.",
+        "inputSchema": _schema({"out": {"type": "string"}}, []),
+    }),
+    "altium_dfm": (tool_dfm, {
+        "title": "House DFM checks",
+        "annotations": READ_ONLY,
+        "description": "House checks Altium's rules cannot express, read from the open board: three global "
+                       "fiducials on every side that carries SMD parts (1.0 mm copper, 3.0 mm mask opening, no "
+                       "net, no paste, not in a line, spread, clear of the edge); silkscreen beyond the board "
+                       "outline (NM-SILK-001); copper tracks off 0/45/90 deg (NM-ROUTE-001); vias in or touching "
+                       "pads (NM-VIA-001) and same-net vias closer than 2 mm (NM-VIA-002); components without a "
+                       "STEP model (NM-3D-001); the barcode field (NM-BC-001). Returns findings.",
+        "inputSchema": _schema({"pcb": {"type": "string"}}, ["pcb"]),
+    }),
+    "altium_check_board": (tool_check_board, {
+        "title": "Check board",
+        "annotations": READ_ONLY,
+        "description": "One machine report before saying a board is done: Altium's DRC, the house checks (altium_dfm), "
+                       "the compiled netlist (a stale compile lists pins twice), the expected nets when given, and "
+                       "project hygiene (documents outside the folder, missing, or unsaved in Altium). Cite it; it is "
+                       "not a sign-off.",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"},
+                                "expect_nets": {"type": "object"}, "sheets_dir": {"type": "string"}},
+                               ["project", "pcb"]),
+    }),
+    "altium_compare_boards": (tool_compare_boards, {
+        "title": "Compare board variants",
+        "annotations": READ_ONLY,
+        "description": "Whether variants of a board share one mechanical interface: identical outline, and each named "
+                       "part (mating connectors, mounting holes) on the same side, place and rotation, pad for pad. "
+                       "Read-only. Mating positions come from pads, not a part's pick-and-place origin.",
+        "inputSchema": _schema({"boards": {"type": "array", "items": {"type": "string"}},
+                                "parts": {"type": "array", "items": {"type": "string"}},
+                                "tolerance": {"type": "number", "description": "mm, default 0.001"}},
+                               ["boards", "parts"]),
+    }),
+    "altium_vcs_status": (tool_vcs_status, {
+        "title": "Working copy status",
+        "annotations": READ_ONLY,
+        "description": "The project's Altium 365 working copy, read with git (no Altium needed): branch, ahead and "
+                       "behind, changed files split into real changes ('to_commit') and Altium's byte-only re-saves "
+                       "('resave_only': schematics compared record by record, text formats line by line; PCB and "
+                       "libraries are 'binary'), and project entries outside the folder or missing. Check it before "
+                       "Save to Server, and restore re-saves with altium_vcs_revert.",
+        "inputSchema": _schema({"project": {"type": "string"}}, ["project"]),
+    }),
+    "altium_vcs_revert": (tool_vcs_revert, {
+        "title": "Plan working copy revert",
+        "annotations": READ_ONLY,
+        "description": "Plan restoring working-copy files to their committed state (typically Altium's re-saves). "
+                       "altium_apply closes the project without saving or committing (answering Altium's prompts "
+                       "'Don't Save' / 'Do nothing'), runs git checkout, reopens the project and checks the files "
+                       "are clean. Never pushes. Only re-saves (altium_vcs_status resave_only) unless "
+                       "allow_destructive; refuses while Altium holds unsaved changes in the project.",
+        "inputSchema": _schema({"project": {"type": "string"}, "files": {"type": "array", "items": {"type": "string"}},
+                                "allow_destructive": {"type": "boolean"}}, ["project", "files"]),
+    }),
+    "altium_drc": (tool_drc, {
+        "title": "Design rule check",
+        "annotations": READ_ONLY,
+        "description": "Run Altium's Design Rule Check and return its report summary (violations per rule).",
+        "inputSchema": _schema({"project": {"type": "string"}, "pcb": {"type": "string"}}, ["project", "pcb"]),
+    }),
+    "altium_outputs": (tool_outputs, {
+        "title": "Plan outputs",
+        "annotations": READ_ONLY,
+        "description": "Plan generating outputs with an OutJob (gerber, drill, pick_place, bom, step, netlist, "
+                       "schematic_pdf; pcb_3d = Altium's own 3D renderings, top, bottom and two angled views, in one "
+                       "PDF; drawings = every Draftsman document next to the project, each to its own PDF). "
+                       "Returns plan_id and hash; altium_apply runs it and lists the files with SHA-256. "
+                       "Contents are not parsed (gerbtrace owns fabrication files).",
+        "inputSchema": _schema({"project": {"type": "string"},
+                                "outputs": {"type": "array", "items": {"type": "string"}},
+                                "outjob": {"type": "string"},
+                                "paper": {"type": "string", "enum": list(altium_outjob.PAPERS)}},
+                               ["project"]),
+    }),
+    "altium_drawing_create": (tool_drawing_create, {
+        "title": "Plan Draftsman drawing",
+        "annotations": READ_ONLY,
+        "description": "Plan adding a Draftsman document (.PCBDwf) next to the project and binding it. With "
+                       "template (a drawing made once in Altium with assembly views, BOM table and notes) it is "
+                       "copied; Draftsman "
+                       "redraws the board views from this project's PCB when opened. Without, Altium creates an empty "
+                       "drawing. Returns plan_id and hash; altium_apply runs it. Publish with altium_outputs drawings.",
+        "inputSchema": _schema({"project": {"type": "string"}, "path": {"type": "string"},
+                                "template": {"type": "string"}}, ["project", "path"]),
+    }),
+    "altium_screenshot": (tool_screenshot, {
+        "title": "Screenshot editor",
+        "annotations": tool_annotations(read_only=False, idempotent=True),
+        "description": "Focus a schematic (kind SCH) or PCB (kind PCB), zoom to fit, save the editor view as PNG, "
+                       "and return it as an inline MCP image (up to 8 MiB). Paths belong to the Windows host.",
+        "inputSchema": _schema({"kind": {"type": "string"}, "path": {"type": "string"}, "out": {"type": "string"}},
+                               ["kind", "path", "out"]),
+    }),
+}
+
+
+def _tool_is_error(name: str, payload: Any) -> bool:
+    """Execution failures differ from a successful inspection that finds design violations."""
+    if not isinstance(payload, dict):
+        return False
+    if payload.get("error") or payload.get("ok") is False:
+        return True
+    if name == "altium_apply":
+        applied = payload.get("applied")
+        verification = payload.get("verification")
+        return (isinstance(applied, dict) and
+                (applied.get("ok") is False or bool(applied.get("error")))) or (
+            isinstance(verification, dict) and verification.get("match") is False)
+    if name == "altium_plan":
+        preview = payload.get("preview")
+        capture = preview.get("screenshot") if isinstance(preview, dict) else None
+        return isinstance(capture, dict) and (capture.get("ok") is False or bool(capture.get("error")))
+    return False
+
+
+def _tool_content(name: str, payload: Any) -> list[dict]:
+    """Attach only screenshots produced by these tools, read on the server's own host."""
+    if not isinstance(payload, dict):
+        return []
+    capture = payload if name == "altium_screenshot" else None
+    if name == "altium_plan" and isinstance(payload.get("preview"), dict):
+        capture = payload["preview"].get("screenshot")
+    if not isinstance(capture, dict) or capture.get("ok") is not True:
+        return []
+    try:
+        path = capture.get("path")
+        if not isinstance(path, str) or not path:
+            raise ValueError("capture returned no PNG path")
+        # A bounded read also handles a file growing between capture and delivery.
+        with Path(path).open("rb") as stream:
+            data = stream.read(MAX_INLINE_IMAGE_BYTES + 1)
+        if len(data) > MAX_INLINE_IMAGE_BYTES:
+            raise ValueError("PNG exceeds the 8 MiB inline image limit")
+        if not data.startswith(b"\x89PNG\r\n\x1a\n"):
+            raise ValueError("capture is not a PNG")
+    except (OSError, ValueError) as exc:
+        return [{"type": "text", "text": f"No inline screenshot was attached: {exc}"}]
+    return [{"type": "image", "data": base64.b64encode(data).decode("ascii"), "mimeType": "image/png"}]
+
+
+SERVER = Server(
+    name="enginehall-altium",
+    title="EngineHall Altium drive",
+    version=__version__,
+    description="Creates and edits Altium Designer projects through typed, planned, verified operations.",
+    instructions=(
+        "Needs Windows with Altium Designer running; call altium_status first. Reads are free. "
+        "Every write is a plan: a planning tool returns plan_id, hash and a preview, the user "
+        "approves it, and altium_apply runs it once with that hash, then verifies and records it. "
+        "Show the preview before applying; plans that unroute, remove or clear need "
+        "allow_destructive and the user's explicit agreement. Schematic coordinates are mils, PCB "
+        "coordinates millimetres. Save to Server stays the user's step, and a check is never a "
+        "sign-off. The altium-designer skill has the operations and the workflow."
+    ),
+    tools=TOOLS,
+    in_band=IN_BAND,
+    describe_error=lambda exc: exc.to_dict() if isinstance(exc, DriveError) else str(exc),
+    tool_is_error=_tool_is_error,
+    tool_content=_tool_content,
+)
+
+handle = SERVER.handle
+serve = SERVER.serve