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

package/dist/protocol/server.js

@@ -15,12 +15,30 @@
  */
 import { Methods, ErrorCodes, createResponse, createErrorResponse, createNotification, isRequest, } from "./types.js";
 import { diskDefaultsFrom } from "../engine/engine.js";
+import { isProtectedSettingKey } from "../settings/manager.js";
 import { setInteractiveApprovalFn } from "../tool-system/permission.js";
 import { getArenaStatus } from "../tool-system/builtin/arena.js";
-import { agentNotificationBus } from "../tool-system/builtin/agent-notifications.js";
+import { agentNotificationBus, notificationQueue, buildNotificationMessage, } from "../tool-system/builtin/agent-notifications.js";
+import { backgroundShellManager } from "../runtime/background-shell.js";
+import { backgroundJobRegistry } from "../tool-system/builtin/background-jobs.js";
+import { listBackgroundWorkForUI } from "../tool-system/builtin/background-work.js";
+import { logger } from "../logging/logger.js";
 import { nanoid } from "nanoid";
 import { redactLlmConfig, maskSecretValue } from "./redact.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
+const COMPACT_STREAM_STRATEGIES = new Set([
+    "micro",
+    "summary",
+    "window",
+    "snip",
+    "emergency",
+    "compacted",
+]);
+function toCompactStreamStrategy(strategy) {
+    return COMPACT_STREAM_STRATEGIES.has(strategy)
+        ? strategy
+        : "compacted";
+}
 export class AgentServer {
     chatManager;
     legacyEngine;
@@ -28,6 +46,8 @@ export class AgentServer {
     transport;
     /** Fresh-disk settings reader for config hot-reload; null when not wired. */
     settingsReader;
+    /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
+    readActiveGoalFromDisk;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -64,6 +84,7 @@ export class AgentServer {
         this.chatManager = options.chatManager ?? null;
         this.legacyEngine = options.engine ?? null;
         this.settingsReader = options.settingsReader ?? null;
+        this.readActiveGoalFromDisk = options.readActiveGoalFromDisk ?? null;
         if (!this.chatManager && !this.legacyEngine) {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
@@ -93,15 +114,121 @@ export class AgentServer {
         // B2.2 — forward background sub-agent completion events through the
         // protocol so Desktop / SDK / remote AgentClients see them too. The
         // bus is fed from `NotificationQueue.enqueue`, so this single
-        // subscription covers every enqueue site (today: only agent.ts). The
-        // bus now guarantees a real sessionId (no more legacy-bucket coercion
-        // to ""), so we forward whatever sid it hands us.
+        // subscription covers every enqueue site — background sub-agents
+        // (agent.ts), background shells (background-shell.ts), and video/job
+        // polls (background-jobs.ts). The bus now guarantees a real sessionId
+        // (no more legacy-bucket coercion to ""), so we forward whatever sid it
+        // hands us.
         this.bgAgentBusUnsubscribe = agentNotificationBus.subscribe((sessionId, event) => {
             this.notify(Methods.StreamEvent, { sessionId, event });
+            // Background work that finishes while the session is IDLE (a
+            // run_in_background Bash like a download, a background sub-agent, or a
+            // video poll — the engine no longer parks on any of them) would otherwise
+            // leave its completion sitting in the queue until the user manually sends.
+            // Wake the session with one run carrying the notification so the model
+            // reads "download complete" and continues on its own (the persisted goal
+            // is judged that turn). If the work finishes while a run is still in
+            // flight, the idle guard below skips it and the run-boundary re-check
+            // (trigger B) drains it at end-of-turn instead. A never-exiting dev server
+            // emits no completion, so it never wakes anything (no task/service
+            // classification needed).
+            this.maybeWakeIdleSession(sessionId);
         });
         // Notify client we're ready
         this.notify(Methods.Status, { status: "ready" });
     }
+    /**
+     * Wake an IDLE chatManager session that has pending background-completion
+     * notifications, by enqueueing one turn whose task is the drained
+     * notification(s). The model then sees the completion and continues; the
+     * session's persisted goal (if any) is judged on that turn.
+     *
+     * Guards:
+     * - chatManager path only (the legacy single-engine / headless path drives
+     *   its own loop and has no idle-session-resume concept).
+     * - Session must exist AND be idle. If it's busy, we do nothing: the in-flight
+     *   run's end-of-turn `drainAll` already collects every pending notification,
+     *   so a second run would be redundant — and `enqueueTurn` while busy would
+     *   queue a spurious extra turn.
+     * - We `drainAll` exactly here and feed the items into the woken turn. This
+     *   also merges a burst of near-simultaneous completions into one wakeup:
+     *   the first drains all currently-pending items; subsequent bus events for
+     *   the same session find it busy (or find an empty queue) and no-op.
+     *
+     * INVARIANT (the burst-merge correctness depends on it): the merge only
+     * holds because (a) the bus fans out to subscribers SYNCHRONOUSLY, and (b)
+     * `enqueueTurn` sets the session's `active` (→ isBusy()===true) SYNCHRONOUSLY
+     * before its first await. So when bus events #2..N arrive — still on the same
+     * synchronous fan-out as #1 — they already see the session as busy and no-op.
+     * If either path is ever made async (e.g. an await is added inside
+     * enqueueTurn before `active` is set, or the bus starts deferring delivery),
+     * this degrades into N concurrent wakeups for N completions. Keep both
+     * synchronous, or replace this comment's assumption with an explicit
+     * "wakeup in flight" guard flag.
+     */
+    maybeWakeIdleSession(sessionId) {
+        if (!this.chatManager)
+            return;
+        const session = this.chatManager.get(sessionId);
+        if (!session || session.isBusy())
+            return;
+        // Headless / automation runs are one-shot: the caller takes result.text and
+        // is gone, so there's no consumer for a woken continuation turn. Headless
+        // already drained its background sub-agents inside engine.run before
+        // returning; any remaining queued notification (video/shell) must NOT spin
+        // an orphan turn. Only the interactive path auto-continues.
+        if (session.engine.isHeadless())
+            return;
+        // Don't resurrect a session the user just Stopped: cancel() leaves it idle
+        // (active=null) so isBusy() reads false, but auto-running a fresh turn here
+        // would defeat the Stop. The flag clears the moment the user sends again.
+        if (session.wasCancelledSinceLastTurn())
+            return;
+        const pending = notificationQueue.drainAll(sessionId);
+        if (pending.length === 0)
+            return;
+        const task = `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`;
+        void session
+            .enqueueTurn(task, {
+            // Synthetic notification, not the user's own input: persisted with an
+            // `injected` flag so a disk rebuild doesn't render it as a phantom user
+            // bubble (the live UI shows only the woken assistant's reply).
+            injected: true,
+            onStream: (event) => this.notify(Methods.StreamEvent, { sessionId, event }),
+        })
+            .catch((err) => {
+            // A wakeup turn failing must not crash the bus fan-out. The drained
+            // notifications are already in the transcript via the run's messages;
+            // log and move on.
+            logger.warn("bg_wakeup.turn_failed", {
+                sessionId,
+                error: err.message,
+            });
+            // Belt-and-braces, mirroring the send() path's run().then(clear-busy):
+            // the renderer set the composer "working" spinner on this run's
+            // session_started, and clears it on turn_complete/error. A failure
+            // BEFORE the turn-loop runs (e.g. a setup error) emits neither, which
+            // would leave the spinner stuck. Emit a terminal `error` (NOT a
+            // turn_complete) so the renderer clears busy AND a woken automation
+            // session's runStatus flips to "failed" rather than being mislabeled
+            // "completed". If the turn-loop already emitted its own `error`, this is
+            // a harmless duplicate (busy already cleared, status already failed).
+            this.notify(Methods.StreamEvent, {
+                sessionId,
+                event: { type: "error", error: err?.message ?? "background wakeup failed" },
+            });
+        })
+            .finally(() => {
+            // Run-boundary re-check (trigger B): the woken summarize turn may have
+            // spawned NEW background work (e.g. goal "generate 2 videos" → after #1
+            // completes, this turn submits #2). When #2 finishes its notification
+            // arrives while we're idle again — but if it arrived DURING this turn
+            // (busy), trigger A skipped it. Re-checking at the run boundary drains
+            // anything that landed while busy, chaining wakeups until the queue is
+            // truly empty. Replaces the old engine for(;;) outer loop.
+            this.maybeWakeIdleSession(sessionId);
+        });
+    }
     // ─── Request Dispatch ───────────────────────────────────────────
     async handleRequest(req) {
         switch (req.method) {
@@ -123,9 +250,30 @@ export class AgentServer {
             case Methods.Inject:
                 this.handleInject(req);
                 break;
+            case Methods.Steer:
+                this.handleSteer(req);
+                break;
+            case Methods.Unsteer:
+                this.handleUnsteer(req);
+                break;
             case Methods.CloseSession:
                 this.handleCloseSession(req);
                 break;
+            case Methods.GoalExtend:
+                this.handleGoalExtend(req);
+                break;
+            case Methods.GoalClear:
+                this.handleGoalClear(req);
+                break;
+            case Methods.GoalGet:
+                this.handleGoalGet(req);
+                break;
+            case Methods.BackgroundShells:
+                this.handleBackgroundShells(req);
+                break;
+            case Methods.BackgroundWork:
+                this.handleBackgroundWork(req);
+                break;
             default:
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.MethodNotFound, `Unknown method: ${req.method}`));
         }
@@ -155,6 +303,7 @@ export class AgentServer {
             session = cm.getOrCreate(params.sessionId, {
                 permissionMode: params.permissionMode,
                 cwd: params.cwd,
+                projectTrusted: params.projectTrusted,
             });
         }
         catch (err) {
@@ -162,6 +311,28 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, code, err.message));
             return;
         }
+        // `requireExisting`: reject if the target session isn't on disk rather than
+        // running the prompt against a freshly-created blank session. A cron
+        // "continue this conversation" job whose session the user deleted must fail
+        // loudly here (SessionNotFound) so the scheduler can auto-disable it,
+        // instead of silently executing with no transcript/goal/context.
+        if (params.requireExisting === true && !session.engine.sessionExistsOnDisk(params.sessionId)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `session ${params.sessionId} does not exist`));
+            return;
+        }
+        if (params.model !== undefined) {
+            if (typeof params.model !== "string" || params.model.length === 0) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "model must be a non-empty string"));
+                return;
+            }
+            try {
+                session.requestModelSwitch(params.model);
+            }
+            catch (err) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                return;
+            }
+        }
         if (typeof params.planMode === "boolean") {
             session.engine.setPlanMode(params.planMode);
         }
@@ -176,6 +347,15 @@ export class AgentServer {
         // headless engines (no human to answer).
         if (!session.engine.isHeadless()) {
             session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
+            // Browser automation bridge: each method routes a browser action to the
+            // client (Electron main drives the webview via CDP) over the SAME
+            // request/response channel as askUser (pendingApprovals + requestId).
+            // Browser actions still keep their own bounded timeout; AskUserQuestion
+            // waits for a real answer or Stop/cancel.
+            session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
+            // Cookie→browser injection (InjectCredential tool): same cross-process
+            // channel; main restores the cookie jar into the built-in browser.
+            session.engine.setInjectCredential((credentialId) => this.requestCredentialInjectForSession(session, sid, credentialId));
         }
         try {
             const result = await session.enqueueTurn(params.task, {
@@ -185,6 +365,7 @@ export class AgentServer {
                     ? params.goal
                     : undefined,
                 onStream: (event) => this.notify(Methods.StreamEvent, { sessionId: sid, event }),
+                clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
             });
             const runResult = {
                 text: result.text,
@@ -194,9 +375,18 @@ export class AgentServer {
                 usage: result.usage,
             };
             this.transport.send(createResponse(req.id, runResult));
+            // Run-boundary re-check (trigger B): the session is idle now. If a
+            // background task (shell/video) completed DURING this run, its bus event
+            // fired while we were busy and trigger A skipped it — drain it now and
+            // wake a continuation turn. Interactive path only; headless already
+            // drained its sub-agents inside engine.run before returning.
+            this.maybeWakeIdleSession(sid);
         }
         catch (err) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+            // Even on a failed run the session goes idle — re-check so a background
+            // completion that landed during the failed run isn't orphaned.
+            this.maybeWakeIdleSession(sid);
         }
     }
     async handleRunLegacy(req) {
@@ -224,6 +414,19 @@ export class AgentServer {
             // Engine.setPermissionMode now keeps this.permissionMode + this.planMode
             // in sync and tools read them via ToolContext.permissionMode/planMode.
         }
+        if (params.model !== undefined) {
+            if (typeof params.model !== "string" || params.model.length === 0) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "model must be a non-empty string"));
+                return;
+            }
+            try {
+                this.legacyEngine.switchModel(params.model);
+            }
+            catch (err) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                return;
+            }
+        }
         this.running = true;
         this.abortController = new AbortController();
         this.notify(Methods.Status, { status: "running" });
@@ -242,6 +445,7 @@ export class AgentServer {
                 sessionId: params.sessionId,
                 signal: runController.signal,
                 onStream: streamToClient,
+                clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
                 goal: typeof params.goal === "string" ||
                     (params.goal != null && typeof params.goal === "object")
                     ? params.goal
@@ -289,7 +493,10 @@ export class AgentServer {
     // ─── Approve ────────────────────────────────────────────────────
     handleApprove(req) {
         const params = (req.params ?? {});
-        // ChatSessionManager path: look up per-session pendingApprovals
+        // ChatSessionManager path: approvals are scoped by (sessionId, requestId).
+        // Never fall back from a session-tagged response to the legacy global map:
+        // a stale/misrouted UI response must fail closed instead of resolving a
+        // pending prompt from another session.
         if (this.chatManager && typeof params.sessionId === "string") {
             const s = this.chatManager.get(params.sessionId);
             if (!s) {
@@ -298,10 +505,14 @@ export class AgentServer {
             }
             const resolve = s.pendingApprovals.get(params.requestId);
             if (!resolve) {
-                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval: ${params.requestId}`));
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval for session ${params.sessionId}: ${params.requestId}`));
                 return;
             }
             s.pendingApprovals.delete(params.requestId);
+            // Cancel the pending timeout for requests that arm one (browser actions,
+            // credential injection, and tool approvals). AskUserQuestion does not use
+            // a timeout; this is harmless for those request ids.
+            this.clearApprovalTimer(params.requestId);
             resolve(params.decision);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
@@ -332,6 +543,13 @@ export class AgentServer {
                 return;
             }
             s.cancel();
+            // s.cancel() only aborts the engine controller + drains queued turns. The
+            // session's pendingApprovals (askUser / browser_action / tool approvals)
+            // are NOT driven directly by the abort signal. Left alone, an awaiting
+            // AskUserQuestion would now wait forever, while bounded request types
+            // would wait until APPROVAL_TIMEOUT_MS. Resolve them as cancelled now and
+            // clear any matching timers, mirroring the legacy path below.
+            this.cancelSessionApprovals(s);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
         }
@@ -348,6 +566,163 @@ export class AgentServer {
         this.clearAllApprovalTimers();
         this.transport.send(createResponse(req.id, { ok: true }));
     }
+    /**
+     * Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). Routed to
+     * a specific session (multi-session path). Returns the resulting effective
+     * limits, or an error if no session / no active run.
+     */
+    handleGoalExtend(req) {
+        const params = (req.params ?? {});
+        const ext = {
+            addTurns: params.addTurns,
+            addTokenBudget: params.addTokenBudget,
+            addTimeBudgetMs: params.addTimeBudgetMs,
+            addStopBlocks: params.addStopBlocks,
+        };
+        // Multi-session path: route to the named session.
+        const session = this.chatManager && typeof params.sessionId === "string"
+            ? this.chatManager.get(params.sessionId)
+            : undefined;
+        // Legacy single-engine path (no chatManager): extend the one engine's run,
+        // mirroring handleCancel which also supports both paths. Without this a
+        // legacy host can cancel but never extend a goal.
+        const result = session
+            ? session.extendGoalRun(ext)
+            : this.legacyEngine
+                ? this.legacyEngine.extendGoalRun(ext)
+                : undefined;
+        if (result === undefined) {
+            // Couldn't even resolve a target (no session and no legacy engine).
+            if (!session && !this.legacyEngine) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, params.sessionId ? `No such session: ${params.sessionId}` : "sessionId is required"));
+                return;
+            }
+        }
+        if (!result) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "No active run to extend"));
+            return;
+        }
+        this.transport.send(createResponse(req.id, { ok: true, limits: result }));
+    }
+    /**
+     * Clear a session's persisted active goal (CC /goal clear). Routes to the
+     * named session, falling back to the legacy single engine (mirrors
+     * handleGoalExtend / handleCancel's dual path). Returns { ok, cleared }.
+     */
+    handleGoalClear(req) {
+        const params = (req.params ?? {});
+        const session = this.chatManager && typeof params.sessionId === "string"
+            ? this.chatManager.get(params.sessionId)
+            : undefined;
+        if (!session && !this.legacyEngine) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, params.sessionId ? `No such session: ${params.sessionId}` : "sessionId is required"));
+            return;
+        }
+        const cleared = session
+            ? session.clearGoal()
+            : params.sessionId
+                ? (this.legacyEngine.clearGoal(params.sessionId) ?? false)
+                : false;
+        this.transport.send(createResponse(req.id, { ok: true, cleared }));
+    }
+    /**
+     * Read a session's persisted active goal so the host can re-surface the goal
+     * block + Cancel button on session load. A persistent goal lives only in
+     * state.activeGoal and is never replayed from the transcript, so a reloaded
+     * (or disk-rebuilt) session has no other way to learn it. Prefers a live
+     * chatManager session, else falls through to a disk read (readActiveGoalFromDisk
+     * in worker mode, or the legacy engine's disk read in single-engine mode) — the
+     * bug case is an aborted/reloaded session that is NOT live. Returns { ok, goal } where goal
+     * is the objective string, or null when there's no goal / unknown session.
+     * Never errors on "no goal" — null is the normal "nothing to show" answer.
+     */
+    handleGoalGet(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || !params.sessionId) {
+            // Missing/empty param is InvalidParams, not SessionClosed (no session was
+            // ever named) — matches handleSteer/handleUnsteer/handleBackgroundShells.
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        // Prefer the live session; otherwise read straight off disk. The goal we
+        // want to recover belongs to a session that is, by definition of this bug,
+        // usually NOT currently live: reopening after restart doesn't create a
+        // ChatSession (that only happens on a send), so chatManager.get() misses.
+        // In worker (chatManager) mode there is no legacyEngine, so the disk read
+        // MUST come from readActiveGoalFromDisk — relying on legacyEngine there
+        // silently returned null and the UI goal block never re-surfaced.
+        const live = this.chatManager ? this.chatManager.get(params.sessionId) : undefined;
+        const goal = live
+            ? live.getGoal()
+            : (this.readActiveGoalFromDisk?.(params.sessionId) ??
+                this.legacyEngine?.getGoal(params.sessionId) ??
+                undefined);
+        this.transport.send(createResponse(req.id, { ok: true, goal: goal ? goal.objective : null }));
+    }
+    /**
+     * Query/control a session's background shells for the desktop UI panel (TODO
+     * 3.2). Reads the singleton BackgroundShellManager directly (shells outlive
+     * the run that spawned them, so we don't need a live ChatSession). Actions:
+     *   - (default) list  → the session's shells
+     *   - output          → full retained output of one shell
+     *   - kill            → terminate one shell's process group
+     * All scoped by sessionId (manager enforces ownership on output/kill).
+     */
+    handleBackgroundShells(req) {
+        const params = (req.params ?? {});
+        const sessionId = params.sessionId;
+        if (typeof sessionId !== "string" || !sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        const action = params.action ?? "list";
+        if (action === "list") {
+            const shells = backgroundShellManager.listForSession(sessionId);
+            this.transport.send(createResponse(req.id, { shells }));
+            return;
+        }
+        if (!params.shellId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "shellId is required"));
+            return;
+        }
+        if (action === "output") {
+            const res = backgroundShellManager.readOutput(params.shellId, "all", sessionId);
+            if (!res.ok) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, res.error));
+                return;
+            }
+            this.transport.send(createResponse(req.id, { header: res.header, text: res.text }));
+            return;
+        }
+        if (action === "kill") {
+            void backgroundShellManager.kill(params.shellId, sessionId).then((res) => {
+                if (!res.ok) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, res.error));
+                }
+                else {
+                    this.transport.send(createResponse(req.id, { ok: true }));
+                }
+            });
+            return;
+        }
+        this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `unknown action: ${action}`));
+    }
+    /**
+     * BackgroundWork — unified, list-only view of a session's background work
+     * across all three registries (shells + sub-agents + jobs) for the desktop
+     * background panel. Per-shell output/kill still flow through BackgroundShells
+     * (by shellId); this just answers "what's running in the background right now".
+     */
+    handleBackgroundWork(req) {
+        const params = (req.params ?? {});
+        const sessionId = params.sessionId;
+        if (typeof sessionId !== "string" || !sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        const items = listBackgroundWorkForUI(sessionId);
+        this.transport.send(createResponse(req.id, { items }));
+    }
     // ─── CloseSession ───────────────────────────────────────────────
     handleCloseSession(req) {
         const params = (req.params ?? {});
@@ -356,8 +731,20 @@ export class AgentServer {
             return;
         }
         if (this.chatManager) {
+            const session = this.chatManager.get(params.sessionId);
+            if (session) {
+                this.cancelSessionApprovals(session, "session closed");
+            }
             this.chatManager.close(params.sessionId);
         }
+        // Explicit session teardown — reap that session's background shells
+        // (design §6 "session 被显式删除 → killSession"). This is the RPC path
+        // (agent/closeSession from the host on delete), distinct from the idle
+        // sweeper's chatManager.close() which must NOT kill (§6). Fire-and-forget.
+        void backgroundShellManager.killSession(params.sessionId);
+        // Drop this session's retained background jobs too (#2/#5): finished jobs
+        // are kept for the panel, so explicit teardown is where they're released.
+        backgroundJobRegistry.dropForSession(params.sessionId);
         this.transport.send(createResponse(req.id, { ok: true }));
     }
     // ─── Configure ──────────────────────────────────────────────────
@@ -368,7 +755,11 @@ export class AgentServer {
             const sid = params.sessionId;
             const s = this.chatManager.get(sid);
             if (!s) {
-                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `No such session: ${sid}`));
+                // Session not found (already cleaned by idle sweeper, or never created).
+                // Don't create one just for configure — let the subsequent run() do it
+                // with proper per-session config. Return OK since there's nothing to
+                // configure on a non-existent session.
+                this.transport.send(createResponse(req.id, { ok: true }));
                 return;
             }
             if (typeof params.planMode === "boolean")
@@ -376,13 +767,32 @@ export class AgentServer {
             if (typeof params.permissionMode === "string") {
                 s.engine.setPermissionMode(params.permissionMode);
             }
+            if (params.clearModels) {
+                this.chatManager.runtime.clearModels();
+            }
+            if (params.reloadModels) {
+                try {
+                    this.chatManager.runtime.reloadModelsFromSettings();
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+                    return;
+                }
+            }
             // Per-session model switch — the missing piece that made model changes
             // worker-global (session-isolation research §3). requestModelSwitch
             // applies immediately when idle, defers to the run boundary when busy
             // so it never swaps the model under a running LLM client.
             if (typeof params.model === "string") {
                 try {
-                    s.requestModelSwitch(params.model);
+                    const entry = s.requestModelSwitch(params.model);
+                    this.transport.send(createResponse(req.id, {
+                        ok: true,
+                        model: entry.model,
+                        key: entry.key,
+                        maxContextTokens: entry.maxContextTokens,
+                    }));
+                    return;
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
@@ -397,7 +807,7 @@ export class AgentServer {
                 }
                 const settings = this.settingsReader();
                 const version = ++this.configVersion;
-                s.engine.refreshRuntimeConfig(diskDefaultsFrom(settings), version);
+                s.engine.refreshRuntimeConfig(diskDefaultsFrom(settings, s.engine.getEffectiveDisabledLists().disabledPlugins), version);
             }
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
@@ -405,9 +815,33 @@ export class AgentServer {
         // Global configure — delegate to legacyEngine if available,
         // or to any session's engine from chatManager for settings ops
         const engine = this.legacyEngine ?? this.anyEngine();
-        if (params.reloadModels && engine) {
+        if (params.clearModels) {
+            if (this.chatManager) {
+                this.chatManager.runtime.clearModels();
+            }
+            else {
+                this.legacyEngine?.getModelPool().clear();
+                this.globalQueryEngine?.getModelPool().clear();
+            }
+        }
+        if (params.reloadModels) {
             try {
-                engine.reloadModelPool();
+                if (this.chatManager) {
+                    this.chatManager.runtime.reloadModelsFromSettings();
+                }
+                else {
+                    const seen = new Set();
+                    const reload = (target) => {
+                        if (!target || seen.has(target))
+                            return;
+                        seen.add(target);
+                        target.reloadModelPool();
+                    };
+                    reload(this.legacyEngine);
+                    reload(this.globalQueryEngine);
+                    if (seen.size === 0)
+                        reload(engine);
+                }
             }
             catch (err) {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -417,7 +851,12 @@ export class AgentServer {
         if (params.model !== undefined && engine) {
             try {
                 const entry = engine.switchModel(params.model);
-                this.transport.send(createResponse(req.id, { ok: true, model: entry.model, key: entry.key }));
+                this.transport.send(createResponse(req.id, {
+                    ok: true,
+                    model: entry.model,
+                    key: entry.key,
+                    maxContextTokens: entry.maxContextTokens,
+                }));
                 return;
             }
             catch (err) {
@@ -445,23 +884,29 @@ export class AgentServer {
                 // Mirrors how reloadModels/model/planMode above act on `engine`.
                 if (engine) {
                     const settings = this.settingsReader();
-                    engine.refreshRuntimeConfig(diskDefaultsFrom(settings), ++this.configVersion);
+                    engine.refreshRuntimeConfig(diskDefaultsFrom(settings, engine.getEffectiveDisabledLists().disabledPlugins), ++this.configVersion);
                 }
                 this.transport.send(createResponse(req.id, { ok: true }));
                 return;
             }
             const settings = this.settingsReader();
-            const patch = diskDefaultsFrom(settings);
-            // #6: content short-circuit. If the disk-default patch is byte-identical
-            // to the last one we broadcast, the disk config that matters to running
-            // sessions hasn't changed — skip the whole forEachSession (and the per-
-            // session reloadHooks churn it triggers). Still return ok; a genuine
-            // change differs in JSON and propagates normally.
-            const patchJson = JSON.stringify(patch);
+            // The MCP merge folds each session's PROJECT capabilityOverrides (a
+            // project-level "on" must override the global disabledPlugins), so the
+            // patch is cwd-dependent — compute it per session, not once.
+            const perSession = [];
+            this.chatManager.forEachSession((s) => {
+                const patch = diskDefaultsFrom(settings, s.engine.getEffectiveDisabledLists().disabledPlugins);
+                perSession.push({ apply: (v) => s.engine.refreshRuntimeConfig(patch, v), patch });
+            });
+            // #6: content short-circuit — now keyed on ALL per-session patches, so a
+            // change visible to only one session (e.g. its project's overrides)
+            // still propagates while a true no-op skips the reloadHooks churn.
+            const patchJson = JSON.stringify(perSession.map((p) => p.patch));
             if (patchJson !== this.lastBroadcastPatch) {
                 this.lastBroadcastPatch = patchJson;
                 const version = ++this.configVersion;
-                this.chatManager.forEachSession((s) => s.engine.refreshRuntimeConfig(patch, version));
+                for (const p of perSession)
+                    p.apply(version);
             }
         }
         this.transport.send(createResponse(req.id, { ok: true }));
@@ -528,6 +973,11 @@ export class AgentServer {
                         // apiKey is redacted at this boundary: clients only get
                         // hasApiKey + optional apiKeyPreview. See protocol/redact.ts.
                         llm: redactLlmConfig(config.llm),
+                        // Resolved feature flags (defaults merged with settings overlay)
+                        // so the /features command can list current state.
+                        featureFlags: engine.getFeatureFlags(),
+                        // Effective permission rules so /permissions can list them (TODO 5.1).
+                        permissionRules: engine.getPermissionRules(),
                     },
                 }));
                 break;
@@ -556,12 +1006,53 @@ export class AgentServer {
                 break;
             }
             case "compact": {
-                if (!engine) {
+                const compactSessionId = typeof params.sessionId === "string" && params.sessionId.length > 0
+                    ? params.sessionId
+                    : undefined;
+                let compactEngine = engine;
+                if (this.chatManager) {
+                    if (compactSessionId) {
+                        let session = this.chatManager.get(compactSessionId);
+                        if (!session) {
+                            const probeEngine = this.anyEngine();
+                            if (!probeEngine?.sessionExistsOnDisk(compactSessionId)) {
+                                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `Session not found: ${compactSessionId}`));
+                                return;
+                            }
+                            try {
+                                session = this.chatManager.getOrCreate(compactSessionId, {
+                                    cwd: probeEngine.getSessionManager().readCwd(compactSessionId),
+                                });
+                            }
+                            catch (err) {
+                                this.transport.send(createErrorResponse(req.id, err.code ?? ErrorCodes.InternalError, err.message));
+                                return;
+                            }
+                        }
+                        compactEngine = session.engine;
+                    }
+                    else {
+                        compactEngine = this.anyEngine();
+                    }
+                }
+                if (!compactEngine) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for compact query"));
                     return;
                 }
                 try {
-                    const result = engine.forceCompact();
+                    const result = await compactEngine.forceCompact(compactSessionId);
+                    if (result.before > result.after) {
+                        const event = {
+                            type: "context_compact",
+                            strategy: toCompactStreamStrategy(result.strategy),
+                            before: result.before,
+                            after: result.after,
+                        };
+                        this.notify(Methods.StreamEvent, {
+                            sessionId: compactSessionId ?? "",
+                            event,
+                        });
+                    }
                     this.transport.send(createResponse(req.id, {
                         type: "compact",
                         data: result,
@@ -654,6 +1145,15 @@ export class AgentServer {
                     const { key, value } = params;
                     if (!key)
                         throw new Error("key is required for config_set");
+                    // Refuse writes to trust-root fields via the generic config path. A
+                    // protocol peer (external driver, paired phone, compromised renderer)
+                    // could otherwise self-authorize tools or inject env/hooks/MCP servers,
+                    // which is equivalent to remotely bypassing workspace trust. Legit
+                    // writes to these go through the dedicated settings UI, not config_set;
+                    // provider/model edits use provider_add / models handlers below.
+                    if (isProtectedSettingKey(key)) {
+                        throw new Error(`config_set refused: "${key}" is a protected trust/permission field and cannot be written through this path.`);
+                    }
                     engine.updateConfig(key, value);
                     // Echo back through the same secret-aware masker as config_get so
                     // a `config_set("llm.apiKey", "...")` confirmation doesn't ship
@@ -861,6 +1361,55 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
         }
     }
+    // ─── Steer ──────────────────────────────────────────────────────
+    // Queue a user message into the in-flight run's turn loop (不打断). Unlike
+    // Inject (appends an assistant context msg for the NEXT run), Steer feeds a
+    // user message to the CURRENT run's next step. No abort, no LLM trigger by
+    // itself — the running loop picks it up at its next step boundary.
+    handleSteer(req) {
+        const params = (req.params ?? {});
+        if (!params.text || !params.sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "text and sessionId required"));
+            return;
+        }
+        const engine = this.chatManager
+            ? this.chatManager.get(params.sessionId)?.engine
+            : this.legacyEngine;
+        if (!engine) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `No such session: ${params.sessionId}`));
+            return;
+        }
+        try {
+            const result = engine.enqueueSteer(params.sessionId, params.text, params.id, params.clientMessageId);
+            this.transport.send(createResponse(req.id, { ok: true, ...result }));
+        }
+        catch (err) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+        }
+    }
+    handleUnsteer(req) {
+        const params = (req.params ?? {});
+        if (!params.id || !params.sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "id and sessionId required"));
+            return;
+        }
+        const engine = this.chatManager
+            ? this.chatManager.get(params.sessionId)?.engine
+            : this.legacyEngine;
+        if (!engine) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `No such session: ${params.sessionId}`));
+            return;
+        }
+        try {
+            // removed=false means the loop already consumed it — not an error, the
+            // host just learns it couldn't be revoked (it will arrive as a bubble).
+            const removed = engine.unsteer(params.sessionId, params.id);
+            this.transport.send(createResponse(req.id, { ok: true, removed }));
+        }
+        catch (err) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+        }
+    }
     // ─── Client Communication ───────────────────────────────────────
     /**
      * Ask the client to approve a tool operation (legacy single-engine path).
@@ -868,27 +1417,42 @@ export class AgentServer {
     requestApprovalFromClient(request) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
-            this.pendingApprovals.set(requestId, resolve);
+            const sessionId = typeof request.sessionId === "string" ? request.sessionId : undefined;
+            const session = this.chatManager && sessionId ? this.chatManager.get(sessionId) : undefined;
+            if (this.chatManager && sessionId && !session) {
+                resolve({ approved: false, reason: `session closed: ${sessionId}` });
+                return;
+            }
+            if (session) {
+                session.pendingApprovals.set(requestId, (decision) => {
+                    resolve(decision);
+                });
+            }
+            else {
+                this.pendingApprovals.set(requestId, resolve);
+            }
             const timer = setTimeout(() => {
-                if (this.pendingApprovals.has(requestId)) {
-                    this.pendingApprovals.delete(requestId);
+                const pending = session?.pendingApprovals ?? this.pendingApprovals;
+                if (pending.has(requestId)) {
+                    pending.delete(requestId);
                     this.approvalTimers.delete(requestId);
                     resolve({ approved: false, reason: "approval timed out" });
                 }
             }, AgentServer.APPROVAL_TIMEOUT_MS);
             this.approvalTimers.set(requestId, timer);
-            this.notify(Methods.ApprovalRequest, { requestId, request });
+            this.notify(Methods.ApprovalRequest, {
+                ...(sessionId ? { sessionId } : {}),
+                requestId,
+                request,
+            });
         });
     }
     /**
-     * Ask the client to answer a question from the agent (legacy single-engine path).
-     */
-    /**
-     * Per-session AskUserQuestion for the chatManager path. Mirrors
-     * requestAskUserFromClient but resolves via the SESSION's pendingApprovals
-     * (the chatManager approve handler looks there, keyed by sessionId+requestId)
-     * and tags the notify with sessionId so the renderer routes the question to
-     * the right chat tab.
+     * Per-session AskUserQuestion for the chatManager path. Resolves via the
+     * SESSION's pendingApprovals (the chatManager approve handler looks there,
+     * keyed by sessionId+requestId) and tags the notify with sessionId so the
+     * renderer routes the question to the right chat tab. This intentionally has
+     * no wall-clock timeout; Stop/cancel drains the pending ask.
      */
     requestAskUserForSession(session, sessionId, question, opts) {
         return new Promise((resolve) => {
@@ -904,14 +1468,6 @@ export class AgentServer {
                     resolve(typeof decision === "string" ? decision : "");
                 }
             });
-            const timer = setTimeout(() => {
-                if (session.pendingApprovals.has(requestId)) {
-                    session.pendingApprovals.delete(requestId);
-                    this.approvalTimers.delete(requestId);
-                    resolve("(approval timed out)");
-                }
-            }, AgentServer.APPROVAL_TIMEOUT_MS);
-            this.approvalTimers.set(requestId, timer);
             const args = { question };
             if (opts?.header !== undefined)
                 args.header = opts.header;
@@ -919,6 +1475,8 @@ export class AgentServer {
                 args.options = opts.options;
             if (opts?.multiSelect !== undefined)
                 args.multiSelect = opts.multiSelect;
+            if (opts?.optionsOnly !== undefined)
+                args.optionsOnly = opts.optionsOnly;
             this.notify(Methods.ApprovalRequest, {
                 sessionId,
                 requestId,
@@ -931,6 +1489,134 @@ export class AgentServer {
             });
         });
     }
+    /**
+     * Build a BrowserBridge whose every method routes a browser action to the
+     * client over the session's pendingApprovals channel (same as askUser). The
+     * client (Electron main) drives the webview via CDP and replies with a JSON
+     * result string we parse back into the typed result. On timeout / malformed
+     * reply we degrade to a safe error result rather than throwing.
+     */
+    makeBrowserBridge(session, sessionId) {
+        const call = (action, payload) => this.requestBrowserActionForSession(session, sessionId, action, payload);
+        return {
+            snapshot: () => call("snapshot", {}),
+            click: (ref) => call("click", { ref }),
+            type: (ref, text) => call("type", { ref, text }),
+            navigate: (url) => call("navigate", { url }),
+            scroll: (dir, amount) => call("scroll", { dir, amount }),
+            readContent: () => call("readContent", {}),
+            extractLinks: () => call("extractLinks", {}),
+            waitForLoad: (timeoutMs) => call("waitForLoad", { timeoutMs }),
+            hover: (ref) => call("hover", { ref }),
+            selectOption: (ref, value) => call("selectOption", { ref, value }),
+            pressKey: (key, ref) => call("pressKey", { key, ref }),
+            fetchImages: (refs) => call("fetchImages", { refs }),
+            screenshot: (ref) => call("screenshot", { ref }),
+            listTabs: () => call("listTabs", {}),
+            switchTab: (tabId) => call("switchTab", { tabId }),
+        };
+    }
+    requestBrowserActionForSession(session, sessionId, action, payload) {
+        return new Promise((resolve) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                // Main replies with { approved:true, answer:<json string> } (reusing the
+                // ApprovalResult shape) or a raw json string. Parse → typed result.
+                let raw;
+                if (decision && typeof decision === "object" && "approved" in decision) {
+                    const r = decision;
+                    raw = r.approved ? r.answer : undefined;
+                }
+                else if (typeof decision === "string") {
+                    raw = decision;
+                }
+                if (raw === undefined) {
+                    resolve({ ok: false, detail: "browser action declined or unavailable" });
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch {
+                    resolve({ ok: false, detail: "malformed browser action result" });
+                }
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    session.pendingApprovals.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    resolve({ ok: false, detail: "browser action timed out" });
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            this.notify(Methods.ApprovalRequest, {
+                sessionId,
+                requestId,
+                request: {
+                    toolName: "__browser_action__",
+                    args: { action, ...payload },
+                    description: `browser:${action}`,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
+    /**
+     * Ask the client (Electron main) to inject a cookie credential into the
+     * built-in browser. Same pendingApprovals channel as browser actions; main
+     * calls restoreCookiesToBrowser and replies with a JSON result string we
+     * parse into { ok, count?, error? }. Degrades to ok:false on timeout/malformed.
+     */
+    requestCredentialInjectForSession(session, sessionId, credentialId) {
+        return new Promise((resolve) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                let raw;
+                if (decision && typeof decision === "object" && "approved" in decision) {
+                    const r = decision;
+                    raw = r.approved ? r.answer : undefined;
+                }
+                else if (typeof decision === "string") {
+                    raw = decision;
+                }
+                if (raw === undefined) {
+                    resolve({ ok: false, error: "credential inject declined or unavailable" });
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch {
+                    resolve({ ok: false, error: "malformed credential inject result" });
+                }
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    session.pendingApprovals.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    resolve({ ok: false, error: "credential inject timed out" });
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            this.notify(Methods.ApprovalRequest, {
+                sessionId,
+                requestId,
+                request: {
+                    toolName: "__credential_action__",
+                    args: { action: "injectCookie", credentialId },
+                    description: `credential:inject:${credentialId}`,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
+    /**
+     * Ask the client to answer a question from the agent (legacy single-engine
+     * path). This intentionally has no wall-clock timeout; Stop/cancel drains
+     * the pending ask.
+     */
     requestAskUserFromClient(question, opts) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
@@ -943,14 +1629,6 @@ export class AgentServer {
                     resolve(result.reason ?? "(user declined to answer)");
                 }
             });
-            const timer = setTimeout(() => {
-                if (this.pendingApprovals.has(requestId)) {
-                    this.pendingApprovals.delete(requestId);
-                    this.approvalTimers.delete(requestId);
-                    resolve("(approval timed out)");
-                }
-            }, AgentServer.APPROVAL_TIMEOUT_MS);
-            this.approvalTimers.set(requestId, timer);
             const args = { question };
             if (opts?.header !== undefined)
                 args.header = opts.header;
@@ -958,6 +1636,8 @@ export class AgentServer {
                 args.options = opts.options;
             if (opts?.multiSelect !== undefined)
                 args.multiSelect = opts.multiSelect;
+            if (opts?.optionsOnly !== undefined)
+                args.optionsOnly = opts.optionsOnly;
             this.notify(Methods.ApprovalRequest, {
                 requestId,
                 request: {
@@ -1010,6 +1690,9 @@ export class AgentServer {
             this.bgAgentBusUnsubscribe = null;
         }
         if (this.chatManager) {
+            this.chatManager.forEachSession((session) => {
+                this.cancelSessionApprovals(session, "server closing");
+            });
             this.chatManager.closeAll();
         }
         // Legacy path cleanup
@@ -1036,6 +1719,25 @@ export class AgentServer {
             this.approvalTimers.delete(requestId);
         }
     }
+    /**
+     * Resolve all of a chat session's pending approvals as cancelled and clear
+     * any matching server-side approval timers. Used by handleCancel's
+     * per-session path so a Stop while a tool is awaiting approval doesn't leave
+     * the tool hanging. Bounded request types have same-keyed timer entries;
+     * AskUserQuestion does not.
+     */
+    cancelSessionApprovals(session, reason = "cancelled") {
+        for (const [requestId, resolve] of session.pendingApprovals) {
+            this.clearApprovalTimer(requestId);
+            try {
+                resolve({ approved: false, reason });
+            }
+            catch {
+                /* a resolver must never break cancel cleanup */
+            }
+        }
+        session.pendingApprovals.clear();
+    }
     clearAllApprovalTimers() {
         for (const timer of this.approvalTimers.values()) {
             clearTimeout(timer);