@lelouchhe/webagent 0.3.0 → 0.5.1

package/lib/client-registry.js

@@ -0,0 +1,149 @@
+/**
+ * ClientRegistry — in-memory tracking of connected clients.
+ *
+ * Tracks per-client metadata that survives SSE disconnect:
+ *   - capabilities advertised by the client on /hello.
+ *   - visible / active / visibleSince: identity-layer visibility state used
+ *     by TTS dispatch (voice branch) and push suppression (main).
+ *
+ * Lifecycle: clients call /hello on SSE connect (register) and POST
+ * /visibility on visibilitychange + 15s heartbeat. SSE disconnect does
+ * not remove a client — it stays in the registry until an explicit
+ * /goodbye or TTL eviction (caller's responsibility). This lets visibility
+ * state outlive transient drops.
+ */
+export class ClientRegistry {
+    clients = new Map();
+    visibilityTtlMs;
+    now;
+    constructor(options = {}) {
+        this.visibilityTtlMs = options.visibilityTtlMs ?? 60_000;
+        this.now = options.now ?? Date.now;
+    }
+    register(id, data) {
+        const existing = this.clients.get(id);
+        if (existing) {
+            existing.capabilities = data.capabilities;
+            existing.lastSeen = this.now();
+            return existing;
+        }
+        const entry = {
+            id,
+            capabilities: data.capabilities,
+            visible: false,
+            active: null,
+            visibleSince: 0,
+            lastSeen: this.now(),
+        };
+        this.clients.set(id, entry);
+        return entry;
+    }
+    remove(id) {
+        this.clients.delete(id);
+    }
+    /**
+     * Atomic visibility setter. Mirrors PushService.updateClient semantics:
+     *   - `visible` omitted = preserve; bool = set (and stamp/clear visibleSince).
+     *   - `active`  omitted = preserve; null = clear; string = replace.
+     *   - Returns `becameVisibleFor=X` only on first transition into
+     *     (visible:true, active:X) — heartbeat refreshes return null so
+     *     callers can fire edge-triggered side effects exactly once.
+     *   - Session-switch while visible (active X→Y) restarts the TTL clock
+     *     even when the patch doesn't carry an explicit visible:true.
+     *
+     * No-op on unknown client.
+     */
+    setVisibility(id, patch) {
+        const entry = this.clients.get(id);
+        if (!entry)
+            return { becameVisibleFor: null };
+        const wasVisibleForSession = entry.visible && entry.active != null ? entry.active : null;
+        if (patch.visible !== undefined) {
+            entry.visible = patch.visible;
+            entry.visibleSince = patch.visible ? this.now() : 0;
+        }
+        if (patch.active !== undefined) {
+            entry.active = patch.active;
+        }
+        const becameVisibleFor = entry.visible &&
+            entry.active != null &&
+            entry.active !== wasVisibleForSession
+            ? entry.active
+            : null;
+        if (becameVisibleFor) {
+            // Any transition into "visible + active=X" restarts TTL — including
+            // session-switches that arrive without an explicit visible:true.
+            entry.visibleSince = this.now();
+        }
+        entry.lastSeen = this.now();
+        return { becameVisibleFor };
+    }
+    /** Is this specific client currently visible & viewing `sessionId` & fresh? */
+    isVisibleForSession(id, sessionId) {
+        const entry = this.clients.get(id);
+        if (!entry)
+            return false;
+        if (!entry.visible)
+            return false;
+        if (entry.active !== sessionId)
+            return false;
+        if (this.now() - entry.visibleSince > this.visibilityTtlMs)
+            return false;
+        return true;
+    }
+    /** Is at least one fresh visible client viewing `sessionId`? */
+    isSessionVisibleToAnyClient(sessionId) {
+        const now = this.now();
+        for (const e of this.clients.values()) {
+            if (!e.visible)
+                continue;
+            if (e.active !== sessionId)
+                continue;
+            if (now - e.visibleSince > this.visibilityTtlMs)
+                continue;
+            return true;
+        }
+        return false;
+    }
+    /** Is this specific client currently fresh-visible (any session)? */
+    isClientVisible(id) {
+        const entry = this.clients.get(id);
+        if (!entry)
+            return false;
+        if (!entry.visible)
+            return false;
+        if (this.now() - entry.visibleSince > this.visibilityTtlMs)
+            return false;
+        return true;
+    }
+    /** Is at least one fresh visible client connected (any session)? */
+    hasAnyVisibleClient() {
+        const now = this.now();
+        for (const e of this.clients.values()) {
+            if (!e.visible)
+                continue;
+            if (now - e.visibleSince > this.visibilityTtlMs)
+                continue;
+            return true;
+        }
+        return false;
+    }
+    updateCapabilities(id, caps) {
+        const entry = this.clients.get(id);
+        if (!entry)
+            return;
+        entry.capabilities = caps;
+        entry.lastSeen = this.now();
+    }
+    touch(id) {
+        const entry = this.clients.get(id);
+        if (entry)
+            entry.lastSeen = this.now();
+    }
+    get(id) {
+        return this.clients.get(id);
+    }
+    list() {
+        return Array.from(this.clients.values());
+    }
+}

package/lib/config.js

@@ -1,30 +1,144 @@
 import { readFileSync } from "node:fs";
 import { parse as parseTOML } from "smol-toml";
 import { z } from "zod";
-const ConfigSchema = z.object({
+export const ConfigSchema = z.object({
     port: z.number().int().positive().default(6800),
+    // Network interface to bind. Default "127.0.0.1" = loopback only
+    // (no LAN exposure). Set to "0.0.0.0" to listen on all IPv4
+    // interfaces, "::" for IPv6/dual-stack, or a specific NIC IP
+    // (e.g. "192.168.1.10") to bind one interface on a multi-homed
+    // host. Note: "localhost" works but resolves via DNS and may
+    // pick IPv6 (`::1`) over IPv4 — prefer the explicit IP form.
+    host: z.string().default("127.0.0.1"),
     data_dir: z.string().default("data"),
     default_cwd: z.string().default(process.cwd()),
     public_dir: z.string().default("dist"),
-    agent_cmd: z.string().default("copilot --acp"),
-    limits: z.object({
+    agent_cmd: z.string().default("auto"),
+    limits: z
+        .object({
         bash_output: z.number().int().positive().default(1_048_576), // 1 MB
         image_upload: z.number().int().positive().default(10_485_760), // 10 MB
+        file_upload: z.number().int().positive().default(52_428_800), // 50 MB — non-image attachments
         cancel_timeout: z.number().int().nonnegative().default(10_000), // 10s; 0 disables
         recent_paths: z.number().int().nonnegative().default(10), // /new menu display limit; 0 = show all
         recent_paths_ttl: z.number().int().nonnegative().default(30), // days before auto-cleanup; 0 = keep forever
-    }).default({
+    })
+        .default({
         bash_output: 1_048_576,
         image_upload: 10_485_760,
+        file_upload: 52_428_800,
         cancel_timeout: 10_000,
         recent_paths: 10,
         recent_paths_ttl: 30,
     }),
-    push: z.object({
-        vapid_subject: z.string().default("mailto:webagent@localhost"),
-    }).default({
-        vapid_subject: "mailto:webagent@localhost",
+    push: z
+        .object({
+        vapid_subject: z.string().default("mailto:noreply@example.com"),
+        global_visibility_suppression: z.boolean().default(true),
+    })
+        .default({
+        vapid_subject: "mailto:noreply@example.com",
+        global_visibility_suppression: true,
     }),
+    // [title] — title generation sub-session configuration.
+    //
+    // `models` is an array of case-insensitive substring patterns. When the
+    // title sub-session is created, we look at the model list the agent
+    // reports (ACP `availableModels`) and pick the first model whose id
+    // matches any pattern in order. Match → call `setConfigOption` with
+    // that model id; no match → skip the call and inherit the agent's
+    // default model (`currentModelId`).
+    //
+    // Default list targets the cheap/fast tier across major providers:
+    //   - "haiku"      → Anthropic (claude-haiku-*)
+    //   - "flash-lite" → Google Gemini (gemini-*-flash-lite)  [must precede "flash"]
+    //   - "nano"       → OpenAI (gpt-*-nano), Gemini Nano
+    //   - "mini"       → OpenAI (gpt-*-mini, 4o-mini), Mistral
+    //   - "flash"      → Google Gemini (gemini-*-flash)
+    //   - "lite"       → Cohere, generic
+    //
+    // Set `models = []` to disable substring matching entirely and always
+    // inherit the agent's default model. To pin one specific model, pass a
+    // single-element array: `models = ["claude-haiku-4.5"]`.
+    title: z
+        .object({
+        models: z
+            .array(z.string())
+            .default(["haiku", "flash-lite", "nano", "mini", "flash", "lite"]),
+    })
+        .default({
+        models: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
+    }),
+    // [debug] — frontend log level.
+    // level ∈ off | debug | info | warn | error. Default "off".
+    // Users can override per page-load via `?debug=<level>` in the URL,
+    // or at runtime via the /log slash command.
+    debug: z
+        .object({
+        level: z.enum(["off", "debug", "info", "warn", "error"]).default("off"),
+    })
+        .default({ level: "off" }),
+    // [messages] — external notifications primitive.
+    // `unprocessed_ttl_days` caps how long an unbound message stays in the
+    // inbox before TTL cleanup removes it. 0 = keep forever.
+    messages: z
+        .object({
+        unprocessed_ttl_days: z.number().int().nonnegative().default(30),
+    })
+        .default({ unprocessed_ttl_days: 30 }),
+    // [share] — public read-only session share links.
+    // Default: disabled. Dogfood manually flips `enabled = true` after
+    // CF Access bypass + Rate Limiting are configured. See docs/share.md.
+    //   enabled        — master kill switch; when false, all share routes
+    //                    return 410 and slash commands are hidden.
+    //   ttl_hours      — global default TTL for public share links. 0 =
+    //                    never expire (default). >0 is clamped to 168 (7d).
+    //                    Per-share override via `shares.ttl_hours` column.
+    //   csp_enforce    — true (default) emits Content-Security-Policy on
+    //                    /s/* and /api/v1/shared/* routes. false emits
+    //                    Content-Security-Policy-Report-Only for rollback.
+    //   viewer_origin  — public viewer URL host; empty string = same as
+    //                    webagent host (default). Useful if viewer is
+    //                    behind a different CF Worker route (e.g.
+    //                    "https://share.example.com").
+    //   internal_hosts — sanitizer internal-domain allowlist; any token
+    //                    matching these substrings gets rewritten to
+    //                    `<internal-host>` before publishing.
+    share: z
+        .object({
+        enabled: z.boolean().default(false),
+        ttl_hours: z.number().int().nonnegative().default(0),
+        csp_enforce: z.boolean().default(true),
+        viewer_origin: z.string().default(""),
+        internal_hosts: z.array(z.string()).default([]),
+    })
+        .default({
+        enabled: false,
+        ttl_hours: 0,
+        csp_enforce: true,
+        viewer_origin: "",
+        internal_hosts: [],
+    }),
+    // [auth] — bearer-token auth knobs.
+    // first_run_bootstrap controls the zero-config first-run UX:
+    //   true  (default) — when auth.json file does NOT exist AND stdin
+    //                     is a TTY, server auto-mints a one-time admin
+    //                     token and prints it as part of the startup-
+    //                     doctor stream. Operator copies the token from
+    //                     terminal scrollback and pastes it into the
+    //                     /login form.
+    //   false           — refuse to serve, print `--create-token` hint,
+    //                     exit 78. Use this when deploying behind a
+    //                     supervisor that provisions auth.json
+    //                     out-of-band (CI, Ansible, k8s init container).
+    // Either way: if auth.json exists but list is empty (deleted/parse-
+    // error), server still exits 78 — that's a config anomaly, not a
+    // fresh install.
+    auth: z
+        .object({
+        first_run_bootstrap: z.boolean().default(true),
+    })
+        .default({ first_run_bootstrap: true }),
 });
 let _config = null;
 function parseArgs() {
@@ -35,7 +149,14 @@ function parseArgs() {
     return null;
 }
 export function loadConfig() {
-    const configPath = parseArgs();
+    return loadConfigFromPath(parseArgs());
+}
+/**
+ * Load + validate config from an explicit path (or defaults if null).
+ * Lets non-CLI callers (daemon parent) load the same effective config
+ * the server would, without needing to mutate process.argv.
+ */
+export function loadConfigFromPath(configPath) {
     let raw = {};
     if (configPath) {
         try {

package/lib/daemon.js

@@ -1,7 +1,10 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { atomicWriteFileSync } from "./atomic-write.js";
+import { loadConfigFromPath } from "./config.js";
+import { runStartupChecks, STARTUP_CHECKED_ENV } from "./startup-checks.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // ---------------------------------------------------------------------------
 // Constants
@@ -30,13 +33,15 @@ export function readPidInfo(filePath) {
         try {
             unlinkSync(filePath);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
         return null;
     }
 }
 /** Write PID info to `filePath`. */
 export function writePidInfo(filePath, info) {
-    writeFileSync(filePath, JSON.stringify(info) + "\n");
+    atomicWriteFileSync(filePath, JSON.stringify(info) + "\n");
 }
 // ---------------------------------------------------------------------------
 // Arg helpers
@@ -48,35 +53,116 @@ export function isSubcommand(arg) {
 export function resolveArgs(args) {
     const result = [...args];
     for (let i = 0; i < result.length; i++) {
-        if (result[i] === "--config" && i + 1 < result.length && !isAbsolute(result[i + 1])) {
+        if (result[i] === "--config" &&
+            i + 1 < result.length &&
+            !isAbsolute(result[i + 1])) {
             result[i + 1] = resolve(result[i + 1]);
         }
     }
     return result;
 }
 // ---------------------------------------------------------------------------
+// Config-path extraction for parent-side checks
+// ---------------------------------------------------------------------------
+/**
+ * Pull the `--config <path>` value out of the daemon's argv (resolving
+ * relative paths against cwd). Used by `cmdStart` to load the same
+ * config the server child would, so the parent process can run the
+ * unified startup checks (preflight + auth bootstrap) in the operator's
+ * TTY before forking. Returns null if no `--config` was passed.
+ */
+export function extractConfigPath(args, cwd) {
+    const idx = args.indexOf("--config");
+    if (idx < 0 || idx + 1 >= args.length)
+        return null;
+    const v = args[idx + 1];
+    return isAbsolute(v) ? v : resolve(cwd, v);
+}
+// ---------------------------------------------------------------------------
+// Restart decision (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Sysexits.h EX_CONFIG. Server exits 78 when configuration is bad
+ * (missing auth.json + non-TTY, preflight failures, etc.). Restarting
+ * cannot fix configuration — supervisor must surface and stop.
+ */
+const EX_CONFIG = 78;
+/**
+ * Pure decision: should the supervisor restart the child, and with what
+ * delay? Side effects (logging, scheduling) live in `runSupervisor`.
+ */
+export function decideRestart(code, _signal, ctx) {
+    if (ctx.stopping) {
+        return { kind: "stop", reason: "supervisor shutting down" };
+    }
+    if (code === EX_CONFIG) {
+        return {
+            kind: "stop",
+            reason: `child exited with EX_CONFIG (${EX_CONFIG}) — not restarting`,
+        };
+    }
+    const stable = ctx.now - ctx.lastStart > STABLE_THRESHOLD_MS;
+    const delay = stable
+        ? RESTART_DELAY_INITIAL
+        : Math.min(ctx.currentDelay * 2, RESTART_DELAY_MAX);
+    return { kind: "restart", delayMs: delay };
+}
+// ---------------------------------------------------------------------------
+// PID file location
+// ---------------------------------------------------------------------------
+//
+// PID file lives in `data_dir`, NOT cwd. This lets multiple instances
+// (e.g. one per agent / port) coexist on the same machine launched from
+// the same shell — each `--config` points at its own data_dir, so each
+// gets its own pid file. The log file stays in cwd (operator-facing).
+function loadDaemonContext(args, cwd) {
+    const cfgPath = extractConfigPath(args, cwd);
+    const config = loadConfigFromPath(cfgPath);
+    const dataDir = isAbsolute(config.data_dir)
+        ? config.data_dir
+        : resolve(cwd, config.data_dir);
+    try {
+        mkdirSync(dataDir, { recursive: true });
+    }
+    catch {
+        /* best-effort — start will surface real errors via startup checks */
+    }
+    return { config, pidFile: join(dataDir, PID_FILE) };
+}
+// ---------------------------------------------------------------------------
 // Command dispatch
 // ---------------------------------------------------------------------------
 export async function run(command, args) {
-    const pidFile = join(process.cwd(), PID_FILE);
+    const { config, pidFile } = loadDaemonContext(args, process.cwd());
     const logFile = join(process.cwd(), LOG_FILE);
     switch (command) {
-        case "start": return cmdStart(pidFile, logFile, args);
-        case "stop": return cmdStop(pidFile);
-        case "status": return cmdStatus(pidFile, logFile);
-        case "restart": return cmdRestart(pidFile, logFile);
+        case "start":
+            return cmdStart(pidFile, logFile, args, config);
+        case "stop":
+            return cmdStop(pidFile);
+        case "status":
+            return cmdStatus(pidFile, logFile);
+        case "restart":
+            return cmdRestart(pidFile, logFile);
     }
 }
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
-async function cmdStart(pidFile, logFile, args) {
+async function cmdStart(pidFile, logFile, args, config) {
     const existing = readPidInfo(pidFile);
     if (existing) {
         console.log(`webagent is already running (pid ${existing.pid})`);
         process.exitCode = 1;
         return;
     }
+    // Run the unified startup gate in this (foreground) process before
+    // forking. This is the operator's TTY, so first-run mint banners
+    // and `[check]` failures land where they can actually be seen and
+    // copy-pasted, instead of being entombed in the daemon log file.
+    // Pass WEBAGENT_STARTUP_CHECKED=1 to the supervisor child so it (and
+    // the server it spawns) skip re-running the gate.
+    await runStartupChecks(config);
     const serverJs = join(__dirname, "server.js");
     if (!existsSync(serverJs)) {
         console.error(`server not found: ${serverJs}`);
@@ -94,10 +180,18 @@ async function cmdStart(pidFile, logFile, args) {
                 writeFileSync(logFile, lines.slice(-LOG_MAX_LINES).join("\n"));
             }
         }
-        catch { /* best-effort */ }
+        catch {
+            /* best-effort */
+        }
     }
     const log = openSync(logFile, "a");
-    const child = spawn(process.execPath, [daemonJs, "__supervisor", ...resolved], { detached: true, stdio: ["ignore", log, log], cwd: process.cwd(), windowsHide: true });
+    const child = spawn(process.execPath, [daemonJs, "__supervisor", ...resolved], {
+        detached: true,
+        stdio: ["ignore", log, log],
+        cwd: process.cwd(),
+        windowsHide: true,
+        env: { ...process.env, [STARTUP_CHECKED_ENV]: "1" },
+    });
     child.unref();
     closeSync(log);
     // Poll for PID file (supervisor writes it on startup)
@@ -128,7 +222,9 @@ async function cmdStop(pidFile) {
         try {
             unlinkSync(pidFile);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
         return;
     }
     // Wait for exit
@@ -143,7 +239,9 @@ async function cmdStop(pidFile) {
             try {
                 unlinkSync(pidFile);
             }
-            catch { /* ignore */ }
+            catch {
+                /* ignore */
+            }
             console.log("webagent stopped");
             return;
         }
@@ -177,7 +275,8 @@ async function cmdRestart(pidFile, logFile) {
     if (process.platform === "win32") {
         // No SIGHUP on Windows — fall back to stop + start (non-atomic)
         await cmdStop(pidFile);
-        await cmdStart(pidFile, logFile, info.args);
+        const { config } = loadDaemonContext(info.args, process.cwd());
+        await cmdStart(pidFile, logFile, info.args, config);
         return;
     }
     // Unix: atomic restart via SIGHUP to supervisor
@@ -206,8 +305,12 @@ async function cmdRestart(pidFile, logFile) {
 // ---------------------------------------------------------------------------
 function runSupervisor(serverArgs) {
     const serverJs = join(__dirname, "server.js");
-    const pidFile = join(process.cwd(), PID_FILE);
-    writePidInfo(pidFile, { pid: process.pid, args: serverArgs, started: new Date().toISOString() });
+    const { pidFile } = loadDaemonContext(serverArgs, process.cwd());
+    writePidInfo(pidFile, {
+        pid: process.pid,
+        args: serverArgs,
+        started: new Date().toISOString(),
+    });
     let child = null;
     let stopping = false;
     let lastStart = 0;
@@ -215,19 +318,33 @@ function runSupervisor(serverArgs) {
     let timer = null;
     function spawnServer() {
         lastStart = Date.now();
-        child = spawn(process.execPath, [serverJs, ...serverArgs], { stdio: "inherit", windowsHide: true });
+        child = spawn(process.execPath, [serverJs, ...serverArgs], {
+            stdio: "inherit",
+            windowsHide: true,
+        });
         child.on("exit", onChildExit);
     }
     function onChildExit(code, signal) {
         child = null;
-        if (stopping)
-            return;
-        if (Date.now() - lastStart > STABLE_THRESHOLD_MS) {
-            delay = RESTART_DELAY_INITIAL;
-        }
-        else {
-            delay = Math.min(delay * 2, RESTART_DELAY_MAX);
+        const action = decideRestart(code, signal, {
+            stopping,
+            lastStart,
+            now: Date.now(),
+            currentDelay: delay,
+        });
+        if (action.kind === "stop") {
+            if (stopping)
+                return;
+            console.error(`[supervisor] ${action.reason} (code=${code} signal=${signal})`);
+            try {
+                unlinkSync(pidFile);
+            }
+            catch {
+                /* ignore */
+            }
+            process.exit(code ?? 1);
         }
+        delay = action.delayMs;
         console.log(`[supervisor] server exited (code=${code} signal=${signal}), restarting in ${delay}ms`);
         timer = setTimeout(spawnServer, delay);
     }
@@ -236,18 +353,27 @@ function runSupervisor(serverArgs) {
             clearTimeout(timer);
             timer = null;
         }
-        return new Promise((resolve) => {
+        return new Promise((innerResolve) => {
             if (!child) {
-                resolve();
+                innerResolve();
                 return;
             }
             const c = child;
-            c.once("exit", () => resolve());
+            // Take ownership of this exit — don't let the auto-restart listener
+            // race with the explicit respawn (SIGHUP path) or shutdown.
+            c.removeListener("exit", onChildExit);
+            c.once("exit", () => {
+                innerResolve();
+            });
             c.kill("SIGTERM");
-            setTimeout(() => { try {
-                c.kill("SIGKILL");
-            }
-            catch { /* ignore */ } }, KILL_GRACE_MS);
+            setTimeout(() => {
+                try {
+                    c.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+            }, KILL_GRACE_MS);
         });
     }
     async function shutdown() {
@@ -258,18 +384,26 @@ function runSupervisor(serverArgs) {
         try {
             unlinkSync(pidFile);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
         process.exit(0);
     }
-    process.on("SIGTERM", () => { shutdown(); });
-    process.on("SIGINT", () => { shutdown(); });
+    process.on("SIGTERM", () => {
+        void shutdown();
+    });
+    process.on("SIGINT", () => {
+        void shutdown();
+    });
     if (process.platform !== "win32") {
-        process.on("SIGHUP", async () => {
-            console.log("[supervisor] SIGHUP received, restarting server");
-            delay = RESTART_DELAY_INITIAL;
-            await killChild();
-            if (!stopping)
-                spawnServer();
+        process.on("SIGHUP", () => {
+            void (async () => {
+                console.log("[supervisor] SIGHUP received, restarting server");
+                delay = RESTART_DELAY_INITIAL;
+                await killChild();
+                if (!stopping)
+                    spawnServer();
+            })();
         });
     }
     console.log(`[supervisor] started (pid ${process.pid})`);