Gateway service
The gateway service is the long-running host process that connects messaging platforms to agent sessions. It accepts platform events, selects or restores the right session, runs agent turns, and sends replies back through the platform that received the event. It also keeps the host observable and usable when a platform, session, network link, or agent turn fails.
Service boundary
The gateway is the coordination boundary between external platforms, durable session state, and agent execution. gateway/run.py exposes GatewayRunner and start_gateway() as the service entry points; the runner owns platform adapters, session routing, turn execution, and shutdown state.
The service keeps these responsibilities together because a reply must preserve the identity of the inbound event. The receiving platform and profile determine authorization, session routing, runtime scope, and the delivery target. In a multi-profile host, the same gateway can serve several profile-specific adapters without treating them as one default identity.
The main service areas are:
- Platform intake: Connects configured adapters and converts platform traffic into common gateway events.
- Session routing: Maps an event to a durable conversation and its active in-memory state.
- Agent execution: Runs one or more agent turns while tracking active work and busy-session input.
- Response delivery: Sends final replies, media, progress, and streamed output through the correct adapter.
- Host health: Publishes service and platform state, watches for stalls, retries recoverable failures, and supports clean drain or restart.
References: gateway/run.py• L3357-3363 gateway/run.py• L5754-5758
Event-to-response flow
The gateway turns an external event into a response through a staged path. The adapter returns quickly after admission so the service can receive control commands and later messages while an agent turn is active.
This diagram shows the high-level path from platform input to platform output.
flowchart LR
A[Platform event] --> B[Adapter normalization]
B --> C[Identity and authorization]
C --> D[Session key and durable session]
D --> E[Active-session guard]
E --> F[Agent turn]
F --> G[Response and delivery ledger]
G --> H[Platform reply or stream]
F --> I[Transcript and session state]
I --> D
The first two gates protect the rest of the system. The event is canonicalized before a session key is derived, then authorization and platform policy decide whether the event may enter a session. A busy session queues normal follow-up input, while control and approval commands can reach the active turn directly.
The detailed intake and turn path is described in Inbound-to-turn routing. Platform sends, media, and streaming are described in Platform delivery.
References: gateway/run_inbound.py• L167-257 gateway/…/base.py• L4038-4078 gateway/…/base.py• L4080-4125
Active session model
An active session is the gateway's live view of a durable conversation. The session store maps a session key to a session identity and durable session ID, while runner state tracks the current agent, turn lease, queued input, and other short-lived work for that key.
The session key is a routing address, not the whole conversation. Several routing keys can point to one durable session, so the gateway also uses a session-level lease to prevent two turns from loading and writing the same transcript at the same time. Session boundaries such as reset, switch, or explicit suspension change that mapping without treating time alone as a reason to replace a conversation.
Session creation, persistence, recovery, and cleanup are covered in Session lifecycle.
References: gateway/run.py• L3410-3435 gateway/run.py• L3560-3568 gateway/session_lifecycle.py• L58-94 gateway/session_recovery.py• L96-103
Agent turn execution
An agent turn is the unit that reads the session context, runs the agent and its tools, records the result, and prepares delivery. GatewayTurnMixin resolves the session and runtime before entering the agent, then shapes the result for the destination platform.
The gateway treats execution and admission as separate concerns. It marks execution only after routing, authorization, and turn preparation pass. During execution it can expose progress, accept interrupts, detect inactivity, and preserve a queued follow-up for a later turn. The turn runs inside the owning profile scope so model credentials, tools, memory, and files belong to the profile that received the event.
The gateway also keeps final response handling separate from streaming. A stream may show interim work, but the turn still produces one final response that controls transcript persistence and final delivery.
References: gateway/run_turn.py• L2144-2213 gateway/run_turn.py• L2928-2935 gateway/turn_executor.py• L9-16
Platform delivery
Platform adapters provide the service boundary for connection, receive, send, media, and platform-specific message features. The common adapter contract lets the gateway use one event and delivery flow across interactive chat platforms, webhooks, relays, and other transports.
Delivery uses the inbound event's pinned identity and destination metadata. This preserves the correct profile, chat, thread, and reply anchor across normal replies, resumed work, queued follow-ups, media, and reconnects. Streaming-capable adapters can update one cumulative message during a turn; the final response closes that stream instead of creating a second copy.
See Platform delivery for the delivery and streaming contract.
References: gateway/…/base.py• L1917-2019 gateway/…/base.py• L116-142 gateway/run_adapters.py• L905-929
Startup and recovery
Startup restores the gateway as a service, not only as a process. It checks access and prior-run state, recovers interrupted sessions, starts platform adapters, and opens the inbound gate only after the service has a usable serving state.
During restore, new external events wait in a startup queue so they do not race synthetic resume turns. A crash-left active-turn marker becomes a bounded resume request when the stored state shows that the previous process stopped during execution. A clean shutdown clears these markers instead, which prevents an already completed turn from running again.
The startup sequence also separates retryable platform failures from failures that need operator action. A gateway can enter degraded service state while it keeps healthy platforms available.
Desktop boot treats a connection and its served profile as one routing scope. It resolves the profile from the selected gateway before it publishes the connection or loads settings and sessions. When a gateway changes, the desktop re-homes that pair together so requests do not reach a valid gateway with a profile that belongs to the old one. Restored profile choices are checked against the gateway's current profile roster and fall back to an available profile when the saved choice no longer exists.
References: gateway/run_startup.py• L729-749 gateway/run_startup.py• L1616-1681 gateway/session_lifecycle.py• L140-205 apps/…/use-gateway-boot.ts• L748-835 apps/…/use-gateway-boot.ts• L855-1003 apps/…/use-gateway-boot.ts• L1525-1723 apps/…/use-gateway-boot-stale-profile.test.tsx• L65-182
Host health and service continuity
Host health combines process liveness, platform state, session work, and storage checks. The gateway writes runtime status for service observers, records active work while draining, and exposes bounded readiness checks that do not mutate runtime state.
The event loop has heartbeat and watchdog support so a blocked loop or stalled turn can be distinguished from an idle gateway. Session watchers reclaim idle resources, prune old routing entries, and report genuine session stalls. Platform failures enter a reconnect loop with backoff; retryable failures keep trying, while non-retryable failures remain visible as degraded or fatal state.
The desktop client applies the same continuity goal to its gateway view. It probes an apparently open connection after sleep or network recovery, retries transport failures with bounded backoff, and delays force-close while an active turn may only be slow. This keeps a healthy turn alive while still recovering a half-open connection that would otherwise make later requests hang.
The service manager can therefore make a useful choice: keep the gateway alive when one platform is down, restart it when the process is unhealthy, or wait for active work during a planned drain. The desktop re-home path also keeps the active connection, profile scope, and session refresh aligned during a gateway change.
References: gateway/readiness.py• L72-119 gateway/run_watchers.py• L37-75 gateway/run_adapters.py• L710-757 gateway/run.py• L3945-3958 apps/…/use-gateway-boot.ts• L491-735 apps/…/use-gateway-boot.ts• L1169-1208 apps/…/use-gateway-boot-rehome-scope.test.tsx• L152-186
Shutdown and drain
Shutdown is a controlled transition from serving to drained. The gateway stops admitting new work, lets active turns and related background work finish within the configured budget, preserves recoverable work when a deadline forces interruption, and then releases adapters and other resources.
The active-work count includes more than visible agent turns. It covers scheduled jobs, API runs, and deferred agent workers so the service does not report idle while work can still change a session or produce a reply. A planned restart uses the same drain model and leaves enough durable information for the next process to recover unfinished work.
References: gateway/run_shutdown.py• L171-220 gateway/run_shutdown.py• L37-66 gateway/session_lifecycle.py• L164-216
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to event identity or session-key derivation must stay aligned with durable session recovery and delivery-adapter selection.
- Changes to busy-session handling must preserve the separate paths for queued user input and inline control or approval commands.
- Changes to final or streamed sends must preserve one final response, delivery-ledger ownership, and the adapter's stream sealing rules.
- Changes to startup restore must preserve the gate that prevents live inbound events from racing resume turns.
- Changes to desktop connection boot or re-home must publish the gateway connection and its served profile as one request scope, then refresh data against that scope.
- Changes to restored desktop profiles must preserve roster validation and the fallback that prevents stale saved profiles from reaching settings or session requests.
- Changes to active-work accounting must include every work source that can hold shutdown or scale-to-zero open.
- Changes to platform reconnect state must keep runtime status, retry ownership, and held inbound events consistent.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| An event is keyed before its identity is resolved | A message can run under the wrong profile or session | Canonicalize the source before routing and fail closed for an unresolved profile |
| A normal follow-up bypasses the busy-session queue | Two turns can use one conversation at the same time or input can be lost | Keep the adapter guard and runner busy path in sequence |
| A control or approval command enters the normal queue | /stop, /new, /approve, or /deny can deadlock or arrive too late | Dispatch commands that bypass the active-session guard inline |
| A crash leaves an active-turn marker | The next gateway may repeat or lose work | Reconcile the marker with the transcript and convert only valid interrupted work to resume state |
| A platform connect or send blocks without a bound | One bad transport can stop startup, reconnect, or shutdown for the whole host | Use bounded connect, delivery, and adapter teardown waits |
| A streamed final is sent as a new plain message | Users see duplicate or frozen output | Let the stream consumer seal one final response and reconcile by edit when possible |
| Runtime status is written as a stale snapshot | Health tools report the wrong serving or drain state | Merge status updates and persist the latest complete snapshot off the event loop |
| A desktop gateway switch publishes a new connection with the old profile | Settings, profile, or session requests go to the wrong gateway scope | Resolve the served profile first and publish the connection/profile pair together |
| A saved desktop profile was removed from the restored gateway | Boot can request settings for a profile that the gateway does not serve | Validate the saved profile against the current roster and use the available fallback |
Key files
| File | Why to read it |
|---|---|
| gateway/run.py | Main runner facade, service entry point, shared lifecycle state, and status updates |
| gateway/run_startup.py | Startup gates, adapter bring-up, restore, and resume coordination |
| gateway/run_inbound.py | Event admission, authorization handoff, and inbound preparation |
| gateway/run_turn.py | Session resolution, agent execution, result shaping, and turn completion |
| gateway/session_lifecycle.py | Durable turn markers, suspension, resume state, and pruning |
| gateway/session_recovery.py | Session-key namespaces and rebuilding routing state from durable rows |
| gateway/…/base.py | Common adapter boundary and active-session input behavior |
| gateway/run_adapters.py | Adapter connect, failure recovery, reconnect, and platform state |
| gateway/run_watchers.py | Session housekeeping and stall detection |
| gateway/run_shutdown.py | Active-work accounting, drain, restart, and shutdown behavior |
| gateway/readiness.py | Bounded health and readiness checks |
| gateway/status.py | Runtime status persistence and process health records |
| apps/…/use-gateway-boot.ts | Desktop gateway boot, profile-scoped re-home, reconnect, liveness checks, and session refresh |
| apps/…/use-gateway-boot-rehome-scope.test.tsx | Proof that a connection change moves the connection and profile scope together |
| apps/…/use-gateway-boot-stale-profile.test.tsx | Proof that restored profile state falls back to a profile served by the gateway |