@maudecode/talaria-web 1.19.0 → 1.21.0

package/dist/sessions/service.d.ts

@@ -1,3 +1,5 @@
+import { type SessionActivityPhase, type ContextDetail } from '@maudecode/talaria-web-contracts';
+import { SessionPrefixIndex } from './prefix-index.js';
 /**
  * Route-level session operations (the Python `/api/session*` handlers): the
  * detail payload, list and search, and every mutation with its guards.
@@ -5,13 +7,14 @@
  */
 import type { AgentStorage, ChatReadiness, PendingSteer, RecoveryAudit, RunStatus, SessionGoal, SessionNotice, RecoveryRepair, SidecarResult } from '@maudecode/talaria-web-contracts';
 import type { RunJournal } from './journal.js';
+import type { OutboundDraft, OutboundDraftAction, OutboundDraftRef } from '@maudecode/talaria-web-contracts';
 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, type StateDbSessionSource } from './state-db.js';
+import { type stateDbSessionRow, type StateDbRead, type StateDbSessionSource, type StateDbSettlementRead } from './state-db.js';
 import { type CompressionJob } from './compress.js';
 import { type SidecarLike } from '../sidecar/client.js';
 import { type ToolResultView } from './merge.js';
@@ -29,15 +32,27 @@ export declare class HttpFailure extends Error {
 }
 /**
  * Python `_agent_runtime_barrier_response`: a stale local Agent checkout is refused with a typed 409 before the caller
- * mutates anything. Any other failure of the check is not a verdict and lets the caller proceed.
+ * mutates anything. An unavailable connection is refused before dispatch; other check failures are not a verdict
+ * and let the caller proceed.
  */
 export declare function ensureAgentRuntimeCurrent(sidecar: SidecarLike | null): Promise<void>;
+/** TAL-1254: how soon a worktree lock the sidecar could not confirm is tried again. */
+export declare const WORKTREE_RETAIN_RETRY_MS = 60000;
 /**
  * TAL-951: whether a chat turn would be admitted now. Ready and source-stale incompatible sidecars both run turn
  * admission's live check: recovery state can change after the handshake. A check
  * that cannot answer fails closed as `sidecar_unavailable`.
  */
 export declare function currentChatReadiness(sidecar: SidecarLike | null): Promise<ChatReadiness>;
+/** Lazy reads shared by one gate sequence, never across a lock wait or sidecar dispatch. */
+interface SessionGateReads {
+    sid: string;
+    owners: (profile?: string) => Promise<Map<string, StateDbSessionSource> | null>;
+    row: () => Promise<ReturnType<typeof stateDbSessionRow>>;
+    meta: () => Promise<Row | null>;
+    messages: (stitch: boolean) => Promise<Message[]>;
+    existing: () => Promise<Set<string>>;
+}
 export interface SessionServiceDeps {
     /** TAL-259: epoch seconds of the state directory's `recovery_stamping_since` marker. */
     recoveryStampingSince: () => Promise<number>;
@@ -48,6 +63,10 @@ export interface SessionServiceDeps {
     /** A profile whose deletion has started takes no new detached work. */
     profileDeleting?: (profile: string | null) => boolean;
     /** TAL-372: the session's background work receipts, for the delegation rows that started them. */
+    sessionActivity?: (sid: string, profile: string | null, opts?: {
+        excludeStreamId?: string;
+        terminalPhase?: SessionActivityPhase;
+    }) => Promise<SessionActivityPhase>;
     backgroundReceipts?: (sid: string) => Receipt[] | Promise<Receipt[]>;
     backgroundPending?: (sid: string) => Promise<Set<string>>;
     store: SessionStore;
@@ -74,6 +93,7 @@ export interface SessionServiceDeps {
         pendingSteers?: (streamId: string) => PendingSteer[];
         /** The live stream's server-selected presentation, else null. */
         runStatus?: (streamId: string) => RunStatus | null;
+        liveToolProgress?: (streamId: string) => Record<string, unknown>[];
         /** TAL-1006: the live stream's open compression span start (epoch seconds), else null. */
         compressionStartedAt?: (streamId: string) => number | null;
         /** TAL-899: whether a Stop holds the session's automatic turns until the user's next turn. */
@@ -110,9 +130,14 @@ 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-1040: the explicit launch route for `provider`: its configured endpoint (model, providers or custom_providers), else null. */
+    profileLaunchRoute?: (profile: string, provider: string) => {
+        provider: string;
+        baseUrl: 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. */
+    /** Explicit discovery for auxiliary title generation; ordinary turn admission uses only fresh cached repair evidence. */
     warmSessionModelRepair?: (profile?: string | null) => Promise<void>;
     yolo: {
         isEnabled: (sid: string) => boolean;
@@ -123,19 +148,13 @@ export interface SessionServiceDeps {
     cliSessions: (profile: string, opts: {
         sourceFilter: string | null;
         sessionIds?: readonly string[];
+        keepEmpty?: boolean;
+        sidebarRows?: boolean;
     }) => Promise<{
         rows: Row[];
         truncated: ReadonlySet<string>;
         storage: AgentStorage;
     }>;
-    /** `cliSessions` read on this thread, for the synchronous single-session lookups. */
-    cliSessionsSync: (profile: string, opts: {
-        sourceFilter: string | null;
-        sessionIds?: readonly string[];
-    }) => Promise<{
-        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;
@@ -154,6 +173,8 @@ export declare class SessionService {
     private readonly compressionJobs;
     /** TAL-1005: the turns now waiting on their session's compression job before they read its history. */
     private readonly compactionWaiters;
+    private worktreeRetainRetry;
+    private worktreesUnconfirmed;
     constructor(deps: SessionServiceDeps);
     private get store();
     /**
@@ -161,7 +182,7 @@ export declare class SessionService {
      * 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): Promise<string>;
-    /** A `@provider:` id is split; any other model an explicit pick did not just choose is checked against the catalog (TAL-542). */
+    /** Split qualified ids and opportunistically repair against fresh evidence; missing discovery never delays a turn. */
     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`
@@ -177,14 +198,18 @@ export declare class SessionService {
      */
     sessionIdVisible(raw: unknown): Promise<boolean>;
     private localTargets;
-    /** One receipt-backed physical target for every operation on a local conversation alias. */
-    resolveSessionId(sid: string): string;
+    /** One receipt-backed physical target for every operation on a local conversation alias, read on the state.db worker. */
+    resolveSessionId(sid: string): Promise<string>;
     /** Python `_lookup_cli_session_metadata(...).get('read_only')` plus the persisted sidecar flag and a not-claimable foreign owner. */
     private isReadOnlyImport;
     /** Python `_session_is_subagent_view_only`: a delegated child by any signal — the persisted sidecar or the state.db row. */
-    isSubagentViewOnly(sid: string): Promise<boolean>;
-    /** TAL-358: batched `sessions.source` owners from the active profile's state.db. */
-    readonly stateDbSources: (ids: string[], profile?: string) => Map<string, StateDbSessionSource> | null;
+    isSubagentViewOnly(sid: string, reads?: SessionGateReads): Promise<boolean>;
+    /** TAL-358: batched `sessions.source` owners from the active profile's state.db, read on the state.db worker (TAL-923). */
+    readonly stateDbSources: (ids: string[], profile?: string) => Promise<Map<string, StateDbSessionSource> | null>;
+    /** The owners of `byProfile`'s ids, read up front, as the synchronous lookup `withOwnerLocks` takes. */
+    private ownerSources;
+    /** `withOwnerLocks` with the owners read on the state.db worker, so a gate or payload never opens state.db on this thread. */
+    private ownerLocked;
     /**
      * 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
@@ -200,38 +225,54 @@ export declare class SessionService {
      */
     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. */
-    readOnlyReason(s: Session | string, profile?: string): Promise<string | null>;
+    readOnlyReason(s: Session | string, profile?: string, reads?: SessionGateReads): Promise<string | null>;
     private loadedReadOnlyReason;
-    /** A loaded session's final owner check stays synchronous with the protected sidecar dispatch. */
-    assertWritable(session: Session, profile?: string): void;
-    assertWritable(session: string, profile?: string): Promise<void>;
+    /**
+     * The final owner check before a protected sidecar dispatch or write: callers dispatch as soon as it resolves. The
+     * owner is the Agent's, which can change at any moment, so reading it on the state.db worker (TAL-923) widens no
+     * window Web could close; the session lock, where one is held, still serializes Web's own writes.
+     */
+    assertWritable(session: Session | string, profile?: string, reads?: SessionGateReads): Promise<void>;
     /** Controls can exist without a local session file; use the same id the sidecar will address. */
     idForMutation(sid: string): Promise<string>;
     isReadOnly(s: Session): Promise<boolean>;
     /** Recheck after the mutex wait; legacy local metadata/handoff actions keep their existing read-only allowance. */
     private withMutationLock;
     /** Full session for mutation, refusing read-only imports (Python `_get_or_materialize_session`). */
-    getForMutation(sid: string): Promise<Session>;
+    getForMutation(sid: string, reads?: SessionGateReads): Promise<Session>;
     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;
-    /** Preserve existing transcript provenance before a turn adds Agent rows from its starting database read. */
-    beginStateDbTurn(s: Session): StateDbRead;
+    stateDbRows(s: Session): Promise<Message[]>;
+    /**
+     * `stateDbRows` and whether the read succeeded on a state.db whose messages carry ids (TAL-493). TAL-1162: read on the
+     * state.db worker; a worker failure is a failed read.
+     */
+    stateDbRead(s: Session): Promise<StateDbRead>;
+    /** `stateDbRead`'s projection of the rows past `afterId` alone (the detail's page tail), on the state.db worker. */
+    stateDbTailRead(s: Session, afterId: number, unidentified: readonly ReadonlyMap<string, number>[]): Promise<StateDbRead & {
+        anchor?: Message;
+        requiresFullRead?: boolean;
+    }>;
+    /** The one read a turn's settlement builds its context from and settles with (`stateDbSettlementRead`). */
+    settlementRead(s: Session): Promise<StateDbSettlementRead>;
+    /**
+     * Preserve existing transcript provenance before a turn adds Agent rows from its starting database read. The stamp
+     * lands before this returns; the read follows.
+     */
+    beginStateDbTurn(s: Session): Promise<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[];
+    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?: {
+    markStateDbSeen(s: Session, read: StateDbRead, opts?: {
         boundary?: boolean;
     }): void;
     /**
@@ -248,7 +289,7 @@ export declare class SessionService {
         agentRows?: Message[] | null;
         startId?: number | null;
         startGeneration?: string | null;
-        read?: StateDbRead;
+        read: StateDbSettlementRead;
     }): 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
@@ -269,15 +310,22 @@ export declare class SessionService {
      * extended append-only with the Agent's state.db rows (a CLI continuation of this session reaches the model), except
      * for a compressed context whose anchor cannot be verified — that stays context-only.
      */
-    modelContext(s: Session, stateRows?: Message[]): Message[];
+    modelContext(s: Session, stateRows: Message[]): Message[];
+    /** `modelContext` over a state.db read taken now. */
+    readModelContext(s: Session): Promise<Message[]>;
     /**
      * TAL-518: the model context a `/btw` clone inherits: the chat's history plus its running turn's prompt, which
      * deferred save keeps out of `messages` and `context_messages` until settlement.
      */
-    sideQuestionContext(s: Session): Message[];
+    sideQuestionContext(s: Session): Promise<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 sessionGateReads;
+    /**
+     * Python `_lookup_cli_session_metadata`: the sidebar row for a state.db session in the active profile, else its plain
+     * row (a segment its chain's row does not name). Both are read by id: the sidebar listing would scan every session to
+     * rank its window (TAL-923).
+     */
     private lookupCliMeta;
     private claudeCodeRows;
     /** Python `_session_index_marks_was_webui`: an index row that once owned a WebUI sidecar (self-heal 404). */
@@ -287,7 +335,7 @@ export declare class SessionService {
      * a WebUI sidecar. `materialized` sessions are writeable (the caller persists the sidecar), `not_claimable` ones are
      * read-only stubs, `was_webui`/`no_foreign_state`/`invalid_sid` answer 404.
      */
-    claimOrSynthesizeCliSession(sid: string, metaIn?: Row | null): Promise<{
+    claimOrSynthesizeCliSession(sid: string, metaIn?: Row | null, reads?: SessionGateReads): Promise<{
         session: Session | null;
         reason: 'materialized' | 'not_claimable' | 'was_webui' | 'no_foreign_state' | 'invalid_sid';
     }>;
@@ -304,6 +352,12 @@ export declare class SessionService {
     backgroundLinked(s: Session, messages: unknown[]): Promise<unknown[]>;
     /** `compact()` plus messages, redacted for the wire (Python `_public_session_projection`). */
     publicSession(s: Session, withMessages?: boolean, messages?: Message[]): Promise<Record<string, unknown>>;
+    /** Opaque read identity, including context changes that do not alter display message counts. */
+    private contextDetailKey;
+    activityPhase(s: Session, opts?: {
+        excludeStreamId?: string;
+        terminalPhase?: SessionActivityPhase;
+    }): Promise<SessionActivityPhase | undefined>;
     /** `compact()` with the wire streaming/read-only flags (TAL-312), for replies that return the session row. */
     wireRow(s: Session): Promise<Record<string, unknown>>;
     /**
@@ -324,6 +378,7 @@ export declare class SessionService {
     private loadRevision;
     private readonly pageTails;
     private readonly pageContexts;
+    activitySummary(s: Session, turnId?: string): ReturnType<SessionPrefixIndex['activitySummary']>;
     private prefixIndex;
     /** Existing projections, once per complete turn range, in absolute transcript coordinates. */
     private deriveRange;
@@ -335,6 +390,9 @@ export declare class SessionService {
         msg_before?: string | null | undefined;
         resolve_model?: string | null | undefined;
     }): Promise<Record<string, unknown>>;
+    /** Project an already settled session without reloading it or running endpoint recovery/profile gates. */
+    windowedDetail(s: Session, limit: number): Promise<Record<string, unknown>>;
+    private detailPayload;
     /**
      * 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.
@@ -356,7 +414,7 @@ export declare class SessionService {
     clearStaleStreamState(session: Session): Promise<boolean>;
     /** Expand saved aliases in one worker query independently of the bounded native sidebar window. */
     private persistedAliasMetadata;
-    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources' | 'agentStorage' | 'pruneOrphanedImports' | 'webuiRows'>): Promise<{
+    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources' | 'agentStorage' | 'pruneOrphanedImports' | 'webuiRows' | 'webDiagnosticIds'>): Promise<{
         body: ListResponse;
         etag: string;
     }>;
@@ -378,11 +436,19 @@ export declare class SessionService {
     /** The first of a stored session's first `depth` messages (0: all) containing every term, with its redacted excerpt. */
     private contentMatch;
     status(sid: string): Promise<Record<string, unknown>>;
+    contextDetail(sid: string, expectedKey: string): Promise<ContextDetail>;
     usage(sid: string): Promise<Record<string, unknown>>;
+    /** Only retained, readable identities in the request profile can become search pointers. */
+    private referenceSource;
+    referenceSearch(q: string, params: Parameters<SessionService['list']>[0]): Promise<Record<string, unknown>>;
+    /** A referenced creation has one durable identity, including after a lost HTTP response or server restart. */
+    createWithReferences(body: Record<string, unknown>, create: (sessionId?: string, validate?: () => Promise<void>) => Promise<Session>): Promise<Session>;
     resolveNewSessionWorkspace(body: Record<string, unknown>, visiblePrevSessionId: string | null, profile: string | null): Promise<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?: {
+        sessionId?: string;
+        validateSources?: () => Promise<void>;
         worktree?: {
             path: string;
             branch: string;
@@ -390,12 +456,34 @@ export declare class SessionService {
             created_at: number;
         } | null;
     }): Promise<Session>;
+    /**
+     * TAL-1040: an `ignore_config` / `safe` chat starts through the active profile's Agent owner, which freezes the mode before
+     * any Agent import. That owner reads no profile default, so the launch route is explicit: the requested model, else this
+     * profile's default as a normal chat starts, with that provider's configured endpoint.
+     */
+    createDiagnostic(body: Record<string, unknown>, mode: 'ignore_config' | 'safe'): Promise<Record<string, unknown>>;
     /** Python `_persist_generated_session_title`: title + generated/manual flags under the session lock, then insights sync. */
     persistGeneratedTitle(sid: string, nextTitle: string, eventReason: string): Promise<Session>;
     rename(sid: string, rawTitle: unknown): Promise<Record<string, unknown>>;
     private pinChain;
     pin(sid: string, pinRequested: boolean): Promise<Record<string, unknown>>;
     private pinUnserialized;
+    /**
+     * TAL-1254: relock the worktrees of every unarchived worktree chat (or just `only`) for the running sidecar, so the
+     * Agent's worktree sweep reads them as live, and flag each one git no longer has as retained. Runs before a
+     * (re)started sidecar reports ready and when a chat is unarchived. The Agent's sweep runs outside Talaria, so a lock
+     * the sidecar could not confirm is retried until git takes it; meanwhile that tree keeps its flag.
+     */
+    retainWorktrees(call: SidecarLike['call'], only?: Session): Promise<void>;
+    /**
+     * Every persisted worktree chat, read from its own file: the index only narrows the files to read, since a crash
+     * between a save and its index update can leave a session out of the index or with a stale `archived`. A file that
+     * cannot be read now, or a session directory that cannot be listed, falls back to the index rows (`_unread`, so their
+     * flags are left alone) and counts in `unread`, which keeps retention retrying until every file has been read.
+     */
+    private worktreeSessionRows;
+    /** One pending retry at a time; a sidecar that is not ready by then retains everything in its next ready gate instead. */
+    private retryWorktreeRetention;
     archive(sid: string, archived: boolean): Promise<Record<string, unknown>>;
     move(sid: string, targetProjectId: string | null): Promise<Record<string, unknown>>;
     private readonly modelConfirmationKey;
@@ -499,7 +587,7 @@ export declare class SessionService {
      * the job's waiting turns added meanwhile (a prompt, a Stop) stay after the compressed context.
      */
     private compressSession;
-    /** Clear and delete share the profile-scoped, best-effort Agent session boundary. */
+    /** Profile-scoped, best-effort lifecycle delivery; archive only notifies plugins. */
     private finalizeSession;
     clear(sid: string): Promise<Record<string, unknown>>;
     retry(sid: string): Promise<Record<string, unknown>>;
@@ -507,7 +595,7 @@ export declare class SessionService {
     duplicate(sid: string): Promise<Record<string, unknown>>;
     branch(sid: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Python `read_session_lineage_report` on the active profile's state.db. */
-    lineageReport(sid: string): Record<string, unknown>;
+    lineageReport(sid: string): Promise<Record<string, unknown>>;
     /** TAL-259: recovery reads the active profile's state.db, and a recovered sidecar joins that profile. */
     private recoveryDeps;
     recoveryAudit(): Promise<RecoveryAudit>;
@@ -542,6 +630,13 @@ export declare class SessionService {
         result: string;
         result_view: ToolResultView;
     }>;
+    /** Artifact state lives in the producer DB, never in a directive, saved scene or client-posted content. */
+    reviewOutboundDraft(input: OutboundDraftRef & {
+        session_id: string;
+        tool_call_id: string;
+    } & Partial<OutboundDraftAction>): Promise<{
+        draft: OutboundDraft | null;
+    }>;
     createShare(sid: string): Promise<Record<string, unknown>>;
     revokeShare(sid: string): Promise<Record<string, unknown>>;
     loadShare(token: string): Promise<Record<string, unknown>>;