@lelouchhe/webagent 0.3.0 → 0.5.1

package/dist/sw.js

@@ -1,12 +1,20 @@
 // Minimal service worker for PWA installability + push notifications.
 // No offline caching — app requires SSE connection.
 
-self.addEventListener('install', () => self.skipWaiting());
-self.addEventListener('activate', (e) => e.waitUntil(self.clients.claim()));
+self.addEventListener("install", () => self.skipWaiting());
+self.addEventListener("activate", (e) => e.waitUntil(self.clients.claim()));
 
 // --- Push notifications ---
+//
+// Two payload shapes from the server:
+//   { kind: "notify", title, body, tag, data }  → showNotification
+//   { kind: "close",  tag }                      → close any existing
+//                                                  notifications with that
+//                                                  tag (cross-device recall
+//                                                  for acked/consumed inbox
+//                                                  messages).
 
-self.addEventListener('push', (e) => {
+self.addEventListener("push", (e) => {
   if (!e.data) return;
 
   let payload;
@@ -16,36 +24,80 @@ self.addEventListener('push', (e) => {
     return;
   }
 
-  const { title, body, data } = payload;
-  e.waitUntil(
-    self.registration.showNotification(title || 'WebAgent', {
-      body: body || '',
-      icon: '/icon-192.png',
-      badge: '/icon-192.png',
-      tag: data?.sessionId || 'default',
-      data: data || {},
-    })
-  );
+  if (payload.kind === "close" && payload.tag) {
+    e.waitUntil(closeByTag(payload.tag));
+    return;
+  }
+
+  // Backward-compat: older payloads had no `kind`. Treat as notify.
+  const { title, body, tag, data } = payload;
+  const finalTag = tag || data?.sessionId || "default";
+  e.waitUntil(showNotify(title, body, finalTag, data));
+});
+
+// iOS Safari's tag-based notification collapse in showNotification is
+// unreliable: notifications stack in Notification Center even with
+// identical tag. The community-standard workaround is to explicitly close
+// any existing same-tag notifications in the SW before showing the new
+// one. Harmless on conformant platforms (they already replace).
+//
+// NOTE: In iOS 17 PWA dogfood this workaround did NOT actually collapse
+// banners either — two same-tag pushes still produced two banners. The
+// underlying cause appears to be in WebKit / APNs and is outside our
+// control. We keep this code because (a) it's correct per the Web
+// Notifications spec, (b) it works on Chrome/Firefox/Android, and
+// (c) future iOS versions may honor it.
+async function showNotify(title, body, tag, data) {
+  const existing = await self.registration.getNotifications({ tag });
+  for (const n of existing) n.close();
+  await self.registration.showNotification(title || "WebAgent", {
+    body: body || "",
+    icon: "/icon-192.png",
+    badge: "/icon-192.png",
+    tag,
+    data: data || {},
+  });
+}
+
+async function closeByTag(tag) {
+  const notifications = await self.registration.getNotifications({ tag });
+  for (const n of notifications) n.close();
+}
+
+// Allow page-side code to request close of a message-tagged notification
+// (frontend dispatches this on `message_acked` / `message_consumed` so the
+// local device's banner disappears without waiting for the server's silent
+// close push).
+self.addEventListener("message", (e) => {
+  const msg = e.data;
+  if (msg && msg.type === "close-notification" && msg.tag) {
+    e.waitUntil(closeByTag(msg.tag));
+  }
 });
 
-self.addEventListener('notificationclick', (e) => {
+self.addEventListener("notificationclick", (e) => {
   e.notification.close();
 
-  const sessionId = e.notification.data?.sessionId;
-  const urlHash = sessionId ? `/#${sessionId}` : '/';
+  const data = e.notification.data || {};
+  // For inbox messages, route to the bound session (if set) or root.
+  // For session events, route to the session.
+  const sessionId = data.sessionId;
+  const urlHash = sessionId ? `/#${sessionId}` : "/";
 
   e.waitUntil(
-    self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then((clients) => {
-      // Focus existing window if open
-      for (const client of clients) {
-        if (client.url.includes(self.location.origin)) {
-          client.focus();
-          client.postMessage({ type: 'navigate', sessionId });
-          return;
+    self.clients
+      .matchAll({ type: "window", includeUncontrolled: true })
+      .then((clients) => {
+        // Focus existing window if open
+        for (const client of clients) {
+          if (client.url.includes(self.location.origin)) {
+            client.focus();
+            client.postMessage({ type: "navigate", sessionId });
+            return;
+          }
         }
-      }
-      // Otherwise open a new window
-      return self.clients.openWindow(urlHash);
-    })
+        // Otherwise open a new window
+        return self.clients.openWindow(urlHash);
+      }),
   );
 });

package/dist/theme-init.js

@@ -0,0 +1,6 @@
+// Set theme attribute synchronously before stylesheet renders, to avoid FOUC.
+// Extracted from inline <script> so a strict CSP `script-src 'self'` works.
+document.documentElement.setAttribute(
+  "data-theme",
+  localStorage.getItem("theme") || "auto",
+);

package/lib/agent-detect.js

@@ -0,0 +1,110 @@
+// Agent auto-detection.
+//
+// When `agent_cmd` is the sentinel "auto" (the new default), we scan PATH
+// in two passes:
+//
+//   L1 — ACP-ready binaries that speak the protocol directly. First hit
+//        wins; we return its exact run command. Order is by perceived
+//        popularity / native-vs-wrapper, not alphabetical — see comments
+//        on each row.
+//
+//   L2 — Bare vendor CLIs whose ACP support requires a separate adapter
+//        package. We don't auto-`npx` them (silent network downloads /
+//        supply-chain trust / startup latency are all real costs); we
+//        just tell the user which adapter to install.
+//
+// If a user explicitly set `agent_cmd` in their TOML, this module is
+// skipped — explicit config always wins. Detection is a first-run
+// affordance, not a policy.
+import { spawnSync } from "node:child_process";
+// L1: ACP-ready binaries. Each row is "if `bin` is in PATH, run `cmd`".
+// Verified against https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json.
+export const L1_CANDIDATES = [
+    { bin: "copilot", cmd: "copilot --acp", label: "GitHub Copilot CLI" },
+    { bin: "gemini", cmd: "gemini --acp", label: "Gemini CLI" },
+    { bin: "opencode", cmd: "opencode acp", label: "OpenCode" },
+    {
+        bin: "claude-agent-acp",
+        cmd: "claude-agent-acp",
+        label: "Claude Code (via ACP adapter)",
+    },
+    { bin: "codex-acp", cmd: "codex-acp", label: "Codex (via ACP adapter)" },
+    {
+        bin: "qwen",
+        cmd: "qwen --acp --experimental-skills",
+        label: "Qwen Code",
+    },
+];
+// L2: Bare vendor CLIs that need a separate adapter to speak ACP.
+export const L2_CANDIDATES = [
+    {
+        bin: "claude",
+        label: "Claude Code",
+        adapter: "@agentclientprotocol/claude-agent-acp",
+        install: "npm i -g @agentclientprotocol/claude-agent-acp",
+    },
+    {
+        bin: "codex",
+        label: "Codex",
+        adapter: "@zed-industries/codex-acp",
+        install: "npm i -g @zed-industries/codex-acp",
+    },
+];
+function inPath(bin) {
+    const which = process.platform === "win32" ? "where" : "which";
+    try {
+        const r = spawnSync(which, [bin], { stdio: "ignore" });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectAgent() {
+    for (const c of L1_CANDIDATES) {
+        if (inPath(c.bin)) {
+            return { ok: true, cmd: c.cmd, bin: c.bin, label: c.label };
+        }
+    }
+    for (const c of L2_CANDIDATES) {
+        if (inPath(c.bin)) {
+            return {
+                ok: false,
+                kind: "l2-hint",
+                bin: c.bin,
+                label: c.label,
+                adapter: c.adapter,
+                install: c.install,
+            };
+        }
+    }
+    return { ok: false, kind: "none" };
+}
+// Format a multi-line, copy-pasteable hint for the operator. server.ts
+// prints this verbatim and exits non-zero when detection fails.
+export function formatDetectionFailure(result) {
+    if (result.kind === "l2-hint") {
+        return [
+            `[bridge] detected ${result.label} (${result.bin}) but no ACP adapter.`,
+            ``,
+            `  Install the adapter to use ${result.label} with webagent:`,
+            `    ${result.install}`,
+            ``,
+            `  Or set agent_cmd in config.toml to a different ACP agent.`,
+        ].join("\n");
+    }
+    return [
+        `[bridge] no ACP-ready agent found in PATH.`,
+        ``,
+        `  Install one of:`,
+        `    npm i -g @github/copilot          # Copilot CLI`,
+        `    npm i -g @google/gemini-cli       # Gemini CLI`,
+        `    npm i -g opencode-ai              # OpenCode`,
+        ``,
+        `  Or for Claude Code / Codex, install the ACP adapter:`,
+        `    npm i -g @agentclientprotocol/claude-agent-acp`,
+        `    npm i -g @zed-industries/codex-acp`,
+        ``,
+        `  Then re-run webagent (or set agent_cmd in config.toml).`,
+    ].join("\n");
+}

package/lib/atomic-write.js

@@ -0,0 +1,50 @@
+// Atomic file writes via tmp + rename(2).
+//
+// rename(2) is atomic within a filesystem on POSIX (and on Windows on the
+// same volume), so concurrent readers only ever see the old file, the new
+// file, or ENOENT — never a half-written or zero-length file. Plain
+// writeFile is open(O_TRUNC) → write → close, which exposes a
+// truncate-but-not-yet-written race window where polling readers see ""
+// and crash on JSON.parse. The flake that motivated extracting this
+// helper was test/daemon.test.ts reading the PID file mid-write.
+//
+// Used for the daemon PID file (`webagent.pid`) and the auth token store
+// (`auth.json`). Both have a single writer process, so no inter-process
+// lock is needed — just atomicity against a polling reader.
+//
+// proper-lockfile is also a dependency in this repo but it provides
+// inter-process *locking* (sentinel-dir semaphore), not atomic writes.
+// Locking plus naive writeFile would still expose the truncate race to
+// readers that don't hold the lock.
+import { writeFileSync, renameSync, chmodSync } from "node:fs";
+import { open, chmod, rename } from "node:fs/promises";
+/**
+ * Synchronous atomic write. Used in code paths where awaiting isn't
+ * convenient (e.g. supervisor bootstrap before signal handlers are
+ * installed).
+ */
+export function atomicWriteFileSync(path, data, mode) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, data, mode != null ? { mode } : undefined);
+    if (mode != null)
+        chmodSync(tmp, mode);
+    renameSync(tmp, path);
+}
+/**
+ * Async atomic write. `mode` is applied via open()'s mode arg AND a
+ * follow-up chmod so the final file ends up with the desired perms
+ * regardless of umask or whether the temp file pre-existed.
+ */
+export async function atomicWriteFile(path, data, mode) {
+    const tmp = `${path}.tmp`;
+    const fh = await open(tmp, "w", mode);
+    try {
+        await fh.writeFile(data);
+    }
+    finally {
+        await fh.close();
+    }
+    if (mode != null)
+        await chmod(tmp, mode);
+    await rename(tmp, path);
+}

package/lib/attachment-dispatch.js

@@ -0,0 +1,86 @@
+import { readFile, realpath } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { isInsideSessionAttachments } from "./sessions-anchor.js";
+const NOOP_LOGGER = { warn: () => { } };
+/**
+ * Builds the ACP prompt block for one client-supplied attachment. Returns
+ * a fallback text block on any failure (DB miss, disk miss, anchor breach,
+ * cross-session reference) so the prompt turn never gets stuck in a retry
+ * loop just because one image vanished.
+ *
+ * Trust boundary (decision 10 in uploads-plan v2.6): client only supplies
+ * `attachmentId`. Everything else (realpath, anchor, MIME for read) comes
+ * from the server-side row.
+ */
+export class AttachmentDispatcher {
+    store;
+    sessionsAnchor;
+    logger;
+    constructor(store, sessionsAnchor, logger = NOOP_LOGGER) {
+        this.store = store;
+        this.sessionsAnchor = sessionsAnchor;
+        this.logger = logger;
+    }
+    async dispatch(sessionId, ref) {
+        const fallback = (reason) => {
+            this.logger.warn(`[attachments] dispatch fallback (${reason}) for ${sessionId}/${ref.attachmentId}`);
+            return {
+                type: "text",
+                text: `[attachment removed: ${ref.displayName}]`,
+            };
+        };
+        // Reject any client trying to smuggle a uri / data / path. The shape
+        // of AttachmentRef already forbids these statically; this guard is a
+        // belt-and-suspenders for callers passing a wider object via `as any`.
+        const wider = ref;
+        if (typeof wider.uri === "string" ||
+            typeof wider.data === "string" ||
+            typeof wider.path === "string") {
+            return fallback("client_supplied_external_field");
+        }
+        const row = this.store.getAttachment(sessionId, ref.attachmentId);
+        if (!row)
+            return fallback("row_not_found");
+        // Cross-session reference — the row exists but for a DIFFERENT session.
+        // store.getAttachment scopes by session_id so this should already be
+        // caught by row_not_found, but assert defensively.
+        if (row.session_id !== sessionId) {
+            return fallback("cross_session");
+        }
+        // Anchor check on the stored realpath. If the file was moved out from
+        // under us, or a future bug let an attacker inject a row with a path
+        // outside SESSIONS_ANCHOR/<sid>/attachments/, we MUST refuse to dispatch
+        // it as a `file://` URI — the agent would happily read it.
+        let resolvedPath;
+        try {
+            resolvedPath = await realpath(row.realpath);
+        }
+        catch {
+            return fallback("realpath_failed");
+        }
+        if (!isInsideSessionAttachments(this.sessionsAnchor, sessionId, resolvedPath)) {
+            return fallback("path_outside_anchor");
+        }
+        if (ref.kind === "image") {
+            try {
+                const buf = await readFile(resolvedPath);
+                return {
+                    type: "image",
+                    data: buf.toString("base64"),
+                    mimeType: row.mime,
+                };
+            }
+            catch {
+                return fallback("read_failed");
+            }
+        }
+        // kind === "file" → ACP resource_link with file:// URI built from the
+        // realpath (NOT from any client-supplied string).
+        return {
+            type: "resource_link",
+            uri: pathToFileURL(resolvedPath).toString(),
+            name: row.name,
+            mimeType: row.mime,
+        };
+    }
+}

package/lib/attachment-interceptor.js

@@ -0,0 +1,130 @@
+// Permission auto-approve interceptor for attachment reads.
+//
+// Plan §1.4 (uploads-plan v2.6, lines 105-183). When an agent requests
+// permission to *read* a path that we know is one of the user-uploaded
+// session attachments, auto-approve with `allow_once`. Any deviation
+// from the strict allowlist falls through to the user prompt.
+//
+// Defenses (mirrored from the plan):
+//   F1 kind === "read" only
+//   F2 every locations[].path realpath ∈ session attachment realpaths
+//   F4 schema gate — locations must exist; if rawInput has known path
+//      keys they must also realpath into the attachment set; if it has
+//      none, allow but bump schemaDrift counter so we notice when the
+//      Copilot CLI changes its raw-input field names.
+//   F6 any realpath / DB error → fall through (deny auto-approve, not
+//      deny the user — the user dialog still shows)
+//   F7 four counters, dumped hourly via attachInterceptorLogger.
+import { realpath as fsRealpath } from "node:fs/promises";
+const READ_TOOL_ALLOWLIST = new Set(["view", "read_file"]);
+const RAWINPUT_PATH_KEYS = ["path", "filePath", "file"];
+export function createCounters() {
+    return {
+        autoAllowed: 0,
+        fellThrough: 0,
+        realpathErrors: 0,
+        schemaDrift: 0,
+    };
+}
+async function checkLocationPaths(locations, attachmentRealpaths, counters, log, miss) {
+    for (const loc of locations) {
+        let rp;
+        try {
+            rp = await fsRealpath(loc.path);
+        }
+        catch (e) {
+            counters.realpathErrors++;
+            log.warn?.("attachment interceptor realpath error", {
+                path: loc.path,
+                error: e.code ?? e.message,
+            });
+            return miss("realpath_failed");
+        }
+        if (!attachmentRealpaths.has(rp))
+            return miss("path_not_in_attachments");
+    }
+    return true;
+}
+async function checkRawInputPaths(raw, attachmentRealpaths, miss) {
+    let foundAnyKey = false;
+    for (const key of RAWINPUT_PATH_KEYS) {
+        const v = raw[key];
+        if (typeof v !== "string")
+            continue;
+        foundAnyKey = true;
+        let rp;
+        try {
+            rp = await fsRealpath(v);
+        }
+        catch {
+            return { ok: false, result: miss("rawinput_realpath_failed") };
+        }
+        if (!attachmentRealpaths.has(rp)) {
+            return { ok: false, result: miss("rawinput_path_mismatch") };
+        }
+    }
+    return { ok: true, foundAnyKey };
+}
+/**
+ * Returns true iff the request matches the strict
+ * "agent reading a known session attachment" pattern.
+ *
+ * Returning false does NOT deny the user prompt — it just declines to
+ * auto-approve, so the normal permission UI continues to render.
+ */
+export async function shouldAutoApproveAttachmentRead(ev, deps) {
+    const { counters, logger } = deps;
+    const log = logger ?? {};
+    const miss = (reason) => {
+        counters.fellThrough++;
+        log.debug?.("attachment auto-allow miss", {
+            reason,
+            sessionId: ev.sessionId,
+            toolKind: ev.toolKind,
+            toolName: ev.toolName,
+        });
+        return false;
+    };
+    if (ev.toolKind !== "read")
+        return miss("tool_kind_not_read");
+    if (typeof ev.toolName === "string" &&
+        !READ_TOOL_ALLOWLIST.has(ev.toolName)) {
+        return miss("tool_name_not_allowlisted");
+    }
+    if (!Array.isArray(ev.locations) || ev.locations.length === 0) {
+        return miss("no_locations");
+    }
+    let attachmentRealpaths;
+    try {
+        attachmentRealpaths = new Set(deps.listAttachmentRealpaths(ev.sessionId));
+    }
+    catch (e) {
+        log.warn?.("attachment interceptor db error", {
+            sessionId: ev.sessionId,
+            error: e.message,
+        });
+        return miss("db_error");
+    }
+    const locOk = await checkLocationPaths(ev.locations, attachmentRealpaths, counters, log, miss);
+    if (locOk !== true)
+        return locOk;
+    const raw = ev.rawInput;
+    if (raw && typeof raw === "object") {
+        const r = await checkRawInputPaths(raw, attachmentRealpaths, miss);
+        if (!r.ok)
+            return r.result;
+        if (!r.foundAnyKey) {
+            counters.schemaDrift++;
+            log.warn?.("attachment interceptor schema drift: rawInput has no known path key", { rawInputKeys: Object.keys(raw) });
+            deps.onSchemaDrift?.({ rawInputKeys: Object.keys(raw) });
+        }
+    }
+    counters.autoAllowed++;
+    log.info?.("attachment auto-allowed", {
+        sessionId: ev.sessionId,
+        toolKind: ev.toolKind,
+        toolName: ev.toolName,
+        locations: ev.locations.map((l) => l.path),
+    });
+    return true;
+}

package/lib/attachment-labels.js

@@ -0,0 +1,139 @@
+import { basename } from "node:path";
+/**
+ * Build a label map from raw attachment rows. Keys: realpath +
+ * basename(realpath). Value: `<name> [#<id4>]`.
+ *
+ * `id` is sliced to 4 chars unconditionally — the post-hoc
+ * disambiguation suffix doubles as a stable reference anchor in
+ * conversation ("the abc1 file"). No collision detection.
+ */
+export function buildLabelMap(rows) {
+    const m = new Map();
+    for (const r of rows) {
+        const label = `${r.name} [#${r.id.slice(0, 4)}]`;
+        m.set(r.realpath, label);
+        const bn = basename(r.realpath);
+        // Don't shadow an existing realpath entry. Realpaths are
+        // absolute so collision with a basename is extremely rare; this
+        // is defensive only.
+        if (!m.has(bn))
+            m.set(bn, label);
+    }
+    return m;
+}
+/** Substring-replace each map key with its label. Longer keys first
+ *  so the basename entry doesn't clobber a full-path occurrence. */
+function rewriteString(s, map) {
+    if (map.size === 0)
+        return s;
+    // Sort keys descending by length: ensures e.g. `/a/b/file.pdf`
+    // gets replaced before its `file.pdf` basename.
+    const keys = [...map.keys()].sort((a, b) => b.length - a.length);
+    let out = s;
+    for (const k of keys) {
+        if (!out.includes(k))
+            continue;
+        out = out.split(k).join(map.get(k) ?? "");
+    }
+    return out;
+}
+/**
+ * Replace internal uuid attachment paths with user-visible labels
+ * in the fields users see. Pure: returns a new event object when
+ * any field changed, otherwise the original reference.
+ *
+ * Touched:
+ *  - `tool_call.title`            (substring rewrite)
+ *  - `tool_call.rawInput.path`    (exact-match replace)
+ *  - `permission_request.title`   (substring rewrite)
+ *
+ * NOT touched (deliberate):
+ *  - `permission_request.rawInput` — F2 interceptor
+ *    (`attachment-interceptor.ts`) authoritatively reads this for
+ *    realpath-equality auto-approve. Mutating it here would silently
+ *    break the security gate even though enrich runs after the
+ *    decision today; future read paths must not be poisoned.
+ *  - `permission_request.locations[].path` — ACP protocol field,
+ *    not user-visible in our UI.
+ *  - `user_message.attachments[].displayName` — rendered as
+ *    `<a class="user-file" download>` link, modality is different.
+ *  - All other event types — pass through.
+ */
+export function enrichEventForDisplay(event, map) {
+    if (map.size === 0)
+        return event;
+    if (event.type === "tool_call") {
+        const newTitle = rewriteString(event.title, map);
+        let newRawInput = event.rawInput;
+        if (event.rawInput &&
+            typeof event.rawInput === "object" &&
+            typeof event.rawInput.path === "string") {
+            const replaced = map.get(event.rawInput.path);
+            if (replaced) {
+                newRawInput = { ...event.rawInput, path: replaced };
+            }
+        }
+        if (newTitle !== event.title || newRawInput !== event.rawInput) {
+            return { ...event, title: newTitle, rawInput: newRawInput };
+        }
+        return event;
+    }
+    if (event.type === "permission_request") {
+        const newTitle = rewriteString(event.title, map);
+        if (newTitle !== event.title) {
+            return { ...event, title: newTitle };
+        }
+        return event;
+    }
+    return event;
+}
+/**
+ * JSON-string variant of `enrichEventForDisplay` for the replay
+ * path: `store.getEvents()` returns rows whose `data` is a JSON
+ * string and whose `type` lives in a sibling column. Same chokepoint
+ * spirit as `reSignAttachmentUrlsInJson` in auth.ts.
+ *
+ * Mutates `row.data` in place when enrichment changes anything
+ * (returning the row unchanged otherwise).
+ */
+export function enrichStoredEventDataForDisplay(type, data, map) {
+    if (map.size === 0)
+        return data;
+    if (type !== "tool_call" && type !== "permission_request")
+        return data;
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return data;
+    }
+    // Synthesize a minimal event shape so we can reuse the object-level
+    // enricher. `sessionId` etc. don't matter to enrich logic.
+    const ev = { type, ...parsed };
+    const out = enrichEventForDisplay(ev, map);
+    if (out === ev)
+        return data;
+    // Strip the synthesized `type` to match the stored shape.
+    const { type: _t, ...rest } = out;
+    void _t;
+    return JSON.stringify(rest);
+}
+/**
+ * Replay-path egress chokepoint: rewrites each stored event row's
+ * `data` field with attachment labels in place. Mutates rows.
+ *
+ * Use anywhere `store.getEvents` results are sent to clients
+ * (history GET, share viewer). Live SSE goes through
+ * `SseManager.sendEvent` which has its own object-level enricher.
+ */
+export function enrichStoredEventsForDisplay(events, map) {
+    if (map.size === 0)
+        return events;
+    for (const ev of events) {
+        if (typeof ev.data === "string") {
+            ev.data = enrichStoredEventDataForDisplay(ev.type, ev.data, map);
+        }
+    }
+    return events;
+}