@lelouchhe/webagent 0.4.0 → 0.6.0

package/lib/client-registry.js

@@ -3,28 +3,37 @@
  *
  * Tracks per-client metadata that survives SSE disconnect:
  *   - capabilities advertised by the client on /hello.
- *   - focus: clientId's current sessionId (set via /focus). Used by push
- *     visibility suppression to know which session each client is viewing.
+ *   - 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 /focus when
- * they switch sessions. 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.
+ * 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 = Date.now();
+            existing.lastSeen = this.now();
             return existing;
         }
         const entry = {
             id,
             capabilities: data.capabilities,
-            focus: null,
-            lastSeen: Date.now(),
+            visible: false,
+            active: null,
+            visibleSince: 0,
+            lastSeen: this.now(),
         };
         this.clients.set(id, entry);
         return entry;
@@ -32,24 +41,104 @@ export class ClientRegistry {
     remove(id) {
         this.clients.delete(id);
     }
-    setFocus(id, sessionId) {
+    /**
+     * 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;
-        entry.focus = sessionId;
-        entry.lastSeen = Date.now();
+            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 = Date.now();
+        entry.lastSeen = this.now();
     }
     touch(id) {
         const entry = this.clients.get(id);
         if (entry)
-            entry.lastSeen = Date.now();
+            entry.lastSeen = this.now();
     }
     get(id) {
         return this.clients.get(id);

package/lib/config.js

@@ -3,6 +3,13 @@ import { parse as parseTOML } from "smol-toml";
 import { z } from "zod";
 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"),
@@ -35,7 +42,7 @@ export const ConfigSchema = z.object({
     }),
     // [title] — title generation sub-session configuration.
     //
-    // `model` is an array of case-insensitive substring patterns. When the
+    // `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
@@ -50,17 +57,17 @@ export const ConfigSchema = z.object({
     //   - "flash"      → Google Gemini (gemini-*-flash)
     //   - "lite"       → Cohere, generic
     //
-    // Set `model = []` to disable substring matching entirely and always
+    // 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: `model = ["claude-haiku-4.5"]`.
+    // single-element array: `models = ["claude-haiku-4.5"]`.
     title: z
         .object({
-        model: z
+        models: z
             .array(z.string())
             .default(["haiku", "flash-lite", "nano", "mini", "flash", "lite"]),
     })
         .default({
-        model: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
+        models: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
     }),
     // [debug] — frontend log level.
     // level ∈ off | debug | info | warn | error. Default "off".

package/lib/event-handler.js

@@ -14,7 +14,9 @@ function handleConfigLikeEvent(event, sessions, store) {
     if (event.configOptions.length)
         sessions.cachedConfigOptions = event.configOptions;
     for (const opt of event.configOptions) {
-        store.updateSessionConfig(event.sessionId, opt.id, opt.currentValue);
+        if (typeof opt.currentValue === "string") {
+            store.updateSessionConfig(event.sessionId, opt.id, opt.currentValue);
+        }
     }
 }
 function handleMessageChunk(event, sessions) {

package/lib/image-dimensions.js

@@ -0,0 +1,64 @@
+function valid(width, height) {
+    if (!Number.isInteger(width) || !Number.isInteger(height))
+        return null;
+    if (width <= 0 || height <= 0)
+        return null;
+    return { width, height };
+}
+export function readImageDimensions(buf) {
+    return (readPngDimensions(buf) ?? readGifDimensions(buf) ?? readJpegDimensions(buf));
+}
+function readPngDimensions(buf) {
+    // PNG: signature + IHDR width/height at fixed offsets.
+    if (buf.length >= 24 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47 &&
+        buf.toString("ascii", 12, 16) === "IHDR") {
+        return valid(buf.readUInt32BE(16), buf.readUInt32BE(20));
+    }
+    return null;
+}
+function readGifDimensions(buf) {
+    // GIF87a/GIF89a: logical screen width/height, little-endian.
+    if (buf.length >= 10 &&
+        (buf.toString("ascii", 0, 6) === "GIF87a" ||
+            buf.toString("ascii", 0, 6) === "GIF89a")) {
+        return valid(buf.readUInt16LE(6), buf.readUInt16LE(8));
+    }
+    return null;
+}
+function isJpegSofMarker(marker) {
+    return ((marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf));
+}
+function readJpegDimensions(buf) {
+    // JPEG: scan marker segments until a SOF marker carrying dimensions.
+    if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+        let offset = 2;
+        while (offset + 3 < buf.length) {
+            if (buf[offset] !== 0xff) {
+                offset++;
+                continue;
+            }
+            while (offset < buf.length && buf[offset] === 0xff)
+                offset++;
+            const marker = buf[offset++];
+            if (marker === 0xd9 || marker === 0xda)
+                break;
+            if (offset + 1 >= buf.length)
+                break;
+            const length = buf.readUInt16BE(offset);
+            if (length < 2 || offset + length > buf.length)
+                break;
+            if (isJpegSofMarker(marker) && length >= 7) {
+                return valid(buf.readUInt16BE(offset + 5), buf.readUInt16BE(offset + 3));
+            }
+            offset += length;
+        }
+    }
+    return null;
+}

package/lib/model-picker.js

@@ -0,0 +1,17 @@
+/** Find the first available model whose id matches any pattern. */
+export function pickModelByPatterns(configOptions, patterns) {
+    const normalized = patterns
+        .map((p) => p.trim().toLowerCase())
+        .filter((p) => p.length > 0);
+    if (normalized.length === 0)
+        return null;
+    const modelOpt = configOptions.find((c) => c.id === "model" && "options" in c);
+    if (!modelOpt || modelOpt.options.length === 0)
+        return null;
+    for (const pattern of normalized) {
+        const hit = modelOpt.options.find((o) => o.value.toLowerCase().includes(pattern));
+        if (hit)
+            return hit.value;
+    }
+    return null;
+}

package/lib/preflight.js

@@ -120,52 +120,71 @@ function checkAgent(agentCmd) {
     };
 }
 /**
- * Probe whether `port` can be bound on 0.0.0.0 (matching what
- * `server.listen` actually uses). Listens, then closes immediately.
- * There's a tiny race window between close and the real
- * server.listen() — that's fine for diagnostics: the goal is a friendly
- * "port already in use" hint, not a hard guarantee.
+ * Probe whether `host:port` can be bound (matching what `server.listen`
+ * actually uses). Listens, then closes immediately. There's a tiny
+ * race window between close and the real server.listen() — that's
+ * fine for diagnostics: the goal is a friendly hint, not a hard
+ * guarantee.
  *
  * Port 0 means "let the OS pick"; we treat it as always-free.
+ *
+ * Probing the same host as the real server matters: a foreign
+ * listener on 0.0.0.0:PORT occupies 127.0.0.1:PORT too (more-specific
+ * bind fails when wildcard already bound), so binding the configured
+ * host catches conflicts and surfaces EADDRNOTAVAIL when the user
+ * typo'd an IP that isn't on any local interface.
  */
-async function checkPort(port) {
-    if (port === 0) {
-        return { ok: true, name: "port", detail: "0 (OS-assigned)" };
-    }
-    // Probe must bind to the same address family as the real server
-    // (server.ts uses "0.0.0.0"). Probing 127.0.0.1 lets a foreign
-    // listener on 0.0.0.0:PORT slip past preflight and only surface as
-    // EADDRINUSE during the real server.listen() — exactly the case
-    // we're trying to catch.
+async function checkPort(port, host) {
+    const label = `${host}:${port}`;
+    // port=0 still gets probed: the OS picks any free port, but bind can
+    // still fail with EADDRNOTAVAIL if `host` isn't on any local
+    // interface — that's exactly the typo we want to catch.
     const result = await new Promise((settle) => {
         const probe = createServer();
         probe.once("error", (err) => {
             settle({ code: err.code ?? "unknown" });
         });
-        probe.listen(port, "0.0.0.0", () => {
+        probe.listen(port, host, () => {
+            const addr = probe.address();
+            const assigned = typeof addr === "object" && addr ? addr.port : port;
             probe.close(() => {
-                settle({});
+                settle({ assigned });
             });
         });
     });
     if (!result.code) {
-        return { ok: true, name: "port", detail: String(port) };
+        if (port === 0) {
+            return {
+                ok: true,
+                name: "port",
+                detail: `${host}:0 (OS-assigned → ${result.assigned})`,
+            };
+        }
+        return { ok: true, name: "port", detail: label };
     }
     if (result.code === "EADDRINUSE") {
         return {
             ok: false,
             name: "port",
-            detail: `${port} (in use)`,
-            hint: `port ${port} is already in use (EADDRINUSE).\nfind the owner: ${process.platform === "win32"
+            detail: `${label} (in use)`,
+            hint: `${label} is already in use (EADDRINUSE).\nfind the owner: ${process.platform === "win32"
                 ? `netstat -ano | findstr :${port}`
                 : `lsof -nP -iTCP:${port} -sTCP:LISTEN`}\nor change \`port\` in config.toml to a free port.`,
         };
     }
+    if (result.code === "EADDRNOTAVAIL") {
+        return {
+            ok: false,
+            name: "port",
+            detail: `${label} (${result.code})`,
+            hint: `cannot bind ${label}: ${result.code}\nthe host '${host}' is not assigned to any local interface.\ncheck \`host\` in config.toml — typical values are "127.0.0.1" (loopback) or "0.0.0.0" (all interfaces).`,
+        };
+    }
     return {
         ok: false,
         name: "port",
-        detail: `${port} (${result.code})`,
-        hint: `cannot bind port ${port}: ${result.code}\ncheck firewall / permissions, or change \`port\` in config.toml.`,
+        detail: `${label} (${result.code})`,
+        hint: `cannot bind ${label}: ${result.code}\ncheck firewall / permissions, or change \`host\`/\`port\` in config.toml.`,
     };
 }
 /**
@@ -179,7 +198,7 @@ export async function runPreflight(opts) {
     checks.push(checkDataDir(opts.data_dir));
     const agent = checkAgent(opts.agent_cmd);
     checks.push(agent);
-    checks.push(await checkPort(opts.port));
+    checks.push(await checkPort(opts.port, opts.host));
     for (const c of checks) {
         if (c.ok)
             printOk(c);

package/lib/push-service.js

@@ -46,18 +46,14 @@ export function isAppleEndpoint(endpoint) {
     return host === "web.push.apple.com" || host.endsWith(".push.apple.com");
 }
 function emptyClientState() {
-    return { visible: false, sessionId: null, endpoint: null, visibleSince: 0 };
+    return { endpoint: null };
 }
 export class PushService {
     store;
     vapidKeys;
     /**
-     * Consolidated per-client state. Previously 3 separate Maps
-     * (clientVisibility/clientEndpoints/clientSessions) which drifted under
-     * partial updates. v2 merges them; `visibleSince` stamps when the client
-     * transitioned to visible so the server can TTL-expire "ghost" visibility
-     * records left by iOS PWA process suspension (where the client never gets
-     * to POST visible:false).
+     * Per-client transport state — only the push endpoint. Visibility lives
+     * in ClientRegistry as of Plan C Step 4.
      */
     clients = new Map();
     /** endpoint → consecutive failure count (absent or 0 = healthy) */
@@ -65,7 +61,8 @@ export class PushService {
     globalVisibilitySuppression;
     visibilityTtlMs;
     now;
-    constructor(store, dataDir, vapidSubject, options = {}) {
+    clientRegistry;
+    constructor(store, dataDir, vapidSubject, options) {
         this.store = store;
         this.vapidKeys = this.loadOrGenerateKeys(dataDir);
         webpush.setVapidDetails(vapidSubject, this.vapidKeys.publicKey, this.vapidKeys.privateKey);
@@ -73,6 +70,7 @@ export class PushService {
             options.globalVisibilitySuppression ?? true;
         this.visibilityTtlMs = options.visibilityTtlMs ?? 60_000;
         this.now = options.now ?? (() => Date.now());
+        this.clientRegistry = options.clientRegistry;
     }
     // ---------------------------------------------------------------------------
     // VAPID keys
@@ -123,43 +121,18 @@ export class PushService {
         return { kind: "notify", title, body, tag, data: { sessionId } };
     }
     // ---------------------------------------------------------------------------
-    // Client visibility tracking
+    // Endpoint mapping (transport-only as of Plan C Step 4)
     // ---------------------------------------------------------------------------
     /**
-     * Atomic consolidated setter. All visibility/session/endpoint updates
-     * should route through here. Callers distinguish "preserve" from "clear"
-     * by omitting the key vs passing `null`. Returns an edge flag so the
-     * caller can fire edge-triggered side effects (e.g. sendClose) without
-     * double-firing on every heartbeat refresh.
+     * Set the push endpoint for a client. Identity-layer state (visibility,
+     * active session) goes through ClientRegistry.setVisibility, not here.
      */
     updateClient(clientId, patch) {
         const prev = this.clients.get(clientId) ?? emptyClientState();
-        const wasVisibleForSession = prev.visible && prev.sessionId != null ? prev.sessionId : null;
         const next = { ...prev };
-        if (patch.visible !== undefined) {
-            next.visible = patch.visible;
-            next.visibleSince = patch.visible ? this.now() : 0;
-        }
-        if (patch.sessionId !== undefined)
-            next.sessionId = patch.sessionId;
         if (patch.endpoint !== undefined)
             next.endpoint = patch.endpoint;
-        const becameVisibleForSession = next.visible &&
-            next.sessionId != null &&
-            next.sessionId !== wasVisibleForSession
-            ? next.sessionId
-            : null;
-        // Any transition into "visible + session X" restarts the TTL clock,
-        // including a session-switch that arrives without an explicit
-        // visible:true in the patch (e.g. a session_created POST that only
-        // carries sessionId). Otherwise the TTL would keep counting from the
-        // previous session's first-visible moment and could prematurely
-        // declare the newly-focused session "stale".
-        if (becameVisibleForSession) {
-            next.visibleSince = this.now();
-        }
         this.clients.set(clientId, next);
-        return { becameVisibleForSession };
     }
     /**
      * Read-only snapshot for tests and diagnostics. Do NOT mutate the
@@ -168,40 +141,29 @@ export class PushService {
     getClientState(clientId) {
         return this.clients.get(clientId) ?? null;
     }
-    /** @deprecated Shim: prefer `updateClient({ visible })`. */
-    setClientVisibility(clientId, visible) {
-        this.updateClient(clientId, { visible });
-    }
-    /** @deprecated Shim: prefer `updateClient({ sessionId })`. */
-    setClientSession(clientId, sessionId) {
-        this.updateClient(clientId, { sessionId });
-    }
-    /** @deprecated Shim: prefer `updateClient({ endpoint })`. */
     registerClient(clientId, endpoint) {
         this.updateClient(clientId, { endpoint });
     }
     removeClient(clientId) {
         this.clients.delete(clientId);
+        // Disconnect also wipes identity-layer state so visibility queries don't
+        // leak past the SSE lifetime. Production calls removeClient on SSE close
+        // (see sse-manager); tests expect the same.
+        this.clientRegistry.remove(clientId);
     }
     hasVisibleClient() {
-        const now = this.now();
-        for (const s of this.clients.values()) {
-            if (s.visible && now - s.visibleSince <= this.visibilityTtlMs)
-                return true;
-        }
-        return false;
+        return this.clientRegistry.hasAnyVisibleClient();
     }
     /** Check if a specific endpoint has at least one visible (non-stale) client. */
     isEndpointVisible(endpoint) {
-        const now = this.now();
-        for (const s of this.clients.values()) {
+        // Identity (visible) comes from registry, transport (endpoint↔clientId)
+        // stays with pushService.clients.
+        const reg = this.clientRegistry;
+        for (const [clientId, s] of this.clients) {
             if (s.endpoint !== endpoint)
                 continue;
-            if (!s.visible)
-                continue;
-            if (now - s.visibleSince > this.visibilityTtlMs)
-                continue;
-            return true;
+            if (reg.isClientVisible(clientId))
+                return true;
         }
         return false;
     }
@@ -219,17 +181,7 @@ export class PushService {
     isSessionVisibleToAnyClient(sessionId) {
         if (!this.globalVisibilitySuppression)
             return false;
-        const now = this.now();
-        for (const s of this.clients.values()) {
-            if (!s.visible)
-                continue;
-            if (s.sessionId !== sessionId)
-                continue;
-            if (now - s.visibleSince > this.visibilityTtlMs)
-                continue;
-            return true;
-        }
-        return false;
+        return this.clientRegistry.isSessionVisibleToAnyClient(sessionId);
     }
     // ---------------------------------------------------------------------------
     // High-level: decide whether to push, and if so, send