@schlessera/brain-ui-server 0.4.0

package/src/ws/turns.ts

@@ -0,0 +1,151 @@
+import type {
+  AgentBackend,
+  PermissionDecision,
+  AskUserResult,
+  LocationFix,
+} from "@schlessera/brain-ui-sdk/server";
+import type { ChatImageAttachment } from "@schlessera/brain-ui-sdk/protocol";
+
+export interface QueuedFollowUp {
+  text: string;
+  attachments: ChatImageAttachment[];
+}
+
+/**
+ * One RUNNING session slot. `abortController`/`timeoutHandle` belong to the
+ * turn currently executing; a queued follow-up runs as the next turn in the
+ * same slot (same sessionId) after the current one resolves.
+ */
+export interface RunningTurn {
+  sessionId: string | null; // null until session_info resolves it (new session)
+  /** Host-minted id of the CURRENT turn in this slot; re-minted per queued follow-up. */
+  turnId: string;
+  providerId: string | null;
+  backend: AgentBackend;
+  abortController: AbortController;
+  timeoutHandle: ReturnType<typeof setTimeout>;
+  queue: QueuedFollowUp[];
+  cancelled: boolean;
+}
+
+// Pending interactive requests are tagged with their turn so a per-session
+// cancel/disconnect can drain only that session's pending entries, and with
+// the turnId that raised them (the slot's id mutates across queued follow-ups).
+export interface PendingApproval {
+  turn: RunningTurn;
+  turnId: string;
+  resolve: (decision: PermissionDecision) => void;
+}
+
+export interface PendingAskUser {
+  turn: RunningTurn;
+  turnId: string;
+  resolve: (result: AskUserResult) => void;
+  reject: (err: Error) => void;
+}
+
+export interface PendingLocation {
+  turn: RunningTurn;
+  turnId: string;
+  resolve: (result: LocationFix) => void;
+  reject: (err: Error) => void;
+}
+
+/**
+ * Mutable turn state for one ws host: the running session slots and every
+ * pending interactive round-trip. This used to be six module-level globals
+ * inside a 976-line handler; as instance state it is testable and owned by an
+ * explicit object with a defined lifecycle.
+ */
+export class TurnCoordinator {
+  readonly running = new Set<RunningTurn>();
+  readonly bySession = new Map<string, RunningTurn>();
+  startingSessions = 0;
+
+  readonly pendingApprovals = new Map<string, PendingApproval>();
+  readonly pendingAskUser = new Map<string, PendingAskUser>();
+  readonly pendingLocation = new Map<string, PendingLocation>();
+
+  private locationCounter = 0;
+
+  nextLocationRequestId(): string {
+    return `loc-${Date.now().toString(36)}-${++this.locationCounter}`;
+  }
+
+  /** True while any session has a running turn. */
+  isTurnActive(): boolean {
+    return this.running.size > 0;
+  }
+
+  /** Cancel every running turn (used on shutdown). */
+  cancelAll(reason: string): boolean {
+    if (this.running.size === 0) return false;
+    for (const turn of [...this.running]) this.cancelTurn(turn, reason);
+    return true;
+  }
+
+  /** Cancel a session's current turn and drop its queued follow-ups. */
+  cancelTurn(turn: RunningTurn, reason: string): void {
+    turn.cancelled = true;
+    turn.queue.length = 0;
+    clearTimeout(turn.timeoutHandle);
+    turn.abortController.abort();
+    this.drainPendingForTurn(turn, reason);
+  }
+
+  /** Resolve/reject every pending interactive request belonging to one turn. */
+  drainPendingForTurn(turn: RunningTurn, reason: string): void {
+    for (const [id, p] of this.pendingApprovals) {
+      if (p.turn !== turn) continue;
+      p.resolve({ behavior: "deny", message: reason });
+      this.pendingApprovals.delete(id);
+    }
+    for (const [id, p] of this.pendingAskUser) {
+      if (p.turn !== turn) continue;
+      p.reject(new Error(reason));
+      this.pendingAskUser.delete(id);
+    }
+    for (const [id, p] of this.pendingLocation) {
+      if (p.turn !== turn) continue;
+      p.reject(new Error(reason));
+      this.pendingLocation.delete(id);
+    }
+  }
+
+  /**
+   * Interactive-request ids (tool-approval / ask-user / location) must be
+   * globally unique so an inbound response resolves the correct turn's
+   * promise. The current backends mint unique ids (SDK tool-use ids,
+   * crypto.randomUUID, a host counter), so a collision across live turns means
+   * a future backend broke that invariant — fail the new request loudly rather
+   * than silently overwriting (and thus resolving) another turn's entry.
+   */
+  collidesAcrossTurns<T extends { turn: RunningTurn }>(
+    map: Map<string, T>,
+    id: string,
+    turn: RunningTurn
+  ): boolean {
+    const existing = map.get(id);
+    if (existing && existing.turn !== turn) {
+      console.error(
+        `[ws] interactive id collision: "${id}" is already pending for another turn`
+      );
+      return true;
+    }
+    return false;
+  }
+
+  /** Test seam: abort everything and clear all turn/pending state. */
+  reset(): void {
+    for (const turn of [...this.running]) {
+      clearTimeout(turn.timeoutHandle);
+      turn.abortController.abort();
+    }
+    this.running.clear();
+    this.bySession.clear();
+    this.pendingApprovals.clear();
+    this.pendingAskUser.clear();
+    this.pendingLocation.clear();
+    this.startingSessions = 0;
+  }
+}