@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/session/memory.js

@@ -27,6 +27,7 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, rename
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { acquireFileLock, writeFileAtomic } from "../utils/file-mutex.js";
 function frontmatterLine(key, value) {
     return `${key}: ${JSON.stringify(value)}\n`;
 }
@@ -178,8 +179,9 @@ export class MemoryManager {
         // save by paying one loadAll() — every save after that just
         // mutates the cache and rewrites MEMORY.md.
         const cache = this.ensureIndexCache();
-        cache.set(fileName, { name: entry.name, description: entry.description });
-        this.writeIndex(cache);
+        const meta = { name: entry.name, description: entry.description };
+        cache.set(fileName, meta);
+        this.writeIndex(cache, { kind: "save", fileName, meta });
         return fileName;
     }
     /**
@@ -386,7 +388,7 @@ export class MemoryManager {
             renameSync(join(this.memoryDir, entry.fileName), join(trashDir, entry.fileName));
             const cache = this.ensureIndexCache();
             cache.delete(entry.fileName);
-            this.writeIndex(cache);
+            this.writeIndex(cache, { kind: "delete", fileName: entry.fileName });
             return true;
         }
         catch {
@@ -627,47 +629,64 @@ export class MemoryManager {
             `\n\nTo read a specific memory, look under ${this.memoryRoot}/{user,dream}/`);
     }
     /**
-     * Two-layer injection index (用户拍板). Merges GLOBAL (cross-project
-     * experience) + PROJECT (this repo's facts) memories into a compact index —
-     * one line per entry, name + description only, NO body. The model reads a
-     * specific entry's full content on demand via MemoryRead (which records a
-     * recall → drives TTL + UI visibility).
+     * Three-layer injection index (用户拍板). Merges GLOBAL (cross-project
+     * experience) + DIGITAL-HUMAN (portable profile experience) + PROJECT
+     * (this repo's facts) memories into a compact index — one line per entry,
+     * name + description only, NO body.
      *
      * This is what fixes "global memory never shows up": global memories are now
      * injected alongside project ones, every session, regardless of cwd.
      *
-     * Static because it must construct two managers (global = no projectDir,
-     * project = with projectDir). `projectDir` undefined → only global is shown.
+     * Static because it must construct the managers for each configured layer.
+     * `projectDir` undefined → no project layer; `profileDir` undefined → no
+     * digital-human layer.
      */
     static buildInjectionIndex(opts) {
         const global = new MemoryManager({ baseDir: opts.baseDir });
         const project = opts.projectDir
             ? new MemoryManager({ baseDir: opts.baseDir, projectDir: opts.projectDir })
             : null;
+        // 数字人层：baseDir 直接指向 profiles/<name>（其 memory/ 子目录随
+        // MemoryManager 的常规布局落盘）。跟着 Profile 走、跨 workspace 复用。
+        const profile = opts.profileDir ? new MemoryManager({ baseDir: opts.profileDir }) : null;
         const pinnedFirst = (a, b) => Number(b.pinned ?? false) - Number(a.pinned ?? false);
         const collect = (mm) => filterByAge([...mm.loadScope("user"), ...mm.loadScope("dream")], opts.maxAgeDays, opts.now).sort(pinnedFirst);
         const globalEntries = collect(global);
+        const profileEntries = profile ? collect(profile) : [];
         const projectEntries = project ? collect(project) : [];
-        if (globalEntries.length === 0 && projectEntries.length === 0)
+        if (globalEntries.length === 0 && profileEntries.length === 0 && projectEntries.length === 0) {
             return "";
-        const fmt = (e) => `- ${e.pinned ? "[pinned] " : ""}[${e.type}] ${e.name}: ${e.description}`;
+        }
+        const fmt = (e, location) => `- ${e.pinned ? "[pinned] " : ""}[scope="${e.scope}" location="${location}" type="${e.type}"] ${e.name}: ${e.description}`;
+        const readableLocations = profile ? "global, profile, or project" : "global or project";
         const lines = [];
         if (globalEntries.length > 0) {
             lines.push("## Global memories (apply across all projects)");
             for (const e of globalEntries)
-                lines.push(fmt(e));
+                lines.push(fmt(e, "global"));
+        }
+        if (profileEntries.length > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push("## Digital-human memories (travel with the active profile)");
+            for (const e of profileEntries)
+                lines.push(fmt(e, "profile"));
         }
         if (projectEntries.length > 0) {
             if (lines.length > 0)
                 lines.push("");
             lines.push("## Project memories (this repo)");
             for (const e of projectEntries)
-                lines.push(fmt(e));
+                lines.push(fmt(e, "project"));
         }
         return (`# Persistent Memory (index)\n\n` +
             `These are summaries of memories from previous sessions. Only the summary is shown here.\n` +
             `When a memory looks relevant to the current task, read its full content with the ` +
-            `MemoryRead tool (scope = user or dream; location = global or project) before relying on it.\n\n` +
+            `MemoryRead tool before relying on it. Every entry includes its exact scope and location; ` +
+            `copy both values exactly and never infer them from the memory name or type. ` +
+            `Readable locations for this run: ${readableLocations}.\n` +
+            `If MemoryRead reports that an entry is missing, do not repeat the same call. ` +
+            `Use MemoryList once to refresh that exact store, or continue without the memory.\n\n` +
             lines.join("\n"));
     }
     /**
@@ -750,13 +769,52 @@ export class MemoryManager {
         this.indexCache = cache;
         return cache;
     }
-    writeIndex(cache) {
-        const lines = [];
-        for (const [fileName, meta] of cache) {
-            lines.push(`- [${meta.name}](${fileName}) — ${meta.description}`);
+    /**
+     * Rewrite MEMORY.md from the CURRENT set of memory files on disk, under a
+     * cross-process lock.
+     *
+     * The in-memory `indexCache` is a per-instance optimisation, and several
+     * managers exist for the same directory (desktop main, agent worker, TUI, a
+     * second desktop instance). Writing the cache out verbatim meant a stale
+     * snapshot clobbered whatever another writer had added:
+     *
+     *   A saves a → B loads {a}, saves b → A still holds {a}, saves c
+     *   → files a, b, c all exist, but MEMORY.md lists only a and c.
+     *
+     * The individual `<name>.md` files are the source of truth; MEMORY.md is a
+     * derived index. So rather than trusting any cache, re-derive it from disk
+     * inside the lock. `pending` carries this writer's own change, which may not
+     * be visible on disk yet (a delete moves the file to trash first, a save
+     * writes it first) — it is applied on top of the freshly scanned set.
+     */
+    writeIndex(cache, pending) {
+        const release = acquireFileLock(this.indexPath);
+        try {
+            // Re-scan under the lock: picks up entries written by other processes
+            // since this instance's cache was built.
+            const merged = new Map();
+            for (const entry of this.loadAll()) {
+                merged.set(entry.fileName, { name: entry.name, description: entry.description });
+            }
+            if (pending?.kind === "save")
+                merged.set(pending.fileName, pending.meta);
+            if (pending?.kind === "delete")
+                merged.delete(pending.fileName);
+            // Keep this instance's cache consistent with what we are about to write,
+            // so the next incremental update starts from the merged truth.
+            cache.clear();
+            for (const [fileName, meta] of merged)
+                cache.set(fileName, meta);
+            const lines = [];
+            for (const [fileName, meta] of merged) {
+                lines.push(`- [${meta.name}](${fileName}) — ${meta.description}`);
+            }
+            const content = lines.length > 0 ? lines.join("\n") + "\n" : "(no memories stored)\n";
+            writeFileAtomic(this.indexPath, content);
+        }
+        finally {
+            release();
         }
-        const content = lines.length > 0 ? lines.join("\n") + "\n" : "(no memories stored)\n";
-        writeFileSync(this.indexPath, content, "utf-8");
     }
     generateId() {
         return `mem_${randomUUID().replace(/-/g, "")}`;

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

@@ -1,12 +1,39 @@
 /**
  * Session lifecycle manager.
  */
-import type { SessionState, SessionWorkspace } from "../types.js";
+import type { SessionForkLineage, SessionState, SessionKind, SessionWorkspace, TokenUsage, TranscriptEvent } from "../types.js";
 import { Transcript } from "./transcript.js";
+import { type GoalConfig, type PersistedGoalTerminationReason } from "../goal/lifecycle.js";
+import { type SessionWorkspaceCapability } from "../capabilities/index.js";
+/** Non-Goal fields accepted by the generic latest-state merge path. */
+export type SessionStateFieldPatch = Readonly<Partial<Omit<SessionState, "sessionId" | "goalLifecycle" | "activeGoal" | "goalTerminal" | "goalTerminals">>>;
+export type GoalTerminalSaveOutcome = "persisted" | "obsolete" | "failed";
 export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+export interface ForkSessionOptions {
+    targetSessionId?: string;
+    /** Inclusive source event cursor; omitted means the frozen transcript tail. */
+    throughEventId?: string;
+    /** `completed` is the interrupted snapshot used by ephemeral side chats. */
+    snapshotMode?: "tail" | "completed";
+    /** Hide this temporary fork from ordinary session lists and resume pickers. */
+    ephemeral?: boolean;
+}
+export interface ForkSessionResult {
+    bundle: SessionBundle;
+    lineage: SessionForkLineage;
+    copiedEventCount: number;
+}
+export interface SummaryForkOptions {
+    targetSessionId?: string;
+    fromEventId: string;
+    toEventId: string;
+    summary: string;
+    sourceEventCount: number;
+    estimatedTokens: number;
+}
 export type SessionWorkspaceResumeResolution = {
     ok: true;
     cwd: string;
@@ -18,7 +45,7 @@ export type SessionWorkspaceResumeResolution = {
     cwd: string;
     workspace: SessionWorkspace;
     message: string;
-    reason: "worktree_missing_branch_exists";
+    reason: "worktree_missing_branch_exists" | "workspace_capability_unavailable";
 };
 /**
  * Validate a session ID before it is joined into a filesystem path.
@@ -34,6 +61,13 @@ export type SessionWorkspaceResumeResolution = {
  * Exported for direct unit testing.
  */
 export declare function assertSafeSessionId(sessionId: unknown): asserts sessionId is string;
+/**
+ * Runtime source of truth for sessions whose state must not outlive their UI
+ * lifecycle. The explicit marker covers modern side forks; the qchat namespace
+ * keeps historical/blank quick chats fail-closed if their older state file did
+ * not contain the marker yet.
+ */
+export declare function isEphemeralSessionState(state: Pick<SessionState, "sessionId" | "ephemeral">): boolean;
 /**
  * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
  * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
@@ -42,9 +76,29 @@ export declare function assertSafeSessionId(sessionId: unknown): asserts session
  * with throwaway test sessions (the rm-usage/test-model sidebar junk).
  */
 export declare function codeShellHome(): string;
+/**
+ * Canonical root for every persisted CodeShell session. An explicit `home`
+ * (a `~/.code-shell`-equivalent data root) overrides the default resolution;
+ * absent → `codeShellHome()` exactly as before.
+ */
+export declare function sessionsRoot(home?: string): string;
+/**
+ * Read the session's persisted main-project root from the legacy `state.cwd`
+ * field. The field name is part of the state.json compatibility contract and
+ * must not be rewritten to `projectRoot`; `state.workspace.root` separately
+ * identifies the current main/worktree execution root used on resume.
+ */
+export declare function sessionMainRoot(state: Pick<SessionState, "cwd">): string | undefined;
 export declare class SessionManager {
     private readonly sessionsDir;
-    constructor(storageDir?: string);
+    private readonly registeredCloseEpochs;
+    private readonly workspaceCapability?;
+    constructor(storageDir?: string, workspaceCapability?: SessionWorkspaceCapability);
+    private cleanupStaleForkStaging;
+    /** Bind one Engine/session pair to the current close epoch without advancing it. */
+    registerSessionGeneration(sessionId: string): number;
+    /** Advance the close epoch once before close waits for the old run to settle. */
+    incrementSessionGeneration(sessionId: string): number;
     /**
      * Create a new on-disk session. If `explicitSessionId` is passed, use
      * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
@@ -52,7 +106,7 @@ export declare class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin): SessionBundle;
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin, kind?: SessionKind): SessionBundle;
     /**
      * Whether a session directory exists on disk. Used by ChatSession-driven
      * cold starts to decide between resume vs create-with-explicit-sid
@@ -60,16 +114,36 @@ export declare class SessionManager {
      */
     exists(sessionId: string): boolean;
     /**
-     * Cheap "what cwd is this session bound to?" probe — reads only state.json,
-     * NOT the transcript (unlike resume()). engine.run uses this to recover a
-     * resumed session's project directory when the caller omits options.cwd
-     * (e.g. a desktop host whose sidebar repo selection has drifted to null),
-     * so a project-bound session keeps loading its own agents/settings/memory
-     * instead of falling back to process.cwd(). Returns undefined for an
-     * unknown, malformed, or traversal-shaped id rather than throwing — the
-     * caller treats "no recoverable cwd" the same as "not given".
+     * Cheap persisted-main-root probe — reads only state.json, NOT the transcript
+     * (unlike resume()). This deliberately reads legacy `state.cwd`, not the
+     * current `state.workspace.root`; callers use it as the stable main-project
+     * fallback when a worktree is unavailable or is being released.
      */
+    readSessionMainRoot(sessionId: string): string | undefined;
+    /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
+    readSessionKind(sessionId: string): SessionKind | undefined;
+    /** Cheap durable digital-human binding read. */
+    readSessionWorkspaceProfile(sessionId: string): string | undefined;
+    /**
+     * Find durable Sessions currently bound to one digital-human profile without loading
+     * transcripts. Used by profile deletion guards so a reusable/historical
+     * Session cannot be left permanently unresumable.
+     */
+    /**
+     * Sessions whose state pins this digital human.
+     *
+     * `includeArchived: false` drops archived Sessions: they are closed history,
+     * not a live binding, so they should not block deleting the profile. A
+     * dangling name is already handled downstream — resolveActiveWorkspaceProfile
+     * logs `profile.active_missing_from_library` and returns undefined.
+     */
+    findSessionIdsByWorkspaceProfile(profileName: string, limit?: number, options?: {
+        includeArchived?: boolean;
+    }): string[];
+    /** @deprecated Use readSessionMainRoot; retained for public API compatibility. */
     readCwd(sessionId: string): string | undefined;
+    /** Disk-only direct-parent ACL metadata. Undefined means unprovable/corrupt. */
+    readParentSessionId(sessionId: string): string | null | undefined;
     /**
      * Disk-only workspace pointer reader. Legacy sessions written before
      * `workspace` existed are treated as main-workspace sessions rooted at
@@ -81,7 +155,11 @@ export declare class SessionManager {
      * `cwd`. P1 will teach ToolContext to resolve cwd from this field; for P0 it
      * is a safety pointer and resume breadcrumb.
      */
-    setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): void;
+    setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): number;
+    /** Read the durable archival timestamp; undefined = not archived / unprovable. */
+    readSessionArchivedAt(sessionId: string): number | undefined;
+    /** Set (number) or clear (undefined) the durable archival marker. */
+    setSessionArchived(sessionId: string, archivedAt: number | undefined): number;
     recordWorkspaceHandoff(sessionId: string, from: SessionWorkspace | undefined, to: SessionWorkspace): void;
     /**
      * Resolve the cwd a resumed session must run in from its persisted workspace
@@ -93,8 +171,8 @@ export declare class SessionManager {
     resolveSessionWorkspaceForResume(sessionId: string): Promise<SessionWorkspaceResumeResolution>;
     /**
      * Cheap "does this session have a persisted goal?" probe — reads only
-     * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY
-     * in state.activeGoal; it is never appended to the transcript as an event, so
+     * state.json, NOT the transcript (like readSessionMainRoot). A persistent goal lives in
+     * the canonical goalLifecycle union; it is never appended to the transcript as an event, so
      * a session rebuilt from disk (e.g. localStorage wiped) can't recover the
      * goal from its messages. The desktop host calls this on session load to
      * re-surface the active-goal block + its Cancel button, which would otherwise
@@ -102,11 +180,12 @@ export declare class SessionManager {
      * run. Returns undefined for an unknown / malformed / traversal-shaped id, or
      * a session with no active goal — never throws.
      */
-    readActiveGoal(sessionId: string): import("../engine/goal.js").GoalConfig | undefined;
+    readActiveGoal(sessionId: string): import("../goal/lifecycle.js").GoalConfig | undefined;
     /**
      * Disk-only "wipe this session's persistent goal" — the counterpart to
-     * readActiveGoal. Reads state.json, removes state.activeGoal, and rewrites it
-     * atomically (via saveState). Returns true only if a goal was actually
+     * readActiveGoal. Reads state.json, transitions the matching goalLifecycle
+     * to terminal(user_cleared), and rewrites it through the field-level CAS.
+     * Returns true only if a goal was actually
      * present (idempotent — clearing a session with no goal is a no-op returning
      * false). Never throws on an unknown / malformed / traversal-shaped id
      * (returns false), matching readActiveGoal's tolerance.
@@ -119,17 +198,121 @@ export declare class SessionManager {
      * Engine.clearGoal also delegates its disk write here so the wipe logic lives
      * in exactly one place.
      */
-    clearActiveGoal(sessionId: string): boolean;
+    clearActiveGoal(sessionId: string, expected?: {
+        goalId?: string;
+        revision?: number;
+    }): boolean;
+    /**
+     * Edit or pause/resume the currently active goal with an identity-checked,
+     * field-level CAS. The goalId is preserved: editing the objective changes
+     * the same user-owned goal rather than terminally cancelling it and arming a
+     * replacement. A changed objective receives a fresh deadline anchor.
+     *
+     * Returns undefined when the session/goal is absent or the patch is invalid.
+     * The returned state lets a live Engine rebase its in-memory bundle after
+     * this control operation.
+     */
+    updateActiveGoal(sessionId: string, patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId?: string;
+        expectedRevision?: number;
+    }): {
+        goal: GoalConfig;
+        stateRevision: number;
+        state: SessionState;
+    } | undefined;
     resume(sessionId: string): SessionBundle;
-    saveState(state: SessionState): void;
     /**
-     * Fork a session from a specific point.
-     * Creates a new session that shares events up to the given turn,
-     * then diverges independently.
+     * Return the exact persistence directory owned by this manager.
+     *
+     * Cross-session sidecars (for example versioned handoffs) use this to stay
+     * inside an identity/custom-data-root boundary instead of falling back to
+     * the process-global default sessions directory.
+     */
+    getStorageDir(): string;
+    /**
+     * Read one durable session state without changing its lifecycle status.
+     * `resume()` intentionally marks the returned in-memory state active; host
+     * coordination code needs a read-only snapshot for completed cursors and
+     * workspace/profile metadata.
+     */
+    readSessionState(sessionId: string): SessionState | undefined;
+    /**
+     * Merge a field-level state update into the latest persisted snapshot.
+     *
+     * Unlike saveState(), callers do not supply a potentially stale whole-state
+     * object. saveState serializes the read/revision-check/write section with the
+     * per-session lock and returns the new persisted revision to the caller.
+     */
+    updateSessionState(sessionId: string, partial: SessionStateFieldPatch): number;
+    /**
+     * Atomically add one billed auxiliary request to the latest source state.
+     * This field-level read/add/write avoids publishing a detached stale state
+     * snapshot and accounts prompt, completion, total, cache, and cost together.
+     */
+    recordAuxiliaryUsage(sessionId: string, usage: TokenUsage, costState?: Record<string, unknown>): void;
+    /** @deprecated Compatibility fixture writer; runtime code must use domain updates. */
+    saveState(state: SessionState, generation?: number): boolean;
+    /**
+     * Persist one goal terminal transition without allowing a revision race to
+     * resurrect that goal. This is always a Goal-domain update: read the newest
+     * snapshot, transition only the matching lifecycle identity, then commit. A detached run
+     * snapshot is never used as the write candidate,
+     * so a successful terminal transition cannot publish stale summary/workspace
+     * or accounting fields. Lock/generation conflicts remain distinct failures.
+     */
+    saveGoalTerminal(state: SessionState, goal: GoalConfig | undefined, reason: PersistedGoalTerminationReason): boolean;
+    /**
+     * Persist a terminal transition and distinguish a durable commit from a stale
+     * run whose Goal identity has already been replaced. Callers may publish a
+     * terminal event only for `persisted`.
+     */
+    saveGoalTerminalOutcome(state: SessionState, goal: GoalConfig | undefined, reason: PersistedGoalTerminationReason): GoalTerminalSaveOutcome;
+    /**
+     * Arm or migrate one active goal as a Goal-domain update. The newest state is
+     * always the write base, so unrelated fields written by another host survive.
+     * Replacement is explicit and terminally closes the latest active identity;
+     * a non-replacement write may only normalize the same legacy/current goal.
+     */
+    saveActiveGoal(state: SessionState, goal: GoalConfig, options?: {
+        replaceCurrent?: boolean;
+    }): boolean;
+    /** Persist active → waiting only for the expected concrete Goal version. */
+    markGoalWaiting(state: SessionState, goal: GoalConfig): boolean;
+    /** Drop a matching active goal only when its terminal identity is durable. */
+    clearTerminatedActiveGoal(state: SessionState, goal: GoalConfig): boolean;
+    /**
+     * Commit only the fields owned by a live run. The detached `state` object is
+     * used solely as a live-view target for the returned revision; it is never
+     * serialized wholesale. This prevents a Goal/workspace/title domain write
+     * from authorizing a later stale metadata overwrite.
      */
-    fork(sourceSessionId: string, forkAtTurn?: number): SessionBundle;
-    list(limit?: number): SessionListEntry[];
+    saveStateOrUpdateFields(state: SessionState, partial: SessionStateFieldPatch): boolean;
+    private saveStateAttempt;
+    private acquireStateLock;
+    /** Recover only the old implementation's regular-file orphan lock. */
+    private prepareLegacyStateLock;
+    private readPersistedState;
+    private rebaseLiveState;
+    private generationKey;
+    /** Create an independent, top-level session from a frozen event cursor. */
+    fork(sourceSessionId: string, options?: ForkSessionOptions): ForkSessionResult;
+    /** Freeze and validate an inclusive source range before any model call. */
+    selectContextPackage(sourceSessionId: string, range: {
+        fromEventId: string;
+        toEventId: string;
+    }): ReturnType<typeof Transcript.selectContextRange>;
+    /** Publish a summary-only top-level fork after summarization has succeeded. */
+    createSummaryFork(sourceSessionId: string, options: SummaryForkOptions): ForkSessionResult;
+    private readForkSnapshot;
+    private publishSessionAtomically;
+    list(limit?: number, opts?: {
+        excludeKinds?: readonly string[];
+    }): SessionListEntry[];
 }
+export declare function buildForkState(source: SessionState, targetSessionId: string, lineage: SessionForkLineage, startedAt?: number): SessionState;
+export declare function buildForkTranscript(sourceEvents: readonly TranscriptEvent[], state: SessionState): TranscriptEvent[];
 export type SessionListEntry = SessionState & {
     preview?: string;
     /** Last activity time — transcript mtime, falling back to startedAt. */