neoctl 0.2.37 → 0.2.39

package/dist/core/query-engine.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { InMemoryAppState } from "../app/app-state.js";
 import { InMemoryAppPromptStore } from "../app/app-prompt.js";
 import { AppPromptContextManager, DefaultContextManager, readProjectMemoryDocuments } from "../context/context-manager.js";
@@ -14,6 +15,7 @@ import { GENERAL_PURPOSE_AGENT } from "../agents/agent-definition.js";
 import { SessionStore } from "../session/session-store.js";
 import { buildPromptCacheDiagnostics } from "./prompt-cache-telemetry.js";
 import { computeStaticTokens } from "./context-metrics.js";
+import { applySessionPrompt, sessionPromptMode, createSessionPromptSnapshot, parseSessionPromptUpdate, SessionPromptError } from "./session-settings-prompt.js";
 const DEFAULT_SESSION_TITLE_DELAY_MS = 5000;
 export class QueryEngine {
     options;
@@ -25,14 +27,23 @@ export class QueryEngine {
     currentModel;
     currentReasoning;
     currentFastMode = false;
+    running = false;
+    pendingSessionSettings = {};
+    sessionPromptState;
+    activeSessionPrompt = null;
+    ephemeralSessionKey = randomUUID();
+    // Idle mutations and the next generator share a barrier. Never compact alongside a request.
+    settingsMutation = Promise.resolve();
     currentContextWindowTokens;
     currentModelGateway;
     sessionInitialized = false;
+    sessionInitialization;
     titleSchedulerVersion = 0;
     titleAgentRun;
     sessionTitleListeners = new Set();
     appPromptStore;
     contextManager;
+    baselineContextManager;
     additionalPromptContextManager;
     pendingCwdTransitionPaths;
     pendingRequestContext;
@@ -49,7 +60,12 @@ export class QueryEngine {
             ?? options.contextManager
             ?? new DefaultContextManager({ cwd: options.cwd });
         this.additionalPromptContextManager = new AdditionalPromptContextManager(baseContextManager, options.additionalPromptSections);
-        this.contextManager = new AppPromptContextManager(this.additionalPromptContextManager, this.appPromptStore);
+        this.baselineContextManager = new AppPromptContextManager(this.additionalPromptContextManager, this.appPromptStore);
+        this.contextManager = { build: async (input) => {
+                // Capture before any asynchronous baseline work: an in-flight request never observes a later edit.
+                const content = this.activeSessionPrompt;
+                return applySessionPrompt(await this.baselineContextManager.build(input), content);
+            } };
         this.pendingCwdTransitionPaths = normalizeCwdTransitionPaths(options.cwdTransitionPaths);
     }
     forkForSession(sessionId, resume = true) {
@@ -77,25 +93,39 @@ export class QueryEngine {
             this.pendingRequestContextConsumed = onConsumed;
     }
     async initialize() {
+        if (this.sessionInitialization)
+            return this.sessionInitialization;
         if (this.sessionInitialized)
             return;
-        this.sessionInitialized = true;
-        if (this.options.session?.enabled === false)
-            return;
-        if (!this.options.session)
-            return;
-        await this.openSession({
-            sessionId: this.options.session.sessionId,
-            resume: this.options.session.resume,
-        });
+        const initialization = (async () => {
+            if (this.options.session?.enabled !== false && this.options.session) {
+                await this.openSession({ sessionId: this.options.session.sessionId, resume: this.options.session.resume });
+            }
+            this.sessionInitialized = true;
+        })();
+        this.sessionInitialization = initialization;
+        try {
+            await initialization;
+        }
+        finally {
+            this.sessionInitialization = undefined;
+        }
     }
     async newSession() {
-        this.sessionInitialized = true;
-        await this.openSession({ resume: false });
-        const snapshot = this.sessionStore?.snapshot();
-        if (!snapshot)
-            throw new Error("session transcripts are disabled");
-        return snapshot;
+        if (this.running)
+            throw new Error("cannot switch session while query engine is running");
+        const mutation = this.settingsMutation.then(async () => {
+            await this.sessionInitialization;
+            await this.openSession({ resume: false });
+            this.sessionInitialized = true;
+            const snapshot = this.sessionStore?.snapshot();
+            if (!snapshot)
+                throw new Error("session transcripts are disabled");
+            return snapshot;
+        });
+        // Session switches share the editor barrier: stale saves can never land in a new session.
+        this.settingsMutation = mutation.catch(() => undefined);
+        return mutation;
     }
     async listSessions(limit = 10) {
         if (this.options.session?.enabled === false || !this.options.session)
@@ -121,92 +151,250 @@ export class QueryEngine {
         });
     }
     async *sendUserText(text, options = {}) {
-        await this.initialize();
-        const cwdTransitionPaths = this.pendingCwdTransitionPaths;
-        const pendingRequestContext = this.pendingRequestContext;
-        const pendingRequestContextConsumed = this.pendingRequestContextConsumed;
-        this.pendingCwdTransitionPaths = undefined;
-        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();
-        const initMessage = createSystemInitMessage({
-            agentId: this.agentId,
-            tools: this.options.tools.names(),
-            model: this.currentModel,
-            commands: [...(this.options.commands ?? [])],
-            agents: [...(this.options.agents ?? [])],
-            skills: [...(this.options.skills ?? [])],
-            plugins: [...(this.options.plugins ?? [])],
-        });
-        initMessage.metadata = {
-            ...initMessage.metadata,
-            reasoning: cloneReasoningConfig(this.currentReasoning),
-        };
-        yield {
-            type: "message",
-            message: initMessage,
-        };
-        this.sessionStore?.recordMessage(initMessage);
-        const queryOptions = {
-            agentId: this.agentId,
-            model: this.currentModel,
-            reasoning: cloneReasoningConfig(this.currentReasoning),
-            queryOrigin: this.options.queryOrigin ?? "repl",
-            serviceTier: this.currentFastMode ? "priority" : undefined,
-            maxOutputTokensOverride: this.options.maxOutputTokensOverride,
-            contextWindowTokensOverride: this.currentContextWindowTokens,
-            maxTurns: this.options.maxTurns,
-            workspaceCwd: this.options.cwd,
-            requestContext: pendingRequestContext || cwdTransitionPaths?.length
-                ? {
-                    ...pendingRequestContext,
-                    ...(cwdTransitionPaths?.length
-                        ? { cwdTransition: { paths: cwdTransitionPaths, current: cwdTransitionPaths.at(-1) } }
-                        : {}),
+        if (this.running)
+            throw new Error("query engine is already running");
+        this.running = true;
+        try {
+            await this.settingsMutation;
+            await this.initialize();
+            const cwdTransitionPaths = this.pendingCwdTransitionPaths;
+            const pendingRequestContext = this.pendingRequestContext;
+            const pendingRequestContextConsumed = this.pendingRequestContextConsumed;
+            this.pendingCwdTransitionPaths = undefined;
+            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();
+            const initMessage = createSystemInitMessage({
+                agentId: this.agentId,
+                tools: this.options.tools.names(),
+                model: this.currentModel,
+                commands: [...(this.options.commands ?? [])],
+                agents: [...(this.options.agents ?? [])],
+                skills: [...(this.options.skills ?? [])],
+                plugins: [...(this.options.plugins ?? [])],
+            });
+            initMessage.metadata = {
+                ...initMessage.metadata,
+                reasoning: cloneReasoningConfig(this.currentReasoning),
+            };
+            yield {
+                type: "message",
+                message: initMessage,
+            };
+            this.sessionStore?.recordMessage(initMessage);
+            const queryOptions = {
+                agentId: this.agentId,
+                model: this.currentModel,
+                reasoning: cloneReasoningConfig(this.currentReasoning),
+                queryOrigin: this.options.queryOrigin ?? "repl",
+                serviceTier: this.currentFastMode ? "priority" : undefined,
+                maxOutputTokensOverride: this.options.maxOutputTokensOverride,
+                contextWindowTokensOverride: this.currentContextWindowTokens,
+                maxTurns: this.options.maxTurns,
+                workspaceCwd: this.options.cwd,
+                requestContext: pendingRequestContext || cwdTransitionPaths?.length
+                    ? {
+                        ...pendingRequestContext,
+                        ...(cwdTransitionPaths?.length
+                            ? { cwdTransition: { paths: cwdTransitionPaths, current: cwdTransitionPaths.at(-1) } }
+                            : {}),
+                    }
+                    : undefined,
+                onRequestContextConsumed: pendingRequestContext ? () => {
+                    pendingRequestContextConsumed?.();
+                    if (this.pendingRequestContext === pendingRequestContext) {
+                        this.pendingRequestContext = undefined;
+                        this.pendingRequestContextConsumed = undefined;
+                    }
+                } : undefined,
+                abortSignal: options.abortSignal,
+                stopAfterTurn: options.stopAfterTurn,
+                beforeTurn: (messages) => {
+                    this.options.refreshTools?.();
+                    return this.consumeSessionSettings(messages);
+                },
+            };
+            const stream = query(this.history, {
+                ...this.options,
+                contextManager: this.contextManager,
+                modelGateway: this.currentModelGateway,
+                taskNotificationSource: this.options.taskNotificationSource,
+                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),
+                exportToolCalls: (calls) => this.recordSyntheticToolCalls(calls),
+                applyCompaction: (result) => this.applyCompactionResult(result),
+            }, queryOptions);
+            for await (const event of stream) {
+                if (event.type === "message") {
+                    const message = await this.persistMessageImages(event.message);
+                    this.history.push(message);
+                    this.sessionStore?.recordMessage(message);
+                    yield { ...event, message };
+                    continue;
                 }
-                : undefined,
-            onRequestContextConsumed: pendingRequestContext ? () => {
-                pendingRequestContextConsumed?.();
-                if (this.pendingRequestContext === pendingRequestContext) {
-                    this.pendingRequestContext = undefined;
-                    this.pendingRequestContextConsumed = undefined;
+                if (event.type === "terminal") {
+                    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 (hadPending)
+                        yield { type: "context.metrics", metrics: await this.contextMetrics() };
                 }
-            } : undefined,
-            abortSignal: options.abortSignal,
-            stopAfterTurn: options.stopAfterTurn,
-        };
-        const stream = query(this.history, {
-            ...this.options,
-            contextManager: this.contextManager,
-            modelGateway: this.currentModelGateway,
-            taskNotificationSource: this.options.taskNotificationSource,
-            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),
-            exportToolCalls: (calls) => this.recordSyntheticToolCalls(calls),
-            applyCompaction: (result) => this.applyCompactionResult(result),
-        }, queryOptions);
-        for await (const event of stream) {
-            if (event.type === "message") {
-                const message = await this.persistMessageImages(event.message);
-                this.history.push(message);
-                this.sessionStore?.recordMessage(message);
-                yield { ...event, message };
-                continue;
+                yield event;
             }
-            if (event.type === "terminal")
-                this.lastTerminalReason = event.reason;
-            yield event;
         }
+        finally {
+            // Covers initialization errors, aborts, exceptions and consumer generator.return().
+            // Do not yield in finally: a closing consumer may never resume the generator.
+            try {
+                do {
+                    await this.flushSessionSettings();
+                } while (Object.keys(this.pendingSessionSettings).length);
+            }
+            finally {
+                this.running = false;
+            }
+        }
+    }
+    /** Queue instance-local settings; no prompt messages or provider-global mutation. */
+    async updateSessionSettings(patch) {
+        const normalized = {};
+        if (Object.hasOwn(patch, "model"))
+            normalized.model = patch.model?.trim() || undefined;
+        if (Object.hasOwn(patch, "reasoning"))
+            normalized.reasoning = cloneReasoningConfig(patch.reasoning);
+        if (Object.hasOwn(patch, "fastMode"))
+            normalized.fastMode = patch.fastMode === true;
+        if (Object.hasOwn(patch, "contextWindowTokens")) {
+            const tokens = normalizePositiveInteger(patch.contextWindowTokens);
+            if (!tokens)
+                throw new Error("context window tokens must be a positive integer");
+            normalized.contextWindowTokens = tokens;
+        }
+        if (patch.compact)
+            normalized.compact = true;
+        if (this.running) {
+            this.pendingSessionSettings = { ...this.pendingSessionSettings, ...normalized };
+            return { deferred: true };
+        }
+        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 } : {}) };
+        });
+        // A rejected mutation must not poison subsequent settings or user input.
+        this.settingsMutation = mutation.catch(() => undefined);
+        return mutation;
+    }
+    /** Editor state includes accepted queued changes; runtime exports still describe the active turn. */
+    async getSessionPrompt() {
+        await this.settingsMutation;
+        await this.initialize();
+        const snapshot = await this.buildPromptExportSnapshot(this.getHistoryMessages());
+        return snapshot.sessionPromptConfig;
+    }
+    async updateSessionPrompt(input) {
+        const update = parseSessionPromptUpdate(input);
+        const mutation = this.settingsMutation.then(async () => {
+            await this.initialize();
+            const key = this.sessionPromptKey();
+            const snapshot = await this.buildPromptExportSnapshot(this.getHistoryMessages());
+            const current = snapshot.sessionPromptConfig;
+            if (key !== this.sessionPromptKey() || update.revision !== current.revision) {
+                throw new SessionPromptError("session prompt changed; reload before saving", 409);
+            }
+            if (!update.reset && update.mode === "legacy_full_override" && current.mode !== "legacy_full_override") {
+                throw new SessionPromptError("full replacement is only supported for existing legacy prompts", 400);
+            }
+            const state = { content: update.reset ? null : update.content, mode: update.reset ? "inherit" : update.mode ?? (current.mode === "legacy_full_override" ? "legacy_full_override" : "append"), revision: randomUUID() };
+            const nextSnapshot = (await this.buildPromptExportSnapshot(this.getHistoryMessages(), state)).sessionPromptConfig;
+            // Persist before accepting, including busy edits, so same-session resume cannot lose them.
+            this.sessionStore?.recordSessionPrompt(state);
+            this.sessionPromptState = state;
+            const deferred = this.running;
+            if (deferred)
+                this.pendingSessionSettings = { ...this.pendingSessionSettings, sessionPrompt: state };
+            else
+                this.activeSessionPrompt = state;
+            return { ok: true, ...nextSnapshot, deferred };
+        });
+        this.settingsMutation = mutation.catch(() => undefined);
+        return mutation;
+    }
+    sessionPromptKey() {
+        return this.sessionStore ? `${this.sessionStore.sessionDir}:${this.agentId}` : this.ephemeralSessionKey;
+    }
+    getPendingSessionSettings() {
+        const patch = { ...this.pendingSessionSettings };
+        if (Object.hasOwn(patch, "reasoning"))
+            patch.reasoning = cloneReasoningConfig(patch.reasoning);
+        if (patch.sessionPrompt)
+            patch.sessionPrompt = { ...patch.sessionPrompt };
+        return patch;
+    }
+    async consumeSessionSettings(messages) {
+        const patch = this.pendingSessionSettings;
+        if (!Object.keys(patch).length)
+            return undefined;
+        this.pendingSessionSettings = {};
+        return this.applySessionSettings(patch, messages);
+    }
+    async applySessionSettings(patch, messages) {
+        const changed = {};
+        if (Object.hasOwn(patch, "sessionPrompt"))
+            this.activeSessionPrompt = patch.sessionPrompt ?? null;
+        if (Object.hasOwn(patch, "model") && patch.model !== this.currentModel) {
+            this.currentModel = patch.model;
+            changed.model = patch.model;
+        }
+        if (Object.hasOwn(patch, "reasoning") && !sameReasoningConfig(patch.reasoning, this.currentReasoning)) {
+            this.currentReasoning = cloneReasoningConfig(patch.reasoning);
+            changed.reasoning = cloneReasoningConfig(patch.reasoning);
+        }
+        if (Object.hasOwn(patch, "fastMode") && patch.fastMode !== this.currentFastMode) {
+            this.currentFastMode = patch.fastMode === true;
+            this.sessionStore?.recordFastMode(this.currentFastMode);
+            changed.fastMode = this.currentFastMode;
+        }
+        if (Object.hasOwn(patch, "contextWindowTokens") && patch.contextWindowTokens !== this.currentContextWindowTokens) {
+            this.currentContextWindowTokens = patch.contextWindowTokens;
+            this.sessionStore?.recordContextWindowTokens(this.currentContextWindowTokens);
+            changed.contextWindowTokens = this.currentContextWindowTokens;
+        }
+        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 };
+            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);
+            }
+        }
+        return results;
     }
     setModel(model, reasoning, updateReasoning = false) {
         this.currentModel = model?.trim() || undefined;
@@ -264,6 +452,9 @@ export class QueryEngine {
         return this.appPromptStore.snapshot();
     }
     reset() {
+        if (this.running)
+            throw new Error("cannot reset while query engine is running");
+        this.pendingSessionSettings = {};
         this.history.length = 0;
         this.lastTerminalReason = undefined;
         this.cancelPendingTitleWork();
@@ -271,17 +462,10 @@ export class QueryEngine {
         this.notifySessionTitleChange(this.sessionStore?.snapshot());
     }
     async compact(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 contextBudget = {
-            ...this.options.contextBudget,
-            contextWindowTokens: this.currentContextWindowTokens ?? this.options.contextBudget?.contextWindowTokens,
-        };
-        const result = withCompactionReport(await (compactor.manualCompact?.(this.history, contextBudget) ?? compactor.compact(this.history, contextBudget)), this.history.length);
-        this.applyCompactionResult(result);
-        return result;
+        const result = await this.updateSessionSettings({ compact: true });
+        return result.compaction ?? { messages: this.getHistoryMessages(), changed: false, reason: "none" };
     }
     async pureCompact(options = {}) {
         await this.initialize();
@@ -353,7 +537,12 @@ export class QueryEngine {
         await this.initialize();
         return this.buildPromptExportSnapshot(this.getHistoryMessages());
     }
-    async buildPromptExportSnapshot(messages) {
+    refreshToolsIfIdle() {
+        if (!this.running)
+            this.options.refreshTools?.();
+    }
+    async buildPromptExportSnapshot(messages, desiredState = this.sessionPromptState) {
+        this.refreshToolsIfIdle();
         const toolContext = {
             agentId: this.agentId,
             tools: this.options.tools,
@@ -376,13 +565,16 @@ export class QueryEngine {
             emit: () => undefined,
         };
         const initialToolDefinitions = this.options.tools.definitions(toolContext);
-        const context = await this.contextManager.build({
+        const activePrompt = this.activeSessionPrompt;
+        const baseline = await this.baselineContextManager.build({
             agentId: this.agentId,
             messages,
             enabledTools: initialToolDefinitions.map((tool) => tool.name),
             toolUseContext: toolContext,
         });
-        const toolDefinitions = this.options.tools.definitions(toolContext);
+        const context = applySessionPrompt(baseline, activePrompt);
+        const desiredPrompt = createSessionPromptSnapshot(this.sessionPromptKey(), desiredState, baseline);
+        const toolDefinitions = initialToolDefinitions;
         const messagesWithUserContext = applyRuntimeContextForPromptCache([], context.userContext, {});
         const userContextPrompt = messagesWithUserContext[0]?.blocks
             .filter((block) => block.type === "text")
@@ -392,7 +584,17 @@ export class QueryEngine {
             model: this.currentModel,
             reasoning: cloneReasoningConfig(this.currentReasoning),
             systemPrompt: context.systemPrompt,
-            baseSystemPrompt: context.systemPrompt,
+            baseSystemPrompt: baseline.systemPrompt,
+            sessionPromptConfig: desiredPrompt,
+            sessionPrompt: {
+                mode: sessionPromptMode(activePrompt),
+                pendingMode: desiredPrompt.mode,
+                effectiveRevision: createSessionPromptSnapshot(this.sessionPromptKey(), activePrompt ?? undefined, baseline).effectiveRevision,
+                override: sessionPromptMode(activePrompt) !== "inherit",
+                revision: desiredPrompt.revision,
+                deferred: Object.hasOwn(this.pendingSessionSettings, "sessionPrompt"),
+                pendingOverride: desiredPrompt.override,
+            },
             promptSections: context.promptSections,
             userContext: context.userContext,
             systemContext: context.systemContext,
@@ -449,6 +651,9 @@ export class QueryEngine {
             resume: options.resume,
             toolResultThresholdChars: this.options.session.toolResultThresholdChars,
         });
+        this.pendingSessionSettings = {};
+        this.sessionPromptState = this.sessionStore.getSessionPrompt();
+        this.activeSessionPrompt = this.sessionPromptState ?? null;
         this.history.length = 0;
         if (options.resume)
             this.history.push(...this.sessionStore.getInitialMessages());
@@ -609,6 +814,11 @@ function resolveSessionTitleDelayMs() {
     }
     return DEFAULT_SESSION_TITLE_DELAY_MS;
 }
+function sameReasoningConfig(a, b) {
+    if (a === null || b === null || a === undefined || b === undefined)
+        return a === b;
+    return a.effort === b.effort && a.summary === b.summary;
+}
 function cloneReasoningConfig(reasoning) {
     if (reasoning === null)
         return null;