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.
| State | Meaning | Recovery behavior |
|---|---|---|
pending | The send has not started. | Redeliver plainly. |
attempting | The process may have sent the message before it stopped. | Redeliver with a visible recovered marker. |
failed | The platform rejected the send. | Retry after reconnect, rate-limit wait, or backoff when safe. |
delivered | The platform accepted the result. | Keep for short retention, then prune. |
abandoned | The 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
| Trigger | Consequence | Guard |
|---|---|---|
| Crash after a final send starts but before acknowledgement | The 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 visible | A 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 guard | A later plain send could bypass the destination decision. | The run records the decline and suppresses later fallback sends. |
| A platform adapter disconnects during service | Replies 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 bot | Repeated retries waste platform rate limits. | The target is marked dead and skipped until a successful send clears it. |
Key files
| File | Why to read it |
|---|---|
| gateway/platform_registry.py | Adapter discovery, capability metadata, and adapter creation. |
| gateway/…/base.py | Shared adapter contract, media delivery, final-send ledger bracket, and rendering hooks. |
| gateway/delivery.py | Target parsing, native-versus-relay transport choice, output limits, and outbound policy. |
| gateway/stream_events.py | Typed agent-to-gateway streaming contract. |
| gateway/stream_dispatch.py | Event routing from the agent worker to the consumer and adapter. |
| gateway/stream_consumer.py | Stream buffering, segment boundaries, final reconciliation, and consumer state. |
| gateway/stream_consumer_transport.py | Native, draft, edit, and first-send transport order. |
| gateway/stream_consumer_fallback.py | Continuation sends, chunking, cursor cleanup, and failed-edit recovery. |
| gateway/delivery_ledger.py | Durable final-response obligations and redelivery rules. |
| gateway/run_startup.py | Startup claims and redelivery of owed final responses. |
| gateway/run_adapters.py | Adapter connect, disconnect, and reconnect supervision. |
| gateway/run_notifications.py | Home-channel, process, update, media, and queued completion notifications. |
| agent/stream_delivery.py | Agent-side stream ownership, filtering, callback fan-out, and interim deduplication. |