@ai-matrx/coding-sessions 0.1.166 → 0.2.0

package/dist/{index-CDeDKQHe.d.cts → index-29t7n472.d.cts}

@@ -2,6 +2,10 @@ import { JsonValue } from '@ai-matrx/agents/portable';
 import { CredentialsPort } from '@ai-matrx/data';
 import { McpHttpReply } from '@ai-matrx/agents/portable/mcp';
 
+/** Where a title came from, strongest first. */
+declare const TITLE_PRECEDENCE: readonly ["override", "app", "app-remembered", "custom-title", "ai-title", "agent-name", "summary", "first-prompt", "last-prompt"];
+type TitleSource = (typeof TITLE_PRECEDENCE)[number];
+
 /**
  * The public contract of `@ai-matrx/coding-sessions`, shared by the engine
  * (Node), the local host (Node) and the UI (browser). Pure types — nothing here
@@ -129,7 +133,22 @@ interface DiscoveredSession {
     provider: CodingProvider;
     providerSessionId: string;
     cwd: string | null;
+    /**
+     * The chat's own title by the one rule (`./sessions`): the coding app's title when the owner of
+     * the apps' index supplied it (title hints), else the transcript's. Never the person's rename —
+     * that is applied once, by the screen, from the preferences.
+     */
     title: string;
+    /** Where `title` came from (`TITLE_PRECEDENCE`). */
+    titleSource?: TitleSource | undefined;
+    /** The app's title is still on its way (hints not loaded yet); `title` is the transcript's for now. */
+    titlePending?: boolean | undefined;
+    /** Archived in the app (hidden by default, like Code › Chats). */
+    archived?: boolean | undefined;
+    /** A scheduled or automated run (hidden by default). */
+    scheduled?: boolean | undefined;
+    /** The app lists it but its conversation file is gone: why. Shown, cannot be taken over. */
+    unavailable?: string | null | undefined;
     updatedAt: string;
     /** Where it was started, when the provider records it ("cli", "vscode", "exec", …). */
     source: string | null;
@@ -254,6 +273,10 @@ type CodingEvent = {
 } | {
     type: "preferences";
     preferences: Record<string, ChatPreference>;
+}
+/** The apps' titles changed (or finished loading): re-read the discovered chats. */
+ | {
+    type: "titles";
 } | {
     type: "item";
     sessionId: string;
@@ -573,11 +596,20 @@ declare const DEFAULT_SUPABASE_URL = "https://db.matrxserver.com";
  * few newest, and a transcript read is capped with the cap announced.
  */
 
+interface CodexHome {
+    /** `<CODEX_HOME>/sessions` (dated folders of rollouts). */
+    sessions: string;
+    /** `<CODEX_HOME>/archived_sessions` (rollouts Codex archived; flat). */
+    archived: string;
+    /** `<CODEX_HOME>/session_index.jsonl` (the app's thread names). */
+    index: string;
+}
 interface ProviderHomes {
     claudeProjects: string;
-    codexSessions: string;
-    codexIndex: string;
+    /** Every Codex home to read (main first). The owner of the apps' index names them (Matrx 2: the Codex source's homes). */
+    codex: CodexHome[];
 }
+declare function codexHome(dir: string): CodexHome;
 declare function defaultProviderHomes(home?: string): ProviderHomes;
 interface DiscoverOptions {
     limit?: number | undefined;
@@ -601,6 +633,40 @@ declare function findSessionFile(provider: CodingProvider, providerSessionId: st
  */
 declare function readSessionFile(provider: CodingProvider, file: string, endOffset?: number | undefined, maxBytes?: number): Promise<SessionHistory>;
 
+/**
+ * TITLE HINTS — the port through which the owner of the coding apps' index (Matrx 2's core, which
+ * reads Claude's records, Codex's database and the rest through its own `fs`/`exec` owners) tells
+ * this package what each chat is called and whether the app hides it. The package never walks the
+ * apps' records itself: it reads transcripts (titles by the transcript rules, content search,
+ * activity) and overlays these hints as they arrive. Pure: browser-safe types and helpers.
+ */
+
+type HintProvider = "claude" | "codex";
+interface TitleHint {
+    /** The app's title (pre-override: the person's rename is applied by whoever draws the row). */
+    title: string;
+    source: TitleSource;
+    /** The app hides it: archived in the app (shown behind a toggle). */
+    archived?: boolean | undefined;
+    /** A scheduled or automated run (shown behind a toggle). */
+    scheduled?: boolean | undefined;
+    /** Listed by the app but its conversation file is gone: why (it is shown, never dropped). */
+    unavailable?: string | null | undefined;
+    /** Last activity the app records (ms), for chats only the app knows. */
+    lastActiveMs?: number | null | undefined;
+}
+interface TitleHints {
+    /** The hints now, keyed `titleHintKey()`; null while the owner's index is still loading. Never waits. */
+    current(): ReadonlyMap<string, TitleHint> | null;
+    /** Called after the hints change (a rename in the app, a new chat, the first load). */
+    subscribe(listener: () => void): () => void;
+}
+declare function titleHintKey(provider: HintProvider, sessionId: string): string;
+/** A hints port the host fills by hand (tests, or an owner that pushes whole snapshots). */
+declare function createTitleHintsStore(): TitleHints & {
+    set(hints: ReadonlyMap<string, TitleHint> | null): void;
+};
+
 /**
  * THE CLEAN ENVIRONMENT — built from an ALLOWLIST, never a denylist.
  *
@@ -724,6 +790,12 @@ declare class PreferenceStore {
     get(key: string): ChatPreference | null;
     /** Merge `patch`; a null/false/empty field is removed, an empty preference deleted. */
     set(key: string, patch: ChatPreference): Record<string, ChatPreference>;
+    /**
+     * 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: string, to: string): boolean;
     private persist;
     flush(): Promise<void>;
 }
@@ -780,6 +852,12 @@ interface CodingSessionsEngineOptions {
      * are unaffected.
      */
     agents?: CodingSessionsAgentsOptions | undefined;
+    /**
+     * What the coding apps' own records say each chat is called (and archived / scheduled / file
+     * gone), from the owner of the apps' index — Matrx 2's core. Never waited for; absent → titles
+     * come from the transcripts alone (the standalone host).
+     */
+    titleHints?: TitleHints | undefined;
 }
 interface CodingSessionsEngine extends CodingSessionsApi {
     subscribe(listener: (event: CodingEvent) => void): () => void;
@@ -799,4 +877,4 @@ interface CodingSessionsEngine extends CodingSessionsApi {
 declare function describeProviderStatus(provider: CodingProvider, probe: Record<string, unknown> | undefined, lastProblem?: ProviderProblem | null, quota?: QuotaWindow[]): ProviderStatus;
 declare function createCodingSessionsEngine(options?: CodingSessionsEngineOptions): Promise<CodingSessionsEngine>;
 
-export { searchLocalChats as A, sessionActivity as B, type CodingSessionsMethod as C, DEFAULT_SERVER_URL as D, EFFORT_LEVELS as E, snippetAround as F, PreferenceStore as P, RAW_TRANSCRIPT_MAX_BYTES as R, type CodingSessionsApi as a, type CodingEvent as b, type CodingSessionsEngine as c, type CodingSessionsEngineOptions as d, type CodingSessionsAgentsOptions as e, DEFAULT_SUPABASE_URL as f, type ProviderHomes as g, type RawBackupPolicy as h, type RawBackupSink as i, type RunStatus as j, buildCleanEnv as k, claudeDefaults as l, codexDefaults as m, createAiMatrxRawBackupSink as n, createCodingSessionsEngine as o, createRawBackupScheduler as p, defaultProviderHomes as q, describeActivity as r, describeProviderStatus as s, discoverLocalSessions as t, endsWithOpenToolCall as u, findDrivingProcess as v, findSessionFile as w, isAllowedEnvName as x, listProcesses as y, readSessionFile as z };
+export { findSessionFile as A, isAllowedEnvName as B, type CodingSessionsMethod as C, DEFAULT_SERVER_URL as D, EFFORT_LEVELS as E, listProcesses as F, readSessionFile as G, searchLocalChats as H, sessionActivity as I, snippetAround as J, titleHintKey as K, PreferenceStore as P, RAW_TRANSCRIPT_MAX_BYTES as R, type TitleHint as T, type CodingSessionsApi as a, type CodingEvent as b, type CodingSessionsEngine as c, type CodingSessionsEngineOptions as d, type CodingSessionsAgentsOptions as e, type CodexHome as f, DEFAULT_SUPABASE_URL as g, type ProviderHomes as h, type RawBackupPolicy as i, type RawBackupSink as j, type RunStatus as k, type TitleHints as l, buildCleanEnv as m, claudeDefaults as n, codexDefaults as o, codexHome as p, createAiMatrxRawBackupSink as q, createCodingSessionsEngine as r, createRawBackupScheduler as s, createTitleHintsStore as t, defaultProviderHomes as u, describeActivity as v, describeProviderStatus as w, discoverLocalSessions as x, endsWithOpenToolCall as y, findDrivingProcess as z };

package/dist/{index-CDeDKQHe.d.ts → index-29t7n472.d.ts}

@@ -2,6 +2,10 @@ import { JsonValue } from '@ai-matrx/agents/portable';
 import { CredentialsPort } from '@ai-matrx/data';
 import { McpHttpReply } from '@ai-matrx/agents/portable/mcp';
 
+/** Where a title came from, strongest first. */
+declare const TITLE_PRECEDENCE: readonly ["override", "app", "app-remembered", "custom-title", "ai-title", "agent-name", "summary", "first-prompt", "last-prompt"];
+type TitleSource = (typeof TITLE_PRECEDENCE)[number];
+
 /**
  * The public contract of `@ai-matrx/coding-sessions`, shared by the engine
  * (Node), the local host (Node) and the UI (browser). Pure types — nothing here
@@ -129,7 +133,22 @@ interface DiscoveredSession {
     provider: CodingProvider;
     providerSessionId: string;
     cwd: string | null;
+    /**
+     * The chat's own title by the one rule (`./sessions`): the coding app's title when the owner of
+     * the apps' index supplied it (title hints), else the transcript's. Never the person's rename —
+     * that is applied once, by the screen, from the preferences.
+     */
     title: string;
+    /** Where `title` came from (`TITLE_PRECEDENCE`). */
+    titleSource?: TitleSource | undefined;
+    /** The app's title is still on its way (hints not loaded yet); `title` is the transcript's for now. */
+    titlePending?: boolean | undefined;
+    /** Archived in the app (hidden by default, like Code › Chats). */
+    archived?: boolean | undefined;
+    /** A scheduled or automated run (hidden by default). */
+    scheduled?: boolean | undefined;
+    /** The app lists it but its conversation file is gone: why. Shown, cannot be taken over. */
+    unavailable?: string | null | undefined;
     updatedAt: string;
     /** Where it was started, when the provider records it ("cli", "vscode", "exec", …). */
     source: string | null;
@@ -254,6 +273,10 @@ type CodingEvent = {
 } | {
     type: "preferences";
     preferences: Record<string, ChatPreference>;
+}
+/** The apps' titles changed (or finished loading): re-read the discovered chats. */
+ | {
+    type: "titles";
 } | {
     type: "item";
     sessionId: string;
@@ -573,11 +596,20 @@ declare const DEFAULT_SUPABASE_URL = "https://db.matrxserver.com";
  * few newest, and a transcript read is capped with the cap announced.
  */
 
+interface CodexHome {
+    /** `<CODEX_HOME>/sessions` (dated folders of rollouts). */
+    sessions: string;
+    /** `<CODEX_HOME>/archived_sessions` (rollouts Codex archived; flat). */
+    archived: string;
+    /** `<CODEX_HOME>/session_index.jsonl` (the app's thread names). */
+    index: string;
+}
 interface ProviderHomes {
     claudeProjects: string;
-    codexSessions: string;
-    codexIndex: string;
+    /** Every Codex home to read (main first). The owner of the apps' index names them (Matrx 2: the Codex source's homes). */
+    codex: CodexHome[];
 }
+declare function codexHome(dir: string): CodexHome;
 declare function defaultProviderHomes(home?: string): ProviderHomes;
 interface DiscoverOptions {
     limit?: number | undefined;
@@ -601,6 +633,40 @@ declare function findSessionFile(provider: CodingProvider, providerSessionId: st
  */
 declare function readSessionFile(provider: CodingProvider, file: string, endOffset?: number | undefined, maxBytes?: number): Promise<SessionHistory>;
 
+/**
+ * TITLE HINTS — the port through which the owner of the coding apps' index (Matrx 2's core, which
+ * reads Claude's records, Codex's database and the rest through its own `fs`/`exec` owners) tells
+ * this package what each chat is called and whether the app hides it. The package never walks the
+ * apps' records itself: it reads transcripts (titles by the transcript rules, content search,
+ * activity) and overlays these hints as they arrive. Pure: browser-safe types and helpers.
+ */
+
+type HintProvider = "claude" | "codex";
+interface TitleHint {
+    /** The app's title (pre-override: the person's rename is applied by whoever draws the row). */
+    title: string;
+    source: TitleSource;
+    /** The app hides it: archived in the app (shown behind a toggle). */
+    archived?: boolean | undefined;
+    /** A scheduled or automated run (shown behind a toggle). */
+    scheduled?: boolean | undefined;
+    /** Listed by the app but its conversation file is gone: why (it is shown, never dropped). */
+    unavailable?: string | null | undefined;
+    /** Last activity the app records (ms), for chats only the app knows. */
+    lastActiveMs?: number | null | undefined;
+}
+interface TitleHints {
+    /** The hints now, keyed `titleHintKey()`; null while the owner's index is still loading. Never waits. */
+    current(): ReadonlyMap<string, TitleHint> | null;
+    /** Called after the hints change (a rename in the app, a new chat, the first load). */
+    subscribe(listener: () => void): () => void;
+}
+declare function titleHintKey(provider: HintProvider, sessionId: string): string;
+/** A hints port the host fills by hand (tests, or an owner that pushes whole snapshots). */
+declare function createTitleHintsStore(): TitleHints & {
+    set(hints: ReadonlyMap<string, TitleHint> | null): void;
+};
+
 /**
  * THE CLEAN ENVIRONMENT — built from an ALLOWLIST, never a denylist.
  *
@@ -724,6 +790,12 @@ declare class PreferenceStore {
     get(key: string): ChatPreference | null;
     /** Merge `patch`; a null/false/empty field is removed, an empty preference deleted. */
     set(key: string, patch: ChatPreference): Record<string, ChatPreference>;
+    /**
+     * 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: string, to: string): boolean;
     private persist;
     flush(): Promise<void>;
 }
@@ -780,6 +852,12 @@ interface CodingSessionsEngineOptions {
      * are unaffected.
      */
     agents?: CodingSessionsAgentsOptions | undefined;
+    /**
+     * What the coding apps' own records say each chat is called (and archived / scheduled / file
+     * gone), from the owner of the apps' index — Matrx 2's core. Never waited for; absent → titles
+     * come from the transcripts alone (the standalone host).
+     */
+    titleHints?: TitleHints | undefined;
 }
 interface CodingSessionsEngine extends CodingSessionsApi {
     subscribe(listener: (event: CodingEvent) => void): () => void;
@@ -799,4 +877,4 @@ interface CodingSessionsEngine extends CodingSessionsApi {
 declare function describeProviderStatus(provider: CodingProvider, probe: Record<string, unknown> | undefined, lastProblem?: ProviderProblem | null, quota?: QuotaWindow[]): ProviderStatus;
 declare function createCodingSessionsEngine(options?: CodingSessionsEngineOptions): Promise<CodingSessionsEngine>;
 
-export { searchLocalChats as A, sessionActivity as B, type CodingSessionsMethod as C, DEFAULT_SERVER_URL as D, EFFORT_LEVELS as E, snippetAround as F, PreferenceStore as P, RAW_TRANSCRIPT_MAX_BYTES as R, type CodingSessionsApi as a, type CodingEvent as b, type CodingSessionsEngine as c, type CodingSessionsEngineOptions as d, type CodingSessionsAgentsOptions as e, DEFAULT_SUPABASE_URL as f, type ProviderHomes as g, type RawBackupPolicy as h, type RawBackupSink as i, type RunStatus as j, buildCleanEnv as k, claudeDefaults as l, codexDefaults as m, createAiMatrxRawBackupSink as n, createCodingSessionsEngine as o, createRawBackupScheduler as p, defaultProviderHomes as q, describeActivity as r, describeProviderStatus as s, discoverLocalSessions as t, endsWithOpenToolCall as u, findDrivingProcess as v, findSessionFile as w, isAllowedEnvName as x, listProcesses as y, readSessionFile as z };
+export { findSessionFile as A, isAllowedEnvName as B, type CodingSessionsMethod as C, DEFAULT_SERVER_URL as D, EFFORT_LEVELS as E, listProcesses as F, readSessionFile as G, searchLocalChats as H, sessionActivity as I, snippetAround as J, titleHintKey as K, PreferenceStore as P, RAW_TRANSCRIPT_MAX_BYTES as R, type TitleHint as T, type CodingSessionsApi as a, type CodingEvent as b, type CodingSessionsEngine as c, type CodingSessionsEngineOptions as d, type CodingSessionsAgentsOptions as e, type CodexHome as f, DEFAULT_SUPABASE_URL as g, type ProviderHomes as h, type RawBackupPolicy as i, type RawBackupSink as j, type RunStatus as k, type TitleHints as l, buildCleanEnv as m, claudeDefaults as n, codexDefaults as o, codexHome as p, createAiMatrxRawBackupSink as q, createCodingSessionsEngine as r, createRawBackupScheduler as s, createTitleHintsStore as t, defaultProviderHomes as u, describeActivity as v, describeProviderStatus as w, discoverLocalSessions as x, endsWithOpenToolCall as y, findDrivingProcess as z };