@maudecode/talaria-web 1.16.1 → 1.18.0

package/dist/sessions/service.d.ts

@@ -3,13 +3,15 @@
  * detail payload, list and search, and every mutation with its guards.
  * Runtime concerns owned by other domains arrive through `SessionServiceDeps`.
  */
-import type { PendingSteer } from '@maudecode/talaria-web-contracts';
+import type { PendingSteer, RecoveryAudit, RecoveryRepair } from '@maudecode/talaria-web-contracts';
 import type { RunJournal } from './journal.js';
 import type { DraftStore } from './drafts.js';
 import type { SessionEventBus } from './events.js';
 import { type ListParams, type ListResponse, type Row, type RuntimeOverlay } from './list.js';
 import { Session, titleFrom, type Message } from './session.js';
 import { type SessionStore } from './store.js';
+import { type ClaudeCodeSessionSource } from './claude-code.js';
+import { type StateDbRead } from './state-db.js';
 import { type CompressionJob } from './compress.js';
 import { type SidecarLike } from '../sidecar/client.js';
 import { type ToolResultView } from './merge.js';
@@ -30,6 +32,8 @@ export declare class HttpFailure extends Error {
  */
 export declare function ensureAgentRuntimeCurrent(sidecar: SidecarLike | null): Promise<void>;
 export interface SessionServiceDeps {
+    /** TAL-259: epoch seconds of the state directory's `recovery_stamping_since` marker. */
+    recoveryStampingSince: () => number;
     /** TAL-255: the Agent sidecar for manual compression (`chat.compress`); null while it is down. */
     sidecar?: () => SidecarLike | null;
     /** Detached sidecar work for a profile: deletion waits for the returned release, so the home outlives the work. */
@@ -73,8 +77,10 @@ export interface SessionServiceDeps {
     journal?: RunJournal;
     hermesHome: string;
     home: string;
-    /** Sync title-only metadata to state.db when `sync_to_insights` is on. */
-    syncTitle: (session: Session) => Promise<void>;
+    /** Sync title-only metadata to state.db when `sync_to_insights` is on; `manual` marks a user-requested title (rename or regenerate). */
+    syncTitle: (session: Session, manual?: boolean) => Promise<void>;
+    /** TAL-591: the background title job for a CLI session a mutation just claimed (Python `import_cli` queued one). */
+    titleClaimed?: (session: Session) => void;
     /** Context length lookup for a model (checkpoint 7 wires the catalog). */
     contextLengthFor: (model: string | null, provider: string | null) => number | null;
     /** TAL-301: the catalog entry id a stored `(model, provider)` pair selects (null when none or not yet known). */
@@ -85,6 +91,10 @@ export interface SessionServiceDeps {
     resolveContextLength?: (model: string | null, provider: string | null, profile: string | null) => Promise<number | null>;
     /** `(model, provider)` normalisation from a request (checkpoint 7 wires provider-qualified ids). */
     modelStateFromRequest: (model: unknown, requestedProvider: unknown, currentProvider: string | null) => [string | null, string | null];
+    /** TAL-542: the pair a stale session model starts on, from the profile's catalog; `null` keeps it. */
+    repairSessionModel?: (profile: string | null, model: string, provider: string | null) => [string, string] | null;
+    /** TAL-542: builds the catalog `repairSessionModel` reads unless a fresh enough one exists. */
+    warmSessionModelRepair?: (profile?: string | null) => Promise<void>;
     yolo: {
         isEnabled: (sid: string) => boolean;
         set: (sid: string, enabled: boolean) => void;
@@ -93,10 +103,19 @@ export interface SessionServiceDeps {
     /** `truncated`: source kinds whose rows stopped at the per-kind window on this read (TAL-482). */
     cliSessions: (profile: string, opts: {
         sourceFilter: string | null;
+    }) => Promise<{
+        rows: Row[];
+        truncated: ReadonlySet<string>;
+    }>;
+    /** `cliSessions` read on this thread, for the synchronous single-session lookups. */
+    cliSessionsSync: (profile: string, opts: {
+        sourceFilter: string | null;
     }) => {
         rows: Row[];
         truncated: ReadonlySet<string>;
     };
+    /** TAL-551: read-only Claude Code transcripts, listed with the CLI rows when both toggles are on. */
+    claudeCode?: ClaudeCodeSessionSource;
     profileHome: (profile: string) => string;
     /** Python `commit_session_memory` (fire-and-forget): the cached Agent flushes memory for a session the user left. */
     commitSessionMemory?: (sid: string) => void;
@@ -112,6 +131,13 @@ export declare class SessionService {
     private readonly compressionJobs;
     constructor(deps: SessionServiceDeps);
     private get store();
+    /**
+     * TAL-577: user-turn admission shared by `chat.start` and server-side wakeups, after `ensureAgentRuntimeCurrent`.
+     * A requested workspace must be trusted; the session's own one, when its directory is gone, falls back to the last one.
+     */
+    turnWorkspace(s: Session, requested?: unknown): string;
+    /** A `@provider:` id is split; any other model an explicit pick did not just choose is checked against the catalog (TAL-542). */
+    turnModel(s: Session, body?: Record<string, unknown>): [string | null, string | null, boolean];
     /**
      * TAL-186: rewrites a session's media references to their URLs. A local path is rewritten only when `/api/media`
      * serves it for this session, under the same resolution, so every rewritten reference loads.
@@ -131,6 +157,20 @@ export declare class SessionService {
     isSubagentViewOnly(sid: string): boolean;
     /** TAL-358: batched `sessions.source` owners from the active profile's state.db. */
     readonly stateDbSources: (ids: string[]) => Map<string, string> | null;
+    /**
+     * TAL-590 (Python #3238): the read-only CLI or API-server imports among `rows` whose active-profile state.db row is
+     * gone, so their source was deleted outside Web and no Web action could remove them. An unreadable state.db proves
+     * nothing (`agentSessionRowsExisting`); another profile's session or one with a run the runtime still holds is never
+     * an orphan, while a stream id a crash left behind does not count as one.
+     */
+    private orphanedImports;
+    private orphanCandidates;
+    private isOrphanedImport;
+    /**
+     * The list's owner locks and orphan prune (an orphan's sidecar goes, as nothing else ever removes it), with their
+     * state.db reads made on the listing worker up front so the synchronous build never opens state.db (TAL-920).
+     */
+    private listStateDbLookups;
     /** The persisted flag folded with the state.db owner lock (TAL-358): the one read-only rule for mutation gates and the wire. */
     isReadOnly(s: Session): boolean;
     /** Full session for mutation, refusing read-only imports (Python `_get_or_materialize_session`). */
@@ -138,12 +178,52 @@ export declare class SessionService {
     private get404;
     /** The Agent's state.db rows for this session (empty for subagent views, which never merge). */
     stateDbRows(s: Session): Message[];
+    /** `stateDbRows` and whether the read succeeded on a state.db whose messages carry ids (TAL-493). */
+    stateDbRead(s: Session): StateDbRead;
+    private stateDbPath;
     /**
      * Python `_merged_session_messages_for_display`: the sidecar transcript merged append-only with the Agent's state.db
      * rows (a WebUI conversation continued from the CLI shows the CLI turns). This is the coordinate space `GET
      * /api/session` exposes, so branching and the next model history slice/extend the same list.
      */
     mergedTranscript(s: Session, local?: Message[], stateRows?: Message[]): Message[];
+    /**
+     * TAL-493: record the highest state.db id this boundary or settled turn read, under the session lock in the same save,
+     * so the merge never replays a covered row and appends every row committed after the read. Call it after the boundary
+     * fields are set: the marker holds only while they and the row it names stay as recorded.
+     */
+    markStateDbSeen(s: Session, read?: StateDbRead, opts?: {
+        boundary?: boolean;
+    }): void;
+    /**
+     * TAL-493: a turn's settlement. Each state.db row the merge shows now is matched to what the turn holds: a row already
+     * in the context it started from (by id), or one row the Agent added this turn (`agentRows` past that context, matched
+     * one to one by full text). An unmatched row is a CLI or gateway row committed while the turn ran: it joins the
+     * transcript and the model context before the marker passes it. Without the Agent's rows (`agentRows` empty), rows past
+     * `startId` (the highest id the turn read when it started) are its own unreported work: covered, never shown. Rows the
+     * turn started from but the transcript lacks (a CLI continuation read into its context) are kept before the turn.
+     */
+    settleStateDb(s: Session, turn: {
+        turnId: string;
+        previousContext: Message[];
+        agentRows?: Message[] | null;
+        startId?: number | null;
+        read?: StateDbRead;
+    }): void;
+    /**
+     * TAL-921: the model context a turn leaves when it ends without its settled result (an error, a Stop, a dead run), as a
+     * Stop's: the Agent's rows when they hold the turn's prompt, else its own rows among `stateRows` (the state.db rows
+     * committed after it started), then the prose that streamed past them. Null when it captured nothing the model can use.
+     */
+    unsettledTurnContext(turn: {
+        previousContext: Message[];
+        prompt: string | Record<string, unknown>[];
+        msgText: string;
+        streamedText: string;
+        historyLength: number;
+        agentRows?: Message[] | null;
+        stateRows: Message[];
+    }): Message[] | null;
     /**
      * Python `reconciled_state_db_messages_for_session(prefer_context=True)`: the model history is the owner context
      * extended append-only with the Agent's state.db rows (a CLI continuation of this session reaches the model), except
@@ -155,8 +235,11 @@ export declare class SessionService {
      * deferred save keeps out of `messages` and `context_messages` until settlement.
      */
     sideQuestionContext(s: Session): Message[];
+    /** Python `_is_messaging_session_id`: from the WebUI metadata or the Agent's row. */
+    private isMessagingSession;
     /** Python `_lookup_cli_session_metadata`: the sidebar row for a state.db session in the active profile. */
     private lookupCliMeta;
+    private claudeCodeRows;
     /** Python `_session_index_marks_was_webui`: an index row that once owned a WebUI sidecar (self-heal 404). */
     private indexMarksWasWebui;
     /**
@@ -169,6 +252,11 @@ export declare class SessionService {
         reason: 'materialized' | 'not_claimable' | 'was_webui' | 'no_foreign_state' | 'invalid_sid';
     };
     private mutationTarget;
+    /**
+     * TAL-551: a Claude Code import is a live view of a transcript Claude Code keeps writing. Web never stores a copy,
+     * which would freeze its messages and pin it to one profile.
+     */
+    private rejectClaudeCode;
     private rejectSubagent;
     /** TAL-372: each delegation row of a turn's scene carries the status of the work it started. */
     backgroundLinked(s: Session, messages: unknown[]): unknown[];
@@ -196,6 +284,11 @@ export declare class SessionService {
         msg_before?: string | null | undefined;
         resolve_model?: string | null | undefined;
     }): Record<string, unknown>;
+    /**
+     * TAL-454: the chat `/branch` copied, while it still loads (archived included). A compression continuation is also a
+     * fork of its parent but not a branch, so it links nowhere.
+     */
+    private branchedFrom;
     /**
      * TAL-316: the active run whose journal can replay its output from the start. The detail then leaves that output to the
      * replay; with no active run, no identifiable prompt, or no complete journal, it returns the persisted transcript unchanged.
@@ -207,12 +300,12 @@ export declare class SessionService {
     private foreignSession;
     /** Python `_handle_session_get` without a sidecar: the state.db transcript as a (read-only or claimable) foreign stub. */
     private foreignSessionDetail;
-    /** Clear persisted streaming flags when no live stream backs them (Python `_clear_stale_stream_state`, no journal recovery). */
+    /** Clear persisted streaming flags when no live stream backs them (Python `_clear_stale_stream_state`). */
     clearStaleStreamState(session: Session): boolean;
-    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources'>): {
+    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources' | 'pruneOrphanedImports' | 'webuiRows'>): Promise<{
         body: ListResponse;
         etag: string;
-    };
+    }>;
     search(q: string, opts: {
         content: boolean;
         depth: number;
@@ -227,12 +320,13 @@ export declare class SessionService {
         content: boolean;
         depth: number;
         projectId: string | null;
-    }): Record<string, unknown>;
-    /** The first of a stored session's first `depth` messages (0: all) containing `query`, with its redacted excerpt. */
+    }): Promise<Record<string, unknown>>;
+    /** The first of a stored session's first `depth` messages (0: all) containing every term, with its redacted excerpt. */
     private contentMatch;
     status(sid: string): Record<string, unknown>;
     usage(sid: string): Record<string, unknown>;
     resolveNewSessionWorkspace(body: Record<string, unknown>, visiblePrevSessionId: string | null, profile: string | null): string | null;
+    /** The server owns the names' normalization (TAL-631): trimmed, blanks dropped, and nothing left is the profile's defaults. */
     validateToolsetsShape(toolsets: unknown): string[] | null;
     create(body: Record<string, unknown>, opts?: {
         worktree?: {
@@ -263,6 +357,40 @@ export declare class SessionService {
     /** The session a compression may run on now, and the model history it compresses: the context a turn would send, so a
      * repeat compression builds on the previous summary instead of re-reading the whole display transcript. */
     private compressionTarget;
+    /** The loaded session's own compression guards: no running turn and enough model history. */
+    private compressionHistory;
+    /** TAL-614: whether a manual compression would start now: `compressionTarget`'s gates, with `readOnly` the wire flag. */
+    private canCompress;
+    /** TAL-258: the session's WebUI record (absent for a CLI or gateway session) and the profile whose state.db holds its rows. */
+    private handoffTarget;
+    /** Python `_handle_conversation_rounds` (TAL-258): the session's rounds and whether the handoff dock is due. */
+    conversationRounds(sid: string, since: number | null): {
+        ok: true;
+        rounds: number;
+        threshold: number;
+        should_show: boolean;
+    };
+    /**
+     * Python `_handle_handoff_summary` (TAL-258): the session's main model summarizes its last 50 state.db messages after
+     * `since`, and the summary is appended as a display-only `handoff_summary` tool row. A failed or cut-off answer falls
+     * back to a deterministic local summary rather than an error.
+     */
+    handoffSummary(sid: string, since: number | null): Promise<{
+        ok: true;
+        summary: string;
+        message_count: number;
+        rounds: number;
+        fallback: boolean;
+        warning?: string;
+    }>;
+    /** The main model's summary at 700 tokens, once more at 1400 when it was cut off, else the local fallback. */
+    private generateHandoffSummary;
+    /**
+     * Python `_persist_handoff_summary`: a messaging session gets the marker in state.db and its WebUI record; any other
+     * session in its WebUI record, or in state.db when it has none. Each store skips a marker its tail already holds, and
+     * the session lock keeps two summaries from both passing that check. A card neither store saved answers 503.
+     */
+    private persistHandoffMarker;
     /** The session's compression job; a deleted session's finished result is dropped rather than served. */
     compressionJob(sid: string): CompressionJob | undefined;
     /**
@@ -277,6 +405,22 @@ export declare class SessionService {
     undo(sid: string): Promise<Record<string, unknown>>;
     duplicate(sid: string): Record<string, unknown>;
     branch(sid: string, body: Record<string, unknown>): Record<string, unknown>;
+    /** Python `read_session_lineage_report` on the active profile's state.db. */
+    lineageReport(sid: string): Record<string, unknown>;
+    /** TAL-259: recovery reads the active profile's state.db, and a recovered sidecar joins that profile. */
+    private recoveryDeps;
+    recoveryAudit(): RecoveryAudit;
+    recoveryRepairSafe(): Promise<RecoveryRepair>;
+    /**
+     * Python `_handle_session_compression_recovery_start`: open a compression-exhausted session's focused continuation, an
+     * empty fork keeping its workspace, model, profile, toolsets and worktree. A retry opens the oldest continuation
+     * already started from it in the same profile; the source's lock makes concurrent starts converge on one child.
+     */
+    compressionRecoveryStart(sid: string): Promise<Record<string, unknown>>;
+    /** Python `find_compression_recovery_session`: the oldest same-profile continuation started from `sid`, cached or persisted. */
+    private compressionRecoveryChild;
+    /** The run that keeps `delete` answering 409, if any; stream status reports it so a draining client can wait on it (TAL-622). */
+    activeRunBlocking(sid: string): string | null;
     delete(sid: string): Promise<Record<string, unknown>>;
     cleanup(zeroOnly: boolean): Record<string, unknown>;
     import(body: Record<string, unknown>): Record<string, unknown>;