@ai-matrx/coding-sessions 0.1.166 → 0.3.0

package/dist/{index-CDeDKQHe.d.cts → index-Bbe11HoB.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 | "unknown" | 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;
@@ -244,6 +263,11 @@ type TranscriptItem = {
     id: string;
     text: string;
 };
+interface TitleStatus {
+    owner: boolean;
+    pending: boolean;
+    problem: string | null;
+}
 /** Everything the engine pushes to a listener. */
 type CodingEvent = {
     type: "session";
@@ -254,6 +278,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;
@@ -409,6 +437,10 @@ interface CodingSessionsApi {
     discoverSessions(options?: {
         limit?: number;
     }): Promise<DiscoveredSession[]>;
+    /** Where the apps' own titles stand: an owner supplies them (`owner`), still loading, or failing (`problem`, shown with Retry). */
+    titleStatus(): Promise<TitleStatus>;
+    /** Ask the owner of the apps' titles again (the Retry). */
+    retryTitles(): Promise<void>;
     recentFolders(): Promise<RecentFolder[]>;
     listSessions(): Promise<CodingSession[]>;
     listRuns(sessionId: string): Promise<RunRecord[]>;
@@ -573,17 +605,34 @@ 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;
+    /** The claude-accounts holder's copies (`<vault>/<id>/transcript.jsonl`): a held chat's history when its own file is gone. */
+    claudeVault?: string | undefined;
+    /** 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;
     homes?: ProviderHomes | undefined;
     /** Processes that are OUR runs (never "live elsewhere"). */
     excludePids?: ReadonlySet<number> | undefined;
+    /**
+     * The apps' own titles from the owner of their index (`provider:id` → title). Given → the apps'
+     * files are not read here at all (Codex thread names come from it); absent → the standalone host
+     * reads Codex's `session_index.jsonl` itself.
+     */
+    appTitles?: ReadonlyMap<string, string> | undefined;
 }
 /** Fresh "is it live elsewhere?" for one session (the preview and the takeover confirm). */
 declare function sessionActivity(provider: CodingProvider, providerSessionId: string, options?: {
@@ -601,6 +650,46 @@ 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;
+    /** Where the owner's title came from; "unknown" when the owner did not say (shown as such, never guessed). */
+    source: TitleSource | "unknown";
+    /** 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, a failure). */
+    subscribe(listener: () => void): () => void;
+    /** Why the apps' titles could not be had right now (shown with a Retry), or null. */
+    problem?(): string | null;
+    /** Ask the owner again now (the Retry). */
+    retry?(): 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;
+    setProblem(problem: string | null): void;
+};
+
 /**
  * THE CLEAN ENVIRONMENT — built from an ALLOWLIST, never a denylist.
  *
@@ -682,6 +771,8 @@ interface SearchOptions {
     homes?: ProviderHomes | undefined;
     cursor?: number | undefined;
     limit?: number | undefined;
+    /** The apps' own titles (`provider:id` → title) from the owner of their index; absent → Codex's index is read here. */
+    appTitles?: ReadonlyMap<string, string> | undefined;
     /** Stop reading after this long and hand back a cursor. Default 3.5 s. */
     budgetMs?: number | undefined;
 }
@@ -724,6 +815,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,9 +877,17 @@ 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;
+    /** Where the providers keep their sessions, learned after start (Matrx 2: Codex homes from its core). */
+    setHomes(homes: ProviderHomes): void;
     /** Stop every live run and wait for the index to be written. */
     dispose(): Promise<void>;
     readonly dataDir: string;
@@ -799,4 +904,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-Bbe11HoB.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 | "unknown" | 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;
@@ -244,6 +263,11 @@ type TranscriptItem = {
     id: string;
     text: string;
 };
+interface TitleStatus {
+    owner: boolean;
+    pending: boolean;
+    problem: string | null;
+}
 /** Everything the engine pushes to a listener. */
 type CodingEvent = {
     type: "session";
@@ -254,6 +278,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;
@@ -409,6 +437,10 @@ interface CodingSessionsApi {
     discoverSessions(options?: {
         limit?: number;
     }): Promise<DiscoveredSession[]>;
+    /** Where the apps' own titles stand: an owner supplies them (`owner`), still loading, or failing (`problem`, shown with Retry). */
+    titleStatus(): Promise<TitleStatus>;
+    /** Ask the owner of the apps' titles again (the Retry). */
+    retryTitles(): Promise<void>;
     recentFolders(): Promise<RecentFolder[]>;
     listSessions(): Promise<CodingSession[]>;
     listRuns(sessionId: string): Promise<RunRecord[]>;
@@ -573,17 +605,34 @@ 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;
+    /** The claude-accounts holder's copies (`<vault>/<id>/transcript.jsonl`): a held chat's history when its own file is gone. */
+    claudeVault?: string | undefined;
+    /** 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;
     homes?: ProviderHomes | undefined;
     /** Processes that are OUR runs (never "live elsewhere"). */
     excludePids?: ReadonlySet<number> | undefined;
+    /**
+     * The apps' own titles from the owner of their index (`provider:id` → title). Given → the apps'
+     * files are not read here at all (Codex thread names come from it); absent → the standalone host
+     * reads Codex's `session_index.jsonl` itself.
+     */
+    appTitles?: ReadonlyMap<string, string> | undefined;
 }
 /** Fresh "is it live elsewhere?" for one session (the preview and the takeover confirm). */
 declare function sessionActivity(provider: CodingProvider, providerSessionId: string, options?: {
@@ -601,6 +650,46 @@ 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;
+    /** Where the owner's title came from; "unknown" when the owner did not say (shown as such, never guessed). */
+    source: TitleSource | "unknown";
+    /** 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, a failure). */
+    subscribe(listener: () => void): () => void;
+    /** Why the apps' titles could not be had right now (shown with a Retry), or null. */
+    problem?(): string | null;
+    /** Ask the owner again now (the Retry). */
+    retry?(): 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;
+    setProblem(problem: string | null): void;
+};
+
 /**
  * THE CLEAN ENVIRONMENT — built from an ALLOWLIST, never a denylist.
  *
@@ -682,6 +771,8 @@ interface SearchOptions {
     homes?: ProviderHomes | undefined;
     cursor?: number | undefined;
     limit?: number | undefined;
+    /** The apps' own titles (`provider:id` → title) from the owner of their index; absent → Codex's index is read here. */
+    appTitles?: ReadonlyMap<string, string> | undefined;
     /** Stop reading after this long and hand back a cursor. Default 3.5 s. */
     budgetMs?: number | undefined;
 }
@@ -724,6 +815,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,9 +877,17 @@ 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;
+    /** Where the providers keep their sessions, learned after start (Matrx 2: Codex homes from its core). */
+    setHomes(homes: ProviderHomes): void;
     /** Stop every live run and wait for the index to be written. */
     dispose(): Promise<void>;
     readonly dataDir: string;
@@ -799,4 +904,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 };