@cjhyy/code-shell-core 0.7.0 → 0.8.0

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

@@ -1,4 +1,6 @@
+import { join } from "node:path";
 import { ChatSession } from "./chat-session.js";
+import { codeShellHome } from "../session/session-manager.js";
 import { backgroundShellManager } from "../runtime/background-shell.js";
 import { clearAgentOutputFiles } from "../tool-system/builtin/agent-output-file.js";
 import { backgroundJobRegistry } from "../tool-system/builtin/background-jobs.js";
@@ -7,35 +9,113 @@ 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";
+/** Identity scope every ChatSessionManager belongs to when none is injected. */
+export const LOCAL_CHAT_IDENTITY = "local";
+/**
+ * An identity becomes an on-disk path segment (`<root>/identities/<id>`), so
+ * it gets the same conservative validation as session ids: no separators, no
+ * parent-dir tokens, short, and a strict character allow-list.
+ */
+function assertSafeIdentity(identity) {
+    if (typeof identity !== "string" || identity.length === 0 || identity.length > 64) {
+        throw new Error(`invalid identity: must be a non-empty string of at most 64 chars`);
+    }
+    if (identity.includes("/") ||
+        identity.includes("\\") ||
+        identity === "." ||
+        identity.includes("..") ||
+        !/^[A-Za-z0-9_.-]+$/.test(identity)) {
+        throw new Error(`invalid identity: unexpected characters: ${identity}`);
+    }
+}
+export const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
 export class ChatSessionManager {
     sessions = new Map();
+    closingSessions = new Map();
+    closedSessions = new Set();
+    sessionGeneration = new Map();
     runtime;
+    /** Identity scope this manager serves ("local" unless injected). */
+    identity;
     factory;
     maxSessions;
     idleTtlMs;
+    projectionGeneration;
+    /** Construction options retained so forIdentity() can derive siblings. */
+    baseOptions;
     sweeper = null;
     constructor(opts) {
         this.runtime = opts.runtime;
+        this.identity = opts.identity ?? LOCAL_CHAT_IDENTITY;
+        if (opts.identity !== undefined)
+            assertSafeIdentity(opts.identity);
         this.factory = opts.engineFactory;
         this.maxSessions = opts.maxSessions ?? 16;
         this.idleTtlMs = opts.idleTtlMs ?? 30 * 60 * 1000;
+        this.projectionGeneration = opts.projectionGeneration ?? 1;
+        this.baseOptions = opts;
+    }
+    /**
+     * Derive a manager scoped to another identity. The derived manager shares
+     * this manager's runtime/limits but persists its sessions under
+     * `<dataRoot>/identities/<identity>/sessions` by injecting
+     * `sessionStorageDir` into every engineFactory slice (Task 1's SessionManager
+     * storageDir seam). Asking for this manager's own identity returns `this`
+     * unchanged, so the default single-identity ("local") path is byte-for-byte
+     * today's behavior. Callers (AgentServer) cache derived managers per
+     * identity; each call here builds a fresh instance.
+     */
+    forIdentity(identity) {
+        assertSafeIdentity(identity);
+        if (identity === this.identity)
+            return this;
+        const sessionStorageDir = join(this.baseOptions.dataRoot ?? codeShellHome(), "identities", identity, "sessions");
+        const baseFactory = this.baseOptions.engineFactory;
+        return new ChatSessionManager({
+            ...this.baseOptions,
+            identity,
+            engineFactory: (slice) => baseFactory({ ...slice, sessionStorageDir }),
+        });
+    }
+    async getOrCreate(sessionId, slice) {
+        const closing = this.closingSessions.get(sessionId);
+        if (closing) {
+            await closing;
+        }
+        return this.getOrCreateNow(sessionId, slice);
     }
-    getOrCreate(sessionId, slice) {
+    /**
+     * Cold-resume a persisted session using its own cwd. The first detached
+     * Engine is only a storage probe; all actual work runs on the second Engine
+     * built from the recovered project slice.
+     */
+    async getOrCreatePersisted(sessionId, slice = {}, restorePersistedModel = true) {
+        const existing = this.sessions.get(sessionId);
+        if (existing)
+            return existing;
+        const probe = this.factory(slice);
+        if (!probe.sessionExistsOnDisk(sessionId))
+            return null;
+        const cwd = probe.getSessionManager().readSessionMainRoot(sessionId);
+        if (!cwd)
+            return null;
+        const session = await this.getOrCreate(sessionId, {
+            ...slice,
+            cwd,
+            projectTrusted: slice.projectTrusted ?? false,
+        });
+        if (restorePersistedModel)
+            session.engine.restoreSessionModel(sessionId);
+        return session;
+    }
+    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 +126,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)
@@ -69,17 +164,80 @@ export class ChatSessionManager {
         for (const s of [...this.sessions.values()])
             fn(s);
     }
+    /** Snapshot-safe, read-only source shared by query("sessions") and Pet projection. */
+    getLiveSessionSnapshot() {
+        const sessions = [];
+        this.forEachSession((session) => {
+            sessions.push({
+                sessionId: session.id,
+                busy: session.isBusy(),
+                queueDepth: session.queueDepth(),
+                lastActivityAt: session.lastActivityAt,
+                kind: session.engine
+                    .getSessionManager?.()
+                    .readSessionKind?.(session.id) ?? "work",
+            });
+        });
+        sessions.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+        return { generation: this.projectionGeneration, identity: this.identity, sessions };
+    }
     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 +253,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 +277,7 @@ export class ChatSessionManager {
                 continue;
             if (backgroundJobRegistry.hasRunningForSession(id))
                 continue;
-            this.close(id);
+            void this.closeSession(id, false);
         }
     }
     startIdleSweeper(intervalMs = 60_000) {
@@ -142,8 +299,27 @@ export class ChatSessionManager {
         void mcpPool.unregisterOwner(session.engine).catch((err) => {
             logger.warn("chat_session.mcp_owner_unregister_failed", {
                 sessionId: session.id,
+                identity: this.identity,
                 error: err instanceof Error ? err.message : String(err),
             });
         });
     }
+    engineSessionManager(engine) {
+        const candidate = engine;
+        const manager = candidate.getSessionManager?.();
+        if (typeof manager?.registerSessionGeneration !== "function" ||
+            typeof manager.incrementSessionGeneration !== "function") {
+            return undefined;
+        }
+        return manager;
+    }
+}
+/**
+ * Factory counterpart of `new ChatSessionManager(opts)` for identity/dataRoot
+ * aware hosts (identity dimension foundations, Task 2). Identity defaults to
+ * "local" and dataRoot to `codeShellHome()`, so omitting both is exactly the
+ * constructor every existing host already calls.
+ */
+export function createChatSessionManager(opts) {
+    return new ChatSessionManager(opts);
 }

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

@@ -1,20 +1,32 @@
 import type { Engine, EngineResult } from "../engine/engine.js";
 import type { ModelEntry } from "../llm/model-pool.js";
 import type { StreamEvent } from "../types.js";
-import type { InputAttachmentMeta } from "./types.js";
+import type { PermissionMode, SessionKind } from "../types.js";
+import type { InputAttachmentMeta, PendingApprovalMetadata } from "./types.js";
+import type { ApprovalRouter } from "../tool-system/permission.js";
+import type { RunBehaviorMode } from "../engine/run-types.js";
+import type { SessionMessageTarget } from "../session/session-message.js";
+import type { LegacyPetWorkspaceOption } from "../types.js";
+import { type GoalConfig } from "../goal/lifecycle.js";
 export interface ChatSessionOptions {
     id: string;
     engine: Engine;
     onStream?: (event: StreamEvent) => void;
 }
+export interface PendingApprovalEntry {
+    resolve: (decision: unknown) => void;
+    metadata: PendingApprovalMetadata;
+}
 export interface TurnOpts {
     /** Working directory override for this turn. If omitted, Engine uses its
      *  configured cwd. */
     cwd?: string;
     onStream?: (event: StreamEvent) => void;
+    /** User-facing text persisted beside the full model-facing task. */
+    displayText?: string;
     /** Goal mode for this turn — forwarded to engine.run (loop-until-done).
      *  String objective or full GoalConfig (objective + optional budgets). */
-    goal?: string | import("../engine/goal.js").GoalConfig;
+    goal?: string | import("../goal/lifecycle.js").GoalConfig;
     /** 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. */
@@ -23,6 +35,26 @@ 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;
+    /** Named behavior profile snapshot for this queued turn only. */
+    behaviorMode?: RunBehaviorMode;
+    /** Generic per-run parameters consumed by the active behavior profile. */
+    profileParams?: Record<string, unknown>;
+    /** Digital human to bind durably to this Work Session. */
+    workspaceProfile?: string;
+    /** Closed same-project Session catalog available to SendMessageToSession. */
+    sessionMessageTargets?: readonly SessionMessageTarget[];
+    /** @deprecated Compat alias for `profileParams.runtimeContext`. */
+    petRuntimeContext?: string;
+    /** @deprecated Compat alias for `profileParams.workspaces`. */
+    petWorkspaces?: LegacyPetWorkspaceOption[];
+    /** Durable classification used only when the Engine creates the session. */
+    kind?: SessionKind;
+    /** Connection owner router for permission prompts in this turn. */
+    approvalRouter?: ApprovalRouter;
 }
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
@@ -33,16 +65,16 @@ export declare class ChatSession {
     readonly id: string;
     readonly engine: Engine;
     /**
-     * Per-session approval callbacks indexed by tool-call requestId.
+     * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
      * contents are mutated by `.set()` / `.delete()` as approvals come and go.
-     * Task 10 will register entries here when the Engine raises an approval
-     * request and clean them up on response.
+     * The resolver stays process-local; only metadata is eligible for Pet snapshots.
      */
-    readonly pendingApprovals: Map<string, (decision: unknown) => void>;
+    readonly pendingApprovals: Map<string, PendingApprovalEntry>;
     lastActivityAt: number;
     private queue;
     private active;
+    private exclusiveOperation;
     private controller;
     private readonly defaultOnStream?;
     /**
@@ -69,8 +101,17 @@ 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>;
+    /**
+     * Run session maintenance (for example context-package summarization) under
+     * the same per-session mutex as turns. Existing activity fails fast; turns
+     * arriving after the lock is acquired remain queued until maintenance has
+     * persisted its final usage/state update.
+     */
+    runExclusive<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T>;
     /**
      * True when the user hit Stop and hasn't started a new turn since. The server
      * consults this before auto-waking an idle session on a background-job
@@ -88,6 +129,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
@@ -106,16 +149,34 @@ export declare class ChatSession {
         maxStopBlocks: number;
     } | null;
     /**
-     * Read this session's persisted active goal (state.activeGoal), or undefined
+     * Read this session's persisted active goal (state.goalLifecycle), or undefined
      * when none. Cheap — reads only state.json. The host calls this on session
      * load to re-surface the goal block + Cancel button after a reload.
      */
-    getGoal(): import("../engine/goal.js").GoalConfig | undefined;
+    getGoal(): import("../goal/lifecycle.js").GoalConfig | undefined;
     /**
      * Clear this session's persisted active goal (CC /goal clear). Works idle or
      * mid-run. Returns true if a goal was actually cleared.
      */
-    clearGoal(): boolean;
+    clearGoal(expected?: {
+        goalId?: string;
+        revision?: number;
+    }): boolean;
+    /** Edit or pause/resume this session's persistent goal. */
+    updateGoal(patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId?: string;
+        expectedRevision?: number;
+    }): import("../goal/lifecycle.js").GoalConfig | undefined;
+    /** Whether a paused Goal can reuse this run's already Goal-capable prompt/tools. */
+    canResumeGoalInPlace(): boolean;
+    /**
+     * Queue the synthetic turn which actually drives an idle/dormant Goal after
+     * Resume. The version guard is checked at queue head, so a later edit/delete
+     * cannot leave a stale "resume" turn behind another user turn.
+     */
+    enqueueGoalResumeTurn(goal: GoalConfig, opts?: Omit<TurnOpts, "goal">): Promise<boolean>;
     /**
      * Switch this session's active model (per-session, not worker-global).
      * Applies immediately when idle; defers to the next run boundary when a
@@ -132,6 +193,8 @@ export declare class ChatSession {
      * path and the deferred run-boundary path.
      */
     private applyModelSwitch;
+    /** Apply and clear a deferred switch before another run may start. */
+    private applyPendingModelSwitchAtRunBoundary;
     queueDepth(): number;
     private pump;
 }