@lelouchhe/webagent 0.3.0 → 0.4.0

package/README.md

@@ -5,6 +5,24 @@
 
 A terminal-style web UI for [ACP](https://agentclientprotocol.com/)-compatible agents — Copilot CLI, Claude Code, Gemini CLI, and [more](docs/configuration.md#acp-compatible-agents).
 
+WebAgent is a thin browser client + Node.js server that lets you drive any ACP agent from a desktop browser, phone, or PWA. Sessions, permissions, and notifications stay in sync across devices; nothing leaves your machine.
+
+## Highlights
+
+- **Zero-config first run** — `npx @lelouchhe/webagent` and you're online. Auto-detects the ACP agent on your `PATH`, mints an admin token on first start, persists everything in `./data/`.
+- **Multi-device, real-time** — REST + SSE keeps sessions, permissions, and bash output synced. Approve a permission on your laptop, see it confirmed on your phone.
+- **Web Push notifications** — Get pinged on `prompt_done`, `permission_request`, or `bash_done` when the tab isn't focused. Smart per-session suppression: if any device is actively viewing session X, no buzz from session X.
+- **PWA + mobile-friendly** — Installable to iOS / Android home screen. Mobile-first input, attach via paste/upload, dark-mode native.
+- **Attachments** — Drag, paste, or `^U` any file (images, code, PDFs, …). Server sniffs real MIME from content, so agents reliably read it.
+- **Inline bash** — `!ls -la` runs directly in your session's cwd, output streams in real time, cancellable.
+- **Sessions that survive everything** — SQLite-persisted history, auto-resume on page open, auto-restore via ACP `loadSession` after server restart, auto-generated titles via a fast model.
+- **Rich slash menu** — `/new`, `/switch`, `/model`, `/mode`, `/think`, `/notify`, `/inbox`, `/share`, `/token`, `/log` — autocomplete with Tab, submenus for pickable values.
+- **Public share links** — `/share` snapshots a session into a sanitized read-only viewer at `/s/<token>` for show-and-tell.
+- **Daemon mode with crash recovery** — `webagent start` runs as a background service with PID file, log rotation, and exponential-backoff restart on crash.
+- **Built-in security** — Bearer token auth, per-device tokens, signed image URLs, strict CSP, single-operator threat model.
+
+See [Features](docs/features.md) for the full tour.
+
 <table>
   <tr>
     <td width="60%">
@@ -36,17 +54,28 @@ A terminal-style web UI for [ACP](https://agentclientprotocol.com/)-compatible a
 
 ## Quick Start
 
-**Prerequisites:** Node.js 22.6+, an ACP-compatible agent installed and authenticated.
+**Prerequisites:** Node.js 22.6+, an ACP-compatible agent installed and authenticated (Copilot CLI, Claude Code adapter, Gemini CLI, etc.).
 
 ```bash
-npm install -g @lelouchhe/webagent
-webagent                                     # start on port 6800
-webagent --config /path/to/config.toml       # custom config
+npx @lelouchhe/webagent      # zero-install, runs on port 6800
+# — or —
+npm install -g @lelouchhe/webagent && webagent
 ```
 
-Or run directly: `npx @lelouchhe/webagent`
+On first run, the server prints a one-time admin token in the startup
+diagnostic. Open `http://localhost:6800`, paste the token into the
+login form, done. The token persists in `data/auth.json` — subsequent
+runs skip the prompt.
+
+Other ways to start:
+
+```bash
+webagent start                               # background daemon (same first-run UX in your terminal)
+webagent --config /path/to/config.toml       # custom config (`webagent config init` to scaffold one)
+webagent --create-token laptop               # mint extra tokens for other devices / CI
+```
 
-Data (SQLite database, uploaded images) is stored in `./data/` by default. See [Configuration & Operations](docs/configuration.md) for daemon mode, TOML settings, and agent setup.
+Data (SQLite database, uploaded files) lives in `./data/` by default. See [Configuration & Operations](docs/configuration.md) for daemon mode, TOML settings, and agent setup.
 
 ## Architecture
 
@@ -57,14 +86,14 @@ Browser ←── REST + SSE ──→ Server ←── ACP ──→ Agent CLI
 
 The frontend is a standard browser client that talks to the server over REST + SSE. The API is the boundary — anyone can build their own client.
 
-| Module | Role |
-|---|---|
-| `routes.ts` | REST API + static files ([full API reference](docs/api.md)) |
-| `event-handler.ts` | ACP event routing → SSE broadcast |
-| `session-manager.ts` | Session state, buffers, bash processes |
-| `bridge.ts` | ACP bridge — agent subprocess lifecycle |
-| `store.ts` | SQLite persistence (WAL mode) |
-| `daemon.ts` | Background service with crash recovery |
+| Module               | Role                                                        |
+| -------------------- | ----------------------------------------------------------- |
+| `routes.ts`          | REST API + static files ([full API reference](docs/api.md)) |
+| `event-handler.ts`   | ACP event routing → SSE broadcast                           |
+| `session-manager.ts` | Session state, buffers, bash processes                      |
+| `bridge.ts`          | ACP bridge — agent subprocess lifecycle                     |
+| `store.ts`           | SQLite persistence (WAL mode)                               |
+| `daemon.ts`          | Background service with crash recovery                      |
 
 Tech stack: Node.js + TypeScript (`--experimental-strip-types`), SQLite (`better-sqlite3`), Zod validation, esbuild bundling.
 
@@ -72,12 +101,18 @@ Frontend source lives in `public/js/*.ts`, bundled by esbuild into a single cont
 
 ## Documentation
 
-| Document | Contents |
-|---|---|
-| **[Features](docs/features.md)** | Chat, images, bash, sessions, slash commands, keyboard shortcuts, themes |
-| **[Configuration & Operations](docs/configuration.md)** | TOML config, daemon commands, agent setup, upgrading |
-| **[API Reference](docs/api.md)** | REST endpoints, SSE events, implementation details |
-| **[ACP Integration](docs/acp.md)** | Client extensions, protocol scope, current limits |
-| **[Client Architecture](docs/client-architecture.md)** | Frontend modules, data flow, conventions |
-| **[Development](docs/development.md)** | Building from source, dev mode, testing, publishing |
-| **[Auto-Start on Boot](docs/autostart.md)** | launchd, systemd, crontab, Windows Task Scheduler |
+| Document                                                | Contents                                                                       |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| **[Features](docs/features.md)**                        | Chat, attachments, bash, sessions, slash commands, keyboard shortcuts, themes  |
+| **[Configuration & Operations](docs/configuration.md)** | TOML config, daemon commands, agent setup, upgrading                           |
+| **[Security](docs/security.md)**                        | Bearer auth, token storage, SSE ticket, signed image URLs, CSP, data layout    |
+| **[API Reference](docs/api.md)**                        | REST endpoints, SSE events, implementation details                             |
+| **[Attachments](docs/uploads.md)**                      | Upload pipeline, on-disk layout, lifecycle, permission auto-approve, observability |
+| **[ACP Integration](docs/acp.md)**                      | Client extensions, protocol scope, current limits                              |
+| **[Client Architecture](docs/client-architecture.md)**  | Frontend modules, data flow, conventions                                       |
+| **[Slash Menu](docs/slash-menu.md)**                    | Walker pipeline, `CmdNode` tree, Tab/Enter/Click contract, how to add commands |
+| **[Messages / Inbox](docs/messages.md)**                | `/inbox` slash command, POST ingress, bound vs unbound messages                |
+| **[Share Links](docs/share.md)**                        | Public read-only session snapshots via `/share` + `/s/<token>`                 |
+| **[Database Schema](docs/schema.md)**                   | SQLite tables, indexes, FK policy, cascade/lifecycle rules, migrations         |
+| **[Development](docs/development.md)**                  | Building from source, dev mode, testing, publishing                            |
+| **[Auto-Start on Boot](docs/autostart.md)**             | launchd, systemd, crontab, Windows Task Scheduler                              |

package/bin/webagent.mjs

@@ -3,9 +3,121 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { copyFileSync, existsSync } from "node:fs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// ---- Subcommand: `webagent config <init|show>` ------------------------------
+//
+// `config init` copies the package's bundled config.toml (the same
+// well-commented file that documents every key + its default) to
+// ./config.toml. Refuses to overwrite without --force. The bundled
+// file is the single source of truth, so what users get always matches
+// the schema (test/config-coverage.test.ts guards that alignment).
+//
+// `config show` dumps the effective merged configuration (defaults
+// overlaid with whatever --config provided) as TOML to stdout. Useful
+// for "what is actually in effect right now".
+if (process.argv[2] === "config") {
+  const sub = process.argv[3];
+  if (sub === "init") {
+    const force = process.argv.includes("--force");
+    const src = fileURLToPath(new URL("../config.toml", import.meta.url));
+    const dst = join(process.cwd(), "config.toml");
+    if (existsSync(dst) && !force) {
+      console.error(
+        `config.toml already exists at ${dst}. Use --force to overwrite.`,
+      );
+      process.exit(1);
+    }
+    try {
+      copyFileSync(src, dst);
+    } catch (err) {
+      console.error(`Failed to write ${dst}:`, err.message ?? err);
+      process.exit(1);
+    }
+    console.log(`wrote ${dst}`);
+    console.log(`edit it, then run:  webagent --config config.toml`);
+    process.exit(0);
+  }
+  if (sub === "show") {
+    // Silence loadConfig's [config] log so stdout contains only TOML.
+    const origLog = console.log;
+    console.log = () => {};
+    const cfgUrl = new URL("../lib/config.js", import.meta.url).href;
+    const tomlUrl = "smol-toml";
+    const { loadConfig } = await import(cfgUrl);
+    const { stringify } = await import(tomlUrl);
+    const cfg = loadConfig();
+    console.log = origLog;
+    process.stdout.write(stringify(cfg));
+    process.exit(0);
+  }
+  console.error("Usage: webagent config <init|show> [--force]");
+  process.exit(64);
+}
+
+// ---- One-shot: --create-token <name> ---------------------------------------
+//
+// Provision an admin-scope token without launching the server. Run this
+// once on first install (or when adding a new client device). The raw
+// token is printed to stdout exactly once; we do not store it anywhere
+// retrievable.
+{
+  const argv = process.argv.slice(2);
+  const idx = argv.indexOf("--create-token");
+  if (idx !== -1) {
+    const name = argv[idx + 1];
+    if (!name || name.startsWith("--")) {
+      console.error("Usage: webagent --create-token <name> [--config <path>]");
+      process.exit(64);
+    }
+    const cfgIdx = argv.indexOf("--config");
+    if (cfgIdx !== -1 && argv[cfgIdx + 1]) {
+      // loadConfig() reads --config from process.argv directly
+      process.argv = [
+        process.argv[0],
+        process.argv[1],
+        "--config",
+        argv[cfgIdx + 1],
+      ];
+    } else {
+      process.argv = [process.argv[0], process.argv[1]];
+    }
+    // Silence loadConfig's [config] log so stdout contains only the raw
+    // token (machine-parseable). Errors still go to stderr.
+    const origLog = console.log;
+    console.log = () => {};
+    const cfgUrl = new URL("../lib/config.js", import.meta.url).href;
+    const storeUrl = new URL("../lib/auth-store.js", import.meta.url).href;
+    const { loadConfig } = await import(cfgUrl);
+    const { AuthStore } = await import(storeUrl);
+    const cfg = loadConfig();
+    console.log = origLog;
+    const store = new AuthStore(join(cfg.data_dir, "auth.json"));
+    await store.load();
+    try {
+      const created = await store.addToken(name, "admin");
+      // First line: raw token (machine-readable). Followed by a newline so
+      // `webagent --create-token foo | tr -d '\n' | pbcopy` works.
+      process.stdout.write(created.token + "\n");
+      console.error(
+        `\nCreated token '${name}' (admin scope). Save it now — it will not be shown again.`,
+      );
+      console.error(
+        `If the server is already running, send SIGHUP so it picks up the new token:`,
+      );
+      console.error(`  kill -HUP $(pgrep -f 'lib/server.js')`);
+      await store.close();
+      process.exit(0);
+    } catch (err) {
+      console.error("Failed to create token:", err.message ?? err);
+      await store.close().catch(() => {});
+      process.exit(1);
+    }
+  }
+}
+
 // ---- Service management subcommands (start/stop/status/restart) -----------
 
 const SUBCOMMANDS = new Set(["start", "stop", "status", "restart"]);
@@ -19,15 +131,14 @@ if (cmd && SUBCOMMANDS.has(cmd)) {
   // ---- Direct server launch (foreground) ----------------------------------
   const server = join(__dirname, "..", "lib", "server.js");
 
-  const child = spawn(
-    process.execPath,
-    [server, ...process.argv.slice(2)],
-    { stdio: "inherit" },
-  );
+  const child = spawn(process.execPath, [server, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
 
-  const signals = process.platform === "win32"
-    ? ["SIGINT", "SIGTERM"]
-    : ["SIGINT", "SIGTERM", "SIGHUP"];
+  const signals =
+    process.platform === "win32"
+      ? ["SIGINT", "SIGTERM"]
+      : ["SIGINT", "SIGTERM", "SIGHUP"];
   for (const sig of signals) {
     process.on(sig, () => child.kill(sig));
   }

package/config.toml

@@ -13,16 +13,25 @@ data_dir = "data"
 # Static assets directory (default: "dist")
 public_dir = "dist"
 
-# ACP agent command (binary + args, space-separated) (default: "copilot --acp")
-agent_cmd = "copilot --acp"
+# ACP agent command (binary + args, space-separated).
+# Default "auto" scans PATH for known ACP-ready agents (in priority order):
+#   copilot, gemini, opencode, claude-agent-acp, codex-acp, qwen
+# Set explicitly to override:
+#   agent_cmd = "claude-agent-acp"
+#   agent_cmd = "codex-acp"
+#   agent_cmd = "gemini --acp"
+agent_cmd = "auto"
 
 [limits]
 # Max bash output stored in DB per command (bytes, default 1 MB)
 bash_output = 1_048_576
 
-# Max image upload size (bytes, default 10 MB)
+# Max image upload size (bytes, default 10 MB). Applies to image/* attachments.
 image_upload = 10_485_760
 
+# Max non-image upload size (bytes, default 50 MB). Applies to all other mime types.
+file_upload = 52_428_800
+
 # Cancel timeout (ms, default 10s). After sending cancel, if the agent
 # does not respond within this time the UI resets to idle. Set to 0 to disable.
 cancel_timeout = 10_000
@@ -35,3 +44,87 @@ recent_paths_ttl = 30
 
 [push]
 vapid_subject = "mailto:noreply@example.com"
+# Kill switch for cross-device global visibility suppression. When true,
+# if any client is actively viewing session X, push for session X is
+# suppressed for every device. Flip to false to rollback the feature
+# without a code change.
+global_visibility_suppression = true
+
+[title]
+# Models matched (by case-insensitive substring) against the agent's
+# reported availableModels for the title-generation sub-session. The first
+# pattern that matches any model id wins; that model is set via
+# setConfigOption. 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 model = [] to disable matching entirely and always inherit the
+# agent's default model. To pin one specific model, use a single-element
+# array, e.g. model = ["claude-haiku-4.5"].
+model = ["haiku", "flash-lite", "nano", "mini", "flash", "lite"]
+
+[debug]
+# Frontend log level. One of: off | debug | info | warn | error.
+# Default "off". Users can override per page-load via ?debug=<level> in
+# the URL, or at runtime via the /debug slash command. level != off
+# emits to both DevTools console and the conversation-flow DOM.
+level = "off"
+
+[messages]
+# Days before an unprocessed unbound inbox message is auto-cleaned
+# (default 30). 0 = keep forever. Bound messages (to:"session:<id>")
+# are stored on the owning session and are not subject to this TTL.
+unprocessed_ttl_days = 30
+
+[share]
+# Public read-only session share links. Default off. Dogfood manually
+# flips `enabled = true` after CF Access bypass + Rate Limiting are
+# configured. See docs/share.md.
+
+# Master kill switch. When false, all /api/v1/sessions/*/share* and
+# /s/* routes return 410, and /share slash commands are hidden.
+enabled = false
+
+# Global default TTL for public share links (hours). 0 = never expire
+# (default). Values >0 are clamped to 168 (7d) at startup with a WARN.
+# Per-share overrides live in the shares.ttl_hours column.
+ttl_hours = 0
+
+# true emits Content-Security-Policy on /s/* + /api/v1/shared/*.
+# Set false to fall back to Content-Security-Policy-Report-Only as an
+# emergency kill switch without touching code.
+csp_enforce = true
+
+# Public viewer origin; null = same as webagent host. Set when viewer is
+# fronted by a separate CF Worker route (e.g. "https://share.example.com").
+viewer_origin = ""
+
+# Sanitizer internal-domain allowlist; substrings matched (case-insensitive)
+# get rewritten to `<internal-host>` before publishing. Example:
+# internal_hosts = ["corp.example.com", "internal-db"]
+internal_hosts = []
+
+[auth]
+# Bearer-token auth knobs.
+#
+# first_run_bootstrap controls the zero-config first-run UX. When true
+# (default), if auth.json does NOT exist AND stdin is a TTY, the 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.
+#
+# Set to false when deploying behind a supervisor that provisions auth.json
+# out-of-band (CI, Ansible, k8s init container) — server falls back to
+# "exit 78 + use --create-token" behavior.
+#
+# Note: this only kicks in for missing auth.json. If the file exists but
+# the token list is empty (manual edit, parse failure), server still exits
+# 78 — that's a config anomaly, not a fresh install.
+first_run_bootstrap = true

package/dist/index.html

@@ -1,47 +1,70 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>>_</title>
-<link rel="icon" href="/icons/icon.svg" type="image/svg+xml">
-<link rel="apple-touch-icon" href="/icons/icon-180.png">
-<link rel="manifest" href="/manifest.json">
-<meta name="theme-color" content="#0d1117" media="(prefers-color-scheme: dark)">
-<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
-<meta name="apple-mobile-web-app-capable" content="yes">
-<meta name="apple-mobile-web-app-status-bar-style" content="default">
-<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.3.2/dist/purify.min.js"></script>
-<script>document.documentElement.setAttribute('data-theme', localStorage.getItem('theme') || 'auto');</script>
-<link rel="stylesheet" href="/styles.008ve1hx.css">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>>_</title>
+    <link rel="icon" href="/icons/icon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="/icons/icon-180.png" />
+    <link rel="manifest" href="/manifest.json" />
+    <meta
+      name="theme-color"
+      content="#0d1117"
+      media="(prefers-color-scheme: dark)"
+    />
+    <meta
+      name="theme-color"
+      content="#ffffff"
+      media="(prefers-color-scheme: light)"
+    />
+    <meta name="mobile-web-app-capable" content="yes" />
+    <!-- Keep apple-prefixed version: iOS Safari still only recognizes this one
+     for standalone PWA mode. Chrome's deprecation warning is satisfied by
+     the standard version above. Remove once iOS supports the standard. -->
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+    <script src="/theme-init.js"></script>
+    <link rel="stylesheet" href="/styles.012p32dz.css" />
+  <link rel="modulepreload" href="/js/chunk.D4ZYHJAM.js">
+<link rel="modulepreload" href="/js/chunk.CGWFHJI2.js">
+<link rel="modulepreload" href="/js/chunk.AJZBJBMO.js">
 </head>
-<body>
+  <body>
+    <div id="header">
+      <div class="header-side header-left">
+        <span class="logo">>_</span>
+      </div>
+      <span id="session-info" class="status"></span>
+      <div class="header-side header-right">
+        <span
+          id="status"
+          class="status-dot is-disconnected"
+          data-state="disconnected"
+          role="status"
+          aria-live="polite"
+          aria-label="disconnected"
+          title="disconnected"
+        ></span>
+        <button id="theme-btn" title="Toggle theme">◑</button>
+      </div>
+    </div>
 
-<div id="header">
-  <div class="header-side header-left">
-    <span class="logo">>_</span>
-  </div>
-  <span id="session-info" class="status"></span>
-  <div class="header-side header-right">
-    <span id="status" class="status-dot is-disconnected" data-state="disconnected" role="status" aria-live="polite" aria-label="disconnected" title="disconnected"></span>
-    <button id="theme-btn" title="Toggle theme">◑</button>
-  </div>
-</div>
+    <div id="messages"></div>
 
-<div id="messages"></div>
+    <div id="attach-preview"></div>
+    <div id="input-area">
+      <div id="slash-menu"></div>
+      <span id="mode-pill"></span>
+      <span id="input-prompt" title="Cycle mode (Ctrl+M)"></span>
+      <textarea id="input" rows="1" placeholder="Message or ?"></textarea>
+      <button id="attach-btn" class="input-btn" title="Attach image (Ctrl+U)">
+        ^U
+      </button>
+      <button id="send-btn" class="input-btn" title="Send (Enter)">↵</button>
+      <input type="file" id="file-input" multiple hidden />
+    </div>
+    <div id="status-bar"></div>
 
-<div id="attach-preview"></div>
-<div id="input-area">
-  <div id="slash-menu"></div>
-  <span id="input-prompt" title="Cycle mode (Ctrl+M)">❯ </span>
-  <textarea id="input" rows="1" placeholder="Message or ?"></textarea>
-  <button id="attach-btn" class="input-btn" title="Attach image (Ctrl+U)">^U</button>
-  <button id="send-btn" class="input-btn" title="Send (Enter)">↵</button>
-  <input type="file" id="file-input" accept="image/*" multiple hidden>
-</div>
-<div id="status-bar"></div>
-
-<script src="/js/app.2562YGRO.js"></script>
-</body>
+    <script type="module" src="/js/app.GSAIYHML.js"></script>
+  </body>
 </html>