@ai-matrx/coding-sessions 0.1.166 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ai-matrx/coding-sessions
 
+## 0.2.0
+
+- **`./sessions` (new, pure):** the one title rule for a coding chat — `resolveSessionTitle` (override >
+  app record > remembered app title > custom-title > ai-title > agent-name > summary > first prompt >
+  last prompt), `cleanTitle` (first non-empty line, 300 chars), `isBridgePlaceholder` (the bridge's old
+  `AI Matrx · <source>` stamp is never a title), `claudeTranscriptTitleSources`, and the `TitleHints`
+  port through which the owner of the apps' index (Matrx 2's core) supplies the apps' own titles,
+  archived / scheduled flags and chats whose file is gone. Vectors: `fixtures/title-precedence.json`.
+- Discovery and search titles come from that rule (no more 140-char flattening); Codex archived
+  rollouts (`archived_sessions/`) are read and marked `archived`; every Codex home in `homes.codex`.
+- Engine option `titleHints`: discovery overlays the apps' titles without waiting (`titlePending`
+  meanwhile, a `titles` event when they land), lists the app's chats whose file is gone as
+  `unavailable`, and the engine's own sessions show the app's title once known.
+- Screen: "titles updating" beside Your other chats; archived chats and scheduled runs hidden by
+  default behind Show hidden chats (a pin shows them); "file missing" rows. A rename made before the
+  provider id is known moves to the chat's lasting key; renames are cut at 300 (was 200).
+- **Consumer action:** `ProviderHomes` is now `{ claudeProjects, codex: CodexHome[] }` (was
+  `codexSessions` / `codexIndex`); build one with `codexHome(dir)`. Hosts that own an apps index pass
+  `titleHints`.
+
 ## 0.1.166
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/engine/index.cjs

@@ -38,9 +38,11 @@ __export(engine_exports, {
   buildCleanEnv: () => buildCleanEnv,
   claudeDefaults: () => claudeDefaults,
   codexDefaults: () => codexDefaults,
+  codexHome: () => codexHome,
   createAiMatrxRawBackupSink: () => createAiMatrxRawBackupSink,
   createCodingSessionsEngine: () => createCodingSessionsEngine,
   createRawBackupScheduler: () => createRawBackupScheduler,
+  createTitleHintsStore: () => createTitleHintsStore,
   defaultProviderHomes: () => defaultProviderHomes,
   describeActivity: () => describeActivity,
   describeProviderStatus: () => describeProviderStatus,
@@ -53,7 +55,8 @@ __export(engine_exports, {
   readSessionFile: () => readSessionFile,
   searchLocalChats: () => searchLocalChats,
   sessionActivity: () => sessionActivity,
-  snippetAround: () => snippetAround
+  snippetAround: () => snippetAround,
+  titleHintKey: () => titleHintKey
 });
 module.exports = __toCommonJS(engine_exports);
 
@@ -1196,6 +1199,9 @@ var PROVIDER_LABEL = {
   claude: "Claude Code",
   codex: "Codex"
 };
+function chatKey(provider, providerSessionId, sessionId) {
+  return providerSessionId ? `${provider}:${providerSessionId}` : `session:${sessionId ?? ""}`;
+}
 var TERMINAL_RUN_STATUSES = ["completed", "stopped", "failed"];
 function isTerminalRunStatus(status) {
   return TERMINAL_RUN_STATUSES.includes(status);
@@ -1510,6 +1516,78 @@ var import_promises4 = __toESM(require("fs/promises"), 1);
 var import_node_os3 = __toESM(require("os"), 1);
 var import_node_path5 = __toESM(require("path"), 1);
 
+// src/sessions/titles.ts
+var TITLE_MAX = 300;
+var BRIDGE_PLACEHOLDER = /^AI Matrx · [a-z-]+$/;
+var TITLE_PRECEDENCE = [
+  /** The person's rename inside Matrx (Coding Sessions' preference). */
+  "override",
+  /** What the coding app's own sidebar shows: Claude's record `title` (renames included); Codex's thread name; Cursor's name. */
+  "app",
+  /** The title the app last showed, remembered by the claude-accounts engine after the record went away. */
+  "app-remembered",
+  /** Claude Code transcript entries (the last one of each kind that is not the bridge placeholder). */
+  "custom-title",
+  "ai-title",
+  "agent-name",
+  "summary",
+  /** The person's first typed message (Codex: the thread's title / first user message). */
+  "first-prompt",
+  "last-prompt"
+];
+var STAMPABLE = /* @__PURE__ */ new Set(["custom-title", "ai-title", "agent-name"]);
+function isBridgePlaceholder(value) {
+  return typeof value === "string" && BRIDGE_PLACEHOLDER.test(value.trim());
+}
+function cleanTitle(value) {
+  if (typeof value !== "string") return null;
+  const line = value.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0);
+  if (!line) return null;
+  return line.length > TITLE_MAX ? `${line.slice(0, TITLE_MAX - 1)}\u2026` : line;
+}
+function resolveSessionTitle(sources) {
+  for (const source of TITLE_PRECEDENCE) {
+    const raw = sources[source];
+    if (STAMPABLE.has(source) && isBridgePlaceholder(raw)) continue;
+    const title = cleanTitle(raw);
+    if (title) return { title, source };
+  }
+  return null;
+}
+function claudeTranscriptTitleSources(head, tail = []) {
+  const out = {};
+  const take = (source, value) => {
+    if (typeof value !== "string" || !value.trim()) return;
+    if (STAMPABLE.has(source) && isBridgePlaceholder(value)) return;
+    out[source] = value;
+  };
+  const normalizer = createClaudeNormalizer();
+  let firstPrompt = null;
+  const scan = (entries, findPrompt) => {
+    for (const entry of entries) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const e = entry;
+      if (e.type === "custom-title") take("custom-title", e.customTitle);
+      else if (e.type === "ai-title") take("ai-title", e.aiTitle);
+      else if (e.type === "agent-name") take("agent-name", e.agentName);
+      else if (e.type === "summary") take("summary", e.summary);
+      else if (e.type === "last-prompt") take("last-prompt", e.lastPrompt);
+      else if (findPrompt && firstPrompt === null) {
+        for (const item of normalizer.push(entry)) {
+          if (item.kind === "user" && item.text.trim()) {
+            firstPrompt = item.text;
+            break;
+          }
+        }
+      }
+    }
+  };
+  scan(head, true);
+  scan(tail, false);
+  if (firstPrompt !== null) out["first-prompt"] = firstPrompt;
+  return out;
+}
+
 // src/engine/activity.ts
 var import_node_child_process2 = require("child_process");
 var RECENT_WRITE_MS = 2 * 60 * 1e3;
@@ -1575,11 +1653,17 @@ function describeActivity(input) {
 }
 
 // src/engine/files.ts
+function codexHome(dir) {
+  return {
+    sessions: import_node_path5.default.join(dir, "sessions"),
+    archived: import_node_path5.default.join(dir, "archived_sessions"),
+    index: import_node_path5.default.join(dir, "session_index.jsonl")
+  };
+}
 function defaultProviderHomes(home = import_node_os3.default.homedir()) {
   return {
     claudeProjects: import_node_path5.default.join(home, ".claude", "projects"),
-    codexSessions: import_node_path5.default.join(home, ".codex", "sessions"),
-    codexIndex: import_node_path5.default.join(home, ".codex", "session_index.jsonl")
+    codex: [codexHome(import_node_path5.default.join(home, ".codex"))]
   };
 }
 var UUIDISH = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
@@ -1613,7 +1697,7 @@ async function claudeCandidates(root) {
   }
   return out;
 }
-async function codexCandidates(root) {
+async function codexTree(root) {
   const out = [];
   for (const year of await safeReaddir(root)) {
     if (!year.isDirectory()) continue;
@@ -1621,17 +1705,23 @@ async function codexCandidates(root) {
       if (!month.isDirectory()) continue;
       for (const day of await safeReaddir(import_node_path5.default.join(root, year.name, month.name))) {
         if (!day.isDirectory()) continue;
-        const dir = import_node_path5.default.join(root, year.name, month.name, day.name);
-        const entries = await safeReaddir(dir);
-        const stats = await Promise.all(
-          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", import_node_path5.default.join(dir, e.name)))
-        );
-        for (const s of stats) if (s) out.push(s);
+        out.push(...await codexFlat(import_node_path5.default.join(root, year.name, month.name, day.name), false));
       }
     }
   }
   return out;
 }
+async function codexFlat(dir, archived) {
+  const entries = await safeReaddir(dir);
+  const stats = await Promise.all(
+    entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", import_node_path5.default.join(dir, e.name)))
+  );
+  return stats.filter((s) => s !== null).map((s) => archived ? { ...s, archived: true } : s);
+}
+async function codexCandidates(homes) {
+  const lists = await Promise.all(homes.flatMap((h) => [codexTree(h.sessions), codexFlat(h.archived, true)]));
+  return lists.flat();
+}
 async function readSlice(file, start, length) {
   const handle = await import_promises4.default.open(file, "r");
   try {
@@ -1653,56 +1743,38 @@ function completeLines(text, droppedFirst) {
 }
 var HEAD_BYTES = 256 * 1024;
 var TAIL_BYTES = 128 * 1024;
-function oneLine(text, max = 140) {
-  const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
-}
 async function describeClaude(candidate) {
   const head = parseJsonl(completeLines(await readSlice(candidate.file, 0, HEAD_BYTES), false));
   const tailStart = Math.max(0, candidate.size - TAIL_BYTES);
   const tail = tailStart > 0 ? parseJsonl(completeLines(await readSlice(candidate.file, tailStart, TAIL_BYTES), true)) : head;
   let cwd = null;
-  let firstPrompt = null;
   let entrypoint = null;
-  const normalizer = createClaudeNormalizer();
   for (const entry of head) {
     if (typeof entry !== "object" || entry === null) continue;
     const e = entry;
     if (!cwd && typeof e.cwd === "string") cwd = e.cwd;
     if (!entrypoint && typeof e.entrypoint === "string") entrypoint = e.entrypoint;
-    if (firstPrompt === null) {
-      for (const item of normalizer.push(entry)) {
-        if (item.kind === "user") {
-          firstPrompt = item.text;
-          break;
-        }
-      }
-    }
-    if (cwd && firstPrompt !== null) break;
+    if (cwd && entrypoint) break;
   }
-  const titles = { custom: null, ai: null, agent: null, summary: null, last: null };
-  for (const entry of [...head, ...tail]) {
-    if (typeof entry !== "object" || entry === null) continue;
-    const e = entry;
-    if (e.type === "custom-title" && typeof e.customTitle === "string") titles.custom = e.customTitle;
-    if (e.type === "ai-title" && typeof e.aiTitle === "string") titles.ai = e.aiTitle;
-    if (e.type === "agent-name" && typeof e.agentName === "string") titles.agent = e.agentName;
-    if (e.type === "summary" && typeof e.summary === "string") titles.summary = e.summary;
-    if (e.type === "last-prompt" && typeof e.lastPrompt === "string") titles.last = e.lastPrompt;
-  }
-  const title = titles.custom ?? titles.ai ?? titles.agent ?? titles.summary ?? firstPrompt ?? titles.last;
-  if (!title) return null;
+  const resolved = resolveSessionTitle(claudeTranscriptTitleSources(head, tailStart > 0 ? tail : []));
+  if (!resolved) return null;
   return {
     provider: "claude",
     providerSessionId: candidate.id,
     cwd,
-    title: oneLine(title),
+    title: resolved.title,
+    titleSource: resolved.source,
     updatedAt: new Date(candidate.mtimeMs).toISOString(),
     source: entrypoint,
     activeElsewhere: null
   };
 }
-async function readCodexIndex(file) {
+async function readCodexIndex(files) {
+  const names = /* @__PURE__ */ new Map();
+  for (const file of files) for (const [id, name] of await readCodexIndexFile(file)) if (!names.has(id)) names.set(id, name);
+  return names;
+}
+async function readCodexIndexFile(file) {
   const names = /* @__PURE__ */ new Map();
   let text;
   try {
@@ -1748,13 +1820,15 @@ async function describeCodex(candidate, names) {
     }
   }
   if (isSubAgent) return null;
-  const title = names.get(candidate.id) ?? firstPrompt;
-  if (!title) return null;
+  const resolved = resolveSessionTitle({ app: names.get(candidate.id), "first-prompt": firstPrompt });
+  if (!resolved) return null;
   return {
     provider: "codex",
     providerSessionId: candidate.id,
     cwd,
-    title: oneLine(title),
+    title: resolved.title,
+    titleSource: resolved.source,
+    ...candidate.archived ? { archived: true } : {},
     updatedAt: new Date(candidate.mtimeMs).toISOString(),
     source,
     activeElsewhere: null
@@ -1799,8 +1873,8 @@ async function discoverLocalSessions(options = {}) {
   const homes = options.homes ?? defaultProviderHomes();
   const [claude, codex, names] = await Promise.all([
     claudeCandidates(homes.claudeProjects),
-    codexCandidates(homes.codexSessions),
-    readCodexIndex(homes.codexIndex)
+    codexCandidates(homes.codex),
+    readCodexIndex(homes.codex.map((h) => h.index))
   ]);
   const candidates = [...claude, ...codex].sort((a, b) => b.mtimeMs - a.mtimeMs);
   const processes = await listProcesses();
@@ -1820,7 +1894,7 @@ async function discoverLocalSessions(options = {}) {
 }
 async function findSessionFile(provider, providerSessionId, homes = defaultProviderHomes()) {
   if (!/^[0-9a-f-]{36}$/i.test(providerSessionId)) return null;
-  const candidates = provider === "claude" ? await claudeCandidates(homes.claudeProjects) : await codexCandidates(homes.codexSessions);
+  const candidates = provider === "claude" ? await claudeCandidates(homes.claudeProjects) : await codexCandidates(homes.codex);
   const hits = candidates.filter((c) => c.id === providerSessionId).sort((a, b) => b.mtimeMs - a.mtimeMs);
   return hits[0]?.file ?? null;
 }
@@ -1872,7 +1946,7 @@ async function readSessionFile(provider, file, endOffset, maxBytes = HISTORY_BUD
 async function listSessionFiles(homes = defaultProviderHomes()) {
   const [claude, codex] = await Promise.all([
     claudeCandidates(homes.claudeProjects),
-    codexCandidates(homes.codexSessions)
+    codexCandidates(homes.codex)
   ]);
   return [...claude, ...codex].sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
@@ -1915,7 +1989,7 @@ var PreferenceStore = class {
     if (!key || key.length > 200) throw new Error("That chat can't be found.");
     const next = { ...this.data[key] };
     if ("title" in patch) {
-      const title = typeof patch.title === "string" ? patch.title.replace(/\s+/g, " ").trim().slice(0, 200) : "";
+      const title = typeof patch.title === "string" ? patch.title.replace(/\s+/g, " ").trim().slice(0, TITLE_MAX) : "";
       if (title) next.title = title;
       else delete next.title;
     }
@@ -1933,6 +2007,18 @@ var PreferenceStore = class {
     this.persist();
     return this.all();
   }
+  /**
+   * Move a preference to the chat's lasting key (`session:<id>` → `<provider>:<id>` once the
+   * provider's id is known), so a rename made early is the one rename everywhere. A preference
+   * already under the lasting key wins field by field.
+   */
+  rekey(from, to) {
+    if (from === to || !this.data[from]) return false;
+    this.data[to] = { ...this.data[from], ...this.data[to] };
+    delete this.data[from];
+    this.persist();
+    return true;
+  }
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
@@ -2060,7 +2146,7 @@ async function searchLocalChats(query, options = {}) {
   const raw = JSON.stringify(needle).slice(1, -1);
   const limit = Math.max(1, Math.min(options.limit ?? 30, 100));
   const deadline = Date.now() + (options.budgetMs ?? 3500);
-  const names = await readCodexIndex(homes.codexIndex);
+  const names = await readCodexIndex(homes.codex.map((h) => h.index));
   const hits = [];
   let i = cursor;
   for (; i < files.length && hits.length < limit && Date.now() < deadline; i += 1) {
@@ -2095,6 +2181,65 @@ async function searchLocalChats(query, options = {}) {
   };
 }
 
+// src/sessions/hints.ts
+function titleHintKey(provider, sessionId) {
+  return `${provider}:${sessionId}`;
+}
+function createTitleHintsStore() {
+  let hints = null;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    current: () => hints,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    set(next) {
+      hints = next;
+      for (const l of listeners) l();
+    }
+  };
+}
+
+// src/engine/title-hints.ts
+function overlayHint(chat, hints, expected) {
+  if (!expected) return chat;
+  if (hints === null) return { ...chat, titlePending: true };
+  const hint = hints.get(titleHintKey(chat.provider, chat.providerSessionId));
+  if (!hint) return chat;
+  return {
+    ...chat,
+    title: hint.title,
+    titleSource: hint.source,
+    ...hint.archived || chat.archived ? { archived: true } : {},
+    ...hint.scheduled ? { scheduled: true } : {}
+  };
+}
+function unavailableFromHints(hints, covered) {
+  if (!hints) return [];
+  const out = [];
+  for (const [key, hint] of hints) {
+    if (!hint.unavailable || covered.has(key)) continue;
+    const at = key.indexOf(":");
+    const provider = key.slice(0, at);
+    if (provider !== "claude" && provider !== "codex") continue;
+    out.push({
+      provider,
+      providerSessionId: key.slice(at + 1),
+      cwd: null,
+      title: hint.title,
+      titleSource: hint.source,
+      updatedAt: new Date(hint.lastActiveMs ?? 0).toISOString(),
+      source: null,
+      activeElsewhere: null,
+      unavailable: hint.unavailable,
+      ...hint.archived ? { archived: true } : {},
+      ...hint.scheduled ? { scheduled: true } : {}
+    });
+  }
+  return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
 // src/engine/store.ts
 var import_node_crypto4 = require("crypto");
 var import_promises6 = __toESM(require("fs/promises"), 1);
@@ -2445,6 +2590,13 @@ async function createCodingSessionsEngine(options = {}) {
       }
     }
   }
+  const titleHints = options.titleHints;
+  const hintsNow = () => titleHints?.current() ?? null;
+  const unsubscribeHints = titleHints?.subscribe(() => emit({ type: "titles" })) ?? null;
+  const withHintTitle = (session) => {
+    const hint = session.providerSessionId ? hintsNow()?.get(titleHintKey(session.provider, session.providerSessionId)) : void 0;
+    return hint ? { ...session, title: hint.title } : session;
+  };
   function saveSession(session) {
     index.putSession(session);
     emit({ type: "session", session });
@@ -2601,7 +2753,12 @@ async function createCodingSessionsEngine(options = {}) {
         if (sid && sid !== knownProviderSession) {
           knownProviderSession = sid;
           const current = index.session(session.id);
-          if (current) saveSession({ ...current, providerSessionId: sid });
+          if (current) {
+            saveSession({ ...current, providerSessionId: sid });
+            if (preferences.rekey(chatKey(current.provider, null, current.id), chatKey(current.provider, sid))) {
+              emit({ type: "preferences", preferences: preferences.all() });
+            }
+          }
         }
         for (const item of items) emitItem(liveRun, item);
       }
@@ -2909,7 +3066,9 @@ async function createCodingSessionsEngine(options = {}) {
       );
     },
     async discoverSessions(opts) {
-      const found = await discoverLocalSessions({ limit: opts?.limit, homes, excludePids: ourPids() });
+      const read = await discoverLocalSessions({ limit: opts?.limit, homes, excludePids: ourPids() });
+      const hints = hintsNow();
+      const found = read.map((chat) => overlayHint(chat, hints, titleHints !== void 0));
       if (backups) {
         for (const chat of found) {
           const key = `${chat.provider}:${chat.providerSessionId}`;
@@ -2920,7 +3079,12 @@ async function createCodingSessionsEngine(options = {}) {
           }
         }
       }
-      return found;
+      const limit = opts?.limit ?? 60;
+      const oldest = found.length >= limit ? found[found.length - 1]?.updatedAt ?? "" : "";
+      const gone = unavailableFromHints(hints, new Set(found.map((c) => titleHintKey(c.provider, c.providerSessionId)))).filter(
+        (c) => c.updatedAt >= oldest
+      );
+      return gone.length ? [...found, ...gone].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).slice(0, limit) : found;
     },
     async recentFolders() {
       const seen = /* @__PURE__ */ new Map();
@@ -2941,7 +3105,7 @@ async function createCodingSessionsEngine(options = {}) {
       );
     },
     async listSessions() {
-      return index.sessions();
+      return index.sessions().map(withHintTitle);
     },
     async listRuns(sessionId) {
       const session = index.session(sessionId);
@@ -3116,7 +3280,9 @@ async function createCodingSessionsEngine(options = {}) {
       return all;
     },
     async searchChats(query, opts) {
-      return searchLocalChats(String(query ?? ""), { homes, cursor: opts?.cursor, limit: opts?.limit });
+      const result = await searchLocalChats(String(query ?? ""), { homes, cursor: opts?.cursor, limit: opts?.limit });
+      const hints = hintsNow();
+      return { ...result, hits: result.hits.map((hit) => ({ ...hit, title: hints?.get(titleHintKey(hit.provider, hit.providerSessionId))?.title ?? hit.title })) };
     },
     async openFolder(raw, target) {
       const folder = await assertFolder(String(raw ?? ""));
@@ -3146,6 +3312,7 @@ async function createCodingSessionsEngine(options = {}) {
       return agents.handleMcp(secret, body);
     },
     async dispose() {
+      unsubscribeHints?.();
       for (const liveRun of live.values()) {
         liveRun.stopRequested = true;
         if (liveRun.pgid !== null) killGroup(liveRun);
@@ -3202,9 +3369,11 @@ function openFolderIn(folder, target) {
   buildCleanEnv,
   claudeDefaults,
   codexDefaults,
+  codexHome,
   createAiMatrxRawBackupSink,
   createCodingSessionsEngine,
   createRawBackupScheduler,
+  createTitleHintsStore,
   defaultProviderHomes,
   describeActivity,
   describeProviderStatus,
@@ -3217,6 +3386,7 @@ function openFolderIn(folder, target) {
   readSessionFile,
   searchLocalChats,
   sessionActivity,
-  snippetAround
+  snippetAround,
+  titleHintKey
 });
 //# sourceMappingURL=index.cjs.map