# HUX runtime integration

This plugin wraps Hermes's real `tool_execution` middleware boundary. It is
inert unless `HUX_RUNTIME_ENABLED=1`; `HUX_TOOL_ENFORCEMENT=1` additionally
requires every exact tool call to be released by HUX before `next_call` runs.

The process needs these read-only files:

- `HUX_SUBJECT_FILE`: router-published `usr_<64 lowercase hex>` binding;
- `HUX_WORKER_KEY_FILE`: mode `0400`, used only for worker-trust loopback calls;
- `HUX_CONTEXT_KEY_FILE`: the WebUI-created, owner-only, single-link 32-byte
  context key. Chat and the runtime use the same `hux.context.id.v1` helper.

Set `HUX_TENANT_SLOT=slot-N`, `HUX_BASE_URL=http://127.0.0.1:8790`, and a
bounded `HUX_TIMEOUT_SECONDS` (default `3`). The HUX service and plugin must be
in the same pod. `HUX_PROJECT_SOURCE` defaults to `profile:default` and must
match the source used by WebUI context creation. No HUX port belongs in a
Service or ingress.

Every turn first calls the worker-trust, idempotent
`POST /hux/v1/context/bootstrap`. The sidecar must verify every supplied ID
against the same context key before registering the deterministic project,
session, and conversation. Deployment remains default-off until that route is
present in the converged backend.

Hermes currently exposes interruption through `on_session_end(interrupted=True)`
but does not give plugins the authoritative process-registry state or reverted
side-effect list required by `hux_hook.on_stop`. The plugin therefore records a
failed/interrupted run and never claims cancellation. A real bridge requires a
new post-interrupt hook fired only after the runtime has killed and reaped every
registered tool process, with `run_id`, `session_id`, `turn_id`,
`process_registry_empty`, and redacted side-effect receipts.

Quality registration must include `services/hermes/plugins/hux-runtime/*.py`
as source and `testing/tests/test_hermes_hux_runtime_plugin.py` as its focused
test. The current focused gate is 54 passing tests with every production file
above 95% line and branch coverage.

## Post-tool emitters (HUX-04 / HUX-08)

`emitters.sync_after_tool` runs only after a successful tool execution and
never raises into the tool path. A successful `write_files` tool whose
arguments name a real, non-symlink file of at most 1 MiB creates (or, when a
same-titled artifact already exists in the conversation, appends an immutable
version to) a typed artifact through the loopback API; the service's secret
scrubbing and `restricted` forcing still apply. A successful `network` or
`web_search` tool records up to three deduplicated `web` sources found in the
first 64 KiB of real tool output. Both use deterministic idempotency keys, so
retries never duplicate records.