@juspay/shooter 1.4.0 → 1.6.0

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

@@ -12,17 +12,18 @@
  */
 
 import type {
+  ConversationMessage,
+  MessagePart,
   OpenCodeMessage,
   OpenCodePart,
   OpenCodePartData,
   OpenCodeSession,
-} from '$generated/types';
+  OpenCodeWatchState as WatchState,
+} from '$lib/types';
 
 import Database from 'better-sqlite3';
 import * as fs from 'fs';
 
-import type { ConversationMessage, MessagePart } from '../sessions/types';
-
 import { resolveOpenCodeDbPath } from '../sessions/opencode-db-path';
 
 // ── Constants ────────────────────────────────────────────────────────
@@ -35,24 +36,6 @@ const POLL_INTERVAL_MS = 2000;
 /** Maximum parameters per SQLite IN clause (SQLite limit is 999). */
 const SQLITE_MAX_PARAMS = 500;
 
-// ── Per-session Watcher State ────────────────────────────────────────
-// WatchState is a runtime/behavioral type (callbacks, emittedSets,
-// intervalHandle) and stays local.
-
-interface WatchState {
-  callbacks: Set<(messages: ConversationMessage[]) => void>;
-  /** Set of message IDs we have already emitted, to avoid duplicates. */
-  emittedMessageIds: Set<string>;
-  /** Map of part ID to last-seen time_updated, to detect in-place updates. */
-  emittedPartUpdatedAt: Map<string, number>;
-  intervalHandle: ReturnType<typeof setInterval>;
-  /** Highest time_created we have seen for messages (milliseconds). */
-  lastMessageTime: number;
-  /** Highest time_updated we have seen for parts (milliseconds). */
-  lastPartTime: number;
-  sessionId: string;
-}
-
 class OpenCodeWatcher {
   private watchers = new Map<string, WatchState>();
 
@@ -156,7 +139,10 @@ class OpenCodeWatcher {
         if (!partsByMessage.has(part.message_id)) {
           partsByMessage.set(part.message_id, []);
         }
-        partsByMessage.get(part.message_id)!.push(part);
+        const bucket = partsByMessage.get(part.message_id);
+        if (bucket) {
+          bucket.push(part);
+        }
       }
 
       return this.buildMessages(messages, partsByMessage);
@@ -449,7 +435,10 @@ class OpenCodeWatcher {
             if (!partsByMessage.has(part.message_id)) {
               partsByMessage.set(part.message_id, []);
             }
-            partsByMessage.get(part.message_id)!.push(part);
+            const bucket = partsByMessage.get(part.message_id);
+            if (bucket) {
+              bucket.push(part);
+            }
           }
 
           const newEntries = this.buildMessages(dedupedMessages, partsByMessage);
@@ -510,7 +499,10 @@ class OpenCodeWatcher {
             if (!partsByMessage.has(part.message_id)) {
               partsByMessage.set(part.message_id, []);
             }
-            partsByMessage.get(part.message_id)!.push(part);
+            const bucket = partsByMessage.get(part.message_id);
+            if (bucket) {
+              bucket.push(part);
+            }
           }
 
           // Fetch the parent messages for context (batched to avoid SQLite param limit).

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

@@ -1,4 +1,9 @@
-import type { TerminalRecord } from '$generated/types';
+import type {
+  ConversationMessage,
+  PtyManagedTerminal as ManagedTerminal,
+  PtyOutputBuffer as OutputBuffer,
+  TerminalRecord,
+} from '$lib/types';
 import type WebSocket from 'ws';
 
 import { type ChildProcess, fork } from 'child_process';
@@ -7,48 +12,11 @@ import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from 'fs'
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-import type { ConversationMessage } from '../sessions/types';
-
+import { broadcastEvent } from '../ws/server.js';
 import { HolderClient } from './holder-client';
 import { openCodeWatcher } from './opencode-watcher';
 import { terminalStore } from './terminal-store';
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface ManagedTerminal {
-  args: string[];
-  clients: Set<WebSocket>;
-  cols: number;
-  command: string;
-  createdAt: Date;
-  currentCwd: null | string;
-  cwd: string;
-  exitCode: null | number;
-  exitedAt: Date | null;
-  holderPid: number;
-  id: string;
-  isActive: boolean;
-  openCodeNoopCb: ((messages: ConversationMessage[]) => void) | null;
-  openCodeSessionId: null | string;
-  outputBuffers: Map<WebSocket, OutputBuffer>;
-  pid: number;
-  pollTimer: null | ReturnType<typeof setInterval>;
-  pty: HolderClient;
-  rows: number;
-  scrollback: string;
-  sessionFile: null | string;
-  socketPath: string;
-  status: 'exited' | 'running';
-  watcherOffset: number;
-}
-
-interface OutputBuffer {
-  data: string[];
-  size: number;
-}
-
 export type { ManagedTerminal };
 
 // ---------------------------------------------------------------------------
@@ -195,7 +163,10 @@ class PtyManager {
       });
     });
 
-    const holderPid = holder.pid!;
+    if (holder.pid === undefined || holder.pid === null) {
+      throw new Error(`Holder process forked but PID unavailable for terminal ${id}`);
+    }
+    const holderPid = holder.pid;
 
     // Connect to the holder via Unix socket
     const client = new HolderClient();
@@ -255,6 +226,13 @@ class PtyManager {
     this.startSessionDiscovery(terminal);
 
     this.terminals.set(id, terminal);
+
+    broadcastEvent({
+      command: terminal.command ?? command,
+      terminalId: id,
+      type: 'terminal-created',
+    });
+
     return terminal;
   }
 
@@ -281,11 +259,14 @@ class PtyManager {
         } catch {
           // Best effort
         }
-        // Also kill the holder process directly
-        try {
-          process.kill(terminal.holderPid, 'SIGKILL');
-        } catch {
-          // Best effort — holder may already be gone
+        // Also kill the holder process directly (guard against invalid PIDs —
+        // process.kill(0) targets the current process group, -1 targets all)
+        if (terminal.holderPid > 0) {
+          try {
+            process.kill(terminal.holderPid, 'SIGKILL');
+          } catch {
+            // Best effort — holder may already be gone
+          }
         }
       }
 
@@ -397,6 +378,7 @@ class PtyManager {
       terminal.status = 'exited';
       terminal.exitedAt = new Date();
       terminalStore.markExited(id, null);
+      this.emitTerminalExited(id, null);
       return true;
     }
 
@@ -411,6 +393,7 @@ class PtyManager {
         terminal.status = 'exited';
         terminal.exitedAt = terminal.exitedAt ?? new Date();
         terminalStore.markExited(id, null);
+        this.emitTerminalExited(id, null);
       }
     }, SIGKILL_DELAY_MS);
 
@@ -577,6 +560,15 @@ class PtyManager {
   // Private: startSessionDiscovery — polling for session files
   // -----------------------------------------------------------------------
 
+  /** Broadcast a terminal-exited event to /ws/events for the activity feed. */
+  private emitTerminalExited(terminalId: string, exitCode: null | number): void {
+    broadcastEvent({
+      code: exitCode ?? null,
+      terminalId,
+      type: 'terminal-exited',
+    });
+  }
+
   /** Evict a terminal, freeing all resources. */
   private evict(id: string): void {
     const terminal = this.terminals.get(id);
@@ -1003,6 +995,8 @@ class PtyManager {
       terminal.exitedAt = new Date();
       terminalStore.markExited(terminal.id, exitCode);
 
+      this.emitTerminalExited(terminal.id, exitCode);
+
       const exitMsg = JSON.stringify({
         code: exitCode,
         signal: null,
@@ -1019,6 +1013,7 @@ class PtyManager {
         terminal.status = 'exited';
         terminal.exitedAt = new Date();
         terminalStore.markOrphaned(terminal.id);
+        this.emitTerminalExited(terminal.id, null);
       }
     });
   }

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

@@ -1,23 +1,16 @@
-import { watch as chokidarWatch, type FSWatcher } from 'chokidar';
+import type {
+  ConversationMessage,
+  MessagePart,
+  OnNewEntries,
+  SessionWatchedFile as WatchedFile,
+} from '$lib/types';
+
+import { watch as chokidarWatch } from 'chokidar';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import type { ConversationMessage, MessagePart } from '../sessions/types';
-
 import { parseJsonlText } from '../sessions/jsonl-parser';
 
-/**
- * Callback invoked when new JSONL entries are parsed from a watched file.
- */
-type OnNewEntries = (entries: ConversationMessage[]) => void;
-
-interface WatchedFile {
-  callbacks: Set<OnNewEntries>;
-  filePath: string;
-  offset: number;
-  watcher: FSWatcher;
-}
-
 // Path to Claude Code's project session data
 const CLAUDE_PROJECTS_DIR = path.join(process.env.HOME || '', '.claude', 'projects');
 
@@ -89,7 +82,10 @@ class SessionWatcher {
           continue;
         }
         try {
-          entries.push(JSON.parse(trimmed));
+          const parsed: unknown = JSON.parse(trimmed);
+          if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            entries.push(parsed as Record<string, unknown>);
+          }
         } catch {
           // skip malformed lines
         }
@@ -274,7 +270,9 @@ class SessionWatcher {
       }
 
       // Parse the new lines using the file's accumulated assistant turn state
-      const assistantTurns = this.assistantTurnsPerFile.get(filePath) || new Map();
+      const assistantTurns: Map<string, { parts: MessagePart[]; timestamp: string }> =
+        this.assistantTurnsPerFile.get(filePath) ??
+        new Map<string, { parts: MessagePart[]; timestamp: string }>();
       const startIndex = this.messageIndexPerFile.get(filePath) || 0;
       const newText = completeLines.join('\n');
       const newMessages = parseJsonlText(newText, assistantTurns, startIndex);

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

@@ -7,7 +7,7 @@
  * Database location: ~/.shooter/shooter.db
  */
 
-import type { TerminalRecord } from '$generated/types';
+import type { TerminalRecord } from '$lib/types';
 
 import Database from 'better-sqlite3';
 import * as fs from 'fs';

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

@@ -2,24 +2,9 @@
 // Manages the /ws/events channel: tracks connected clients and broadcasts
 // ShooterEvents to all listeners. No client-to-server messages are expected.
 
-import type { PermissionDecision, SessionSource } from '$generated/types';
+import type { WireShooterEvent as ShooterEvent } from '$lib/types';
 import type { WebSocket } from 'ws';
 
-// ── Event types ─────────────────────────────────────────────────────
-
-export type ShooterEvent =
-  | { code: null | number; terminalId: string; type: 'terminal-exited' }
-  | { command: string; terminalId: string; type: 'terminal-created' }
-  | { decision: PermissionDecision; requestId: string; type: 'permission-resolved' }
-  | {
-      input: Record<string, unknown>;
-      requestId: string;
-      tool: string;
-      type: 'permission-requested';
-    }
-  | { project: string; sessionId: string; source: SessionSource; type: 'session-started' }
-  | { sessionId: string; summary: string; type: 'session-ended' };
-
 // ── Connection tracking ─────────────────────────────────────────────
 
 /** All clients subscribed to the global events channel. */

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

@@ -6,6 +6,7 @@
 // Cloudflare Tunnel closes idle WebSocket connections after ~100 seconds,
 // so 30-second pings keep connections alive through the tunnel.
 
+import type { PendingPong } from '$lib/types';
 import type { WebSocket } from 'ws';
 
 import { getAllConnections } from './server.js';
@@ -24,11 +25,6 @@ let pingInterval: null | ReturnType<typeof setInterval> = null;
  * Stores the timeout timer and the listener functions so they can be
  * removed cleanly when stopKeepalive() is called mid-cycle.
  */
-interface PendingPong {
-  onClose: () => void;
-  onPong: () => void;
-  timer: ReturnType<typeof setTimeout>;
-}
 const pendingPongs = new Map<WebSocket, PendingPong>();
 
 // ── Public API ───────────────────────────────────────────────────────

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

@@ -16,7 +16,7 @@ import {
 } from './events-handler.js';
 import { handleSessionConnection } from './session-handler.js';
 import { handleTerminalConnection } from './terminal-handler.js';
-export type { ShooterEvent } from './events-handler.js';
+export type { WireShooterEvent as ShooterEvent } from '$lib/types';
 
 // ── Connection tracking ──────────────────────────────────────────────
 

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

@@ -3,98 +3,31 @@
 // on connect and streams new messages (text, tool-use, tool-result,
 // thinking) as they appear.
 
-import type { MessageRole, TextContentBlock } from '$generated/types';
+import type {
+  WireSessionClientMessage as ClientMessage,
+  WsConnectionState as ConnectionState,
+  ConversationMessage,
+  WireHistoryMessage as HistoryMessage,
+  WireHistoryPart as HistoryPart,
+  SessionManagedTerminal as ManagedTerminal,
+  MessagePart,
+  SessionPtyManagerFullLike as PtyManagerFullLike,
+  SessionPtyManagerLike as PtyManagerLike,
+  WireSessionServerMessage as ServerMessage,
+  SessionWatcherLike,
+  TextContentBlock,
+} from '$lib/types';
 import type { WebSocket } from 'ws';
 
 import * as fs from 'fs';
 import * as path from 'path';
 
-import type { ConversationMessage, MessagePart } from '../sessions/types';
-
-// ── Types ────────────────────────────────────────────────────────────
-
-/** Inbound messages from the client. */
-type ClientMessage =
-  | { sessionId: string; type: 'subscribe' }
-  | { text: string; type: 'send-input' }
-  | { type: 'cancel' };
-
-/** A message in the history payload. */
-interface HistoryMessage {
-  content: HistoryPart[];
-  id: string;
-  role: MessageRole;
-  timestamp: string;
-}
-
-/** A single part within a history message — discriminated union. */
-type HistoryPart =
-  | { content: string; type: 'text' }
-  | { content: string; type: 'thinking' }
-  | { id: string; input: Record<string, unknown>; toolName: string; type: 'tool_use' }
-  | { isError: boolean; output: string; toolUseId: string; type: 'tool_result' };
-
-interface ManagedTerminal {
-  id: string;
-  openCodeSessionId: null | string;
-  pty: {
-    pid: number;
-    write: (data: string) => void;
-  };
-  sessionFile: null | string;
-  status: 'exited' | 'running';
-}
-
-/** Extended PTY manager interface with list() for UUID-based terminal search. */
-interface PtyManagerFullLike extends PtyManagerLike {
-  list: () => ManagedTerminal[];
-}
-
-interface PtyManagerLike {
-  getTerminal: (id: string) => ManagedTerminal | undefined;
-}
-
-// ── PTY Manager type ─────────────────────────────────────────────────
-
-/** Outbound messages to the client. */
-type ServerMessage =
-  | { content: TextContentBlock[]; role: MessageRole; timestamp: string; type: 'message' }
-  | {
-      id: string;
-      input: Record<string, unknown>;
-      name: string;
-      status: 'running';
-      type: 'tool-use';
-    }
-  | { id: string; isError: boolean; output: string; status: 'done'; type: 'tool-result' }
-  | { message: string; type: 'error' }
-  | { messages: HistoryMessage[]; type: 'history' }
-  | { text: string; type: 'thinking' }
-  | { type: 'session-end' };
-
-interface SessionWatcherLike {
-  getHistory: (sessionFile: string) => ConversationMessage[];
-  subscribe: (
-    sessionFile: string,
-    callback: (messages: ConversationMessage[]) => void
-  ) => () => void;
-}
-
 // ── Module-level references ──────────────────────────────────────────
 
 let _ptyManager: null | PtyManagerLike = null;
 let _ptyManagerFull: null | PtyManagerFullLike = null;
 let _sessionWatcher: null | SessionWatcherLike = null;
 
-/** Per-connection state tracked for cleanup. */
-interface ConnectionState {
-  /** True when the session is file-only (no terminal backing it). */
-  isExternalSession: boolean;
-  retryInterval: null | ReturnType<typeof setInterval>;
-  terminalId: string;
-  unsubscribe: (() => void) | null;
-}
-
 /**
  * Handle a new WebSocket connection on the `/ws/session/:id` channel.
  * Accepts BOTH Shooter terminal IDs and external Claude Code session UUIDs.
@@ -285,7 +218,7 @@ function findTerminalBySessionUuid(uuid: string): ManagedTerminal | undefined {
   // module-level _ptyManagerFull reference if available.
   if (_ptyManagerFull) {
     for (const t of _ptyManagerFull.list()) {
-      if (t.sessionFile && t.sessionFile.includes(`${uuid}.jsonl`)) {
+      if (t.sessionFile?.includes(`${uuid}.jsonl`)) {
         return _ptyManager.getTerminal(t.id);
       }
     }
@@ -296,7 +229,7 @@ function findTerminalBySessionUuid(uuid: string): ManagedTerminal | undefined {
 /** Parse and validate an inbound client message. */
 function parseClientMessage(raw: string): ClientMessage | null {
   try {
-    const msg = JSON.parse(raw);
+    const msg = JSON.parse(raw) as Record<string, unknown>;
     if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') {
       return null;
     }
@@ -589,7 +522,8 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
         case 'send-input': {
           if (state.isExternalSession) {
             safeSend(ws, {
-              message: 'Cannot send input — this is a read-only session. Connect to a terminal first.',
+              message:
+                'Cannot send input — this is a read-only session. Connect to a terminal first.',
               type: 'error',
             });
             return;
@@ -615,8 +549,8 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
           }
 
           // Try terminal first, then external
-          const newTerminal = _ptyManager?.getTerminal(msg.sessionId)
-            ?? findTerminalBySessionUuid(msg.sessionId);
+          const newTerminal =
+            _ptyManager?.getTerminal(msg.sessionId) ?? findTerminalBySessionUuid(msg.sessionId);
 
           if (newTerminal) {
             state.terminalId = newTerminal.id;

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

@@ -2,25 +2,14 @@
 // Relays terminal output to connected clients and routes client input
 // (keystrokes, resize, signals) back to the PTY.
 
-import type { TerminalSignal } from '$generated/types';
+import type {
+  WireTerminalClientMessage as ClientMessage,
+  TerminalPtyManagerLike as PtyManagerLike,
+  WireTerminalServerMessage as ServerMessage,
+  TerminalSignal,
+} from '$lib/types';
 import type { WebSocket } from 'ws';
 
-// ── Types ────────────────────────────────────────────────────────────
-
-/** Inbound messages from the client. */
-type ClientMessage =
-  | { cols: number; rows: number; type: 'resize' }
-  | { data: string; type: 'input' }
-  | { signal: TerminalSignal; type: 'signal' };
-
-/** Outbound messages to the client. */
-type ServerMessage =
-  | { bytes: number; type: 'output-dropped' }
-  | { chunk: number; data: string; total: number; type: 'scrollback' }
-  | { code: null | number; signal: null | string; type: 'exit' }
-  | { data: string; type: 'output' }
-  | { message: string; type: 'error' };
-
 // ── Constants ────────────────────────────────────────────────────────
 
 /** Signal name → numeric code for process.kill(). */
@@ -30,28 +19,6 @@ const SIGNAL_MAP: Record<string, NodeJS.Signals> = {
   SIGTSTP: 'SIGTSTP',
 };
 
-// ── PTY Manager type ─────────────────────────────────────────────────
-// Minimal duck-typed shape matching the real pty-manager singleton.
-
-interface ManagedTerminal {
-  clients: Set<WebSocket>;
-  exitCode: null | number;
-  id: string;
-  pty: {
-    kill: (signal: string) => void;
-    pid: number;
-    resize: (cols: number, rows: number) => void;
-    write: (data: string) => void;
-  };
-  status: 'exited' | 'running';
-}
-
-interface PtyManagerLike {
-  attach: (id: string, ws: WebSocket) => boolean;
-  detach: (id: string, ws: WebSocket) => boolean;
-  getTerminal: (id: string) => ManagedTerminal | undefined;
-}
-
 // Placeholder: will be replaced with the real ptyManager singleton import.
 // import { ptyManager } from '../terminal/pty-manager';
 let _ptyManager: null | PtyManagerLike = null;
@@ -153,8 +120,13 @@ export function setPtyManager(manager: PtyManagerLike): void {
 /** Parse and validate an inbound client message. Returns null for invalid messages. */
 function parseClientMessage(raw: string): ClientMessage | null {
   try {
-    const msg = JSON.parse(raw);
-    if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') {
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const msg = parsed as Record<string, unknown>;
+    if (typeof msg.type !== 'string') {
       return null;
     }
 
@@ -164,27 +136,32 @@ function parseClientMessage(raw: string): ClientMessage | null {
           return null;
         }
         return { data: msg.data, type: 'input' };
-      case 'resize':
+      case 'resize': {
+        const cols = msg.cols;
+        const rows = msg.rows;
         if (
-          typeof msg.cols !== 'number' ||
-          typeof msg.rows !== 'number' ||
-          !Number.isFinite(msg.cols) ||
-          !Number.isFinite(msg.rows)
+          typeof cols !== 'number' ||
+          typeof rows !== 'number' ||
+          !Number.isFinite(cols) ||
+          !Number.isFinite(rows)
         ) {
           return null;
         }
-        if (msg.cols < 1 || msg.rows < 1 || msg.cols > 500 || msg.rows > 200) {
+        if (cols < 1 || rows < 1 || cols > 500 || rows > 200) {
           return null;
         }
-        return { cols: Math.floor(msg.cols), rows: Math.floor(msg.rows), type: 'resize' };
-      case 'signal':
-        if (typeof msg.signal !== 'string' || !Object.hasOwn(SIGNAL_MAP, msg.signal)) {
+        return { cols: Math.floor(cols), rows: Math.floor(rows), type: 'resize' };
+      }
+      case 'signal': {
+        const signal = msg.signal;
+        if (typeof signal !== 'string' || !Object.hasOwn(SIGNAL_MAP, signal)) {
           return null;
         }
         return {
-          signal: msg.signal as TerminalSignal,
+          signal: signal as TerminalSignal,
           type: 'signal',
         };
+      }
       default:
         return null;
     }

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

@@ -5,7 +5,7 @@
 // This avoids putting the long-lived API_KEY in WebSocket URL query parameters,
 // which would appear in proxy logs, Cloudflare access logs, and browser history.
 
-import type { Ticket } from '$generated/types';
+import type { Ticket } from '$lib/types';
 
 import { randomBytes } from 'crypto';
 

package/src/lib/modules/shared/providers.ts

@@ -0,0 +1,21 @@
+import type { ProviderId } from '$lib/types';
+
+/** Env key names required for each provider to be considered configured. */
+export const PROVIDER_ENV_KEYS: Record<ProviderId, string[]> = {
+  anthropic: ['ANTHROPIC_API_KEY'],
+  'google-ai': ['GOOGLE_AI_API_KEY'],
+  litellm: ['LITELLM_API_KEY', 'LITELLM_BASE_URL'],
+  mistral: ['MISTRAL_API_KEY'],
+  openai: ['OPENAI_API_KEY'],
+};
+
+/** Check which providers have credentials configured. */
+export function getProviderAvailability(
+  env: Record<string, string | undefined>
+): Record<ProviderId, boolean> {
+  const result = {} as Record<ProviderId, boolean>;
+  for (const [id, keys] of Object.entries(PROVIDER_ENV_KEYS)) {
+    result[id as ProviderId] = keys.every((k) => Boolean(env[k]?.trim()));
+  }
+  return result;
+}

package/src/lib/types/activity.ts

@@ -0,0 +1,18 @@
+// Activity feed types that require union types not expressible in type-crafter YAML.
+
+/** A single content block within a WebSocket session message. */
+export interface ActivityContentBlock {
+  content?: string;
+  is_error?: boolean;
+  name?: string;
+  text?: string;
+  type: string;
+}
+
+/** A conversation message from a Claude Code session history batch.
+ *  Uses a union type (string | array) which the YAML schema cannot express. */
+export interface ActivitySessionMessage {
+  content: ActivityContentBlock[] | string;
+  role: string;
+  timestamp?: string;
+}