Routing — Message Dispatch & Session Management

TypeScript RPC WebSocket Stateful

What Is This & Why Does It Exist?

Once a client is authenticated, its requests need to reach the right handler with the right session context. The Routing subsystem is the dispatcher that makes this happen.

Architecture

The Routing layer sits after authentication and protocol validation. It maps RPC method names to handlers, manages session state, and coordinates broadcasts.

flowchart TB
    subgraph Input
        REQ["Validated RequestFrame
method + params"]
    end

    subgraph Routing["Routing Layer"]
        DISPATCH["GatewayRequestHandlers
Record of string to GatewayRequestHandler"]
        OPTS["GatewayRequestOptions
req, client, respond, context"]

        subgraph Session["Session Manager"]
            CREATE["Create Session"]
            RESUME["Resume Session"]
            PATCH["Patch Session"]
            LIFE["Lifecycle Events"]
        end

        subgraph Identity["Identity Resolver"]
            RESOLVE["resolveAssistantIdentity()"]
            DEFAULT["DEFAULT_ASSISTANT_IDENTITY"]
        end
    end

    subgraph Targets["Target Systems"]
        AGENT["Agent Runtime"]
        WIZARD["Wizard Sessions"]
        CONFIG["Config Handlers"]
        PRESENCE["Presence System"]
    end

    REQ --> DISPATCH
    DISPATCH --> OPTS
    OPTS --> Session
    OPTS --> Identity
    OPTS --> AGENT
    OPTS --> WIZARD
    OPTS --> CONFIG
    OPTS --> PRESENCE
    Session --> LIFE
    LIFE --> BROADCAST["broadcast()"]

Data Flow

sequenceDiagram
    participant C as Client
    participant D as Dispatcher
    participant H as Handler
    participant S as Session Manager
    participant I as Identity Resolver
    participant A as Agent Runtime
    participant B as Broadcast

    C->>D: RequestFrame {method, params, id}
    D->>D: lookup GatewayRequestHandlers[method]
    D->>H: handler(GatewayRequestHandlerOptions)
    H->>I: resolveAssistantIdentity(cfg, agentId)
    I-->>H: AssistantIdentity {name, avatar, emoji}
    H->>S: create/resume GatewaySessionRow
    S-->>H: session {key, kind, status}
    H->>A: forward to agent runtime
    A-->>H: response payload
    H->>S: persistGatewaySessionLifecycleEvent()
    S->>B: broadcast lifecycle event
    H-->>C: ResponseFrame {ok, payload}

Key Types & Functions

Session Kinds

Session Row Key Fields

Code Examples

Defining a Request Handler

import { GatewayRequestHandler } from './server-methods/types';

const handleSessionsList: GatewayRequestHandler = async (opts) => {
  const { req, client, respond, context } = opts;
  const params = req.params as SessionsListParams;

  const result: SessionsListResult = await context.deps.sessionStore.list({
    limit: params.limit ?? 50,
    offset: params.offset ?? 0,
  });

  respond(true, result);
};

// Register in the handler map
const handlers: GatewayRequestHandlers = {
  'sessions.list': handleSessionsList,
  'sessions.send': handleSessionsSend,
  'config.get': handleConfigGet,
  // ... 80+ more methods
};

Resolving Assistant Identity

import {
  resolveAssistantIdentity,
  AssistantIdentity,
  DEFAULT_ASSISTANT_IDENTITY,
} from './assistant-identity';

const identity: AssistantIdentity = resolveAssistantIdentity({
  cfg: openClawConfig,
  agentId: 'main',
  workspaceDir: '/home/user/.openclaw',
});

// identity.name => "Assistant" (or custom name, max 50 chars)
// identity.avatar => "A" (or URL, max 200 chars)
// identity.emoji => undefined (or custom, max 16 chars)

Persisting Session Lifecycle Events

import {
  persistGatewaySessionLifecycleEvent,
  deriveGatewaySessionLifecycleSnapshot,
} from './session-lifecycle-state';

const snapshot = deriveGatewaySessionLifecycleSnapshot({
  session: currentSession,
  event: { ts: Date.now(), data: { phase: 'end', status: 'done' } },
});

await persistGatewaySessionLifecycleEvent({
  sessionKey: 'sess_abc123',
  event: { ts: Date.now(), data: { phase: 'end' } },
});

Configuration

Deep-Dive Focus Pages

Directory Map

src/gateway/
├── assistant-identity.ts           ← AssistantIdentity, resolveAssistantIdentity
├── session-utils.types.ts          ← GatewaySessionRow (32+), SessionRunStatus
├── session-lifecycle-state.ts      ← Lifecycle snapshots, persistence
├── server-methods/
│   └── types.ts                    ← GatewayRequestHandler, GatewayRequestContext
├── server/
│   └── ws-types.ts                 ← GatewayWsClient (WebSocket client)
└── protocol/
    └── index.ts                    ← 80+ validators, ConnectParams, RequestFrame