# Agentic HIL

Agentic HIL is a local MCP stdio server that gives AI agents safe, policy-gated access to real embedded hardware: flashing, serial, CAN, and test-adapter stimuli/fault injection. HardCI adapters are the reference hardware.

Canonical setup request: `Install from https://github.com/hp-8472/agentic-hil and set it up for this project.`

Names: the Python package/install target and Python-facing identifiers such as imports, pytest plugin names, fixtures, and Python examples use `agentic_hil`. The CLI command, repository URL, and MCP server name use `agentic-hil`.

First normal pip attempt:

```bash
python -m pip install --user agentic_hil
agentic-hil --version
```

Run without installing (no admin rights, no PATH changes):

```bash
uvx --from agentic_hil agentic-hil --version
uvx --from git+https://github.com/hp-8472/agentic-hil agentic-hil --version
```

Alternative isolated user-local install: `uv tool install agentic_hil` or `pipx install agentic_hil`. Never sudo, never --break-system-packages. Requires Python 3.10+.

Bootstrap each firmware project from the project directory:

```bash
agentic-hil init
agentic-hil doctor
agentic-hil mcp-config --output .mcp.json
```

Each firmware project keeps its own `.hardci/config.yaml` — the policy for that project's target, debugger, permissions, artifact roots, com_ports, can_buses, and adapters.

MCP stdio command:

```text
agentic-hil mcp-stdio --config .hardci/config.yaml
```

Use MCP tools for hardware actions:

```text
hardci_debugger_info, hardci_probe_target, hardci_artifact_upload,
hardci_flash_firmware, hardci_reset_target,
hardci_com_session_start/_stop, hardci_com_write, hardci_com_read,
hardci_can_session_start/_stop, hardci_can_send, hardci_can_read,
hardci_adapter_session_start/_stop, hardci_adapter_set_value,
hardci_adapter_inject_fault, hardci_adapter_clear_fault, hardci_adapter_measure,
hardci_get_last_report, hardci_classify_last_error
```

Required workflow:

1. Build firmware.
2. Probe before flashing.
3. Flash only validated artifacts from allowed roots.
4. Stimulate via com/can/adapter tools, assert on feedback.
5. Read the structured result and last report; classify failures before changing code again.

pytest: installing `agentic_hil` registers the Python plugin `agentic_hil`; the `agentic_hil` fixture drives the same tools in CI regression suites.

Safety: do not request raw OpenOCD commands, do not open host serial/CAN/adapter devices directly, do not flash outside allowed artifact roots. Treat `permission_denied` as authoritative.

Agent setup guide: AI_AGENT_QUICKSTART.md. Human docs: README.md, TROUBLESHOOTING.md.
