@juspay/shooter 1.18.0 → 1.20.0

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/lib/types/terminal-client.ts

@@ -80,12 +80,24 @@ export interface QuickKeysProps {
 
 // --- keyboard-shortcuts types ---
 
-export interface ShortcutManagerOptions {
-  onHelp: () => void;
+export interface ShareGateProps {
+  /** Returns an error message to display, or null on success. */
+  onSubmit: (password: string) => Promise<null | string>;
 }
 
 // --- xterm-wrapper types ---
 
+export interface ShareSheetProps {
+  onClose: () => void;
+  open?: boolean;
+  shareUrl: string;
+  terminalId: string;
+}
+
+export interface ShortcutManagerOptions {
+  onHelp: () => void;
+}
+
 export interface ShortcutsHelpProps {
   onClose: () => void;
   open: boolean;
@@ -105,11 +117,14 @@ export interface TerminalOptions {
   container: HTMLElement;
   fontSize?: number;
   getTicket: () => Promise<string>;
+  initialCols?: number;
+  initialRows?: number;
   onActivity?: (active: boolean) => void;
   onCwd?: (path: string) => void;
   onDisconnect?: () => void;
   onExit?: (code: number) => void;
   onReconnect?: () => void;
+  readOnly?: boolean;
   terminalId?: string;
   wsUrl: string;
 }
@@ -126,7 +141,9 @@ export interface WsTerminalInboundMessage {
   active?: boolean;
   bytes?: number;
   code?: number;
+  cols?: number;
   data?: string;
   path?: string;
+  rows?: number;
   type: string;
 }

package/src/lib/types/ws.ts

@@ -146,6 +146,7 @@ export type WireTerminalServerMessage =
   | { bytes: number; type: 'output-dropped' }
   | { chunk: number; data: string; total: number; type: 'scrollback' }
   | { code: null | number; signal: null | string; type: 'exit' }
+  | { cols: number; rows: number; type: 'resize' }
   | { data: string; type: 'output' }
   | { message: string; type: 'error' };
 

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 });
+};

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

@@ -0,0 +1,17 @@
+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';
+
+/** DELETE /api/sos/[id]/members/[mid] — remove a member (unsubscribes its watcher). */
+export const DELETE: RequestHandler = ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  if (!sosCoordinator.removeMember(params.id ?? '', params.mid ?? '')) {
+    return json({ error: 'Super-session or member not found' }, { status: 404 });
+  }
+  return json({ removed: true });
+};

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

@@ -0,0 +1,85 @@
+import type { SosRoutingRule } from '$lib/types';
+
+import { validateAuth } from '$lib/modules/server/auth';
+import { sosCoordinator } from '$lib/modules/server/sos/coordinator';
+import { json } from '@sveltejs/kit';
+import { randomBytes } from 'crypto';
+
+import type { RequestHandler } from './$types';
+
+const ACTIONS = new Set(['block', 'escalate', 'relay']);
+
+/** GET /api/sos/[id]/rules — current routing rules. */
+export const GET: RequestHandler = ({ params, request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  const rules = sosCoordinator.getRoutingRules(params.id ?? '');
+  if (rules === null) {
+    return json({ error: 'Super-session not found' }, { status: 404 });
+  }
+  return json({ routingRules: rules });
+};
+
+/** PATCH /api/sos/[id]/rules — replace the routing rules. */
+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 { routingRules?: unknown };
+  if (!Array.isArray(payload.routingRules)) {
+    return json({ error: 'routingRules must be an array' }, { status: 400 });
+  }
+
+  const rules: SosRoutingRule[] = [];
+  for (const raw of payload.routingRules) {
+    const rule = normalizeRule(raw);
+    if (!rule) {
+      return json(
+        { error: 'Each rule needs fromMemberId, toMemberId, and action' },
+        { status: 400 }
+      );
+    }
+    rules.push(rule);
+  }
+
+  const error = sosCoordinator.setRoutingRules(params.id ?? '', rules);
+  if (error) {
+    return json({ error }, { status: error.includes('not found') ? 404 : 400 });
+  }
+  return json({ routingRules: rules });
+};
+
+function normalizeRule(raw: unknown): null | SosRoutingRule {
+  if (typeof raw !== 'object' || raw === null) {
+    return null;
+  }
+  const r = raw as Record<string, unknown>;
+  if (
+    typeof r.fromMemberId !== 'string' ||
+    typeof r.toMemberId !== 'string' ||
+    typeof r.action !== 'string' ||
+    !ACTIONS.has(r.action)
+  ) {
+    return null;
+  }
+  return {
+    action: r.action as SosRoutingRule['action'],
+    fromMemberId: r.fromMemberId,
+    id: typeof r.id === 'string' && r.id ? r.id : randomBytes(6).toString('hex'),
+    matchPattern: typeof r.matchPattern === 'string' ? r.matchPattern : '',
+    priority: typeof r.priority === 'number' ? r.priority : 100,
+    toMemberId: r.toMemberId,
+  };
+}

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

@@ -1,6 +1,9 @@
 import { validateAuth } from '$lib/modules/server/auth';
 import { ptyManager } from '$lib/modules/server/terminal/pty-manager.js';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
+import { shareStore } from '$lib/modules/server/terminal/share-store';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
+import { closeGuests } from '$lib/modules/server/ws/guest-registry';
 import { json } from '@sveltejs/kit';
 
 import type { RequestHandler } from './$types';
@@ -21,10 +24,11 @@ function lastScrollbackLine(scrollback: string): null | string {
 }
 
 // GET /api/terminals/:id — Get terminal details by ID
+// Accepts the API key (owner) or a share session token scoped to this terminal.
 export const GET: RequestHandler = ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
   }
 
   try {
@@ -37,6 +41,7 @@ export const GET: RequestHandler = ({ params, request }) => {
     return json({
       args: terminal.args,
       clientCount: terminal.clients.size,
+      cols: terminal.cols,
       command: terminal.command,
       createdAt: terminal.createdAt.toISOString(),
       cwd: terminal.cwd,
@@ -45,10 +50,12 @@ export const GET: RequestHandler = ({ params, request }) => {
       id: terminal.id,
       lastOutput: lastScrollbackLine(terminal.scrollback),
       pid: terminal.pid,
+      rows: terminal.rows,
       sessionWs: `/ws/session/${terminal.id}`,
       status: terminal.status,
       timestamp: new Date().toISOString(),
       ws: `/ws/terminal/${terminal.id}`,
+      ...(access.level === 'guest' ? { shareMode: access.mode } : {}),
     });
   } catch (error) {
     console.error('[terminals] Failed to get terminal:', toErrorMessage(error));
@@ -72,6 +79,8 @@ export const DELETE: RequestHandler = ({ params, request }) => {
 
     if (terminal.status === 'exited') {
       ptyManager.remove(params.id);
+      shareStore.deleteShare(params.id);
+      closeGuests(params.id);
       console.log(`[terminals] Removed exited terminal ${params.id}`);
       return json({
         removed: true,
@@ -81,6 +90,8 @@ export const DELETE: RequestHandler = ({ params, request }) => {
     }
 
     ptyManager.kill(params.id);
+    shareStore.deleteShare(params.id);
+    closeGuests(params.id);
 
     console.log(`[terminals] Killed terminal ${params.id} (pid=${terminal.pid})`);
 

package/src/routes/api/terminals/[id]/paste-image/+server.ts

@@ -1,4 +1,4 @@
-import { validateAuth } from '$lib/modules/server/auth';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
 import { json } from '@sveltejs/kit';
 import { mkdirSync, writeFileSync } from 'fs';
@@ -6,10 +6,14 @@ import { mkdirSync, writeFileSync } from 'fs';
 import type { RequestHandler } from './$types';
 
 // POST /api/terminals/[id]/paste-image — Write clipboard image for a terminal
+// Accepts the API key (owner) or a control-mode share token for this terminal.
 export const POST: RequestHandler = async ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  if (access.level === 'guest' && access.mode !== 'control') {
+    return json({ error: 'View-only access' }, { status: 403 });
   }
 
   const terminalId = params.id;

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

@@ -1,15 +1,19 @@
-import { validateAuth } from '$lib/modules/server/auth';
 import { ptyManager } from '$lib/modules/server/terminal/pty-manager.js';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
 import { json } from '@sveltejs/kit';
 
 import type { RequestHandler } from './$types';
 
 // POST /api/terminals/:id/resize — Resize terminal
+// Accepts the API key (owner) or a control-mode share token for this terminal.
 export const POST: RequestHandler = async ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  if (access.level === 'guest' && access.mode !== 'control') {
+    return json({ error: 'View-only access' }, { status: 403 });
   }
 
   let body: { cols?: number; rows?: number };