@threadbase-sh/streamer 1.15.0

package/dist/index.d.cts

@@ -0,0 +1,834 @@
+import { Client } from '@temporalio/client';
+import { UserInputSignal, Stage } from '@threadbase-sh/agent-types';
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+import { Logger as Logger$1 } from 'pino';
+import { HttpBindings } from '@hono/node-server';
+import { ServerResponse, IncomingMessage } from 'http';
+import { WebSocket } from 'ws';
+import Database from 'better-sqlite3';
+import { z } from 'zod';
+import { Pool } from 'pg';
+
+interface AgentClient {
+    startSession(sessionId: string): Promise<string>;
+    sendUserInput(sessionId: string, payload: UserInputSignal): Promise<void>;
+    endSession(sessionId: string): Promise<void>;
+    getSessionStage(sessionId: string): Promise<string>;
+}
+interface AgentClientOpts {
+    temporalClient: Client;
+    taskQueue: string;
+}
+declare function createAgentClient({ temporalClient, taskQueue }: AgentClientOpts): AgentClient;
+
+interface AgentConfig {
+    enabled: boolean;
+    temporal: {
+        address: string;
+        namespace: string;
+        taskQueue: string;
+    };
+    webhook: {
+        hmacSecret: string;
+        timestampSkewSeconds: number;
+    };
+    dedupe: {
+        perSessionCapacity: number;
+    };
+    payload: {
+        limitBytes: number;
+        trajectoryLogBytes: number;
+        trajectoryLogTurns: number;
+    };
+    sessionBusyRetryMs: number;
+    conversationsDir: string;
+}
+declare function readAgentConfig(env?: NodeJS.ProcessEnv): AgentConfig;
+
+interface AppendArgs {
+    sessionId: string;
+    turnId: string;
+    content: string;
+    reviewerOverruled?: boolean;
+}
+interface ConversationWriter {
+    appendAssistantTurn(args: AppendArgs): Promise<void>;
+}
+declare function createConversationWriter(opts: {
+    baseDir: string;
+}): ConversationWriter;
+
+interface ProgressDedupeLRU {
+    hasSeen(eventId: string): boolean;
+    readonly size: number;
+}
+declare function createProgressDedupeLRU(capacity: number): ProgressDedupeLRU;
+
+type LogDest = "console" | "pino" | "both";
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface Logger {
+    debug(msg: string, fields?: Record<string, unknown>, dest?: LogDest): void;
+    info(msg: string, fields?: Record<string, unknown>, dest?: LogDest): void;
+    warn(msg: string, fields?: Record<string, unknown>, dest?: LogDest): void;
+    error(msg: string, fields?: Record<string, unknown>, dest?: LogDest): void;
+    log(level: LogLevel, msg: string, fields?: Record<string, unknown>, dest?: LogDest): void;
+    pino: Logger$1;
+}
+
+type SessionStatus = "running" | "waiting_input" | "idle";
+interface ManagedSession {
+    id: string;
+    projectId?: string;
+    projectPath: string;
+    projectName: string;
+    branch: string;
+    status: SessionStatus;
+    startedAt: Date;
+    completedAt: Date | null;
+    promptCount: number;
+    lastOutput: string;
+    failureReason?: string;
+    sessionName?: string;
+    model?: string;
+    account?: string;
+    messageCount?: number;
+    preview?: string;
+    firstMessageText?: string;
+    firstMessageAt?: Date;
+    lastMessageText?: string;
+    lastMessageAt?: Date;
+    lastActivityAt?: Date;
+    filePath?: string;
+    resumedFromConversationId?: string;
+    /**
+     * Multi-agent mode only. Per-session in-memory LRU of progress event ids
+     * seen by the webhook receiver. Used to drop Temporal-replay duplicates
+     * before they reach the WebSocket. See spec §7.1.
+     */
+    progressDedupeIds?: ProgressDedupeLRU;
+    /** Multi-agent: current stage of the active turn (advisory; advisory wire field). */
+    stage?: Stage | string;
+    /** Multi-agent: ms since the session last emitted a stage transition. */
+    stalledSinceMs?: number;
+    /** Multi-agent: 1 or 2 when stage === "rework". */
+    reworkAttempt?: number;
+    /**
+     * Multi-agent: id of the in-flight turn, or null when idle. Set when
+     * `POST /api/sessions/:id/input` accepts a request; cleared by the webhook
+     * receiver on stage=done or terminal_failure. Undefined in PTY mode.
+     */
+    currentTurnId?: string | null;
+    /**
+     * Multi-agent resume: stable identity of the underlying conversation
+     * (the JSONL filename), distinct from `id` which is per-orchestrator-instance.
+     * Undefined in PTY mode (PTY uses `resumedFromConversationId` instead).
+     */
+    conversationId?: string;
+}
+interface DiscoveredProcess {
+    pid: number;
+    projectPath: string;
+    projectName: string;
+    branch: string;
+    conversationId: string | null;
+    startedAt: Date;
+}
+type WSMessage = {
+    type: "terminal_output";
+    sessionId: string;
+    data: string;
+} | {
+    type: "session_update";
+    session?: SessionResponse;
+    sessionId?: string;
+    turnId?: string;
+    stage?: Stage | string;
+    stalledSinceMs?: number;
+    reworkAttempt?: number;
+} | {
+    type: "session_list";
+    sessions: SessionResponse[];
+} | {
+    type: "conversation_event";
+    sessionId: string;
+    line: string;
+} | {
+    type: "conversation_events";
+    sessionId: string;
+    lines: string[];
+} | {
+    type: "ping";
+    ts: number;
+} | {
+    type: "terminal_replay";
+    sessionId: string;
+    lines: string[];
+} | {
+    type: "session_ready";
+    session: SessionResponse;
+} | {
+    type: "agent_output";
+    sessionId: string;
+    turnId: string;
+    role: "worker" | "reviewer" | "signoff";
+    content: string;
+    partial?: boolean;
+    reviewerOverruled?: boolean;
+    stage?: Stage | string;
+    reworkAttempt?: number;
+} | {
+    type: "turn_failure";
+    sessionId: string;
+    turnId: string;
+    reason: string;
+} | {
+    type: "cache_ready";
+} | {
+    type: "scan_progress";
+    scanned: number;
+    total: number;
+};
+interface SessionResponse {
+    id: string;
+    conversationId: string;
+    projectId?: string;
+    status: SessionStatus;
+    projectPath: string;
+    projectName: string;
+    branch: string;
+    lastOutput: string;
+    elapsedMs: number;
+    promptCount: number;
+    startedAt: string;
+    completedAt: string | null;
+    ptyAttached: boolean;
+    failureReason?: string;
+    pid?: number;
+    sessionName?: string;
+    model?: string;
+    account?: string;
+    messageCount?: number;
+    preview?: string;
+    firstMessageText?: string;
+    firstMessageAt?: string;
+    lastMessageText?: string;
+    lastMessageAt?: string;
+    lastActivityAt?: string;
+    filePath?: string;
+    resumedFromConversationId?: string;
+}
+interface ConversationListResponse {
+    conversations: unknown[];
+    hasMore: boolean;
+    offset: number;
+    total: number;
+}
+type SessionSortKey = "startedAt" | "lastActivityAt" | "projectName" | "status";
+type SortOrder = "asc" | "desc";
+interface SessionListPage {
+    sessions: SessionResponse[];
+    nextCursor: string | null;
+    total: number;
+}
+interface SessionListQuery {
+    limit: number;
+    cursor?: string;
+    sortBy: SessionSortKey;
+    order: SortOrder;
+    status?: SessionStatus[];
+}
+interface SessionCursor {
+    k: string | number;
+    id: string;
+}
+interface ServerConfig {
+    port: number;
+    apiKey?: string;
+    localNoAuth?: boolean;
+    verbose?: boolean;
+    browseRoot?: string;
+    publicUrl?: string;
+    disableDb?: boolean;
+    scanProfiles?: Array<{
+        id: string;
+        label: string;
+        configDir: string;
+        enabled: boolean;
+        emoji: string;
+    }>;
+    ptyGracePeriodMs?: number;
+    cacheDir?: string;
+    tailSize?: number;
+    directoryScanDebounceMs?: number;
+}
+interface PTYManagerOptions {
+    onOutput?: (sessionId: string, data: string) => void;
+    onStatusChange?: (session: ManagedSession) => void;
+    onReady?: (session: ManagedSession) => void;
+    logger?: Logger;
+}
+interface StartSessionOptions {
+    projectPath: string;
+    projectName?: string;
+    branch?: string;
+}
+interface StartFreshSessionOptions {
+    projectPath: string;
+    projectName?: string;
+    systemPrompt?: string;
+}
+
+interface ConversationCacheOptions {
+    filterAgentConversations?: boolean;
+    agentEntrypoints?: ReadonlySet<string>;
+    onAgentFileDetected?: (filePath: string) => void;
+}
+interface ConversationListItem {
+    id: string;
+    filePath: string;
+    projectId: string | null;
+    projectPath: string | null;
+    projectName: string | null;
+    title: string | null;
+    model: string | null;
+    account: string | null;
+    branch: string | null;
+    messageCount: number;
+    lastActivity: string;
+    firstMessage: string | null;
+    lastMessage: string | null;
+    preview: string | null;
+    source: string | null;
+}
+interface CachedTailMessage {
+    role: string;
+    timestamp: string;
+    text: string;
+    content?: unknown[];
+}
+interface CachedTail {
+    conversationId: string;
+    messages: CachedTailMessage[];
+    tailSize: number;
+}
+interface ScannerMeta {
+    id: string;
+    sessionId?: string;
+    filePath: string;
+    projectPath?: string;
+    projectName?: string;
+    title?: string;
+    model?: string;
+    account?: string;
+    gitBranch?: string;
+    messageCount?: number;
+    timestamp?: string;
+    firstMessage?: unknown;
+    lastMessage?: unknown;
+    preview?: string;
+}
+declare class ConversationCache {
+    private db;
+    private tailSize;
+    private fileIndex;
+    private fileIndexLoaded;
+    private tailSeq;
+    private nameSeq;
+    private stmts;
+    private migrationsDir?;
+    private filterAgentConversations;
+    private agentEntrypoints;
+    private onAgentFileDetected?;
+    private constructor();
+    /**
+     * Expose the underlying handle so projects/cache_metadata repositories can
+     * share the same connection. Internal API; not part of the public surface.
+     */
+    getDatabase(): Database.Database;
+    getAgentEntrypoints(): ReadonlySet<string>;
+    static open(dbPath: string, tailSize?: number, migrationsDir?: string, options?: ConversationCacheOptions): ConversationCache;
+    close(): void;
+    getPopularProjects(limit: number): Array<{
+        path: string;
+        name: string;
+        sessionCount: number;
+    }>;
+    private ensureFileIndex;
+    updateFromLine(filePath: string, rawLine: string): void;
+    /**
+     * Batched form of updateFromLine: applies a burst of newly-appended lines
+     * (one chokidar read) in a single transaction with one message_count bump,
+     * one meta write, and one tail read/write — instead of 2-4 synchronous
+     * writes per line. Semantics are identical to replaying each line through
+     * 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.
+     */
+    updateFromLines(filePath: string, rawLines: string[]): void;
+    upsertFromScannerMeta(metas: ScannerMeta[]): string[];
+    deleteByFilePath(filePath: string): boolean;
+    populateTailFromFile(convId: string, filePath: string): boolean;
+    listConversations(opts: {
+        project?: string;
+        limit: number;
+        offset: number;
+    }): {
+        conversations: ConversationListItem[];
+        total: number;
+    };
+    /** Returns a map of filePath → { mtimeMs, size } for all rows that have
+     *  stat data stored. Used by the server to build the statCache passed to
+     *  ConversationScanner.scan() so unchanged files are skipped. */
+    getFileStats(): Map<string, {
+        mtimeMs: number;
+        size: number;
+    }>;
+    getMetaById(id: string): ConversationListItem | null;
+    setConversationProjectId(conversationId: string, projectId: string): void;
+    markAsStreamer(id: string): void;
+    getLatestConversation(): {
+        id: string;
+        lastActivity: string | null;
+    } | null;
+    hasOrphanProjectId(): boolean;
+    listConversationsForProjectBackfill(): Array<{
+        id: string;
+        projectPath: string | null;
+        projectId: string | null;
+        lastActivity: string | null;
+    }>;
+    getConversationTail(id: string): CachedTail | null;
+    hasConversation(id: string): boolean;
+    upsertSessionName(sessionId: string, name: string): void;
+    getSessionName(sessionId: string): string | null;
+    listSessionNames(): Record<string, string>;
+    invalidate(id?: string): void;
+    invalidateByFilePath(filePath: string): string | null;
+    /**
+     * Drop rows whose `file_path` no longer exists on disk AND which have no
+     * cached tail to fall back to. Rows with a tail are left alone so
+     * `handleGetConversation` can still serve the cached tail even when the
+     * JSONL has been deleted.
+     */
+    pruneGhostFiles(exists?: (filePath: string) => boolean): string[];
+}
+
+type CacheMetadataKey = "last_conversation_id" | "last_conversation_created_at" | "projects_last_indexed_at" | "conversations_last_indexed_at" | "conversations_dirty";
+declare class CacheMetadataRepository {
+    private get;
+    private upsert;
+    private del;
+    constructor(db: Database.Database);
+    getCacheMetadata(key: CacheMetadataKey): string | null;
+    setCacheMetadata(key: CacheMetadataKey, value: string): void;
+    deleteCacheMetadata(key: CacheMetadataKey): void;
+}
+
+/**
+ * Thin repository wrapper around ConversationCache for the project-id flow.
+ * The cache is the source of truth for conversation rows; this just exposes
+ * a stable, repo-style API for services that don't want to know about the
+ * cache class directly.
+ */
+declare class ConversationsRepository {
+    private cache;
+    constructor(cache: ConversationCache);
+    updateConversationProjectId(args: {
+        conversationId: string;
+        projectId: string;
+    }): void;
+    listConversationsForProjectBackfill(): {
+        id: string;
+        projectPath: string | null;
+        projectId: string | null;
+        lastActivity: string | null;
+    }[];
+    getLatestConversation(): {
+        id: string;
+        lastActivity: string | null;
+    } | null;
+    hasOrphanRows(): boolean;
+}
+
+/**
+ * Persisted Project row. Mirrors the projects SQLite table.
+ */
+declare const ProjectSchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lastConversationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lastConversationCreatedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lastIndexedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    latestMessageAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    latestMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    messageCount: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+type Project = z.infer<typeof ProjectSchema>;
+
+interface UpsertProjectInput {
+    lastConversationId?: string | null;
+    lastConversationCreatedAt?: string | null;
+    latestMessageAt?: string | null;
+    latestMessageId?: string | null;
+    name?: string | null;
+}
+declare class ProjectsRepository {
+    private getByPath;
+    private getById;
+    private listAll;
+    private insert;
+    private update;
+    constructor(db: Database.Database);
+    getProjectByPath(rawPath: string): Project | null;
+    getProjectById(id: string): Project | null;
+    listProjects(): Project[];
+    /**
+     * Insert a project at the given canonical path, or update its metadata
+     * if one already exists. Returns the persisted Project row.
+     *
+     * Idempotent: passing the same path twice returns the same project id.
+     */
+    upsertProjectByPath(rawPath: string, input?: UpsertProjectInput): Project;
+}
+
+declare class SessionStore {
+    private managed;
+    private discovered;
+    addManaged(session: ManagedSession): void;
+    /**
+     * Multi-agent mode only. Attach a dedupe LRU to a session record. Idempotent —
+     * calling twice keeps the existing LRU (and its contents).
+     */
+    initAgentSession(sessionId: string, dedupeCapacity: number): void;
+    updateManaged(sessionId: string, updates: Partial<ManagedSession>): ManagedSession | null;
+    removeManaged(sessionId: string): boolean;
+    getManaged(sessionId: string): ManagedSession | null;
+    setDiscovered(processes: DiscoveredProcess[]): void;
+    listManaged(): ManagedSession[];
+    list(ptyAttachedIds: Set<string>): SessionResponse[];
+    get(sessionId: string, ptyAttachedIds: Set<string>): SessionResponse | null;
+    paginate(ptyAttachedIds: Set<string>, query: SessionListQuery): SessionListPage;
+}
+
+/**
+ * Sessions live in-memory in SessionStore (Postgres-backed persistence
+ * was dropped per the SQLite-only direction). This repository wraps the
+ * store with a stable, project-id-aware API for the new services.
+ */
+declare class SessionsRepository {
+    private store;
+    constructor(store: SessionStore);
+    updateSessionProjectId(args: {
+        sessionId: string;
+        projectId: string;
+    }): void;
+    listManagedSessions(): ManagedSession[];
+}
+
+declare class PTYManager {
+    private sessions;
+    private onOutput;
+    private onStatusChange;
+    private onReady;
+    private pendingReady;
+    private queuedInputs;
+    private log;
+    private firstChunkAt;
+    private chunkIndex;
+    private lastChunkAt;
+    constructor(options?: PTYManagerOptions);
+    start(sessionId: string, options: StartSessionOptions): Promise<ManagedSession>;
+    startFresh(options: StartFreshSessionOptions): Promise<ManagedSession>;
+    sendKeys(sessionId: string, keys: string): void;
+    sendInput(sessionId: string, input: string): number;
+    private writeSubmit;
+    private flushQueuedInputs;
+    cancel(sessionId: string): void;
+    killPid(pid: number): void;
+    putOnHold(sessionId: string): void;
+    getOutput(sessionId: string): string;
+    getOutputLines(sessionId: string, maxLines: number): Promise<string[]>;
+    getSession(sessionId: string): ManagedSession | null;
+    hasSession(sessionId: string): boolean;
+    listSessions(): ManagedSession[];
+    dispose(): void;
+    private handleOutput;
+    private markReady;
+    private handleExit;
+}
+
+declare class WSHub {
+    private clients;
+    private pingTimer;
+    private pongTimers;
+    addClient(ws: WebSocket): void;
+    broadcast(message: WSMessage): void;
+    unicast(ws: WebSocket, message: WSMessage): void;
+    get connectionCount(): number;
+    dispose(): void;
+    private startPing;
+}
+
+type ApiDeps = {
+    apiKey: string;
+    localNoAuth: boolean;
+    publicUrl: string | null;
+    browseRoot: string | null;
+    ptyManager: PTYManager;
+    sessionStore: SessionStore;
+    wsHub: WSHub;
+    cache: () => ConversationCache | null;
+    projectsRepo: () => ProjectsRepository | null;
+    conversationsRepo: () => ConversationsRepository | null;
+    sessionsRepo: () => SessionsRepository | null;
+    cacheMetadataRepo: () => CacheMetadataRepository | null;
+    ptyAttachedIds: () => Set<string>;
+    handleListSessions: (url: URL, res: ServerResponse) => Promise<void>;
+    handleSessionsCount: (res: ServerResponse) => void;
+    handleGetRecentSessions: (url: URL, res: ServerResponse) => void;
+    handleGetSessionNames: (res: ServerResponse) => void;
+    handleGetSession: (sessionId: string, res: ServerResponse) => void;
+    handleGetOutput: (sessionId: string, res: ServerResponse) => void;
+    handleSendInput: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleCancel: (sessionId: string, res: ServerResponse) => void;
+    handleSetSessionName: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleUploadFile: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleAdopt: (sessionId: string, res: ServerResponse) => Promise<void>;
+    handleResume: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleStartSession: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleListConversations: (url: URL, res: ServerResponse) => Promise<void>;
+    handleConversationsCount: (url: URL, res: ServerResponse) => Promise<void>;
+    handleGetConversation: (id: string, url: URL, res: ServerResponse, ifNoneMatch?: string) => Promise<void>;
+    handleSearch: (url: URL, res: ServerResponse) => Promise<void>;
+    handleGetPopularProjects: (url: URL, res: ServerResponse) => void;
+    handleListProjectChats: (url: URL, res: ServerResponse) => Promise<void>;
+    handlePairStart: (res: ServerResponse) => void;
+    handlePairExchange: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleBrowse: (url: URL, res: ServerResponse) => Promise<void>;
+    handleMkdir: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    handleWsOpen: (ws: WebSocket) => void;
+    handleWsMessage: (ws: WebSocket, raw: unknown) => void;
+    handleWsClose: (ws: WebSocket) => void;
+    agentClient: AgentClient | null;
+    conversationWriter: ConversationWriter | null;
+    agentConfig: AgentConfig;
+};
+
+type AppEnv = {
+    Bindings: HttpBindings;
+    Variables: {
+        requestId?: string;
+        validatedBody?: unknown;
+        validatedQuery?: unknown;
+    };
+};
+
+interface AgentDeps {
+    sessionStore: {
+        getManaged: (sessionId: string) => {
+            id: string;
+            progressDedupeIds?: {
+                hasSeen: (id: string) => boolean;
+            };
+            currentTurnId?: string | null;
+        } | null;
+    };
+    wsHub: {
+        broadcast: (m: WSMessage) => void;
+    };
+    conversationWriter: {
+        appendAssistantTurn: (a: {
+            sessionId: string;
+            turnId: string;
+            content: string;
+            reviewerOverruled?: boolean;
+        }) => Promise<void>;
+    } | null;
+    agentConfig: {
+        enabled: boolean;
+        webhook: {
+            hmacSecret: string;
+            timestampSkewSeconds: number;
+        };
+        dedupe: {
+            perSessionCapacity: number;
+        };
+    };
+}
+declare const createProgressRoutes: (deps: ApiDeps & AgentDeps) => Hono<AppEnv, hono_types.BlankSchema, "/">;
+
+declare function generateApiKey(): string;
+declare function validateApiKey(provided: string, expected: string): boolean;
+declare function loadOrCreateApiKey(): string;
+
+interface DbConfig {
+    connectionString: string;
+    max: number;
+    ssl?: string;
+    statementTimeout?: number;
+    instanceId: string;
+}
+declare function isDbEnabled(): boolean;
+declare function getDbConfig(): DbConfig | null;
+
+declare function maskConnectionString(url: string): string;
+declare function createPool(config: DbConfig): Promise<Pool>;
+
+declare function discoverClaudeProcesses(): Promise<DiscoveredProcess[]>;
+
+declare class StreamerServer {
+    private httpServer;
+    private ptyManager;
+    private sessionStore;
+    private wsHub;
+    private fileWatcher;
+    private sessionFileMap;
+    private scanner;
+    private scannerReady;
+    private scannerStale;
+    private binding;
+    private cacheReady;
+    private apiKey;
+    private localNoAuth;
+    private verbose;
+    private scanProfiles;
+    private dbPool;
+    private dbInstanceId;
+    private disableDb;
+    private browseRoot;
+    private publicUrl;
+    private pairTokens;
+    private exchangeAttempts;
+    private ptyGracePeriodMs;
+    private ptyGraceTimers;
+    private sessionSubscribers;
+    private clientIdToWs;
+    private wsToClientId;
+    private cache;
+    private projectsRepo;
+    private conversationsRepo;
+    private sessionsRepo;
+    private cacheMetadataRepo;
+    private discoveryCache;
+    private cacheDir;
+    private tailSize;
+    private directoryDebounceMs;
+    private markScannerStaleDebounced;
+    private includeAgents;
+    private agentEntrypoints;
+    private honoApp;
+    private log;
+    private agentConfig;
+    private agentClient;
+    constructor(config: ServerConfig & {
+        apiKey: string;
+    });
+    private ptyAttachedIds;
+    /**
+     * 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
+     * a full broadcast if no match exists (old clients, or no WS registered yet).
+     */
+    private broadcastOrUnicastSessionList;
+    private addSessionSubscriber;
+    private startGraceTimer;
+    get port(): number;
+    listen(port: number, opts?: {
+        awaitReady?: boolean;
+    }): Promise<void>;
+    private bindWithRetry;
+    private bindWithRetryLoop;
+    close(): Promise<void>;
+    private handleRequest;
+    private handlePairStart;
+    private handlePairExchange;
+    private checkExchangeRateLimit;
+    private handleListConversations;
+    private handleConversationsCount;
+    private handleSessionsCount;
+    private handleGetRecentSessions;
+    private handleGetPopularProjects;
+    private handleListProjectChats;
+    private buildStatCache;
+    private getScanner;
+    private getFreshScanner;
+    private findJsonlPath;
+    private readCwdFromJsonl;
+    private findConversationByUuid;
+    private isConversationSnapshotStale;
+    private handleGetConversation;
+    private handleSearch;
+    private handleListSessions;
+    private handleGetSession;
+    private handleResume;
+    private handleSendInput;
+    private handleUploadFile;
+    private handleGetOutput;
+    private handleCancel;
+    private handleAdopt;
+    private handleStartSession;
+    private linkSessionToProject;
+    private watchConversationFile;
+    private watchForJsonl;
+    private handleBrowse;
+    private handleMkdir;
+    private handleSetSessionName;
+    private handleGetSessionNames;
+}
+
+interface ConversationWatcherEvents {
+    /** Fires once per new newline-terminated line appended to a watched file. */
+    onNewLine?: (filePath: string, line: string) => void;
+    /**
+     * Fires once per chokidar read with ALL new lines from that read, batched.
+     * When set, it REPLACES the per-line onNewLine dispatch for that file —
+     * callers pick one. Lets a burst of appended lines collapse into a single
+     * downstream cache write + WebSocket broadcast.
+     */
+    onNewLines?: (filePath: string, lines: string[]) => void;
+    /** Fires when chokidar reports an add/change/unlink at the directory level. */
+    onConversationChanged?: (filePath: string) => void | Promise<void>;
+    /** Fires when a tailed file is deleted (per-file watcher unlink event). */
+    onFileDeleted?: (filePath: string) => void;
+    /** Reported errors per file. */
+    onError?: (filePath: string, error: Error) => void;
+}
+/**
+ * Chokidar-backed replacement for src/file-watcher.ts.
+ *
+ *   - watch(filePath)      → tail a single JSONL file, emitting onNewLine
+ *                            for each appended line.
+ *   - watchDirectory(dir)  → mark cache dirty on add/change/unlink events
+ *                            for any file inside the directory.
+ *
+ * Per the refactor plan, file watching is an OPTIMIZATION; correctness
+ * still relies on refresh=1 / the latest HDD conversation id check.
+ */
+declare class ConversationWatcher {
+    private files;
+    private directories;
+    private onNewLine;
+    private onNewLines;
+    private onConversationChanged;
+    private onFileDeleted;
+    private onError;
+    constructor(events?: ConversationWatcherEvents);
+    watch(filePath: string): void;
+    unwatch(filePath: string): void;
+    /**
+     * Watch a directory of conversation JSONL files. Fires
+     * onConversationChanged for any add/change/unlink event so the caller
+     * can mark the cache dirty without scanning everything immediately.
+     */
+    watchDirectory(directory: string): void;
+    unwatchDirectory(directory: string): void;
+    dispose(): void;
+    private readNewLines;
+}
+
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, type ManagedSession, PTYManager, type PTYManagerOptions, type ProgressDedupeLRU, type ServerConfig, type SessionCursor, type SessionListPage, type SessionListQuery, type SessionResponse, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, StreamerServer, WSHub, type WSMessage, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };