atlas-iac/dockerfiles/hermes-worker-hux/hux_hook/NOTES.md

hux_hook: wiring notes for the agent runtime patch

hux_hook is a stdlib-only library the Hermes agent process imports. HUX (hermes-hux-foundation, loopback 127.0.0.1:8790 in the same pod) is the source of truth; the agent never decides an approval, never reads the tenant ledger directly and never persists raw tool arguments or output.

Environment the agent process needs

Variable	Purpose
HUX_BASE_URL	default http://127.0.0.1:8790; the service is loopback-only
HUX_TENANT_SLOT	slot-N, same value the service was started with (HUX_TENANT_SLOT on the service side)
HUX_SUBJECT	usr_<hash> of the slot owner; the router derives it, the pod env carries it
HUX_WORKER_KEY	shared key mounted read-only under /runtime-access; sent as X-Hux-Relay-Key
HUX_SURFACE / HUX_TRUST	default worker / worker; the agent hook is never a human surface (SO-35)
HUX_TIMEOUT_SECONDS	default 5

Headers the client sends (exactly hux/identity.py): X-Hermes-Tenant-Identity, X-Hux-Subject, X-Hux-Surface, X-Hux-Trust, X-Hux-Relay-Key, plus Idempotency-Key on creates and If-Match on revisioned PUTs.

Construction

from hux_hook import HuxClient
client = HuxClient(os.environ.get("HUX_BASE_URL", "http://127.0.0.1:8790"),
                   {"tenant_slot": os.environ["HUX_TENANT_SLOT"], "subject": os.environ["HUX_SUBJECT"],
                    "surface": "worker", "trust": "worker"},
                   key=os.environ.get("HUX_WORKER_KEY"), timeout=float(os.environ.get("HUX_TIMEOUT_SECONDS", "5")))

One client per process. client.capabilities() is cached; call client.forget_capabilities() on SIGHUP or when the WebUI reports a flag change.

Where each call goes in the tool loop

1. Run start: emit(client, conversation_id, "run.started", "...", run_id=run_id).
2. Immediately before executing any tool that is not read-only: d = before_tool(client, run_id, conversation_id, tool_name, arguments, capability, external, risk).
   • d.proceed is True: execute now, with exactly the arguments object that was hashed. Re-serialising or "normalising" arguments after the gate breaks SO-37.
   • d.reason == "approval_required": do not execute. Surface d.approval_id to the UI (chat posts POST /hux/v1/approvals/{id} with once|session|always|deny from a human surface), park the turn, and call before_tool again with the same arguments after the decision. The idempotent replay reaches the gate; a once approval releases exactly once.
   • Any other reason (approval_denied, budget_exhausted, hux_unavailable, autonomy_off, service_error:*, a gate reason): refuse the tool and tell the model why. Never fall back to the upstream gateway approval prompt while hux.autonomy is on. Capability mapping is the runtime's job: read_files, write_files, shell, network, web_search, send_message, memory_write, artifact_write, spend_tokens, delegate, deploy, external_side_effect (see hux/rules.py). external=True for anything that leaves the tenant (messages, network, deploy).
3. After every tool: after_tool(client, run_id, conversation_id, tool_name, ok, bytes_out, turn, argument_hash=canonical_argument_hash(tool_name, arguments), duration_ms=..., exit_code=...) then record_spend(client, run_id, conversation_id, tool_calls=1, tokens=<delta>). Both are best-effort: they return None on failure and never raise.
4. Delegation: record_spend(..., delegations=1) / subagents=1 when spawning; the child run uses its own run_id and the same conversation_id.
5. Memory: before proposing a memory write call memory_gate(client, conversation_id); False means do not even propose. The write itself still goes through POST /hux/v1/memory, which enforces forget, disable and topic rules server-side.
6. Stop: when the user cancels, kill the tool processes, then receipt = on_stop(client, run_id, conversation_id, process_registry_empty=<real registry check>, side_effects=[{"description": ..., "reverted": bool}, ...]). None means no receipt exists and the stop is NOT done: retry, and never report "cancelled" to the user without a receipt (SO-41). process_registry_empty must come from the gateway's process registry, not from a timer.
7. Run end: emit(..., "run.completed" | "run.failed", ...).

What must never happen

• Raw arguments, file contents, command output, prompts or secrets in any summary, detail or evidence. The library only ever sends tool name, capability, hash, byte counts, status.
• Deciding an approval with the worker identity (the service answers 403; do not retry as chat).
• Executing a tool after proceed=False for any reason, including HUX being unreachable.
• Logging HuxServiceError bodies with request payloads: exceptions carry status/code/message only.

Routes used

GET /hux/v1/capabilities, POST /hux/v1/approvals, POST /hux/v1/runs/{id}/gate, POST /hux/v1/runs/{id}/budget, POST /hux/v1/runs/{id}/stop, POST /hux/v1/conversations/{id}/events, GET /hux/v1/privacy/policy, GET /hux/v1/conversations/{id}.