Agentic HIL

Upload a local or base64-encoded firmware artifact into the configured Agentic HIL artifact store.

Declare a multi-step run and lock every device it names for the whole run, not for one call. Call this before a sequence like flash, reset, read: without it each call takes and releases its own device, and between two calls the board is free for anything else on this machine. Declared devices are held until bench_run_stop, the only devices this run may touch, and a device already held fails the call immediately naming its holder.

Report whether a run is open on this server, which devices it declared, and since when. Read this if you are not sure whether you still hold the bench.

End the declared run and release every device it held. Always call this when the run is finished; it is safe to call when no run is open.

List configured named CAN buses and active session status, with listen_only and the evidence that would back it on each adapter (listen_only_enforcement). Use this instead of ip link or candump on a SocketCAN interface.

Read CAN frames from an active configured CAN bus session. Use this instead of candump.

Send one classic CAN frame on an active configured CAN bus session. Use this instead of cansend.

Open a configured CAN bus session. A bus configured listen_only refuses rather than opening when the adapter cannot be held to it.

Stop a configured CAN bus session.

Classify the most recent Agentic HIL/debugger failure.

List configured named COM ports and detected host serial ports. Use this instead of screen, minicom, picocom, or opening /dev/tty* or COM* directly.

Read buffered feedback from an active COM port session. Use this instead of screen, minicom, or picocom.

Open a configured COM port and start a background feedback session.

Stop a configured COM port session.

Write text or hex stimulus to an active COM port session.

Clear all breakpoints from the active debug session.

Continue target execution until stop or timeout.

Read an allowed symbol from target memory and write Intel HEX.

Return active debug-session status.

Return the last structured stop reason.

Halt the target in the active debug session.

List breakpoints in the active debug session.

Set a typed breakpoint by symbol/function name or file and line.

Start a typed debug session for a validated ELF artifact.

Stop the active typed debug session.

Resolve an allowed debug symbol.

Read an allowed symbol's current bytes out of target memory and return them, as hex in memory order and, at 1, 2, 4 or 8 bytes, as an unsigned and a signed integer read in the byte order the firmware image declares. Use this instead of reading a variable through a raw gdb print.

Check whether the configured debugger backend is available. Use this instead of running openocd, pyocd, or st-info yourself.

List every connected probe ID visible to the configured debugger backend. Use this instead of st-info --probe, pyocd list, or JLinkExe.

Flash a validated firmware artifact. Provide exactly one of image_path or artifact_id. Use this instead of openocd, st-flash, or pyocd flash.

Return the most recent structured Agentic HIL report.

Clear this bench's quarantine. A quarantine is the audit halt: the evidence chain for this bench could not be written or read, and no hardware action rebuilds a record that was never written. Every other incident settles itself at the next contact and holds nothing, so on a bench with nothing standing this answers ok with nothing_to_recover: true and changes nothing. Of what does stand, a reason that names no hardware contact still clears with no argument. Anything else needs operator_statement: ask the operator in chat what state the bench is in, then pass back what they answered, in their words. It is written verbatim to the recovery ledger as their statement, relayed by you. Never write one you were not given: a ledger line that reflects no actual operator utterance is a false record with you recorded as the actor; when you have nobody to ask, relay the `agentic-hil recover --confirm-safe-state --quarantine-id <id>` line the refusal hands you and let them run it themselves. A refusal with error_type config_changed means the authoritative configuration was edited after the incident was recorded: show the operator the two digests on the result, and once they confirm the delta is understood, call again with accept_config_change: true (the operator's own line takes --accept-config-change instead). Needs permissions.allow_recover for the one route that clears something. Use this instead of deleting the server's state files, which is never the fix.

Probe the configured embedded target through the configured debugger. Use this instead of openocd, pyocd, or gdb.

Read the attached probe and carry its identity into this project's configuration: probe id, the backend's executable, the detected controller, and the probe's own COM device. Use this when a configuration was written before the board was plugged in and holds placeholders, instead of printing values for a person to retype. Returns the plan by default and writes only with apply:true, through project_config_set and its permissions. A key that already holds a value nobody generated is reported, never overwritten.

Generate this workspace's Agentic HIL configuration from attached hardware when it has none yet. Takes no arguments. Every permission in the generated file is true (flashing, reset, COM and CAN writes, and all three permissions.allow_config_* grants) except allow_raw_debugger_commands and allow_mass_erase, which are false: either one being true refuses flash_firmware on that probe, and neither is a tool you have here. The bench is workable from that file without anybody editing YAML, flashing included. Report what it granted and ask the operator which of it this bench should not have; do not ask for those two to be turned on, because that is the one change that stops flashing. Regenerating an existing configuration needs allow_config_write and carries over the permissions of the configuration this server loaded at startup, for the entries that are still in it; an entry the regeneration discovers for the first time arrives at those same defaults, and a workspace whose configuration is gone gets a file at those defaults. Because this server does not reload, a narrowing you made with project_config_set in this session is not in what it loaded and a regeneration now puts that permission back. Regenerating is the operator's call, not a way to narrow or to re-open. Use this instead of writing a configuration by hand when a tool reports config_file_not_found.

Report which keys of this project's configuration you may change right now, which you may not, and which permission would open a locked one, for this configuration in this state, not in general. Also carries each key's current value and the value shape the shipped schema declares for it. Read this before project_config_set instead of guessing a key and being refused.

Re-read this bench's device description from the authoritative configuration without restarting the server: target, debuggers, com_ports and can_buses, minus every permissions: block. Call this when a board was plugged in and written into the file after this server started, instead of asking the operator for a restart. Permissions are not re-read at all, in either direction: a device this server has never seen arrives with no grant, so it can be probed and read and cannot be flashed, reset, mass-erased or written to until an operator restarts the server. Everything outside those four sections (version, workspace_root, state_root, debug, artifacts, validation, recovery, reports, logs, and the project permissions) still needs a restart, and the result names them. Refused while a run, a session or an unresolved incident holds this bench, and when the file is missing, unreadable or does not load.

Change named keys of this project's configuration, field-wise. Two separate permissions gate it: allow_config_description_write for what the bench is (target, probe id, port device and baudrate, CAN bus settings) and allow_config_permissions_write for every permission key (each permissions: block, and the two grants that sit directly on a section, artifacts.allow_upload and debug.allow_all_symbols). Values are scalars checked against the shipped schema; the changed file is validated before it replaces the working one, and a write is refused while a run holds hardware. Use this instead of editing the configuration file yourself.

Reset the configured target through the configured debugger. Use this instead of st-util, openocd, or a raw gdb reset.

Replace this Agentic HIL installation with the newest release, gated by permissions.allow_upgrade. Takes no arguments: it can only lift to the latest release, never to a version you name, so it cannot be used to install a build that reads this bench's permissions differently. It replaces the package on disk and does not change the code this server is running. A successful call answers upgraded_on_disk with previous_version, version, running_version and restart_required: true, and the operator restarting the MCP server is what loads it; the agentic-hil command line reads the new code straight away. Refused while a run or a session holds this bench, and refused on Windows, where the files of a running process are locked and only `agentic-hil upgrade` at a shell can replace them. Use this instead of running uv, pipx or pip yourself.

Run this project's declarative test plan against the bench. Use this instead of `agentic-hil test-reactor` at a shell. The plan is a reviewed file of ordered steps: it is validated in full before the first hardware action, the run holds every device the plan names from before its first step to after its last, each step is judged by the same permission the matching tool is judged by, and a step reaching for a device the plan did not declare is refused. test_config_path selects another plan, workspace-relative or absolute, and must resolve inside workspace_root; without it the project's default plan runs. detach: true runs the plan in its own process and answers at once with a run handle to ask test_reactor_status about and test_reactor_stop to end, which is what an hours-long endurance plan wants; the default runs the plan to its end and answers with the whole result and the path of the report it wrote.

Say what a test run handle is doing: running and which step it is on, finished or stopped with its verdict and its report path, or its worker gone. Without run, list the runs this bench still has records of.

Ask a test run to end after the step it is in, close its devices in the usual order and write its report. Cooperative and nothing else: this leaves a request the run reads between its steps, so a run cannot be left half way through a step by whoever asked it to stop. A run that had already ended is answered as such and nothing is asked of it.