@maudecode/talaria-web 1.18.0 → 1.19.0

package/dist/sessions/turn.d.ts

@@ -4,11 +4,12 @@ import type { SessionService } from './service.js';
 import { HttpFailure } from './service.js';
 import type { SessionEventBus } from './events.js';
 import { StreamRegistry, SessionChannels } from './streams.js';
-import { type ClarifyAnswers, type PendingSteer, type SteerWithdrawn, type SteerWithdrawRequest } from '@maudecode/talaria-web-contracts';
+import { type RunStatus, type ClarifyAnswers, type PendingSteer, type SessionGoal, type SessionNotice, type SteerWithdrawn, type SteerWithdrawRequest, type SteerSendNowResponse } from '@maudecode/talaria-web-contracts';
 import { PendingPrompts } from './pending.js';
-import { RunJournal, type RunJournalWriter } from './journal.js';
+import type { RunJournal } from './journal.js';
 import { Session } from './session.js';
-import { type Config } from '../config/agent-config.js';
+import { type Config, type PersonalityRow } from '../config/agent-config.js';
+import { type BackgroundUpdate } from './background-updates.js';
 import type { WorkspaceRegistry } from '../workspace/workspaces.js';
 export declare const CHAT_LOCK_WAIT_SECONDS = 2;
 export interface TurnRunnerDeps {
@@ -49,6 +50,10 @@ export interface TurnRunnerDeps {
     configPath?: (profileHome: string) => string;
     /** The profile's config.yaml (turn budgets, reasoning effort, personality, delivery context); null when unavailable. */
     profileConfig?: (profile: string | null) => Promise<Config | null>;
+    /** TAL-901: the personalities the profile's Agent offers (`AgentConfig.agentPersonalities`); throws when it cannot list them. */
+    personalities?: (profile: string | null) => Promise<PersonalityRow[]>;
+    /** TAL-821: a provider's name as the profile's model catalog lists it (`ProviderCatalog.providerLabel`). */
+    providerLabel?: (profile: string | null, provider: string) => string;
     /** `auto_title_refresh_every`: a generated title follows the latest exchange every N exchanges; 0 turns it off. */
     titleRefreshEvery?: () => number;
     env?: Record<string, string | undefined>;
@@ -57,7 +62,10 @@ export interface TurnRunnerDeps {
 }
 export type SteerWithdrawReason = SteerWithdrawRequest['reason'];
 export interface StartTurnOptions {
+    /** The user's text: the transcript row, title, and `persist_user_message`. */
     msg: string;
+    /** What the model gets instead of `msg` (TAL-817: a prompt built-in's expansion); the Agent keeps it as the row's `api_content`. */
+    prompt?: string;
     attachments?: Record<string, unknown>[];
     workspace: string;
     model: string | null;
@@ -65,17 +73,32 @@ export interface StartTurnOptions {
     normalizedModel?: boolean;
     source?: string;
     goalRelated?: boolean;
+    /** Durable delegation identities acknowledged by this automatic turn. */
+    completionKeys?: string[];
+    backgroundUpdate?: BackgroundUpdate;
     ephemeral?: boolean;
+    /** TAL-801: a spoken turn, which the Agent runs on the profile's `auxiliary.voice_chat` slot. */
+    voiceTurn?: boolean;
+    /** TAL-818: the starting client renders `connect_card`; other turns keep the Agent's plain connect links. */
+    connectCard?: boolean;
+    /** The starting client can answer the masked skill-secret variant. */
+    skillSecret?: boolean;
     /** The settled turn's answer: its last non-error assistant reply, or `` when it produced none. */
-    onDone?: (answer: string) => void;
+    onDone?: (answer: string) => void | Promise<void>;
     /** Runs on every other end: an error, a cancel, or a writeback another stream took over (Python background runner: `complete_background(..., "(background task failed)")`). */
-    onFailed?: (failure: TurnFailure) => void;
+    onFailed?: (failure: TurnFailure) => void | Promise<void>;
 }
 /** How a turn that did not complete ended: the `apperror` frame it sent, if any, and whether it was cancelled. */
 export interface TurnFailure {
     apperror: Record<string, unknown> | null;
     cancelled: boolean;
 }
+export type AdmissionResult = StartTurnResponse & {
+    _status?: number;
+    error?: string;
+    active_stream_id?: string | null;
+    held?: boolean;
+};
 export interface StartTurnResponse {
     stream_id?: string;
     session_id?: string;
@@ -115,7 +138,7 @@ export declare function explicitTextSignal(cfg: Config): boolean;
 export declare const GATEWAY_APPROVAL_RELAY_UNAVAILABLE = "Gateway approval could not be relayed because the active run is unavailable. Reopen the session or retry after it reconnects.";
 export declare class TurnRunner {
     readonly deps: TurnRunnerDeps;
-    readonly writers: Map<string, RunJournalWriter>;
+    readonly writers: Map<string, import("./storage/backend.js").JournalWriter>;
     private readonly sessionPuts;
     /** Per-session chain for sidecar YOLO mutation + local commit, so opposing toggles cannot interleave. */
     private readonly yoloChains;
@@ -132,6 +155,10 @@ export declare class TurnRunner {
     private readonly liveUsage;
     /** TAL-397: each running turn's latest todo list, which an error or cancel keeps on the session. */
     private readonly liveTodos;
+    /** The current presentation, scoped to its owning stream and released on every terminal path. */
+    private readonly runStatuses;
+    /** TAL-1006: each live stream's open compression span, by its start (epoch seconds). */
+    private readonly compressionSpans;
     /** Streams whose run completed (`done` emitted) and only await title work; a late cancel is a no-op for these. */
     private readonly settledStreams;
     /** The last adaptive title refresh per session; a successor turn's refresh runs after it (TAL-589). */
@@ -145,14 +172,38 @@ export declare class TurnRunner {
     private readonly stopContexts;
     /** Each turn's worker, so a stopped background turn can be awaited before the user's turn takes the session. */
     private readonly workers;
+    /** TAL-899: sessions whose user pressed Stop; no automatic turn starts in them until the user's next turn is admitted. */
+    private readonly stopHeld;
+    private readonly notices;
+    private readonly goals;
     constructor(deps: TurnRunnerDeps);
     private get registry();
+    /** TAL-899: whether a Stop holds the session's automatic turns (session `automatic_turns_held`). */
+    automaticTurnsHeld(sessionId: string): Promise<boolean>;
+    /** TAL-803: the Agent's active notices for the session (session `notices`). */
+    sessionNotices(sessionId: string): SessionNotice[];
+    /** TAL-808: the session's standing goal (session `goal`). */
+    sessionGoal(sessionId: string): SessionGoal | null;
+    /**
+     * TAL-808: reads the session's goal from the Agent and, when its view changed, sends `session_goal` on `put` (else the
+     * session's live stream) and `sessions_changed`, which reloads the session for a client between turns.
+     */
+    refreshGoal(s: Pick<Session, 'session_id' | 'profile'>, put?: (event: string, data: Record<string, unknown>) => Promise<void>): Promise<void>;
+    /** TAL-808: a session's first detail after a restart reads its goal before answering, so it tells no one else. */
+    loadGoal(sessionId: string): Promise<void>;
+    /** The Agent's `goals.get` into the cache, and a re-read when a timed park ends; whether the view changed. A failed read keeps the last one. */
+    private readGoal;
+    /** Hygiene sweep: a deleted session's hold, notices and goal go with it (TAL-899, TAL-803, TAL-808). */
+    sweep(): Promise<void>;
+    /**
+     * Admit automatic turns through the same workspace recovery and model resolution as user turns. After the user's Stop
+     * none starts (TAL-899): the answer is a `held` 409, and the caller keeps its work for the user's next turn.
+     */
+    startServerTurn(session: Session, opts: Pick<StartTurnOptions, 'msg' | 'source' | 'goalRelated' | 'completionKeys' | 'backgroundUpdate'>): Promise<AdmissionResult>;
+    /** A user's turn; admitting it releases the hold a Stop put on automatic turns (TAL-899). */
+    start(session: Session, opts: StartTurnOptions): Promise<AdmissionResult>;
     /** Python `_start_chat_stream_for_session`: persist pending state, register the channel, launch the worker. */
-    start(session: Session, opts: StartTurnOptions): StartTurnResponse & {
-        _status?: number;
-        error?: string;
-        active_stream_id?: string | null;
-    };
+    private admit;
     /** Resolves once the stream's worker has ended (settled, failed, or torn down); it never rejects. */
     finished(streamId: string): Promise<void>;
     /** Python `_checkpoint_user_message_for_eager_session_save`. */
@@ -174,15 +225,21 @@ export declare class TurnRunner {
      */
     private buildUserMessage;
     /** The settled session as a terminal frame carries it: the display window, redacted. */
-    publicTerminalSession(s: Session): Record<string, unknown>;
+    publicTerminalSession(s: Session): Promise<Record<string, unknown>>;
     /**
      * Python `_session_payload_with_terminal_window`: the same visible-message window contract as `GET /api/session?
      * msg_limit=` (renderable rows, limited payload shape, windowed tool calls, todo state) with the full count.
      */
     private terminalSessionPayload;
+    /** TAL-540, Python `_live_usage_snapshot`: a finished compression's frame, with the counters and the ring's post-compression figures, so clients update before `done`. */
+    private compressedFrame;
+    /** Release only the pending admission metadata; transcript settlement belongs to the caller. */
+    private clearPendingTurn;
     /** Python `_materialize_pending_user_turn_before_error` + error message append + save. */
     /** `runtimeProvider`: the provider the Agent resolved for the turn, when it reported one. */
     private persistError;
+    /** Every terminal path carries the same starting read's id and generation into settlement. */
+    private settleStateDb;
     /**
      * TAL-921: the model context a turn that ends without its settled result leaves: the work its Agent reported, else the
      * rows it committed past its starting read in `read`, the read its settlement uses.
@@ -207,9 +264,20 @@ export declare class TurnRunner {
     private keepLiveState;
     private teardown;
     /** Journal files with a live writer (retention must leave them alone). */
-    activeJournalPaths(): Set<string>;
     /** Python `_generate_llm_session_title_via_aux`: aux-route statuses (`llm_aux`, `llm_aux_retry`, `llm_*_aux`). */
     private llmTitle;
+    /**
+     * TAL-902: `/refine [focus]` starts the Agent's memory/skill review of the chat's model context on its agent
+     * (`chat.refine`, the agent a turn would build); no turn starts. Without a chat, while a turn runs, or before anything
+     * was said it answers with the Agent's wording instead.
+     */
+    refine(s: Session | null, focus: string): Promise<string>;
+    /**
+     * TAL-903: the workspace a session's agent is built at, and whether it is a host path (the profile's terminal runs
+     * locally). Only then does the Agent anchor AGENTS.md discovery and its memory provider there; `chat.start` and
+     * `chat.refine` send the same pair, so the agent `/refine` builds is the one the next turn reuses.
+     */
+    private agentWorkspace;
     /**
      * Python `generate_session_title_for_session`: on-demand title from the persisted transcript; never touches
      * `llm_title_generated`. An explicit regenerate runs even with `auxiliary.title_generation.enabled` off (TAL-531).
@@ -242,6 +310,7 @@ export declare class TurnRunner {
         cancelled: boolean;
         withdrawn: SteerWithdrawn[];
     }>;
+    private stop;
     /**
      * TAL-460: a user's message never joins a background turn. That turn stops quietly (`finalizeCancelled`) and its worker
      * unwinds before the user's turn is admitted, so two Agent runs never share the session. True when one was stopped.
@@ -291,6 +360,9 @@ export declare class TurnRunner {
     private settleConsumedSteers;
     /** What every client shows for a pending steer; the server decides which actions it offers. */
     private pendingSteerView;
+    runStatus(streamId: string): RunStatus | null;
+    /** TAL-1006: the start (epoch seconds) of the stream's open compression span, else null. */
+    compressionStartedAt(streamId: string): number | null;
     /** TAL-424: the active stream's pending steers, oldest first (session detail `pending_steers`). */
     pendingSteers(streamId: string): PendingSteer[];
     private withSteerChain;
@@ -314,9 +386,7 @@ export declare class TurnRunner {
      * once); during tools it goes last on the Agent's queue and stays `sending_now` until taken; with nothing live it
      * stays pending.
      */
-    sendSteerNow(sessionId: string, steerId: string): Promise<{
-        redirected: boolean;
-    }>;
+    sendSteerNow(sessionId: string, steerId: string): Promise<SteerSendNowResponse>;
     respondApproval(sessionId: string, choice: string, approvalId: string, enableYolo: boolean): Promise<Record<string, unknown>>;
     /** The live chat frame after approvals were withdrawn: the new queue head, or `approval_cleared` once none is left. */
     private approvalHeadFrame;
@@ -333,7 +403,7 @@ export declare class TurnRunner {
      * prompt is queued; `invalid` when the answers do not fit its steps; `ok:false` without either when the sidecar
      * did not acknowledge (prompt retained).
      */
-    respondClarify(sessionId: string, clarifyId: string, reply: string | ClarifyAnswers): Promise<{
+    respondClarify(sessionId: string, clarifyId: string, reply: string | ClarifyAnswers | null): Promise<{
         ok: boolean;
         response?: string;
         stale?: boolean;