wind-agent-cli 1.37.2

package/server/modules/websocket/README.md

@@ -0,0 +1,273 @@
+# WebSocket Module
+
+This module owns the server-side WebSocket gateway used by:
+
+1. Chat streaming (`/ws`)
+2. Interactive terminal sessions (`/shell`)
+3. Plugin WebSocket passthrough (`/plugin-ws/:pluginName`)
+
+It is intentionally structured as **small services** plus a **barrel export** in `index.ts`.
+
+## Public API
+
+`server/modules/websocket/index.ts` exports:
+
+1. `createWebSocketServer(server, dependencies)`  
+Creates and wires the shared `ws` server.
+2. `connectedClients` and `WS_OPEN_STATE`  
+Shared chat client registry and open-state constant used by other modules.
+
+## Why Dependency Injection Is Used
+
+The module receives runtime-specific functions from `server/index.ts` instead of importing legacy runtime files directly.
+
+Benefits:
+
+1. Keeps module boundaries clean (`server/modules/*` architecture rule).
+2. Makes each service easier to test in isolation.
+3. Keeps WebSocket transport concerns separate from provider runtime concerns.
+
+## Service Map
+
+| File | Responsibility |
+|---|---|
+| `services/websocket-server.service.ts` | Creates `WebSocketServer`, binds `verifyClient`, routes connection by pathname |
+| `services/websocket-auth.service.ts` | Authenticates upgrade requests and attaches `request.user` |
+| `services/chat-websocket.service.ts` | Handles the `/ws` chat protocol (`chat.send` / `chat.abort` / `chat.subscribe` / `chat.permission-response`) |
+| `services/chat-run-registry.service.ts` | Tracks live provider runs per app session id: seq numbering, event replay buffer, provider-id mapping, completion state |
+| `services/chat-session-writer.service.ts` | Gateway writer handed to provider runtimes: remaps provider session ids to app ids, swallows `session_created`, assigns `seq` |
+| `services/shell-websocket.service.ts` | Handles `/shell` PTY lifecycle, reconnect buffering, auth URL detection |
+| `services/plugin-websocket-proxy.service.ts` | Bridges client socket to plugin socket |
+| `services/websocket-writer.service.ts` | Adapts raw WebSocket to writer interface (`send`, `setSessionId`, `getSessionId`) for non-chat writer consumers |
+| `services/websocket-state.service.ts` | Holds shared chat client set and open-state constant |
+
+## High-Level Architecture
+
+```mermaid
+flowchart LR
+  A[HTTP Server] --> B[createWebSocketServer]
+  B --> C[verifyWebSocketClient]
+  B --> D{Pathname}
+  D -->|/ws| E[handleChatConnection]
+  D -->|/shell| F[handleShellConnection]
+  D -->|/plugin-ws/:name| G[handlePluginWsProxy]
+  D -->|other| H[close()]
+
+  E --> I[connectedClients Set]
+  E --> J[chatRunRegistry + ChatSessionWriter]
+  F --> K[ptySessionsMap]
+  G --> L[Upstream Plugin ws://127.0.0.1:port/ws]
+
+  I --> M[projects.service loading_progress]
+  I --> N[sessions-watcher.service session_upserted]
+```
+
+## Connection Handshake + Routing
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant WSS as WebSocketServer
+  participant Auth as verifyWebSocketClient
+  participant Router as connection router
+  participant Chat as /ws handler
+  participant Shell as /shell handler
+  participant Proxy as /plugin-ws handler
+
+  Client->>WSS: Upgrade Request
+  WSS->>Auth: verifyClient(info)
+  alt Platform mode
+    Auth->>Auth: authenticateWebSocket(null)
+    Auth->>Auth: attach request.user
+  else OSS mode
+    Auth->>Auth: read token from ?token or Authorization
+    Auth->>Auth: authenticateWebSocket(token)
+    Auth->>Auth: attach request.user
+  end
+
+  alt Auth failed
+    Auth-->>WSS: false (reject handshake)
+  else Auth ok
+    Auth-->>WSS: true
+    WSS->>Router: on("connection", ws, request)
+    alt pathname == /ws
+      Router->>Chat: handleChatConnection(ws, request, deps.chat)
+    else pathname == /shell
+      Router->>Shell: handleShellConnection(ws, deps.shell)
+    else pathname startsWith /plugin-ws/
+      Router->>Proxy: handlePluginWsProxy(ws, pathname, getPluginPort)
+    else unknown
+      Router->>Router: ws.close()
+    end
+  end
+```
+
+## `/ws` Chat Flow
+
+When a chat socket connects:
+
+1. Add socket to `connectedClients`.
+2. Parse each incoming message with `parseIncomingJsonObject`.
+3. Dispatch by `data.type` (four message types, none provider-specific).
+4. On close, remove socket from `connectedClients`.
+
+### Session identity model
+
+The frontend only ever knows the **app session id** (allocated by
+`POST /api/providers/sessions` or discovered via the session index). The
+provider-native id (JSONL file name, CLI resume id) stays inside the backend:
+
+1. `chat.send` resolves the app id to `{ provider, project_path }` from the sessions DB and passes the **app session id** to the provider runtime.
+2. The provider runtime resolves the provider-native id from the sessions DB itself (`sessionsService.resolveProviderSessionId`) at the exact points its CLI/SDK needs it (resume flags, provider-owned databases). Runtimes key their process maps by the app session id, so abort and pending-approval lookups use app ids too.
+3. The `ChatSessionWriter` remaps every outbound event back to the app id, and turns `session_created` announcements into a DB mapping update instead of forwarding them.
+
+### Chat Message Dispatch
+
+```mermaid
+flowchart TD
+  A[Incoming WS message] --> B[parseIncomingJsonObject]
+  B -->|invalid| C[send kind:protocol_error]
+  B -->|ok| D{data.type}
+
+  D -->|chat.send| E[resolve session row -> startRun -> providerRuntimeService.run]
+  D -->|chat.abort| F[providerRuntimeService.abort + synthetic complete]
+  D -->|chat.subscribe| G[chat_subscribed ack + attach socket + replay events seq > lastSeq]
+  D -->|chat.permission-response| H[providerRuntimeService.resolveToolApproval]
+  D -->|other| I[send kind:protocol_error]
+```
+
+### Chat Notes
+
+1. **Unified envelope**: every server-to-client frame carries a `kind` — either a provider `NormalizedMessage` kind or a gateway kind (`chat_subscribed`, `session_upserted`, `loading_progress`, `protocol_error`). There is no second `type`-based protocol.
+2. **Unified terminal lifecycle**: every provider run ends with exactly one `complete` message built by `createCompleteMessage()` (`server/shared/utils.ts`): `{ kind: "complete", sessionId, actualSessionId, exitCode, success, aborted }`. The chat handler emits a synthetic `complete` for runs that crash or get aborted, and the run registry drops duplicate completes.
+3. **Per-run event log**: every live event gets a monotonically increasing `seq`. `chat.subscribe { sessions: [{ sessionId, lastSeq }] }` re-attaches the live stream to the requesting socket (any provider, not just Claude) and replays events with `seq > lastSeq`. If the buffer no longer covers `lastSeq`, the client refreshes over REST.
+4. `chat_subscribed` includes `isProcessing` (replaces `check-session-status`) and `pendingPermissions` (replaces `get-pending-permissions`).
+
+## `/shell` Terminal Flow
+
+The shell handler manages persistent PTY sessions keyed by:
+
+`<projectPath>_<sessionIdOrDefault>[_cmd_<hash>]`
+
+This enables reconnect behavior and isolates command-specific plain-shell sessions.
+
+### Shell Lifecycle
+
+```mermaid
+stateDiagram-v2
+  [*] --> WaitingInit
+  WaitingInit --> ValidateInit: message.type == init
+  ValidateInit --> ReconnectExisting: session key exists and not login reset
+  ValidateInit --> SpawnNewPTY: valid path + valid sessionId
+  ValidateInit --> EmitError: invalid payload/path/sessionId
+
+  ReconnectExisting --> Running: attach ws, replay buffer
+  SpawnNewPTY --> Running: pty.spawn + wire onData/onExit
+
+  Running --> Running: input -> pty.write
+  Running --> Running: resize -> pty.resize
+  Running --> Running: onData -> buffer + output + auth_url detection
+  Running --> Exited: onExit
+  Running --> Detached: ws close
+
+  Detached --> Running: reconnect before timeout
+  Detached --> Killed: timeout reached -> pty.kill
+  Exited --> [*]
+  Killed --> [*]
+  EmitError --> WaitingInit
+```
+
+### Shell Behaviors in Detail
+
+1. `init`:
+Reads `projectPath`, `sessionId`, `provider`, `hasSession`, `initialCommand`, `isPlainShell`.
+2. Login reset:
+For login-like commands, existing keyed PTY session is killed and recreated.
+3. Validation:
+Path must exist and be a directory; `sessionId` must match safe pattern.
+4. Command build:
+Provider-specific command construction with resume semantics.
+5. PTY output buffering:
+Stores up to 5000 chunks for replay on reconnect.
+6. URL detection:
+Strips ANSI, accumulates text buffer, extracts URLs, emits `auth_url` once per normalized URL, supports `autoOpen`.
+7. Close behavior:
+Socket disconnect does not instantly kill PTY; session is kept alive and terminated on timeout.
+
+## `/plugin-ws/:pluginName` Proxy Flow
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Proxy as handlePluginWsProxy
+  participant PM as getPluginPort
+  participant Upstream as Plugin WS
+
+  Client->>Proxy: Connect /plugin-ws/:name
+  Proxy->>Proxy: Validate pluginName regex
+  alt Invalid name
+    Proxy-->>Client: close(4400, "Invalid plugin name")
+  else Valid
+    Proxy->>PM: getPluginPort(name)
+    alt Plugin not running
+      Proxy-->>Client: close(4404, "Plugin not running")
+    else Port found
+      Proxy->>Upstream: new WebSocket(ws://127.0.0.1:port/ws)
+      Client-->>Upstream: relay messages bidirectionally
+      Upstream-->>Client: relay messages bidirectionally
+      Upstream-->>Client: close propagation
+      Client-->>Upstream: close propagation
+      Upstream-->>Client: close(4502, "Upstream error") on upstream error
+    end
+  end
+```
+
+## Shared Client Registry and Broadcasts
+
+Only chat sockets (`/ws`) are tracked in `connectedClients`.
+
+That shared set is consumed by:
+
+1. `modules/projects/services/projects-with-sessions-fetch.service.ts`
+Broadcasts `kind: loading_progress` while project snapshots are being built.
+2. `modules/providers/services/sessions-watcher.service.ts`
+Broadcasts per-session `kind: session_upserted` deltas when provider session artifacts change (no full project snapshots).
+
+This design centralizes cross-module realtime fanout without requiring route-local references to WebSocket internals.
+
+## Writer Adapter (`WebSocketWriter`)
+
+`WebSocketWriter` normalizes chat transport behavior to match existing writer-style interfaces used elsewhere.
+
+Methods:
+
+1. `send(data)`  
+JSON-serializes and sends only if socket is open.
+2. `setSessionId(sessionId)` / `getSessionId()`  
+Supports provider session bookkeeping and resume flows.
+3. `updateWebSocket(newRawWs)`  
+Allows active session stream redirection on reconnect.
+
+## Error Handling and Close Codes
+
+Current explicit close codes in this module:
+
+1. `4400`: Invalid plugin name
+2. `4404`: Plugin not running
+3. `4502`: Upstream plugin WebSocket error
+
+Other errors:
+
+1. Chat handler catches and emits `{ kind: "protocol_error", code, error }`.
+2. Shell handler catches and writes terminal-visible error output.
+3. Unknown websocket paths are closed immediately.
+
+## Extending This Module
+
+To add a new websocket route:
+
+1. Add a new handler service under `services/`.
+2. Extend `WebSocketServerDependencies` in `websocket-server.service.ts` if needed.
+3. Add a new pathname branch in the router.
+4. Wire dependency injection from `server/index.ts`.
+5. Keep `index.ts` as barrel-only export surface.

package/server/modules/websocket/index.ts

@@ -0,0 +1,3 @@
+export { WS_OPEN_STATE, connectedClients } from './services/websocket-state.service.js';
+export { createWebSocketServer } from './services/websocket-server.service.js';
+export { chatRunRegistry } from './services/chat-run-registry.service.js';

package/server/modules/websocket/services/chat-run-registry.service.ts

@@ -0,0 +1,343 @@
+import path from 'node:path';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { generateDisplayName } from '@/modules/projects/index.js';
+import { ChatSessionWriter } from '@/modules/websocket/services/chat-session-writer.service.js';
+import { connectedClients, WS_OPEN_STATE } from '@/modules/websocket/services/websocket-state.service.js';
+import type {
+  LLMProvider,
+  NormalizedMessage,
+  RealtimeClientConnection,
+} from '@/shared/types.js';
+
+type ChatRunStatus = 'running' | 'completed';
+
+/**
+ * One live (or recently finished) provider run for a single app session.
+ *
+ * State notes — why each mutable field is essential:
+ * - `providerSessionId`: the provider-native id captured mid-run. The abort
+ *   handler needs it to address the provider runtime, and the DB mapping is
+ *   written from it so history/resume work after the run.
+ * - `status`: drives `chat_subscribed.isProcessing`, prevents double sends
+ *   into the same session, and guards the synthetic-complete fallback in the
+ *   chat handler (only emitted when a runtime died without completing).
+ * - `lastSeq` / `events`: the per-run event log. Every live event gets a
+ *   monotonically increasing `seq` and is buffered so a reconnecting client
+ *   can replay exactly the events it missed via `chat.subscribe`.
+ */
+type ChatRun = {
+  appSessionId: string;
+  provider: LLMProvider;
+  providerSessionId: string | null;
+  status: ChatRunStatus;
+  lastSeq: number;
+  events: NormalizedMessage[];
+  writer: ChatSessionWriter;
+  startedAt: number;
+  completedAt: number | null;
+};
+
+/**
+ * How long a completed run stays available for replay. Covers the window
+ * between a run finishing and the client refreshing history over REST (for
+ * example when the browser tab was asleep while the run completed).
+ */
+const COMPLETED_RUN_RETENTION_MS = 5 * 60 * 1000;
+
+/**
+ * Upper bound on buffered events per run so a very long tool-heavy run cannot
+ * grow memory unbounded. When exceeded, the oldest events are dropped —
+ * a reconnecting client whose `lastSeq` predates the buffer falls back to a
+ * REST history refresh, which is always the authoritative source.
+ */
+const MAX_BUFFERED_EVENTS_PER_RUN = 5000;
+
+/**
+ * Active and recently-completed runs keyed by app session id.
+ *
+ * This map is the single in-memory source of truth for "is something running
+ * for this session" — the chat websocket handler, abort path, and subscribe
+ * path all consult it instead of asking each provider runtime individually.
+ */
+const runs = new Map<string, ChatRun>();
+
+async function broadcastCanonicalSessionUpsert(appSessionId: string): Promise<void> {
+  const row = sessionsDb.getSessionById(appSessionId);
+  if (!row || row.isArchived) {
+    return;
+  }
+
+  const projectPath = row.project_path;
+  const project = projectPath ? projectsDb.getProjectPath(projectPath) : null;
+  const displayName = project?.custom_project_name?.trim()
+    ? project.custom_project_name
+    : await generateDisplayName(path.basename(projectPath ?? '') || (projectPath ?? ''), projectPath);
+
+  const payload = JSON.stringify({
+    kind: 'session_upserted',
+    sessionId: row.session_id,
+    providerSessionId: row.provider_session_id,
+    provider: row.provider,
+    session: {
+      id: row.session_id,
+      summary: row.custom_name || '',
+      messageCount: 0,
+      lastActivity: row.updated_at ?? row.created_at ?? new Date().toISOString(),
+    },
+    project: project
+      ? {
+        projectId: project.project_id,
+        path: project.project_path,
+        fullPath: project.project_path,
+        displayName,
+        isStarred: Boolean(project.isStarred),
+      }
+      : null,
+    timestamp: new Date().toISOString(),
+  });
+
+  connectedClients.forEach((client) => {
+    if (client.readyState === WS_OPEN_STATE) {
+      client.send(payload);
+    }
+  });
+}
+
+function evictRunLater(appSessionId: string): void {
+  const timer = setTimeout(() => {
+    const run = runs.get(appSessionId);
+    if (run && run.status === 'completed') {
+      runs.delete(appSessionId);
+    }
+  }, COMPLETED_RUN_RETENTION_MS);
+
+  // Never keep the process alive just to evict a buffered run.
+  timer.unref?.();
+}
+
+/**
+ * Decorates one outbound live event for a run and records it in the event log.
+ *
+ * Responsibilities:
+ * 1. Remap `sessionId` (and `actualSessionId` on `complete`) to the stable
+ *    app session id — provider-native ids never leave the backend.
+ * 2. Assign the next `seq` so clients can detect/replay gaps.
+ * 3. Buffer the event for `chat.subscribe` replay.
+ * 4. Flip the run to `completed` when the terminal `complete` event passes by.
+ */
+function decorateAndRecordEvent(run: ChatRun, message: NormalizedMessage): NormalizedMessage | null {
+  // Exactly-one-complete contract: when a run is aborted the chat handler
+  // emits the terminal `complete` immediately, but the killed runtime may
+  // still emit its own `complete` from its exit handler moments later.
+  // Whichever arrives first wins; the duplicate is dropped here.
+  if (message.kind === 'complete' && run.status === 'completed') {
+    return null;
+  }
+
+  run.lastSeq += 1;
+
+  const outbound: NormalizedMessage = {
+    ...message,
+    sessionId: run.appSessionId,
+    seq: run.lastSeq,
+  };
+
+  if (message.kind === 'complete') {
+    // The provider may report its own id here; the frontend only ever knows
+    // the app id, so the "actual" id is by definition the app id as well.
+    outbound.actualSessionId = run.appSessionId;
+    run.status = 'completed';
+    run.completedAt = Date.now();
+    evictRunLater(run.appSessionId);
+  }
+
+  run.events.push(outbound);
+  if (run.events.length > MAX_BUFFERED_EVENTS_PER_RUN) {
+    run.events.splice(0, run.events.length - MAX_BUFFERED_EVENTS_PER_RUN);
+  }
+
+  return outbound;
+}
+
+/**
+ * Records the provider-native session id for a run and persists the
+ * app-id-to-provider-id mapping so history fetches and future resumes can
+ * address the provider transcript.
+ *
+ * Called from the gateway writer when the runtime either calls
+ * `setSessionId(...)` or emits its `session_created` event — whichever
+ * happens first wins; later calls with the same id are no-ops.
+ */
+function recordProviderSessionId(run: ChatRun, providerSessionId: string): void {
+  if (!providerSessionId || run.providerSessionId === providerSessionId) {
+    return;
+  }
+
+  run.providerSessionId = providerSessionId;
+
+  try {
+    sessionsDb.assignProviderSessionId(run.appSessionId, providerSessionId);
+    void broadcastCanonicalSessionUpsert(run.appSessionId).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('[ChatRunRegistry] Failed to broadcast canonical session mapping', {
+        appSessionId: run.appSessionId,
+        providerSessionId,
+        error: message,
+      });
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('[ChatRunRegistry] Failed to persist provider session id mapping', {
+      appSessionId: run.appSessionId,
+      providerSessionId,
+      error: message,
+    });
+  }
+}
+
+/**
+ * Registry of live provider runs keyed by the stable app session id.
+ *
+ * The registry is what makes the websocket protocol provider-independent:
+ * every run gets a `ChatSessionWriter` that remaps provider-native session
+ * ids to the app id, assigns `seq` numbers, and buffers events for replay —
+ * regardless of which provider runtime produced them.
+ */
+export const chatRunRegistry = {
+  /**
+   * Starts tracking a run and returns it, or `null` when a run is already in
+   * progress for the session (callers must reject the duplicate send).
+   */
+  startRun(input: {
+    appSessionId: string;
+    provider: LLMProvider;
+    providerSessionId: string | null;
+    connection: RealtimeClientConnection;
+    userId: string | number | null;
+  }): ChatRun | null {
+    const existing = runs.get(input.appSessionId);
+    if (existing && existing.status === 'running') {
+      return null;
+    }
+
+    const run: ChatRun = {
+      appSessionId: input.appSessionId,
+      provider: input.provider,
+      providerSessionId: input.providerSessionId,
+      status: 'running',
+      lastSeq: 0,
+      events: [],
+      writer: null as unknown as ChatSessionWriter,
+      startedAt: Date.now(),
+      completedAt: null,
+    };
+
+    run.writer = new ChatSessionWriter({
+      connection: input.connection,
+      userId: input.userId,
+      provider: input.provider,
+      providerSessionId: input.providerSessionId,
+      onProviderSessionId: (providerSessionId) => {
+        recordProviderSessionId(run, providerSessionId);
+      },
+      decorateOutboundEvent: (message) => decorateAndRecordEvent(run, message),
+    });
+
+    runs.set(input.appSessionId, run);
+    return run;
+  },
+
+  getRun(appSessionId: string): ChatRun | undefined {
+    return runs.get(appSessionId);
+  },
+
+  isProcessing(appSessionId: string): boolean {
+    return runs.get(appSessionId)?.status === 'running';
+  },
+
+  listRunningRuns(): Array<{
+    sessionId: string;
+    provider: LLMProvider;
+    startedAt: number;
+    lastSeq: number;
+  }> {
+    return Array.from(runs.values())
+      .filter((run) => run.status === 'running')
+      .map((run) => ({
+        sessionId: run.appSessionId,
+        provider: run.provider,
+        startedAt: run.startedAt,
+        lastSeq: run.lastSeq,
+      }));
+  },
+
+  /**
+   * Re-attaches a run's outbound stream to a (new) websocket connection.
+   *
+   * This is the generic replacement for the Claude-only writer reconnect:
+   * after a page refresh the new socket subscribes and immediately starts
+   * receiving the still-running stream, for every provider.
+   */
+  attachConnection(appSessionId: string, connection: RealtimeClientConnection): boolean {
+    const run = runs.get(appSessionId);
+    if (!run) {
+      return false;
+    }
+
+    run.writer.updateWebSocket(connection);
+    return true;
+  },
+
+  /**
+   * Returns buffered events with `seq` greater than `afterSeq` for replay.
+   *
+   * An empty array with `run.lastSeq > afterSeq` not covered by the buffer
+   * means the buffer was truncated; the client should refresh over REST.
+   */
+  replayEvents(appSessionId: string, afterSeq: number): NormalizedMessage[] {
+    const run = runs.get(appSessionId);
+    if (!run) {
+      return [];
+    }
+
+    return run.events.filter((event) => typeof event.seq === 'number' && event.seq > afterSeq);
+  },
+
+  /**
+   * Emits a synthetic terminal `complete` if (and only if) the run is still
+   * marked running. Used when a provider runtime throws or resolves without
+   * having produced its own terminal event, and by the abort path.
+   */
+  completeRun(appSessionId: string, opts: { exitCode: number; aborted?: boolean }): void {
+    const run = runs.get(appSessionId);
+    if (!run || run.status !== 'running') {
+      return;
+    }
+
+    run.writer.sendComplete(opts);
+  },
+
+  /**
+   * Safety-net variant of `completeRun` scoped to one specific run: a no-op
+   * unless `run` is still the session's current, running run. A runtime
+   * promise can resolve after its own `complete` already streamed AND a new
+   * run has replaced it in the registry (a queued message sends within
+   * milliseconds of the previous turn ending) — the session-keyed
+   * `completeRun` would terminate that newer run.
+   */
+  completeRunIfCurrent(run: ChatRun, opts: { exitCode: number; aborted?: boolean }): void {
+    if (runs.get(run.appSessionId) !== run || run.status !== 'running') {
+      return;
+    }
+
+    run.writer.sendComplete(opts);
+  },
+
+  /**
+   * Test-only escape hatch: clears every tracked run.
+   */
+  clearAll(): void {
+    runs.clear();
+  },
+};