Agentic HIL

Removes every breakpoint GDB holds in the debug_start_session session (else session_not_active), then checks none is left. It neither resumes nor halts the core. It answers cleared (the count) and backend_reconciled true; a second call clears 0. Unconfirmed: ok false, breakpoint_reconciliation_failed; a retry is safe. GDB server only, exactly one debugger configured; else not_supported.

Resumes the core in the debug_start_session session until it stops. Needs allow_debug_execution, else permission_denied. Returns stop_reason, stop (frame): breakpoint_hit is ok; unexpected_breakpoint and target_exception are not. An exception or debugger_error stop is not resumed. No session: session_not_active. GDB server only, exactly one debugger configured; else not_supported.

Read a symbol from target memory and write it as Intel HEX to output_path; returns address, size_bytes and output. Value inline: debug_symbol_value. OpenOCD needs debug_start_session (else session_not_active); pyOCD and STM32CubeProgrammer use an open session, else the ELF flash_firmware last wrote (else symbol_source_not_available). Over debug.max_dump_size_bytes: permission_denied.

Reports if the debug_start_session session is open and its status: halted, running, error or cleanup_required. Records new stops; never halts or resumes the core; debug_halt halts, debug_get_stop_reason reads the last stop. Abnormal stop: ok true, target_ok false, target_error_type. No session: ok, active false, status stopped. GDB server only, exactly one debugger configured; else not_supported.

Reads why the core last stopped: stop_reason (breakpoint_hit, halted, exception), stop (frame). Records a new stop; never halts or resumes the core. Abnormal stop: ok true, target_ok false, target_error_type. None yet: stop_reason_not_available. Without debug_start_session: session_not_active. Session: debug_get_session_status. GDB server only, exactly one debugger configured; else not_supported.

Halts the core; the session stays open. Needs debug_start_session (else session_not_active) on a GDB server, exactly one debugger configured, else not_supported. Returns stop_reason halted or a stopped core's recorded stop. If an acknowledged interrupt's stop times out, ok and halt_confirmed are false, target_state unknown, quarantined; a confirmed halt lifts it unless the session is in error.

Lists the breakpoints from the debug_start_session session's own record without asking GDB: breakpoints (id, backend_id, location), status, and cleanup_required, quarantined and hardware_state when cleanup is unconfirmed. Never halts or resumes the core. No session: ok, active false. debug_clear_breakpoints removes them. GDB server only, exactly one debugger configured; else not_supported.

Adds a breakpoint in the debug_start_session session (else session_not_active) without resuming the core. Each call adds one and returns its breakpoint id; debug_list_breakpoints lists them. A location without a grant answers permission_denied. An unconfirmed insert answers cleanup_required; call debug_clear_breakpoints. GDB server only, exactly one debugger configured; else not_supported.

Opens a GDB session on an ELF for debug_continue and debug_halt. OpenOCD, pyOCD or ST-LINK_gdbserver; else not_supported. Needs GDB (debug.gdb_executable or PATH), the debugger's executable and allow_raw_debugger_commands off. Returns the core halted: session (status, stop_reason), log_path. A second start: session_already_active. debug_get_session_status inspects it; debug_stop_session ends it.

Ends the debug_start_session session; debug_halt keeps it open. Confirms core halted, disables resume on detach, ends GDB and debug server, drops breakpoints, frees flash_firmware and reset_target. OpenOCD, pyOCD or ST-LINK_gdbserver only; else not_supported. Success: safe_state_confirmed true. No session: ok, active false. Unproven: ok false, cleanup_required, hardware_state unknown, quarantined.

Find a symbol's hex address, size_bytes and resolved_from in the ELF. Reads no target memory; for bytes use debug_symbol_value, for Intel HEX debug_dump_symbol_ihex. OpenOCD needs debug_start_session (else session_not_active). pyOCD and STM32CubeProgrammer use an open session, else the ELF flash_firmware last wrote (else symbol_source_not_available; symbol_source_changed if changed since).

Reads a symbol from target memory, like gdb print. Address: debug_symbol_info; file: debug_dump_symbol_ihex. Returns hex plus value_unsigned and value_signed at 1/2/4/8 bytes. OpenOCD needs debug_start_session (else session_not_active); pyOCD and STM32CubeProgrammer use an open session, else flash_firmware's last ELF (else symbol_source_not_available). Over max_dump_size_bytes: permission_denied.

Check the debugger backend is installed: runs only --version, at most 10 s; contacts no probe or board. Replaces openocd. Returns backend, executable, version, config_status. Next: debugger_probes_list (probe ids), probe_target (board). Failures: debugger_not_found (missing), timeout; not_supported unless exactly one debugger is configured; permission_denied without allow_probe (config version 1).

List the probe ids of the in-circuit debuggers or programmers on this host; connects to no board. Replaces st-info. Returns probes, each with a probe_id to set as the debugger entry's probe_id. pyOCD and STM32CubeProgrammer ask their CLI; OpenOCD reads the USB serial inventory, complete false (adapters it cannot read there: not_supported). Failure: probe_discovery_failed.

Write firmware to the board via the in-circuit debugger or programmer, not st-flash; every call writes it again. Needs allow_flash, else permission_denied. resource_busy: debug_stop_session first; device_busy: held elsewhere. The debugger entry's timeout_s (seconds, 60 unless set) caps each debugger command, else timeout. No bench_run_start needed; capture with reset_after_flash adds boot output.

Return the newest stored hardware report, pass or fail, under `report`. For the last failure diagnosed, even after successes, use classify_last_error. Needs no board; reading changes nothing. After a failure it can be the recovery's reset_target or probe_target (report.tool). ok stays true for a failed report: judge report.ok, report.audit_ok, report.cleanup_required. None yet: report_not_found.

Read who holds this bench, from any process (`bench_held`, `held_devices`), and any open incident: `blocked`, `cleanup_reasons`, `auto_recoverable`, `quarantine_guidance`, `next_step`. Only `incident_stands: true` needs hardware_recover; otherwise the next hardware call settles it or stands it down. `standing_incidents` are other projects' incidents, not yours to clear. Drives no device.

Clear the standing quarantine that blocks hardware calls. Call it when hardware_lease_status shows incident_stands, rather than deleting state files. It needs allow_recover and touches no hardware. A no-contact reason clears with no argument. Any other reason answers recovery_requires_physical_check: ask the operator, pass their answer verbatim as operator_statement, never invent one.

Power-cycle the board on one supply channel: output off, wait `off_s`, output on, each state read back. Needs `allow_output`. The stored set points are held to the effective limits and the protection is armed at them first. A type that cannot read its output state is refused before contact (`not_supported`). Every call cycles the board again.

Switch one supply channel's output on or off and read the state back. Needs `allow_output`. Before switching on, the stored set points are held to the effective limits and the protection is armed at them. A type that cannot read its output state is refused before contact (`not_supported`). Switching to the state already held changes nothing.

Set the voltage, the current or both on one supply channel. Needs `allow_set`. Refused before contact when the configuration sets no limit for the channel, or a value is above its effective limit (`power_supply_limit_exceeded`). Arms the supply's protection at the limits first, writes, and reads every value back exactly (`power_supply_readback_mismatch`). Does not switch the output.

Read a configured bench power supply: per channel its set points, measured voltage and current, output state, protection and effective limits, each exact or null where the type cannot read it. Writes nothing and needs no grant. `missing_limits` and `writes_refused_reason` say why writes on a channel would be refused. A unit other than the configured one fails `power_supply_identity_mismatch`.

Connect the in-circuit debugger or programmer to the board and confirm it answers (target_detected true), with no reset and no flash; reset_target resets. Replaces openocd. Refused with resource_busy while a debug session is open. Failures: adapter_not_found (no probe), target_not_detected (board silent), debugger_not_found (backend missing), timeout (one command over debugger.timeout_s).

Fill the configuration keys that still hold placeholders from the attached probe. Call it once a board is attached, so nobody retypes its serial. It may also rename a COM device to its stable name and correct a stale identity_source. It writes only when apply is true, never flashes or erases. A read that leaves the board state unknown may get it reset into halt by recovery (resource_quarantined).

Generate this workspace's configuration from attached hardware instead of writing one by hand: every permission true except allow_raw_debugger_commands and allow_mass_erase, which it writes false. Never ask for those two to be turned on. Regenerating is the operator's call, not a way to narrow or re-open.

List the keys project_config_set may change: writable_keys with current_value and value_schema, locked_keys naming in unlocked_by the permission that opens each. Read it before project_config_set instead of guessing; it needs no permission. writes_blocked_by_open_run is true while this server holds a run or session. Bad YAML answers config_invalid, an unreadable file config_unreadable.

Re-read target, debuggers, com_ports and can_buses from this workspace's configuration into the running server, never permissions or debug. Call it after project_config_set, project_config_adopt_hardware or a hand edit, rather than a restart. New devices get every permission false; changed grants need a restart (restart_required_for). description_changes lists what moved.

Write values you choose to named keys of the configuration file. Call it after project_config_describe lists the keys, rather than editing the configuration file. Device keys need allow_config_description_write, permission keys allow_config_permissions_write, else permission_denied. Permissions only narrow: closing allow_config_permissions_write freezes them all at once (permissions_frozen).

Reset the board through the in-circuit debugger or programmer: the firmware restarts, flash is kept. Replaces st-util. Needs allow_reset (else permission_denied). Refused with resource_busy while a debug session is open: debug_stop_session first. To check the board without a reset use probe_target. Failures: reset_failed (reset not confirmed), timeout (one command over debugger.timeout_s).

Upgrade this installation to the newest release with the uv, pipx or pip that installed it. Use it when the operator asks; it takes no arguments and needs allow_upgrade. Each manager run may take 600 s. running_version stays old until this server restarts. On Windows, ask the operator to run agentic-hil upgrade (upgrade_cli_only_on_host). On failure the operator runs any reinstall_command.

Run a test plan file (agentic-hil://reference/test-plan) on the board. For calls made one by one, use bench_run_start, whose open run refuses this with `run_already_active`. `permission_denied` and `device_busy` refuse at once, before any step. A failing step gets the recovery `recovery.auto_recover` allows, reported in `recovery`. With detach, poll test_reactor_status; test_reactor_stop ends it.

Follow a detached test_reactor_run by its handle; for a bench_run_start run, use bench_run_status. `state` goes starting, running, then finished or stopped, or worker_gone if its process died; `stop_requested_at` dates a test_reactor_stop. Once ended, `run_ok` is the verdict and `canonical_report_path` its own report; `report_path` is a mirror the next run overwrites. Fails `run_state_invalid`.

Ask a test plan run to stop by writing a request it reads between steps. It finishes the step it is in (a delay or device wait ends early), closes its devices and writes its report; one still starting ends before any step. Answers at once `stop_requested: true`, also on a repeat; an ended run answers `stop_requested: false`. Fails `run_state_invalid`, or `run_worker_gone` (its process died).