agentus 0.1.0 → 0.3.0

package/packages/server/src/index.ts

@@ -14,13 +14,13 @@ import { exportFilename, renderJson, renderMarkdown, type ExportSessionHeader }
 import { SessionManager, SessionUnavailable } from "./acp/session-manager.js";
 import { describeAcpError } from "./acp/errors.js";
 import { BACKENDS } from "./acp/backends.js";
-import { classifyError, checkedHealth, coerceRow, inspectRow, planFor, seedRows, startupCheck } from "./acp/registry.js";
-import { FsError, listDirs, readTextFile } from "./fs.js";
+import { classifyError, checkedHealth, coerceRow, inspectRow, planFor, rowWarnings, seedRows, startupCheck } from "./acp/registry.js";
+import { ChangedOnDiskError, FsError, listDirs, readTextFile, statFile, writeTextFile } from "./fs.js";
 import { terms } from "./term.js";
 import { VoiceError, listVoiceModels, setHotwordSource, synthesize, transcribe, voiceCapabilities } from "./voice.js";
 import { hotwordsFor, vocabularyOf } from "./hotwords.js";
 import { openDashscopeStream } from "./dashscope.js";
-import { initSettings, publicSettings, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
+import { agentSettings, initSettings, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
 import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
 import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent } from "../../shared/src/index.js";
@@ -169,9 +169,19 @@ const mgr = new SessionManager(store, emit);
 
 /** The session list every client stays current with: the rows PLUS what is already waiting for
  *  an answer. Pending approvals are STATE, not just an event — a page that connects or refreshes
- *  after the request was raised still has to be able to show it. */
+ *  after the request was raised still has to be able to show it.
+ *
+ *  Three buckets, because the rail has three answers to 「这个会话在哪」 and one field cannot carry
+ *  them: `sessions` = live (a process is attached), `cold` = on disk with no process and NOT
+ *  archived (they belong in 工作空间 too — a crashed slot must not look archived), `archived` = the
+ *  operator put it away. Each row also carries `cold`/`archivedAt`, so a client never has to infer
+ *  state from which list a row arrived in (that inference is exactly what merged 已归档 with 死了). */
 const sessionsEvent = (): ServerEvent => ({
-  t: "sessions", sessions: mgr.list(), pending: mgr.pendingPermissions(),
+  t: "sessions",
+  sessions: mgr.list(),
+  cold: mgr.cold(),
+  archived: mgr.archived(),
+  pending: mgr.pendingPermissions(),
 });
 
 // ---- notify channel (docs/android-notify-contract.md) ----------------------------
@@ -234,6 +244,43 @@ initSettings(DATA_DIR, store);
 // so the lookup is injected rather than imported.
 setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word));
 
+// ---- idle reclaim (AionUi parity: 设置 → 系统 → 「Agent 空闲超时（分钟）」) ---------------------
+// The operator's standing answer to 「一个 ready 了好几个小时的槽位还挂着 agent 进程」. It STOPS the
+// process and nothing else: the row stays in 工作空间 wearing `reaped`, one click brings it back, and
+// its transcript is untouched — reaping is not archiving (that is the operator's own decision now).
+//
+// The threshold is read on every tick, so changing it in 设置 applies immediately (no restart — a
+// restart would kill exactly the slots this feature exists to keep alive cheaply). Two env knobs for
+// QA: AGENTUS_IDLE_KILL_MIN accepts a FRACTION of a minute, which is how the reclaim path is
+// exercised in seconds instead of in five minutes (AionUi made its own timeouts env-configurable for
+// the same reason), and AGENTUS_IDLE_SWEEP_MS moves the tick.
+{
+  // ABSENT must mean "follow 设置", not 0 — `Number("")` is 0, which would silently disable the
+  // reaper on every instance that never sets the env (measured: the startup line said 「0 min」 on an
+  // instance whose setting was 5). Only a real, non-empty value is an override.
+  const envNum = (raw: string | undefined): number | null => {
+    const s = String(raw ?? "").trim();
+    if (!s) return null;
+    const n = Number(s);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+  };
+  const envIdle = envNum(process.env.AGENTUS_IDLE_KILL_MIN);
+  const envIdleMs = envIdle != null ? envIdle * 60_000 : null;
+  const envSweep = envNum(process.env.AGENTUS_IDLE_SWEEP_MS);
+  const sweepMs = envSweep != null && envSweep >= 1000 ? envSweep : 30_000;
+  const source = envIdleMs != null ? "AGENTUS_IDLE_KILL_MIN" : "settings.agent.idleKillMin";
+  console.log(
+    `[agentus] idle reclaim: ${
+      envIdleMs != null ? envIdle : agentSettings().idleKillMin
+    } min (${source}), sweep ${Math.round(sweepMs / 1000)}s, 0 = off`,
+  );
+  mgr.startIdleReaper({
+    idleMs: () => envIdleMs ?? agentSettings().idleKillMin * 60_000,
+    watched: (id) => notify.operatorWatching(id),
+    intervalMs: sweepMs,
+  });
+}
+
 /** The tail of the session being dictated into, for DashScope's context enhancement
  *  ("根据上下文"): user/assistant turns only, capped at 5 by the API. */
 function dictationContext(sessionId?: string): { role: "user" | "assistant"; text: string }[] {
@@ -620,7 +667,10 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
             // settings page shows it next to the row: it is the one declaration an operator may
             // want to flip when an agent gains (or loses) native plan support.
             nativePlanSource: row.nativePlanSource,
-            warnings: plan.warnings,
+            // Which permission mode a NEW session from this row starts in (null = the agent's own
+            // default); the settings page edits it next to the other row declarations.
+            defaultMode: row.defaultMode,
+            warnings: rowWarnings(row),
             health: row.health, handshake: row.handshake,
           };
         }),
@@ -633,7 +683,7 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
       if (store.getBackend(row.id)) return send(res, 409, { error: `backend ${row.id} already exists` });
       store.upsertBackend(row);
       const plan = planFor(row);
-      return send(res, 201, { ok: true, id: row.id, warnings: plan.warnings });
+      return send(res, 201, { ok: true, id: row.id, warnings: rowWarnings(row) });
     }
     const beMatch = url.pathname.match(/^\/api\/backends\/([\w.-]+)(\/.*)?$/);
     if (beMatch) {
@@ -643,7 +693,7 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
       if (!existing) return send(res, 404, { error: `unknown backend: ${beId}` });
       if (req.method === "GET" && beSub === "") {
         const plan = planFor(existing);
-        return send(res, 200, { ...existing, home: plan.home, warnings: plan.warnings });
+        return send(res, 200, { ...existing, home: plan.home, warnings: rowWarnings(existing) });
       }
       if ((req.method === "PATCH" || req.method === "PUT") && beSub === "") {
         const body = (await readJson(req)) as Record<string, unknown>;
@@ -651,7 +701,7 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         if (!row) return send(res, 400, { error });
         store.upsertBackend(row);
         const plan = planFor(row);
-        return send(res, 200, { ok: true, id: row.id, warnings: plan.warnings });
+        return send(res, 200, { ok: true, id: row.id, warnings: rowWarnings(row) });
       }
       if (req.method === "DELETE" && beSub === "") {
         // A row that OPEN sessions still name must stay: deleting it would leave them pointing
@@ -700,7 +750,7 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
     if (url.pathname === "/api/sessions" && req.method === "GET") {
       // `pending` rides along because it is STATE, not an event: a page that loads or refreshes
       // after the request was raised never saw the event, and would otherwise show nothing.
-      return send(res, 200, { live: mgr.list(), archived: mgr.archived(), pending: mgr.pendingPermissions() });
+      return send(res, 200, { live: mgr.list(), cold: mgr.cold(), archived: mgr.archived(), pending: mgr.pendingPermissions() });
     }
     // The session's plan object — what the cockpit's card renders. STATE too, and the one piece of
     // it that cannot be replayed: after the agent process died there are no frames left to read,
@@ -740,6 +790,79 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         throw e;
       }
     }
+    // What IS this file? The panel asks before reading: an image or a PDF should not be pulled
+    // through the text endpoint to learn that it is not text, and `kind` decides which renderer
+    // and whether an editor is offered. Cheap: a stat plus a hash, no bytes decoded.
+    if (url.pathname === "/api/fs/stat" && req.method === "GET") {
+      try {
+        return send(res, 200, statFile(url.searchParams.get("path")));
+      } catch (e) {
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
+    // The file's RAW BYTES, for the renderers that need the real thing: an <img> in a reply,
+    // a PDF in the preview panel, an audio/video tag. Before this existed there was no way to
+    // show a local image at all (the read endpoint decodes utf-8 text and calls binary files
+    // "binary file"), so every `![shot](/Users/…/shot.png)` an agent wrote was a broken image.
+    //
+    // Same trust model as the endpoints above: any path the server process can read, because
+    // the operator can already point an agent at any directory and browse it via /api/fs/dirs.
+    // Behind the same auth gate. `inline` on purpose — a preview must not turn into a download.
+    if (url.pathname === "/api/fs/raw" && req.method === "GET") {
+      try {
+        const req0 = url.searchParams.get("path");
+        if (!req0) return send(res, 400, { error: "path is required", code: "bad_path" });
+        const info = statFile(req0);
+        res.writeHead(200, {
+          "content-type": info.contentType,
+          "content-length": String(info.size),
+          "cache-control": "no-store",
+          "content-disposition": "inline",
+        });
+        const stream = fs.createReadStream(info.path);
+        stream.on("error", () => res.destroy());
+        // The operator may close the panel mid-stream; an unhandled 'error' on the response
+        // would crash the process for a click that is not an error.
+        res.on("close", () => stream.destroy());
+        return stream.pipe(res);
+      } catch (e) {
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
+    // Save an edit made in the panel. 409 carries the CURRENT bytes when the file changed on
+    // disk while the operator was typing, so the UI can offer to reload instead of choosing
+    // silently whose work to lose (see writeTextFile).
+    if (url.pathname === "/api/fs/file" && (req.method === "PUT" || req.method === "POST")) {
+      const body = await readJson(req);
+      try {
+        const path0 = typeof body.path === "string" ? body.path : "";
+        if (!path0) return send(res, 400, { error: "path is required", code: "bad_path" });
+        const content = typeof body.content === "string" ? body.content : "";
+        const ifHash = typeof body.ifHash === "string" ? body.ifHash : undefined;
+        return send(res, 200, { ok: true, ...writeTextFile(path0, content, { ifHash }) });
+      } catch (e) {
+        if (e instanceof ChangedOnDiskError) {
+          return send(res, 409, {
+            error: "changed_on_disk",
+            path: e.target,
+            hash: e.currentHash,
+            content: e.currentContent,
+            truncated: e.truncated,
+            hint: "the file changed on disk since you opened it",
+          });
+        }
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
     // The windows remembered per model (the settings page and scripts read this).
     if (url.pathname === "/api/context-limits" && req.method === "GET") {
       return send(res, 200, { limits: store.listModelLimits() });
@@ -756,7 +879,8 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         if (body.theme && typeof body.theme === "object") saveTheme(body.theme as Record<string, unknown>);
         if (body.call && typeof body.call === "object") saveCall(body.call as Record<string, unknown>);
         if (body.prefs && typeof body.prefs === "object") savePrefs(body.prefs as Record<string, unknown>);
-        if (!body.voice && !body.theme && !body.call && !body.prefs) saveSettings(body);
+        if (body.agent && typeof body.agent === "object") saveAgent(body.agent as Record<string, unknown>);
+        if (!body.voice && !body.theme && !body.call && !body.prefs && !body.agent) saveSettings(body);
         return send(res, 200, publicSettings());
       } catch (e) {
         return send(res, 400, { error: String((e as Error)?.message ?? e) });
@@ -872,6 +996,30 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         }
         return send(res, 404, { error: `no such session: ${id}` });
       }
+      if (req.method === "POST" && sub === "/archive") {
+        // 归档: the operator's own storage decision (and it stops a live process — see
+        // SessionManager.setArchived). Distinct from DELETE, which on a LIVE slot only closes it and
+        // on a COLD one purges the record: 归档 is the middle statement, and before this route the UI
+        // had no way to make it.
+        try {
+          const info = await mgr.setArchived(id, true);
+          emit(sessionsEvent());
+          return send(res, 200, info);
+        } catch (e) {
+          return send(res, 404, { error: String((e as Error)?.message ?? e) });
+        }
+      }
+      if (req.method === "POST" && sub === "/unarchive") {
+        // 取消归档: moves the flag only. Waking the slot is a SEPARATE /resume, so a restore that
+        // cannot load leaves a visible cold slot in 工作空间 instead of an error nobody asked for.
+        try {
+          const info = await mgr.setArchived(id, false);
+          emit(sessionsEvent());
+          return send(res, 200, info);
+        } catch (e) {
+          return send(res, 404, { error: String((e as Error)?.message ?? e) });
+        }
+      }
       if (req.method === "POST" && sub === "/resume") {
         // AC5's other half: bring a cold slot back to life (respawn + loadSession)
         try {
@@ -1226,7 +1374,11 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
   }
   let term: ReturnType<typeof terms.start> | null = null;
   try {
-    term = terms.start(root.path);
+    // The client sends its viewport size on the socket URL: the pty must be born at the right size
+    // (the shell reads it when it paints the first prompt). Later changes arrive as term-resize.
+    const cols = Number(url.searchParams.get("cols") || 0);
+    const rows = Number(url.searchParams.get("rows") || 0);
+    term = terms.start(root.path, cols && rows ? { cols, rows } : undefined);
   } catch (e) {
     ws.send(JSON.stringify({ t: "term-error", error: String((e as Error)?.message ?? e) }));
     ws.close();
@@ -1236,12 +1388,15 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
   const send = (msg: unknown): void => {
     if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
   };
-  send({ t: "term-ready", id: session.id, cwd: session.cwd, pid: session.pid });
+  // The buffered tail goes out first, so a reconnect (or a second tab) lands on the scrollback the
+  // way ttyd's RESUME does instead of a blank screen.
+  if (session.buffer) send({ t: "term-data", id: session.id, data: session.buffer });
+  send({ t: "term-ready", id: session.id, cwd: session.cwd, pid: session.pid, tty: session.tty });
   const onData = (chunk: string): void => send({ t: "term-data", id: session.id, data: chunk });
   session.subscribers.add(onData);
   session.child.on("exit", () => send({ t: "term-exit", id: session.id }));
   ws.on("message", (data) => {
-    let cmd: { t?: string; data?: string };
+    let cmd: { t?: string; data?: string; cols?: number; rows?: number };
     try {
       cmd = JSON.parse(String(data));
     } catch {
@@ -1249,10 +1404,12 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
     }
     if (cmd.t === "term-input" && typeof cmd.data === "string") {
       try {
-        session.child.stdin.write(cmd.data);
+        session.child.stdin?.write(cmd.data);
       } catch (e) {
         send({ t: "term-error", error: `write failed: ${String((e as Error)?.message ?? e)}` });
       }
+    } else if (cmd.t === "term-resize" && typeof cmd.cols === "number" && typeof cmd.rows === "number") {
+      session.resize(cmd.cols, cmd.rows);
     } else if (cmd.t === "term-close") {
       terms.kill(session.id);
       ws.close();

package/packages/server/src/notify/center.ts

@@ -197,7 +197,18 @@ export class NotifyCenter {
 
   /** True when a notification for this session would interrupt the operator looking at it. */
   private watching(sessionId: string): boolean {
-    if (!this.rules().quietWhenWatching) return false;
+    return this.rules().quietWhenWatching && this.operatorWatching(sessionId);
+  }
+
+  /** Is the operator looking at this session RIGHT NOW? A fresh presence report (the SPA re-reports
+   *  every few seconds) from a visible page or a live call.
+   *
+   *  Public and rule-free on purpose — the ONE question two features share with different gates.
+   *  `watching()` above answers "should notification be quiet?" and therefore consults the operator's
+   *  quietWhenWatching preference; the idle reaper asks "would killing this slot's process pull the
+   *  rug out from under a reply he is reading?", and routing THAT through a notification preference
+   *  would let a checkbox decide whether agent processes get killed. */
+  operatorWatching(sessionId: string): boolean {
     if (this.presence.sessionId !== sessionId) return false;
     if (Date.now() - this.presence.at >= NotifyCenter.WATCH_TTL_MS) return false;
     // A call counts even when nobody has touched the screen for minutes: on a call the hands are free

package/packages/server/src/pty-helper.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Run one command on a REAL pseudo-terminal and shovel bytes between it and stdio.
+
+This is the whole trick behind a web terminal (ttyd does the same thing in C): `forkpty` gives the
+child a controlling terminal, so the shell believes a human is at the keyboard — line editing,
+prompts, colours, job control, full-screen programs (vim, top) all work. Without it (pipe stdio)
+the shell is in non-interactive mode: no prompt on screen, no echo, no cursor, SIGWINCH meaningless,
+and any terminal emulator in front of it is a lie.
+
+Why a Python helper instead of node-pty: node-pty is a build-time native module and this project
+stays dependency-free on install. Python 3 is present on macOS and essentially every Linux; its
+stdlib already has forkpty + termios, which is all a PTY needs. If python3 is missing the server
+falls back to pipes and says so in the panel.
+
+Wire format, all raw bytes:
+    stdin  (fd 0)  -> keystrokes from the browser, written straight to the PTY master
+    stdout (fd 1)  <- everything the PTY produces, written straight out (no filtering, no ANSI
+                      stripping: a terminal emulator consumes the escape sequences, a <pre> cannot)
+    fd 3           <- control channel, one command per line: "resize <cols> <rows>"
+
+Sizing: the initial size comes from AGENTUS_PTY_COLS / AGENTUS_PTY_ROWS, and `resize` applies
+TIOCSWINSZ to the master — the kernel then signals the child's foreground process group (SIGWINCH),
+which is what makes vim redraw at the new width.
+
+Exit: when the child exits we exit with its status; when stdin hits EOF (the socket closed) or we
+are signalled, we kill the child's process group first so no shell is orphaned.
+"""
+import errno
+import fcntl
+import os
+import pty
+import select
+import signal
+import struct
+import sys
+import termios
+
+CTL_FD = 3
+
+
+def set_winsize(fd: int, cols: int, rows: int) -> None:
+    cols = max(1, min(cols, 1000))
+    rows = max(1, min(rows, 1000))
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+
+def main() -> int:
+    argv = sys.argv[1:] or [os.environ.get("SHELL") or "/bin/sh"]
+    try:
+        cols = int(os.environ.get("AGENTUS_PTY_COLS") or 80)
+        rows = int(os.environ.get("AGENTUS_PTY_ROWS") or 24)
+    except ValueError:
+        cols, rows = 80, 24
+
+    pid, master = pty.fork()
+    if pid == 0:  # child: this IS the shell now
+        os.environ["TERM"] = os.environ.get("TERM") or "xterm-256color"
+        try:
+            os.execvp(argv[0], argv)
+        except Exception as exc:  # noqa: BLE001 - report it on the terminal rather than dying mute
+            os.write(2, f"cannot start {argv[0]}: {exc}\r\n".encode())
+            os._exit(127)
+
+    set_winsize(master, cols, rows)
+
+    ctl = None
+    try:
+        ctl = os.fdopen(CTL_FD, "r", buffering=1)
+    except OSError:
+        ctl = None  # no control channel: a fixed-size terminal is still a terminal
+
+    stdin_fd = 0
+    running = True
+    while running:
+        watch = [master, stdin_fd] + ([CTL_FD] if ctl else [])
+        try:
+            ready, _, _ = select.select(watch, [], [])
+        except OSError as exc:
+            if exc.errno == errno.EINTR:
+                continue
+            break
+
+        if master in ready:
+            try:
+                data = os.read(master, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # the child closed the pty: it is gone
+            os.write(1, data)
+
+        if stdin_fd in ready:
+            try:
+                data = os.read(stdin_fd, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # EOF: the browser went away, take the shell with us
+            os.write(master, data)
+
+        if ctl and CTL_FD in ready:
+            line = ctl.readline()
+            if line == "":
+                ctl.close()
+                ctl = None
+                continue
+            parts = line.split()
+            if parts and parts[0] == "resize" and len(parts) == 3 and parts[1].isdigit() and parts[2].isdigit():
+                set_winsize(master, int(parts[1]), int(parts[2]))
+
+    # Reap the child, then leave with its status so the server can report a real exit code.
+    status = 0
+    try:
+        _, raw = os.waitpid(pid, 0)
+        status = os.waitstatus_to_exitcode(raw) if hasattr(os, "waitstatus_to_exitcode") else 0
+    except ChildProcessError:
+        pass
+    except KeyboardInterrupt:
+        pass
+    return 0 if status is None else status
+
+
+def _terminate(_signum, _frame):  # noqa: ANN001 - signal handler
+    # The server kills our process group; this is the polite path when only we are signalled.
+    try:
+        os.kill(0, signal.SIGKILL)
+    except OSError:
+        pass
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGTERM, _terminate)
+    signal.signal(signal.SIGHUP, _terminate)
+    sys.exit(main())

package/packages/server/src/settings.ts

@@ -114,6 +114,24 @@ export const CALL_DEFAULT: CallSettings = {
 
 export const INTERRUPT_MODES: InterruptMode[] = ["voice", "button"];
 
+/** How the cockpit treats AGENT PROCESSES — as opposed to what a conversation contains. AionUi
+ *  ships the same knob in 设置 → 系统 as 「Agent 空闲超时（分钟）」 (default 5, 1–60, step 5) with the
+ *  honest description 「空闲超过该时长后自动终止 Agent 进程以释放内存」. Agentus keeps that meaning
+ *  and adds ONE thing AionUi does not have: 0 = 关闭. A cockpit deliberately left holding a
+ *  long-running slot (a build, a tunnel watcher, a call) must be able to say "never reclaim this",
+ *  and "set it to 60 and hope" is not the same statement. */
+export interface AgentSettings {
+  /** minutes of no activity before a live slot's agent process is stopped to reclaim memory;
+   *  0 = never. The row and its transcript always survive — this only stops the process. */
+  idleKillMin: number;
+}
+
+export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5 };
+
+/** What the settings page may offer: the ends of the number field. Server-side enforcement uses
+ *  the same pair, so a hand-written request cannot store a nonsense value. */
+export const AGENT_IDLE_RANGE: [number, number] = [0, 60];
+
 /** The NUMERIC knobs. `interruptMode` is a two-way choice, not a slider, so it is deliberately
  *  outside both the range table and the loops that validate numbers. */
 export const CALL_NUMERIC = ["bargeSensitivity", "bargeMs", "silenceMs", "minChars"] as const;
@@ -147,6 +165,7 @@ export interface Settings {
   theme: ThemeSettings;
   call: CallSettings;
   prefs: PrefsSettings;
+  agent: AgentSettings;
   updatedAt: number;
 }
 
@@ -173,7 +192,7 @@ let db: Store | null = null;
 let legacyFile = "";
 let cache: Settings = {
   voice: { ...DEFAULTS }, theme: { ...THEME_DEFAULT }, call: { ...CALL_DEFAULT },
-  prefs: { ...PREFS_DEFAULT }, updatedAt: 0,
+  prefs: { ...PREFS_DEFAULT }, agent: { ...AGENT_DEFAULT }, updatedAt: 0,
 };
 /** keys that came from env/.env (shown as "auto-detected" and used when settings are empty) */
 let envCreds: { apiKey: string; baseUrl: string; source: string } | null = null;
@@ -237,6 +256,7 @@ export function initSettings(dataDir: string, store: Store): Settings {
     theme: { ...THEME_DEFAULT, ...(stored.theme ?? {}) },
     call: pickCall(stored.call),
     prefs: pickPrefs(stored.prefs),
+    agent: pickAgent(stored.agent),
     updatedAt: Number((stored as Settings).updatedAt ?? 0),
   };
   // an unset baseUrl/apiKey bootstrap from the environment: the operator said the
@@ -266,6 +286,20 @@ function pickCall(raw: unknown): CallSettings {
   return out;
 }
 
+/** The agent-process knobs. Out-of-range or unparseable values fall back to the shipped default
+ *  rather than throwing: this section decides whether a slot's process is reclaimed, and a settings
+ *  row that cannot be read must never leave the reaper in an undefined state (an undefined `> 0`
+ *  comparison would silently turn reclaiming OFF — the safe failure is the documented default). */
+function pickAgent(raw: unknown): AgentSettings {
+  const out = { ...AGENT_DEFAULT };
+  if (raw && typeof raw === "object") {
+    const v = Number((raw as Record<string, unknown>).idleKillMin);
+    const [lo, hi] = AGENT_IDLE_RANGE;
+    if (Number.isFinite(v) && v >= lo && v <= hi) out.idleKillMin = v;
+  }
+  return out;
+}
+
 function pickPrefs(raw: unknown): PrefsSettings {
   const out = { ...PREFS_DEFAULT };
   if (raw && typeof raw === "object") {
@@ -289,6 +323,7 @@ function persist(): void {
     db.setSetting("theme", cache.theme);
     db.setSetting("call", cache.call);
     db.setSetting("prefs", cache.prefs);
+    db.setSetting("agent", cache.agent);
   } catch (e) {
     console.error(`[agentus] cannot write settings: ${(e as Error).message}`);
   }
@@ -331,6 +366,9 @@ export function publicSettings(): Record<string, unknown> {
     hotwordLimit: v.hotwordLimit,
     prefs: cache.prefs,
     prefsDefaults: PREFS_DEFAULT,
+    agent: cache.agent,
+    agentDefaults: AGENT_DEFAULT,
+    agentIdleRange: AGENT_IDLE_RANGE,
     // the defaults, so the UI can offer "reset to Bailian defaults"
     defaults: { ...DEFAULTS, apiKey: undefined, baseUrl: undefined },
     updatedAt: cache.updatedAt,
@@ -456,6 +494,31 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
   return cache;
 }
 
+/** Agent-process knobs: its own update, like theme/call, so a bad number here cannot lock the
+ *  operator out of the page that would fix it. Range-checked against AGENT_IDLE_RANGE before it is
+ *  stored — this number decides whether agent processes get killed, so it is not a text field. */
+export function saveAgent(patch: Record<string, unknown>): Settings {
+  const a = { ...cache.agent };
+  if ("idleKillMin" in patch) {
+    const raw = typeof patch.idleKillMin === "number" ? patch.idleKillMin : Number(patch.idleKillMin);
+    const [lo, hi] = AGENT_IDLE_RANGE;
+    if (!Number.isFinite(raw) || raw < lo || raw > hi) {
+      throw new Error(`invalid idleKillMin: ${JSON.stringify(patch.idleKillMin)} (expected ${lo}…${hi} minutes, 0 = off)`);
+    }
+    a.idleKillMin = raw;
+  }
+  cache = { ...cache, agent: a, updatedAt: Date.now() };
+  persist();
+  return cache;
+}
+
+/** The agent-process knobs as the reaper reads them — on every tick, so a settings change applies
+ *  without a restart. Returns the live cache object, not a copy: a caller that wants a snapshot has
+ *  no business holding this one. */
+export function agentSettings(): AgentSettings {
+  return cache.agent;
+}
+
 /** Normalise the two URL shapes operators paste: MaaS root or .../compatible-mode/v1. */
 export function dashscopeUrls(baseUrl: string): { root: string; compat: string; ws: string } {
   const trimmed = baseUrl.replace(/\/+$/, "");