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

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

@@ -32,26 +32,85 @@
 import { Engine } from "../engine/engine.js";
 import { EngineRuntime } from "../engine/runtime.js";
 import { ChatSessionManager } from "../protocol/chat-session-manager.js";
+import { SessionManager } from "../session/session-manager.js";
+import { validateSettings } from "../settings/schema.js";
 import { AgentServer } from "../protocol/server.js";
 import { StdioTransport } from "../protocol/transport.js";
-import { SettingsManager } from "../settings/manager.js";
+import { createNotification } from "../protocol/types.js";
+import { setCronChangedSink } from "../tool-system/builtin/cron.js";
+import { SettingsManager, noRepoDir } 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 { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
 import { CostTracker } from "../cost-tracker.js";
+import { installGracefulShutdown } from "./graceful-shutdown.js";
+import { backgroundShellManager } from "../runtime/background-shell.js";
+import { logger } from "../logging/logger.js";
+import { cronScheduler } from "../automation/scheduler.js";
+import { CronStore, defaultCronStorePath } from "../automation/store.js";
+import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.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,
+    };
+}
+/**
+ * Resolve a session's effective cwd. A protocol slice with an explicit cwd
+ * points the session at that project; a slice WITHOUT a cwd is a no-repo
+ * "纯聊天" session (the renderer omits cwd when no project is selected) and must
+ * land in the no-repo sandbox (~/.code-shell/no-repo) — NOT the worker's boot
+ * cwd.
+ *
+ * Why not the boot cwd: this stdio worker is long-lived and reused across
+ * sessions/projects, so its boot cwd is whatever project first spawned it.
+ * Inheriting it for a no-repo chat would (a) silently run the chat against a
+ * stale, unrelated project's files and (b) defeat the no-repo skill/plugin
+ * whitelist inversion (which only fires when cwd === noRepoDir).
+ */
+export function resolveSessionCwd(slice) {
+    return slice.cwd ?? noRepoDir();
+}
 // ─── 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.
 // 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();
-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,
-};
+// Bootstrap load must NOT crash the worker on a schema-invalid (but JSON-valid)
+// settings file: a hand-edited settings.json with e.g. `permissions.defaultMode:
+// "ask"` or `env.FOO: 123` makes SettingsSchema.parse throw a ZodError at module
+// top level, which the desktop/mobile host sees as "connection lost" / a
+// nonzero-exit worker. Fall back to schema defaults and print a readable,
+// truncated reason so the user can fix the file (freshSettings() applies the
+// same best-effort contract per session once the worker is up).
+let settings;
+try {
+    settings = settingsManager.get();
+}
+catch (err) {
+    const reason = (err instanceof Error ? err.message : String(err)).slice(0, 2000);
+    console.error(`[agent-server] settings.json 校验失败,已回退到默认配置(请修正后重启):\n${reason}`);
+    settings = validateSettings({});
+}
+// LLMConfig is pure model identity now — only the bare identity fields go here.
+// temperature/imageDetail/timeout/retryMaxAttempts are ClientDefaults, derived
+// inside Engine.populateModelPoolFromSettings (temperature is a ClientDefaults
+// knob; imageDetail from settings.images.detail).
+const seedLlm = resolveLLMConfigForTag(settings, "text", settings.defaults?.text);
+if (!seedLlm) {
+    console.error(`[agent-server] 没有可用的文本模型连接(defaults.text=${settings.defaults?.text ?? "未设置"})。` +
+        `请在「连接」页添加并填写凭证。`);
+    process.exit(1);
+}
+const llmConfig = seedLlm;
 // ─── Step 1: seed engine — populates model pool from settings ─────
 const seedEngine = new Engine({
     llm: llmConfig,
@@ -62,9 +121,12 @@ const seedEngine = new Engine({
 // ─── 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
+// the temperature ClientDefault / 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;
@@ -90,32 +152,163 @@ 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,
-        // Inherit full scope so spawned subagents read user config too.
-        settingsScope: "full",
-        // 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) => {
+        // Effective cwd for THIS session: explicit slice.cwd → that project; absent
+        // → the no-repo sandbox (NOT the worker's stale boot cwd). See
+        // resolveSessionCwd for the full rationale.
+        const sessionCwd = resolveSessionCwd(slice);
+        // Read settings for THIS session's cwd, not the worker's boot cwd. A single
+        // worker serves many projects; the boot-cwd `freshSettings()` snapshot pins
+        // every session to the first project's project-layer settings, so project
+        // `mcpServers` / `agent.*` / permissions from the boot project would leak
+        // into (and shadow) other projects' sessions. A per-session SettingsManager
+        // still reads the full hierarchy (user ~/.code-shell + THIS project's
+        // .code-shell), keeping user-global settings while picking up the correct
+        // project overlay. Falls back to the boot snapshot if this project's file is
+        // malformed (same best-effort contract as freshSettings()).
+        const sessionSettingsManager = new SettingsManager(sessionCwd, "full");
+        let live;
+        try {
+            live = sessionSettingsManager.load();
+        }
+        catch {
+            live = freshSettings();
+        }
+        // Fold project capabilityOverrides over the global disabledPlugins before
+        // the MCP merge — a plugin force-enabled in 能力总览 (project "on") must
+        // contribute its MCP servers even while globally disabled, and vice versa.
+        // Raw `live.disabledPlugins` alone ignored the project layer.
+        const { disabledPlugins } = computeEffectiveDisabledLists(sessionSettingsManager, sessionCwd);
+        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,
+            // sessionCwd resolves slice.cwd → no-repo sandbox (never the stale boot
+            // cwd). The slice.cwd spread below is now redundant with this but kept
+            // for clarity / explicitness.
+            cwd: sessionCwd,
+            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 ?? {}, disabledPlugins, live.mcpServerOverrides ?? {}),
+            // 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,
+            // Workspace trust for this project (asserted by desktop main's
+            // trust-store, threaded via RunParams). When false, core strips the
+            // project's dangerous .code-shell settings (permissions/env/hooks/…).
+            projectTrusted: slice.projectTrusted,
+            ...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,
+            // cwd already set to sessionCwd above (slice.cwd → no-repo fallback).
+        });
+    },
     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({
+// Cron jobs are persisted by this worker but only main arms/executes their
+// timers (this worker keeps setExecutionEnabled(false) above). When an AI tool
+// creates/deletes a cron job here, notify main over stdio so it reloads the
+// store and (re)arms its scheduler — otherwise AI-created jobs never fire.
+setCronChangedSink(() => {
+    stdioTransport.send(createNotification("agent/cronChanged", {}));
+});
+// Disk-only active-goal reader for agent/goalGet. In worker mode there is no
+// legacyEngine, and reopening a session after restart doesn't create a live
+// ChatSession (that only happens on a send), so chatManager.get() misses. This
+// reads the same ~/.code-shell/sessions/<id>/state.json every Engine writes, so
+// the goal block re-surfaces on load ("goal 还在但页面不显示" fix).
+const goalDiskReader = new SessionManager();
+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,
+    readActiveGoalFromDisk: (sessionId) => goalDiskReader.readActiveGoal(sessionId),
 });
+// 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() → chatManager.closeAll() also reaps background shells.
+installGracefulShutdown(agentServer);
+// Reap orphaned background shells left by a previously-crashed worker
+// (design §难点1): a worker crash detaches its `npm run dev` children, which
+// keep holding ports. Scanning pidfiles on boot lists still-alive groups as
+// `orphaned` (so ListShells/KillShell can clean them) and deletes stale ones.
+try {
+    const orphans = backgroundShellManager.reapOrphansFromPidfiles();
+    if (orphans.length > 0) {
+        logger.info("bg_shell.orphans_found", { count: orphans.length });
+    }
+}
+catch {
+    /* best-effort — never block worker startup on this */
+}
 // 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 {};

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

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+import { Engine } from "../engine/engine.js";
+import { EngineRuntime } from "../engine/runtime.js";
+import { ChatSessionManager } from "../protocol/chat-session-manager.js";
+import { AgentServer } from "../protocol/server.js";
+import { listenTcp } from "../protocol/tcp-transport.js";
+import { SettingsManager } from "../settings/manager.js";
+import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.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 { HeadlessApprovalBackend } from "../tool-system/permission.js";
+import { createRunManager } from "../run/factory.js";
+import { startAutomation } from "../automation/index.js";
+import { CronStore, defaultCronStorePath } from "../automation/store.js";
+import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.js";
+const cwd = process.env.AGENT_CWD ?? process.cwd();
+const port = Number(process.env.AGENT_TCP_PORT ?? "4321");
+const host = process.env.AGENT_TCP_HOST ?? "127.0.0.1";
+const settingsManager = new SettingsManager(cwd, "full");
+// Read once at startup and reuse for every session (see engineFactory below).
+// This is intentional for the TCP host: it's a headless long-running server,
+// so config changes — including `mcpServers` — take effect on restart, not
+// mid-session. (The stdio host re-reads per session via freshSettings(); the
+// difference is by design, not a bug. Assessment §4.8.)
+const settings = settingsManager.get();
+const seedLlm = resolveLLMConfigForTag(settings, "text", settings.defaults?.text);
+if (!seedLlm) {
+    console.error(`[agent-server] 没有可用的文本模型连接(defaults.text=${settings.defaults?.text ?? "未设置"})。` +
+        `请在「连接」页添加并填写凭证。`);
+    process.exit(1);
+}
+const llmConfig = seedLlm;
+// ── Shared runtime (same bootstrap as stdio) ─────────────────────
+const seedEngine = new Engine({ llm: llmConfig, cwd, settingsScope: "full" });
+const modelPool = seedEngine.getModelPool();
+const toolRegistry = seedEngine.getToolRegistry();
+const resolvedLlmConfig = seedEngine.getConfig().llm;
+const resolvedClientDefaults = seedEngine.getConfig().clientDefaults;
+const mcpPool = new MCPManager(toolRegistry);
+const costTracker = new CostTracker();
+const runtime = new EngineRuntime({
+    modelPool,
+    toolRegistry,
+    settings: settingsManager,
+    mcpPool,
+    costTracker,
+});
+const chatManager = new ChatSessionManager({
+    runtime,
+    engineFactory: (slice) => {
+        // Fold project capabilityOverrides over the global disabledPlugins for
+        // the MCP merge (能力总览 project "on" must override global off) — same
+        // contract as the stdio host's factory.
+        const sessionCwd = slice.cwd ?? cwd;
+        const { disabledPlugins } = computeEffectiveDisabledLists(new SettingsManager(sessionCwd, "full"), sessionCwd);
+        return new Engine({
+            llm: runtime.modelPool.resolveLLMConfig() ?? resolvedLlmConfig,
+            clientDefaults: resolvedClientDefaults,
+            cwd,
+            runtime,
+            settingsScope: "full",
+            mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, disabledPlugins, settings.mcpServerOverrides ?? {}),
+            permissionMode: slice.permissionMode,
+            preset: slice.preset,
+            customSystemPrompt: slice.customSystemPrompt,
+            appendSystemPrompt: slice.appendSystemPrompt,
+            // Personalization + instruction compat come from disk settings only
+            // (not per-request slice overrides) — same disk-only contract as the
+            // stdio host. Shared helper keeps the three fields wired identically.
+            ...personalizationFrom(settings.agent),
+            maxTurns: slice.maxTurns,
+            maxContextTokens: slice.maxContextTokens,
+            ...(slice.cwd ? { cwd: slice.cwd } : {}),
+        });
+    },
+    maxSessions: 16,
+    idleTtlMs: 30 * 60 * 1000,
+});
+chatManager.startIdleSweeper();
+// ── Automation (same module the desktop loads) ──────────────────
+// Read-only by default until write tiers are configured per job. Runs land in
+// the RunStore so history is queryable.
+const automationRunManager = createRunManager({
+    llm: resolvedLlmConfig,
+    cwd,
+    permissionMode: "default",
+    approvalBackend: new HeadlessApprovalBackend("approve-read-only"),
+});
+const automation = startAutomation({
+    store: new CronStore(defaultCronStorePath()),
+    runManager: automationRunManager,
+});
+// ── Serve over TCP ──────────────────────────────────────────────
+// One AgentServer per accepted connection, all sharing the same chatManager.
+const servers = new Set();
+listenTcp({ port, host }, (transport) => {
+    const server = new AgentServer({ chatManager, transport });
+    servers.add(server);
+})
+    .then((listener) => {
+    process.stderr.write(`[code-shell] automation server listening on ${host}:${listener.port}\n`);
+    const shutdown = () => {
+        automation.stop();
+        for (const s of servers)
+            s.close();
+        void listener.close().then(() => process.exit(0));
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+})
+    .catch((err) => {
+    process.stderr.write(`[code-shell] failed to start automation server: ${String(err)}\n`);
+    process.exit(1);
+});

package/dist/cli/graceful-shutdown.d.ts

@@ -0,0 +1,27 @@
+/** Minimal surface we need from a server to shut it down cleanly. */
+interface Closable {
+    close(): void;
+}
+/** Minimal surface we need from `process` (injectable for tests). */
+interface ProcLike {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    exit(code?: number): void;
+}
+export interface GracefulShutdownOptions {
+    /** Defaults to the real `process`. */
+    proc?: ProcLike;
+    /** Signals to handle. Defaults to SIGTERM, SIGINT, SIGHUP. */
+    signals?: string[];
+}
+/**
+ * Register signal handlers that cleanly shut down a long-lived server before
+ * the process exits. Without this, SIGTERM/SIGINT (Ctrl+C)/SIGHUP terminate
+ * the process immediately, leaking the idle sweeper interval, open sessions,
+ * pending approvals, and child processes (MCP servers, tools).
+ *
+ * Idempotent: the first signal runs close() exactly once; later signals (or a
+ * second handler firing) are ignored. A throwing close() is swallowed so the
+ * process still exits.
+ */
+export declare function installGracefulShutdown(server: Closable, options?: GracefulShutdownOptions): void;
+export {};

package/dist/cli/graceful-shutdown.js

@@ -0,0 +1,30 @@
+/**
+ * Register signal handlers that cleanly shut down a long-lived server before
+ * the process exits. Without this, SIGTERM/SIGINT (Ctrl+C)/SIGHUP terminate
+ * the process immediately, leaking the idle sweeper interval, open sessions,
+ * pending approvals, and child processes (MCP servers, tools).
+ *
+ * Idempotent: the first signal runs close() exactly once; later signals (or a
+ * second handler firing) are ignored. A throwing close() is swallowed so the
+ * process still exits.
+ */
+export function installGracefulShutdown(server, options = {}) {
+    const proc = options.proc ?? globalThis.process;
+    const signals = options.signals ?? ["SIGTERM", "SIGINT", "SIGHUP"];
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            server.close();
+        }
+        catch {
+            // Best-effort cleanup — never block exit on a close() failure.
+        }
+        proc.exit(0);
+    };
+    for (const sig of signals) {
+        proc.on(sig, shutdown);
+    }
+}

package/dist/context/compaction.d.ts

@@ -16,6 +16,25 @@ import type { Message } from "../types.js";
  * Uses per-block-type estimation with 33% overhead padding.
  */
 export declare function estimateTokens(messages: Message[]): number;
+/**
+ * Reconcile user-supplied compaction ratios into a safe ordering.
+ *
+ * The three tiers must satisfy `floor < compact < summarize` or the manager
+ * fires them in the wrong order (e.g. an emergency window-compact before the
+ * cheaper summary). Users edit these freely in settings.json, so we clamp
+ * rather than trust: summarize is pulled up to at least compact, floor is
+ * pushed down to at most compact. Absent fields are left undefined so the
+ * ContextManager keeps its own default for them.
+ */
+export declare function clampContextRatios(input: {
+    compactAtRatio?: number;
+    summarizeAtRatio?: number;
+    microcompactFloorRatio?: number;
+}): {
+    compactAtRatio?: number;
+    summarizeAtRatio?: number;
+    microcompactFloorRatio?: number;
+};
 /**
  * Expand a slice start-index backwards so that every tool_result in the
  * kept range has its corresponding tool_use in the kept range too.
@@ -74,6 +93,43 @@ export interface MicrocompactOptions {
  *    forced into blind re-Reads (which then trip the Investigation guard).
  */
 export declare function microcompact(messages: Message[], options?: MicrocompactOptions): Message[];
+export interface DedupeFileReadsResult {
+    messages: Message[];
+    /** How many stale Read results were cleared. */
+    clearedCount: number;
+}
+/**
+ * Content-aware dedup: when the SAME file is Read more than once, every Read
+ * result except the most recent is stale — the file's current state is in the
+ * latest read. Clear the older ones (replace with a fingerprint pointing at
+ * the newer read) regardless of the recency window or pressure floor, because
+ * this is pure waste removal, not lossy compaction: the model never needs two
+ * copies of the same file.
+ *
+ * Distinct from microcompact (which is recency-gated and pressure-gated): a
+ * file Read 3 times in the last 3 turns keeps 3 full copies under microcompact
+ * but only the newest under this pass. Zero-cost and always safe to run, so the
+ * ContextManager calls it as an early tier.
+ *
+ * Only `Read` is deduped (its result is exactly the file content). Edit/Write
+ * results are diffs/confirmations, not full snapshots, so they're left alone.
+ */
+export declare function dedupeFileReads(messages: Message[]): DedupeFileReadsResult;
+/**
+ * Observation masking for browser_observe(snapshot) results (the research's
+ * highest-leverage browser-token saving: a page snapshot is large and only the
+ * LATEST one matters for the next decision; older ones are stale element lists).
+ * Keep the most recent snapshot result verbatim; replace every earlier one with
+ * a one-line placeholder. Deterministic — no LLM summarization needed.
+ *
+ * Keyed on the snapshot OBSERVATION (browser_observe with mode snapshot) — read/
+ * extract observations and act results are left untouched. Renamed from
+ * maskOldBrowserSnapshots when the 9 browser_* tools collapsed into 3.
+ */
+export declare function maskOldObservations(messages: Message[]): {
+    messages: Message[];
+    maskedCount: number;
+};
 /**
  * Apply aggregate per-message tool result budget.
  * When total tool_result content in a single message exceeds maxTotalChars,