@qduc/term2 0.7.2 → 0.8.0

package/dist/services/session-manager.d.ts

@@ -0,0 +1,57 @@
+import type { UserTurn } from '../types/user-turn.js';
+import type { ConversationAgentClient } from './conversation-agent-client.js';
+import type { ISettingsService } from './service-interfaces.js';
+import { ConversationStore } from './conversation-store.js';
+import { ConversationLogger } from './conversation-logger.js';
+import type { StateSnapshot } from './conversation-log-events.js';
+import { SessionLifecycle } from './session-lifecycle.js';
+import { SessionToolTracker } from './session-tool-tracker.js';
+import { SessionInputPlanner } from './session-input-planner.js';
+import { type SavedToolExecution } from './tool-execution-ledger.js';
+/**
+ * Facade that owns state/persistence/undo/shell-context/mode-notice operations
+ * for the conversation session. Extracted from ConversationSession to reduce
+ * its surface area and make the delegation boundary explicit.
+ */
+export declare class SessionManager {
+    #private;
+    constructor(deps: {
+        conversationStore: ConversationStore;
+        toolTracker: SessionToolTracker;
+        state: SessionLifecycle;
+        conversationLogger: ConversationLogger;
+        agentClient: ConversationAgentClient;
+        settingsService?: ISettingsService;
+        inputPlanner: SessionInputPlanner;
+    });
+    reset(): void;
+    undoLastUserTurn(): {
+        text: string;
+        images?: UserTurn['images'];
+    } | null;
+    undoNUserTurns(n: number): {
+        text: string;
+        images?: UserTurn['images'];
+    } | null;
+    listUserTurns(): {
+        index: number;
+        text: string;
+        imageCount: number;
+    }[];
+    getCurrentSnapshot(): StateSnapshot;
+    exportState(): {
+        history: unknown[];
+        previousResponseId: string | null;
+        toolLedger: SavedToolExecution[];
+    };
+    importState(state: {
+        history: unknown[];
+        previousResponseId: string | null;
+        toolLedger?: SavedToolExecution[];
+        updatedAt?: string;
+    }): void;
+    addShellContext(historyText: string): void;
+    queueModeNotice(text: string): void;
+    previewLargeUncachedInput(input: string | UserTurn, now?: number): import("./large-uncached-input-guard.js").LargeUncachedInputDecision;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/services/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../source/services/session-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAkC,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrG;;;;GAIG;AACH,qBAAa,cAAc;;gBASb,IAAI,EAAE;QAChB,iBAAiB,EAAE,iBAAiB,CAAC;QACrC,WAAW,EAAE,kBAAkB,CAAC;QAChC,KAAK,EAAE,gBAAgB,CAAC;QACxB,kBAAkB,EAAE,kBAAkB,CAAC;QACvC,WAAW,EAAE,uBAAuB,CAAC;QACrC,eAAe,CAAC,EAAE,gBAAgB,CAAC;QACnC,YAAY,EAAE,mBAAmB,CAAC;KACnC;IAYD,KAAK,IAAI,IAAI;IAMb,gBAAgB,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;KAAE,GAAG,IAAI;IAOxE,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;KAAE,GAAG,IAAI;IAO/E,aAAa,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE;IAMtE,kBAAkB,IAAI,aAAa;IAgBnC,WAAW,IAAI;QACb,OAAO,EAAE,OAAO,EAAE,CAAC;QACnB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,UAAU,EAAE,kBAAkB,EAAE,CAAC;KAClC;IAID,WAAW,CAAC,KAAK,EAAE;QACjB,OAAO,EAAE,OAAO,EAAE,CAAC;QACnB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAMR,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI1C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAInC,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,SAAa;CAYrE"}

package/dist/services/session-manager.js

@@ -0,0 +1,87 @@
+import { reconcileHistoryWithToolLedger } from './tool-execution-ledger.js';
+import { getMethod } from './interruption-info.js';
+/**
+ * Facade that owns state/persistence/undo/shell-context/mode-notice operations
+ * for the conversation session. Extracted from ConversationSession to reduce
+ * its surface area and make the delegation boundary explicit.
+ */
+export class SessionManager {
+    #conversationStore;
+    #toolTracker;
+    #state;
+    #conversationLogger;
+    #agentClient;
+    #settingsService;
+    #inputPlanner;
+    constructor(deps) {
+        this.#conversationStore = deps.conversationStore;
+        this.#toolTracker = deps.toolTracker;
+        this.#state = deps.state;
+        this.#conversationLogger = deps.conversationLogger;
+        this.#agentClient = deps.agentClient;
+        this.#settingsService = deps.settingsService;
+        this.#inputPlanner = deps.inputPlanner;
+    }
+    // ── Reset ─────────────────────────────────────────────────────────
+    reset() {
+        this.#state.resetSession();
+    }
+    // ── Undo ──────────────────────────────────────────────────────────
+    undoLastUserTurn() {
+        const removed = this.#conversationStore.removeLastUserTurn();
+        if (removed === null)
+            return null;
+        this.#afterUndo(1);
+        return removed;
+    }
+    undoNUserTurns(n) {
+        const removed = this.#conversationStore.removeNLastUserTurns(n);
+        if (removed === null)
+            return null;
+        this.#afterUndo(n);
+        return removed;
+    }
+    listUserTurns() {
+        return this.#conversationStore.listUserTurns();
+    }
+    // ── Snapshot / State ──────────────────────────────────────────────
+    getCurrentSnapshot() {
+        const providerFn = getMethod(this.#agentClient, 'getProvider');
+        const provider = providerFn
+            ? providerFn.call(this.#agentClient)
+            : this.#settingsService?.get('agent.provider');
+        const model = this.#settingsService?.get('agent.model');
+        return {
+            history: reconcileHistoryWithToolLedger(this.#conversationStore.getHistory(), this.#toolTracker.export())
+                .history,
+            previousResponseId: this.#state.exportPersistedState().previousResponseId,
+            toolLedger: this.#toolTracker.export(),
+            ...(model ? { model } : {}),
+            ...(provider ? { provider } : {}),
+        };
+    }
+    exportState() {
+        return this.#state.exportPersistedState();
+    }
+    importState(state) {
+        this.#state.importPersistedState(state);
+    }
+    // ── Shell context / mode notice ───────────────────────────────────
+    addShellContext(historyText) {
+        this.#conversationStore.addShellContext(historyText);
+    }
+    queueModeNotice(text) {
+        this.#state.pendingModeNotice = text;
+    }
+    previewLargeUncachedInput(input, now = Date.now()) {
+        return this.#inputPlanner.previewLargeUncachedInput(input, now, {
+            pendingModeNotice: this.#state.pendingModeNotice,
+        });
+    }
+    // ── Private helpers ───────────────────────────────────────────────
+    #afterUndo(count) {
+        this.#state.afterUndo();
+        this.#conversationLogger.log({ type: 'undo', removedUserTurns: count, snapshot: this.getCurrentSnapshot() });
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/services/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../../source/services/session-manager.ts"],"names":[],"mappings":"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"}

package/dist/services/session-manager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-manager.test.d.ts.map

package/dist/services/session-manager.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.test.d.ts","sourceRoot":"","sources":["../../source/services/session-manager.test.ts"],"names":[],"mappings":""}

package/dist/services/session-manager.test.js

@@ -0,0 +1,38 @@
+// @ts-nocheck - focused collaborator test with a tiny state stub
+import test from 'ava';
+import { SessionManager } from './session-manager.js';
+test('getCurrentSnapshot reads previousResponseId from persisted state, not a state accessor', (t) => {
+    const state = {
+        exportPersistedState: () => ({
+            history: [],
+            previousResponseId: 'resp-1',
+            toolLedger: [],
+        }),
+        resetSession: () => undefined,
+        afterUndo: () => undefined,
+        pendingModeNotice: null,
+    };
+    const manager = new SessionManager({
+        conversationStore: {
+            getHistory: () => [],
+            removeLastUserTurn: () => null,
+            removeNLastUserTurns: () => null,
+            listUserTurns: () => [],
+            addShellContext: () => undefined,
+        },
+        toolTracker: {
+            export: () => [],
+        },
+        state,
+        conversationLogger: {
+            log: () => undefined,
+        },
+        agentClient: {},
+        inputPlanner: {
+            previewLargeUncachedInput: () => ({ kind: 'pass' }),
+        },
+    });
+    const snapshot = manager.getCurrentSnapshot();
+    t.is(snapshot.previousResponseId, 'resp-1');
+});
+//# sourceMappingURL=session-manager.test.js.map

package/dist/services/session-manager.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.test.js","sourceRoot":"","sources":["../../source/services/session-manager.test.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,IAAI,MAAM,KAAK,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,IAAI,CAAC,wFAAwF,EAAE,CAAC,CAAC,EAAE,EAAE;IACnG,MAAM,KAAK,GAAG;QACZ,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YAC3B,OAAO,EAAE,EAAE;YACX,kBAAkB,EAAE,QAAQ;YAC5B,UAAU,EAAE,EAAE;SACf,CAAC;QACF,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS;QAC7B,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;QAC1B,iBAAiB,EAAE,IAAI;KACxB,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC;QACjC,iBAAiB,EAAE;YACjB,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE;YACpB,kBAAkB,EAAE,GAAG,EAAE,CAAC,IAAI;YAC9B,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAI;YAChC,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE;YACvB,eAAe,EAAE,GAAG,EAAE,CAAC,SAAS;SACjC;QACD,WAAW,EAAE;YACX,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE;SACjB;QACD,KAAK;QACL,kBAAkB,EAAE;YAClB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;SACrB;QACD,WAAW,EAAE,EAAE;QACf,YAAY,EAAE;YACZ,yBAAyB,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACpD;KACF,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAC9C,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC"}

package/dist/services/session-retry-orchestrator.d.ts

@@ -0,0 +1,135 @@
+import { type RunState } from '@openai/agents';
+import type { AgentStream } from './agent-stream.js';
+import type { ConversationEvent } from './conversation-events.js';
+import type { ConversationAgentClient } from './conversation-agent-client.js';
+import type { ILoggingService } from './service-interfaces.js';
+import { type RetryDecision } from './retry-handler.js';
+import type { UserTurn } from '../types/user-turn.js';
+import { GenerationGuard } from './generation-guard.js';
+import type { ClassifiedFailure } from './retry-contracts.js';
+export type RetryState = {
+    transientRetryCount?: number;
+    flexServiceTierFallbackCount?: number;
+    hallucinationRetryCount?: number;
+    transportFallbackRetryCount?: number;
+};
+export type RetryDispatchContext = {
+    error: unknown;
+    turn: UserTurn;
+    gen: number;
+    stream: AgentStream | null;
+    retries: RetryState;
+    maxTransientRetries: number;
+    maxModelRetries?: number;
+};
+export type RetryOutcome = {
+    kind: 'stale_generation';
+} | {
+    kind: 'unrecoverable';
+} | {
+    kind: 'retry_flex_fallback';
+    runOptions: {
+        skipUserMessage: boolean;
+        retries: RetryState;
+        maxModelRetries?: number;
+    };
+    useStandardServiceTier: true;
+} | {
+    kind: 'retry_transient';
+    runOptions: {
+        skipUserMessage: boolean;
+        retries: RetryState;
+        maxModelRetries?: number;
+        resumeState?: RunState<any, any>;
+        resumePreviousResponseId?: string | null;
+    };
+    delayMs: number;
+    isResuming: boolean;
+    restoreOptions?: {
+        removeLastUserMessage?: boolean;
+    };
+} | {
+    kind: 'retry_transport_downgrade';
+    runOptions: {
+        skipUserMessage: boolean;
+        retries: RetryState;
+        maxModelRetries?: number;
+    };
+    restoreOptions?: {
+        removeLastUserMessage?: boolean;
+    };
+} | {
+    kind: 'retry_hallucination';
+    runOptions: {
+        skipUserMessage?: boolean;
+        retries?: RetryState;
+        maxModelRetries?: number;
+    };
+    hadStream: boolean;
+    addErrorContext?: string;
+};
+/**
+ * Owns retry state and retry decision logic for a conversation session.
+ *
+ * The session delegates to this orchestrator for retry classification,
+ * retry event construction, and retry plan generation. The session keeps
+ * the actual rerun/stream orchestration (recursive `yield* run(...)`) to
+ * avoid the pitfall of the orchestrator becoming a session-in-disguise.
+ */
+export declare class SessionRetryOrchestrator {
+    #private;
+    private logger;
+    private sessionId;
+    private agentClient;
+    private retryHandler;
+    private generationGuard;
+    private allowFreshStartRetries;
+    private chainingBroken;
+    private inputSurgeKind;
+    constructor(logger: ILoggingService, sessionId: string, agentClient: ConversationAgentClient, allowFreshStartRetries?: boolean, generationGuard?: GenerationGuard);
+    get currentGeneration(): number;
+    isCurrentGeneration(gen: number): boolean;
+    incrementGeneration(): void;
+    get chainingBrokenState(): boolean;
+    breakChaining(): void;
+    get inputSurgeKindState(): 'delta' | 'full_history';
+    setInputSurgeKind(kind: 'delta' | 'full_history'): void;
+    get freshStartRetriesAllowed(): boolean;
+    classifyError(opts: {
+        error: unknown;
+        transientRetryCount: number;
+        transportFallbackRetryCount: number;
+        hallucinationRetryCount: number;
+        flexServiceTierFallbackCount: number;
+        maxTransientRetries: number;
+        stream: AgentStream | null;
+        maxModelRetries?: number;
+    }): RetryDecision;
+    classifyForStart(opts: {
+        error: unknown;
+        transientRetryCount: number;
+        transportFallbackRetryCount: number;
+        hallucinationRetryCount: number;
+        flexServiceTierFallbackCount: number;
+        maxTransientRetries: number;
+        stream: AgentStream | null;
+        maxModelRetries?: number;
+    }): ClassifiedFailure;
+    classifyForContinuation(opts: {
+        error: unknown;
+        transientRetryCount: number;
+        stream: AgentStream | null;
+        maxTransientRetries: number;
+    }): RetryDecision;
+    handleRetryDecision(ctx: RetryDispatchContext): AsyncGenerator<ConversationEvent, RetryOutcome>;
+    restoreForRetry(opts: {
+        ledgerSnapshot: import('./tool-execution-ledger.js').SavedToolExecution[];
+        stream: AgentStream | null;
+        toolLedger: import('./tool-execution-ledger.js').ToolExecutionLedger;
+        conversationStore: import('./conversation-store.js').ConversationStore;
+        clearPreviousResponseId: () => void;
+        restoreCompletedToolLedgerEntries: (snapshot: import('./tool-execution-ledger.js').SavedToolExecution[]) => void;
+        removeLastUserMessage?: () => void;
+    }): void;
+}
+//# sourceMappingURL=session-retry-orchestrator.d.ts.map

package/dist/services/session-retry-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-retry-orchestrator.d.ts","sourceRoot":"","sources":["../../source/services/session-retry-orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/services/session-retry-orchestrator.js

@@ -0,0 +1,297 @@
+import { MAX_HALLUCINATION_RETRIES } from './conversation-retry-policy.js';
+import { RetryHandler } from './retry-handler.js';
+import { extractHistoryLength } from './stream-snapshot.js';
+import { GenerationGuard } from './generation-guard.js';
+/**
+ * Owns retry state and retry decision logic for a conversation session.
+ *
+ * The session delegates to this orchestrator for retry classification,
+ * retry event construction, and retry plan generation. The session keeps
+ * the actual rerun/stream orchestration (recursive `yield* run(...)`) to
+ * avoid the pitfall of the orchestrator becoming a session-in-disguise.
+ */
+export class SessionRetryOrchestrator {
+    logger;
+    sessionId;
+    agentClient;
+    retryHandler;
+    generationGuard;
+    allowFreshStartRetries;
+    chainingBroken = false;
+    inputSurgeKind = 'delta';
+    constructor(logger, sessionId, agentClient, allowFreshStartRetries = true, generationGuard) {
+        this.logger = logger;
+        this.sessionId = sessionId;
+        this.agentClient = agentClient;
+        this.allowFreshStartRetries = allowFreshStartRetries;
+        this.generationGuard = generationGuard ?? new GenerationGuard();
+        this.retryHandler = new RetryHandler(this.logger, this.sessionId, this.agentClient);
+    }
+    get currentGeneration() {
+        return this.generationGuard.currentGeneration;
+    }
+    isCurrentGeneration(gen) {
+        return this.generationGuard.isCurrent(gen);
+    }
+    incrementGeneration() {
+        this.generationGuard.invalidate();
+    }
+    get chainingBrokenState() {
+        return this.chainingBroken;
+    }
+    breakChaining() {
+        this.chainingBroken = true;
+    }
+    get inputSurgeKindState() {
+        return this.inputSurgeKind;
+    }
+    setInputSurgeKind(kind) {
+        this.inputSurgeKind = kind;
+    }
+    get freshStartRetriesAllowed() {
+        return this.allowFreshStartRetries;
+    }
+    classifyError(opts) {
+        const streamHistoryLength = extractHistoryLength(opts.stream);
+        return this.retryHandler.classifyError({
+            ...opts,
+            streamHistoryLength,
+        });
+    }
+    classifyForStart(opts) {
+        let decision = this.classifyError(opts);
+        if (!this.allowFreshStartRetries && !opts.stream && decision.kind !== 'none' && decision.kind !== 'unrecoverable') {
+            this.logger.warn('Retry requires fresh start but fresh-start retries are disabled for this session', {
+                eventType: 'retry.fresh_start_blocked',
+                category: 'retry',
+                phase: 'retry',
+                sessionId: this.sessionId,
+                traceId: this.logger.getCorrelationId(),
+                retryKind: decision.kind,
+                errorMessage: opts.error instanceof Error ? opts.error.message : String(opts.error),
+            });
+            decision = { kind: 'unrecoverable' };
+        }
+        return this.#toClassifiedFailure(decision);
+    }
+    #toClassifiedFailure(decision) {
+        switch (decision.kind) {
+            case 'flex_fallback':
+                return { kind: 'service_tier_fallback' };
+            case 'transient':
+                return { kind: 'transient', attempt: decision.attempt, delayMs: decision.delay };
+            case 'transport_downgrade':
+                return { kind: 'transport_downgrade' };
+            case 'hallucination':
+                if (decision.decision.kind !== 'retry') {
+                    return { kind: 'unrecoverable' };
+                }
+                return {
+                    kind: 'model_retry',
+                    errorContext: decision.decision.shouldInjectErrorContext ? decision.decision.errorContextMessage : undefined,
+                    retryEvent: decision.decision.retryEvent,
+                };
+            case 'none':
+            case 'unrecoverable':
+                return { kind: 'unrecoverable' };
+        }
+    }
+    classifyForContinuation(opts) {
+        const decision = this.classifyError({
+            error: opts.error,
+            transientRetryCount: opts.transientRetryCount,
+            transportFallbackRetryCount: 0,
+            hallucinationRetryCount: 0,
+            flexServiceTierFallbackCount: 0,
+            maxTransientRetries: opts.maxTransientRetries,
+            stream: opts.stream,
+            maxModelRetries: undefined,
+        });
+        if (!this.allowFreshStartRetries && !opts.stream && decision.kind !== 'none' && decision.kind !== 'unrecoverable') {
+            this.logger.warn('Retry requires fresh start but fresh-start retries are disabled for this session', {
+                eventType: 'retry.fresh_start_blocked',
+                category: 'retry',
+                phase: 'retry',
+                sessionId: this.sessionId,
+                traceId: this.logger.getCorrelationId(),
+                retryKind: decision.kind,
+                errorMessage: opts.error instanceof Error ? opts.error.message : String(opts.error),
+            });
+            return { kind: 'unrecoverable' };
+        }
+        return decision;
+    }
+    async *handleRetryDecision(ctx) {
+        const { error, gen, stream, retries, maxTransientRetries, maxModelRetries } = ctx;
+        void ctx.turn;
+        const { transientRetryCount = 0, flexServiceTierFallbackCount = 0, hallucinationRetryCount = 0, transportFallbackRetryCount = 0, } = retries;
+        const streamHistoryLength = extractHistoryLength(stream);
+        let decision = this.retryHandler.classifyError({
+            error,
+            transientRetryCount,
+            transportFallbackRetryCount,
+            hallucinationRetryCount,
+            flexServiceTierFallbackCount,
+            maxTransientRetries,
+            stream,
+            streamHistoryLength,
+            maxModelRetries,
+        });
+        if (!this.allowFreshStartRetries && !stream && decision.kind !== 'none' && decision.kind !== 'unrecoverable') {
+            this.logger.warn('Retry requires fresh start but fresh-start retries are disabled for this session', {
+                eventType: 'retry.fresh_start_blocked',
+                category: 'retry',
+                phase: 'retry',
+                sessionId: this.sessionId,
+                traceId: this.logger.getCorrelationId(),
+                retryKind: decision.kind,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+            decision = { kind: 'unrecoverable' };
+        }
+        switch (decision.kind) {
+            case 'flex_fallback': {
+                this.#logRetry('Flex service tier timed out, retrying with standard service tier', 'retry.flex_service_tier', {
+                    retryType: 'flex_service_tier',
+                    retryAttempt: 1,
+                    attempt: 1,
+                    maxRetries: 1,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
+                yield {
+                    type: 'retry',
+                    toolName: 'service_tier',
+                    attempt: 1,
+                    maxRetries: 1,
+                    errorMessage: 'Flex service tier timed out. Falling back to standard service tier and retrying.',
+                    retryType: 'flex_service_tier',
+                };
+                if (!this.isCurrentGeneration(gen)) {
+                    return { kind: 'stale_generation' };
+                }
+                return {
+                    kind: 'retry_flex_fallback',
+                    runOptions: {
+                        skipUserMessage: true,
+                        retries: { ...retries, flexServiceTierFallbackCount: flexServiceTierFallbackCount + 1 },
+                        maxModelRetries,
+                    },
+                    useStandardServiceTier: true,
+                };
+            }
+            case 'transient': {
+                const isResuming = Boolean(stream?.state && typeof this.agentClient.continueRunStream === 'function');
+                this.#logRetry('Transient upstream error detected, retrying turn', 'retry.transient', {
+                    retryType: 'upstream',
+                    retryAttempt: decision.attempt,
+                    attempt: decision.attempt,
+                    maxRetries: maxTransientRetries,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    delayMs: decision.delay,
+                });
+                yield {
+                    type: 'retry',
+                    toolName: isResuming ? 'continuation' : 'turn',
+                    attempt: decision.attempt,
+                    maxRetries: maxTransientRetries,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    retryType: 'upstream',
+                };
+                if (!this.isCurrentGeneration(gen)) {
+                    return { kind: 'stale_generation' };
+                }
+                await new Promise((resolve) => setTimeout(resolve, decision.delay));
+                if (!this.isCurrentGeneration(gen)) {
+                    return { kind: 'stale_generation' };
+                }
+                return {
+                    kind: 'retry_transient',
+                    runOptions: {
+                        skipUserMessage: Boolean(stream),
+                        retries: { ...retries, transientRetryCount: decision.attempt },
+                        maxModelRetries,
+                        resumeState: isResuming ? stream?.state : undefined,
+                        resumePreviousResponseId: isResuming ? stream?.lastResponseId ?? null : undefined,
+                    },
+                    delayMs: decision.delay,
+                    isResuming,
+                    restoreOptions: isResuming ? undefined : { removeLastUserMessage: true },
+                };
+            }
+            case 'transport_downgrade': {
+                const attempt = transportFallbackRetryCount + 1;
+                this.#logRetry('Transient upstream error exhausted WS retries, forcing HTTP fallback', 'retry.transport_fallback', {
+                    retryType: 'upstream',
+                    retryAttempt: attempt,
+                    attempt,
+                    maxRetries: 1,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
+                yield {
+                    type: 'retry',
+                    toolName: 'transport',
+                    attempt,
+                    maxRetries: 1,
+                    errorMessage: 'WebSocket retries exhausted. Falling back to HTTP transport and retrying.',
+                    retryType: 'upstream',
+                };
+                if (!this.isCurrentGeneration(gen)) {
+                    return { kind: 'stale_generation' };
+                }
+                return {
+                    kind: 'retry_transport_downgrade',
+                    runOptions: {
+                        skipUserMessage: Boolean(stream),
+                        retries: { transientRetryCount: 0, transportFallbackRetryCount: attempt },
+                        maxModelRetries,
+                    },
+                };
+            }
+            case 'hallucination': {
+                const decisionResult = decision.decision;
+                if (decisionResult.kind !== 'retry') {
+                    break;
+                }
+                this.#logRetry('Recoverable model error detected, retrying', 'retry.model_error', {
+                    toolName: decisionResult.logPayload.toolName,
+                    retryType: decisionResult.logPayload.retryType,
+                    retryAttempt: decisionResult.attempt,
+                    attempt: decisionResult.attempt,
+                    maxRetries: maxModelRetries ?? MAX_HALLUCINATION_RETRIES,
+                    errorMessage: decisionResult.message,
+                });
+                yield decisionResult.retryEvent;
+                if (!this.isCurrentGeneration(gen)) {
+                    return { kind: 'stale_generation' };
+                }
+                return {
+                    kind: 'retry_hallucination',
+                    runOptions: {
+                        ...decisionResult.nextRunOptions,
+                        maxModelRetries,
+                    },
+                    hadStream: decisionResult.hadStream,
+                    addErrorContext: decisionResult.shouldInjectErrorContext ? decisionResult.errorContextMessage : undefined,
+                };
+            }
+            case 'none':
+            case 'unrecoverable':
+                break;
+        }
+        return { kind: 'unrecoverable' };
+    }
+    restoreForRetry(opts) {
+        this.retryHandler.restoreForRetry(opts);
+    }
+    #logRetry(message, eventType, fields) {
+        this.logger.warn(message, {
+            eventType,
+            category: 'retry',
+            phase: 'retry',
+            sessionId: this.sessionId,
+            traceId: this.logger.getCorrelationId(),
+            ...fields,
+        });
+    }
+}
+//# sourceMappingURL=session-retry-orchestrator.js.map