@juspay/shooter 1.20.0 → 1.22.0

package/src/lib/modules/server/sessions/next-step-consensus.ts

@@ -0,0 +1,210 @@
+// Pure, deterministic next-step consensus algorithm.
+// No I/O, no LLM. Fully unit-testable.
+// See spec docs/superpowers/specs/2026-05-29-autonomous-summarization-engine-design.md §4
+
+import type { AgentProposal, ConsensusResult, MergeOptions, NextStep } from '$lib/types';
+
+const DEFAULT_K = 3;
+const DEFAULT_QUORUM = 3;
+const JACCARD_THRESHOLD = 0.6;
+
+/** A grouped cluster of proposals that all map to the same semantic step. @internal */
+// eslint-disable-next-line no-restricted-syntax
+interface Cluster {
+  /** Distinct agent indices that proposed a member of this cluster. */
+  agentIndices: Set<number>;
+  /** All individual proposals that map into this cluster (for label + confidence). */
+  members: { confidence: number; text: string }[];
+  /** Normalized representative text (first normalized form in cluster). */
+  normalized: string;
+}
+
+/**
+ * Merge up to 5 agent next-step lists into a consensus result.
+ *
+ * Algorithm (per spec §4):
+ * 1. Cap each agent list at K items.
+ * 2. Normalize each text (lowercase, trim, collapse whitespace, strip trailing punct).
+ * 3. Group near-duplicates: same normalized string OR Jaccard token-overlap ≥ 0.6.
+ *    Track distinct agent indices per group for vote counting.
+ * 4. Score each group by vote count = |distinct agent indices|.
+ * 5. Consensus = groups with votes ≥ quorum, sorted by votes desc then mean confidence desc.
+ * 6. If no group meets quorum, return the single highest-vote group flagged tentative:true.
+ * 7. Label each output step with the highest-confidence original phrasing in the group.
+ */
+export function mergeNextStepConsensus(
+  lists: readonly (readonly AgentProposal[])[],
+  opts?: MergeOptions
+): ConsensusResult {
+  const k = opts?.k ?? DEFAULT_K;
+  const quorum = opts?.quorum ?? DEFAULT_QUORUM;
+  const agentCount = lists.length;
+
+  if (agentCount === 0) {
+    return { agentCount: 0, quorum, steps: [] };
+  }
+
+  // Step 1 + 2: cap each agent list and normalize proposals.
+  const clusters: Cluster[] = [];
+
+  for (let agentIndex = 0; agentIndex < lists.length; agentIndex++) {
+    const list = lists[agentIndex];
+    const capped = list.slice(0, k);
+
+    for (const proposal of capped) {
+      const norm = normalize(proposal.text);
+      if (norm.length === 0) {
+        continue;
+      }
+
+      // Step 3: find an existing cluster to join.
+      const targetCluster = findOrCreateCluster(clusters, norm);
+      targetCluster.agentIndices.add(agentIndex);
+      // Sanitise confidence at ingestion: the type says `number` but the value comes from raw LLM
+      // JSON, so a missing/NaN/Infinity/out-of-range confidence must NOT leak into meanConf (it
+      // would poison the mean and could spuriously clear the downstream 0.7 inject floor). Invalid
+      // → 0 (correctly fails the floor); valid → clamped to [0,1].
+      targetCluster.members.push({
+        confidence: safeConfidence(proposal.confidence),
+        text: proposal.text,
+      });
+    }
+  }
+
+  if (clusters.length === 0) {
+    return { agentCount, quorum, steps: [] };
+  }
+
+  // Step 4: compute vote count and mean confidence per cluster.
+  const scored = clusters.map((cluster) => {
+    const votes = cluster.agentIndices.size;
+    const meanConf =
+      cluster.members.reduce((sum, m) => sum + m.confidence, 0) / cluster.members.length;
+
+    // Label = original phrasing from the highest-confidence member.
+    const bestMember = cluster.members.reduce((best, m) =>
+      m.confidence > best.confidence ? m : best
+    );
+
+    return { cluster, meanConf, text: bestMember.text, votes };
+  });
+
+  // Step 5: separate consensus groups from sub-quorum groups.
+  const consensusGroups = scored
+    .filter((s) => s.votes >= quorum)
+    .sort((a, b) => b.votes - a.votes || b.meanConf - a.meanConf);
+
+  if (consensusGroups.length > 0) {
+    const steps: NextStep[] = consensusGroups.map((s) => ({
+      confidence: s.meanConf,
+      text: s.text,
+      votes: s.votes,
+    }));
+    return { agentCount, quorum, steps };
+  }
+
+  // Step 6: no group reached quorum — tentative fallback (single highest-vote group).
+  const best = scored.reduce((prev, curr) => {
+    if (curr.votes > prev.votes) {
+      return curr;
+    }
+    if (curr.votes === prev.votes && curr.meanConf > prev.meanConf) {
+      return curr;
+    }
+    return prev;
+  });
+
+  const steps: NextStep[] = [
+    {
+      confidence: best.meanConf,
+      tentative: true,
+      text: best.text,
+      votes: best.votes,
+    },
+  ];
+  return { agentCount, quorum, steps };
+}
+
+/**
+ * Find a cluster whose normalized key matches `norm` exactly or has Jaccard ≥ threshold,
+ * or create and register a new one.
+ */
+function findOrCreateCluster(clusters: Cluster[], norm: string): Cluster {
+  for (const cluster of clusters) {
+    if (cluster.normalized === norm) {
+      return cluster;
+    }
+    if (jaccard(cluster.normalized, norm) >= JACCARD_THRESHOLD) {
+      return cluster;
+    }
+  }
+  const newCluster: Cluster = {
+    agentIndices: new Set(),
+    members: [],
+    normalized: norm,
+  };
+  clusters.push(newCluster);
+  return newCluster;
+}
+
+/**
+ * Compute the Jaccard token-overlap coefficient between two normalized strings.
+ * J(A,B) = |A ∩ B| / |A ∪ B|
+ */
+function jaccard(a: string, b: string): number {
+  const setA = tokenSet(a);
+  const setB = tokenSet(b);
+  if (setA.size === 0 && setB.size === 0) {
+    return 1;
+  }
+  if (setA.size === 0 || setB.size === 0) {
+    return 0;
+  }
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) {
+      intersection++;
+    }
+  }
+  const union = setA.size + setB.size - intersection;
+  return intersection / union;
+}
+
+/**
+ * Normalize a step text for grouping:
+ * lowercase, trim, collapse internal whitespace, strip trailing punctuation.
+ */
+function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, ' ')
+    .replace(/[.,;:!?]+$/, '');
+}
+
+/** Coerce a raw (untrusted) confidence into a finite number in [0,1]; invalid → 0. */
+function safeConfidence(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+
+// ── Private helper ──────────────────────────────────────────────────────────
+
+/**
+ * Tokenize a normalized string into a set of tokens.
+ */
+function tokenSet(normalized: string): Set<string> {
+  // Strip wrapping punctuation from each token so code-bearing proposals cluster: the lenses phrase
+  // the same action differently and wrap code in backticks/quotes (`return a - b`, "calc.js"), which
+  // otherwise fragments the tokens ("`return" ≠ "return") and makes the Jaccard overlap undercount
+  // real agreement. Pure-punctuation tokens (operators like - / +) drop out, which is fine — we are
+  // grouping intent, not preserving exact syntax.
+  return new Set(
+    normalized
+      .split(/\s+/)
+      .map((t) => t.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ''))
+      .filter((t) => t.length > 0)
+  );
+}

package/src/lib/modules/server/sessions/summary-store.ts

@@ -0,0 +1,113 @@
+/**
+ * Summary Store — SQLite persistence for session summary records.
+ *
+ * Persists SessionSummaryRecord rows written by the autopilot engine after
+ * each summarise+consensus pipeline run. Uses better-sqlite3 with WAL journal
+ * mode, mirroring the pattern from terminal-store.ts.
+ *
+ * Database location: ~/.shooter/shooter.db (shared with terminal-store)
+ */
+
+import type { SessionSummaryRecord } from '$lib/types';
+
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { shooterDataDir } from '../utils/shooter-home.js';
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const DB_DIR = shooterDataDir();
+const DB_PATH = path.join(DB_DIR, 'shooter.db');
+
+// ── Column list ──────────────────────────────────────────────────────
+
+const COLUMNS = [
+  'id',
+  'terminal_id',
+  'session_id',
+  'project_name',
+  'summary',
+  'next_steps',
+  'trigger',
+  'created_at',
+] as const;
+
+// ── Row ↔ Record conversion ──────────────────────────────────────────
+
+export class SummaryStore {
+  private db: Database.Database;
+
+  constructor() {
+    fs.mkdirSync(DB_DIR, { recursive: true });
+    this.db = new Database(DB_PATH);
+    this.db.pragma('journal_mode = WAL');
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS session_summaries (
+        id           TEXT PRIMARY KEY,
+        terminal_id  TEXT,
+        session_id   TEXT,
+        project_name TEXT,
+        summary      TEXT NOT NULL,
+        next_steps   TEXT NOT NULL DEFAULT '[]',
+        trigger      TEXT NOT NULL,
+        created_at   TEXT NOT NULL
+      )
+    `);
+  }
+
+  insert(record: SessionSummaryRecord): void {
+    const placeholders = COLUMNS.map(() => '?').join(', ');
+    this.db
+      .prepare(`INSERT INTO session_summaries (${COLUMNS.join(', ')}) VALUES (${placeholders})`)
+      .run(
+        record.id,
+        record.terminalId,
+        record.sessionId,
+        record.projectName,
+        record.summary,
+        record.nextSteps,
+        record.trigger,
+        record.createdAt
+      );
+  }
+
+  listRecent(limit: number, sessionId?: string): SessionSummaryRecord[] {
+    if (sessionId) {
+      const rows = this.db
+        .prepare(
+          'SELECT * FROM session_summaries WHERE session_id = ? ORDER BY created_at DESC LIMIT ?'
+        )
+        .all(sessionId, limit) as Record<string, unknown>[];
+      return rows.map(rowToRecord);
+    }
+    const rows = this.db
+      .prepare('SELECT * FROM session_summaries ORDER BY created_at DESC LIMIT ?')
+      .all(limit) as Record<string, unknown>[];
+    return rows.map(rowToRecord);
+  }
+}
+
+// ── SummaryStore ─────────────────────────────────────────────────────
+
+function rowToRecord(row: Record<string, unknown>): SessionSummaryRecord {
+  return {
+    createdAt: row.created_at as string,
+    id: row.id as string,
+    nextSteps: row.next_steps as string,
+    projectName: (row.project_name as string) ?? null,
+    sessionId: (row.session_id as string) ?? null,
+    summary: row.summary as string,
+    terminalId: (row.terminal_id as string) ?? null,
+    trigger: row.trigger as string,
+  };
+}
+
+// ── Singleton ────────────────────────────────────────────────────────
+// Shared instance across module loaders (same pattern as terminal-store).
+
+const SS_GLOBAL_KEY = '__shooter_summary_store';
+export const summaryStore: SummaryStore =
+  ((globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] as SummaryStore) || new SummaryStore();
+(globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] = summaryStore;

package/src/lib/modules/server/terminal/agent-launch.ts

@@ -0,0 +1,26 @@
+// Inject a default `--permission-mode` into a claude launch, configurable via the
+// SHOOTER_AGENT_PERMISSION_MODE env var, so managed agent terminals can actually act instead of
+// being auto-denied by a restrictive global Claude config. Claude-only (the flag is
+// claude-specific) and never overrides an explicit --permission-mode the caller passed.
+// Pure — unit-tested in tests/agent-launch.test.cjs.
+
+const CLAUDE_COMMANDS = new Set(['claude']);
+
+export function withAgentPermissionMode(
+  command: string,
+  args: string[],
+  mode: string | undefined
+): string[] {
+  const trimmed = (mode ?? '').trim();
+  if (trimmed.length === 0) {
+    return args; // feature off when unset
+  }
+  const base = command.split('/').pop() ?? command;
+  if (!CLAUDE_COMMANDS.has(base)) {
+    return args; // --permission-mode is claude-specific
+  }
+  if (args.includes('--permission-mode')) {
+    return args; // an explicit flag always wins
+  }
+  return [...args, '--permission-mode', trimmed];
+}

package/src/lib/modules/server/terminal/pty-holder.cjs

@@ -114,6 +114,12 @@ try {
   /* best effort */
 }
 ptyEnv.SHOOTER_CLIPBOARD_DIR = clipboardDir;
+// Tag this PTY with its Shooter terminal id so in-agent lifecycle hooks
+// (notifier.cjs) can attribute their events to THIS managed terminal. The
+// autopilot engine + phone driver key on terminalId; a plain shell that a
+// user starts outside Shooter never sees this var, so its behaviour is
+// unchanged.
+ptyEnv.SHOOTER_TERMINAL_ID = id;
 
 // Prepend clipboard shim scripts to PATH so tools find our xclip/wl-paste
 const shimsDir = path.resolve(__dirname, '..', 'scripts', 'clipboard-shims');

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

@@ -18,6 +18,7 @@ import {
   readOnlySourceForCommand,
 } from '../sessions/provider-paths';
 import { broadcastEvent } from '../ws/server.js';
+import { withAgentPermissionMode } from './agent-launch.js';
 import { HolderClient } from './holder-client';
 import { openCodeWatcher } from './opencode-watcher';
 import { terminalStore } from './terminal-store';
@@ -134,8 +135,17 @@ class PtyManager {
     const socketPath = `/tmp/shooter-term-${id}.sock`;
     const holderScript = resolveHolderPath();
 
+    // Inject the configured default --permission-mode for claude (SHOOTER_AGENT_PERMISSION_MODE),
+    // so a managed agent can act instead of being auto-denied by a restrictive global config.
+    // No-op unless set; never overrides an explicit flag. Persisted so reconnect keeps it.
+    const launchArgs = withAgentPermissionMode(
+      command,
+      args,
+      process.env.SHOOTER_AGENT_PERMISSION_MODE
+    );
+
     // Fork the holder process as detached so it survives server restarts
-    const holderArgs = [id, socketPath, cwd, String(cols), String(rows), command, ...args];
+    const holderArgs = [id, socketPath, cwd, String(cols), String(rows), command, ...launchArgs];
     const holder: ChildProcess = fork(holderScript, holderArgs, {
       detached: true,
       stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
@@ -179,7 +189,7 @@ class PtyManager {
 
     const now = new Date();
     const terminal: ManagedTerminal = {
-      args,
+      args: launchArgs,
       clients: new Set(),
       cols,
       command,
@@ -210,7 +220,7 @@ class PtyManager {
 
     // Persist to SQLite
     terminalStore.insert({
-      args: JSON.stringify(args),
+      args: JSON.stringify(launchArgs),
       cols,
       command,
       createdAt: now.toISOString(),

package/src/lib/modules/server/terminal/session-watcher.ts

@@ -26,6 +26,10 @@ class SessionWatcher {
     string,
     Map<string, { parts: MessagePart[]; timestamp: string }>
   >();
+  // Last read offset per file, retained ACROSS stop() so a re-subscribe resumes where it left off
+  // instead of jumping to the current end of file (which would skip any lines — e.g. an agent-idle
+  // marker — written while no subscriber happened to be attached).
+  private lastOffsetPerFile = new Map<string, number>();
   // Buffer for incomplete trailing lines (no terminating newline yet)
   private lineBufferPerFile = new Map<string, string>();
   // Track message index per file for generating fallback IDs
@@ -107,6 +111,8 @@ class SessionWatcher {
     }
 
     void watched.watcher.close();
+    // Remember where we stopped reading so a future re-subscribe resumes from here, not from EOF.
+    this.lastOffsetPerFile.set(filePath, watched.offset);
     this.watchedFiles.delete(filePath);
     this.assistantTurnsPerFile.delete(filePath);
     this.messageIndexPerFile.delete(filePath);
@@ -149,8 +155,12 @@ class SessionWatcher {
       };
     }
 
-    // Initialize tracking state for this file
-    const initialOffset = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    // Initialize tracking state for this file. Resume from the last read offset if we watched this
+    // file before (so content written during the gap is not skipped); otherwise start at EOF.
+    const fileSize = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    const remembered = this.lastOffsetPerFile.get(filePath);
+    this.lastOffsetPerFile.delete(filePath);
+    const initialOffset = remembered !== undefined ? Math.min(remembered, fileSize) : fileSize;
     this.assistantTurnsPerFile.set(filePath, new Map());
     this.messageIndexPerFile.set(filePath, 0);
     this.lineBufferPerFile.set(filePath, '');

package/src/lib/modules/server/terminal/terminal-store.ts

@@ -13,9 +13,11 @@ import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 
+import { shooterDataDir } from '../utils/shooter-home.js';
+
 // ── Constants ────────────────────────────────────────────────────────
 
-const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_DIR = shooterDataDir();
 const DB_PATH = path.join(DB_DIR, 'shooter.db');
 
 // ── Snake/Camel Conversion ───────────────────────────────────────────

package/src/lib/modules/server/utils/shooter-home.ts

@@ -0,0 +1,16 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+/**
+ * The Shooter data directory — the SQLite DB and engine/permission state live here.
+ *
+ * Honors `SHOOTER_HOME` so an isolated instance (a test server, or a second server run alongside
+ * the user's daemon) keeps its DB/state separate from the default `~/.shooter` instead of sharing
+ * it (which would let one server's `reconnectAll()` adopt the other's live terminals). This matches
+ * the CLI (`bin/shooter.cjs`) and the env loader (`env.ts`), which already treat `SHOOTER_HOME` as
+ * the data dir. When unset, falls back to `~/.shooter`.
+ */
+export function shooterDataDir(): string {
+  const override = process.env.SHOOTER_HOME?.trim();
+  return override && override.length > 0 ? override : join(homedir(), '.shooter');
+}

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

@@ -13,6 +13,18 @@ const eventsClients: Set<WebSocket> =
   ((globalThis as Record<string, unknown>)[EVENTS_KEY] as Set<WebSocket>) || new Set<WebSocket>();
 (globalThis as Record<string, unknown>)[EVENTS_KEY] = eventsClients;
 
+/**
+ * Server-side listeners (e.g. the always-on autopilot engine) that observe
+ * every broadcast event. Kept on globalThis so the listener registered from the
+ * server.ts module graph and the broadcaster called from the bundled SvelteKit
+ * handler graph share one set.
+ */
+const LISTENERS_KEY = '__shooter_ws_event_listeners';
+const eventListeners: Set<(event: ShooterEvent) => void> =
+  ((globalThis as Record<string, unknown>)[LISTENERS_KEY] as Set<(event: ShooterEvent) => void>) ||
+  new Set<(event: ShooterEvent) => void>();
+(globalThis as Record<string, unknown>)[LISTENERS_KEY] = eventListeners;
+
 // ── Handlers ────────────────────────────────────────────────────────
 
 /**
@@ -31,6 +43,15 @@ export function broadcastEvent(event: ShooterEvent): void {
       ws.send(data);
     }
   }
+
+  // Fan out to server-side listeners (autopilot engine, etc.).
+  for (const listener of eventListeners) {
+    try {
+      listener(event);
+    } catch {
+      // a faulty listener must never break the broadcast
+    }
+  }
 }
 
 /**
@@ -62,3 +83,14 @@ export function handleEventsConnection(ws: WebSocket): void {
     eventsClients.delete(ws);
   });
 }
+
+/**
+ * Register a server-side listener that receives every broadcast ShooterEvent.
+ * Returns an unsubscribe function. Used by the always-on autopilot engine.
+ */
+export function onShooterEvent(listener: (event: ShooterEvent) => void): () => void {
+  eventListeners.add(listener);
+  return (): void => {
+    eventListeners.delete(listener);
+  };
+}

package/src/lib/modules/server/ws/presence-store.ts

@@ -0,0 +1,50 @@
+// Viewer-presence store: "is someone actually watching" (foreground) vs "away".
+//
+// Why this exists: the phone-resident autonomous loop holds a PERSISTENT /ws/events
+// connection to run. So raw WebSocket-connection count no longer means "the user is
+// watching" — it's always > 0. The autopilot push decision must instead key on whether a
+// viewer is FOREGROUNDED (heartbeat within TTL), reported via POST /api/presence.
+//
+// globalThis singleton so the SvelteKit route (which writes it) and the server.ts engine
+// (which reads it) share one instance across the dual module graph — same pattern as the
+// ws ticket store and the event-listener registry.
+
+const PRESENCE_TTL_MS = 45_000;
+const KEY = '__shooter_presence';
+
+// eslint-disable-next-line no-restricted-syntax -- internal singleton shape, never exported
+interface PresenceRecord {
+  everReported: boolean;
+  lastForegroundAt: number;
+}
+
+/** True once any client has ever reported presence (used for backward-compatible fallback). */
+export function hasEverReported(): boolean {
+  return store().everReported;
+}
+
+/** True when a viewer reported `foreground` within the TTL window. */
+export function isViewerPresent(
+  now: number = Date.now(),
+  ttlMs: number = PRESENCE_TTL_MS
+): boolean {
+  return now - store().lastForegroundAt < ttlMs;
+}
+
+/**
+ * Record a presence heartbeat. `foreground` marks the viewer as actively watching (now);
+ * `background` marks them away immediately (so push resumes without waiting out the TTL).
+ */
+export function reportPresence(state: 'background' | 'foreground', now: number = Date.now()): void {
+  const s = store();
+  s.everReported = true;
+  s.lastForegroundAt = state === 'foreground' ? now : 0;
+}
+
+function store(): PresenceRecord {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[KEY]) {
+    g[KEY] = { everReported: false, lastForegroundAt: 0 };
+  }
+  return g[KEY] as PresenceRecord;
+}