AMB Redis-Streams client plugin
Find a file
San Mononoke 6f0f90eb1c feat: initial release of hermes-amb-client standalone plugin
Extracted from hermes-agent branch feature/amb-client-2026-09.
Per J7 directive 2026-09-09 (cross-pack modularity), any AI agent can
pip install this and publish/consume against the AMB substrate.

Phase 1B of a2a-amb-kanban-prexx (synthesis v2.0 §3, §5).

Co-authored-by: San Mononoke <san@mononoke.local>
2026-09-09 18:00:46 -04:00
src/hermes_amb_client feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00
tests feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00
.gitignore feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00
LICENSE feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00
pyproject.toml feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00
README.md feat: initial release of hermes-amb-client standalone plugin 2026-09-09 18:00:46 -04:00

hermes-amb-client

AMB (Agent Message Bus) Redis-Streams client + synchronous facade.

Standalone Python plugin extracted from hermes-agent on 2026-09-09 per J7 directive (cross-pack modularity). Any agent can pip install hermes-amb-client and publish/consume against the AMB substrate without depending on hermes-agent.

What is AMB?

The Agent Message Bus is the canonical inter-wolf signal fabric on Mononoke (Redis Streams on 127.0.0.1:6380 for Mononoke-wolves; per-pack brokers for Toyoko and outpost-wolves). It's the in-house modular bridge that connects wolves, humans, external agents, and app APIs. See WORKSPACES/starros-v1/specs/AMB-Substrate.md for the full design contract.

What this client provides

  • AmbClient (async): wraps redis.asyncio with the AMB envelope convention, consumer-group model, and per-wolf authentication.
  • AmbConfig (dataclass): broker URL, password source (canonical LoadCredential path on Mononoke, with env-var fallback), DB index, socket timeout, wolf name.
  • amb_publish / amb_subscribe / amb_consume_one (synchronous facade): three narrow handlers the gateway and HOOK.yaml dispatchers can call without spinning up an asyncio loop.

Install

pip install hermes-amb-client

Use

import asyncio
from hermes_amb_client import AmbClient, AmbConfig

async def publish_event():
    config = AmbConfig()
    async with AmbClient(config) as client:
        await client.publish(
            target_topic="amb:pack.broadcast",
            kind="event",
            source_wolf="my-wolf",
            payload={"event": "hello"}
        )

asyncio.run(publish_event())

Auth contract

The credential resolution order (matches a2a_amb_bridge.py):

  1. AMB_REDIS_PASSWORD env var (explicit override) wins.
  2. AMB_PASSWORD_FILE (default /run/credentials/hermes-amb-consumer-<wolf>.service/amb-password) — the canonical systemd-LoadCredential path on Mononoke.
  3. None — broker has no auth (fine for dev rigs).

Production paths always use #2 to avoid leaking the credential via systemctl show or /proc/<pid>/environ.

Cross-pack contract

  • Wire field name: AMB envelopes use the data= field of XADD (NOT envelope=) per wolf-council/amb-a2a-protocol v3.0.1 changelog.
  • Topic topology: amb:wolf.<name>.{event,command,status}, amb:pack.broadcast, amb:pack.<room>, amb:kanban:task:completed, amb:req.<from>.<to>:<uuid>.
  • Socket timeout: 5.0 seconds (synthesis §9.9). Mandatory.

Provenance

Extracted from hermes-agent branch feature/amb-client-2026-09 on 2026-09-09. Phase 1B of a2a-amb-kanban-prexx project (synthesis v2.0 §3, §5). OMP review at /tmp/omp-amb-client-review.md (San fallback).

License

Apache-2.0