@cjhyy/code-shell-core 0.7.0 → 0.7.1

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

@@ -15,16 +15,24 @@ export interface ChatSessionManagerOptions {
     maxSessions?: number;
     idleTtlMs?: number;
 }
+export declare const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
 export declare class ChatSessionManager {
     private readonly sessions;
+    private readonly closingSessions;
+    private readonly closedSessions;
+    private readonly sessionGeneration;
     readonly runtime: EngineRuntime;
     private readonly factory;
     private readonly maxSessions;
     private readonly idleTtlMs;
     private sweeper;
     constructor(opts: ChatSessionManagerOptions);
-    getOrCreate(sessionId: string, slice: EngineConfigSlice): ChatSession;
+    getOrCreate(sessionId: string, slice: EngineConfigSlice): Promise<ChatSession>;
+    private getOrCreateNow;
     get(sessionId: string): ChatSession | undefined;
+    isClosing(sessionId: string): boolean;
+    isClosed(sessionId: string): boolean;
+    isUnavailable(sessionId: string): boolean;
     sessionExistsOnDisk(sessionId: string, slice: EngineConfigSlice): boolean;
     /**
      * Iterate every live session once. Public iterator so callers (e.g. the
@@ -33,7 +41,9 @@ export declare class ChatSessionManager {
      * the values so a callback that closes a session can't perturb the walk.
      */
     forEachSession(fn: (s: ChatSession) => void): void;
-    close(sessionId: string): void;
+    close(sessionId: string): Promise<void>;
+    private closeSession;
+    private rememberClosedSession;
     closeAll(): void;
     /**
      * Await-able shutdown. Cancels every session and reaps every background
@@ -46,4 +56,5 @@ export declare class ChatSessionManager {
     startIdleSweeper(intervalMs?: number): void;
     stopIdleSweeper(): void;
     private unregisterMcpOwner;
+    private engineSessionManager;
 }

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

@@ -7,8 +7,12 @@ import { clearInjectCredentialSessionAllow } from "../credentials/inject-credent
 import { logger } from "../logging/logger.js";
 import { clearSessionPathApprovals, openSessionPathApprovals } from "../tool-system/path-policy.js";
 import { clearInteractiveApprovalSession, openInteractiveApprovalSession, } from "../tool-system/permission.js";
+export const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
 export class ChatSessionManager {
     sessions = new Map();
+    closingSessions = new Map();
+    closedSessions = new Set();
+    sessionGeneration = new Map();
     runtime;
     factory;
     maxSessions;
@@ -20,22 +24,21 @@ export class ChatSessionManager {
         this.maxSessions = opts.maxSessions ?? 16;
         this.idleTtlMs = opts.idleTtlMs ?? 30 * 60 * 1000;
     }
-    getOrCreate(sessionId, slice) {
+    async getOrCreate(sessionId, slice) {
+        const closing = this.closingSessions.get(sessionId);
+        if (closing) {
+            await closing;
+        }
+        return this.getOrCreateNow(sessionId, slice);
+    }
+    getOrCreateNow(sessionId, slice) {
         openSessionPathApprovals(sessionId);
         openInteractiveApprovalSession(sessionId);
         const existing = this.sessions.get(sessionId);
         if (existing) {
             existing.lastActivityAt = Date.now();
-            // Re-apply the per-send permission mode so a pill change on an
-            // already-running session takes effect on the NEXT turn. Without this the
-            // engine kept whatever mode it was first created with — changing the pill
-            // on a resumed session was silently ignored at enforcement time (#11
-            // secondary: "档位 doesn't take effect after first send"). setPermissionMode
-            // reconfigures the live permission backend, so it's safe between turns.
-            if (slice.permissionMode &&
-                typeof existing.engine.getPermissionMode === "function" &&
-                existing.engine.getPermissionMode() !== slice.permissionMode) {
-                existing.engine.setPermissionMode(slice.permissionMode);
+            if (slice.permissionMode && existing.engine.getPermissionMode?.() !== slice.permissionMode) {
+                existing.engine.setPermissionMode?.(slice.permissionMode);
             }
             return existing;
         }
@@ -46,12 +49,27 @@ export class ChatSessionManager {
         }
         const engine = this.factory(slice);
         const session = new ChatSession({ id: sessionId, engine });
+        const sessionManager = this.engineSessionManager(engine);
+        const generation = sessionManager?.registerSessionGeneration(sessionId) ?? 1;
+        this.sessionGeneration.set(sessionId, generation);
         this.sessions.set(sessionId, session);
+        // A direct user run is an explicit resume/open and may clear the tombstone.
+        // Background wakeups must check isUnavailable() before reaching this path.
+        this.closedSessions.delete(sessionId);
         return session;
     }
     get(sessionId) {
         return this.sessions.get(sessionId);
     }
+    isClosing(sessionId) {
+        return this.closingSessions.has(sessionId);
+    }
+    isClosed(sessionId) {
+        return this.closedSessions.has(sessionId);
+    }
+    isUnavailable(sessionId) {
+        return this.isClosing(sessionId) || this.isClosed(sessionId);
+    }
     sessionExistsOnDisk(sessionId, slice) {
         const existing = this.sessions.get(sessionId);
         if (existing)
@@ -70,16 +88,62 @@ export class ChatSessionManager {
             fn(s);
     }
     close(sessionId) {
+        return this.closeSession(sessionId, true);
+    }
+    closeSession(sessionId, markClosed) {
+        const alreadyClosing = this.closingSessions.get(sessionId);
+        if (alreadyClosing)
+            return alreadyClosing;
         const s = this.sessions.get(sessionId);
-        if (!s)
-            return;
+        if (!s) {
+            if (markClosed)
+                this.rememberClosedSession(sessionId);
+            return Promise.resolve();
+        }
+        const sessionManager = this.engineSessionManager(s.engine);
+        const generation = this.sessionGeneration.get(sessionId) ?? 0;
+        const invalidated = sessionManager?.incrementSessionGeneration(sessionId) ?? generation + 1;
+        this.sessionGeneration.set(sessionId, invalidated);
         s.cancel();
         clearSessionPathApprovals(sessionId);
         clearInteractiveApprovalSession(sessionId);
         clearCredentialSessionAllow(sessionId);
         clearInjectCredentialSessionAllow(sessionId);
-        this.unregisterMcpOwner(s);
-        this.sessions.delete(sessionId);
+        const finishClose = () => {
+            this.unregisterMcpOwner(s);
+            if (this.sessions.get(sessionId) === s)
+                this.sessions.delete(sessionId);
+            if (markClosed)
+                this.rememberClosedSession(sessionId);
+            else
+                this.closedSessions.delete(sessionId);
+            this.sessionGeneration.delete(sessionId);
+        };
+        if (!s.isBusy()) {
+            finishClose();
+            return Promise.resolve();
+        }
+        const closing = (async () => {
+            try {
+                await s.settled;
+                finishClose();
+            }
+            finally {
+                this.closingSessions.delete(sessionId);
+            }
+        })();
+        this.closingSessions.set(sessionId, closing);
+        return closing;
+    }
+    rememberClosedSession(sessionId) {
+        this.closedSessions.delete(sessionId);
+        this.closedSessions.add(sessionId);
+        while (this.closedSessions.size > CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT) {
+            const oldest = this.closedSessions.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.closedSessions.delete(oldest);
+        }
     }
     closeAll() {
         // Fire-and-forget variant for callers that can't await (e.g. AgentServer
@@ -95,8 +159,7 @@ export class ChatSessionManager {
      * immediately afterward (the TUI REPL) doesn't orphan detached dev servers.
      */
     async closeAllAsync() {
-        for (const id of [...this.sessions.keys()])
-            this.close(id);
+        await Promise.all([...this.sessions.keys()].map((id) => this.close(id)));
         // App/worker shutdown — reap every background shell so a detached
         // `npm run dev` doesn't outlive the process as an orphan holding a port
         // (design §6 / §难点1). NOTE: deliberately NOT in close()/sweepIdle() —
@@ -120,7 +183,7 @@ export class ChatSessionManager {
                 continue;
             if (backgroundJobRegistry.hasRunningForSession(id))
                 continue;
-            this.close(id);
+            void this.closeSession(id, false);
         }
     }
     startIdleSweeper(intervalMs = 60_000) {
@@ -146,4 +209,13 @@ export class ChatSessionManager {
             });
         });
     }
+    engineSessionManager(engine) {
+        const candidate = engine;
+        const manager = candidate.getSessionManager?.();
+        if (typeof manager?.registerSessionGeneration !== "function" ||
+            typeof manager.incrementSessionGeneration !== "function") {
+            return undefined;
+        }
+        return manager;
+    }
 }

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

@@ -1,7 +1,9 @@
 import type { Engine, EngineResult } from "../engine/engine.js";
 import type { ModelEntry } from "../llm/model-pool.js";
 import type { StreamEvent } from "../types.js";
+import type { PermissionMode } from "../types.js";
 import type { InputAttachmentMeta } from "./types.js";
+import type { ApprovalRouter } from "../tool-system/permission.js";
 export interface ChatSessionOptions {
     id: string;
     engine: Engine;
@@ -23,6 +25,12 @@ export interface TurnOpts {
     clientMessageId?: string;
     /** Structured input attachments for this turn. */
     attachments?: InputAttachmentMeta[];
+    /** Permission mode snapshot for this queued turn only. */
+    permissionMode?: PermissionMode;
+    /** Plan-mode snapshot for this queued turn only. */
+    planMode?: boolean;
+    /** Connection owner router for permission prompts in this turn. */
+    approvalRouter?: ApprovalRouter;
 }
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
@@ -69,6 +77,8 @@ export declare class ChatSession {
      * (the user is engaging again) so normal wakeups resume working afterward.
      */
     private cancelledSinceLastTurn;
+    private settlePromise;
+    private resolveSettled;
     constructor(opts: ChatSessionOptions);
     enqueueTurn(task: string, opts: TurnOpts): Promise<EngineResult>;
     /**
@@ -88,6 +98,8 @@ export declare class ChatSession {
      */
     cancel(): void;
     isBusy(): boolean;
+    /** Resolves after the active engine.run() has completed its pump finally. */
+    get settled(): Promise<void>;
     /**
      * Extend the in-flight goal run's turn/budget ceilings (TODO 3.1). Delegates
      * to the engine, which forwards to the active TurnLoop. Returns null when no

package/dist/protocol/chat-session.js

@@ -44,6 +44,8 @@ export class ChatSession {
      * (the user is engaging again) so normal wakeups resume working afterward.
      */
     cancelledSinceLastTurn = false;
+    settlePromise = Promise.resolve();
+    resolveSettled = null;
     constructor(opts) {
         this.id = opts.id;
         this.engine = opts.engine;
@@ -94,6 +96,10 @@ export class ChatSession {
     isBusy() {
         return this.active !== null;
     }
+    /** Resolves after the active engine.run() has completed its pump finally. */
+    get settled() {
+        return this.settlePromise;
+    }
     /**
      * Extend the in-flight goal run's turn/budget ceilings (TODO 3.1). Delegates
      * to the engine, which forwards to the active TurnLoop. Returns null when no
@@ -158,6 +164,9 @@ export class ChatSession {
         if (!next)
             return;
         this.active = next;
+        this.settlePromise = new Promise((resolve) => {
+            this.resolveSettled = resolve;
+        });
         this.cancelledActive = false;
         this.controller = new AbortController();
         try {
@@ -171,6 +180,9 @@ export class ChatSession {
                 injected: next.opts.injected,
                 clientMessageId: next.opts.clientMessageId,
                 attachments: next.opts.attachments,
+                permissionMode: next.opts.permissionMode,
+                planMode: next.opts.planMode,
+                approvalRouter: next.opts.approvalRouter,
             });
             this.lastActivityAt = Date.now();
             next.resolve(result);
@@ -195,19 +207,32 @@ export class ChatSession {
             }
         }
         finally {
+            // close() must never be held hostage by run-boundary cleanup. Resolve
+            // before model switching or any other operation that may throw.
+            this.resolveSettled?.();
+            this.resolveSettled = null;
             this.active = null;
             this.controller = null;
             this.cancelledActive = false;
             // Run boundary: apply any model switch that was deferred because it was
             // requested mid-run. Done here (not in pump) so it still applies when
             // no further turn is queued.
-            if (this.pendingModel !== null) {
-                this.applyModelSwitch(this.pendingModel);
+            try {
+                if (this.pendingModel !== null) {
+                    this.applyModelSwitch(this.pendingModel);
+                }
+            }
+            catch {
+                // requestModelSwitch already returned when the switch was queued. A
+                // run-boundary persistence failure must not become an unhandled pump
+                // rejection or prevent the session from settling/continuing.
+            }
+            finally {
                 this.pendingModel = null;
+                // Drain the next turn even if deferred model switching failed.
+                if (this.queue.length > 0)
+                    void this.pump();
             }
-            // Drain the next turn if one is waiting.
-            if (this.queue.length > 0)
-                void this.pump();
         }
     }
 }

package/dist/protocol/client.d.ts

@@ -11,9 +11,9 @@
  *   const result = await client.run("fix the bug");
  */
 import type { Transport } from "./transport.js";
-import { type RunParams, type RunResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
+import { type RunParams, type RunResult, type ForkSessionParams, type ForkSessionResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
 import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent } from "../types.js";
-export type ApprovalRequestMeta = Pick<ApprovalRequestNotification, "sessionId">;
+export type ApprovalRequestMeta = Pick<ApprovalRequestNotification, "connectionId" | "sessionId" | "generation">;
 export type ApprovalResolvedEvent = ApprovalResolvedNotification;
 export interface AgentClientEvents {
     /** Multi-session envelope: carries sessionId + event. */
@@ -34,6 +34,8 @@ export declare class AgentClient {
     private transport;
     private emitter;
     private pendingRequests;
+    /** Routing tuple captured from approval notifications and echoed on approve. */
+    private approvalRoutes;
     /**
      * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
      * internal envelope-filtering wrapper actually registered on the
@@ -68,6 +70,7 @@ export declare class AgentClient {
      * Legacy form:        cancel(reason?)
      */
     cancel(sessionId?: string, reason?: string): Promise<void>;
+    forkSession(params: ForkSessionParams): Promise<ForkSessionResult>;
     /**
      * Clear a session's persisted active goal (CC `/goal clear`). Returns whether
      * a goal was actually cleared (false = there was none).

package/dist/protocol/client.js

@@ -17,6 +17,8 @@ export class AgentClient {
     transport;
     emitter = new EventEmitter();
     pendingRequests = new Map();
+    /** Routing tuple captured from approval notifications and echoed on approve. */
+    approvalRoutes = new Map();
     /**
      * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
      * internal envelope-filtering wrapper actually registered on the
@@ -78,16 +80,24 @@ export class AgentClient {
     approve(...args) {
         if (args.length === 3) {
             const [sessionId, requestId, decision] = args;
+            const route = this.approvalRoutes.get(requestId);
             return this.request(Methods.Approve, {
+                ...route,
                 sessionId,
                 requestId,
                 decision,
+            }).finally(() => {
+                this.approvalRoutes.delete(requestId);
             });
         }
         const [requestId, decision] = args;
+        const route = this.approvalRoutes.get(requestId);
         return this.request(Methods.Approve, {
+            ...route,
             requestId,
             decision,
+        }).finally(() => {
+            this.approvalRoutes.delete(requestId);
         });
     }
     /**
@@ -99,6 +109,9 @@ export class AgentClient {
     async cancel(sessionId, reason) {
         await this.request(Methods.Cancel, { sessionId, reason });
     }
+    async forkSession(params) {
+        return this.request(Methods.ForkSession, params);
+    }
     /**
      * Clear a session's persisted active goal (CC `/goal clear`). Returns whether
      * a goal was actually cleared (false = there was none).
@@ -286,7 +299,14 @@ export class AgentClient {
                 const request = params.request;
                 if (requestId && request) {
                     const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
-                    const meta = sessionId === undefined ? {} : { sessionId };
+                    const connectionId = typeof params.connectionId === "string" ? params.connectionId : undefined;
+                    const generation = typeof params.generation === "number" ? params.generation : undefined;
+                    const meta = {
+                        ...(connectionId === undefined ? {} : { connectionId }),
+                        ...(sessionId === undefined ? {} : { sessionId }),
+                        ...(generation === undefined ? {} : { generation }),
+                    };
+                    this.approvalRoutes.set(requestId, meta);
                     this.emitter.emit("approvalRequest", requestId, request, meta);
                 }
                 break;
@@ -294,6 +314,7 @@ export class AgentClient {
             case Methods.ApprovalResolved: {
                 const requestId = params.requestId;
                 if (requestId) {
+                    this.approvalRoutes.delete(requestId);
                     const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
                     const event = sessionId === undefined ? { requestId } : { sessionId, requestId };
                     this.emitter.emit("approvalResolved", event);

package/dist/protocol/server.d.ts

@@ -16,6 +16,7 @@
 import type { Transport } from "./transport.js";
 import type { Engine } from "../engine/engine.js";
 import type { ValidatedSettings } from "../settings/schema.js";
+import { type ApprovalRouter } from "../tool-system/permission.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
 export interface AgentServerOptions {
     /**
@@ -56,6 +57,11 @@ export interface AgentServerOptions {
      * service.
      */
     workspaceBridge?: boolean;
+    /** Stable transport connection identity. Supplying it enables strict
+     * connection+session+generation+requestId approval response matching. */
+    connectionId?: string;
+    /** Shared owner router; injectable for hosts/tests, process singleton by default. */
+    approvalRouter?: ApprovalRouter;
 }
 export declare class AgentServer {
     private readonly chatManager;
@@ -67,10 +73,17 @@ export declare class AgentServer {
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     private readonly readActiveGoalFromDisk;
     private readonly workspaceBridgeEnabled;
+    private readonly connectionId;
+    private readonly strictApprovalRouting;
+    private readonly approvalRouter;
+    private approvalConnectionUnregister;
+    private disconnected;
+    private readonly pendingApprovalTargets;
     /**
      * Last per-session EngineConfigSlice supplied by agent/run. Kept even after
      * idle eviction so background-completion wakeups can rebuild the ChatSession
-     * with the same cwd/permission/trust inputs before draining the queue.
+     * with the same cwd/trust inputs before draining the queue. Per-turn
+     * permission/plan overrides deliberately do not survive into wakeup turns.
      */
     private readonly lastSliceBySession;
     /** Lazy disk reader for cold wakeup rehydrate when this process lacks a slice. */
@@ -114,6 +127,7 @@ export declare class AgentServer {
      * itself outlives the server (it's a process-local singleton).
      */
     private bgAgentBusUnsubscribe;
+    private readonly wakeupsInFlight;
     constructor(options: AgentServerOptions);
     /**
      * Wake an IDLE chatManager session that has pending background-completion
@@ -133,23 +147,18 @@ export declare class AgentServer {
      *   the first drains all currently-pending items; subsequent bus events for
      *   the same session find it busy (or find an empty queue) and no-op.
      *
-     * INVARIANT (the burst-merge correctness depends on it): the merge only
-     * holds because (a) the bus fans out to subscribers SYNCHRONOUSLY, and (b)
-     * `enqueueTurn` sets the session's `active` (→ isBusy()===true) SYNCHRONOUSLY
-     * before its first await. So when bus events #2..N arrive — still on the same
-     * synchronous fan-out as #1 — they already see the session as busy and no-op.
-     * If either path is ever made async (e.g. an await is added inside
-     * enqueueTurn before `active` is set, or the bus starts deferring delivery),
-     * this degrades into N concurrent wakeups for N completions. Keep both
-     * synchronous, or replace this comment's assumption with an explicit
-     * "wakeup in flight" guard flag.
+     * `wakeupsInFlight` serializes the now-async rehydrate path, so a burst of
+     * completion events cannot create duplicate sessions or enqueue duplicate
+     * wakeup turns while getOrCreate waits for a closing generation to settle.
      */
     private maybeWakeIdleSession;
+    private wakeIdleSession;
     private rehydrateSessionForWake;
     private sliceForWakeRehydrate;
     private rememberSessionSlice;
     private wireInteractiveSession;
     private handleRequest;
+    private handleForkSession;
     private handleRun;
     private handleRunMulti;
     private handleRunLegacy;
@@ -207,6 +216,7 @@ export declare class AgentServer {
      * Ask the client to approve a tool operation (legacy single-engine path).
      */
     private requestApprovalFromClient;
+    private approvalRouteEnvelope;
     /**
      * Per-session AskUserQuestion for the chatManager path. Resolves via the
      * SESSION's pendingApprovals (the chatManager approve handler looks there,
@@ -249,6 +259,9 @@ export declare class AgentServer {
      */
     private anyEngine;
     close(): void;
+    /** Release only this transport's approval ownership. Safe on socket close
+     * even when the ChatSessionManager is shared by other TCP connections. */
+    disconnect(reason?: string): void;
     private clearApprovalTimer;
     /**
      * Resolve all of a chat session's pending approvals as cancelled and clear
@@ -258,5 +271,6 @@ export declare class AgentServer {
      * AskUserQuestion does not.
      */
     private cancelSessionApprovals;
+    private failClosedApprovalTargets;
     private clearAllApprovalTimers;
 }