@threadbase-sh/streamer 1.45.0 → 1.46.1

package/dist/index.d.cts

@@ -824,6 +824,22 @@ declare class ConversationCache {
         name: string;
         sessionCount: number;
     }>;
+    /** Every project with at least one cached conversation, most recently active
+     *  first. Paths are the raw `project_path` values, which is what
+     *  /api/conversations?project= matches on exactly — so a summary row is
+     *  always joinable against the page it describes. */
+    listProjectSummaries(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        projects: Array<{
+            path: string;
+            name: string;
+            conversationCount: number;
+            lastActivity: string;
+        }>;
+        total: number;
+    };
     private ensureFileIndex;
     updateFromLine(filePath: string, rawLine: string): void;
     /**
@@ -1689,6 +1705,7 @@ type ApiDeps = {
     handleSearchTarget: (id: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleListProjects: (url: URL, res: ServerResponse) => void;
     handleGetPopularProjects: (url: URL, res: ServerResponse) => void;
+    handleGetProjectSummaries: (url: URL, res: ServerResponse) => void;
     handlePairStart: (res: ServerResponse) => void;
     handlePairExchange: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleBrowse: (url: URL, res: ServerResponse) => Promise<void>;
@@ -2119,6 +2136,7 @@ declare class StreamerServer {
     private handleSessionsCount;
     private handleGetRecentSessions;
     private handleGetPopularProjects;
+    private handleGetProjectSummaries;
     private buildStatCache;
     private codexScanOpts;
     private newScanner;
@@ -2322,6 +2340,27 @@ declare class ConversationWatcher {
      * 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.
+     *
+     * **This costs one OS watch handle per file under `directory`, not one per
+     * directory.** chokidar recurses the tree and registers a separate fs.watch
+     * per entry, because a directory watch alone does not report writes to files
+     * inside it — and per-file `change` events are exactly what the caller needs
+     * (they drive poke()'s tail self-heal and the external-tail attach). So the
+     * handle count tracks the size of the conversation corpus on disk, not the
+     * number of live sessions, and it does not shrink until transcripts are
+     * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+     *
+     * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+     * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+     * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+     * there. **Linux is the tight one**: these are inotify watches billed to the
+     * per-user `max_user_watches`, which can be 8192 and is shared with every
+     * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+     * event — which is why server.ts wires onError rather than leaving it unset.
+     *
+     * Before trading handles for a bound here, note the regression it invites: a
+     * conversation excluded from the walk (by age or by an LRU cap) is one whose
+     * external appends produce no event at all, and that failure is silent.
      */
     watchDirectory(directory: string): void;
     unwatchDirectory(directory: string): void;

package/dist/index.d.ts

@@ -824,6 +824,22 @@ declare class ConversationCache {
         name: string;
         sessionCount: number;
     }>;
+    /** Every project with at least one cached conversation, most recently active
+     *  first. Paths are the raw `project_path` values, which is what
+     *  /api/conversations?project= matches on exactly — so a summary row is
+     *  always joinable against the page it describes. */
+    listProjectSummaries(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        projects: Array<{
+            path: string;
+            name: string;
+            conversationCount: number;
+            lastActivity: string;
+        }>;
+        total: number;
+    };
     private ensureFileIndex;
     updateFromLine(filePath: string, rawLine: string): void;
     /**
@@ -1689,6 +1705,7 @@ type ApiDeps = {
     handleSearchTarget: (id: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleListProjects: (url: URL, res: ServerResponse) => void;
     handleGetPopularProjects: (url: URL, res: ServerResponse) => void;
+    handleGetProjectSummaries: (url: URL, res: ServerResponse) => void;
     handlePairStart: (res: ServerResponse) => void;
     handlePairExchange: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleBrowse: (url: URL, res: ServerResponse) => Promise<void>;
@@ -2119,6 +2136,7 @@ declare class StreamerServer {
     private handleSessionsCount;
     private handleGetRecentSessions;
     private handleGetPopularProjects;
+    private handleGetProjectSummaries;
     private buildStatCache;
     private codexScanOpts;
     private newScanner;
@@ -2322,6 +2340,27 @@ declare class ConversationWatcher {
      * 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.
+     *
+     * **This costs one OS watch handle per file under `directory`, not one per
+     * directory.** chokidar recurses the tree and registers a separate fs.watch
+     * per entry, because a directory watch alone does not report writes to files
+     * inside it — and per-file `change` events are exactly what the caller needs
+     * (they drive poke()'s tail self-heal and the external-tail attach). So the
+     * handle count tracks the size of the conversation corpus on disk, not the
+     * number of live sessions, and it does not shrink until transcripts are
+     * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+     *
+     * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+     * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+     * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+     * there. **Linux is the tight one**: these are inotify watches billed to the
+     * per-user `max_user_watches`, which can be 8192 and is shared with every
+     * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+     * event — which is why server.ts wires onError rather than leaving it unset.
+     *
+     * Before trading handles for a bound here, note the regression it invites: a
+     * conversation excluded from the walk (by age or by an LRU cap) is one whose
+     * external appends produce no event at all, and that failure is silent.
      */
     watchDirectory(directory: string): void;
     unwatchDirectory(directory: string): void;

package/dist/index.js

@@ -5306,7 +5306,10 @@ var createMiscRoutes = (deps) => {
       // Same contract: this server serves GET /api/config/feature-flags. Lives
       // here rather than behind /api/config (admin-only) so a read-only client
       // still learns the server supports flags even if it can't read values.
-      featureFlags: true
+      featureFlags: true,
+      // Same contract: this server serves GET /api/projects/summary, which the
+      // Hub's grouped views need before they can draw a tree.
+      projectSummary: true
     });
   });
   app.get("/api/profiles", (c) => c.json([]));
@@ -5453,6 +5456,11 @@ var createProjectRoutes = (deps) => {
     deps.handleGetPopularProjects(url, c.env.outgoing);
     return alreadyHandled4();
   });
+  app.get("/summary", (c) => {
+    const url = new URL(c.req.url);
+    deps.handleGetProjectSummaries(url, c.env.outgoing);
+    return alreadyHandled4();
+  });
   return app;
 };
 
@@ -6320,6 +6328,21 @@ var ConversationCache = class _ConversationCache {
          ORDER BY cnt DESC
          LIMIT ?`
       ),
+      // Same table, same rows and same NULL filter /api/conversations lists
+      // from, so a group's count/last-activity can never disagree with the
+      // page it opens. Bare project_name is the one from the MAX(last_activity)
+      // row (SQLite's documented min/max-aggregate bare-column rule).
+      projectSummaries: db.prepare(
+        `SELECT project_path, project_name, COUNT(*) as cnt, MAX(last_activity) as latest
+         FROM conversation_meta
+         WHERE project_path IS NOT NULL
+         GROUP BY project_path
+         ORDER BY latest DESC, project_path ASC
+         LIMIT ? OFFSET ?`
+      ),
+      projectSummaryCount: db.prepare(
+        "SELECT COUNT(DISTINCT project_path) as n FROM conversation_meta WHERE project_path IS NOT NULL"
+      ),
       getFileState: db.prepare("SELECT * FROM conversation_file_state WHERE path = ?"),
       upsertFileState: db.prepare(
         `INSERT INTO conversation_file_state
@@ -6695,6 +6718,23 @@ var ConversationCache = class _ConversationCache {
       sessionCount: r.cnt
     }));
   }
+  /** Every project with at least one cached conversation, most recently active
+   *  first. Paths are the raw `project_path` values, which is what
+   *  /api/conversations?project= matches on exactly — so a summary row is
+   *  always joinable against the page it describes. */
+  listProjectSummaries(opts) {
+    const total = this.stmts.projectSummaryCount.get().n;
+    const rows = opts.limit === 0 ? [] : this.stmts.projectSummaries.all(opts.limit, opts.offset);
+    return {
+      total,
+      projects: rows.map((r) => ({
+        path: r.project_path,
+        name: r.project_name ?? r.project_path.split(/[/\\]/).pop() ?? r.project_path,
+        conversationCount: r.cnt,
+        lastActivity: new Date(r.latest ?? 0).toISOString()
+      }))
+    };
+  }
   ensureFileIndex() {
     if (this.fileIndexLoaded) return;
     const rows = this.stmts.allFilePaths.all();
@@ -8347,6 +8387,27 @@ var ConversationWatcher = class {
    * 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.
+   *
+   * **This costs one OS watch handle per file under `directory`, not one per
+   * directory.** chokidar recurses the tree and registers a separate fs.watch
+   * per entry, because a directory watch alone does not report writes to files
+   * inside it — and per-file `change` events are exactly what the caller needs
+   * (they drive poke()'s tail self-heal and the external-tail attach). So the
+   * handle count tracks the size of the conversation corpus on disk, not the
+   * number of live sessions, and it does not shrink until transcripts are
+   * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+   *
+   * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+   * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+   * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+   * there. **Linux is the tight one**: these are inotify watches billed to the
+   * per-user `max_user_watches`, which can be 8192 and is shared with every
+   * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+   * event — which is why server.ts wires onError rather than leaving it unset.
+   *
+   * Before trading handles for a bound here, note the regression it invites: a
+   * conversation excluded from the walk (by age or by an LRU cap) is one whose
+   * external appends produce no event at all, and that failure is silent.
    */
   watchDirectory(directory) {
     if (this.directories.has(directory)) return;
@@ -10643,6 +10704,13 @@ var StreamerServer = class {
             event: "cache.invalidate_on_unlink"
           });
         this.cacheMonitor?.recordUnlink(filePath);
+      },
+      onError: (filePath, err) => {
+        const enospc = err.code === "ENOSPC";
+        this.log.error(
+          enospc ? `Watcher hit the OS watch-handle limit on ${filePath} \u2014 raise fs.inotify.max_user_watches (Linux) or the process fd limit; conversation discovery and live tails are degraded until then` : `Watcher error on ${filePath}: ${err.message}`,
+          { filePath, err, event: enospc ? "watcher.limit_exhausted" : "watcher.error" }
+        );
       }
     });
     this.ptyManager = new LiveSessionManager({
@@ -10836,6 +10904,7 @@ var StreamerServer = class {
       handleSearchTarget: (id, req, res) => this.handleSearchTarget(id, req, res),
       handleListProjects: (url, res) => handleListProjects(url, res),
       handleGetPopularProjects: (url, res) => this.handleGetPopularProjects(url, res),
+      handleGetProjectSummaries: (url, res) => this.handleGetProjectSummaries(url, res),
       handlePairStart: (res) => this.handlePairStart(res),
       handlePairExchange: (req, res) => this.handlePairExchange(req, res),
       handleBrowse: (url, res) => this.handleBrowse(url, res),
@@ -12401,6 +12470,20 @@ var StreamerServer = class {
     const projects = this.cache.getPopularProjects(limit);
     json(res, 200, { projects, total: projects.length });
   }
+  handleGetProjectSummaries(url, res) {
+    if (this.rejectIfWarmingUp(res)) return;
+    const limit = intParam(url, "limit", 200);
+    const offset = intParam(url, "offset", 0);
+    if (!this.cache) {
+      json(res, 503, {
+        error: "Conversation cache unavailable",
+        code: "CACHE_UNAVAILABLE"
+      });
+      return;
+    }
+    const { projects, total } = this.cache.listProjectSummaries({ limit, offset });
+    json(res, 200, { projects, total, offset, hasMore: offset + projects.length < total });
+  }
   buildStatCache(previousScanner) {
     if (!this.cache) return void 0;
     if (!previousScanner) {