@cjhyy/code-shell-core 0.9.5 → 0.9.6

package/dist/llm/providers/openai.js

@@ -16,7 +16,7 @@ import { capabilitiesFor } from "../capabilities/index.js";
 import { clampMaxTokens } from "../clamp-max-tokens.js";
 import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
 import { stripVisionFromHistory } from "../strip-vision.js";
-import { resolvePromptCachePolicy, uniquePromptCacheBreakpointIndexes, } from "../prompt-cache.js";
+import { createPromptCacheKey, PromptCacheHistory, resolvePromptCachePolicy, uniquePromptCacheBreakpointIndexes, } from "../prompt-cache.js";
 import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError } from "../stream-watchdog.js";
 /**
  * Extract prompt-cache counts from an OpenAI-compatible usage object.
@@ -25,8 +25,8 @@ import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError } from "../stream-watchd
  *   top-level field). Both OpenAI and OpenRouter report this.
  * - Cache WRITES (first-time prefix ingestion) are reported by OpenRouter as
  *   `prompt_tokens_details.cache_write_tokens` (verified live 2026-07-02).
- *   OpenAI's automatic caching has no separate write charge and omits it. We
- *   map it to `cacheCreationTokens` so the UI can show "writing cache" on the
+ *   Earlier OpenAI models omit it; GPT-5.6+ reports separately billed writes.
+ *   We map it to `cacheCreationTokens` so the UI can show "writing cache" on the
  *   first turn, not just hits on later turns.
  *
  * Returns a spreadable partial so callers omit each key entirely when the API
@@ -163,6 +163,9 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     return text;
 }
 const MISSING_TOOL_RESULT_WIRE_TEXT = "Error: Tool execution did not complete before the conversation resumed.";
+// Clients are recreated between Engine runs. Keep only bounded, expiring
+// boundary hashes across those recreations; never retain conversation text.
+const sharedPromptCacheHistory = new PromptCacheHistory();
 /**
  * OpenAI requires each assistant tool_calls batch to be followed immediately
  * by exactly one role:tool message per id. Normalize at the provider boundary
@@ -210,6 +213,7 @@ function normalizeOpenAIToolMessagePairs(messages) {
 }
 export class OpenAIClient extends LLMClientBase {
     _client = null;
+    promptCacheHistory;
     dangerouslyAllowBrowser;
     // Sticky override: once the endpoint tells us `max_tokens` is rejected for
     // this model, switch to `max_completion_tokens` for the lifetime of the
@@ -228,6 +232,7 @@ export class OpenAIClient extends LLMClientBase {
     _disablePromptCacheKey = false;
     constructor(config, defaults, runtimeOptions = {}) {
         super(config, defaults);
+        this.promptCacheHistory = runtimeOptions.promptCacheHistory ?? sharedPromptCacheHistory;
         this.dangerouslyAllowBrowser = runtimeOptions.dangerouslyAllowBrowser === true;
     }
     initClient() {
@@ -305,8 +310,35 @@ export class OpenAIClient extends LLMClientBase {
             // Per-call reasoning wins; otherwise fall back to provider default
             // (settings.providers[].reasoning, threaded through LLMConfig).
             const reasoning = options.reasoning ?? this.config.reasoning;
-            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning, options.promptCache);
+            const { messages, stablePrefixEndIndex } = this.buildMessages(options.systemPrompt, options.messages, reasoning, options.promptCache);
             const tools = options.tools?.length ? this.convertTools(options.tools) : undefined;
+            const cachePolicy = this.promptCachePolicy(options.promptCache);
+            let cachePlan;
+            if (cachePolicy.strategy === "openai-hybrid" && options.promptCache?.scopeId) {
+                let latestEligibleIndex = -1;
+                for (let index = messages.length - 1; index >= 0; index--) {
+                    const message = messages[index];
+                    if ((message.role === "user" || message.role === "tool") &&
+                        (typeof message.content === "string"
+                            ? message.content.length > 0
+                            : Array.isArray(message.content) && message.content.length > 0)) {
+                        latestEligibleIndex = index;
+                        break;
+                    }
+                }
+                // Hash the effective request settings, including tools and passthrough
+                // schemas. Transport streaming does not alter the rendered prefix.
+                const { messages: _cacheMessages, ...requestIdentity } = this.buildRequestBody(options, messages, tools, reasoning, false);
+                cachePlan = this.promptCacheHistory.prepare({
+                    scopeKey: createPromptCacheKey(options.promptCache.scopeId, JSON.stringify(this.getPromptCacheScopeIdentity())),
+                    messages,
+                    latestBoundaryIndex: latestEligibleIndex,
+                    requestIdentity,
+                });
+            }
+            if (options.promptCache || cachePolicy.strategy === "anthropic-explicit") {
+                this.applyPromptCacheBreakpoints(messages, cachePolicy, stablePrefixEndIndex, cachePlan?.readBoundaryIndex);
+            }
             const span = logger.span("llm.request", {
                 cat: "llm",
                 provider: this.provider,
@@ -314,12 +346,15 @@ export class OpenAIClient extends LLMClientBase {
                 stream: !!(options.stream && options.onChunk),
                 messageCount: messages.length,
                 toolCount: tools?.length ?? 0,
-                cacheStrategy: this.promptCachePolicy(options.promptCache).strategy,
+                cacheStrategy: cachePolicy.strategy,
             });
             try {
                 const response = options.stream && options.onChunk
                     ? await this.streamMessage(options, messages, tools, reasoning, requestSignal)
                     : await this.nonStreamMessage(options, messages, tools, reasoning, requestSignal);
+                if (cachePlan && !requestSignal?.aborted && (response.usage?.promptTokens ?? 0) > 0) {
+                    this.promptCacheHistory.commit(cachePlan);
+                }
                 span.end({
                     stopReason: response.stopReason,
                     promptTokens: response.usage?.promptTokens,
@@ -965,20 +1000,21 @@ export class OpenAIClient extends LLMClientBase {
         const stablePrefixEndIndex = stablePrefixEndMessage
             ? normalized.indexOf(stablePrefixEndMessage)
             : undefined;
-        const cachePolicy = this.promptCachePolicy(promptCache);
-        if (promptCache || cachePolicy.strategy === "anthropic-explicit") {
-            this.applyPromptCacheBreakpoints(normalized, cachePolicy, stablePrefixEndIndex !== undefined && stablePrefixEndIndex >= 0
+        return {
+            messages: normalized,
+            stablePrefixEndIndex: stablePrefixEndIndex !== undefined && stablePrefixEndIndex >= 0
                 ? stablePrefixEndIndex
-                : undefined);
-        }
-        return normalized;
+                : undefined,
+        };
     }
     /**
      * Translate semantic prefix boundaries to the active wire format. Both
      * formats annotate content blocks without reordering messages.
      */
-    applyPromptCacheBreakpoints(messages, policy, stablePrefixEndIndex) {
-        if (policy.strategy !== "anthropic-explicit" && policy.strategy !== "openai-explicit") {
+    applyPromptCacheBreakpoints(messages, policy, stablePrefixEndIndex, previousBoundaryIndex) {
+        if (policy.strategy !== "anthropic-explicit" &&
+            policy.strategy !== "openai-explicit" &&
+            policy.strategy !== "openai-hybrid") {
             return;
         }
         const markedMessages = new Set();
@@ -1014,7 +1050,14 @@ export class OpenAIClient extends LLMClientBase {
         const requested = uniquePromptCacheBreakpointIndexes([
             policy.breakpoints.includes("system") ? 0 : undefined,
             policy.breakpoints.includes("stable-history") ? stablePrefixEndIndex : undefined,
-            policy.breakpoints.includes("rolling-history") ? messages.length - 1 : undefined,
+            // Hybrid uses at most three explicit boundaries (system, stable, prior
+            // successful tail), leaving the fourth write slot for the implicit tail.
+            // Retaining the previous boundary lets this request read the last write.
+            policy.strategy === "openai-hybrid"
+                ? previousBoundaryIndex
+                : policy.breakpoints.includes("rolling-history")
+                    ? messages.length - 1
+                    : undefined,
         ]);
         for (const index of requested)
             mark(index);

package/dist/protocol/background-result-wakeup.d.ts

@@ -3,6 +3,11 @@ import { type NotificationQueue } from "../tool-system/builtin/agent-notificatio
 import type { ApprovalRouter } from "../tool-system/permission.js";
 import type { ChatSession } from "./chat-session.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
+import type { WorkspaceContext } from "../workspace/workspace-context.js";
+interface BackgroundRunWorkspace {
+    cwd?: string;
+    workspaceContext?: WorkspaceContext;
+}
 interface BackgroundResultWakeOptions {
     sessionId: string;
     manager: ChatSessionManager | null;
@@ -10,11 +15,13 @@ interface BackgroundResultWakeOptions {
     approvalRouter: ApprovalRouter;
     onStream(event: StreamEvent): void;
     notificationMailbox?: NotificationQueue;
+    /** Reconstruct fresh host authority for a cold, project-bound Session. */
+    resolveWorkspace?(session: ChatSession): Promise<BackgroundRunWorkspace>;
 }
 /**
  * Drain pending background results into exactly one synthetic continuation.
  * Busy sessions are awaited so a completion cannot fall into the gap between
  * the notification bus callback and the interactive run-boundary re-check.
  */
-export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox, }: BackgroundResultWakeOptions): Promise<boolean>;
+export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox, resolveWorkspace, }: BackgroundResultWakeOptions): Promise<boolean>;
 export {};

package/dist/protocol/background-result-wakeup.js

@@ -5,7 +5,7 @@ import { buildNotificationMessage, notificationQueue, } from "../tool-system/bui
  * Busy sessions are awaited so a completion cannot fall into the gap between
  * the notification bus callback and the interactive run-boundary re-check.
  */
-export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox = notificationQueue, }) {
+export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox = notificationQueue, resolveWorkspace, }) {
     if (!manager) {
         logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_chat_manager" });
         return false;
@@ -14,54 +14,92 @@ export async function wakeSessionForBackgroundResults({ sessionId, manager, rehy
         logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_unavailable" });
         return false;
     }
+    if (notificationMailbox.getSnapshot(sessionId).length === 0) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_pending_results" });
+        return false;
+    }
     let session = manager.get(sessionId) ?? (await rehydrate(sessionId));
     if (!session) {
         logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_missing" });
         return false;
     }
-    while (session.isBusy()) {
-        logger.debug("bg_wakeup.waiting_for_idle", {
-            sessionId,
-            pendingCount: notificationMailbox.getSnapshot(sessionId).length,
-        });
-        await session.settled;
-        if (manager.isUnavailable(sessionId)) {
-            logger.debug("bg_wakeup.skipped", {
+    let runWorkspace;
+    for (;;) {
+        if (manager.isUnavailable(sessionId) || manager.get(sessionId) !== session) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_owner_changed" });
+            return false;
+        }
+        while (session.isBusy()) {
+            logger.debug("bg_wakeup.waiting_for_idle", {
                 sessionId,
-                reason: "session_became_unavailable",
+                pendingCount: notificationMailbox.getSnapshot(sessionId).length,
             });
+            await session.settled;
+            if (manager.isUnavailable(sessionId)) {
+                logger.debug("bg_wakeup.skipped", {
+                    sessionId,
+                    reason: "session_became_unavailable",
+                });
+                return false;
+            }
+            const current = manager.get(sessionId);
+            if (!current) {
+                logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_evicted_after_settle" });
+                return false;
+            }
+            session = current;
+        }
+        // Headless/automation runs are one-shot and have no continuation consumer.
+        if (session.engine.isHeadless()) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "headless" });
             return false;
         }
-        const current = manager.get(sessionId);
-        if (!current) {
-            logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_evicted_after_settle" });
+        // A user Stop must win over a later background completion.
+        if (session.wasCancelledSinceLastTurn()) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "cancelled_since_last_turn" });
             return false;
         }
-        session = current;
-    }
-    // Headless/automation runs are one-shot and have no continuation consumer.
-    if (session.engine.isHeadless()) {
-        logger.debug("bg_wakeup.skipped", { sessionId, reason: "headless" });
-        return false;
-    }
-    // A user Stop must win over a later background completion.
-    if (session.wasCancelledSinceLastTurn()) {
-        logger.debug("bg_wakeup.skipped", { sessionId, reason: "cancelled_since_last_turn" });
-        return false;
-    }
-    let runWorkspace = {};
-    try {
-        const resolver = session.engine.resolveSessionRunWorkspace;
-        runWorkspace = resolver?.call(session.engine, sessionId) ?? {};
-    }
-    catch (error) {
-        // Resolve before draining so an unavailable authoritative worktree context
-        // leaves the completion recoverable by a later user run.
-        logger.warn("bg_wakeup.workspace_unavailable", {
-            sessionId,
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return false;
+        if (notificationMailbox.getSnapshot(sessionId).length === 0) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_pending_results" });
+            return false;
+        }
+        const resolvedEngine = session.engine;
+        const settledBeforeResolution = session.settled;
+        try {
+            if (resolveWorkspace) {
+                runWorkspace = await resolveWorkspace(session);
+            }
+            else {
+                const resolver = session.engine.resolveSessionRunWorkspace;
+                runWorkspace = resolver?.call(session.engine, sessionId) ?? {};
+            }
+        }
+        catch (error) {
+            // Resolve before draining so an unavailable authoritative worktree context
+            // leaves the completion recoverable by a later user run.
+            logger.warn("bg_wakeup.workspace_unavailable", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+        // Host resolution yields to other turns, Stop, close and root migration.
+        // Validate ownership before consuming anything, and never carry a context
+        // across an intervening run boundary even when that run already finished.
+        if (manager.isUnavailable(sessionId) || manager.get(sessionId) !== session) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_owner_changed" });
+            return false;
+        }
+        if (session.wasCancelledSinceLastTurn()) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "cancelled_since_last_turn" });
+            return false;
+        }
+        if (session.isBusy() ||
+            session.engine !== resolvedEngine ||
+            session.settled !== settledBeforeResolution) {
+            continue;
+        }
+        break;
     }
     const pending = notificationMailbox.drainAll(sessionId);
     if (pending.length === 0) {

package/dist/protocol/chat-session-manager.d.ts

@@ -36,6 +36,12 @@ export interface ChatSessionManagerOptions {
      */
     dataRoot?: string;
 }
+export interface GetOrCreateSessionOptions {
+    /** Only explicit user opens may clear a closed Session's tombstone. */
+    allowReopen?: boolean;
+    /** Cancel lifecycle waits without creating or reopening the Session. */
+    signal?: AbortSignal;
+}
 export interface LiveChatSessionSnapshot {
     generation: number;
     /** Identity scope of the manager that produced this snapshot. */
@@ -95,7 +101,7 @@ export declare class ChatSessionManager {
      * identity; each call here builds a fresh instance.
      */
     forIdentity(identity: string): ChatSessionManager;
-    getOrCreate(sessionId: string, slice: EngineConfigSlice): Promise<ChatSession>;
+    getOrCreate(sessionId: string, slice: EngineConfigSlice, options?: GetOrCreateSessionOptions): Promise<ChatSession>;
     /**
      * Prove whether this worker currently owns a resident Engine, or fence the
      * Session so Main can perform one durable migration without a re-resume race.

package/dist/protocol/chat-session-manager.js

@@ -28,6 +28,27 @@ function assertSafeIdentity(identity) {
         throw new Error(`invalid identity: unexpected characters: ${identity}`);
     }
 }
+function waitForSessionTransition(transition, signal) {
+    if (!signal)
+        return transition;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (failed = false, error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            if (failed)
+                reject(error);
+            else
+                resolve();
+        };
+        const onAbort = () => finish(true, signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        transition.then(() => finish(), (error) => finish(true, error));
+    });
+}
 export const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
 export class ChatSessionManager {
     sessions = new Map();
@@ -80,29 +101,37 @@ export class ChatSessionManager {
             engineFactory: (slice) => baseFactory({ ...slice, sessionStorageDir }),
         });
     }
-    async getOrCreate(sessionId, slice) {
+    async getOrCreate(sessionId, slice, options = {}) {
+        const assertAccess = () => {
+            options.signal?.throwIfAborted();
+            if (options.allowReopen === false && this.isUnavailable(sessionId)) {
+                throw new Error(`target Session is closing or closed: ${sessionId}`);
+            }
+        };
         // A non-resident migration claim is a short ownership handoff to Main.
         // Wait rather than fail the user's run: once Main atomically commits (or
         // aborts) and releases the token, the Engine is created from current disk.
         for (;;) {
+            assertAccess();
             const residentMigration = this.residentMigrations.get(sessionId);
             if (residentMigration) {
-                await residentMigration.released;
+                await waitForSessionTransition(residentMigration.released, options.signal);
                 continue;
             }
             const claim = this.migrationClaims.get(sessionId);
             if (claim) {
-                await claim.released;
+                await waitForSessionTransition(claim.released, options.signal);
                 continue;
             }
             const closing = this.closingSessions.get(sessionId);
             if (closing) {
-                await closing;
+                await waitForSessionTransition(closing, options.signal);
                 continue;
             }
             // No await separates the final claim check from getOrCreateNow. On this
             // process's event loop, either this creates the resident owner first or
             // beginSessionMigration installs the fence first; both cannot win.
+            assertAccess();
             return this.getOrCreateNow(sessionId, slice);
         }
     }
@@ -327,13 +356,20 @@ export class ChatSessionManager {
         return this.closeSession(sessionId, true);
     }
     closeSession(sessionId, markClosed) {
-        const migration = this.residentMigrations.get(sessionId);
-        if (migration) {
-            return migration.released.then(() => this.closeSession(sessionId, markClosed));
-        }
         const alreadyClosing = this.closingSessions.get(sessionId);
         if (alreadyClosing)
             return alreadyClosing;
+        const migration = this.residentMigrations.get(sessionId);
+        if (migration) {
+            // Publish closing intent before waiting so internal senders cannot
+            // acquire the migrated owner ahead of this deferred close operation.
+            const closing = migration.released.then(() => {
+                this.closingSessions.delete(sessionId);
+                return this.closeSession(sessionId, markClosed);
+            });
+            this.closingSessions.set(sessionId, closing);
+            return closing;
+        }
         const s = this.sessions.get(sessionId);
         if (!s) {
             if (sessionId.startsWith("qchat-")) {

package/dist/protocol/chat-session.d.ts

@@ -28,6 +28,8 @@ export interface TurnOpts {
     /** Goal mode for this turn — forwarded to engine.run (loop-until-done).
      *  String objective or full GoalConfig (objective + optional budgets). */
     goal?: string | import("../goal/lifecycle.js").GoalConfig;
+    /** Disable all Goal resolution for this standalone turn. */
+    disableGoal?: boolean;
     /** Marks this turn as a synthetic system-reminder injection (background-job
      *  completion notification) rather than the user's own input — persisted so
      *  the disk reader skips it as a user bubble on replay. See Engine.run. */

package/dist/protocol/chat-session.js

@@ -138,7 +138,9 @@ export class ChatSession {
         // Drain queued turns as cancelled
         const drained = this.queue.splice(0);
         for (const t of drained) {
-            t.reject(new Error("cancelled: session aborted before turn ran"));
+            t.reject(Object.assign(new Error("cancelled: session aborted before turn ran"), {
+                name: "AbortError",
+            }));
         }
     }
     isBusy() {
@@ -306,6 +308,7 @@ export class ChatSession {
                 signal: this.controller.signal,
                 onStream,
                 goal: next.opts.goal,
+                disableGoal: next.opts.disableGoal,
                 injected: next.opts.injected,
                 clientMessageId: next.opts.clientMessageId,
                 archiveBeforeCurrentTurn: next.opts.archiveBeforeCurrentTurn,

package/dist/protocol/server.d.ts

@@ -371,6 +371,9 @@ export declare class AgentServer {
     private makePanelBridge;
     private requestPanelActionForSession;
     private requestWorkspaceSwitchForSession;
+    /** The same host authority resolves both dispatched turns and their reply wakeups. */
+    private resolveHostSessionWorkspace;
+    private requestWorkspaceActionForSession;
     /**
      * Ask the client to answer a question from the agent (legacy single-engine
      * path). This intentionally has no wall-clock timeout; Stop/cancel drains