pi-web-ui 0.22.1 → 0.24.0

package/dist/server/agent-service.js

@@ -14,15 +14,28 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
+import { findVisionModels, transcribeImages, } from "./vision-bridge.js";
 const SNAPSHOT_INTERVAL_MS = 60;
 const WIDGET_REFRESH_MS = 2000;
 const WIDGET_WIDTH = 80;
 /** Preview panel cap: only the first 512KB of a file is ever read/sent. */
 const MAX_PREVIEW_BYTES = 512 * 1024;
+/** Thrown when the service is quiesced (draining) and the request is NEW work
+ *  the admission controller refuses: a brand-new client attach, a prompt,
+ *  a fork, a session resume, or a goal wizard start. index.ts closes the
+ *  WebSocket with 4403 so the browser reconnect loop can retry after the
+ *  server reopens admission (see AgentService.quiesce). */
+export class QuiesceRejectedError extends Error {
+    code = "QUIESCED";
+    constructor(detail) {
+        super(`服务器正在排空存量工作（quiesce）——${detail}`);
+        this.name = "QuiesceRejectedError";
+    }
+}
 const PREVIEW_IMAGE_EXTS = new Set([
     "png",
     "jpg",
@@ -218,6 +231,42 @@ function decodeText(buf) {
         }
     }
 }
+/** Sniff an image MIME type from magic bytes (extension is only a hint).
+ *  Returns null when the bytes don't look like a known raster format —
+ *  callers keep such files as plain path references. */
+function sniffImageMime(buf, ext) {
+    if (buf.length >= 8 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47) {
+        return "image/png";
+    }
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const head = buf.slice(0, 6).toString("ascii");
+    if (head === "GIF87a" || head === "GIF89a")
+        return "image/gif";
+    if (buf.length >= 12 &&
+        buf.slice(0, 4).toString("ascii") === "RIFF" &&
+        buf.slice(8, 12).toString("ascii") === "WEBP") {
+        return "image/webp";
+    }
+    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d)
+        return "image/bmp";
+    // Unknown but raster-looking extension — trust the extension so existing
+    // image attachments keep working.
+    const known = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+    };
+    return known[ext] ?? null;
+}
 /** Windows persona appendix — appended to the SDK system prompt on win32 only.
  *  Two failure modes it guards against: (1) the SDK bash tool has NO default
  *  timeout, so a long-running command hangs the whole conversation forever;
@@ -856,6 +905,8 @@ class ClientStateStore {
             customSystemPrompt: s?.settings?.customSystemPrompt ?? "",
             disabledSkills: s?.settings?.disabledSkills ?? [],
             disabledExtensions: s?.settings?.disabledExtensions ?? [],
+            visionBridgeEnabled: s?.settings?.visionBridgeEnabled ?? true,
+            visionBridgeModel: s?.settings?.visionBridgeModel ?? null,
         };
     }
     /** Persist the client's settings-panel state (partial merge). */
@@ -868,6 +919,8 @@ class ClientStateStore {
             customSystemPrompt: settings.customSystemPrompt ?? cur.customSystemPrompt ?? "",
             disabledSkills: settings.disabledSkills ?? cur.disabledSkills ?? [],
             disabledExtensions: settings.disabledExtensions ?? cur.disabledExtensions ?? [],
+            visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
+            visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
         };
         this.save();
     }
@@ -931,6 +984,9 @@ function conversationTitle(session) {
 }
 export class ClientSession {
     clientId;
+    /** Set by AgentService.attach: reflects the SERVICE-wide quiesce flag
+     *  (server draining — new work rejected). Default false for direct use. */
+    isQuiesced = () => false;
     cwd;
     /** pi config dir (auth/models/skills). */
     agentDir;
@@ -1046,6 +1102,12 @@ export class ClientSession {
     }
     /** PTY terminals for this client (killed when the last socket detaches). */
     terminals = new TerminalManager((msg) => this.emit(msg));
+    /**
+     * Vision-bridge transcript cache (batch hash → text). A re-sent / re-asked
+     * prompt with the same images skips the vision API call entirely — editing
+     * a question doesn't re-burn tokens on re-transcribing identical screenshots.
+     */
+    visionBridgeCache = new Map();
     /** Web-facing extension UI context (widgets, notifications). */
     webUi = new WebUIContext((msg) => this.emit(msg));
     widgetsTimer = null;
@@ -2042,7 +2104,8 @@ export class ClientSession {
                 baseUrl: p.baseUrl,
                 apiKey: p.apiKey,
                 authHeader: p.authHeader,
-                headers: p.headers,
+                // headers are intentionally NOT sent to the browser — they may
+                // contain Authorization / API-key values; kept server-side only.
                 models,
             };
         });
@@ -2075,14 +2138,17 @@ export class ClientSession {
         }
         try {
             const { providers } = this.readModelsConfig();
+            // headers never reach the browser, so the incoming config can't carry
+            // them — preserve the previously stored values when they are absent.
+            const prevHeaders = providers[pid]?.headers;
             providers[pid] = {
                 ...(config.name?.trim() ? { name: config.name.trim() } : {}),
                 ...(config.api?.trim() ? { api: config.api.trim() } : {}),
                 ...(config.baseUrl?.trim() ? { baseUrl: config.baseUrl.trim() } : {}),
                 ...(config.apiKey?.trim() ? { apiKey: config.apiKey.trim() } : {}),
                 ...(config.authHeader ? { authHeader: true } : {}),
-                ...(config.headers && Object.keys(config.headers).length > 0
-                    ? { headers: config.headers }
+                ...(prevHeaders && Object.keys(prevHeaders).length > 0
+                    ? { headers: prevHeaders }
                     : {}),
                 models,
             };
@@ -2463,6 +2529,9 @@ export class ClientSession {
             settings: {
                 promptMode: this.settings.promptMode,
                 customSystemPrompt: this.settings.customSystemPrompt,
+                visionBridgeEnabled: this.settings.visionBridgeEnabled,
+                visionBridgeModel: this.settings.visionBridgeModel,
+                visionModels: this.collectVisionModels(),
                 disabledSkills: [...this.settings.disabledSkills],
                 disabledExtensions: [...this.settings.disabledExtensions],
                 skills,
@@ -2471,8 +2540,26 @@ export class ClientSession {
             },
         });
     }
+    /** Vision-capable configured models, for the settings-panel picker. */
+    collectVisionModels() {
+        try {
+            return findVisionModels(this.session.modelRuntime).map((m) => ({
+                provider: m.provider,
+                id: m.id,
+                label: m.label,
+            }));
+        }
+        catch {
+            // Session not ready yet — the picker stays empty until next push.
+            return [];
+        }
+    }
     /** Persist + apply a partial settings update (prompt text/mode, toggles). */
     async setSettings(partial) {
+        const needsReload = partial.promptMode !== undefined ||
+            partial.customSystemPrompt !== undefined ||
+            partial.disabledSkills !== undefined ||
+            partial.disabledExtensions !== undefined;
         if (partial.promptMode !== undefined)
             this.settings.promptMode = partial.promptMode;
         if (partial.customSystemPrompt !== undefined) {
@@ -2484,9 +2571,16 @@ export class ClientSession {
         if (partial.disabledExtensions !== undefined) {
             this.settings.disabledExtensions = partial.disabledExtensions;
         }
+        if (partial.visionBridgeEnabled !== undefined) {
+            this.settings.visionBridgeEnabled = partial.visionBridgeEnabled;
+        }
+        if (partial.visionBridgeModel !== undefined) {
+            this.settings.visionBridgeModel = partial.visionBridgeModel ?? null;
+        }
         this.stateStore.saveSettings(this.clientId, this.settings);
         this.pushSettings();
-        await this.applyRuntimeSettings();
+        if (needsReload)
+            await this.applyRuntimeSettings();
     }
     /** Save the CURRENT settings as a named preset (overwrites if exists). */
     async savePreset(name) {
@@ -2522,6 +2616,9 @@ export class ClientSession {
             customSystemPrompt: p.customSystemPrompt,
             disabledSkills: [...p.disabledSkills],
             disabledExtensions: [...p.disabledExtensions],
+            // Presets don't capture vision-bridge prefs — keep the current ones.
+            visionBridgeEnabled: this.settings.visionBridgeEnabled,
+            visionBridgeModel: this.settings.visionBridgeModel,
         };
         this.stateStore.saveSettings(this.clientId, this.settings);
         this.pushSettings();
@@ -2572,7 +2669,52 @@ export class ClientSession {
     // ---------------------------------------------------------------------------
     // Commands
     // ---------------------------------------------------------------------------
-    async prompt(text, attachments) {
+    /** True when the service is draining (quiesced): emits a rejection notice
+     *  and returns true. Guards every NEW-work entry point (prompt / new chat /
+     *  edit-resend / session resume / goal wizard) — existing runs keep going.
+     *  Called BEFORE any LLM/token work starts so quiesce is a hard admission
+     *  gate, not a best-effort hint. */
+    quiesceBlocked() {
+        if (!this.isQuiesced())
+            return false;
+        this.emit({
+            type: "notice",
+            level: "error",
+            text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-web-ui server unquiesce 可恢复。",
+        });
+        this.flushSnapshot();
+        return true;
+    }
+    /** Conversations with an in-flight run — active work for quiesce status. */
+    activeConversations() {
+        let n = 0;
+        for (const c of this.convs.values()) {
+            try {
+                if (c.session.isStreaming)
+                    n += 1;
+            }
+            catch {
+                // session being replaced — not running
+            }
+        }
+        return n;
+    }
+    /** Messages queued in the SDK (steer + follow-up) — pending work for
+     *  quiesce status. Quiesce refuses to add more, so this only drains. */
+    pendingMessages() {
+        let n = 0;
+        for (const c of this.convs.values())
+            n += c.queueFollowUp + c.queueSteering;
+        return n;
+    }
+    async prompt(text, attachments, 
+    /**
+     * true = followUp: while streaming, queue the prompt and deliver it only
+     * after the WHOLE run finishes (补充 button — "AI 生成结束才发送").
+     * false/undefined = steer: the pi CLI Enter semantic — injected right
+     * after the current turn settles, skipping remaining planned tool calls.
+     */
+    queue = false) {
         try {
             const s = this.session;
             // Native slash commands (see NATIVE_COMMANDS) are executed here and
@@ -2583,6 +2725,11 @@ export class ClientSession {
                 this.flushSnapshot();
                 return;
             }
+            // Native commands above are pure config tweaks (no tokens) — allow them
+            // even while quiesced. Everything that reaches the SDK is NEW work and
+            // is refused until admission reopens.
+            if (this.quiesceBlocked())
+                return;
             // Attach files as independent nextTurn context messages (asides) so the
             // user message stays clean; they render as separate attachment cards.
             const asides = await this.buildAttachmentMessages(attachments);
@@ -2590,13 +2737,19 @@ export class ClientSession {
                 await s.sendCustomMessage(aside.message, { deliverAs: "nextTurn" });
             }
             if (s.isStreaming) {
-                // Steer: interrupts the current run — the message is delivered right
-                // after the current assistant turn settles (remaining planned tool
-                // calls are skipped) and the agent immediately responds to it. This
-                // is the pi CLI Enter-during-streaming semantic (docs/usage: Enter
-                // queues a steering message); followUp would wait for the whole run
+                // queue=true (补充 button) → followUp: the message is delivered only
+                // after the whole run finishes — the agent finishes what it started,
+                // then responds to the queued message. queue=false/undefined
+                // (plain Enter) → steer: interrupts the current run — the message
+                // is delivered right after the current assistant turn settles
+                // (remaining planned tool calls are skipped) and the agent
+                // immediately responds to it. This is the pi CLI
+                // Enter-during-streaming semantic (docs/usage: Enter queues a
+                // steering message); followUp would wait for the whole run
                 // to finish, which users perceive as ordinary queueing.
-                await s.prompt(text, { streamingBehavior: "steer" });
+                await s.prompt(text, {
+                    streamingBehavior: queue ? "followUp" : "steer",
+                });
             }
             else {
                 await s.prompt(text);
@@ -2665,9 +2818,147 @@ export class ClientSession {
             ".svg": "image/svg+xml",
         };
         const out = [];
+        // -- Vision bridge ------------------------------------------------------
+        // When the active model can't accept images (DeepSeek, GLM, …), pasted
+        // images are transcribed by a configured vision model first and the
+        // transcript is fed to the text-only model as text evidence (see
+        // vision-bridge.ts — any model in models.json whose input includes
+        // "image" works, zero extra config). Vision-capable main models keep
+        // the raw image-content path untouched.
+        const mainModel = this.session.model;
+        const mainSupportsVision = mainModel?.input?.includes("image") ?? false;
+        const bridgedImages = [];
+        /** Raw image bytes for path-referenced image files (idx → info), pre-read
+         *  so the loop below doesn't re-read them. SVG stays a plain text file —
+         *  the model reads its source, far more useful than a rasterized blob. */
+        const pathImageData = new Map();
+        /** Cap for path images (fully read + base64'd); larger ones fall back to
+         *  a plain path reference (the model can still attempt to read them). */
+        const MAX_PATH_IMAGE_BYTES = 5 * 1024 * 1024;
+        for (const [idx, att] of attachments.entries()) {
+            if (att.imageData) {
+                const raw = att.imageData.replace(/^data:[^;]*;base64,/, "");
+                const mimeType = att.mimeType?.startsWith("image/")
+                    ? att.mimeType
+                    : "image/png";
+                const bytes = Buffer.byteLength(raw, "base64");
+                // Only images that would actually be sent (non-empty, under the cap).
+                if (bytes > 0 && bytes <= 2 * 1024 * 1024) {
+                    if (!mainSupportsVision) {
+                        bridgedImages.push({ idx, att, raw, mimeType, bytes });
+                    }
+                }
+                continue;
+            }
+            if (att.fileData || !att.path)
+                continue;
+            const ext = extname(att.path).toLowerCase();
+            if (!IMAGE_EXT.has(ext) || ext === ".svg")
+                continue;
+            const abs = resolve(root, att.path);
+            const rawRel = relative(root, abs);
+            if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`))
+                continue;
+            let st;
+            try {
+                st = await fs.stat(abs);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile() || st.size === 0 || st.size > MAX_PATH_IMAGE_BYTES) {
+                continue;
+            }
+            const buf = await fs.readFile(abs);
+            const mime = sniffImageMime(buf, ext);
+            if (!mime)
+                continue;
+            const raw = buf.toString("base64");
+            pathImageData.set(idx, { raw, mimeType: mime, bytes: st.size });
+            if (!mainSupportsVision) {
+                bridgedImages.push({ idx, att, raw, mimeType: mime, bytes: st.size });
+            }
+        }
+        /** Transcript per attachment index (filled below, keyed by bridgedImages idx). */
+        const bridgeTranscripts = new Map();
+        if (bridgedImages.length > 0) {
+            if (!this.settings.visionBridgeEnabled) {
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且视觉桥已在设置中关闭：图片将原样发送、可能被忽略。`,
+                });
+            }
+            else {
+                const visionModels = findVisionModels(this.session.modelRuntime);
+                // Preferred model from settings ("provider/id") — validated to exist
+                // and actually accept images; falls back to the first auto-detected.
+                let chosen = visionModels[0] ?? null;
+                const pref = this.settings.visionBridgeModel;
+                if (pref) {
+                    const spec = this.resolveReviewModel(pref);
+                    if (spec) {
+                        const pm = this.session.modelRuntime.getModel(spec.provider, spec.id);
+                        if (pm?.input?.includes("image")) {
+                            chosen = {
+                                provider: spec.provider,
+                                id: spec.id,
+                                label: `${pm.name ?? pm.id} (${spec.provider})`,
+                            };
+                        }
+                    }
+                }
+                if (!chosen) {
+                    this.emit({
+                        type: "notice",
+                        level: "warning",
+                        text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且未找到可用的视觉模型：图片将原样发送、可能被忽略。在模型配置里添加任意支持图片的模型（如 qwen-vl、GLM-4V、Gemini）即可自动启用视觉桥转写。`,
+                    });
+                }
+                else {
+                    // Batch hash so re-sending identical images (edit & re-ask) reuses
+                    // the transcript instead of re-burning tokens on the vision API.
+                    const batchHash = bridgedImages
+                        .map((b) => `${b.att.name ?? "img"}:${b.raw.slice(0, 48)}`)
+                        .join("|");
+                    let transcript = this.visionBridgeCache.get(batchHash);
+                    if (transcript === undefined) {
+                        this.emit({
+                            type: "notice",
+                            level: "info",
+                            text: `当前模型不支持识图，正在用视觉桥（${chosen.label}）转写 ${bridgedImages.length} 张图片…`,
+                        });
+                        try {
+                            const chosenModel = this.session.modelRuntime.getModel(chosen.provider, chosen.id);
+                            transcript = await transcribeImages(this.session.modelRuntime, bridgedImages.map((b) => ({
+                                data: b.raw,
+                                mimeType: b.mimeType,
+                                name: b.att.name,
+                            })), { model: chosenModel ?? undefined });
+                            this.visionBridgeCache.set(batchHash, transcript);
+                            this.emit({
+                                type: "notice",
+                                level: "info",
+                                text: `✅ 图片已由视觉桥转写完成（${chosen.label}）`,
+                            });
+                        }
+                        catch (err) {
+                            transcript = "";
+                            this.emit({
+                                type: "notice",
+                                level: "error",
+                                text: `图片转写失败（${chosen.label}）：${err.message}。图片将原样发送、可能被忽略。`,
+                            });
+                        }
+                    }
+                    for (const b of bridgedImages)
+                        bridgeTranscripts.set(b.idx, transcript ?? "");
+                }
+            }
+        }
         /** Cap for reading a file in "lines" mode (selected slice is inlined). */
         const MAX_LINES_READ_BYTES = 2 * 1024 * 1024;
-        for (const att of attachments) {
+        for (const [idx, att] of attachments.entries()) {
             // Raw pasted/dropped/uploaded image — no workspace path involved (the
             // browser downscales client-side; this guard only prevents abuse).
             if (att.imageData) {
@@ -2691,6 +2982,32 @@ export class ClientSession {
                     });
                     continue;
                 }
+                const transcript = bridgeTranscripts.get(idx);
+                if (transcript) {
+                    // Bridged: the text-only main model can't see images, so it gets the
+                    // vision model's transcript as text evidence; the image block is
+                    // kept so the card still shows the original thumbnail.
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `\n<vision-bridge>\n${transcript}\n</vision-bridge>`,
+                                },
+                                { type: "image", data: raw, mimeType },
+                            ],
+                            display: true,
+                            details: {
+                                name: att.name ?? "image.png",
+                                path: undefined,
+                                mode: "bridged",
+                                size: bytes,
+                            },
+                        },
+                    });
+                    continue;
+                }
                 out.push({
                     message: {
                         customType: "file",
@@ -2843,8 +3160,63 @@ export class ClientSession {
                 continue;
             }
             const ext = extname(att.path).toLowerCase();
-            if (IMAGE_EXT.has(ext)) {
-                // Images can't be referenced — they must be inlined, so keep a hard cap.
+            if (IMAGE_EXT.has(ext) && ext !== ".svg") {
+                const pathImg = pathImageData.get(idx);
+                const transcript = bridgeTranscripts.get(idx);
+                if (transcript) {
+                    // Text-only main model: the vision bridge transcribed this image —
+                    // the model gets the transcript as text evidence (+ thumbnail).
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `
+<vision-bridge>
+${transcript}
+</vision-bridge>`,
+                                },
+                                ...(pathImg
+                                    ? ([{
+                                            type: "image",
+                                            data: pathImg.raw,
+                                            mimeType: pathImg.mimeType,
+                                        }])
+                                    : []),
+                            ],
+                            display: true,
+                            details: {
+                                name,
+                                path: rel,
+                                mode: "bridged",
+                                size: stat.size,
+                            },
+                        },
+                    });
+                    continue;
+                }
+                if (pathImg) {
+                    // Vision-capable main model (or bridge failed): send the raw image
+                    // content straight from the pre-read bytes.
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "image",
+                                    data: pathImg.raw,
+                                    mimeType: pathImg.mimeType,
+                                },
+                            ],
+                            display: true,
+                            details: { name, path: rel, mode: "image", size: stat.size },
+                        },
+                    });
+                    continue;
+                }
+                // Pre-read failed (unsupported sniff / too large): fall back to the
+                // legacy inline-cap behavior.
                 if (stat.size > MAX_ATTACHMENT_BYTES) {
                     this.emit({
                         type: "notice",
@@ -3255,6 +3627,8 @@ export class ClientSession {
         }
     }
     async newChat() {
+        if (this.quiesceBlocked())
+            return;
         // Reuse an already-open blank conversation instead of piling up new ones
         // on every click: if the active chat has no messages it IS the new chat
         // (focus already on it); otherwise switch to the first blank one (under
@@ -3438,6 +3812,8 @@ export class ClientSession {
     }
     /** Switch the active session to a persisted one (from listSessions). */
     async switchSession(path) {
+        if (this.quiesceBlocked())
+            return;
         try {
             await this.runtime.switchSession(path);
             await this.bindSession();
@@ -3496,6 +3872,8 @@ export class ClientSession {
      * session list, so nothing is ever lost.
      */
     async editMessage(messageId, text) {
+        if (this.quiesceBlocked())
+            return;
         const trimmed = text.trim();
         if (!trimmed) {
             this.emit({
@@ -4035,6 +4413,8 @@ export class ClientSession {
      * Mutually exclusive with the review loop.
      */
     async startGoalWizard(text, opts) {
+        if (this.quiesceBlocked())
+            return;
         const draft = (text ?? "").trim();
         if (!draft)
             return;
@@ -4726,6 +5106,15 @@ export class ClientSession {
 export class AgentService {
     cwd;
     clients = new Map();
+    /** Quiesce (draining) state — the service refuses NEW work (prompts, forks,
+     *  session resumes, new clients) so a deploy/upgrade/backup can stop cleanly
+     *  once existing runs finish. Controlled via the local control socket:
+     *  `pi-web-ui server quiesce|unquiesce`. */
+    quiesced = false;
+    quiescedAt = 0;
+    /** Attached browser sockets (reported by index.ts on open/close) — the
+     *  control socket reports real sockets, not cached client-session objects. */
+    socketCount = 0;
     pending = new Map();
     stateStore;
     /**
@@ -4740,6 +5129,60 @@ export class AgentService {
         this.stateStore = new ClientStateStore(stateFile);
     }
     /** Get or create the session for a client, racing attach calls safely. */
+    /** True while the service is draining — new work is refused. */
+    isQuiesced() {
+        return this.quiesced;
+    }
+    /** Enter quiesce: stop admitting new work. Existing runs keep going. */
+    quiesce() {
+        this.quiesced = true;
+        this.quiescedAt = Date.now();
+    }
+    /** Leave quiesce: admit new work again. */
+    unquiesce() {
+        this.quiesced = false;
+        this.quiescedAt = 0;
+    }
+    /** Snapshot for the control socket / status command. */
+    quiesceInfo() {
+        return this.quiesced
+            ? { quiesced: true, quiescedSince: this.quiescedAt }
+            : { quiesced: false };
+    }
+    /** Aggregate across every client session: conversations with in-flight runs. */
+    activeConversations() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.activeConversations();
+        return n;
+    }
+    /** Aggregate across every client session: messages queued in the SDK. */
+    pendingMessages() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.pendingMessages();
+        return n;
+    }
+    /** index.ts calls this when a browser socket opens/closes. */
+    noteSocketOpen() {
+        this.socketCount += 1;
+    }
+    noteSocketClose() {
+        this.socketCount = Math.max(0, this.socketCount - 1);
+    }
+    /** Full status for the control socket / `server status` command. */
+    serviceStatus() {
+        return {
+            pid: process.pid,
+            version: VERSION,
+            cwd: this.cwd,
+            ...this.quiesceInfo(),
+            connectedClients: this.socketCount,
+            activeConversations: this.activeConversations(),
+            pendingMessages: this.pendingMessages(),
+        };
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
     async attach(clientId, send) {
         let cs = this.clients.get(clientId);
         if (!cs) {
@@ -4749,6 +5192,13 @@ export class AgentService {
             }
             else {
                 // Restore this client's last-used workspace when it still exists;
+                // Admission gate: while quiesced, only clients with an EXISTING
+                // session may attach (they can watch their runs drain); brand-new
+                // clients are refused — index.ts closes their socket (4403) and the
+                // browser reconnect loop retries after admission reopens.
+                if (this.quiesced) {
+                    throw new QuiesceRejectedError("新连接被拒绝，请等服务器恢复后重试");
+                }
                 // otherwise fall back to the server's configured default cwd.
                 let cwd = this.cwd;
                 const saved = this.stateStore.get(clientId);
@@ -4783,6 +5233,7 @@ export class AgentService {
         // Forward hooks (set once by index.ts) to every session.
         cs.onUpdateReady = this.onUpdateReady;
         cs.onQuit = this.onQuit;
+        cs.isQuiesced = () => this.quiesced;
         return cs;
     }
     /** Remove a socket from a client's broadcast set (called on socket close). */