Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / gateway-platform-delivery

Gateway platform delivery and streaming

The gateway connects one agent turn to many messaging services. Platform adapters receive and send platform-native events. Delivery routing, message rendering, streaming, recovery records, and notices then make the agent result visible without changing the agent-owned conversation history. This page is a child of Gateway service and relates to Gateway inbound and turn routing and Gateway session lifecycle and recovery.

Platform adapter boundary

The platform adapter is the gateway boundary for an external messaging service. It owns the service connection and its send operations, while the gateway owns session policy, turn control, and the choice of adapter for a reply.

Adapter discovery and lifecycle

The registry lets built-in and plugin adapters use the same gateway path. A platform name resolves to an adapter entry that can check requirements, validate configuration, create the adapter, and describe delivery capabilities. Plugin adapters can load only when a caller needs them, which keeps unrelated gateway work light.

The gateway connects each enabled adapter with a bounded wait. A failed but retryable adapter moves to background reconnect handling. This lets other platforms continue to carry messages while the failed service recovers.

References: gateway/platform_registry.py• L42-81 gateway/platform_registry.py• L351-429 gateway/run_adapters.py• L180-208 gateway/run_adapters.py• L710-735

Adapter capabilities

Adapters expose the parts of a platform contract that differ between services. These capabilities tell the gateway whether it can edit messages, stream native frames, use draft previews, split long text, attach media, or show a typing state. The gateway uses these answers to select a safe presentation path instead of assuming that every platform supports the same actions.

References: gateway/…/base.py• L1917-1945 gateway/…/base.py• L2035-2095 website/…/adding-platform-adapters.md• L15-29

Outbound delivery

Outbound delivery turns a completed response or scheduled result into one or more platform sends. It resolves the logical target, preserves chat and thread context, applies platform limits, and reports each target result without letting one failed target hide the others.

Delivery target resolution

Targets can point to the originating conversation, a platform home channel, a specific chat and thread, or local output. A concrete native adapter is preferred. A relay adapter is used only when its authenticated connection declares that it fronts the requested logical platform.

The target keeps the platform, chat, and thread separate from the transport that carries the send. This distinction matters for relays and for multiplexed profiles because the answer must leave through the bot that owns the conversation.

flowchart LR
    A[Response or scheduled result] --> B[Delivery target]
    B --> C{Native adapter available?}
    C -- Yes --> D[Native platform transport]
    C -- No --> E{Relay fronts target?}
    E -- Yes --> F[Relay transport with logical platform]
    E -- No --> G[Delivery failure]

References: gateway/delivery.py• L48-83 gateway/delivery.py• L109-150 gateway/delivery.py• L164-208

Text and media delivery

The adapter sends the text result with thread and reply metadata. Media is a separate delivery phase so a response can carry images, audio, video, or documents without mixing attachment rules into text routing. Explicit media directives control post-stream attachments; a plain local path is not promoted to an attachment after text has already streamed.

Long scheduled output is saved as a full local artifact before non-chunking platforms receive a shortened message. Platforms that split messages receive the full content through their own chunking path. Silence narration is filtered at the shared platform egress for normal assistant replies, while local artifacts and scheduled job output keep their content.

References: gateway/…/base.py• L4310-4376 gateway/run_notifications.py• L349-408 gateway/delivery.py• L223-258 gateway/delivery.py• L279-333

Streaming event consumption

Streaming separates agent progress from platform presentation. The agent emits facts about text, message boundaries, commentary, tool calls, and gateway notices. The gateway consumes those facts asynchronously and lets the selected adapter decide how much of them the user should see.

Stream event flow

The stream event contract carries transport facts, not a second conversation record. Text deltas and message stops feed the stream sink. Tool-start events become optional progress chrome. Long-run hints and gateway notices go to gateway-owned handlers.

sequenceDiagram
    participant Agent as Agent worker
    participant Events as Stream events
    participant Dispatch as Gateway dispatcher
    participant Consumer as Stream consumer
    participant Adapter as Platform adapter

    Agent->>Events: Emit text, boundary, tool, or notice
    Events->>Dispatch: Deliver typed event
    Dispatch->>Consumer: Queue text or segment update
    Dispatch->>Adapter: Format tool progress or handle notice
    Consumer->>Adapter: Send frame, draft, edit, or message
    Agent->>Consumer: Provide authoritative final response
    Consumer->>Adapter: Close or reconcile final delivery

References: gateway/stream_events.py• L1-75 gateway/stream_dispatch.py• L21-81 gateway/…/base.py• L2097-2135

Stream transport modes

The consumer chooses the strongest transport that the chat supports. Native streams keep a platform stream open. Draft streams show an ephemeral preview and still require a regular final message. Edit streams send an initial message and update it as more text arrives.

The consumer uses one ordered queue for worker-thread callbacks and the async send loop. It can split oversized text, close code fences for final display, and stop a stale stream when the session run is no longer current. Streaming is presentation only; the completed response remains the source for final delivery and history.

References: gateway/stream_consumer.py• L60-105 gateway/stream_consumer.py• L527-610 gateway/stream_consumer_transport.py• L127-168 gateway/stream_consumer_transport.py• L313-368

Message rendering

Message rendering translates shared stream facts into platform-appropriate visible content. The gateway keeps the event meaning stable, while the adapter supplies platform-specific tool labels, formatting, and support for rich or native stream features.

Progressive message rendering

The consumer normally edits one visible preview as text grows. At a tool boundary it can close the current segment and start another message. Commentary remains an interim message and must not be mistaken for the turn final. When a platform treats the stream itself as the message, frames stay cumulative and prefix-stable until the consumer declares the final payload.

The final response is authoritative because it can include text added after the last stream delta. The consumer compares the delivered payload with that final response before the gateway suppresses a later final send. This prevents a preview or an interim message from silently standing in for an incomplete answer.

References: gateway/stream_consumer.py• L191-227 gateway/stream_consumer.py• L286-358 gateway/stream_consumer.py• L849-904 gateway/stream_consumer.py• L911-920

Tool and interim presentation

Tool progress is optional platform chrome. The adapter can render a short or detailed tool line, or return no line when the platform has no suitable presentation. Commentary and reasoning are filtered before they reach the user-facing stream, while selected callbacks can send visible interim content or audio to other sinks.

References: gateway/stream_dispatch.py• L58-81 gateway/…/base.py• L2112-2135 agent/stream_delivery.py• L298-362

Delivery ledger

The delivery ledger records a final response that the gateway owes to a platform. It closes the gap between turn completion and a platform acknowledgement, so a process crash does not make a completed answer disappear without a recovery path.

Obligation states

The normal final text path records an obligation before it sends. It marks the row as attempting immediately before the network wait, then marks it delivered only after a successful result. A definitive rejection becomes failed and can be retried under the platform and target rules.

StateMeaningRecovery behavior
pendingThe send has not started.Redeliver plainly.
attemptingThe process may have sent the message before it stopped.Redeliver with a visible recovered marker.
failedThe platform rejected the send.Retry after reconnect, rate-limit wait, or backoff when safe.
deliveredThe platform accepted the result.Keep for short retention, then prune.
abandonedThe age or attempt bound is exhausted.Stop automatic redelivery.

References: gateway/delivery_ledger.py• L1-10 gateway/…/base.py• L4245-4307 gateway/…/base.py• L4378-4401

Crash and reconnect recovery

At startup the gateway claims rows whose owner process is no longer alive and only spends an attempt when a matching platform transport is available. It clears resume markers before sending because the answer already exists in the ledger and must not cause the agent turn to run again. A reconnect path can claim transient failures owned by the current adapter without waiting for a full process restart.

Rate-limit failures keep a deadline. Dead chats are not retried because the target is known to be gone. Other failed sends use bounded backoff and visible recovery markers when delivery may have reached the platform.

References: gateway/run_startup.py• L336-377 gateway/run_startup.py• L445-490 gateway/run_startup.py• L520-552 gateway/delivery_ledger.py• L368-446

Notifications

Notifications are gateway-generated messages that report service state rather than answer user content. They use the same platform transports as replies but follow separate privacy, diagnostic, and dedup rules.

Service and diagnostic notices

Startup, restart, update, storage, and platform notices can go to configured home channels. A notice may use a private send when the platform supports it and falls back to the public conversation when that private path fails. Diagnostic notices are classified separately so display policy can suppress them without suppressing human-requested content.

References: gateway/run_notifications.py• L176-208 gateway/run_notifications.py• L900-922 gateway/warning_notifications.py• L18-37 gateway/warning_notifications.py• L65-101

Process completion notices

Background process completion wakes re-enter the gateway as internal events. The gateway marks their machine origin so the agent does not treat them as human instructions. The notice then follows the owning session and profile route before the platform adapter sends it.

References: gateway/run_notifications.py• L92-111 gateway/run_notifications.py• L114-122 gateway/run_notifications.py• L125-130

Fallback behavior

Fallback behavior keeps useful output available when a preferred transport, adapter, or target is not usable. Each fallback preserves the difference between an incomplete preview, a complete answer, and a send whose acknowledgement is uncertain.

Streaming delivery fallback

If native or draft streaming fails, the consumer falls back to message editing or a normal send. If edits stop working after part of the answer is visible, it sends only the unseen continuation when possible. It sends the full answer only when the visible prefix cannot be trusted, and it avoids a plain resend when the connector has rejected the destination.

If a final edit times out, the consumer treats the result as potentially visible and records that uncertainty. If a stream is sealed and another delivery lane must finish the turn, that lane edits the existing message first. It sends a new message only when no editable message exists.

References: gateway/stream_consumer_transport.py• L347-426 gateway/stream_consumer_fallback.py• L96-162 gateway/stream_consumer_fallback.py• L164-209 gateway/run_notifications.py• L429-475

Platform and target fallback

When an adapter disconnects, the gateway queues it for reconnect instead of blocking other platforms. A platform that cannot be created because its requirements or configuration are not valid is reported as unavailable rather than treated as a working transport. A target that is known to be permanently unreachable is skipped until a later explicit success clears that status.

References: gateway/run_adapters.py• L47-53 gateway/run_adapters.py• L252-285 gateway/run_adapters.py• L794-874 gateway/delivery.py• L179-207

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the adapter capability contract aligned with stream transport selection. A new native or draft capability must also define its final and failure behavior.
  • Keep the final-send path and queued-response path inside the delivery-ledger bracket. A new final egress path can otherwise lose a response between turn completion and platform acknowledgement.
  • Preserve the distinction between the logical target platform and the live relay transport. A relay must not send a target through an unrelated platform or profile.
  • Preserve stream-final reconciliation when adding a new send or edit door. Interim sends must not seal a stream, and a sealed stream must be reconciled by edit before a new send.
  • Keep notification classification separate from human content. Diagnostic policy must not mute a user-requested reply.

Important failure modes

TriggerConsequenceGuard
Crash after a final send starts but before acknowledgementThe platform may show a duplicate after recovery.Ledger state becomes attempting and recovery adds a visible marker.
Stream edit fails after a partial answer is visibleA full resend can duplicate the visible prefix.The fallback computes and sends only the unseen continuation.
Draft or edit egress is refused by a relay guardA later plain send could bypass the destination decision.The run records the decline and suppresses later fallback sends.
A platform adapter disconnects during serviceReplies and notices cannot reach that platform.The adapter leaves the live map and enters bounded background reconnect handling.
A chat is deleted or a user blocks the botRepeated retries waste platform rate limits.The target is marked dead and skipped until a successful send clears it.

Key files

FileWhy to read it
gateway/platform_registry.pyAdapter discovery, capability metadata, and adapter creation.
gateway/…/base.pyShared adapter contract, media delivery, final-send ledger bracket, and rendering hooks.
gateway/delivery.pyTarget parsing, native-versus-relay transport choice, output limits, and outbound policy.
gateway/stream_events.pyTyped agent-to-gateway streaming contract.
gateway/stream_dispatch.pyEvent routing from the agent worker to the consumer and adapter.
gateway/stream_consumer.pyStream buffering, segment boundaries, final reconciliation, and consumer state.
gateway/stream_consumer_transport.pyNative, draft, edit, and first-send transport order.
gateway/stream_consumer_fallback.pyContinuation sends, chunking, cursor cleanup, and failed-edit recovery.
gateway/delivery_ledger.pyDurable final-response obligations and redelivery rules.
gateway/run_startup.pyStartup claims and redelivery of owed final responses.
gateway/run_adapters.pyAdapter connect, disconnect, and reconnect supervision.
gateway/run_notifications.pyHome-channel, process, update, media, and queued completion notifications.
agent/stream_delivery.pyAgent-side stream ownership, filtering, callback fan-out, and interim deduplication.