docs: add start-here index and gateway lane-queue diagram

2026-02-15 11:20:32 -08:00
parent 3f877db762
commit 6e3f1fdd3f
3 changed files with 89 additions and 0 deletions
@@ -22,6 +22,50 @@ The gateway provides:
 - **Streaming Events**: Real-time updates during agent processing
 - **HTTP Server**: Serves static dashboard and handles webhook endpoints

+### Execution Model (Sessions + Per-Session Queue)
+
+Two concepts matter for correct clients:
+
+- **connectionId**: a single WebSocket connection identity (assigned on connect)
+- **sessionId**: the conversation/session the connection is attached to (defaults to a per-connection session, but can be switched to resume an old session)
+
+The gateway serialises agent work **per session**, not per WebSocket connection:
+
+- Requests that target the same `sessionId` run one-at-a-time (FIFO) in a per-session lane.
+- Requests for different sessions can run in parallel.
+
+This is implemented via a per-lane queue (`LaneQueue`) in the gateway server, and used by `agent.send` and `agent.cancel`.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant C as Client
+  participant G as Gateway (WS JSON-RPC)
+  participant LQ as LaneQueue (per-session)
+  participant SB as SessionBridge
+  participant A as AgentOrchestrator
+
+  C->>G: agent.send {connectionId, message}
+  G->>SB: resolve sessionId for connectionId
+  SB-->>G: sessionId (laneId)
+  G->>LQ: enqueue(laneId, work)
+
+  alt lane idle
+    LQ-->>G: starts work immediately
+  else lane busy
+    Note over LQ: work queued (FIFO) for this lane
+  end
+
+  G->>A: process(message) in that session
+  A-->>G: streaming events (content/tool_start/tool_end)
+  G-->>C: events + final done
+
+  C->>G: agent.cancel {connectionId}
+  G->>LQ: cancel(laneId) (queued items rejected)
+  G->>SB: cancel active op (best-effort)
+  G-->>C: result.cancelled=true/false
+```
+
 ### Base URL

 - WebSocket: `ws://localhost:18800` (or `wss://` if using TLS)