@minionry/minion 0.7.36

package/dist/server/cli/improvisation-session-manager.js

@@ -0,0 +1,1016 @@
+// Copyright (c) 2025-present Minionry, Inc. All rights reserved.
+import { EventEmitter } from 'node:events';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { EngineSession, shouldRouteToEngine, toPromptAttachments } from '../engines/execution/engine-session.js';
+import { createEngine } from '../engines/factory.js';
+import { EngineStartError, isEngineId } from '../engines/types.js';
+import { AnalyticsEvents, trackEvent } from '../services/analytics.js';
+import { getClientId } from '../services/client-id.js';
+import { resolveEnabledEngineId } from '../services/settings.js';
+import { resolveSystemPromptContent, resolveSystemPromptLabel } from '../services/system-prompts.js';
+import { formatErrorMarker, parseErrorMarker } from '../services/timeline/assembler.js';
+import { forgetNativeResumeHandles, hasSettledMovements, nativeResumeHandle, recordNativeResumeHandle, shouldPrimeFromHistory, } from './engine-resume.js';
+import { getEtaProfileCached } from './eta-estimator.js';
+import { resolveClaudeEffort } from './headless/claude-invoker-process.js';
+import { describeDispatchBlocker, engineAvailability } from './headless/engine-availability.js';
+import { describeParkUntil } from './headless/engine-notice.js';
+import { getAssessorHealth } from './headless/haiku-assessments.js';
+import { herror, runWithFileLogger } from './headless/headless-logger.js';
+import { isTerminalEngineNotice, pickPreferredResult } from './headless/retry-strategies.js';
+import { addTokenUsage, emptyTokenUsage } from './headless/types.js';
+import { currentSessionOrigin } from './history-portability.js';
+import { cleanupAttachments, preparePromptAndAttachments } from './improvisation-attachments.js';
+import { ensureHistoryDir, loadHistory, normalizeSessionHistory, reconcileOrphanedMovements, resolveHistoryPaths, saveHistory, } from './improvisation-history-store.js';
+import { buildCancelledMovement, buildErrorMovement, buildSuccessMovement, CANCELLED_FALLBACK_RESULT, shouldAutoContinue, } from './improvisation-movements.js';
+import { OutputQueue } from './improvisation-output-queue.js';
+import { applyToolTimeoutRetry, buildStreamingCallbacks, createExecutionRunner, detectNativeTimeoutContextLoss, detectResumeContextLoss, determineResumeStrategy, selectBestResult, shouldRetryContextLoss, shouldRetryServerError, shouldRetrySessionNotFound, shouldRetrySignalCrash } from './improvisation-retry.js';
+import { createRetryLoopState } from './improvisation-types.js';
+const AGENT_LOG_DIR = join(homedir(), '.minionry', 'logs', 'agent');
+function stallContinuationPrompt(result) {
+    const pendingTasks = result.pendingBackgroundTasks ?? [];
+    if (pendingTasks.length > 0) {
+        return `${buildPendingBackgroundContinuePrompt(pendingTasks)}\nThose tasks were terminated with the process; their notifications will never arrive. Do not wait for them and do not schedule wakeups to check on them.`;
+    }
+    if (result.backgroundTasksPendingAtExit) {
+        return 'Your process was terminated while background agents/workflows were still running; that background work was lost and its notifications will never arrive. Do not wait for them — re-launch what is still needed and finish the original task.';
+    }
+    return undefined;
+}
+import { abortPlan as abortPlanCascade, completePlan as completePlanCascade, pausePlan as pausePlanCascade, resumePlan as resumePlanCascade, } from './plan-lifecycle.js';
+import { buildHistoricalContext, buildPendingBackgroundContinuePrompt } from './prompt-builders.js';
+function attachmentRecords(attachments) {
+    if (!attachments || attachments.length === 0)
+        return [];
+    return attachments.map((attachment) => ({
+        fileName: attachment.fileName,
+        ...(attachment.mimeType ? { mimeType: attachment.mimeType } : {}),
+        isImage: attachment.isImage,
+        ...(attachment.content ? { sizeBytes: Math.floor((attachment.content.length * 3) / 4) } : {}),
+    }));
+}
+export class ImprovisationSessionManager extends EventEmitter {
+    sessionId;
+    improviseDir;
+    historyPath;
+    history;
+    currentRunner = null;
+    options;
+    engineId = 'claude-code';
+    engineSession = null;
+    engineSessionModel;
+    engineSessionPromptKey;
+    engineSessionWorkingDir;
+    pendingApproval;
+    outputBuffer;
+    thinkingBuffer;
+    isFirstPrompt = true;
+    claudeSessionId;
+    isResumedSession = false;
+    _currentAttachments = [];
+    _primeFromHistory = false;
+    _resolvedModel;
+    accumulatedKnowledge = '';
+    _isExecuting = false;
+    _executionStartTimestamp;
+    executionEventLog = [];
+    _cancelled = false;
+    _cancelCompleteEmitted = false;
+    _currentUserPrompt = '';
+    _currentSequenceNumber = 0;
+    _hasPersistedToDisk = false;
+    _etaProfile = null;
+    _frozenPromptTokenUsage = emptyTokenUsage();
+    _currentInvocationTokenUsage = emptyTokenUsage();
+    static resumeFromHistory(workingDir, historicalSessionId, overrides) {
+        const historyDir = join(workingDir, '.minionry', 'history');
+        const timestamp = historicalSessionId.replace('improv-', '');
+        const historyPath = join(historyDir, `${timestamp}.json`);
+        if (!existsSync(historyPath)) {
+            throw new Error(`Historical session not found: ${historicalSessionId}`);
+        }
+        const historyData = normalizeSessionHistory(JSON.parse(readFileSync(historyPath, 'utf-8')), historicalSessionId);
+        const manager = new ImprovisationSessionManager({
+            workingDir,
+            sessionId: historyData.sessionId,
+            ...overrides,
+        });
+        manager.history = historyData;
+        manager.keepToolRestrictions();
+        manager.settleOrphanedStubs();
+        manager.accumulatedKnowledge = historyData.movements
+            .filter(m => m.summary)
+            .map(m => m.summary)
+            .join('\n\n');
+        manager.isResumedSession = true;
+        manager.isFirstPrompt = true;
+        manager._hasPersistedToDisk = true;
+        manager.claudeSessionId = nativeResumeHandle(historyData, manager.resolveEngineId(), manager.localOrigin());
+        return manager;
+    }
+    constructor(options = {}) {
+        super();
+        const resolvedSessionId = options.sessionId || `improv-${Date.now()}`;
+        this.options = {
+            workingDir: options.workingDir || process.cwd(),
+            sessionId: resolvedSessionId,
+            tokenBudgetThreshold: options.tokenBudgetThreshold || 170000,
+            maxSessions: options.maxSessions || 10,
+            verbose: options.verbose || false,
+            noColor: options.noColor || false,
+            model: options.model,
+            effortLevel: options.effortLevel,
+            fastMode: options.fastMode,
+            ultracode: options.ultracode,
+            agentLabel: options.agentLabel || resolvedSessionId,
+            ...(options.tabId ? { tabId: options.tabId } : {}),
+            ...(options.planId ? { planId: options.planId } : {}),
+            ...(options.disallowedTools?.length ? { disallowedTools: [...options.disallowedTools] } : {}),
+            ...(options.appOrigin ? { appOrigin: options.appOrigin } : {}),
+            ...(options.appRun ? { appRun: options.appRun } : {}),
+            ...(options.appSystemPrompt ? { appSystemPrompt: options.appSystemPrompt } : {}),
+        };
+        this.sessionId = this.options.sessionId;
+        const paths = resolveHistoryPaths(this.options.workingDir, this.sessionId);
+        this.improviseDir = paths.improviseDir;
+        this.historyPath = paths.historyPath;
+        ensureHistoryDir(this.improviseDir);
+        createEngine(this.engineId);
+        this.history = loadHistory(this.historyPath, this.sessionId);
+        this.keepToolRestrictions();
+        this.settleOrphanedStubs();
+        this.outputBuffer = new OutputQueue(text => this.emit('onOutput', text));
+        this.outputBuffer.start();
+        this.thinkingBuffer = new OutputQueue(text => this.emit('onThinking', text));
+        this.thinkingBuffer.start();
+    }
+    applyOverrides(overrides) {
+        if (typeof overrides.model === 'string' && overrides.model.length > 0) {
+            this.options.model = overrides.model;
+            this._resolvedModel = undefined;
+        }
+        if (typeof overrides.effortLevel === 'string' && overrides.effortLevel.length > 0) {
+            if (overrides.effortLevel === 'ultracode') {
+                this.options.effortLevel = 'auto';
+                this.options.ultracode = true;
+            }
+            else {
+                this.options.effortLevel = overrides.effortLevel;
+            }
+        }
+        if (typeof overrides.fastMode === 'boolean') {
+            this.options.fastMode = overrides.fastMode;
+        }
+        if (typeof overrides.ultracode === 'boolean') {
+            this.options.ultracode = overrides.ultracode;
+        }
+        this.options.systemPromptProfile =
+            typeof overrides.systemPromptProfile === 'string' && overrides.systemPromptProfile.length > 0
+                ? overrides.systemPromptProfile
+                : undefined;
+        this.options.systemPromptLang =
+            typeof overrides.systemPromptLang === 'string' && overrides.systemPromptLang.length > 0
+                ? overrides.systemPromptLang
+                : undefined;
+        this.applyEngineOverride(overrides.engine);
+    }
+    applyEngineOverride(engine) {
+        if (!isEngineId(engine))
+            return;
+        if (engine !== this.history.engine) {
+            this._resolvedModel = undefined;
+            this.history.engine = engine;
+            this.claudeSessionId = nativeResumeHandle(this.history, engine, this.localOrigin());
+            return;
+        }
+        this.history.engine = engine;
+    }
+    localOrigin() {
+        return { clientId: getClientId(), workingDir: this.options.workingDir };
+    }
+    keepToolRestrictions() {
+        const tools = [...new Set([...(this.options.disallowedTools ?? []), ...(this.history.disallowedTools ?? [])])];
+        if (tools.length === 0)
+            return;
+        this.options.disallowedTools = tools;
+        this.history.disallowedTools = tools;
+    }
+    settleOrphanedStubs() {
+        const settled = reconcileOrphanedMovements(this.history);
+        if (settled === 0)
+            return;
+        herror(`[session] ${this.sessionId}: settled ${settled} orphaned in-flight movement(s) left by a previous process`);
+        if (existsSync(this.historyPath))
+            this.persistHistory();
+    }
+    queueOutput(text) {
+        this.outputBuffer.queue_(text);
+    }
+    queueThinking(text) {
+        this.thinkingBuffer.queue_(text);
+    }
+    flushOutputQueue() {
+        this.thinkingBuffer.flush();
+        this.outputBuffer.flush();
+    }
+    allocateSequenceNumber(msgId) {
+        if (msgId) {
+            const orphan = this.history.movements.find((m) => m.msgId === msgId && m.outcome?.cancelOrigin === 'process-exit');
+            if (orphan)
+                return orphan.sequenceNumber;
+        }
+        return this.history.movements.length + 1;
+    }
+    async executePrompt(userPrompt, attachments, options) {
+        const _execStart = Date.now();
+        const isAutoContinue = options?.isAutoContinue ?? false;
+        const displayPrompt = options?.displayPrompt ?? userPrompt;
+        this._isExecuting = true;
+        this._cancelled = false;
+        this._cancelOrigin = 'user';
+        this._cancelCompleteEmitted = false;
+        this._currentRetryState = null;
+        this.clearWakeupTimer();
+        if (!isAutoContinue) {
+            this._autoContinueCount = 0;
+            this._autoContinuePending = false;
+            this._wakeupContinueCount = 0;
+            this._limitContinueCount = 0;
+        }
+        this._executionStartTimestamp = _execStart;
+        this.executionEventLog = [];
+        this._frozenPromptTokenUsage = emptyTokenUsage();
+        this._currentInvocationTokenUsage = emptyTokenUsage();
+        const sequenceNumber = this.allocateSequenceNumber(options?.msgId);
+        this._currentUserPrompt = displayPrompt;
+        this._currentSequenceNumber = sequenceNumber;
+        this._currentMsgId = options?.msgId;
+        this._currentAttachments = attachmentRecords(attachments);
+        const pendingMovement = {
+            id: `prompt-${sequenceNumber}`,
+            sequenceNumber,
+            userPrompt: displayPrompt,
+            timestamp: new Date().toISOString(),
+            tokensUsed: 0,
+            summary: '',
+            filesModified: [],
+            durationMs: 0,
+            ...(isAutoContinue && { isAutoContinue: true }),
+            ...(options?.msgId && { msgId: options.msgId }),
+            ...(this._currentAttachments.length > 0 && { attachments: this._currentAttachments }),
+        };
+        this.persistMovement(pendingMovement);
+        const engineId = this.resolveEngineId();
+        this._primeFromHistory = shouldPrimeFromHistory({
+            history: this.history,
+            engineId,
+            isFirstPrompt: this.isFirstPrompt,
+            isResumedSession: this.isResumedSession,
+            hasNativeHandle: this.claudeSessionId !== undefined,
+            hasLiveProcess: shouldRouteToEngine(engineId),
+        });
+        await this.refreshEtaProfile();
+        this.emit('onMovementStart', sequenceNumber, displayPrompt, isAutoContinue, this._etaProfile);
+        trackEvent(AnalyticsEvents.IMPROVISE_PROMPT_RECEIVED, {
+            prompt_length: userPrompt.length,
+            has_attachments: !!(attachments && attachments.length > 0),
+            attachment_count: attachments?.length || 0,
+            image_attachment_count: attachments?.filter(a => a.isImage).length || 0,
+            sequence_number: sequenceNumber,
+            is_resumed_session: this.isResumedSession,
+            model: this.options.model || 'default',
+            effort_level: this.options.effortLevel || 'auto',
+        });
+        let retryLoopState;
+        try {
+            this.executionEventLog.push({
+                type: 'movementStart',
+                data: { sequenceNumber, prompt: displayPrompt, timestamp: Date.now(), executionStartTimestamp: this._executionStartTimestamp },
+                timestamp: Date.now(),
+            });
+            const { prompt: promptWithAttachments, imageAttachments } = preparePromptAndAttachments(userPrompt, attachments, this.options.workingDir, this.sessionId, (msg) => { this.queueOutput(msg); this.flushOutputQueue(); });
+            const state = createRetryLoopState(promptWithAttachments, 3);
+            retryLoopState = state;
+            this._currentRetryState = state;
+            let result = await runWithFileLogger(`${this.sessionId}-${sequenceNumber}`, () => this.runRetryLoop(state, sequenceNumber, imageAttachments, options?.workingDir), AGENT_LOG_DIR);
+            if (this._cancelled || this._cancelCompleteEmitted) {
+                return this.handleCancelledExecution(result, displayPrompt, sequenceNumber, _execStart, state);
+            }
+            if (state.contextLost)
+                this.claudeSessionId = undefined;
+            result = await selectBestResult(state, result, userPrompt, this.options.verbose);
+            this.captureSessionAndSurfaceErrors(result);
+            this.surfaceAssessorHealth(state);
+            this.isFirstPrompt = false;
+            this.flushOutputQueue();
+            const movement = buildSuccessMovement(result, { sequenceNumber, userPrompt: displayPrompt, execStart: _execStart, isAutoContinue, ...this.movementMetaArgs(), outcome: this.outcomeExtras(state) }, state.retryLog);
+            this.handleConflicts(result);
+            this.persistMovement(movement);
+            this._isExecuting = false;
+            this._executionStartTimestamp = undefined;
+            this.executionEventLog = [];
+            this._currentRetryState = null;
+            if (!this._cancelCompleteEmitted) {
+                this.emitMovementComplete(movement, result, _execStart, sequenceNumber);
+            }
+            this.maybeAutoContinue(result, userPrompt);
+            return movement;
+        }
+        catch (error) {
+            this.handleExecutionError(error, displayPrompt, sequenceNumber, _execStart, retryLoopState?.bestResult ?? undefined, retryLoopState);
+        }
+        finally {
+            this.flushOutputQueue();
+        }
+    }
+    outcomeExtras(state) {
+        if (!state)
+            return {};
+        return {
+            attempts: state.retryNumber + 1,
+            ...(state.assessments.length > 0 ? { assessments: state.assessments } : {}),
+            ...(state.assessorFailed ? { assessorFailed: true } : {}),
+        };
+    }
+    surfaceAssessorHealth(state) {
+        if (!state.assessorFailed || this._assessorDegradedNoticeEmitted)
+            return;
+        const health = getAssessorHealth();
+        if (health.consecutiveFailures < 3)
+            return;
+        this._assessorDegradedNoticeEmitted = true;
+        this.queueOutput(`\n[[MINIONRY_ASSESSOR_DEGRADED]] The Haiku assessor has failed ${health.consecutiveFailures} times in a row (${health.lastError ?? 'unknown error'}) — retry decisions are using deterministic fallbacks until it recovers.\n`);
+        this.flushOutputQueue();
+    }
+    buildRetryCallbacks() {
+        return {
+            isCancelled: () => this._cancelled,
+            queueOutput: (text) => this.queueOutput(text),
+            queueThinking: (text) => this.queueThinking(text),
+            flushOutputQueue: () => this.flushOutputQueue(),
+            emit: (event, ...args) => {
+                if (event === 'onTokenUsage' && args[0] && typeof args[0] === 'object') {
+                    this._currentInvocationTokenUsage = args[0];
+                    const total = addTokenUsage(this._frozenPromptTokenUsage, this._currentInvocationTokenUsage);
+                    this.emit(event, total);
+                    return;
+                }
+                if (event === 'onExecutionTargetUpdate' && args[0] && typeof args[0] === 'object') {
+                    const resolved = args[0];
+                    if (typeof resolved.model === 'string' && resolved.model)
+                        this._resolvedModel = resolved.model;
+                    this.emit(event, this.getExecutionTarget());
+                    return;
+                }
+                this.emit(event, ...args);
+            },
+            addEventLog: (entry) => this.executionEventLog.push(entry),
+            setRunner: (runner) => { this.currentRunner = runner; },
+        };
+    }
+    freezeInvocationTokens() {
+        this._frozenPromptTokenUsage = addTokenUsage(this._frozenPromptTokenUsage, this._currentInvocationTokenUsage);
+        this._currentInvocationTokenUsage = emptyTokenUsage();
+    }
+    buildRetrySessionState() {
+        return {
+            options: { ...this.options, verbose: true },
+            claudeSessionId: this.claudeSessionId,
+            isFirstPrompt: this.isFirstPrompt,
+            isResumedSession: this.isResumedSession,
+            history: this.history,
+            executionStartTimestamp: this._executionStartTimestamp,
+            primeFromHistory: this._primeFromHistory,
+        };
+    }
+    syncSessionStateBack(session) {
+        if (session.claudeSessionId !== this.claudeSessionId) {
+            this.claudeSessionId = session.claudeSessionId;
+        }
+    }
+    async runRetryLoop(state, sequenceNumber, imageAttachments, workingDirOverride) {
+        let result;
+        const callbacks = this.buildRetryCallbacks();
+        const RETRY_BACKOFF_MS = [1000, 5000, 30000];
+        while (true) {
+            if (this._cancelled)
+                break;
+            if (state.retryNumber > 0) {
+                const delay = RETRY_BACKOFF_MS[Math.min(state.retryNumber - 1, RETRY_BACKOFF_MS.length - 1)];
+                await new Promise(r => setTimeout(r, delay));
+                if (this._cancelled)
+                    break;
+            }
+            result = await this.executeRetryIteration(state, callbacks, sequenceNumber, imageAttachments, workingDirOverride);
+            if (this._cancelled)
+                break;
+            if (await this.evaluateRetryStrategies(result, state, callbacks))
+                continue;
+            break;
+        }
+        return result;
+    }
+    async executeRetryIteration(state, callbacks, sequenceNumber, imageAttachments, workingDirOverride) {
+        if (state.checkpointRef.value)
+            state.lastWatchdogCheckpoint = state.checkpointRef.value;
+        state.checkpointRef.value = null;
+        state.contextLost = false;
+        const engineId = this.resolveEngineId();
+        if (shouldRouteToEngine(engineId)) {
+            state.lastUseResume = false;
+            state.lastNativeTimeouts = 0;
+            return this.runEngineIteration(engineId, state, callbacks, imageAttachments, workingDirOverride);
+        }
+        const session = this.buildRetrySessionState();
+        const resume = determineResumeStrategy(state, session);
+        const runner = createExecutionRunner(state, session, callbacks, sequenceNumber, resume, imageAttachments, workingDirOverride);
+        this.currentRunner = runner;
+        const result = await runner.run();
+        this.currentRunner = null;
+        this.freezeInvocationTokens();
+        state.bestResult = state.bestResult ? pickPreferredResult(state.bestResult, result) : result;
+        state.lastUseResume = resume.useResume;
+        state.lastNativeTimeouts = result.nativeTimeoutCount ?? 0;
+        detectResumeContextLoss(result, state, this.options.verbose);
+        await detectNativeTimeoutContextLoss(result, state, this.options.verbose);
+        if (!state.contextLost && result.postTimeoutOutput) {
+            this.queueOutput(result.postTimeoutOutput);
+            this.flushOutputQueue();
+        }
+        return result;
+    }
+    resolveEngineId() {
+        return resolveEnabledEngineId(this.history.engine);
+    }
+    async runEngineIteration(engineId, state, callbacks, imageAttachments, workingDirOverride) {
+        const { session: engineSession, lostResume } = await this.ensureEngineSession(engineId, workingDirOverride);
+        this.currentRunner = null;
+        const prime = this._primeFromHistory || (lostResume && hasSettledMovements(this.history));
+        const prompt = state.retryNumber === 0 && prime
+            ? `${buildHistoricalContext(this.history.movements.filter((m) => m.sequenceNumber !== this._currentSequenceNumber))}\n${state.currentPrompt}`
+            : state.currentPrompt;
+        const result = await engineSession.runTurn(prompt, toPromptAttachments(imageAttachments), { ...buildStreamingCallbacks(callbacks), questionCallback: (req) => this.askUser(req) });
+        this.freezeInvocationTokens();
+        state.bestResult = state.bestResult ? pickPreferredResult(state.bestResult, result) : result;
+        this.adoptNativeResumeHandle(engineId, result.claudeSessionId);
+        return result;
+    }
+    adoptNativeResumeHandle(engineId, handle) {
+        recordNativeResumeHandle(this.history, engineId, handle);
+        const vetted = this.history.engineSessions?.[engineId];
+        if (vetted)
+            this.claudeSessionId = vetted;
+    }
+    askUser(req) {
+        return new Promise((resolve) => {
+            const delivered = this.emit('onAskUserQuestion', {
+                toolUseId: req.requestId,
+                questions: req.questions,
+                respond: (answers) => resolve(answers),
+            });
+            if (!delivered)
+                resolve(null);
+        });
+    }
+    async ensureEngineSession(engineId, workingDirOverride) {
+        const model = this.options.model;
+        const workingDir = workingDirOverride || this.options.workingDir;
+        const promptKey = this.options.systemPromptProfile
+            ? `${this.options.systemPromptProfile}${this.options.systemPromptLang ?? ''}`
+            : undefined;
+        if (this.engineSession?.isAlive &&
+            this.engineSession.engineId === engineId &&
+            this.engineSessionModel === model &&
+            this.engineSessionWorkingDir === workingDir &&
+            this.engineSessionPromptKey === promptKey) {
+            return { session: this.engineSession, lostResume: false };
+        }
+        if (this.engineSession) {
+            const stale = this.engineSession;
+            this.engineSession = null;
+            await stale.dispose();
+        }
+        const appRun = this.options.appRun;
+        const systemPrompt = this.startSystemPrompt();
+        const startOptions = {
+            workingDir,
+            ...(model ? { model } : {}),
+            ...(this.options.effortLevel ? { effortLevel: this.options.effortLevel } : {}),
+            ...(this.options.fastMode ? { fastMode: this.options.fastMode } : {}),
+            ...(this.options.ultracode ? { ultracode: this.options.ultracode } : {}),
+            ...(systemPrompt ? { systemPrompt } : {}),
+            ...(this.options.disallowedTools ? { disallowedTools: this.options.disallowedTools } : {}),
+            ...(this.claudeSessionId ? { resumeSessionId: this.claudeSessionId } : {}),
+            ...(appRun ? { appRun } : {}),
+        };
+        const session = await EngineSession.start(engineId, startOptions);
+        this.engineSession = session;
+        this.engineSessionModel = model;
+        this.engineSessionWorkingDir = workingDir;
+        this.engineSessionPromptKey = promptKey;
+        return { session, lostResume: this.lostNativeResume(engineId, session, startOptions.resumeSessionId) };
+    }
+    lostNativeResume(engineId, session, resumeSessionId) {
+        if (resumeSessionId === undefined || session.resumedNatively !== false)
+            return false;
+        herror(`[session] ${this.sessionId}: ${engineId} could not continue ${resumeSessionId}; this turn carries the transcript`);
+        return true;
+    }
+    startSystemPrompt() {
+        if (this.options.appRun)
+            return this.options.appSystemPrompt;
+        if (!this.options.systemPromptProfile)
+            return undefined;
+        return resolveSystemPromptContent(this.options.systemPromptProfile, this.options.systemPromptLang);
+    }
+    disposeEngineSession() {
+        if (!this.engineSession)
+            return;
+        const session = this.engineSession;
+        this.engineSession = null;
+        this.engineSessionModel = undefined;
+        this.engineSessionWorkingDir = undefined;
+        this.engineSessionPromptKey = undefined;
+        session.dispose().catch((err) => herror('Engine session dispose failed:', err));
+    }
+    async evaluateRetryStrategies(result, state, callbacks) {
+        const session = this.buildRetrySessionState();
+        if (isTerminalEngineNotice(result)) {
+            herror(`[session] ${this.sessionId}: no retry — engine notice (${result.engineNotice?.kind}): ${result.engineNotice?.text.slice(0, 120)}`);
+            this.syncSessionStateBack(session);
+            return false;
+        }
+        if (shouldRetrySessionNotFound(result, state, session, callbacks)) {
+            this.syncSessionStateBack(session);
+            return true;
+        }
+        if (shouldRetryServerError(result, state, session, callbacks)) {
+            this.syncSessionStateBack(session);
+            return true;
+        }
+        if (shouldRetrySignalCrash(result, state, session, callbacks)) {
+            this.syncSessionStateBack(session);
+            return true;
+        }
+        if (shouldRetryContextLoss(result, state, session, callbacks)) {
+            this.syncSessionStateBack(session);
+            return true;
+        }
+        if (applyToolTimeoutRetry(state, callbacks, this.options.model, this.options.effortLevel))
+            return true;
+        this.syncSessionStateBack(session);
+        return false;
+    }
+    resetExecutionState() {
+        this._isExecuting = false;
+        this._executionStartTimestamp = undefined;
+        this.executionEventLog = [];
+        this.currentRunner = null;
+    }
+    handleCancelledExecution(result, userPrompt, sequenceNumber, execStart, state) {
+        this.resetExecutionState();
+        if (result)
+            this.adoptNativeResumeHandle(this.resolveEngineId(), result.claudeSessionId);
+        this.isFirstPrompt = false;
+        const origin = this._cancelOrigin;
+        const buildArgs = { sequenceNumber, userPrompt, execStart, msgId: this._currentMsgId, ...this.movementMetaArgs(), outcome: this.outcomeExtras(state) };
+        if (this._cancelCompleteEmitted) {
+            const existingIdx = this.history.movements.findIndex(m => m.sequenceNumber === sequenceNumber);
+            if (existingIdx >= 0) {
+                const existing = this.history.movements[existingIdx];
+                const resultHasContent = !!result && (!!result.assistantResponse || (result.toolUseHistory?.length ?? 0) > 0);
+                if (!result || (!resultHasContent && (existing.assistantResponse || existing.toolUseHistory?.length))) {
+                    this.persistHistory();
+                    return existing;
+                }
+                const upgraded = buildCancelledMovement(result, buildArgs, { origin, retryLog: state?.retryLog });
+                upgraded.durationMs = existing.durationMs;
+                this.persistMovement(upgraded);
+                return upgraded;
+            }
+        }
+        const cancelledMovement = buildCancelledMovement(result, buildArgs, { origin, retryLog: state?.retryLog });
+        this.persistMovement(cancelledMovement);
+        this.emitMovementComplete(cancelledMovement, result ?? CANCELLED_FALLBACK_RESULT, execStart, sequenceNumber);
+        return cancelledMovement;
+    }
+    handleExecutionError(error, displayPrompt, sequenceNumber, execStart, failedResult, state) {
+        this.resetExecutionState();
+        if (failedResult)
+            this.adoptNativeResumeHandle(this.resolveEngineId(), failedResult.claudeSessionId);
+        this.isFirstPrompt = false;
+        const errorMessage = error instanceof EngineStartError
+            ? formatErrorMarker(error.code, error.message)
+            : error instanceof Error ? error.message : String(error);
+        const reported = error instanceof EngineStartError ? new Error(errorMessage, { cause: error }) : error;
+        const errorMovement = buildErrorMovement(errorMessage, { sequenceNumber, userPrompt: displayPrompt, execStart, msgId: this._currentMsgId, ...this.movementMetaArgs(), outcome: this.outcomeExtras(state) }, failedResult, state?.retryLog);
+        this.persistMovement(errorMovement);
+        this.flushOutputQueue();
+        this.emit('onMovementError', reported, sequenceNumber);
+        trackEvent(AnalyticsEvents.IMPROVISE_MOVEMENT_ERROR, {
+            error_message: errorMessage.slice(0, 200),
+            sequence_number: sequenceNumber,
+            duration_ms: Date.now() - execStart,
+            model: this.options.model || 'default',
+            effort_level: this.options.effortLevel || 'auto',
+        });
+        if (!parseErrorMarker(errorMessage)) {
+            this.queueOutput(`\n❌ Error: ${errorMessage}\n`);
+        }
+        this.flushOutputQueue();
+        throw reported;
+    }
+    captureSessionAndSurfaceErrors(result) {
+        this.adoptNativeResumeHandle(this.resolveEngineId(), result.claudeSessionId);
+        if (!result.completed && result.error && !result.engineNotice) {
+            const line = parseErrorMarker(result.error)
+                ? result.error
+                : formatErrorMarker(result.errorCode ?? 'EXECUTION_FAILED', result.error);
+            this.queueOutput(`\n${line}\n`);
+            this.flushOutputQueue();
+        }
+    }
+    handleConflicts(result) {
+        if (!result.conflicts || result.conflicts.length === 0)
+            return;
+        this.queueOutput(`\n⚠ File conflicts detected: ${result.conflicts.length}`);
+        result.conflicts.forEach(c => {
+            this.queueOutput(`  - ${c.filePath} (modified by: ${c.modifiedBy.join(', ')})`);
+            if (c.backupPath)
+                this.queueOutput(`    Backup created: ${c.backupPath}`);
+        });
+        this.flushOutputQueue();
+    }
+    persistMovement(movement) {
+        const existingIdx = this.history.movements.findIndex(m => m.sequenceNumber === movement.sequenceNumber);
+        if (existingIdx >= 0) {
+            const previousTokens = this.history.movements[existingIdx].tokensUsed;
+            this.history.movements[existingIdx] = movement;
+            this.history.totalTokens += movement.tokensUsed - previousTokens;
+        }
+        else {
+            this.history.movements.push(movement);
+            this.history.totalTokens += movement.tokensUsed;
+        }
+        this.history.execution = this.executionRecord();
+        this.persistHistory();
+    }
+    executionRecord() {
+        const model = this._resolvedModel ?? this.options.model;
+        return {
+            engine: this.resolveEngineId(),
+            ...(model ? { model } : {}),
+            ...(this.options.effortLevel ? { effortLevel: this.options.effortLevel } : {}),
+            ...(this.options.fastMode ? { fastMode: true } : {}),
+            ...(this.options.ultracode ? { ultracode: true } : {}),
+            ...(this.options.systemPromptProfile ? { systemPromptProfile: this.options.systemPromptProfile } : {}),
+            ...(this.options.systemPromptLang ? { systemPromptLang: this.options.systemPromptLang } : {}),
+        };
+    }
+    movementMetaArgs() {
+        return {
+            ...this.executionMeta(),
+            ...(this._currentAttachments.length > 0 ? { attachments: this._currentAttachments } : {}),
+        };
+    }
+    emitMovementComplete(movement, result, execStart, sequenceNumber) {
+        this.emit('onMovementComplete', movement);
+        trackEvent(AnalyticsEvents.IMPROVISE_MOVEMENT_COMPLETED, {
+            tokens_used: movement.tokensUsed,
+            duration_ms: Date.now() - execStart,
+            sequence_number: sequenceNumber,
+            tool_count: result.toolUseHistory?.length || 0,
+            model: this.options.model || 'default',
+            effort_level: this.options.effortLevel || 'auto',
+        });
+        this.emit('onSessionUpdate', this.getHistory());
+    }
+    _autoContinueCount = 0;
+    _autoContinuePending = false;
+    static MAX_AUTO_CONTINUES = 1;
+    maybeAutoContinue(result, userPrompt) {
+        if (this._cancelled)
+            return;
+        if (result.engineNotice?.kind === 'limit') {
+            this.scheduleLimitContinue(result.engineNotice);
+            return;
+        }
+        if (result.engineNotice || result.startupTimedOut)
+            return;
+        if (result.completed && result.pendingWakeup) {
+            this.scheduleWakeupContinue(result.pendingWakeup);
+            return;
+        }
+        const isStallKill = !!result.signalName || !!result.interrupted;
+        if (isStallKill && this._autoContinueCount < ImprovisationSessionManager.MAX_AUTO_CONTINUES) {
+            this.scheduleAutoContinue('Process stalled', stallContinuationPrompt(result));
+        }
+        else if (shouldAutoContinue(result, this._autoContinueCount, ImprovisationSessionManager.MAX_AUTO_CONTINUES, this._cancelled)) {
+            this.scheduleAutoContinue();
+        }
+        void userPrompt;
+    }
+    scheduleAutoContinue(reason, continuationPrompt) {
+        this._autoContinueCount++;
+        this._autoContinuePending = true;
+        const msg = reason || 'Response appears incomplete';
+        this.queueOutput(`\n[[MINIONRY_AUTO_CONTINUE]] ${msg} — resuming session (retry ${this._autoContinueCount}/${ImprovisationSessionManager.MAX_AUTO_CONTINUES}).\n`);
+        this.flushOutputQueue();
+        setImmediate(() => {
+            if (this._cancelled || this._isExecuting || !this._autoContinuePending)
+                return;
+            this._autoContinuePending = false;
+            this.runAutomaticContinuation(continuationPrompt ?? 'continue', 'continue');
+        });
+    }
+    runAutomaticContinuation(prompt, displayPrompt) {
+        const blocker = engineAvailability.automaticDispatchBlocker();
+        if (blocker?.kind === 'limit' && blocker.until !== undefined) {
+            this.queueOutput(`\n[[MINIONRY_LIMIT_PARK]] Automatic continuation deferred — ${describeDispatchBlocker(blocker)}.\n`);
+            this.flushOutputQueue();
+            this.armTimerAt(blocker.until, () => this.runAutomaticContinuation(prompt, displayPrompt));
+            return;
+        }
+        if (blocker?.kind === 'auth') {
+            this.queueOutput(`\n[[MINIONRY_ERROR:AUTH_REQUIRED]] Automatic continuation skipped — ${describeDispatchBlocker(blocker)}. Send a new prompt once you are logged in.\n`);
+            this.flushOutputQueue();
+            return;
+        }
+        this.executePrompt(prompt, undefined, { isAutoContinue: true, displayPrompt }).catch((err) => {
+            herror('Automatic continuation failed:', err);
+        });
+    }
+    armTimerAt(at, fn) {
+        const MAX_TIMER_MS = 24 * 60 * 60_000;
+        const delay = Math.min(Math.max(at - Date.now(), 0), MAX_TIMER_MS);
+        this.clearWakeupTimer();
+        this._wakeupTimer = setTimeout(() => {
+            this._wakeupTimer = null;
+            if (this._isExecuting || this._cancelled)
+                return;
+            if (Date.now() < at) {
+                this.armTimerAt(at, fn);
+                return;
+            }
+            fn();
+        }, delay);
+    }
+    _limitContinueCount = 0;
+    static MAX_LIMIT_CONTINUES = 3;
+    scheduleLimitContinue(notice) {
+        const resetAt = notice.resetAt ?? Date.now() + 15 * 60_000;
+        if (this._limitContinueCount >= ImprovisationSessionManager.MAX_LIMIT_CONTINUES) {
+            this.queueOutput(`\n[[MINIONRY_LIMIT_PARK]] Usage limit reached again — ${ImprovisationSessionManager.MAX_LIMIT_CONTINUES} automatic resumes already used for this prompt. Send a new prompt after ${describeParkUntil(resetAt)}.\n`);
+            this.flushOutputQueue();
+            return;
+        }
+        this._limitContinueCount++;
+        this.queueOutput(`\n[[MINIONRY_LIMIT_PARK]] Usage limit reached — this conversation resumes automatically at ${describeParkUntil(resetAt)} (resume ${this._limitContinueCount}/${ImprovisationSessionManager.MAX_LIMIT_CONTINUES}).${notice.resetParsed ? '' : ' The notice named no reset time, so this is a short wait; a new prompt from you overrides it.'}\n`);
+        this.flushOutputQueue();
+        this.armTimerAt(resetAt, () => this.runAutomaticContinuation('Your previous turn stopped because the usage limit was reached. The limit has reset — continue the task from where you left off.', 'continue (after usage limit reset)'));
+    }
+    _wakeupTimer = null;
+    _wakeupContinueCount = 0;
+    static MAX_WAKEUP_CONTINUES = 24;
+    clearWakeupTimer() {
+        if (this._wakeupTimer) {
+            clearTimeout(this._wakeupTimer);
+            this._wakeupTimer = null;
+        }
+    }
+    scheduleWakeupContinue(wakeup) {
+        if (this._wakeupContinueCount >= ImprovisationSessionManager.MAX_WAKEUP_CONTINUES) {
+            this.queueOutput(`\n[[MINIONRY_BACKGROUND_WAIT]] Scheduled wakeup NOT honored — ${ImprovisationSessionManager.MAX_WAKEUP_CONTINUES} automatic continuations reached for this prompt. Send a new prompt to keep going.\n`);
+            this.flushOutputQueue();
+            return;
+        }
+        this._wakeupContinueCount++;
+        const delayMs = Math.min(Math.max(wakeup.fireAtMs - Date.now(), 0), 3_600_000);
+        const fireAt = new Date(Date.now() + delayMs);
+        this.queueOutput(`\n[[MINIONRY_BACKGROUND_WAIT]] Scheduled wakeup honored — session resumes at ${fireAt.toLocaleTimeString()} (continuation ${this._wakeupContinueCount}/${ImprovisationSessionManager.MAX_WAKEUP_CONTINUES})${wakeup.reason ? `: ${wakeup.reason}` : ''}.\n`);
+        this.flushOutputQueue();
+        const prompt = wakeup.prompt && !wakeup.prompt.startsWith('<<')
+            ? wakeup.prompt
+            : 'Your scheduled wakeup fired. Check progress on your background work and continue the task.';
+        this.clearWakeupTimer();
+        this._wakeupTimer = setTimeout(() => {
+            this._wakeupTimer = null;
+            if (this._isExecuting || this._cancelled)
+                return;
+            this.runAutomaticContinuation(prompt, 'continue (scheduled wakeup)');
+        }, delayMs);
+    }
+    executionMeta() {
+        return {
+            engine: this.resolveEngineId(),
+            model: this._resolvedModel ?? this.options.model,
+            fastMode: this.options.fastMode,
+        };
+    }
+    async refreshEtaProfile() {
+        try {
+            this._etaProfile = await getEtaProfileCached(this.improviseDir, this.executionMeta());
+        }
+        catch {
+            this._etaProfile = null;
+        }
+    }
+    persistHistory() {
+        if (!this.history.origin)
+            this.history.origin = currentSessionOrigin(this.options.workingDir);
+        saveHistory(this.historyPath, this.history);
+        if (!this._hasPersistedToDisk) {
+            this._hasPersistedToDisk = true;
+            this.emit('onHistoryPersisted');
+        }
+    }
+    getHistory() {
+        return this.history;
+    }
+    _cancelOrigin = 'user';
+    _currentRetryState = null;
+    _currentMsgId;
+    _assessorDegradedNoticeEmitted = false;
+    snapshotInFlightResult() {
+        const runner = this.currentRunner;
+        const snapshot = runner && typeof runner.snapshot === 'function' ? runner.snapshot() : null;
+        if (!snapshot)
+            return CANCELLED_FALLBACK_RESULT;
+        return {
+            ...CANCELLED_FALLBACK_RESULT,
+            ...(snapshot.assistantResponse !== undefined ? { assistantResponse: snapshot.assistantResponse } : {}),
+            ...(snapshot.thinkingOutput !== undefined ? { thinkingOutput: snapshot.thinkingOutput } : {}),
+            ...(snapshot.toolUseHistory ? { toolUseHistory: snapshot.toolUseHistory } : {}),
+            ...(snapshot.claudeSessionId ? { claudeSessionId: snapshot.claudeSessionId } : {}),
+            ...(snapshot.apiTokenUsage ? { apiTokenUsage: snapshot.apiTokenUsage, outputTokens: snapshot.apiTokenUsage.outputTokens } : {}),
+            ...(snapshot.engineNotice ? { engineNotice: snapshot.engineNotice } : {}),
+        };
+    }
+    settleInFlight(origin) {
+        this._cancelled = true;
+        this._cancelOrigin = origin;
+        this.clearWakeupTimer();
+        this._autoContinuePending = false;
+        const snapshot = this._isExecuting ? this.snapshotInFlightResult() : undefined;
+        if (this.currentRunner) {
+            this.currentRunner.cleanup();
+            this.currentRunner = null;
+        }
+        this.engineSession?.cancel().catch((err) => herror('Engine session cancel failed:', err));
+        if (this._isExecuting && !this._cancelCompleteEmitted) {
+            this._cancelCompleteEmitted = true;
+            const execStart = this._executionStartTimestamp || Date.now();
+            this._isExecuting = false;
+            this._executionStartTimestamp = undefined;
+            if (snapshot?.claudeSessionId)
+                this.adoptNativeResumeHandle(this.resolveEngineId(), snapshot.claudeSessionId);
+            const cancelledMovement = buildCancelledMovement(snapshot, {
+                sequenceNumber: this._currentSequenceNumber,
+                userPrompt: this._currentUserPrompt,
+                execStart,
+                msgId: this._currentMsgId,
+                ...this.movementMetaArgs(),
+                outcome: this.outcomeExtras(this._currentRetryState),
+            }, { origin, retryLog: this._currentRetryState?.retryLog });
+            this.persistMovement(cancelledMovement);
+            this.emitMovementComplete(cancelledMovement, snapshot ?? CANCELLED_FALLBACK_RESULT, execStart, this._currentSequenceNumber);
+        }
+    }
+    cancel() {
+        this.settleInFlight('user');
+        this.outputBuffer.destroy();
+        this.thinkingBuffer.destroy();
+        this.flushOutputQueue();
+    }
+    settleForLifecycle(origin) {
+        if (!this._isExecuting)
+            return false;
+        this.settleInFlight(origin);
+        this.flushOutputQueue();
+        return true;
+    }
+    destroy() {
+        if (this._isExecuting)
+            this.settleInFlight('destroy');
+        this.clearWakeupTimer();
+        if (this.currentRunner) {
+            this.currentRunner.cleanup();
+            this.currentRunner = null;
+        }
+        this.disposeEngineSession();
+        this.outputBuffer.destroy();
+        this.thinkingBuffer.destroy();
+        this.flushOutputQueue();
+    }
+    clearHistory() {
+        this.history.movements = [];
+        this.history.totalTokens = 0;
+        this.accumulatedKnowledge = '';
+        this.isFirstPrompt = true;
+        this.claudeSessionId = undefined;
+        forgetNativeResumeHandles(this.history);
+        this.disposeEngineSession();
+        cleanupAttachments(this.options.workingDir, this.sessionId);
+        this.persistHistory();
+        this.emit('onSessionUpdate', this.getHistory());
+    }
+    async requestApproval(plan) {
+        return new Promise((resolve) => {
+            this.pendingApproval = { plan, resolve };
+            this.emit('onApprovalRequired', plan);
+        });
+    }
+    respondToApproval(approved) {
+        if (this.pendingApproval) {
+            this.pendingApproval.resolve(approved);
+            this.pendingApproval = undefined;
+        }
+    }
+    getSessionInfo() {
+        return {
+            sessionId: this.sessionId,
+            startTime: this.history.startedAt,
+            workingDir: this.options.workingDir,
+            totalTokens: this.history.totalTokens,
+            tokenBudgetThreshold: this.options.tokenBudgetThreshold,
+            movementCount: this.history.movements.length,
+        };
+    }
+    get isExecuting() {
+        return this._isExecuting;
+    }
+    setTabId(tabId) {
+        this.options.tabId = tabId;
+    }
+    setPlanId(planId) {
+        this.options.planId = planId;
+    }
+    get agentId() {
+        return `agent-${this.sessionId}`;
+    }
+    get agentLabel() {
+        return this.options.agentLabel ?? this.sessionId;
+    }
+    get planId() {
+        return this.options.planId;
+    }
+    get appOrigin() {
+        return this.options.appOrigin;
+    }
+    get engine() {
+        return this.history.engine || 'claude-code';
+    }
+    get executionStartTimestamp() {
+        return this._executionStartTimestamp;
+    }
+    resolveClaudeCodeEffort() {
+        const modelForTier = this._resolvedModel ?? this.options.model;
+        return resolveClaudeEffort(modelForTier, this.options.effortLevel) ?? this.options.effortLevel;
+    }
+    getExecutionTarget() {
+        const profile = this.options.systemPromptProfile;
+        const engine = this.resolveEngineId();
+        const isClaudeDefaultModel = engine === 'claude-code' && this.options.model === 'default';
+        return {
+            engine,
+            model: this._resolvedModel ?? (isClaudeDefaultModel ? undefined : this.options.model),
+            effortLevel: engine === 'claude-code' ? this.resolveClaudeCodeEffort() : this.options.effortLevel,
+            fastMode: this.options.fastMode,
+            ultracode: this.options.ultracode,
+            ...(profile
+                ? {
+                    systemPromptProfile: profile,
+                    systemPromptLang: this.options.systemPromptLang,
+                    systemPromptLabel: resolveSystemPromptLabel(profile),
+                }
+                : {}),
+        };
+    }
+    get etaProfile() {
+        return this._etaProfile;
+    }
+    getExecutionEventLog() {
+        return this.executionEventLog;
+    }
+    startNewSession(overrides) {
+        this.persistHistory();
+        return new ImprovisationSessionManager({
+            ...this.options,
+            sessionId: `improv-${Date.now()}`,
+            ...overrides,
+        });
+    }
+    static abortPlan(planId, deps, opts = {}) {
+        return abortPlanCascade(planId, deps, opts);
+    }
+    static pausePlan(planId, deps) {
+        return pausePlanCascade(planId, deps);
+    }
+    static resumePlan(planId, deps) {
+        return resumePlanCascade(planId, deps);
+    }
+    static completePlan(planId, deps) {
+        return completePlanCascade(planId, deps);
+    }
+}