@cjhyy/code-shell-core 0.8.13 → 0.9.0

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

@@ -34,6 +34,9 @@ export class ChatSessionManager {
     closingSessions = new Map();
     closedSessions = new Set();
     sessionGeneration = new Map();
+    sessionSlices = new Map();
+    migrationClaims = new Map();
+    residentMigrations = new Map();
     runtime;
     /** Identity scope this manager serves ("local" unless injected). */
     identity;
@@ -78,11 +81,133 @@ export class ChatSessionManager {
         });
     }
     async getOrCreate(sessionId, slice) {
-        const closing = this.closingSessions.get(sessionId);
-        if (closing) {
-            await closing;
+        // 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 (;;) {
+            const residentMigration = this.residentMigrations.get(sessionId);
+            if (residentMigration) {
+                await residentMigration.released;
+                continue;
+            }
+            const claim = this.migrationClaims.get(sessionId);
+            if (claim) {
+                await claim.released;
+                continue;
+            }
+            const closing = this.closingSessions.get(sessionId);
+            if (closing) {
+                await closing;
+                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.
+            return this.getOrCreateNow(sessionId, slice);
+        }
+    }
+    /**
+     * 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.
+     */
+    beginSessionMigration(sessionId, ownershipToken) {
+        if (this.residentMigrations.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} migration is already in progress` };
+        }
+        const resident = this.sessions.get(sessionId);
+        if (resident)
+            return { status: "resident", session: resident };
+        if (this.closingSessions.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} is closing` };
+        }
+        if (this.migrationClaims.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} migration is already in progress` };
+        }
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.migrationClaims.set(sessionId, { ownershipToken, released, release });
+        return { status: "not-resident", ownershipToken };
+    }
+    /** Release only the exact claim minted for this Session. */
+    completeSessionMigration(sessionId, ownershipToken) {
+        const claim = this.migrationClaims.get(sessionId);
+        if (!claim || claim.ownershipToken !== ownershipToken)
+            return false;
+        this.migrationClaims.delete(sessionId);
+        claim.release();
+        return true;
+    }
+    /**
+     * Rebuild an idle resident Engine against a new authoritative main root.
+     *
+     * Transaction order is intentional:
+     * 1. construct and restore the candidate while durable state still points at
+     *    the old owner (factory/restore failure is therefore a no-op),
+     * 2. atomically commit durable state through the old owning Engine,
+     * 3. synchronously swap the Engine inside the existing ChatSession,
+     * 4. dispose the unreachable old Engine before reporting success.
+     *
+     * No await occurs between the idle check, durable commit and owner swap.
+     */
+    async migrateResidentSessionMainRoot(sessionId, target) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session ${sessionId} is not resident`);
+        if (session.isBusy() || session.queueDepth() > 0) {
+            throw new Error(`Session ${sessionId} is running or has queued turns`);
+        }
+        if (this.residentMigrations.has(sessionId) || this.migrationClaims.has(sessionId)) {
+            throw new Error(`Session ${sessionId} migration is already in progress`);
+        }
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.residentMigrations.set(sessionId, { released, release });
+        const previous = session.engine;
+        let candidate;
+        let committed = false;
+        try {
+            const previousSlice = this.sessionSlices.get(sessionId) ?? {};
+            const permissionMode = previous.getPermissionMode?.() ?? previousSlice.permissionMode;
+            const nextSlice = {
+                ...previousSlice,
+                cwd: target.mainRoot,
+                workspaceContext: target.workspaceContext,
+                projectTrusted: target.projectTrusted,
+                ...(permissionMode ? { permissionMode } : {}),
+            };
+            const built = this.factory(nextSlice);
+            if (built === previous) {
+                throw new Error(`Session ${sessionId} Engine factory reused the resident owner`);
+            }
+            candidate = built;
+            if (permissionMode && candidate.getPermissionMode?.() !== permissionMode) {
+                candidate.setPermissionMode?.(permissionMode);
+            }
+            const candidateGeneration = this.engineSessionManager(candidate)?.registerSessionGeneration(sessionId) ??
+                this.sessionGeneration.get(sessionId) ??
+                1;
+            candidate.restoreSessionModel?.(sessionId);
+            const workspace = previous.migrateSessionMainRoot(sessionId, target.project, target.mainRoot);
+            session.replaceEngine(previous, candidate);
+            this.sessionGeneration.set(sessionId, candidateGeneration);
+            this.sessionSlices.set(sessionId, nextSlice);
+            committed = true;
+            await this.disposeEngine(previous, sessionId);
+            return workspace;
+        }
+        catch (error) {
+            if (!committed && candidate)
+                await this.disposeEngine(candidate, sessionId);
+            throw error;
+        }
+        finally {
+            this.residentMigrations.delete(sessionId);
+            release();
         }
-        return this.getOrCreateNow(sessionId, slice);
     }
     /**
      * Cold-resume a persisted session using its own cwd. The first detached
@@ -129,6 +254,7 @@ export class ChatSessionManager {
         const sessionManager = this.engineSessionManager(engine);
         const generation = sessionManager?.registerSessionGeneration(sessionId) ?? 1;
         this.sessionGeneration.set(sessionId, generation);
+        this.sessionSlices.set(sessionId, { ...slice });
         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.
@@ -201,6 +327,10 @@ 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;
@@ -237,6 +367,7 @@ export class ChatSessionManager {
             else
                 this.closedSessions.delete(sessionId);
             this.sessionGeneration.delete(sessionId);
+            this.sessionSlices.delete(sessionId);
         };
         if (!s.isBusy()) {
             finishClose();
@@ -278,6 +409,9 @@ export class ChatSessionManager {
      * immediately afterward (the TUI REPL) doesn't orphan detached dev servers.
      */
     async closeAllAsync() {
+        for (const [sessionId, claim] of [...this.migrationClaims]) {
+            this.completeSessionMigration(sessionId, claim.ownershipToken);
+        }
         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
@@ -335,6 +469,35 @@ export class ChatSessionManager {
             });
         });
     }
+    async disposeEngine(engine, sessionId) {
+        const dispose = engine.dispose;
+        if (typeof dispose === "function") {
+            try {
+                await dispose.call(engine);
+            }
+            catch (error) {
+                logger.warn("chat_session.engine_dispose_failed", {
+                    sessionId,
+                    identity: this.identity,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return;
+        }
+        const mcpPool = this.runtime.mcpPool;
+        if (typeof mcpPool?.unregisterOwner !== "function")
+            return;
+        try {
+            await mcpPool.unregisterOwner(engine);
+        }
+        catch (error) {
+            logger.warn("chat_session.mcp_owner_unregister_failed", {
+                sessionId,
+                identity: this.identity,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     engineSessionManager(engine) {
         const candidate = engine;
         const manager = candidate.getSessionManager?.();

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

@@ -21,6 +21,7 @@ export interface TurnOpts {
     /** Working directory override for this turn. If omitted, Engine uses its
      *  configured cwd. */
     cwd?: string;
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     onStream?: (event: StreamEvent) => void;
     /** User-facing text persisted beside the full model-facing task. */
     displayText?: string;
@@ -37,6 +38,8 @@ export interface TurnOpts {
     archiveBeforeCurrentTurn?: {
         fromClientMessageId?: string;
         segmentId?: string;
+        /** Host-authored replacement for the archived span; skips the summarizer. */
+        summary?: string;
     };
     /** Structured input attachments for this turn. */
     attachments?: InputAttachmentMeta[];
@@ -68,7 +71,7 @@ export interface TurnOpts {
  */
 export declare class ChatSession {
     readonly id: string;
-    readonly engine: Engine;
+    private currentEngine;
     /**
      * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
@@ -109,6 +112,13 @@ export declare class ChatSession {
     private settlePromise;
     private resolveSettled;
     constructor(opts: ChatSessionOptions);
+    get engine(): Engine;
+    /**
+     * Swap the Engine at an idle run boundary without replacing the ChatSession
+     * that owns the queue, stream callback, approvals, idle timestamp and id.
+     * The expected-owner check makes a stale migration fail closed.
+     */
+    replaceEngine(expected: Engine, replacement: Engine): void;
     enqueueTurn(task: string, opts: TurnOpts): Promise<EngineResult>;
     /**
      * Run session maintenance (for example context-package summarization) under

package/dist/protocol/chat-session.js

@@ -7,7 +7,7 @@ import { isSameGoalInstance } from "../goal/lifecycle.js";
  */
 export class ChatSession {
     id;
-    engine;
+    currentEngine;
     /**
      * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
@@ -49,9 +49,26 @@ export class ChatSession {
     resolveSettled = null;
     constructor(opts) {
         this.id = opts.id;
-        this.engine = opts.engine;
+        this.currentEngine = opts.engine;
         this.defaultOnStream = opts.onStream;
     }
+    get engine() {
+        return this.currentEngine;
+    }
+    /**
+     * Swap the Engine at an idle run boundary without replacing the ChatSession
+     * that owns the queue, stream callback, approvals, idle timestamp and id.
+     * The expected-owner check makes a stale migration fail closed.
+     */
+    replaceEngine(expected, replacement) {
+        if (this.active || this.exclusiveOperation || this.queue.length > 0) {
+            throw new Error(`Session ${this.id} is running or has queued turns`);
+        }
+        if (this.currentEngine !== expected) {
+            throw new Error(`Session ${this.id} Engine ownership changed during migration`);
+        }
+        this.currentEngine = replacement;
+    }
     enqueueTurn(task, opts) {
         this.lastActivityAt = Date.now();
         // The user (or a wakeup the guard already let through) is starting a turn —
@@ -283,6 +300,7 @@ export class ChatSession {
             const onStream = next.opts.onStream ?? this.defaultOnStream;
             const result = await this.engine.run(next.task, {
                 cwd: next.opts.cwd,
+                workspaceContext: next.opts.workspaceContext,
                 sessionId: this.id,
                 displayText: next.opts.displayText,
                 signal: this.controller.signal,

package/dist/protocol/mobile-remote-types.d.ts

@@ -66,10 +66,18 @@ export interface MobilePermissionModeSnapshotEntry {
     mode: PermissionMode;
 }
 export interface MobileProjectMeta {
+    id?: string;
     path: string;
     name: string;
     addedAt?: number;
     pinned?: boolean;
+    roots?: Array<{
+        id: string;
+        path: string;
+        name: string;
+        role: "primary" | "secondary";
+    }>;
+    primaryRootId?: string;
 }
 export type MobileImageMime = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
 export interface MobileImageBase {
@@ -112,6 +120,11 @@ export type MobileClientEvent = {
     sessionId: string;
 } | {
     type: "session.create";
+    /** Stable V2 project identity. null explicitly selects the no-repo workspace. */
+    projectId?: string | null;
+    /** Stable V2 root identity. Omit to use the project's current primary root. */
+    rootId?: string;
+    /** Legacy client compatibility only; Main validates it against mounted roots. */
     cwd?: string | null;
     name?: string;
 } | {
@@ -230,6 +243,8 @@ export type MobileServerEvent = {
     type: "chat.accepted";
     sessionId?: string;
     cwd?: string | null;
+    projectId?: string | null;
+    rootId?: string;
     clientMessageId?: string;
     attachments?: MobileAttachmentSummary[];
 } | {

package/dist/protocol/server.d.ts

@@ -198,6 +198,7 @@ export declare class AgentServer {
      */
     private bgAgentBusUnsubscribe;
     private readonly wakeupsInFlight;
+    private readonly sessionWorkspaceRpc;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —
@@ -310,8 +311,6 @@ export declare class AgentServer {
      */
     private handleBackgroundWork;
     private handleCloseSession;
-    private handleReleaseWorkspace;
-    private handleSetWorkspace;
     private handleConfigure;
     /**
      * Resolve the Engine that owns a session-scoped query (compact, archive_range,

package/dist/protocol/server.js

@@ -30,6 +30,7 @@ import { redactSecrets } from "../logging/sanitize-messages.js";
 import { compileComposition } from "../composition/compiler.js";
 import { attachProtocolContributions } from "../composition/protocol-attach.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
+import { SessionWorkspaceRpcHandlers } from "./session-workspace-rpc.js";
 import { describePluginCommands, expandPluginCommandBody, scanPluginCommands, MAX_PLUGIN_COMMAND_ARGUMENT_CHARS, } from "../plugins/pluginCommandsLoader.js";
 function isValidRunAttachment(value) {
     if (!value || typeof value !== "object")
@@ -85,6 +86,13 @@ function runInputError(params) {
                 return `archiveBeforeCurrentTurn.${field} must be a bounded non-empty string`;
             }
         }
+        if (archive.summary !== undefined &&
+            (typeof archive.summary !== "string" ||
+                archive.summary.trim().length === 0 ||
+                archive.summary.length > 4_000 ||
+                /[\u0000]/u.test(archive.summary))) {
+            return "archiveBeforeCurrentTurn.summary must be a non-empty string up to 4000 characters";
+        }
     }
     if (params.behaviorMode !== undefined &&
         (typeof params.behaviorMode !== "string" || params.behaviorMode.length === 0)) {
@@ -373,6 +381,7 @@ export class AgentServer {
      */
     bgAgentBusUnsubscribe = null;
     wakeupsInFlight = new Set();
+    sessionWorkspaceRpc;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —
@@ -418,6 +427,14 @@ export class AgentServer {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
         this.transport = options.transport;
+        this.sessionWorkspaceRpc = new SessionWorkspaceRpcHandlers({
+            transport: this.transport,
+            getChatManager: () => this.chatManager,
+            getLegacyEngine: () => this.legacyEngine,
+            getLastSlice: (sessionId) => this.lastSliceBySession.get(sessionId),
+            rememberSessionSlice: (sessionId, slice) => this.rememberSessionSlice(sessionId, slice),
+            wireInteractiveSession: (session, sessionId) => this.wireInteractiveSession(session, sessionId),
+        });
         // Protocol surface from the compiled composition. Each contributing
         // module may attach one observer; the server calls them at every
         // lifecycle hook point and isolates per-observer failures.
@@ -780,10 +797,16 @@ export class AgentServer {
                 await this.handleCloseSession(req);
                 break;
             case Methods.ReleaseWorkspace:
-                this.handleReleaseWorkspace(req);
+                this.sessionWorkspaceRpc.release(req);
                 break;
             case Methods.SetWorkspace:
-                this.handleSetWorkspace(req);
+                this.sessionWorkspaceRpc.set(req);
+                break;
+            case Methods.MigrateSessionMainRoot:
+                await this.sessionWorkspaceRpc.migrateMainRoot(req);
+                break;
+            case Methods.CompleteSessionMainRootMigration:
+                this.sessionWorkspaceRpc.completeMainRootMigration(req);
                 break;
             case Methods.GoalExtend:
                 this.handleGoalExtend(req);
@@ -1146,6 +1169,7 @@ export class AgentServer {
         }
         const sessionConfig = {
             cwd: params.cwd,
+            workspaceContext: params.workspaceContext,
             projectTrusted: params.projectTrusted,
             preset: params.preset ??
                 (params.behaviorMode === ISOLATED_TASK_BEHAVIOR_MODE ? "general" : undefined),
@@ -1219,6 +1243,7 @@ export class AgentServer {
             }
             const run = session.enqueueTurn(params.task, {
                 cwd: params.cwd,
+                workspaceContext: params.workspaceContext,
                 displayText: displayText || undefined,
                 injected: params.injected === true,
                 attachments: Array.isArray(params.attachments) ? params.attachments : undefined,
@@ -1351,6 +1376,7 @@ export class AgentServer {
             });
             const result = await this.legacyEngine.run(params.task, {
                 cwd: params.cwd,
+                workspaceContext: params.workspaceContext,
                 sessionId: params.sessionId,
                 displayText: displayText || undefined,
                 injected: params.injected === true,
@@ -1937,55 +1963,6 @@ export class AgentServer {
         backgroundJobRegistry.dropForSession(params.sessionId);
         this.transport.send(createResponse(req.id, { ok: true }));
     }
-    // ─── ReleaseWorkspace ──────────────────────────────────────────
-    handleReleaseWorkspace(req) {
-        const params = (req.params ?? {});
-        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
-            return;
-        }
-        if (this.chatManager) {
-            const session = this.chatManager.get(params.sessionId);
-            if (!session) {
-                this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
-                return;
-            }
-            const engine = session.engine;
-            const workspace = engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
-            this.transport.send(createResponse(req.id, { ok: true, workspace }));
-            return;
-        }
-        const engine = this.legacyEngine;
-        const workspace = engine?.releaseSessionWorkspace?.(params.sessionId) ?? null;
-        this.transport.send(createResponse(req.id, { ok: true, workspace }));
-    }
-    handleSetWorkspace(req) {
-        const params = (req.params ?? {});
-        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
-            return;
-        }
-        if (!params.workspace ||
-            typeof params.workspace !== "object" ||
-            typeof params.workspace.root !== "string" ||
-            params.workspace.root.length === 0 ||
-            (params.workspace.kind !== "main" && params.workspace.kind !== "worktree")) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid workspace is required"));
-            return;
-        }
-        const engine = this.chatManager
-            ? this.chatManager.get(params.sessionId)?.engine
-            : this.legacyEngine;
-        if (!engine) {
-            this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
-            return;
-        }
-        const workspace = engine.setSessionWorkspace?.(params.sessionId, params.workspace);
-        this.transport.send(createResponse(req.id, {
-            ok: workspace !== undefined && workspace !== null,
-            workspace: workspace ?? null,
-        }));
-    }
     // ─── Configure ──────────────────────────────────────────────────
     handleConfigure(req) {
         const params = (req.params ?? {});

package/dist/protocol/session-workspace-rpc.d.ts

@@ -0,0 +1,23 @@
+import type { Engine } from "../engine/engine.js";
+import type { ChatSession } from "./chat-session.js";
+import type { ChatSessionManager, EngineConfigSlice } from "./chat-session-manager.js";
+import type { Transport } from "./transport.js";
+import { type RpcRequest } from "./types.js";
+interface SessionWorkspaceRpcDependencies {
+    transport: Transport;
+    getChatManager(): ChatSessionManager | null;
+    getLegacyEngine(): Engine | null;
+    getLastSlice(sessionId: string): EngineConfigSlice | undefined;
+    rememberSessionSlice(sessionId: string, slice: EngineConfigSlice): void;
+    wireInteractiveSession(session: ChatSession, sessionId: string): void;
+}
+/** Protocol boundary for Session workspace ownership and root migration. */
+export declare class SessionWorkspaceRpcHandlers {
+    private readonly deps;
+    constructor(deps: SessionWorkspaceRpcDependencies);
+    release(req: RpcRequest): void;
+    set(req: RpcRequest): void;
+    migrateMainRoot(req: RpcRequest): Promise<void>;
+    completeMainRootMigration(req: RpcRequest): void;
+}
+export {};