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

package/dist/capability-control/project.js

@@ -0,0 +1,147 @@
+/**
+ * Pure projection functions: each turns one loader's output + the relevant
+ * slice of current settings into CapabilityDescriptor[]. No I/O, no state —
+ * the CapabilityService feeds them and composes the results.
+ *
+ * See docs/superpowers/specs/2026-05-29-capability-control-design.md
+ */
+/**
+ * Builtin tools. A tool's switch lives in the denylist when it ships in the
+ * preset default set (turning it off = adding to agent.disabledBuiltinTools),
+ * and in the allowlist otherwise (turning it on = adding to
+ * agent.enabledBuiltinTools). This mirrors resolveBuiltinToolNames, whose
+ * effective set is `preset.builtinTools ∪ enabled − disabled`.
+ */
+export function projectBuiltin(input) {
+    const defaults = new Set(input.presetDefaults);
+    const on = new Set(input.effective);
+    return input.tools.map((t) => {
+        const inPreset = defaults.has(t.name);
+        return {
+            id: `builtin:${t.name}`,
+            kind: "builtin",
+            name: t.name,
+            description: t.description,
+            enabled: on.has(t.name),
+            control: inPreset
+                ? {
+                    settingsKey: "agent.disabledBuiltinTools",
+                    mode: "denylist",
+                    token: t.name,
+                }
+                : {
+                    settingsKey: "agent.enabledBuiltinTools",
+                    mode: "allowlist",
+                    token: t.name,
+                },
+            origin: { isReadOnly: t.isReadOnly },
+        };
+    });
+}
+/**
+ * MCP, projected per server (not per tool). Every configured server gets a
+ * descriptor — including unconnected ones — driven by the mcpServers config;
+ * tool counts come from the registry's connected mcp tools (0 if none).
+ */
+export function projectMcp(input) {
+    const counts = new Map();
+    for (const t of input.mcpTools) {
+        if (t.source !== "mcp" || !t.serverName)
+            continue;
+        counts.set(t.serverName, (counts.get(t.serverName) ?? 0) + 1);
+    }
+    return Object.entries(input.mcpServers).map(([serverName, cfg]) => {
+        const toolCount = counts.get(serverName) ?? 0;
+        return {
+            id: `mcp:${serverName}`,
+            kind: "mcp",
+            name: serverName,
+            description: `${toolCount} tools`,
+            enabled: cfg.enabled !== false,
+            control: {
+                settingsKey: "mcpServers",
+                mode: "record-flag",
+                token: serverName,
+            },
+            origin: { serverName, toolCount },
+        };
+    });
+}
+/**
+ * Project/user skills. The caller MUST pass the FULL skill set (scanSkills
+ * with empty opts), because scanSkills filters disabled entries out — passing
+ * a filtered set would drop disabled skills from the list, leaving the UI no
+ * way to re-enable them. Plugin-sourced skills are excluded here; they surface
+ * under their plugin via projectPlugins.
+ */
+export function projectSkills(input) {
+    const disabled = new Set(input.disabledSkills);
+    return input.skills
+        .filter((s) => s.source === "project" || s.source === "user")
+        .map((s) => ({
+        id: `skill:${s.name}`,
+        kind: "skill",
+        name: s.name,
+        description: s.description,
+        enabled: !disabled.has(s.name),
+        control: {
+            settingsKey: "disabledSkills",
+            mode: "denylist",
+            token: s.name,
+        },
+        origin: { filePath: s.filePath },
+    }));
+}
+/**
+ * Project/user sub-agent roles, projected per role. Like projectSkills, the
+ * caller MUST pass the FULL agent set (loaded WITHOUT the disabled filter), so
+ * disabled roles still appear in the list and can be re-enabled. Plugin-sourced
+ * agents are excluded — they ride their plugin's switch via projectPlugins, and
+ * disabledAgents only governs user/project roles. Toggling writes the top-level
+ * `disabledAgents` denylist (same key the 子代理 tab uses), so the two stay in
+ * sync; the project overlay layers on via capabilityOverrides.agents.
+ */
+export function projectAgents(input) {
+    const disabled = new Set(input.disabledAgents);
+    return input.agents
+        .filter((a) => a.source === "project" || a.source === "user")
+        .map((a) => ({
+        id: `agent:${a.name}`,
+        kind: "agent",
+        name: a.name,
+        description: a.description,
+        enabled: !disabled.has(a.name),
+        control: {
+            settingsKey: "disabledAgents",
+            mode: "denylist",
+            token: a.name,
+        },
+        origin: { filePath: a.filePath },
+    }));
+}
+/**
+ * Installed plugins, projected per plugin. Install keys are `<plugin>@<market>`;
+ * the bare plugin name is the substring before the last `@` and matches the
+ * `plugin:` prefix that disabledPlugins controls.
+ */
+export function projectPlugins(input) {
+    const disabled = new Set(input.disabledPlugins);
+    const names = new Set();
+    for (const key of Object.keys(input.installed)) {
+        const at = key.lastIndexOf("@");
+        names.add(at > 0 ? key.slice(0, at) : key);
+    }
+    return [...names].map((name) => ({
+        id: `plugin:${name}`,
+        kind: "plugin",
+        name,
+        description: "",
+        enabled: !disabled.has(name),
+        control: {
+            settingsKey: "disabledPlugins",
+            mode: "denylist",
+            token: name,
+        },
+        origin: { pluginName: name },
+    }));
+}

package/dist/capability-control/service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * CapabilityService — the single control-layer entry point.
+ *
+ *  - list(): composes the four projections into one CapabilityDescriptor[].
+ *  - setEnabled(id, on): reads the target descriptor's inlined `control` and
+ *    routes the write to the right settings key. It never branches on `kind`.
+ *
+ * Dependencies are injected (not imported) so the service is unit-testable
+ * without touching disk: the engine / desktop wiring supplies the real
+ * ToolRegistry, SettingsManager, and loaders.
+ *
+ * See docs/superpowers/specs/2026-05-29-capability-control-design.md
+ */
+import type { ToolRegistry } from "../tool-system/registry.js";
+import type { SettingsManager } from "../settings/manager.js";
+import type { SkillDefinition } from "../skills/scanner.js";
+import type { AgentDefinition } from "../agent/agent-definition.js";
+import type { InstalledPluginsV2 } from "../plugins/types.js";
+import type { CapabilityDescriptor, WriteScope, CapabilityOverrideState } from "./types.js";
+export interface CapabilityServiceDeps {
+    registry: Pick<ToolRegistry, "listToolsDetailed">;
+    settings: Pick<SettingsManager, "get" | "saveUserSetting" | "saveProjectSetting" | "deleteProjectSetting" | "getForScope">;
+    cwd: string;
+    scanSkills: (cwd: string, opts?: {
+        disabledSkills?: string[];
+        disabledPlugins?: string[];
+    }) => SkillDefinition[];
+    /** Full agent role set for `cwd` (user + project), loaded WITHOUT the
+     *  disabled filter so disabled roles still list and can be re-enabled. */
+    scanAgents: (cwd: string) => AgentDefinition[];
+    readInstalledPlugins: () => InstalledPluginsV2;
+    resolveBuiltinToolNames: (o?: {
+        preset?: string;
+        enabledBuiltinTools?: string[];
+        disabledBuiltinTools?: string[];
+    }) => string[];
+}
+export declare class CapabilityService {
+    private readonly deps;
+    constructor(deps: CapabilityServiceDeps);
+    /**
+     * List capability descriptors. With no `cwd` this is the user/global view
+     * (enabled === global baseline). With a `cwd` it's that project's view:
+     * each descriptor gains globalEnabled / projectOverride / effectiveSource
+     * and `enabled` reflects the tri-state overlay (spec §6.1).
+     */
+    list(cwd?: string): CapabilityDescriptor[];
+    /**
+     * Toggle a capability. Default scope is "user" (back-compat: old callers
+     * pass no opts → global write, unchanged). scope:"project" maps on/off to a
+     * tri-state override and writes capabilityOverrides (requires cwd).
+     */
+    setEnabled(id: string, on: boolean, opts?: {
+        scope?: WriteScope;
+        cwd?: string;
+    }): void;
+    /**
+     * Write a project tri-state override. "inherit" deletes the key (we never
+     * persist the literal). All capability kinds — including builtin, which
+     * writes to capabilityOverrides.builtin.<token> — now support project
+     * overrides; only a kind with no bucket (bucketForKind returns undefined)
+     * is rejected.
+     */
+    setOverride(id: string, state: CapabilityOverrideState, opts: {
+        scope: "project";
+        cwd: string;
+    }): void;
+    /** Existing global write path — unchanged behavior, refactored out of setEnabled. */
+    private writeUserScope;
+}

package/dist/capability-control/service.js

@@ -0,0 +1,147 @@
+/**
+ * CapabilityService — the single control-layer entry point.
+ *
+ *  - list(): composes the four projections into one CapabilityDescriptor[].
+ *  - setEnabled(id, on): reads the target descriptor's inlined `control` and
+ *    routes the write to the right settings key. It never branches on `kind`.
+ *
+ * Dependencies are injected (not imported) so the service is unit-testable
+ * without touching disk: the engine / desktop wiring supplies the real
+ * ToolRegistry, SettingsManager, and loaders.
+ *
+ * See docs/superpowers/specs/2026-05-29-capability-control-design.md
+ */
+import { CapabilityNotFoundError } from "./types.js";
+import { projectBuiltin, projectMcp, projectSkills, projectPlugins, projectAgents, } from "./project.js";
+import { applyOverride, bucketForKind, overrideTokenForId, overrideFor, } from "./overlay.js";
+export class CapabilityService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * List capability descriptors. With no `cwd` this is the user/global view
+     * (enabled === global baseline). With a `cwd` it's that project's view:
+     * each descriptor gains globalEnabled / projectOverride / effectiveSource
+     * and `enabled` reflects the tri-state overlay (spec §6.1).
+     */
+    list(cwd) {
+        const s = this.deps.settings.get();
+        const agent = (s.agent ?? {});
+        const tools = this.deps.registry.listToolsDetailed();
+        const preset = agent.preset;
+        const base = [
+            ...projectBuiltin({
+                tools: tools.filter((t) => t.source === "builtin"),
+                presetDefaults: this.deps.resolveBuiltinToolNames({ preset }),
+                effective: this.deps.resolveBuiltinToolNames({
+                    preset,
+                    enabledBuiltinTools: agent.enabledBuiltinTools ?? [],
+                    disabledBuiltinTools: agent.disabledBuiltinTools ?? [],
+                }),
+            }),
+            ...projectMcp({
+                mcpServers: s.mcpServers ?? {},
+                mcpTools: tools.filter((t) => t.source === "mcp"),
+            }),
+            ...projectSkills({
+                skills: this.deps.scanSkills(this.deps.cwd, {}),
+                disabledSkills: s.disabledSkills ?? [],
+            }),
+            ...projectPlugins({
+                installed: this.deps.readInstalledPlugins().plugins,
+                disabledPlugins: s.disabledPlugins ?? [],
+            }),
+            ...projectAgents({
+                agents: this.deps.scanAgents(this.deps.cwd),
+                disabledAgents: s.disabledAgents ?? [],
+            }),
+        ];
+        const overrides = cwd
+            ? this.deps.settings.getForScope("project", cwd).capabilityOverrides
+            : undefined;
+        return base.map((d) => {
+            const globalEnabled = d.enabled;
+            const token = overrideTokenForId(d.id);
+            const ov = cwd ? overrideFor(overrides, d.kind, token) : undefined;
+            const enabled = applyOverride(globalEnabled, ov);
+            return {
+                ...d,
+                enabled,
+                globalEnabled,
+                projectOverride: ov,
+                effectiveSource: ov ? "project" : cwd ? "default" : "user",
+            };
+        });
+    }
+    /**
+     * Toggle a capability. Default scope is "user" (back-compat: old callers
+     * pass no opts → global write, unchanged). scope:"project" maps on/off to a
+     * tri-state override and writes capabilityOverrides (requires cwd).
+     */
+    setEnabled(id, on, opts) {
+        if (opts?.scope === "project") {
+            this.setOverride(id, on ? "on" : "off", {
+                scope: "project",
+                cwd: opts.cwd ?? this.deps.cwd,
+            });
+            return;
+        }
+        this.writeUserScope(id, on);
+    }
+    /**
+     * Write a project tri-state override. "inherit" deletes the key (we never
+     * persist the literal). All capability kinds — including builtin, which
+     * writes to capabilityOverrides.builtin.<token> — now support project
+     * overrides; only a kind with no bucket (bucketForKind returns undefined)
+     * is rejected.
+     */
+    setOverride(id, state, opts) {
+        const descriptor = this.list().find((c) => c.id === id);
+        if (!descriptor)
+            throw new CapabilityNotFoundError(id);
+        const bucket = bucketForKind(descriptor.kind);
+        if (!bucket)
+            throw new Error(`Capability kind '${descriptor.kind}' has no project override`);
+        if (!opts.cwd)
+            throw new Error("project override requires cwd");
+        const token = overrideTokenForId(id);
+        const path = `capabilityOverrides.${bucket}.${token}`;
+        if (state === "inherit")
+            this.deps.settings.deleteProjectSetting(path, opts.cwd);
+        else
+            this.deps.settings.saveProjectSetting(path, state, opts.cwd);
+    }
+    /** Existing global write path — unchanged behavior, refactored out of setEnabled. */
+    writeUserScope(id, on) {
+        const descriptor = this.list().find((c) => c.id === id);
+        if (!descriptor)
+            throw new CapabilityNotFoundError(id);
+        const { settingsKey, mode, token } = descriptor.control;
+        const s = this.deps.settings.get();
+        if (mode === "record-flag") {
+            const servers = { ...(s.mcpServers ?? {}) };
+            // Never conjure a server that was never configured.
+            if (!servers[token])
+                return;
+            servers[token] = { ...servers[token], enabled: on };
+            this.deps.settings.saveUserSetting("mcpServers", servers);
+            return;
+        }
+        const arr = new Set(readArray(s, settingsKey));
+        // denylist: present ⇒ OFF, so we want it present when turning off.
+        const wantPresent = mode === "allowlist" ? on : !on;
+        if (wantPresent)
+            arr.add(token);
+        else
+            arr.delete(token);
+        this.deps.settings.saveUserSetting(settingsKey, [...arr]);
+    }
+}
+/** Read an array at a dotted settings path (e.g. agent.disabledBuiltinTools). */
+function readArray(s, key) {
+    let cur = s;
+    for (const part of key.split("."))
+        cur = cur?.[part];
+    return Array.isArray(cur) ? cur : [];
+}

package/dist/capability-control/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Capability-control descriptor types.
+ *
+ * A read-only projection layer over the four extension-capability loaders
+ * (builtin tools, MCP servers, skills, plugins). A CapabilityDescriptor is a
+ * computed view, never a source of truth — the truth stays in the loaders +
+ * settings. Each descriptor carries an inlined `control` describing how to
+ * toggle it, so the switch router never has to branch on `kind`.
+ *
+ * See docs/superpowers/specs/2026-05-29-capability-control-design.md
+ */
+/** A uniform, read-only projection of one extension capability. */
+export interface CapabilityDescriptor {
+    /** Globally unique; the source prefix isolates the namespace. */
+    id: string;
+    kind: "builtin" | "mcp" | "skill" | "plugin" | "agent";
+    /** Display name: builtin=tool, mcp=server, skill=skill, plugin=plugin, agent=role. */
+    name: string;
+    /** One-line description pulled from the underlying metadata. */
+    description: string;
+    /** Computed from preset defaults + the relevant switch config. */
+    enabled: boolean;
+    /** Which settings key the switch writes, and how. */
+    control: CapabilityControl;
+    /** user/global baseline enablement, before any project overlay. */
+    globalEnabled?: boolean;
+    /** Project overlay state in a project-scope view. Absent === inherit. */
+    projectOverride?: "on" | "off";
+    /** Where the effective `enabled` value came from. */
+    effectiveSource?: "user" | "project" | "default";
+    /** Source details for UI grouping / navigation. */
+    origin?: {
+        serverName?: string;
+        pluginName?: string;
+        filePath?: string;
+        toolCount?: number;
+        isReadOnly?: boolean;
+    };
+}
+/** Describes which settings key the switch writes and the write semantics. */
+export interface CapabilityControl {
+    settingsKey: "agent.enabledBuiltinTools" | "agent.disabledBuiltinTools" | "mcpServers" | "disabledSkills" | "disabledPlugins" | "disabledAgents";
+    /**
+     *  - "denylist"    → off = token present in array (disabled*); on = removed
+     *  - "allowlist"   → on  = token present in array (enabled*); off = removed
+     *  - "record-flag" → flip mcpServers[token].enabled
+     */
+    mode: "denylist" | "allowlist" | "record-flag";
+    /** Identifier written into the array, or used as the record key. */
+    token: string;
+}
+export declare class CapabilityNotFoundError extends Error {
+    constructor(id: string);
+}
+/**
+ * Which settings file a capability write targets. Distinct from
+ * SettingsManager's disk-READ scope ("isolated" | "project" | "full"): this is
+ * the WRITE scope — user → global settings, project → capabilityOverrides.
+ */
+export type WriteScope = "user" | "project";
+/** Tri-state project override as seen by callers. */
+export type CapabilityOverrideState = "inherit" | "on" | "off";

package/dist/capability-control/types.js

@@ -0,0 +1,17 @@
+/**
+ * Capability-control descriptor types.
+ *
+ * A read-only projection layer over the four extension-capability loaders
+ * (builtin tools, MCP servers, skills, plugins). A CapabilityDescriptor is a
+ * computed view, never a source of truth — the truth stays in the loaders +
+ * settings. Each descriptor carries an inlined `control` describing how to
+ * toggle it, so the switch router never has to branch on `kind`.
+ *
+ * See docs/superpowers/specs/2026-05-29-capability-control-design.md
+ */
+export class CapabilityNotFoundError extends Error {
+    constructor(id) {
+        super(`Capability not found: ${id}`);
+        this.name = "CapabilityNotFoundError";
+    }
+}

package/dist/cli/agent-server-stdio.d.ts

@@ -29,4 +29,15 @@
  * transport is stdio NDJSON and the protocol surface is unchanged, this
  * bootstrap is invisible to them.
  */
-export {};
+import type { EngineConfigSlice } from "../protocol/chat-session-manager.js";
+import type { ValidatedSettings } from "../settings/schema.js";
+/**
+ * Resolve per-session agent config: protocol slice overrides win, else fall
+ * back to disk settings.agent.*. Fixes the bug where settings.agent.* never
+ * reached session engines (slice arrived with only permissionMode+cwd).
+ */
+export declare function resolveSessionAgentConfig(slice: EngineConfigSlice, settings: ValidatedSettings): {
+    preset: string;
+    customSystemPrompt: string | undefined;
+    appendSystemPrompt: string | undefined;
+};

package/dist/cli/agent-server-stdio.js

@@ -35,33 +35,59 @@ import { ChatSessionManager } from "../protocol/chat-session-manager.js";
 import { AgentServer } from "../protocol/server.js";
 import { StdioTransport } from "../protocol/transport.js";
 import { SettingsManager } from "../settings/manager.js";
+import { personalizationFrom } from "../settings/personalization.js";
 import { MCPManager } from "../tool-system/mcp-manager.js";
+import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
 import { CostTracker } from "../cost-tracker.js";
+import { installGracefulShutdown } from "./graceful-shutdown.js";
+import { cronScheduler } from "../automation/scheduler.js";
+import { CronStore, defaultCronStorePath } from "../automation/store.js";
+/**
+ * Resolve per-session agent config: protocol slice overrides win, else fall
+ * back to disk settings.agent.*. Fixes the bug where settings.agent.* never
+ * reached session engines (slice arrived with only permissionMode+cwd).
+ */
+export function resolveSessionAgentConfig(slice, settings) {
+    return {
+        preset: slice.preset ?? settings.agent.preset,
+        customSystemPrompt: slice.customSystemPrompt ?? settings.agent.customSystemPrompt,
+        appendSystemPrompt: slice.appendSystemPrompt ?? settings.agent.appendSystemPrompt,
+    };
+}
 // ─── Read base config from environment / settings ─────────────────
 const cwd = process.env.AGENT_CWD ?? process.cwd();
 // Load settings once to derive llm config for the seed engine.
-const settingsManager = new SettingsManager(cwd);
+// Desktop is a host application: read the full disk hierarchy (incl. the
+// user's ~/.code-shell). The SDK default 'project' would skip user config.
+const settingsManager = new SettingsManager(cwd, "full");
 const settings = settingsManager.get();
+// LLMConfig is pure model identity now — only the bare identity fields go here.
+// temperature/imageDetail/timeout/retryMaxAttempts are ClientDefaults, derived
+// inside Engine.populateModelPoolFromSettings from settings.model.temperature
+// and settings.images.detail.
 const llmConfig = {
     provider: settings.model.provider,
     model: settings.model.name,
     apiKey: settings.model.apiKey ?? "",
     baseUrl: settings.model.baseUrl,
-    temperature: settings.model.temperature,
     maxTokens: settings.model.maxTokens,
 };
 // ─── Step 1: seed engine — populates model pool from settings ─────
 const seedEngine = new Engine({
     llm: llmConfig,
     cwd,
+    settingsScope: "full",
     // No runtime — Engine.populateModelPoolFromSettings() runs in ctor.
 });
 // ─── Step 2: extract shared resources ────────────────────────────
 const modelPool = seedEngine.getModelPool();
 const toolRegistry = seedEngine.getToolRegistry();
-// Capture the seed engine's resolved llmConfig (post-populateModelPoolFromSettings).
-// This includes resolved provider/baseUrl/apiKey from settings.providers[].
+// Capture the seed engine's resolved llmConfig + clientDefaults
+// (post-populateModelPoolFromSettings). Session engines inherit defaults so
+// settings.model.temperature / images.detail apply uniformly without each
+// factory call re-reading settings.
 const resolvedLlmConfig = seedEngine.getConfig().llm;
+const resolvedClientDefaults = seedEngine.getConfig().clientDefaults;
 // Reuse the same SettingsManager instance for the runtime instead of constructing
 // a fresh one — avoids duplication and keeps the pattern cleaner.
 const sharedSettings = settingsManager;
@@ -87,30 +113,104 @@ const runtime = new EngineRuntime({
     costTracker,
 });
 // ─── Step 4: ChatSessionManager ──────────────────────────────────
+// Re-read settings from disk on each new session so edits the user makes in
+// the settings UI take effect on the NEXT session without restarting the
+// worker (the `settings` bootstrap snapshot above is read once at process
+// start and would otherwise pin every session to the launch-time values).
+// This is the "pull on session creation" tier — mirrors how Codex's new
+// threads call load_with_overrides() per start. (Hot-reloading ALREADY-RUNNING
+// sessions is a separate, heavier push mechanism, intentionally out of scope.)
+// Best-effort: if a freshly-edited settings.json is malformed, fall back to the
+// last-known-good bootstrap snapshot rather than failing to create a session.
+function freshSettings() {
+    try {
+        return settingsManager.load();
+    }
+    catch {
+        return settings;
+    }
+}
 const chatManager = new ChatSessionManager({
     runtime,
-    engineFactory: (slice) => new Engine({
-        llm: resolvedLlmConfig,
-        cwd,
-        runtime,
-        // Per-session overrides from the protocol request
-        permissionMode: slice.permissionMode,
-        preset: slice.preset,
-        customSystemPrompt: slice.customSystemPrompt,
-        appendSystemPrompt: slice.appendSystemPrompt,
-        maxTurns: slice.maxTurns,
-        maxContextTokens: slice.maxContextTokens,
-        ...(slice.cwd ? { cwd: slice.cwd } : {}),
-    }),
+    // resolvedLlmConfig is the bootstrap-time snapshot. When the user
+    // hot-switches models via configure() the modelPool.activeKey moves
+    // ahead of it, so newly-created sessions must re-resolve from the pool
+    // each time the factory fires; fall back to the snapshot only when the
+    // pool can't resolve (no active key — shouldn't happen in practice).
+    engineFactory: (slice) => {
+        const live = freshSettings();
+        return new Engine({
+            llm: runtime.modelPool.resolveLLMConfig() ?? resolvedLlmConfig,
+            // Inherit the seed engine's resolved clientDefaults so every session
+            // engine sees the user's temperature/imageDetail without each factory
+            // call re-running populateModelPoolFromSettings.
+            clientDefaults: resolvedClientDefaults,
+            cwd,
+            runtime,
+            // This stdio worker exists only to serve the desktop app, so every
+            // session it creates is a desktop-origin session.
+            origin: "desktop",
+            // Inherit full scope so spawned subagents read user config too.
+            settingsScope: "full",
+            // MCP servers from settings — the worker reads the full disk
+            // hierarchy at bootstrap (incl. ~/.code-shell). Without this the
+            // factory-built session Engine has config.mcpServers === undefined,
+            // so Engine.run()'s connectAll() guard never fires and no MCP server
+            // (stdio OR url) is ever connected. The shared runtime.mcpPool means
+            // the first session to connect populates connections for the worker.
+            // Plugin-provided MCP servers (mcp-servers.json in installed plugins)
+            // are merged in here so the model can actually call them.
+            mcpServers: mergePluginMcpServers(live.mcpServers ?? {}, live.disabledPlugins ?? []),
+            // Per-session overrides from the protocol request; fall back to
+            // settings.agent.* so the user's 个性化 settings actually apply
+            // (previously slice arrived with only permissionMode+cwd, so these
+            // were always undefined — the 自定义指令 box never took effect).
+            // `live` is re-read from disk per session, so settings edits take effect
+            // on the next session without a worker restart.
+            permissionMode: slice.permissionMode,
+            ...resolveSessionAgentConfig(slice, live),
+            // Personalization + instruction compat come from disk settings only
+            // (not per-request protocol overrides), so they read straight from
+            // `live` here rather than through the slice. Shared helper keeps the
+            // three fields wired identically across desktop / TUI / TCP.
+            ...personalizationFrom(live.agent),
+            maxTurns: slice.maxTurns,
+            maxContextTokens: slice.maxContextTokens,
+            ...(slice.cwd ? { cwd: slice.cwd } : {}),
+        });
+    },
     maxSessions: 16,
     idleTtlMs: 30 * 60 * 1000,
 });
 chatManager.startIdleSweeper();
+// ─── Cron persistence ────────────────────────────────────────────
+// The agent's CronCreate/Delete tools operate on the shared cronScheduler
+// singleton. In the desktop host this worker is a SEPARATE process from the
+// Electron main process that owns the live scheduler, so the only way a
+// chat-created job reaches the automation UI is through the shared on-disk
+// store (~/.code-shell/cron.json). Give this process's scheduler that store so
+// CronCreate persists; loadJobs() so the agent can list/modify existing jobs.
+// Execution is DISABLED here — this worker must not run scheduled jobs (the
+// main process owns execution); persistence is its only cron role. Without
+// this, loadJobs()/CronCreate would arm timers in this process too, double-
+// running jobs and corrupting run stats.
+cronScheduler.setStore(new CronStore(defaultCronStorePath()));
+cronScheduler.setExecutionEnabled(false);
+cronScheduler.loadJobs();
 // ─── Step 5: AgentServer over stdio ──────────────────────────────
 const stdioTransport = new StdioTransport(process.stdin, process.stdout);
-new AgentServer({
+const agentServer = new AgentServer({
     chatManager,
     transport: stdioTransport,
+    // Config hot-reload (layer 2) reads disk through the SAME closure the
+    // engineFactory uses for new sessions, so a reloaded running session and a
+    // newly-created session converge on identical disk config (no divergence).
+    settingsReader: freshSettings,
 });
+// Clean up on termination signals. Without this, SIGTERM (parent kill),
+// SIGINT (Ctrl+C), or SIGHUP would drop the process without closing sessions,
+// clearing the idle sweeper, or terminating child MCP/tool processes.
+// AgentServer.close() also closes the chatManager's sessions.
+installGracefulShutdown(agentServer);
 // Keep the process alive — readline in StdioTransport holds the event loop.
 // On parent close / stdin EOF the process will exit naturally.

package/dist/cli/agent-server-tcp.d.ts

@@ -0,0 +1,20 @@
+/**
+ * agent-server-tcp — headless server entry point over TCP (Phase 6).
+ *
+ * Mirrors agent-server-stdio.ts (same EngineRuntime + ChatSessionManager +
+ * AgentServer bootstrap), but listens on a TCP socket instead of stdio and
+ * also starts the in-process automation scheduler so a deployed server runs
+ * scheduled jobs 7x24 with no Electron/GUI.
+ *
+ * The automation module is the SAME zero-env-dependency module the desktop
+ * loads (startAutomation) — this is the "thin server host" the plan's D2
+ * describes: one module, two hosts.
+ *
+ * Usage:
+ *   AGENT_TCP_PORT=4321 node dist/cli/agent-server-tcp.js
+ *
+ * v1 SECURITY: binds 127.0.0.1 by default and has NO authentication. Do not
+ * expose to a public interface without adding auth (token/TLS). Use SSH
+ * tunneling for remote access in v1.
+ */
+export {};