@threadbase-sh/streamer 1.33.0 → 1.35.0

package/dist/index.d.ts

@@ -196,6 +196,12 @@ type WSMessage = {
     sessionId: string;
     lines: string[];
     seqs?: (number | null)[];
+} | {
+    type: "conversation_updated";
+    conversationId: string;
+    messageCount: number;
+    lastActivity: string;
+    ownership: "external" | "managed";
 } | {
     type: "question";
     sessionId: string;
@@ -252,7 +258,30 @@ type WSMessage = {
     type: "scan_progress";
     scanned: number;
     total: number;
+} | {
+    type: "cache_alert";
+    fingerprint: string;
+    severity: "high" | "low";
+    missingCount: number;
+    totalRows: number;
+    detectedAt: string;
+    sample: {
+        id: string;
+        title?: string;
+    }[];
+} | {
+    type: "cache_alert_resolved";
+    fingerprint: string;
+    action: CacheAlertResolveAction;
 };
+/** The four cache-integrity resolution actions (POST /api/cache/alert/resolve). */
+type CacheAlertResolveAction = "prune_all" | "prune_selected" | "ignore" | "reset_rescan";
+type ServerWarmupState = "startup" | "cache_reset" | "conversation_refresh";
+interface ServerWarmingUpResponse {
+    error: "Server is warming up";
+    code: "SERVER_WARMING_UP";
+    warmupState: ServerWarmupState;
+}
 interface SessionResponse {
     id: string;
     conversationId: string;
@@ -284,6 +313,36 @@ interface SessionResponse {
     resumedFromConversationId?: string;
     /** See `ManagedSession.boundConversationId` — never repurposes `conversationId`. */
     boundConversationId?: string;
+    /**
+     * Who owns the underlying process. Additive — older clients ignore it, and it
+     * deliberately does NOT introduce a new `status` value: `VALID_STATUSES`
+     * rejects unknown values in `?status=` and the store drops sessions outside
+     * the requested set, so a new status string would make these sessions vanish
+     * from already-shipped apps.
+     *   managed    — this streamer spawned and holds the PTY
+     *   external   — a process we discovered but do not own (read-only)
+     *   historical — a cached conversation, no process known
+     */
+    ownership?: SessionOwnership;
+    /**
+     * Whether the process is believed to be running. Only ever "alive" when
+     * discovery actually saw it; never guessed from file activity.
+     */
+    processLiveness?: ProcessLiveness;
+    /**
+     * INFERRED from JSONL writes, never authoritative: "active_writing" means the
+     * transcript grew recently, which cannot distinguish a generating agent from
+     * one blocked on a permission gate (gates are screen-only). Absent for
+     * sessions we own — their `status` is the authoritative signal.
+     */
+    activity?: SessionActivity;
+}
+type SessionOwnership = "managed" | "external" | "historical";
+type ProcessLiveness = "alive" | "gone" | "unknown";
+interface SessionActivity {
+    state: "active_writing" | "quiet";
+    lastEventAt: string;
+    source: "jsonl";
 }
 interface ConversationListResponse {
     conversations: unknown[];
@@ -456,6 +515,7 @@ interface ScannerMeta {
     projectPath?: string;
     projectName?: string;
     title?: string;
+    sessionName?: string;
     model?: string;
     account?: string;
     gitBranch?: string;
@@ -579,7 +639,8 @@ declare class ConversationCache {
      * updateFromLine in order: the agent filter short-circuits the whole batch,
      * project context is backfilled last-wins, message_count increases by the
      * number of surviving message lines, and last_activity/last_message reflect
-     * the final message line.
+     * the newest message line by timestamp (a monotonic guard keeps them from
+     * moving backward when an interleaved writer appends an older line — P0.3).
      */
     updateFromLines(filePath: string, rawLines: string[]): void;
     upsertFromScannerMeta(metas: ScannerMeta[]): string[];
@@ -605,6 +666,12 @@ declare class ConversationCache {
         stat: FileStatEntry;
         meta: ConversationMeta;
     }>;
+    /**
+     * Conversation id for a JSONL path, or null when no row exists yet. Resolves
+     * by file_path (NOT conversationIdForFile) so codex rollout files — named
+     * rollout-<ts>-<uuid>.jsonl, whose stem is not the row id — resolve correctly.
+     */
+    getIdByFilePath(filePath: string): string | null;
     getMetaById(id: string): ConversationListItem | null;
     setConversationProjectId(conversationId: string, projectId: string): void;
     markAsStreamer(id: string): void;
@@ -628,15 +695,15 @@ declare class ConversationCache {
     /**
      * Drop the cached row for a file. Two callers with opposite intent:
      *  - a directory-watch "change" event (the file was appended to) — pass
-     *    `skipIfTailed: true`. A cached tail means the row is being actively
-     *    maintained from the file's real content by the live-tail
-     *    (updateFromLines) or warm-up path, fresher than any scanner-derived
-     *    view. Both watchers fire on the same append with no ordering guarantee;
-     *    without this guard the invalidate can land after the tail write and wipe
-     *    the just-cached row, flickering the conversation out of
-     *    /api/conversations on nearly every message (CRITICAL #2). The debounced
-     *    rescan still re-derives metadata, so skipping the eager drop loses
-     *    nothing.
+     *    `skipIfTailed: true`, which NEVER deletes (upsert-or-leave). A change
+     *    event fires on every external append; deleting here flickers the
+     *    conversation out of /api/conversations — whether it's a live-tailed row
+     *    the updateFromLines/warm-up path just wrote (CRITICAL #2; both watchers
+     *    fire on the same append with no ordering guarantee) OR a refresh-created
+     *    untailed row (a ?refresh=1 upsert never populates a tail, so the old
+     *    "delete when untailed" behavior made it vanish on its next append with no
+     *    client action). The live-tail path owns the row's content and the
+     *    debounced rescan re-derives metadata, so leaving the row loses nothing.
      *  - a genuine unlink (the file is gone) — leave `skipIfTailed` false so the
      *    row is always removed, otherwise a deleted session ghosts in the cache.
      */
@@ -678,6 +745,30 @@ declare class ConversationCache {
     reconcileDeletions(livePaths: Set<string>, opts?: {
         exists?: (filePath: string) => boolean;
     }): string[];
+    /**
+     * Read-only: list cached rows whose `file_path` no longer exists on disk.
+     * Unlike pruneGhostFiles/reconcileDeletions this mutates nothing — it just
+     * reports drift for the CacheIntegrityMonitor to classify. `tailed` flags
+     * rows that still have cached history (which pruneGhostFiles would keep).
+     */
+    listMissingFiles(exists?: (filePath: string) => boolean): {
+        id: string;
+        filePath: string;
+        title: string | null;
+        tailed: boolean;
+    }[];
+    /**
+     * Drop the given conversation ids outright — main row, tail, and message
+     * index — regardless of whether they have a tail. Used by the cache-integrity
+     * resolution actions (prune_all / prune_selected). Returns the count dropped.
+     */
+    dropRowsById(ids: string[]): number;
+    /**
+     * Wipe all cached conversation state — meta, tails, and message index — and
+     * reset the in-memory file index. Only called by the `reset_rescan`
+     * resolution action, which repopulates from a fresh disk scan afterward.
+     */
+    clearAll(): void;
 }
 
 type CacheMetadataKey = "last_conversation_id" | "last_conversation_created_at" | "projects_last_indexed_at" | "conversations_last_indexed_at" | "conversations_dirty";
@@ -832,6 +923,90 @@ declare class WSHub {
     private startPing;
 }
 
+/** One missing conversation the alert covers. */
+interface MissingEntry {
+    id: string;
+    filePath: string;
+    title: string | null;
+    tailed: boolean;
+}
+interface PendingAlert {
+    fingerprint: string;
+    severity: "high" | "low";
+    detectedAt: string;
+    missingCount: number;
+    totalRows: number;
+    backupPath?: string;
+    /** Capped at 1000 entries in the persisted file. */
+    missing: MissingEntry[];
+}
+
+type ResolveAction = CacheAlertResolveAction;
+/** The `cache_alert` WS variant, narrowed from the WSMessage union. */
+type CacheAlertWsMessage = Extract<WSMessage, {
+    type: "cache_alert";
+}>;
+type ResolveResult = {
+    ok: true;
+    action: ResolveAction;
+    pruned?: number;
+    backupPath?: string;
+} | {
+    alreadyResolved: true;
+} | {
+    conflict: true;
+    currentFingerprint: string;
+};
+declare class CacheIntegrityMonitor {
+    private readonly cache;
+    private readonly wsHub;
+    private readonly log;
+    private readonly cacheDir;
+    private readonly rescan?;
+    private readonly runDuringReset?;
+    private _pending;
+    private ignoredIds;
+    private deferredUnlinks;
+    private unlinkTimes;
+    constructor(cache: ConversationCache, wsHub: WSHub, log: Logger, cacheDir: string, rescan?: (() => Promise<ScannerMeta[]>) | undefined, runDuringReset?: (<T>(operation: () => Promise<T>) => Promise<T>) | undefined);
+    get pending(): PendingAlert | null;
+    private persist;
+    private classifySeverity;
+    private sampleOf;
+    private buildWsMessage;
+    wsMessage(): CacheAlertWsMessage | null;
+    healthzField(): {
+        severity: "high" | "low";
+        missingCount: number;
+        fingerprint: string;
+        detectedAt: string;
+    } | undefined;
+    /**
+     * Scan the cache for rows whose file is gone, excluding ids the user chose to
+     * ignore. If none remain, clear any stale pending alert and return (the caller
+     * decides whether to run pruneGhostFiles). Otherwise classify severity, persist
+     * the pending record, back up on high severity, and broadcast the alert.
+     */
+    runDetection(detectedAt?: string): Promise<void>;
+    /** Queue an unlink while an alert is pending — the row is not invalidated. */
+    deferUnlink(filePath: string): void;
+    /**
+     * Record a live unlink while NO alert is pending. Crossing the storm threshold
+     * (>= 10 unlinks within 30s) re-triggers detection.
+     */
+    recordUnlink(filePath: string): void;
+    private ensureBackup;
+    private clearPending;
+    private applyDeferredUnlinks;
+    private broadcastResolved;
+    /**
+     * Apply the human's chosen resolution. Idempotent per fingerprint: no pending
+     * alert → alreadyResolved; a different fingerprint → conflict. See the spec's
+     * four-action semantics.
+     */
+    resolve(fingerprint: string, action: ResolveAction, ids?: string[]): Promise<ResolveResult>;
+}
+
 type ApiDeps = {
     apiKey: string;
     localNoAuth: boolean;
@@ -847,6 +1022,7 @@ type ApiDeps = {
     sessionStore: SessionStore;
     wsHub: WSHub;
     cache: () => ConversationCache | null;
+    cacheMonitor: () => CacheIntegrityMonitor | null;
     projectsRepo: () => ProjectsRepository | null;
     conversationsRepo: () => ConversationsRepository | null;
     sessionsRepo: () => SessionsRepository | null;
@@ -990,6 +1166,7 @@ declare class PTYManager implements SessionRunner {
     private handleOutput;
     private detectLivePrompts;
     private handleQuiet;
+    private recheckReadyFromScreen;
     private markReady;
     private handleExit;
 }
@@ -1001,8 +1178,11 @@ declare class StreamerServer {
     private wsHub;
     private fileWatcher;
     private sessionFileMap;
+    private externalTails;
     private pendingLineSeqs;
     private pendingQuestions;
+    private contendedSessions;
+    private selfPtyEndedAt;
     private pendingQuestionKey;
     private pendingPermission;
     private scanner;
@@ -1012,7 +1192,8 @@ declare class StreamerServer {
     private scannerStale;
     private refreshInFlight;
     private binding;
-    private cacheReady;
+    private activeWarmups;
+    private nextWarmupId;
     private inFlightCacheWrites;
     private apiKey;
     private apiKeySource;
@@ -1036,10 +1217,12 @@ declare class StreamerServer {
     private defaultModel;
     private defaultEffort;
     private ptyGraceTimers;
+    private ptyGraceDeferCounts;
     private sessionSubscribers;
     private clientIdToWs;
     private wsToClientId;
     private cache;
+    private cacheMonitor;
     private projectsRepo;
     private conversationsRepo;
     private sessionsRepo;
@@ -1061,6 +1244,7 @@ declare class StreamerServer {
         apiKey: string;
     });
     private ptyAttachedIds;
+    private rememberSelfPtyEnded;
     /**
      * Send a session_list to only the client that triggered this HTTP request
      * (identified by X-Client-Id header → registered WS socket). Falls back to
@@ -1070,6 +1254,11 @@ declare class StreamerServer {
     private addSessionSubscriber;
     private startGraceTimer;
     get port(): number;
+    private currentWarmupState;
+    private beginWarmup;
+    private finishWarmup;
+    private withWarmup;
+    private rejectIfWarmingUp;
     listen(port: number, opts?: {
         awaitReady?: boolean;
     }): Promise<void>;
@@ -1126,6 +1315,43 @@ declare class StreamerServer {
      * Claude lines pass through unchanged so seq alignment stays intact.
      */
     private broadcastConversationLines;
+    /** True when a managed (PTY) session owns the tail for this canonical path. */
+    private isManagedTailPath;
+    /**
+     * Attach a live tail to a JSONL nobody is tailing yet, when it was touched
+     * recently enough to look actively written by an external agent. Capped at
+     * EXTERNAL_TAIL_MAX with LRU eviction.
+     */
+    private maybeAttachExternalTail;
+    /** Stop tailing an external file and drop its bookkeeping. */
+    private detachExternalTail;
+    /** Make room for one more tail by evicting the least recently active ones. */
+    private evictExternalTailsIfNeeded;
+    /**
+     * INFERRED activity for an externally-owned conversation, derived purely from
+     * how recently its JSONL grew (the external tail's bookkeeping). Returns
+     * undefined when we hold no tail for it, so a session we know nothing about
+     * reports no activity rather than a fabricated "quiet".
+     *
+     * This can never distinguish a generating agent from one blocked on a
+     * permission gate — gates render on the PTY screen and never reach the JSONL —
+     * which is why it is a separate field and not folded into `status`.
+     */
+    private externalActivityFor;
+    /** Attach inferred `activity` to externally-owned sessions in a response set. */
+    private withExternalActivity;
+    /** Detach external tails idle past EXTERNAL_TAIL_IDLE_MS. */
+    private sweepIdleExternalTails;
+    /**
+     * Push appended lines from an externally-owned conversation. Reuses the exact
+     * conversation_events / conversation_event shapes mobile already consumes,
+     * keyed by the conversation UUID — an external session has no PTY, so it must
+     * never produce terminal_output / terminal_replay / session_ready, and never a
+     * session_update whose session.id is a conversation UUID (that would mint a
+     * phantom session row in the mobile cache). Question cards are likewise never
+     * derived here: with no PTY there is nothing that could deliver an answer.
+     */
+    private broadcastExternalTailLines;
     private findConversationByUuid;
     private isConversationSnapshotStale;
     private handleGetConversation;
@@ -1136,6 +1362,7 @@ declare class StreamerServer {
     private handleResume;
     private enrichResumedSessionAsync;
     private handleSendInput;
+    private processJsonlQuestions;
     private cancelPendingQuestion;
     private handleLiveQuestion;
     private handlePermissionChange;
@@ -1148,6 +1375,7 @@ declare class StreamerServer {
     private handleStartSession;
     private linkSessionToProject;
     private watchConversationFile;
+    private readFirstLineSessionId;
     private watchForJsonl;
     private watchForCodexRollout;
     private handleBrowse;
@@ -1179,6 +1407,13 @@ interface ConversationWatcherEvents {
     onConversationChanged?: (filePath: string) => void | Promise<void>;
     /** Fires when a tailed file is deleted (per-file watcher unlink event). */
     onFileDeleted?: (filePath: string) => void;
+    /**
+     * Fires when a tailed file shrank below our read offset (in-place truncation
+     * or replacement by a shorter file). The tail has already reset to byte 0;
+     * the consumer must discard any byte-offset index built for the old content,
+     * which no longer describes this file.
+     */
+    onTruncated?: (filePath: string) => void;
     /** Reported errors per file. */
     onError?: (filePath: string, error: Error) => void;
 }
@@ -1201,6 +1436,7 @@ declare class ConversationWatcher {
     private onNewLineSpans;
     private onConversationChanged;
     private onFileDeleted;
+    private onTruncated;
     private onError;
     constructor(events?: ConversationWatcherEvents);
     watch(filePath: string): void;
@@ -1225,4 +1461,4 @@ declare class ConversationWatcher {
     private readNewLines;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type SessionCursor, type SessionListPage, type SessionListQuery, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, StreamerServer, type UserMessage, WSHub, type WSMessage, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, StreamerServer, type UserMessage, WSHub, type WSMessage, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };