@lelouchhe/webagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LelouchHe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# WebAgent
+
+A terminal-style web UI for ACP-compatible agents.
+
+Tech stack: Node.js + TypeScript (`--experimental-strip-types`), real-time WebSocket communication (`ws`), SQLite persistence (`better-sqlite3`), Zod validation.
+
+## Screenshots
+
+<table>
+  <tr>
+    <td width="50%">
+      <img src="docs/images/overview-chat.png" alt="Desktop chat overview" />
+      <br />
+      <sub>Streaming chat in the terminal-style desktop layout.</sub>
+    </td>
+    <td width="50%">
+      <img src="docs/images/plan-busy.png" alt="Plan mode while busy" />
+      <br />
+      <sub>Plan mode highlighted while a turn is still running.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <img src="docs/images/permission-dialog.png" alt="Permission request dialog" />
+      <br />
+      <sub>Permission prompts stay inline in the conversation flow.</sub>
+    </td>
+    <td width="50%">
+      <img src="docs/images/bash-output.png" alt="Inline bash command output" />
+      <br />
+      <sub><code>!&lt;command&gt;</code> output streams directly into the session.</sub>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/images/mobile-autopilot.png" alt="Mobile autopilot mode" width="320" />
+  <br />
+  <sub>Compact mobile layout with mode highlighting and terminal-style action keys.</sub>
+</p>
+
+## Prerequisites
+
+- Node.js 22.6+ (requires `--experimental-strip-types`)
+- An ACP-compatible agent (e.g. [Copilot CLI](https://github.com/github/copilot-cli)) installed and authenticated
+
+## Install
+
+```bash
+npm install -g @lelouchhe/webagent
+```
+
+Or run directly with npx:
+
+```bash
+npx @lelouchhe/webagent
+```
+
+## Run
+
+```bash
+webagent                             # start with defaults (port 6800)
+webagent --config /path/to/config.toml   # start with custom config
+```
+
+Data (SQLite database, uploaded images) is stored in `./data/` relative to your current working directory by default.
+
+### From source
+
+```bash
+git clone https://github.com/LelouchHe/webagent.git
+cd webagent
+npm install
+npm run build         # build static assets (public/ → dist/)
+npm start             # start on port 6800
+```
+
+### Development
+
+```bash
+npm run dev           # port 6801, uses data-dev/, auto-restarts on file changes
+```
+
+How you keep the process running in the background is intentionally left to your own environment and preferred process manager.
+
+### Configuration
+
+Configuration is via TOML files, passed with `--config`:
+
+```bash
+webagent --config config.toml
+```
+
+If no `--config` is provided, all settings use built-in defaults. See `config.toml` for the checked-in default settings and `config.dev.toml` for development.
+
+| Key | Default | Description |
+|---|---|---|
+| `port` | `6800` | HTTP/WebSocket server port |
+| `data_dir` | `data` | SQLite + uploads directory |
+| `default_cwd` | `process.cwd()` | Working directory for new sessions |
+| `public_dir` | `dist` | Static assets directory |
+| `agent_cmd` | `copilot --acp` | ACP agent command (binary + args, space-separated) |
+| `limits.bash_output` | `1048576` (1 MB) | Max bash output stored in DB per command |
+| `limits.image_upload` | `10485760` (10 MB) | Max image upload size |
+| `limits.cancel_timeout` | `10000` (10s) | Cancel timeout in ms; 0 disables |
+
+To use a different ACP-compatible agent backend:
+
+```toml
+agent_cmd = "my-agent --acp"
+```
+
+## Features
+
+### Chat
+
+- Real-time streaming responses with Markdown rendering + syntax highlighting
+- Collapsible thinking process display
+- Tool call display (status animation, expandable details, diff rendering)
+- Agent execution plan display (pending ○ / in-progress ◉ / done ●)
+- Permission confirmation dialog for sensitive operations (Allow / Deny), synced across devices; auto-approved in autopilot mode
+- Smart scroll: force-scrolls on load/switch/send, soft auto-scroll during streaming
+
+### Images
+
+- Upload images (button or `^U` shortcut)
+- Paste images (Ctrl+V / Cmd+V)
+- Preview before sending + removable, supports multiple images
+- Server-side storage, displayed inline in chat
+
+### Bash Execution
+
+- `!<command>` to run shell commands directly
+- Real-time output streaming (stderr in red)
+- Collapsible output with exit code display
+- Cancel running processes
+- Cancel is session-scoped inside WebAgent: it stops the current ACP turn plus WebAgent-owned session work (like local `!` bash), but it cannot stop host-level tasks started outside the WebAgent server/runtime
+
+### Session Management
+
+- Auto-resumes last session on page open, no manual switching needed
+- After server restart, restores session context via ACP `loadSession` so conversations can continue
+- Auto-generated titles (async, using a fast model)
+- Session history persisted in SQLite, survives restarts
+- `/sessions` lists all sessions (git-branch style, `*` marks current in green)
+- Switching sessions replays full message history
+
+### Slash Commands
+
+Type `/` to trigger an autocomplete menu (arrow keys to navigate, Tab to select, Esc to close).
+
+| Command | Description |
+|---|---|
+| `/new [cwd]` | Create new session (optionally specify working directory) |
+| `/pwd` | Show current working directory |
+| `/model [name]` | View or switch model (fuzzy match, e.g. `/model opus`) |
+| `/mode [name]` | View or switch mode (Agent / Plan / Autopilot) |
+| `/think [level]` | View or switch reasoning effort (low / medium / high) |
+| `/cancel` | Cancel current response |
+| `/switch <title\|id>` | Switch to a session (match by title or ID prefix) |
+| `/delete <title\|id>` | Delete a session |
+| `/prune` | Delete all sessions except current |
+| `/help` | Show help |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| `Enter` | Send message |
+| `Shift+Enter` | New line |
+| `Ctrl+X` | Cancel current response |
+| `Ctrl+M` | Cycle mode (Agent → Plan → Autopilot) |
+| `Ctrl+U` | Upload image |
+
+Tap the `❯` prompt indicator to cycle mode. Tap `new` to create a new session (hidden when input has content).
+
+### Theme
+
+- Dark / light / system, toggle with `◑`
+- Terminal-style UI (monospace font, `>_` logo)
+- Preference saved to localStorage
+
+### Other
+
+- PWA support (installable to home screen)
+- WebSocket auto-reconnect (3s retry on disconnect)
+- 30s heartbeat keepalive
+- Auto-expanding input box
+- Mobile-friendly layout
+- Multi-client broadcast (events synced across devices)
+
+## Testing
+
+```bash
+npm test              # unit + integration
+npm run test:e2e      # Playwright browser E2E
+```
+
+- `TEST_SCENARIOS.md` is the scenario-level coverage map for the current suite.
+- Use it when reviewing what is already protected before adding new tests or auditing gaps.
+- The E2E suite now covers session lifecycle, reconnect/restart recovery, permissions, cancel flows, bash lifecycle, media persistence, slash-menu UX, config persistence/inheritance, and multi-client config behavior.
+
+## Architecture
+
+```
+Browser ←WebSocket→ server.ts ←ACP→ copilot CLI
+                     ├── routes.ts (HTTP handlers)
+                     ├── ws-handler.ts (WS dispatch)
+                     ├── session-manager.ts (state)
+                     ├── title-service.ts (auto-title)
+                     └── store.ts (SQLite)
+```
+
+- **server.ts** — HTTP/WebSocket server bootstrap
+- **routes.ts** — HTTP request handlers (static files, REST API, image upload)
+- **ws-handler.ts** — WebSocket message dispatch + broadcast
+- **session-manager.ts** — Session state management (live sessions, buffers, bash procs, model cache)
+- **bridge.ts** — ACP bridge, manages agent subprocess, handles permissions and file I/O
+- **store.ts** — SQLite persistence (sessions + events tables, WAL mode)
+- **title-service.ts** — Async session title generation (dedicated Haiku session)
+- **types.ts** — Shared types + Zod schemas for WS messages
+
+## ACP Scope and Current Limits
+
+WebAgent uses ACP for the core agent loop: session creation / restore, prompt turns, permission requests, streaming updates, model selection, and text file read/write.
+
+Current scope in this repo:
+
+- Session lifecycle goes through ACP (`newSession`, `loadSession`, `prompt`, `cancel`)
+- The UI renders a subset of ACP session updates: assistant text, thinking text, tool calls, tool call updates, and plans
+- Session history is persisted locally and restored after server restart
+
+Current limits:
+
+- MCP servers are not forwarded to the agent; sessions are created with an empty `mcpServers` list
+- ACP terminal APIs are not used; `!<command>` runs through the app's own local `bash` bridge instead of an ACP-managed terminal session
+- The web UI does not expose native CLI command surfaces such as `/plan`, `/fleet`, `/mcp`, `/agent`, or `/skills`
+- Autopilot mode is supported: permissions are auto-approved server-side using `allow_once`
+- Event handling is intentionally narrower than a native CLI client; only selected ACP updates are rendered/persisted, and the silent title-generation session suppresses normal UI events
+- Model switching depends on the agent's ACP implementation and currently uses the SDK's unstable session-model API
+- ACP does not expose context window usage, token counts, or remaining capacity
+- No method to compact or clear session context; only option is to create a new session
+
+In practice, this means WebAgent provides a browser UI for the core ACP chat/session workflow, but not the full product surface of direct Copilot CLI or Claude Code in a terminal.

package/bin/webagent.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const server = join(__dirname, "..", "src", "server.ts");
+
+const child = spawn(
+  process.execPath,
+  ["--experimental-strip-types", server, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => child.kill(sig));
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/config.toml

@@ -0,0 +1,28 @@
+# WebAgent production configuration
+
+# HTTP/WebSocket server port (default: 6800)
+port = 6800
+
+# SQLite + uploads directory (default: "data")
+data_dir = "data"
+
+# Default working directory for new sessions (default: process.cwd()).
+# Leave this commented out to use the process working directory.
+# default_cwd = "/path/to/your/workspace"
+
+# Static assets directory (default: "dist")
+public_dir = "dist"
+
+# ACP agent command (binary + args, space-separated) (default: "copilot --acp")
+agent_cmd = "copilot --acp"
+
+[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)
+image_upload = 10_485_760
+
+# 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

package/dist/icons/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'>
+  <rect width='100' height='100' rx='16' fill='#0d1117'/>
+  <text x='12' y='68' font-family='monospace' font-size='56' font-weight='bold' fill='#58a6ff'>>_</text>
+</svg>

package/dist/index.html

@@ -0,0 +1,46 @@
+<!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">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+<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.mmjqzu9r.css">
+</head>
+<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="messages"></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 ?" autofocus></textarea>
+  <button id="new-btn" class="input-btn" title="New session">new</button>
+  <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>
+
+<script type="module" src="/js/app.mmjqzu9r.js"></script>
+</body>
+</html>

package/dist/js/app.mmjqzu9r.js

@@ -0,0 +1,10 @@
+// Boot entry point — imports all modules and starts the app
+
+import './render.mmjqzu9r.js';    // theme, click-to-collapse listeners
+import './commands.mmjqzu9r.js';  // slash menu listeners
+import './images.mmjqzu9r.js';    // attach/paste listeners
+import './input.mmjqzu9r.js';     // keyboard/send listeners
+import { connect } from './connection.mmjqzu9r.js';
+
+connect();
+if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js');