@cjhyy/code-shell-core 0.5.0-rc.1 → 0.5.0-rc.2

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

@@ -7,6 +7,28 @@ export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function assertSafeSessionId(sessionId: unknown): asserts sessionId is string;
+/**
+ * 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
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export declare function codeShellHome(): string;
 export declare class SessionManager {
     private readonly sessionsDir;
     constructor(storageDir?: string);
@@ -17,7 +39,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): SessionBundle;
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin): SessionBundle;
     /**
      * Whether a session directory exists on disk. Used by ChatSession-driven
      * cold starts to decide between resume vs create-with-explicit-sid

package/dist/session/session-manager.js

@@ -7,10 +7,57 @@ import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export function assertSafeSessionId(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new SessionError(`invalid session id: must be a non-empty string`);
+    }
+    // basename check: reject any path-shaped value. Covers absolute paths,
+    // POSIX and Windows separators, parent-dir tokens, and the lone "..".
+    if (sessionId.includes("/") || sessionId.includes("\\")) {
+        throw new SessionError(`invalid session id: contains path separator: ${sessionId}`);
+    }
+    if (sessionId === "." || sessionId === ".." || sessionId.includes("..")) {
+        throw new SessionError(`invalid session id: contains parent-dir token: ${sessionId}`);
+    }
+    // Conservative character allow-list: letters, digits, and `-_.` only.
+    // This matches what nanoid emits plus the dotted variants in-house code
+    // already uses (e.g. "tui-main", "agent.foo"). Anything else (NUL,
+    // newline, control chars, shell metacharacters, glob chars) is rejected.
+    if (!/^[A-Za-z0-9_.-]+$/.test(sessionId)) {
+        throw new SessionError(`invalid session id: unexpected characters: ${sessionId}`);
+    }
+    // Cap the length to keep filesystem APIs happy and avoid disk-name DoS.
+    if (sessionId.length > 128) {
+        throw new SessionError(`invalid session id: too long (max 128 chars)`);
+    }
+}
+/**
+ * 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
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export function codeShellHome() {
+    return process.env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
+}
 export class SessionManager {
     sessionsDir;
     constructor(storageDir) {
-        this.sessionsDir = storageDir ?? join(homedir(), ".code-shell", "sessions");
+        this.sessionsDir = storageDir ?? join(codeShellHome(), "sessions");
         mkdirSync(this.sessionsDir, { recursive: true });
     }
     /**
@@ -20,7 +67,12 @@ export class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd, model, provider, explicitSessionId) {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin) {
+        // External callers may pass any string; nanoid output is trusted. Either
+        // way the ID gets joined into a filesystem path, so the public entry
+        // point validates before that join.
+        if (explicitSessionId !== undefined)
+            assertSafeSessionId(explicitSessionId);
         const sessionId = explicitSessionId ?? nanoid(16);
         const sessionDir = join(this.sessionsDir, sessionId);
         mkdirSync(sessionDir, { recursive: true });
@@ -34,6 +86,12 @@ export class SessionManager {
             turnCount: 0,
             invokedSkills: [],
             status: "active",
+            // Always write the key: a sub-agent gets its parent sid; a top-level
+            // session gets explicit null. This lets the desktop disk-rebuild tell a
+            // new top-level session (key present, null) apart from a legacy session
+            // (key absent) and from a sub-agent (key present, non-empty string).
+            parentSessionId: parentSessionId ?? null,
+            ...(origin ? { origin } : {}),
         };
         writeFileSync(join(sessionDir, "state.json"), JSON.stringify(state, null, 2), "utf-8");
         const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
@@ -52,9 +110,19 @@ export class SessionManager {
      * without catching SessionError.
      */
     exists(sessionId) {
+        // exists() is a probe — callers use it to decide between resume and
+        // create-with-explicit-sid. Treat an invalid id as "not present"
+        // rather than letting the traversal-shaped string reach existsSync.
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return false;
+        }
         return existsSync(join(this.sessionsDir, sessionId));
     }
     resume(sessionId) {
+        assertSafeSessionId(sessionId);
         const sessionDir = join(this.sessionsDir, sessionId);
         if (!existsSync(sessionDir)) {
             throw new SessionError(`Session not found: ${sessionId}`);
@@ -70,6 +138,9 @@ export class SessionManager {
         return { state, transcript };
     }
     saveState(state) {
+        // state.sessionId could come from a deserialized state.json that was
+        // tampered with on disk. Validate before joining.
+        assertSafeSessionId(state.sessionId);
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
         // Atomic write: stage to .tmp, then rename. Protects against two processes

package/dist/settings/disk-defaults.d.ts

@@ -0,0 +1,35 @@
+import type { ValidatedSettings } from "./schema.js";
+import type { EngineConfig } from "../engine/engine.js";
+/**
+ * The subset of EngineConfig the config hot-reload ("layer 2") pushes onto an
+ * already-running session's `this.config`. These are the "disk-default" fields:
+ * read from settings.json at construction, otherwise frozen for the session's
+ * life. Request-override fields (permissionMode / goal / maxTurns /
+ * maxContextTokens / cwd) are intentionally excluded — those are per-request
+ * and handled by handleConfigure / run() options, not by disk hot-push.
+ *
+ * Reload semantics per field (see Engine.refreshRuntimeConfig):
+ *   - preset: system-prompt / behavior hot-reloads (next-turn PromptComposer
+ *     re-resolves it); the builtin TOOL SET it implies needs a session restart
+ *     (registry is ctor-frozen, possibly shared via runtime).
+ *   - customSystemPrompt / appendSystemPrompt / responseLanguage / userProfile:
+ *     hot — re-read by the next-turn PromptComposer.
+ *
+ * IMPORTANT (#8): every field here is pushed as a PURE DISK value and will
+ * OVERRIDE any per-request slice override of the same field on the running
+ * session. Safe for the desktop host today (its slice carries only
+ * permissionMode+cwd, both excluded above). A future host that sets any of
+ * these per-request MUST exclude that field from the reload patch — or track
+ * per-request overrides separately — to avoid the reload clobbering it.
+ */
+export type DiskDefaultPatch = Pick<EngineConfig, "preset" | "customSystemPrompt" | "appendSystemPrompt" | "responseLanguage" | "userProfile" | "instructions" | "mcpServers">;
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export declare function diskDefaultsFrom(settings: ValidatedSettings): DiskDefaultPatch;

package/dist/settings/disk-defaults.js

@@ -0,0 +1,24 @@
+import { personalizationFrom } from "./personalization.js";
+import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export function diskDefaultsFrom(settings) {
+    const agent = settings.agent ?? {};
+    return {
+        preset: agent.preset,
+        customSystemPrompt: agent.customSystemPrompt,
+        appendSystemPrompt: agent.appendSystemPrompt,
+        ...personalizationFrom(agent),
+        // Same merge engineFactory uses: user-configured servers + enabled
+        // plugins' servers. Plugin servers a disabled plugin would contribute are
+        // skipped, matching new-session construction.
+        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, settings.disabledPlugins ?? []),
+    };
+}

package/dist/settings/manager.d.ts

@@ -4,6 +4,14 @@
  * Priority: CLI flags > local > project > user > managed
  */
 import { type ValidatedSettings } from "./schema.js";
+/**
+ * Resolve the user's home directory. Prefers `process.env.HOME` so that
+ * runtime env overrides (set after process start, e.g. in tests) actually
+ * take effect — on some runtimes (e.g. Bun on macOS) `os.homedir()` is
+ * cached from the user database at process startup and ignores later
+ * `process.env.HOME` mutations.
+ */
+export declare function userHome(): string;
 export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
 /**
  * Which disk layers a SettingsManager is allowed to read.
@@ -42,6 +50,31 @@ export declare class SettingsManager {
      * The merged cache is invalidated so the next get() picks up the change.
      */
     saveUserSetting(key: string, value: unknown): void;
+    /**
+     * Persist a single setting (dotted key path) to the PROJECT-level config
+     * file at ${cwd}/.code-shell/settings.json. This is where capabilityOverrides
+     * live — project overlays never touch the global user file. Atomic write +
+     * cache invalidation mirror saveUserSetting.
+     */
+    saveProjectSetting(key: string, value: unknown, cwd: string): void;
+    /**
+     * Delete a single dotted key from the PROJECT-level config file. Used to
+     * express "inherit" — we don't persist the literal "inherit"; we remove the
+     * override key. No-ops if the file or any intermediate segment is absent.
+     */
+    deleteProjectSetting(key: string, cwd: string): void;
+    /**
+     * Read ONE scope's raw settings file, validated but UNMERGED. Capability
+     * overlay math needs the project overlay and the user/global baseline
+     * separately — the merged get() collapses provenance and can't express
+     * tri-state inheritance. user → ~/.code-shell/settings.json, project →
+     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
+     * are returned (defaults are not synthesized), so an absent file → {}.
+     */
+    getForScope(scope: "user" | "project", cwd?: string): Partial<ValidatedSettings>;
+    private projectSettingsPath;
+    private readJsonObject;
+    private atomicWriteJson;
     private loadJsonFile;
     private deepMerge;
 }

package/dist/settings/manager.js

@@ -15,7 +15,7 @@ import { migrateModels } from "../migrate-models.js";
  * cached from the user database at process startup and ignores later
  * `process.env.HOME` mutations.
  */
-function userHome() {
+export function userHome() {
     return process.env.HOME ?? homedir();
 }
 export class SettingsManager {
@@ -155,6 +155,99 @@ export class SettingsManager {
         renameSync(tmp, path);
         this.invalidate();
     }
+    /**
+     * Persist a single setting (dotted key path) to the PROJECT-level config
+     * file at ${cwd}/.code-shell/settings.json. This is where capabilityOverrides
+     * live — project overlays never touch the global user file. Atomic write +
+     * cache invalidation mirror saveUserSetting.
+     */
+    saveProjectSetting(key, value, cwd) {
+        const path = this.projectSettingsPath(cwd);
+        const current = this.readJsonObject(path);
+        const parts = key.split(".");
+        let target = current;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const seg = parts[i];
+            const next = target[seg];
+            if (!next || typeof next !== "object" || Array.isArray(next)) {
+                target[seg] = {};
+            }
+            target = target[seg];
+        }
+        target[parts[parts.length - 1]] = value;
+        this.atomicWriteJson(path, current);
+        this.invalidate();
+    }
+    /**
+     * Delete a single dotted key from the PROJECT-level config file. Used to
+     * express "inherit" — we don't persist the literal "inherit"; we remove the
+     * override key. No-ops if the file or any intermediate segment is absent.
+     */
+    deleteProjectSetting(key, cwd) {
+        const path = this.projectSettingsPath(cwd);
+        if (!existsSync(path))
+            return;
+        const current = this.readJsonObject(path);
+        const parts = key.split(".");
+        let target = current;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const next = target?.[parts[i]];
+            if (!next || typeof next !== "object" || Array.isArray(next))
+                return;
+            target = next;
+        }
+        if (target)
+            delete target[parts[parts.length - 1]];
+        this.atomicWriteJson(path, current);
+        this.invalidate();
+    }
+    /**
+     * Read ONE scope's raw settings file, validated but UNMERGED. Capability
+     * overlay math needs the project overlay and the user/global baseline
+     * separately — the merged get() collapses provenance and can't express
+     * tri-state inheritance. user → ~/.code-shell/settings.json, project →
+     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
+     * are returned (defaults are not synthesized), so an absent file → {}.
+     */
+    getForScope(scope, cwd) {
+        const path = scope === "user"
+            ? join(userHome(), ".code-shell", "settings.json")
+            : this.projectSettingsPath(cwd ?? this.cwd);
+        const raw = this.readJsonObject(path);
+        // validateSettings applies defaults; for a scope view we want only the
+        // file's own keys, so validate then project back the present keys.
+        const validated = validateSettings(raw);
+        const out = {};
+        for (const k of Object.keys(raw))
+            out[k] = validated[k];
+        return out;
+    }
+    projectSettingsPath(cwd) {
+        if (!cwd || cwd.trim().length === 0) {
+            throw new Error("project setting write requires a non-empty cwd");
+        }
+        return join(cwd, ".code-shell", "settings.json");
+    }
+    readJsonObject(path) {
+        if (!existsSync(path))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Corrupt file — overwrite rather than crash.
+        }
+        return {};
+    }
+    atomicWriteJson(path, data) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+        renameSync(tmp, path);
+    }
     loadJsonFile(path, name, priority) {
         if (!existsSync(path))
             return;

package/dist/settings/personalization.d.ts

@@ -0,0 +1,19 @@
+/** The agent.* subset of settings the Engine needs for personalization +
+ * instruction-file compat. Hosts spread this into EngineConfig so the three
+ * fields stay wired identically across desktop / TUI / TCP (avoids per-host drift). */
+export interface PersonalizationConfig {
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+}
+export declare function personalizationFrom(agent: {
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+}): PersonalizationConfig;

package/dist/settings/personalization.js

@@ -0,0 +1,7 @@
+export function personalizationFrom(agent) {
+    return {
+        responseLanguage: agent.responseLanguage,
+        userProfile: agent.userProfile,
+        instructions: agent.instructions,
+    };
+}