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

package/dist/protocol/server.js

@@ -14,14 +14,43 @@
  * falls back to borrowing any live session's engine for those reads.
  */
 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";
 export class AgentServer {
     chatManager;
     legacyEngine;
+    globalQueryEngine = null;
     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).
+     */
+    configVersion = 0;
+    /**
+     * JSON of the last disk-default patch broadcast to ALL live sessions (#6).
+     * When a new reloadSettings request produces a byte-identical patch we SKIP
+     * the entire forEachSession broadcast — every session's refreshRuntimeConfig
+     * would otherwise unconditionally reloadHooks() (invalidate + full disk
+     * re-read + hook teardown/re-register) per call, and the personalization UI
+     * auto-saves on a 600ms debounce, so identical re-saves caused K× hook churn
+     * per keystroke-pause. A genuine change still differs in JSON → propagates.
+     * null until the first broadcast.
+     */
+    lastBroadcastPatch = null;
     // ── Legacy single-engine state (used when chatManager is null) ──
     running = false;
     abortController = null;
@@ -41,6 +70,8 @@ export class AgentServer {
     constructor(options) {
         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");
         }
@@ -53,29 +84,138 @@ export class AgentServer {
                 });
             }
         });
-        // Wire approval flow for the legacy single-engine path.
-        // In the chatManager path approval flows are per-session and registered
-        // when the session's engine raises an approval request via onStream.
+        setInteractiveApprovalFn((request) => {
+            return this.requestApprovalFromClient(request);
+        });
         if (this.legacyEngine) {
-            setInteractiveApprovalFn((request) => {
-                return this.requestApprovalFromClient(request);
-            });
-            this.legacyEngine.setAskUser((question, opts) => {
-                return this.requestAskUserFromClient(question, opts);
-            });
+            // Only wire an interactive askUser when a human is present. For
+            // unattended (headless) runs we leave askUser undefined so
+            // AskUserQuestion hits its headless-error branch and returns immediately
+            // instead of suspending until the tool-exec timeout (~300s).
+            if (!this.legacyEngine.isHeadless()) {
+                this.legacyEngine.setAskUser((question, opts) => {
+                    return this.requestAskUserFromClient(question, opts);
+                });
+            }
         }
         // 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) {
@@ -97,9 +237,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}`));
         }
@@ -129,6 +290,7 @@ export class AgentServer {
             session = cm.getOrCreate(params.sessionId, {
                 permissionMode: params.permissionMode,
                 cwd: params.cwd,
+                projectTrusted: params.projectTrusted,
             });
         }
         catch (err) {
@@ -136,13 +298,46 @@ 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 (typeof params.planMode === "boolean") {
             session.engine.setPlanMode(params.planMode);
         }
         const sid = params.sessionId;
+        // Wire AskUserQuestion for this interactive session. The chatManager path
+        // builds a fresh per-session Engine via engineFactory, which (unlike the
+        // legacy single-engine path) never had askUser wired — so AskUserQuestion
+        // always fell into its "not available in headless mode" branch in normal
+        // chat (and in a resumed automation session). Route it to the client with
+        // this session's id so the renderer attributes the question to the right
+        // tab, resolving via the session's own pendingApprovals. Skip genuinely
+        // 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),
+            // reusing its proven resolve/timeout/cleanup. The main-side handler
+            // replies with the action's JSON result.
+            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, {
                 cwd: params.cwd,
+                goal: typeof params.goal === "string" ||
+                    (params.goal != null && typeof params.goal === "object")
+                    ? params.goal
+                    : undefined,
                 onStream: (event) => this.notify(Methods.StreamEvent, { sessionId: sid, event }),
             });
             const runResult = {
@@ -153,9 +348,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) {
@@ -191,12 +395,20 @@ export class AgentServer {
         };
         // TodoWrite emits task_update directly through ToolContext.streamCallback;
         // no module singleton wiring needed anymore.
+        // Snapshot the controller for the catch block — `this.abortController`
+        // is nulled in the `finally`, so by the time we'd want to check
+        // `signal.aborted` below it's already gone.
+        const runController = this.abortController;
         try {
             const result = await this.legacyEngine.run(params.task, {
                 cwd: params.cwd,
                 sessionId: params.sessionId,
-                signal: this.abortController.signal,
+                signal: runController.signal,
                 onStream: streamToClient,
+                goal: typeof params.goal === "string" ||
+                    (params.goal != null && typeof params.goal === "object")
+                    ? params.goal
+                    : undefined,
             });
             const runResult = {
                 text: result.text,
@@ -208,7 +420,28 @@ export class AgentServer {
             this.transport.send(createResponse(req.id, runResult));
         }
         catch (err) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+            // ESC / Stop path. If the user cancelled, the engine's
+            // in-flight LLM call or Bash spawn rejects with an AbortError
+            // that bubbles up here. Don't surface it as InternalError —
+            // the user already knows they pressed stop; clients should
+            // just clear busy.
+            const errName = err.name;
+            const aborted = runController.signal.aborted ||
+                errName === "AbortError" ||
+                errName === "APIUserAbortError";
+            if (aborted) {
+                const cancelledResult = {
+                    text: "",
+                    reason: "aborted_streaming",
+                    sessionId: params.sessionId ?? "",
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                };
+                this.transport.send(createResponse(req.id, cancelledResult));
+            }
+            else {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+            }
         }
         finally {
             this.running = false;
@@ -232,6 +465,11 @@ export class AgentServer {
                 return;
             }
             s.pendingApprovals.delete(params.requestId);
+            // Cancel the pending timeout for THIS request (the ask path armed one).
+            // The legacy single-engine branch below already does this; without it
+            // here a decided request leaves a live timer that fires at
+            // APPROVAL_TIMEOUT_MS and churns a dead map entry.
+            this.clearApprovalTimer(params.requestId);
             resolve(params.decision);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
@@ -262,6 +500,14 @@ 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 by the abort signal — they only settle on a client reply
+            // or the 5-minute APPROVAL_TIMEOUT_MS. Left alone, the awaiting tool call
+            // hangs until that timeout (delaying run wind-down) and the server-side
+            // approvalTimers entry leaks. Resolve them as cancelled now and clear the
+            // matching timers, mirroring the legacy path below.
+            this.cancelSessionApprovals(s);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
         }
@@ -278,6 +524,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 ?? {});
@@ -288,6 +691,14 @@ export class AgentServer {
         if (this.chatManager) {
             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 ──────────────────────────────────────────────────
@@ -306,15 +717,51 @@ export class AgentServer {
             if (typeof params.permissionMode === "string") {
                 s.engine.setPermissionMode(params.permissionMode);
             }
+            // 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);
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                    return;
+                }
+            }
+            // Hot-reload disk-default config onto this one session (layer 2).
+            if (params.reloadSettings === true) {
+                if (!this.settingsReader) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "reloadSettings is not supported by this AgentServer: no settingsReader is wired"));
+                    return;
+                }
+                const settings = this.settingsReader();
+                const version = ++this.configVersion;
+                s.engine.refreshRuntimeConfig(diskDefaultsFrom(settings, s.engine.getEffectiveDisabledLists().disabledPlugins), version);
+            }
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
         }
         // 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.reloadModels) {
             try {
-                engine.reloadModelPool();
+                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 (this.chatManager) {
+                    this.chatManager.forEachSession((s) => reload(s.engine));
+                }
+                if (seen.size === 0)
+                    reload(engine);
             }
             catch (err) {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -335,6 +782,48 @@ export class AgentServer {
         if (params.planMode !== undefined && engine) {
             engine.setPlanMode(params.planMode);
         }
+        // Config hot-reload layer 2: re-read disk settings once and push the
+        // disk-default config patch (+ settings-hook reload + incremental MCP
+        // connect) onto every live session. Parallel to reloadModels; no new
+        // protocol method. In-flight turns are untouched — refreshRuntimeConfig
+        // only mutates this.config, picked up at the next turn boundary.
+        if (params.reloadSettings === true) {
+            if (!this.settingsReader) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "reloadSettings is not supported by this AgentServer: no settingsReader is wired"));
+                return;
+            }
+            if (!this.chatManager) {
+                // Single-engine host (legacyEngine / anyEngine, no chatManager): there
+                // are no sessions to fan out to, but the one engine must still pick up
+                // the reload — otherwise we'd report ok:true while silently dropping it.
+                // Mirrors how reloadModels/model/planMode above act on `engine`.
+                if (engine) {
+                    const settings = this.settingsReader();
+                    engine.refreshRuntimeConfig(diskDefaultsFrom(settings, engine.getEffectiveDisabledLists().disabledPlugins), ++this.configVersion);
+                }
+                this.transport.send(createResponse(req.id, { ok: true }));
+                return;
+            }
+            const settings = this.settingsReader();
+            // 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;
+                for (const p of perSession)
+                    p.apply(version);
+            }
+        }
         this.transport.send(createResponse(req.id, { ok: true }));
     }
     // ─── Query ──────────────────────────────────────────────────────
@@ -361,12 +850,15 @@ export class AgentServer {
             case "sessions": {
                 if (this.chatManager) {
                     // Return the ChatSessionManager's live sessions
-                    const sessions = [...this.chatManager.sessions.entries()].map(([id, s]) => ({
-                        sessionId: id,
-                        busy: s.isBusy(),
-                        queueDepth: s.queueDepth(),
-                        lastActivityAt: s.lastActivityAt,
-                    }));
+                    const sessions = [];
+                    this.chatManager.forEachSession((s) => {
+                        sessions.push({
+                            sessionId: s.id,
+                            busy: s.isBusy(),
+                            queueDepth: s.queueDepth(),
+                            lastActivityAt: s.lastActivityAt,
+                        });
+                    });
                     this.transport.send(createResponse(req.id, { type: "sessions", data: sessions }));
                 }
                 else if (engine) {
@@ -393,15 +885,14 @@ export class AgentServer {
                         model: config.llm.model,
                         cwd: config.cwd,
                         maxContextTokens: config.maxContextTokens,
-                        llm: {
-                            provider: config.llm.provider,
-                            model: config.llm.model,
-                            apiKey: config.llm.apiKey,
-                            baseUrl: config.llm.baseUrl,
-                            temperature: config.llm.temperature,
-                            maxTokens: config.llm.maxTokens,
-                            enableStreaming: config.llm.enableStreaming,
-                        },
+                        // 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;
@@ -499,7 +990,15 @@ export class AgentServer {
                             cachedAt: cache ? cache.fetchedAt : undefined,
                         };
                     });
-                    this.transport.send(createResponse(req.id, { type: "providers", data: enriched }));
+                    // Strip apiKey / other secret-shaped fields from each provider
+                    // before sending. `...p` above spreads the whole provider record,
+                    // which includes apiKey verbatim — without this redact pass, any
+                    // protocol client could call query("providers") and harvest
+                    // credentials. The shared redactor preserves
+                    // presence-without-value (hasApiKey-style consumers still see the
+                    // field shape, just with [redacted] in place of the secret).
+                    const safe = redactSecrets(enriched);
+                    this.transport.send(createResponse(req.id, { type: "providers", data: safe }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -520,8 +1019,21 @@ 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);
-                    this.transport.send(createResponse(req.id, { type: "config_set", data: { key, value } }));
+                    // Echo back through the same secret-aware masker as config_get so
+                    // a `config_set("llm.apiKey", "...")` confirmation doesn't ship
+                    // the new secret through the response/log path.
+                    const safeValue = maskSecretValue(key, value);
+                    this.transport.send(createResponse(req.id, { type: "config_set", data: { key, value: safeValue } }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -538,7 +1050,9 @@ export class AgentServer {
                     if (!key)
                         throw new Error("key is required for config_get");
                     const value = engine.readSetting(key);
-                    this.transport.send(createResponse(req.id, { type: "config_get", data: { key, value } }));
+                    // Mask secret-looking keys (apiKey/token/secret/…) at the boundary.
+                    const safeValue = maskSecretValue(key, value);
+                    this.transport.send(createResponse(req.id, { type: "config_get", data: { key, value: safeValue } }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -721,6 +1235,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 {
+            engine.enqueueSteer(params.sessionId, params.text, params.id);
+            this.transport.send(createResponse(req.id, { ok: true }));
+        }
+        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).
@@ -743,6 +1306,179 @@ export class AgentServer {
     /**
      * 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.
+     */
+    requestAskUserForSession(session, sessionId, question, opts) {
+        return new Promise((resolve) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                const result = decision;
+                if (result && typeof result === "object" && "approved" in result) {
+                    resolve(result.approved ? (result.answer ?? "") : (result.reason ?? "(user declined to answer)"));
+                }
+                else {
+                    // chatManager approve handler resolves with the raw decision value.
+                    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;
+            if (opts?.options !== undefined)
+                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,
+                request: {
+                    toolName: "__ask_user__",
+                    args,
+                    description: question,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
+    /**
+     * 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",
+                },
+            });
+        });
+    }
     requestAskUserFromClient(question, opts) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
@@ -770,6 +1506,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: {
@@ -785,16 +1523,26 @@ export class AgentServer {
         this.transport.send(createNotification(method, params));
     }
     /**
-     * Get any available engine — used for global query ops when chatManager is
-     * present but no legacyEngine was supplied. Borrows the first live session.
+     * Get any available engine — used for global query/configure ops when
+     * chatManager is present but no legacyEngine was supplied. Prefer a live chat
+     * session; before the first user turn, lazily build a detached engine through
+     * the manager's factory so global UI surfaces (/login, model manager, model
+     * selector) can query models/providers without requiring a chat session first.
      */
     anyEngine() {
         if (!this.chatManager)
             return null;
-        // Access private `sessions` map — acceptable for same-package access.
         const sessions = this.chatManager.sessions;
         const first = sessions.values().next().value;
-        return first ? first.engine : null;
+        if (first)
+            return first.engine;
+        if (this.globalQueryEngine)
+            return this.globalQueryEngine;
+        const factory = this.chatManager.factory;
+        if (typeof factory !== "function")
+            return null;
+        this.globalQueryEngine = factory({});
+        return this.globalQueryEngine;
     }
     // ─── Lifecycle ──────────────────────────────────────────────────
     close() {
@@ -838,6 +1586,26 @@ export class AgentServer {
             this.approvalTimers.delete(requestId);
         }
     }
+    /**
+     * Resolve all of a chat session's pending approvals as cancelled and clear
+     * the 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 until APPROVAL_TIMEOUT_MS (and leak the timer). Each
+     * requestId in the session map has a same-keyed entry in this.approvalTimers
+     * (see requestAskUserForSession / makeBrowserBridge).
+     */
+    cancelSessionApprovals(session) {
+        for (const [requestId, resolve] of session.pendingApprovals) {
+            this.clearApprovalTimer(requestId);
+            try {
+                resolve({ approved: false, reason: "cancelled" });
+            }
+            catch {
+                /* a resolver must never break cancel cleanup */
+            }
+        }
+        session.pendingApprovals.clear();
+    }
     clearAllApprovalTimers() {
         for (const timer of this.approvalTimers.values()) {
             clearTimeout(timer);