@qduc/term2 0.7.3 → 0.9.0

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

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

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

package/dist/services/session-runtime-controller.d.ts

@@ -0,0 +1,26 @@
+import type { ReasoningEffortSetting } from '../contracts/conversation.js';
+import type { ConversationAgentClient } from './conversation-agent-client.js';
+import type { SessionLifecycle } from './session-lifecycle.js';
+/**
+ * Manages runtime settings that affect the agent client's behavior:
+ * model, reasoning effort, temperature, provider, and retry callback.
+ *
+ * Each setting mutation calls `afterProviderChanged()` on the state controller
+ * before delegating to the agent client, ensuring session state is properly
+ * reset (e.g., response chaining is severed).
+ */
+export declare class SessionRuntimeController {
+    #private;
+    constructor(deps: {
+        agentClient: ConversationAgentClient;
+        state: SessionLifecycle;
+    });
+    setModel(model: string): void;
+    setReasoningEffort(effort: ReasoningEffortSetting): void;
+    setTemperature(temperature?: number): void;
+    setProvider(provider: string): void;
+    /** Alias for setProvider, kept for public API surface. */
+    switchProvider(provider: string): void;
+    setRetryCallback(callback: () => void): void;
+}
+//# sourceMappingURL=session-runtime-controller.d.ts.map

package/dist/services/session-runtime-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-runtime-controller.d.ts","sourceRoot":"","sources":["../../source/services/session-runtime-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;GAOG;AACH,qBAAa,wBAAwB;;gBAIvB,IAAI,EAAE;QAAE,WAAW,EAAE,uBAAuB,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE;IAKnF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAMxD,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAM1C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMnC,0DAA0D;IAC1D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAItC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;CAK7C"}

package/dist/services/session-runtime-controller.js

@@ -0,0 +1,46 @@
+import { getMethod } from './interruption-info.js';
+/**
+ * Manages runtime settings that affect the agent client's behavior:
+ * model, reasoning effort, temperature, provider, and retry callback.
+ *
+ * Each setting mutation calls `afterProviderChanged()` on the state controller
+ * before delegating to the agent client, ensuring session state is properly
+ * reset (e.g., response chaining is severed).
+ */
+export class SessionRuntimeController {
+    #agentClient;
+    #state;
+    constructor(deps) {
+        this.#agentClient = deps.agentClient;
+        this.#state = deps.state;
+    }
+    setModel(model) {
+        this.#state.afterProviderChanged();
+        this.#agentClient.setModel(model);
+    }
+    setReasoningEffort(effort) {
+        this.#state.afterProviderChanged();
+        const setReasoningEffort = getMethod(this.#agentClient, 'setReasoningEffort');
+        setReasoningEffort?.call(this.#agentClient, effort);
+    }
+    setTemperature(temperature) {
+        this.#state.afterProviderChanged();
+        const setTemperature = getMethod(this.#agentClient, 'setTemperature');
+        setTemperature?.call(this.#agentClient, temperature);
+    }
+    setProvider(provider) {
+        this.#state.afterProviderChanged();
+        const setProvider = getMethod(this.#agentClient, 'setProvider');
+        setProvider?.call(this.#agentClient, provider);
+    }
+    /** Alias for setProvider, kept for public API surface. */
+    switchProvider(provider) {
+        this.setProvider(provider);
+    }
+    setRetryCallback(callback) {
+        if (typeof this.#agentClient.setRetryCallback === 'function') {
+            this.#agentClient.setRetryCallback(callback);
+        }
+    }
+}
+//# sourceMappingURL=session-runtime-controller.js.map

package/dist/services/session-runtime-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-runtime-controller.js","sourceRoot":"","sources":["../../source/services/session-runtime-controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAwB;IAC1B,YAAY,CAA0B;IACtC,MAAM,CAAmB;IAElC,YAAY,IAAuE;QACjF,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,QAAQ,CAAC,KAAa;QACpB,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACnC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,kBAAkB,CAAC,MAA8B;QAC/C,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACnC,MAAM,kBAAkB,GAAG,SAAS,CAAiC,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;QAC9G,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,cAAc,CAAC,WAAoB;QACjC,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,SAAS,CAA6B,IAAI,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;QAClG,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACvD,CAAC;IAED,WAAW,CAAC,QAAgB;QAC1B,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,SAAS,CAAiB,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;QAChF,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,0DAA0D;IAC1D,cAAc,CAAC,QAAgB;QAC7B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,gBAAgB,CAAC,QAAoB;QACnC,IAAI,OAAO,IAAI,CAAC,YAAY,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;YAC7D,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF"}

package/dist/services/session-state-controller.d.ts

@@ -0,0 +1,83 @@
+import { SessionRetryOrchestrator } from './session-retry-orchestrator.js';
+import { SessionInputPlanner } from './session-input-planner.js';
+import { ApprovalState } from './approval-state.js';
+import { SessionToolTracker } from './session-tool-tracker.js';
+import { ShellAutoApprovalResolver } from './shell-auto-approval-resolver.js';
+import { TurnItemAccumulator } from './turn-item-accumulator.js';
+import { ConversationStore } from './conversation-store.js';
+import type { ConversationAgentClient } from './conversation-agent-client.js';
+import type { ILoggingService } from './service-interfaces.js';
+import type { SavedToolExecution } from './tool-execution-ledger.js';
+import { type ApplicationSessionState } from './turn-coordinator.js';
+/**
+ * Owns and manages session-level state transitions:
+ * - previousResponseId and pendingModeNotice
+ * - generation resets, store clearing
+ * - import/export reconciliation
+ * - undo side effects
+ * - approval/cache/input guard reset hooks
+ *
+ * ConversationSession delegates to this object for lifecycle operations
+ * instead of implementing them inline.
+ */
+export declare class SessionStateController {
+    #private;
+    /** The last response ID from the provider, used for conversation chaining. */
+    previousResponseId: string | null;
+    /** A pending mode-notice text to prepend to the next user turn. */
+    pendingModeNotice: string | null;
+    constructor(deps: {
+        retryOrchestrator: SessionRetryOrchestrator;
+        inputPlanner: SessionInputPlanner;
+        approvalState: ApprovalState;
+        toolTracker: SessionToolTracker;
+        shellAutoApproval: ShellAutoApprovalResolver;
+        turnAccumulator: TurnItemAccumulator;
+        conversationStore: ConversationStore;
+        agentClient: ConversationAgentClient;
+        logger: ILoggingService;
+        sessionId: string;
+        appState: ApplicationSessionState;
+    });
+    /**
+     * Full session reset: clears conversation store, tool tracker, input planner,
+     * and all continuity state.
+     */
+    resetSession(options?: {
+        clearConversations?: boolean;
+    }): void;
+    /**
+     * Reset after a provider/model/reasoning-effort/temperature change.
+     * Keeps the conversation store intact but severs the response chain.
+     */
+    afterProviderChanged(): void;
+    /**
+     * Clean up after an undo operation.
+     *
+     * Call this *after* the user turn has been removed from the conversation store.
+     */
+    afterUndo(): void;
+    /**
+     * Export the current session state for persistence.
+     */
+    exportPersistedState(): {
+        history: unknown[];
+        previousResponseId: string | null;
+        toolLedger: SavedToolExecution[];
+    };
+    /**
+     * Import a previously persisted session state.
+     *
+     * Reconciles the persisted history with the tool execution ledger,
+     * clears the current store, and resets all continuity state so the
+     * first resumed turn sends full history.
+     */
+    importPersistedState(state: {
+        history: unknown[];
+        previousResponseId: string | null;
+        toolLedger?: SavedToolExecution[];
+        updatedAt?: string;
+    }): void;
+    setInputSurgeKind(kind: 'delta' | 'full_history'): void;
+}
+//# sourceMappingURL=session-state-controller.d.ts.map

package/dist/services/session-state-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state-controller.d.ts","sourceRoot":"","sources":["../../source/services/session-state-controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE;;;;;;;;;;GAUG;AACH,qBAAa,sBAAsB;;IACjC,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEzC,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAc5B,IAAI,EAAE;QAChB,iBAAiB,EAAE,wBAAwB,CAAC;QAC5C,YAAY,EAAE,mBAAmB,CAAC;QAClC,aAAa,EAAE,aAAa,CAAC;QAC7B,WAAW,EAAE,kBAAkB,CAAC;QAChC,iBAAiB,EAAE,yBAAyB,CAAC;QAC7C,eAAe,EAAE,mBAAmB,CAAC;QACrC,iBAAiB,EAAE,iBAAiB,CAAC;QACrC,WAAW,EAAE,uBAAuB,CAAC;QACrC,MAAM,EAAE,eAAe,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,uBAAuB,CAAC;KACnC;IAgBD;;;OAGG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAS9D;;;OAGG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;;;OAIG;IACH,SAAS,IAAI,IAAI;IAOjB;;OAEG;IACH,oBAAoB,IAAI;QACtB,OAAO,EAAE,OAAO,EAAE,CAAC;QACnB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,UAAU,EAAE,kBAAkB,EAAE,CAAC;KAClC;IAQD;;;;;;OAMG;IACH,oBAAoB,CAAC,KAAK,EAAE;QAC1B,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;IA2DR,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI;CAGxD"}

package/dist/services/session-state-controller.js

@@ -0,0 +1,149 @@
+import { getMethod } from './interruption-info.js';
+import { reconcileHistoryWithToolLedger } from './tool-execution-ledger.js';
+/**
+ * Owns and manages session-level state transitions:
+ * - previousResponseId and pendingModeNotice
+ * - generation resets, store clearing
+ * - import/export reconciliation
+ * - undo side effects
+ * - approval/cache/input guard reset hooks
+ *
+ * ConversationSession delegates to this object for lifecycle operations
+ * instead of implementing them inline.
+ */
+export class SessionStateController {
+    /** The last response ID from the provider, used for conversation chaining. */
+    previousResponseId = null;
+    /** A pending mode-notice text to prepend to the next user turn. */
+    pendingModeNotice = null;
+    #retryOrchestrator;
+    #inputPlanner;
+    #approvalState;
+    #toolTracker;
+    #shellAutoApproval;
+    #turnAccumulator;
+    #conversationStore;
+    #agentClient;
+    #logger;
+    #sessionId;
+    #appState;
+    constructor(deps) {
+        this.#retryOrchestrator = deps.retryOrchestrator;
+        this.#inputPlanner = deps.inputPlanner;
+        this.#approvalState = deps.approvalState;
+        this.#toolTracker = deps.toolTracker;
+        this.#shellAutoApproval = deps.shellAutoApproval;
+        this.#turnAccumulator = deps.turnAccumulator;
+        this.#conversationStore = deps.conversationStore;
+        this.#agentClient = deps.agentClient;
+        this.#logger = deps.logger;
+        this.#sessionId = deps.sessionId;
+        this.#appState = deps.appState;
+    }
+    // ── Public lifecycle methods ─────────────────────────────────────
+    /**
+     * Full session reset: clears conversation store, tool tracker, input planner,
+     * and all continuity state.
+     */
+    resetSession(options) {
+        this.#resetProviderContinuity(options);
+        this.#conversationStore.clear();
+        this.#toolTracker.reset();
+        this.#inputPlanner.reset();
+        this.setInputSurgeKind('delta');
+        this.#appState.status = 'idle';
+    }
+    /**
+     * Reset after a provider/model/reasoning-effort/temperature change.
+     * Keeps the conversation store intact but severs the response chain.
+     */
+    afterProviderChanged() {
+        this.#resetProviderContinuity();
+    }
+    /**
+     * Clean up after an undo operation.
+     *
+     * Call this *after* the user turn has been removed from the conversation store.
+     */
+    afterUndo() {
+        this.#pruneToolLedgerToCurrentHistory();
+        this.#resetProviderContinuity();
+        this.#inputPlanner.markUndoOrRewind();
+        this.setInputSurgeKind('delta');
+    }
+    /**
+     * Export the current session state for persistence.
+     */
+    exportPersistedState() {
+        return {
+            history: this.#toolTracker.getReconciledHistory(),
+            previousResponseId: this.previousResponseId,
+            toolLedger: this.#toolTracker.export(),
+        };
+    }
+    /**
+     * Import a previously persisted session state.
+     *
+     * Reconciles the persisted history with the tool execution ledger,
+     * clears the current store, and resets all continuity state so the
+     * first resumed turn sends full history.
+     */
+    importPersistedState(state) {
+        this.#conversationStore.clear();
+        this.#toolTracker.import(state.toolLedger);
+        const reconciled = reconcileHistoryWithToolLedger(state.history, state.toolLedger);
+        if (reconciled.addedCompletedPairs > 0 || reconciled.droppedIncompleteCalls > 0) {
+            this.#logger.warn('Reconciled saved conversation history with tool execution ledger', {
+                eventType: 'conversation.tool_ledger.reconciled',
+                category: 'conversation',
+                phase: 'resume',
+                sessionId: this.#sessionId,
+                addedCompletedPairs: reconciled.addedCompletedPairs,
+                droppedIncompleteCalls: reconciled.droppedIncompleteCalls,
+            });
+        }
+        for (const item of reconciled.history) {
+            this.#conversationStore.addImportedItem(item);
+        }
+        // Provider-side response chains can expire while the local transcript remains valid.
+        // Force the first resumed turn to resync from full history; successful completion
+        // will populate a fresh previousResponseId for subsequent chained turns.
+        this.previousResponseId = null;
+        this.#inputPlanner.previousResponseId = null;
+        this.#toolTracker.clearEmittedToolStarted();
+        this.#inputPlanner.reset();
+        this.#shellAutoApproval.clearCache();
+        this.#approvalState.clearPending();
+        this.#approvalState.consumeAborted();
+        this.#toolTracker.clearArguments();
+        this.#turnAccumulator.resetPersistedTurnState();
+        this.#inputPlanner.markResumedSession({
+            updatedAtMs: state.updatedAt ? Date.parse(state.updatedAt) : null,
+        });
+        this.#retryOrchestrator.incrementGeneration();
+    }
+    // ── Internal helpers ──────────────────────────────────────────────
+    #resetProviderContinuity({ clearConversations = true } = {}) {
+        this.#retryOrchestrator.incrementGeneration();
+        this.previousResponseId = null;
+        this.#inputPlanner.previousResponseId = null;
+        this.#approvalState.clearPending();
+        this.#approvalState.consumeAborted();
+        this.#toolTracker.clearArguments();
+        this.#toolTracker.clearEmittedToolStarted();
+        this.#shellAutoApproval.clearCache();
+        this.#inputPlanner.reset();
+        this.#turnAccumulator.resetPersistedTurnState();
+        if (clearConversations) {
+            const clearConversationsFn = getMethod(this.#agentClient, 'clearConversations');
+            clearConversationsFn?.call(this.#agentClient);
+        }
+    }
+    #pruneToolLedgerToCurrentHistory() {
+        this.#toolTracker.pruneToCurrentHistory();
+    }
+    setInputSurgeKind(kind) {
+        this.#retryOrchestrator.setInputSurgeKind(kind);
+    }
+}
+//# sourceMappingURL=session-state-controller.js.map

package/dist/services/session-state-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state-controller.js","sourceRoot":"","sources":["../../source/services/session-state-controller.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAI5E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAsB;IACjC,8EAA8E;IAC9E,kBAAkB,GAAkB,IAAI,CAAC;IAEzC,mEAAmE;IACnE,iBAAiB,GAAkB,IAAI,CAAC;IAExC,kBAAkB,CAA2B;IAC7C,aAAa,CAAsB;IACnC,cAAc,CAAgB;IAC9B,YAAY,CAAqB;IACjC,kBAAkB,CAA4B;IAC9C,gBAAgB,CAAsB;IACtC,kBAAkB,CAAoB;IACtC,YAAY,CAA0B;IACtC,OAAO,CAAkB;IACzB,UAAU,CAAS;IACnB,SAAS,CAA0B;IAEnC,YAAY,IAYX;QACC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACjD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;QACvC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC;QACzC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACjD,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,eAAe,CAAC;QAC7C,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;IACjC,CAAC;IAED,oEAAoE;IAEpE;;;OAGG;IACH,YAAY,CAAC,OAA0C;QACrD,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,oBAAoB;QAClB,IAAI,CAAC,wBAAwB,EAAE,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,IAAI,CAAC,gCAAgC,EAAE,CAAC;QACxC,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAChC,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,CAAC;QACtC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,oBAAoB;QAKlB,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,oBAAoB,EAAE;YACjD,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;YAC3C,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE;SACvC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,oBAAoB,CAAC,KAKpB;QACC,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,UAAU,GAAG,8BAA8B,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACnF,IAAI,UAAU,CAAC,mBAAmB,GAAG,CAAC,IAAI,UAAU,CAAC,sBAAsB,GAAG,CAAC,EAAE,CAAC;YAChF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kEAAkE,EAAE;gBACpF,SAAS,EAAE,qCAAqC;gBAChD,QAAQ,EAAE,cAAc;gBACxB,KAAK,EAAE,QAAQ;gBACf,SAAS,EAAE,IAAI,CAAC,UAAU;gBAC1B,mBAAmB,EAAE,UAAU,CAAC,mBAAmB;gBACnD,sBAAsB,EAAE,UAAU,CAAC,sBAAsB;aAC1D,CAAC,CAAC;QACL,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,OAA2B,EAAE,CAAC;YAC1D,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC;QACD,qFAAqF;QACrF,kFAAkF;QAClF,yEAAyE;QACzE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC7C,IAAI,CAAC,YAAY,CAAC,uBAAuB,EAAE,CAAC;QAC5C,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,CAAC;QACrC,IAAI,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC;QACnC,IAAI,CAAC,cAAc,CAAC,cAAc,EAAE,CAAC;QACrC,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC,gBAAgB,CAAC,uBAAuB,EAAE,CAAC;QAChD,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC;YACpC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI;SAClE,CAAC,CAAC;QACH,IAAI,CAAC,kBAAkB,CAAC,mBAAmB,EAAE,CAAC;IAChD,CAAC;IAED,qEAAqE;IAErE,wBAAwB,CAAC,EAAE,kBAAkB,GAAG,IAAI,KAAuC,EAAE;QAC3F,IAAI,CAAC,kBAAkB,CAAC,mBAAmB,EAAE,CAAC;QAC9C,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC7C,IAAI,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC;QACnC,IAAI,CAAC,cAAc,CAAC,cAAc,EAAE,CAAC;QACrC,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC,YAAY,CAAC,uBAAuB,EAAE,CAAC;QAC5C,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,CAAC;QACrC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,gBAAgB,CAAC,uBAAuB,EAAE,CAAC;QAEhD,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,oBAAoB,GAAG,SAAS,CAAW,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;YAC1F,oBAAoB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,gCAAgC;QAC9B,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC;IAC5C,CAAC;IAED,iBAAiB,CAAC,IAA8B;QAC9C,IAAI,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/services/session-state-controller.test.d.ts

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

package/dist/services/session-state-controller.test.d.ts.map

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