@juspay/shooter 1.18.0 → 1.19.0

package/src/lib/modules/server/terminal/pty-input.ts

@@ -0,0 +1,37 @@
+/**
+ * PTY input helpers.
+ *
+ * Submitting text to an interactive agent TUI (codex, claude, gemini, qwen, …)
+ * is not as simple as appending a newline. These TUIs read the PTY in raw mode:
+ *
+ *   - A bare LF (`\n`) is NOT the Enter key — it types a literal newline into
+ *     the prompt and never submits. (Verified: LF leaves codex sitting on its
+ *     prompt; the message just accumulates.)
+ *   - Even `"<text>\r"` written as a SINGLE chunk is treated as a bracketed
+ *     paste by the TUI, so the trailing CR is absorbed into the pasted body
+ *     instead of submitting. (Verified: codex types the text but does not run.)
+ *
+ * The reliable approach — the same bytes a real terminal emulator sends when a
+ * human pastes and presses Enter — is to wrap the body in an explicit bracketed
+ * paste (`ESC[200~` … `ESC[201~`) and then send a CR. The paste-end marker
+ * closes the paste unambiguously, so the following CR is a real Enter. This
+ * also preserves embedded newlines in multi-line messages (the whole point of
+ * bracketed paste) and submits correctly in modern interactive shells, where
+ * bracketed paste is enabled by default.
+ *
+ * Verified empirically against codex 0.136 and claude 2.1 — both receive the
+ * message and complete a turn.
+ */
+
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+
+/**
+ * Build the PTY byte sequence that delivers `text` to an interactive terminal
+ * and submits it (presses Enter). Any trailing newline the caller added is
+ * stripped — the CR after the paste-end marker is what submits.
+ */
+export function ptySubmitSequence(text: string): string {
+  const body = text.replace(/[\r\n]+$/, '');
+  return `${PASTE_START}${body}${PASTE_END}\r`;
+}

package/src/lib/modules/server/ws/server.ts

@@ -15,6 +15,7 @@ import {
   handleEventsConnection,
 } from './events-handler.js';
 import { handleSessionConnection } from './session-handler.js';
+import { handleSuperSessionConnection } from './super-session-handler.js';
 import { handleTerminalConnection } from './terminal-handler.js';
 export type { WireShooterEvent as ShooterEvent } from '$lib/types';
 
@@ -61,10 +62,11 @@ export function setupWebSocketHandlers(
 
   // Route matching
   const terminalMatch = /^\/ws\/terminal\/(.+)$/.exec(pathname);
+  const superSessionMatch = /^\/ws\/super-session\/(.+)$/.exec(pathname);
   const sessionMatch = /^\/ws\/session\/(.+)$/.exec(pathname);
   const isEvents = pathname === '/ws/events';
 
-  if (!terminalMatch && !sessionMatch && !isEvents) {
+  if (!terminalMatch && !superSessionMatch && !sessionMatch && !isEvents) {
     socket.destroy();
     return;
   }
@@ -83,6 +85,9 @@ export function setupWebSocketHandlers(
     if (terminalMatch) {
       const terminalId = terminalMatch[1];
       handleTerminalConnection(ws, terminalId);
+    } else if (superSessionMatch) {
+      const superSessionId = superSessionMatch[1];
+      handleSuperSessionConnection(ws, superSessionId);
     } else if (sessionMatch) {
       const sessionId = sessionMatch[1];
       handleSessionConnection(ws, sessionId);

package/src/lib/modules/server/ws/session-handler.ts

@@ -23,6 +23,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { findCodexRolloutById } from '../sessions/codex-reader';
+import { ptySubmitSequence } from '../terminal/pty-input';
 
 // ── Module-level references ──────────────────────────────────────────
 
@@ -547,7 +548,11 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
             safeSend(ws, { message: 'Terminal has exited', type: 'error' });
             return;
           }
-          currentTerminal.pty.write(`${msg.text}\n`);
+          // Deliver + submit via a bracketed paste (see pty-input.ts): a bare
+          // LF never submits to an agent TUI and a trailing CR in the same
+          // write is absorbed as paste content. Bracketed paste closes the
+          // paste explicitly so the following CR is a real Enter.
+          currentTerminal.pty.write(ptySubmitSequence(msg.text));
           break;
         }
 

package/src/lib/modules/server/ws/super-session-handler.ts

@@ -0,0 +1,200 @@
+// WebSocket handler for /ws/super-session/:id — the merged Session-Over-Sessions
+// stream. On connect it replays the merged transcript (sos-history) and then
+// streams live tagged messages from every member. Accepts human-driven control
+// messages: relay-forward (inject into a member's terminal), member-add,
+// member-remove. Mirrors session-handler.ts in shape.
+
+import type { SessionSource, SosClientMessage, SosServerMessage } from '$lib/types';
+import type { WebSocket } from 'ws';
+
+import * as path from 'path';
+
+import { PROVIDERS } from '../sessions/registry';
+import { sosCoordinator } from '../sos/coordinator';
+
+const MAX_RELAY_TEXT = 10240; // 10 KB, same cap as /ws/session send-input
+// Stop streaming to a client whose outbound buffer exceeds this — bounds memory
+// growth when a slow consumer can't drain sos-history replay or a live burst.
+const MAX_WS_BUFFERED_BYTES = 1_000_000;
+const VALID_SOURCES = new Set<string>(PROVIDERS.map((p) => p.source));
+
+export function handleSuperSessionConnection(ws: WebSocket, id: string): void {
+  const session = sosCoordinator.getSuperSession(id);
+  if (!session) {
+    safeSend(ws, { message: `Super-session not found: ${id}`, type: 'sos-error' });
+    ws.close(1008, 'Super-session not found');
+    return;
+  }
+
+  // subscribe() replays the current transcript as an sos-history message, then
+  // streams live sos-message / sos-member-* events. If a send fails (socket
+  // closed or buffer over cap), stop feeding this client to bound memory.
+  let unsubscribe: (() => void) | null = null;
+  unsubscribe = sosCoordinator.subscribe(id, (msg) => {
+    if (!safeSend(ws, msg)) {
+      unsubscribe?.();
+      unsubscribe = null;
+    }
+  });
+
+  ws.on('message', (raw: Buffer | string) => {
+    const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+    const msg = parseClientMessage(data);
+    if (!msg) {
+      // Surface schema drift instead of silently dropping the frame — a dead
+      // control in the UI is much harder to debug than an explicit error.
+      safeSend(ws, { message: 'Invalid super-session control message', type: 'sos-error' });
+      return;
+    }
+    handleClientMessage(ws, id, msg);
+  });
+
+  ws.on('close', () => {
+    unsubscribe?.();
+  });
+  ws.on('error', () => {
+    // cleanup happens in 'close'
+  });
+}
+
+/** True when the string is a known provider source. */
+export function isValidProvider(value: string): value is SessionSource {
+  return VALID_SOURCES.has(value);
+}
+
+/** True for a bare session id (OpenCode) or an absolute path under HOME. */
+export function isValidSessionKey(key: string): boolean {
+  if (/^[A-Za-z0-9_-]+$/.test(key)) {
+    return true;
+  }
+  const home = process.env.HOME || '';
+  if (home === '' || !path.isAbsolute(key)) {
+    return false;
+  }
+  // Resolve before comparing so `..` segments cannot escape the HOME sandbox
+  // (e.g. /home/user/../etc/passwd passes a raw prefix check but not this).
+  const relative = path.relative(path.resolve(home), path.resolve(key));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function handleClientMessage(ws: WebSocket, superSessionId: string, msg: SosClientMessage): void {
+  switch (msg.type) {
+    case 'member-add': {
+      const member = sosCoordinator.addMember(superSessionId, {
+        capability: msg.capability,
+        provider: msg.provider,
+        sessionKey: msg.sessionKey,
+        terminalId: msg.terminalId ?? null,
+      });
+      if (!member) {
+        safeSend(ws, { message: 'Failed to add member', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'member-remove': {
+      const ok = sosCoordinator.removeMember(superSessionId, msg.memberId);
+      if (!ok) {
+        safeSend(ws, { message: 'Member not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-approve': {
+      if (!sosCoordinator.approveRelay(superSessionId, msg.relayId)) {
+        safeSend(ws, { message: 'Pending relay not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-deny': {
+      if (!sosCoordinator.denyRelay(superSessionId, msg.relayId)) {
+        safeSend(ws, { message: 'Pending relay not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-forward': {
+      const error = sosCoordinator.relayForward(superSessionId, msg.toMemberId, msg.text);
+      if (error) {
+        safeSend(ws, { message: error, type: 'sos-error' });
+      }
+      break;
+    }
+  }
+}
+
+function parseClientMessage(raw: string): null | SosClientMessage {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null;
+  }
+  const msg = parsed as Record<string, unknown>;
+
+  switch (msg.type) {
+    case 'member-add': {
+      if (
+        typeof msg.sessionKey !== 'string' ||
+        !isValidSessionKey(msg.sessionKey) ||
+        typeof msg.provider !== 'string' ||
+        !isValidProvider(msg.provider)
+      ) {
+        return null;
+      }
+      return {
+        capability: typeof msg.capability === 'string' ? msg.capability : undefined,
+        provider: msg.provider,
+        sessionKey: msg.sessionKey,
+        terminalId: typeof msg.terminalId === 'string' ? msg.terminalId : undefined,
+        type: 'member-add',
+      };
+    }
+    case 'member-remove': {
+      if (typeof msg.memberId !== 'string' || msg.memberId.length === 0) {
+        return null;
+      }
+      return { memberId: msg.memberId, type: 'member-remove' };
+    }
+    case 'relay-approve': {
+      if (typeof msg.relayId !== 'string' || msg.relayId.length === 0) {
+        return null;
+      }
+      return { relayId: msg.relayId, type: 'relay-approve' };
+    }
+    case 'relay-deny': {
+      if (typeof msg.relayId !== 'string' || msg.relayId.length === 0) {
+        return null;
+      }
+      return { relayId: msg.relayId, type: 'relay-deny' };
+    }
+    case 'relay-forward': {
+      if (
+        typeof msg.toMemberId !== 'string' ||
+        typeof msg.text !== 'string' ||
+        msg.text.length === 0 ||
+        msg.text.length > MAX_RELAY_TEXT
+      ) {
+        return null;
+      }
+      return { text: msg.text, toMemberId: msg.toMemberId, type: 'relay-forward' };
+    }
+    default:
+      return null;
+  }
+}
+
+function safeSend(ws: WebSocket, msg: SosServerMessage): boolean {
+  try {
+    if (ws.readyState !== 1 /* OPEN */) {
+      return false;
+    }
+    if (ws.bufferedAmount > MAX_WS_BUFFERED_BYTES) {
+      return false;
+    }
+    ws.send(JSON.stringify(msg));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/types/index.ts

@@ -12,8 +12,8 @@ export type * from './gemini';
 export * from './generated';
 export type * from './neurolink';
 export type * from './server';
-
 export type * from './sessions';
+
 // Explicit re-exports to resolve conflicts between generated types and the
 // hand-written sessions.ts versions. The generated Sessions module exports
 // wrapper-class variants (CMessagePartTextPart, etc.) with `type: string`
@@ -27,5 +27,6 @@ export type {
   ToolResultPart,
   ToolUsePart,
 } from './sessions';
+export type * from './sos';
 export type * from './terminal-client';
 export type * from './ws';

package/src/lib/types/sos.ts

@@ -0,0 +1,134 @@
+// Session-Over-Sessions (SoS) types — the coordinator that merges N running
+// agent sessions into one source-tagged super-session and relays messages
+// between them. See docs/SESSION-OVER-SESSIONS.md.
+//
+// A member's `sessionKey` is exactly what the server's session-watcher adapter
+// keys on: a JSONL/JSON file path for file-backed providers, or a bare session
+// id for OpenCode. That lets the coordinator reuse the same watcher routing the
+// WS session handler uses, covering all providers with no new watching code.
+
+import type { SessionSource } from './generated';
+import type { ConversationMessage } from './sessions';
+
+/** An escalated relay awaiting human approve/deny (Phase 2 HITL). */
+export interface PendingRelay {
+  createdAt: string;
+  expiresAt: string;
+  fromMemberId: string;
+  id: string;
+  text: string;
+  timer: null | ReturnType<typeof setTimeout>;
+  toMemberId: string;
+}
+
+/** A control message sent from a SoS client to the coordinator over /ws/super-session/:id. */
+export type SosClientMessage =
+  | {
+      capability?: string;
+      provider: SessionSource;
+      sessionKey: string;
+      terminalId?: string;
+      type: 'member-add';
+    }
+  | { memberId: string; type: 'member-remove' }
+  | { relayId: string; type: 'relay-approve' }
+  | { relayId: string; type: 'relay-deny' }
+  | { text: string; toMemberId: string; type: 'relay-forward' };
+
+/**
+ * Injects relay text into a Shooter-owned terminal's stdin. Supplied by
+ * server.ts (which owns PtyManager) so the coordinator stays free of PTY deps.
+ * Performs the ownership check (terminal exists + running) and returns the
+ * outcome.
+ */
+export type SosInjector = (terminalId: string, text: string) => { error?: string; ok: boolean };
+
+/** A WS listener registered against a super-session. */
+export type SosListener = (msg: SosServerMessage) => void;
+
+export interface SosMember {
+  /** Free-text capability tag, e.g. 'frontend' | 'backend' | '' (unused in MVP routing). */
+  capability: string;
+  /** Random hex id, primary key in sos_sessions. */
+  id: string;
+  provider: SessionSource;
+  registeredAt: string;
+  /** Watcher key: file path for file-backed providers, session id for OpenCode. */
+  sessionKey: string;
+  status: SosMemberStatus;
+  /** PtyManager terminal id when launched via Shooter; null for externally-observed sessions. */
+  terminalId: null | string;
+}
+
+// ── WebSocket protocol (/ws/super-session/:id) ──────────────────────────
+
+/** Lifecycle status of a SoS member's underlying agent session. */
+export type SosMemberStatus = 'Compacting' | 'Finished' | 'Idle' | 'Waiting' | 'Working';
+
+/**
+ * A static routing rule (Phase 2). The coordinator evaluates these in ascending
+ * `priority` against each new member message; the first match decides the
+ * action. `fromMemberId` may be 'ANY'; an empty `matchPattern` matches all text.
+ */
+export interface SosRoutingRule {
+  action: 'block' | 'escalate' | 'relay';
+  fromMemberId: string;
+  id: string;
+  matchPattern: string;
+  priority: number;
+  toMemberId: string;
+}
+
+/** A message broadcast from the coordinator to subscribed SoS clients. */
+export type SosServerMessage =
+  | {
+      decision: 'approved' | 'denied' | 'expired';
+      relayId: string;
+      type: 'sos-relay-resolved';
+    }
+  | { entries: SosTranscriptEntry[]; type: 'sos-history' }
+  | { entry: SosTranscriptEntry; type: 'sos-message' }
+  | {
+      expiresAt: string;
+      fromMemberId: string;
+      preview: string;
+      relayId: string;
+      toMemberId: string;
+      type: 'sos-relay-pending';
+    }
+  | { member: SosMember; type: 'sos-member-added' }
+  | { memberId: string; status: SosMemberStatus; type: 'sos-member-status' }
+  | { memberId: string; type: 'sos-member-removed' }
+  | { message: string; type: 'sos-error' };
+
+/** One message in the merged transcript, tagged with its origin member. */
+export interface SosTranscriptEntry {
+  memberId: string;
+  message: ConversationMessage;
+  provider: SessionSource;
+  /** True when the coordinator injected this message (loop-guard marker). */
+  relayed: boolean;
+}
+
+/** A super-session: N merged agent sessions coordinated as one. */
+export interface SuperSession {
+  createdAt: string;
+  id: string;
+  label: string;
+  members: SosMember[];
+  routingRules: SosRoutingRule[];
+  status: 'active' | 'archived' | 'paused';
+  /** Source-tagged merged transcript; in-memory ring buffer (capped). */
+  transcript: SosTranscriptEntry[];
+}
+
+/** Coordinator-internal runtime state for one live super-session. */
+export interface SuperSessionRuntime {
+  /** `${fromMemberId}:${toMemberId}` -> last auto-relay epoch ms (cooldown guard). */
+  cooldowns: Map<string, number>;
+  listeners: Set<SosListener>;
+  /** Escalated relays awaiting human decision, keyed by relayId. */
+  pending: Map<string, PendingRelay>;
+  session: SuperSession;
+  unsubscribes: Map<string, () => void>;
+}

package/src/routes/+layout.svelte

@@ -10,6 +10,7 @@
   import DashboardSvg from '$lib/assets/icons/dashboard.svg?raw';
   import SettingsSvg from '$lib/assets/icons/settings.svg?raw';
   import TerminalSvg from '$lib/assets/icons/terminal.svg?raw';
+  import ToolSvg from '$lib/assets/icons/tool.svg?raw';
   import { Button, Icon, Pill } from '@juspay/svelte-ui-components';
   import { onMount, type Snippet } from 'svelte';
 
@@ -133,6 +134,10 @@
         <Icon svg={TerminalSvg} classes="icon-26" />
         <span>Terminals</span>
       </a>
+      <a href="/sos" class="tab-item" class:active={$page.url.pathname.startsWith('/sos')}>
+        <Icon svg={ToolSvg} classes="icon-26" />
+        <span>SoS</span>
+      </a>
     </div>
   </nav>
 </div>
@@ -191,6 +196,7 @@
   }
   .tab-item {
     display: flex;
+    flex: 1;
     flex-direction: column;
     align-items: center;
     justify-content: center;
@@ -199,7 +205,7 @@
     font-size: 11px;
     font-weight: 500;
     text-decoration: none;
-    padding: 6px 36px;
+    padding: 6px 8px;
     border-radius: var(--radius-md);
     transition: color var(--transition-fast);
     user-select: none;
@@ -226,7 +232,8 @@
       height: 60px;
     }
     .tab-item {
-      padding: 6px 28px;
+      padding: 6px 8px;
+      min-width: 0;
       font-size: 10px;
       gap: 3px;
       min-height: 44px;

package/src/routes/api/sos/+server.ts

@@ -0,0 +1,36 @@
+import { validateAuth } from '$lib/modules/server/auth';
+import { sosCoordinator } from '$lib/modules/server/sos/coordinator';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+/** GET /api/sos — list all super-sessions. */
+export const GET: RequestHandler = ({ request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  return json({ superSessions: sosCoordinator.listSuperSessions() });
+};
+
+/** POST /api/sos — create a new super-session. */
+export const POST: RequestHandler = async ({ request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  if (typeof body !== 'object' || body === null) {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  const payload = body as { label?: unknown };
+  const label =
+    typeof payload.label === 'string' && payload.label.trim() ? payload.label.trim() : 'Untitled';
+  const session = sosCoordinator.createSuperSession(label);
+  return json(session, { status: 201 });
+};

package/src/routes/api/sos/[id]/+server.ts

@@ -0,0 +1,55 @@
+import { validateAuth } from '$lib/modules/server/auth';
+import { sosCoordinator } from '$lib/modules/server/sos/coordinator';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+/** GET /api/sos/[id] — fetch one super-session (incl. members + transcript). */
+export const GET: RequestHandler = ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  const session = sosCoordinator.getSuperSession(params.id ?? '');
+  if (!session) {
+    return json({ error: 'Super-session not found' }, { status: 404 });
+  }
+  return json(session);
+};
+
+/** PATCH /api/sos/[id] — update lifecycle status (active | paused | archived). */
+export const PATCH: RequestHandler = async ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  if (typeof body !== 'object' || body === null) {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  const payload = body as { status?: unknown };
+  if (payload.status !== 'active' && payload.status !== 'paused' && payload.status !== 'archived') {
+    return json({ error: 'status must be active | paused | archived' }, { status: 400 });
+  }
+  if (!sosCoordinator.setStatus(params.id ?? '', payload.status)) {
+    return json({ error: 'Super-session not found' }, { status: 404 });
+  }
+  return json({ id: params.id, status: payload.status });
+};
+
+/** DELETE /api/sos/[id] — tear down a super-session (unsubscribes all members). */
+export const DELETE: RequestHandler = ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  if (!sosCoordinator.deleteSuperSession(params.id ?? '')) {
+    return json({ error: 'Super-session not found' }, { status: 404 });
+  }
+  return json({ deleted: true });
+};

package/src/routes/api/sos/[id]/inject/+server.ts

@@ -0,0 +1,44 @@
+import { validateAuth } from '$lib/modules/server/auth';
+import { sosCoordinator } from '$lib/modules/server/sos/coordinator';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+const MAX_RELAY_TEXT = 10240; // 10 KB, same cap as /ws/session send-input
+
+/**
+ * POST /api/sos/[id]/inject — human-initiated relay: inject text into a member's
+ * Shooter-owned terminal and record it in the merged transcript.
+ */
+export const POST: RequestHandler = async ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  if (typeof body !== 'object' || body === null) {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  const payload = body as { text?: unknown; toMemberId?: unknown };
+  if (typeof payload.toMemberId !== 'string' || payload.toMemberId.length === 0) {
+    return json({ error: 'toMemberId is required (string)' }, { status: 400 });
+  }
+  if (typeof payload.text !== 'string' || payload.text.length === 0) {
+    return json({ error: 'text is required (string)' }, { status: 400 });
+  }
+  if (Buffer.byteLength(payload.text, 'utf8') > MAX_RELAY_TEXT) {
+    return json({ error: `text exceeds ${MAX_RELAY_TEXT} bytes` }, { status: 413 });
+  }
+
+  const error = sosCoordinator.relayForward(params.id ?? '', payload.toMemberId, payload.text);
+  if (error) {
+    const status = error.includes('not found') ? 404 : 400;
+    return json({ error }, { status });
+  }
+  return json({ ok: true });
+};

package/src/routes/api/sos/[id]/members/+server.ts

@@ -0,0 +1,47 @@
+import { validateAuth } from '$lib/modules/server/auth';
+import { sosCoordinator } from '$lib/modules/server/sos/coordinator';
+import { isValidProvider, isValidSessionKey } from '$lib/modules/server/ws/super-session-handler';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+/** POST /api/sos/[id]/members — add a member session to a super-session. */
+export const POST: RequestHandler = async ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  if (typeof body !== 'object' || body === null) {
+    return json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+  const payload = body as {
+    capability?: unknown;
+    provider?: unknown;
+    sessionKey?: unknown;
+    terminalId?: unknown;
+  };
+
+  if (typeof payload.sessionKey !== 'string' || !isValidSessionKey(payload.sessionKey)) {
+    return json({ error: 'sessionKey must be a session id or a path under home' }, { status: 400 });
+  }
+  if (typeof payload.provider !== 'string' || !isValidProvider(payload.provider)) {
+    return json({ error: 'provider must be a known session source' }, { status: 400 });
+  }
+
+  const member = sosCoordinator.addMember(params.id ?? '', {
+    capability: typeof payload.capability === 'string' ? payload.capability : undefined,
+    provider: payload.provider,
+    sessionKey: payload.sessionKey,
+    terminalId: typeof payload.terminalId === 'string' ? payload.terminalId : null,
+  });
+  if (!member) {
+    return json({ error: 'Super-session not found' }, { status: 404 });
+  }
+  return json(member, { status: 201 });
+};