@miadi/hooks-gateway

Optional event gateway boundary for Miadi hook events.

@miadi/hooks-core is the local-first package: it normalizes agent hook events, builds canonical envelopes, and records sessiondata. @miadi/hooks-gateway is the optional service layer above it: it receives canonical hook events, records a durable ledger, routes events to streams, and coordinates workers.

Intent

Miadi remains local-first. Partners can use hooks-core without running a gateway. Use hooks-gateway when events need durable replay, delivery status, external subscribers, or cross-host coordination.

Boundary

hooks-gateway owns:

• HTTP ingress for HookEventEnvelope events from hooks-core
• idempotency checks and durable event ledger
• queue/stream publishing to Redis or NATS JetStream
• worker dispatch for plan-insight, interpretation, export, and partner delivery
• delivery status and replay cursors

hooks-gateway does not own:

• provider-specific hook behavior
• local JSONL sessiondata writing
• agent runtime execution

Implemented first slice (0.1.0)

The SPEC's first slice exists as code (jgwill/Miadi#485, lineage jgwill/Miadi#484), with miadi-chronicle episode 128 as its acceptance story — a durable boundary where the same archived event replayed is one run and a revised payload is a new run:

• createGateway({ ledger, publishers }) — POST /events validating the @miadi/hooks-core envelope (schema_version, id, idempotency_key, canonical_event).
• GatewayLedger interface + MemoryLedger — duplicate idempotency_key returns the original event id with a counted attempt and re-runs no side effects; nothing is erased. The Postgres ledger from the SPEC lands behind this interface.
• StreamPublisher seam + createLogWorker() — the one worker of the slice: it logs received event IDs. Redis/NATS publishers land behind the same seam.
• httpSink(url) — an opt-in @miadi/hooks-core HookSink delivering envelopes to a gateway; receipts and failures surface through callbacks, never silently dropped. Local capture stays network-free.

Verified end to end in test/gateway.test.ts: an episode 128 _codex_* line processed by the real codexAdapter flows through httpSink into the ledger; its exact replay answers duplicate, attempts: 2.

Not in this slice, by design: Postgres, Redis/NATS, delivery-status workers, replay cursors, Hookdeck perimeter.

• partner-specific business logic

Infrastructure Shape

• Redis or NATS: event stream and consumer coordination.
• Postgres: durable ledger, idempotency keys, subscriptions, delivery attempts.
• Workers: consume events and perform side effects.
• Hookdeck: optional perimeter for external webhook delivery, retries, observability, and partner destination management.

Hookdeck Position

Hookdeck is not required for local Miadi hooks. It is useful at the perimeter:

• Hookdeck CLI for development forwarding and inspection.
• Managed Hookdeck or Outpost for partner-facing delivery, retries, and destination management.

Short version: hooks-core defines and records local events; hooks-gateway distributes them; Hookdeck supports external delivery.