neoctl 0.2.45 → 0.2.47

package/dist/core/query-engine.js

@@ -1,4 +1,6 @@
 import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { executionRecoveryHint, isResumableExecution } from "./execution-state.js";
 import { InMemoryAppState } from "../app/app-state.js";
 import { InMemoryAppPromptStore } from "../app/app-prompt.js";
 import { AppPromptContextManager, DefaultContextManager, readProjectMemoryDocuments } from "../context/context-manager.js";
@@ -8,7 +10,8 @@ import { ToolRegistry } from "../tools/registry.js";
 import { createSystemInitMessage, createTextMessage } from "../types/messages.js";
 import { buildContextMetrics } from "./context-metrics.js";
 import { applyRuntimeContextForPromptCache } from "./message-pipeline.js";
-import { persistMessageImages } from "./image-storage.js";
+import { abortableWork } from "./abortable-stream.js";
+import { SessionImageStore } from "./session-images.js";
 import { query } from "./query.js";
 import { runAgent } from "./run-agent.js";
 import { GENERAL_PURPOSE_AGENT } from "../agents/agent-definition.js";
@@ -19,13 +22,58 @@ import { applySessionPrompt, sessionPromptMode, createSessionPromptSnapshot, par
 const DEFAULT_SESSION_TITLE_DELAY_MS = 5000;
 export class QueryEngine {
     options;
+    simulation;
+    displayOnlyMessages = [];
+    /** Instance-local execution boundary; never inherited by forkForSession or written to provider settings. */
+    setSimulation(simulation) {
+        if (this.running)
+            throw new Error("cannot replace execution while a query is running");
+        this.cancelPendingTitleWork();
+        this.simulation = simulation;
+    }
+    /** Persist a visible message without submitting it to a model or changing an in-flight context. */
+    async recordDisplayMessage(message) {
+        await this.initialize();
+        const store = this.sessionStore;
+        const windowId = store?.snapshot().firstWindowId;
+        const stored = await this.imageStore.persistMessage({ ...message, metadata: { ...message.metadata, displayOnly: true } });
+        if (store !== this.sessionStore || windowId !== store?.snapshot().firstWindowId)
+            throw new Error("Session changed while recording message");
+        if (store)
+            store.recordMessage(stored);
+        else
+            this.displayOnlyMessages.push(stored);
+        return stored;
+    }
     agentId;
     history = [];
     titleTimers = new Set();
     lastTerminalReason;
+    executionState;
+    executionStartedAt;
+    executionNow() {
+        return this.options.timingClock?.monotonicNow() ?? performance.now();
+    }
+    getExecutionState() {
+        if (!this.executionState)
+            return undefined;
+        const elapsedMs = (this.executionState.elapsedMs ?? 0) + (this.executionStartedAt === undefined
+            ? 0 : Math.max(0, this.executionNow() - this.executionStartedAt));
+        return { ...this.executionState, elapsedMs: Math.floor(elapsedMs) };
+    }
+    markExecutionPaused() {
+        this.setExecutionState({ status: "paused", reason: "user_pause" });
+    }
+    setExecutionState(state) {
+        const elapsedMs = state.elapsedMs ?? this.getExecutionState()?.elapsedMs ?? 0;
+        this.executionState = { ...state, elapsedMs, ...(this.executionState?.resumeCompaction ? { resumeCompaction: true } : {}) };
+        this.executionStartedAt = state.status === "running" ? this.executionNow() : undefined;
+        this.sessionStore?.recordExecutionState(this.executionState);
+    }
     queryTiming;
     timingRecords = new Map();
     sessionStore;
+    imageStore;
     currentModel;
     currentReasoning;
     currentFastMode = false;
@@ -103,6 +151,7 @@ export class QueryEngine {
             if (this.options.session?.enabled !== false && this.options.session) {
                 await this.openSession({ sessionId: this.options.session.sessionId, resume: this.options.session.resume });
             }
+            this.imageStore ??= await SessionImageStore.open(undefined, this.agentId);
             this.sessionInitialized = true;
         })();
         this.sessionInitialization = initialization;
@@ -152,13 +201,35 @@ export class QueryEngine {
             rootDir: this.options.session.rootDir,
         });
     }
-    async *sendUserText(text, options = {}) {
+    sendUserText(text, options = {}) {
+        return this.runQuery(text, options);
+    }
+    /** A UI continuation is a runtime action, not an invented user utterance. */
+    continueExecution(options = {}) {
+        return this.runQuery(undefined, options);
+    }
+    async *runQuery(text, options = {}) {
         if (this.running)
             throw new Error("query engine is already running");
         this.running = true;
+        let terminalReceived = false;
+        let queryAccepted = text !== undefined;
         try {
             await this.settingsMutation;
             await this.initialize();
+            const recovery = isResumableExecution(this.executionState) ? this.executionState : undefined;
+            if (text === undefined && !recovery)
+                throw new Error("No interrupted execution to continue");
+            queryAccepted = true;
+            if (recovery) {
+                this.pendingRequestContext = { ...this.pendingRequestContext,
+                    executionRecovery: executionRecoveryHint(recovery),
+                    ...(text === undefined ? { continuationAction: "用户点击了继续按钮，请继续尚未完成的任务。这是运行时动作，不是用户发送的新消息。" } : {}),
+                };
+            }
+            const elapsedMs = recovery?.elapsedMs ?? 0;
+            this.setExecutionState(options.abortSignal?.aborted
+                ? { status: "paused", reason: "user_pause", elapsedMs } : { status: "running", elapsedMs });
             const cwdTransitionPaths = this.pendingCwdTransitionPaths;
             const pendingRequestContext = this.pendingRequestContext;
             const pendingRequestContextConsumed = this.pendingRequestContextConsumed;
@@ -166,18 +237,20 @@ export class QueryEngine {
             this.options.cwdTransitionPaths = undefined;
             if (cwdTransitionPaths?.length)
                 void this.options.onCwdTransitionConsumed?.();
-            const userMessage = options.blocks
-                ? await this.persistMessageImages({
-                    ...createTextMessage("user", options.displayText ?? text),
-                    blocks: options.blocks,
-                })
-                : createTextMessage("user", text);
-            this.history.push(userMessage);
-            this.sessionStore?.recordMessage(userMessage);
-            this.scheduleSessionTitleCheck();
+            if (text !== undefined) {
+                const userMessage = options.blocks
+                    ? await this.persistMessageImages({
+                        ...createTextMessage("user", options.displayText ?? text),
+                        blocks: options.blocks,
+                    })
+                    : createTextMessage("user", text);
+                this.history.push(userMessage);
+                this.sessionStore?.recordMessage(userMessage);
+                this.scheduleSessionTitleCheck();
+            }
             const initMessage = createSystemInitMessage({
                 agentId: this.agentId,
-                tools: this.options.tools.names(),
+                tools: (this.simulation?.tools ?? this.options.tools).names(),
                 model: this.currentModel,
                 commands: [...(this.options.commands ?? [])],
                 agents: [...(this.options.agents ?? [])],
@@ -193,6 +266,7 @@ export class QueryEngine {
                 message: initMessage,
             };
             this.sessionStore?.recordMessage(initMessage);
+            const compactor = this.cancellableCompactor(options.abortSignal);
             const queryOptions = {
                 agentId: this.agentId,
                 model: this.currentModel,
@@ -220,29 +294,33 @@ export class QueryEngine {
                 } : undefined,
                 abortSignal: options.abortSignal,
                 stopAfterTurn: options.stopAfterTurn,
-                beforeTurn: (messages) => {
-                    this.options.refreshTools?.(this);
-                    return this.consumeSessionSettings(messages);
+                beforeTurn: (messages, started) => {
+                    if (!this.simulation)
+                        this.options.refreshTools?.(this);
+                    return this.consumeSessionSettings(messages, started, compactor);
                 },
             };
             const stream = query(this.history, {
                 ...this.options,
-                acquireTurnResources: this.options.acquireTurnResources ? () => this.options.acquireTurnResources(this) : undefined,
+                acquireTurnResources: this.simulation ? undefined : this.options.acquireTurnResources ? () => this.options.acquireTurnResources(this) : undefined,
+                tools: this.simulation?.tools ?? this.options.tools,
+                compactor,
                 onTimingState: timing => { this.queryTiming = timing; },
                 onTiming: record => {
                     this.timingRecords.set(record.id, { ...record });
                     this.sessionStore?.recordTiming(record);
                 },
                 contextManager: this.contextManager,
-                modelGateway: this.currentModelGateway,
+                modelGateway: this.simulation?.modelGateway ?? this.currentModelGateway,
                 taskNotificationSource: this.options.taskNotificationSource,
+                imageStore: this.imageStore,
                 toolResultMemory: this.sessionStore?.toolResultMemory,
                 session: this.sessionStore ? { sessionId: this.sessionStore.sessionId, sessionDir: this.sessionStore.sessionDir, rootDir: this.options.session?.rootDir } : undefined,
                 recordContentReplacements: (records) => this.sessionStore?.recordContentReplacements(records),
                 // query owns synthetic tool-use messages; persist them only via the message event below.
                 // The export callback is an observer, not a second history writer.
                 exportToolCalls: this.options.exportToolCalls,
-                applyCompaction: (result) => this.applyCompactionResult(result),
+                applyCompaction: (result) => { options.abortSignal?.throwIfAborted(); this.applyCompactionResult(result); },
             }, queryOptions);
             for await (const event of stream) {
                 if (event.type === "message") {
@@ -253,13 +331,17 @@ export class QueryEngine {
                     continue;
                 }
                 if (event.type === "terminal") {
+                    terminalReceived = true;
                     this.lastTerminalReason = event.reason;
-                    // The final assistant/tool messages have already been recorded by this wrapper.
-                    const hadPending = Object.keys(this.pendingSessionSettings).length > 0;
-                    for (const result of await this.flushSessionSettings()) {
-                        if (result.report)
-                            yield { type: "context.compacted", compaction: result.report };
+                    if (this.executionState?.status !== "paused") {
+                        this.setExecutionState({
+                            status: event.reason === "completed" || event.reason === "turn_yielded" ? "completed" : "interrupted",
+                            reason: event.reason,
+                        });
                     }
+                    // Settle ordinary settings only; pending compact waits for the next model call.
+                    const hadPending = Object.keys(this.pendingSessionSettings).length > 0;
+                    await this.flushSessionSettings();
                     if (hadPending)
                         yield { type: "context.metrics", metrics: await this.contextMetrics() };
                 }
@@ -267,12 +349,12 @@ export class QueryEngine {
             }
         }
         finally {
-            // Covers initialization errors, aborts, exceptions and consumer generator.return().
-            // Do not yield in finally: a closing consumer may never resume the generator.
+            // Even a failed journal write must release the engine run lock.
             try {
-                do {
-                    await this.flushSessionSettings();
-                } while (Object.keys(this.pendingSessionSettings).length);
+                if (queryAccepted && !terminalReceived && this.executionState?.status !== "paused") {
+                    this.setExecutionState({ status: "interrupted", reason: "unexpected_termination" });
+                }
+                await this.flushSessionSettings();
             }
             finally {
                 this.running = false;
@@ -280,7 +362,7 @@ export class QueryEngine {
         }
     }
     /** Queue instance-local settings; no prompt messages or provider-global mutation. */
-    async updateSessionSettings(patch) {
+    async updateSessionSettings(patch, options = {}) {
         const normalized = {};
         if (Object.hasOwn(patch, "model"))
             normalized.model = patch.model?.trim() || undefined;
@@ -302,10 +384,26 @@ export class QueryEngine {
         }
         const mutation = this.settingsMutation.then(async () => {
             await this.initialize();
-            const update = await this.applySessionSettings(normalized, this.getHistoryMessages());
-            if (update?.compaction)
-                this.applyCompactionResult(update.compaction);
-            return { deferred: false, ...(update?.compaction ? { compaction: update.compaction } : {}) };
+            if (normalized.compact)
+                delete this.pendingSessionSettings.compact;
+            const previousExecution = this.getExecutionState();
+            if (normalized.compact)
+                this.setExecutionState({ status: "running", resumeCompaction: true });
+            try {
+                const update = await this.applySessionSettings(normalized, this.getHistoryMessages(), undefined, this.cancellableCompactor(options.abortSignal));
+                options.abortSignal?.throwIfAborted();
+                if (update?.compaction)
+                    this.applyCompactionResult(update.compaction);
+                if (normalized.compact)
+                    this.setExecutionState({ status: previousExecution?.status ?? "completed", reason: previousExecution?.reason });
+                return { deferred: false, ...(update?.compaction ? { compaction: update.compaction } : {}) };
+            }
+            catch (error) {
+                if (normalized.compact)
+                    this.setExecutionState(options.abortSignal?.aborted
+                        ? { status: "paused", reason: "user_pause" } : { status: "interrupted", reason: "compaction_failed" });
+                throw error;
+            }
         });
         // A rejected mutation must not poison subsequent settings or user input.
         this.settingsMutation = mutation.catch(() => undefined);
@@ -357,14 +455,14 @@ export class QueryEngine {
             patch.sessionPrompt = { ...patch.sessionPrompt };
         return patch;
     }
-    async consumeSessionSettings(messages) {
-        const patch = this.pendingSessionSettings;
+    async consumeSessionSettings(messages, started, compactor) {
+        const patch = { ...this.pendingSessionSettings, ...(this.executionState?.resumeCompaction ? { compact: true } : {}) };
         if (!Object.keys(patch).length)
             return undefined;
         this.pendingSessionSettings = {};
-        return this.applySessionSettings(patch, messages);
+        return this.applySessionSettings(patch, messages, started, compactor);
     }
-    async applySessionSettings(patch, messages) {
+    async applySessionSettings(patch, messages, started, activeCompactor) {
         const changed = {};
         if (Object.hasOwn(patch, "sessionPrompt"))
             this.activeSessionPrompt = patch.sessionPrompt ?? null;
@@ -388,23 +486,20 @@ export class QueryEngine {
         }
         let compaction;
         if (patch.compact) {
-            const compactor = this.options.compactor ?? new ModelDrivenCompactor(this.currentModelGateway);
-            const budget = { ...this.options.contextBudget, contextWindowTokens: this.currentContextWindowTokens ?? this.options.contextBudget?.contextWindowTokens };
+            const compactor = activeCompactor ?? this.cancellableCompactor();
+            const budget = { ...this.options.contextBudget, onCompactionStart: started, imageRegistry: this.imageStore?.snapshot(), contextWindowTokens: this.currentContextWindowTokens ?? this.options.contextBudget?.contextWindowTokens };
             compaction = withCompactionReport(await (compactor.manualCompact?.(messages, budget) ?? compactor.compact(messages, budget)), messages.length);
         }
         return Object.keys(changed).length || compaction ? { settings: changed, compaction } : undefined;
     }
     async flushSessionSettings() {
-        const results = [];
-        while (Object.keys(this.pendingSessionSettings).length) {
-            const update = await this.consumeSessionSettings(this.getHistoryMessages());
-            if (update?.compaction) {
-                this.applyCompactionResult(update.compaction);
-                if (update.compaction.changed)
-                    results.push(update.compaction);
-            }
+        // Ordinary settings can settle at the terminal boundary. A busy compact request
+        // must wait for the next model call, including when the current query ends/aborts.
+        while (Object.keys(this.pendingSessionSettings).some(key => key !== "compact")) {
+            const { compact, ...patch } = this.pendingSessionSettings;
+            this.pendingSessionSettings = compact ? { compact: true } : {};
+            await this.applySessionSettings(patch, this.getHistoryMessages());
         }
-        return results;
     }
     setModel(model, reasoning, updateReasoning = false) {
         this.currentModel = model?.trim() || undefined;
@@ -464,9 +559,13 @@ export class QueryEngine {
     reset() {
         if (this.running)
             throw new Error("cannot reset while query engine is running");
+        this.simulation = undefined;
+        this.displayOnlyMessages.length = 0;
         this.pendingSessionSettings = {};
         this.history.length = 0;
         this.lastTerminalReason = undefined;
+        this.executionState = undefined;
+        this.executionStartedAt = undefined;
         this.cancelPendingTitleWork();
         this.sessionStore?.reset();
         this.queryTiming = undefined;
@@ -476,16 +575,17 @@ export class QueryEngine {
     async compact(options = {}) {
         if (options.abortSignal?.aborted)
             return { messages: this.getHistoryMessages(), changed: false, reason: "none" };
-        const result = await this.updateSessionSettings({ compact: true });
+        const result = await this.updateSessionSettings({ compact: true }, options);
         return result.compaction ?? { messages: this.getHistoryMessages(), changed: false, reason: "none" };
     }
     async pureCompact(options = {}) {
         await this.initialize();
         if (options.abortSignal?.aborted)
             return { messages: this.getHistoryMessages(), changed: false, reason: "none" };
-        const compactor = this.options.compactor ?? new ModelDrivenCompactor(this.currentModelGateway);
+        const compactor = this.simulation?.compactor ?? this.options.compactor ?? new ModelDrivenCompactor(this.currentModelGateway);
         const contextBudget = {
             ...this.options.contextBudget,
+            imageRegistry: this.imageStore?.snapshot(),
             contextWindowTokens: this.currentContextWindowTokens ?? this.options.contextBudget?.contextWindowTokens,
         };
         const result = withCompactionReport(await (compactor.pureCompact?.(this.history, contextBudget) ?? { messages: this.getHistoryMessages(), changed: false, reason: "none" }), this.history.length);
@@ -521,12 +621,44 @@ export class QueryEngine {
         return [...records.values()].map(record => ({ ...record }));
     }
     getDisplayEntries() {
-        return this.sessionStore?.getDisplayEntries() ?? this.history.map((message) => ({ type: "message", message: cloneMessage(message) }));
+        return this.sessionStore?.getDisplayEntries() ?? [...this.history, ...this.displayOnlyMessages].map((message) => ({ type: "message", message: cloneMessage(message) }));
+    }
+    clearPendingCompaction() {
+        if (!this.executionState?.resumeCompaction)
+            return;
+        delete this.executionState.resumeCompaction;
+        this.setExecutionState(this.getExecutionState());
+    }
+    /** Keep the durable history untouched until the entire result can be committed. */
+    cancellableCompactor(signal) {
+        const source = this.simulation?.compactor ?? this.options.compactor ?? new ModelDrivenCompactor(this.currentModelGateway);
+        const run = (messages, budget = {}, kind = "compact", error) => {
+            const started = reason => {
+                signal?.throwIfAborted();
+                if (!this.executionState?.resumeCompaction) {
+                    this.setExecutionState({ ...(this.getExecutionState() ?? { status: "running" }), resumeCompaction: true });
+                }
+                budget.onCompactionStart?.(reason);
+            };
+            return abortableWork(async () => {
+                if (kind !== "compact")
+                    started(kind === "manualCompact" ? "manualcompact" : "reactive_compact");
+                const options = { ...budget, abortSignal: signal, onCompactionStart: started };
+                return kind === "reactiveCompact" && source.reactiveCompact ? source.reactiveCompact(messages, error, options)
+                    : kind === "manualCompact" && source.manualCompact ? source.manualCompact(messages, options)
+                        : source.compact(messages, options);
+            }, signal);
+        };
+        return { compact: (m, b) => run(m, b), manualCompact: (m, b) => run(m, b, "manualCompact"),
+            reactiveCompact: (m, e, b) => run(m, b, "reactiveCompact", e) };
     }
     applyCompactionResult(result) {
-        if (!result.changed)
+        if (!result.changed) {
+            this.clearPendingCompaction();
             return;
+        }
         this.sessionStore?.recordCompactCheckpoint(result.messages, result.reason, result.report);
+        this.clearPendingCompaction();
         this.history.length = 0;
         this.history.push(...result.messages.map(cloneMessage));
     }
@@ -559,14 +691,14 @@ export class QueryEngine {
         return this.buildPromptExportSnapshot(this.getHistoryMessages());
     }
     refreshToolsIfIdle() {
-        if (!this.running)
+        if (!this.running && !this.simulation)
             this.options.refreshTools?.(this);
     }
     async buildPromptExportSnapshot(messages, desiredState = this.sessionPromptState) {
         this.refreshToolsIfIdle();
         const toolContext = {
             agentId: this.agentId,
-            tools: this.options.tools,
+            tools: this.simulation?.tools ?? this.options.tools,
             appState: new InMemoryAppState(this.agentId, this.options.cwd),
             toolResultMemory: this.sessionStore?.toolResultMemory,
             session: this.sessionStore ? {
@@ -585,7 +717,7 @@ export class QueryEngine {
             },
             emit: () => undefined,
         };
-        const initialToolDefinitions = this.options.tools.definitions(toolContext);
+        const initialToolDefinitions = (this.simulation?.tools ?? this.options.tools).definitions(toolContext);
         const activePrompt = this.activeSessionPrompt;
         const baseline = await this.baselineContextManager.build({
             agentId: this.agentId,
@@ -630,24 +762,15 @@ export class QueryEngine {
         };
     }
     async persistMessageImages(message) {
-        if (!message.blocks.some((block) => block.type === "image"))
-            return message;
-        const persistedBlocks = await persistMessageImages(message.blocks, { sessionDir: this.sessionStore?.sessionDir, agentId: this.agentId });
-        const hasRetention = typeof message.metadata?.imageRetention === "string";
-        return {
-            ...message,
-            blocks: persistedBlocks,
-            metadata: message.role === "user"
-                ? { ...message.metadata, imageRetention: "pinned", imageTtlTurns: undefined }
-                : hasRetention
-                    ? message.metadata
-                    : { ...message.metadata, imageRetention: "while_relevant", imageTtlTurns: 4 },
-        };
+        this.imageStore ??= await SessionImageStore.open(this.sessionStore?.sessionDir, this.agentId);
+        return this.imageStore.persistMessage(message);
     }
     async openSession(options) {
         if (this.options.session?.enabled === false || !this.options.session)
             return;
         this.cancelPendingTitleWork();
+        this.simulation = undefined;
+        this.displayOnlyMessages.length = 0;
         this.sessionStore = await SessionStore.open({
             agentId: this.agentId,
             cwd: this.options.cwd ?? process.cwd(),
@@ -656,6 +779,11 @@ export class QueryEngine {
             resume: options.resume,
             toolResultThresholdChars: this.options.session.toolResultThresholdChars,
         });
+        this.imageStore = await SessionImageStore.open(this.sessionStore.sessionDir, this.agentId);
+        const execution = this.sessionStore.getExecutionState();
+        this.executionState = execution?.status === "running"
+            ? { ...execution, status: "interrupted", reason: "runtime_terminated" } : execution;
+        this.executionStartedAt = undefined;
         this.pendingSessionSettings = {};
         this.sessionPromptState = this.sessionStore.getSessionPrompt();
         this.activeSessionPrompt = this.sessionPromptState ?? null;
@@ -674,7 +802,7 @@ export class QueryEngine {
     }
     scheduleSessionTitleCheck() {
         const store = this.sessionStore;
-        if (!store || titleWorkComplete(store))
+        if (this.simulation || !store || titleWorkComplete(store))
             return;
         const version = this.titleSchedulerVersion;
         const timer = setTimeout(() => {
@@ -689,7 +817,7 @@ export class QueryEngine {
             if (version !== this.titleSchedulerVersion)
                 return;
             const store = this.sessionStore;
-            if (!store || titleWorkComplete(store))
+            if (this.simulation || !store || titleWorkComplete(store))
                 return;
             if (this.titleAgentRun?.version === version)
                 return;