claude-ide-bridge 2.4.10 → 2.4.11

package/README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A standalone MCP bridge that gives [Claude Code](https://claude.ai/code) full IDE integration — **138+ tools** for LSP, debugging, terminals, Git, GitHub, diagnostics, code analysis, screen capture, and more. Works with any VS Code-compatible editor (VS Code, Windsurf, Cursor) and pairs with a companion extension for real-time editor state.
+A standalone MCP bridge that gives [Claude Code](https://claude.ai/code) full IDE integration — **124+ tools** for LSP, debugging, terminals, Git, GitHub, diagnostics, code analysis, screen capture, and more. Works with any VS Code-compatible editor (VS Code, Windsurf, Cursor) and pairs with a companion extension for real-time editor state.
 
 ## How It Works
 
@@ -102,6 +102,30 @@ claude-ide-bridge start-all --workspace /your/project
 
 Launches four tmux panes: health monitor, bridge, Claude Code, and remote control — with automatic restart on failure. Requires `tmux`.
 
+## Documentation
+
+> **These guides are essential for setup and deployment** — not optional reading. Each covers a specific scenario you'll encounter when running the bridge beyond localhost.
+
+| Guide | What it covers |
+|-------|----------------|
+| **[Remote Access](docs/remote-access.md)** | Production reverse proxy setup (Caddy/nginx), TLS, Streamable HTTP transport |
+| **[SSH Resilience](docs/ssh-resilience.md)** | Surviving SSH drops, tmux strategies, phone-to-VPS workflows |
+| **[IP Allowlist](docs/ip-allowlist.md)** | Firewall rules, network access control for remote bridge instances |
+| **[Worktree Isolation](docs/worktree-isolation.md)** | How git worktrees interact with the bridge, safe concurrent editing |
+| **[Privacy Policy](docs/privacy-policy.md)** | What data the bridge handles, stores, and never transmits |
+| **[Demo Setup](docs/demo-setup.md)** | Standing up a persistent demo instance for review/testing |
+| **[Architecture Decisions](docs/adr/)** | ADRs for version numbers, reconnect guards, lock files, error model, session eviction |
+
+**Reference docs** (in [`documents/`](documents/)):
+
+| Doc | What it covers |
+|-----|----------------|
+| **[Platform Docs](documents/platform-docs.md)** | Complete tool reference (124+ tools), parameters, examples |
+| **[Data Reference](documents/data-reference.md)** | Data flows, state management, protocol details |
+| **[Plugin Authoring](documents/plugin-authoring.md)** | Writing custom plugins — manifest schema, entrypoint API |
+| **[Use Cases](documents/use-cases.md)** | Real-world workflows and scenarios |
+| **[Roadmap](documents/roadmap.md)** | Planned features and development direction |
+
 ## Full Orchestrator
 
 The `start-all` command launches everything in a tmux session: bridge + Claude Code + remote control, with automatic health monitoring and process restart.
@@ -164,11 +188,15 @@ claude --plugin-dir ./claude-ide-bridge-plugin
 
 | Event | What it does |
 |-------|-------------|
+| `PreToolUse` on Edit/Write | Resolves relative path args to absolute before bridge tools execute |
 | `PostToolUse` on Edit/Write | Reminds Claude to check diagnostics after file edits |
 | `SessionStart` | Reports bridge status, connection, and tool count |
+| `InstructionsLoaded` | Injects live bridge status each time CLAUDE.md loads |
+| `Elicitation` | Pre-fills file/path/uri fields using the active editor |
+| `WorktreeCreate` | Reports bridge ↔ worktree relationship; warns about LSP limitations |
 | `SubagentStart` | Verifies bridge is alive before IDE subagents run |
 
-## 138+ MCP Tools
+## 124+ MCP Tools
 
 ### File Operations (8)
 `openFile` · `openDiff` · `saveDocument` · `closeTab` · `closeAllDiffTabs` · `checkDocumentDirty` · `getOpenEditors` · `searchWorkspace`
@@ -194,8 +222,8 @@ claude --plugin-dir ./claude-ide-bridge-plugin
 ### Code Quality (3)
 `fixAllLintErrors` · `formatDocument` · `organizeImports`
 
-### Snapshots & Plans (10)
-`createSnapshot` · `restoreSnapshot` · `diffSnapshot` · `listSnapshots` · `deleteSnapshot` · `createPlan` · `updatePlan` · `getPlan` · `listPlans` · `deletePlan`
+### Snapshots & Plans (5)
+`createPlan` · `updatePlan` · `getPlan` · `listPlans` · `deletePlan`
 
 ### Editor State (6)
 `getCurrentSelection` · `getLatestSelection` · `getOpenEditors` · `getBufferContent` · `setEditorDecorations` · `clearEditorDecorations`
@@ -230,16 +258,16 @@ Text editing · Workspace settings · File watchers · Decorations · `executeVS
 | Debug | 5 | Yes |
 | Decorations | 2 | Yes |
 | Screen Capture | 1 | Yes |
-| Snapshots & Plans | 10 | No |
+| Snapshots & Plans | 5 | No |
 | Bridge & Session | 3 | No |
 | Clipboard | 2 | Mixed |
 | HTTP | 2 | No |
 | VS Code Integration | 10 | Yes |
-| **Total** | **~138** | |
+| **Total** | **~124** | |
 
 ## MCP Prompts (Slash Commands)
 
-The bridge exposes 7 built-in slash commands via the MCP `prompts/list` + `prompts/get` protocol. These appear as `/mcp__bridge__<name>` in any MCP client that supports prompts.
+The bridge exposes 15 built-in slash commands via the MCP `prompts/list` + `prompts/get` protocol. These appear as `/mcp__bridge__<name>` in any MCP client that supports prompts.
 
 | Prompt | Argument | Description |
 |--------|----------|-------------|
@@ -250,6 +278,13 @@ The bridge exposes 7 built-in slash commands via the MCP `prompts/list` + `promp
 | `/mcp__bridge__git-review` | `base` (optional, default: `main`) | Review all changes since a git base branch |
 | `/mcp__bridge__cowork` | `task` (optional) | Gather full IDE context and propose a Cowork action plan — run this **before** opening a Cowork session |
 | `/mcp__bridge__set-effort` | `level` (optional: `low`/`medium`/`high`, default: `medium`) | Prepend an effort-level instruction to tune Claude's thoroughness for the next task |
+| `/mcp__bridge__project-status` | _(none)_ | Quick project health: git status + diagnostics + test summary (Dispatch) |
+| `/mcp__bridge__quick-tests` | `filter` (optional) | Run tests and return concise pass/fail summary (Dispatch) |
+| `/mcp__bridge__quick-review` | _(none)_ | Review uncommitted changes with diff summary and diagnostics (Dispatch) |
+| `/mcp__bridge__build-check` | _(none)_ | Check if the project builds successfully (Dispatch) |
+| `/mcp__bridge__recent-activity` | `count` (optional, default: `10`) | Recent git log and uncommitted changes (Dispatch) |
+| `/mcp__bridge__team-status` | _(none)_ | Workspace state, active tasks, and recent activity for team leads (Agent Teams) |
+| `/mcp__bridge__health-check` | _(none)_ | Comprehensive project health: tests, diagnostics, security (Scheduled Tasks) |
 
 > **Cowork sessions and MCP tools:** MCP tools (including all bridge tools) are **not available inside a Cowork session**. Use a two-step workflow: run `/mcp__bridge__cowork` in a regular Claude Code chat first — it gathers full IDE context and produces an action plan — then open a Cowork session armed with that context.
 
@@ -571,6 +606,176 @@ Config location:
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
+## Dispatch (Mobile Remote Control)
+
+[Dispatch](https://docs.anthropic.com) is a Claude Desktop feature that lets you send instructions from your phone to your desktop Claude session. Combined with the bridge, you can check on your project, run tests, and review changes — all from a phone message.
+
+### How it works
+
+```
+Your Phone (Claude App)
+    │
+    ▼  terse instruction
+Claude Desktop (main conversation)
+    │
+    ▼  MCP tool calls
+Bridge Server ──► IDE Extension ──► Your Code
+    │
+    ▼  results
+Claude Desktop
+    │
+    ▼  concise summary
+Your Phone
+```
+
+Dispatch messages land in Claude Desktop's **main conversation**, which has full MCP bridge access. Claude calls the bridge tools, gathers results, and sends a summary back to your phone.
+
+> **Not Cowork:** Dispatch routes through the main conversation, not a Cowork session. All 124+ bridge tools are available. The Cowork tool-access limitation does not apply here.
+
+### Setup
+
+1. **Bridge running** — `claude-ide-bridge --watch` in your project directory
+2. **Claude Desktop connected** — stdio shim configured (see [Use with Claude Desktop](#use-with-claude-desktop))
+3. **Dispatch paired** — open Claude Desktop → Cowork → Dispatch → scan QR code with Claude mobile app
+4. **Computer awake** — your desktop must be powered on and not sleeping
+
+### Phone-friendly prompts
+
+The bridge includes 5 Dispatch-optimized prompts designed for terse phone triggers. Each instructs Claude to call specific bridge tools and return concise, phone-screen-friendly output:
+
+| Prompt | Phone message | What it does |
+|--------|--------------|--------------|
+| `project-status` | "How's the build?" | Git status + diagnostics + test summary |
+| `quick-tests` | "Run the tests" | Pass/fail summary with failure details |
+| `quick-review` | "Review my changes" | Diff summary + diagnostics for changed files |
+| `build-check` | "Does it build?" | Build/compile check with error summary |
+| `recent-activity` | "What changed?" | Recent git log + uncommitted changes |
+
+You can also type any natural-language instruction — the prompts above are shortcuts that produce consistently formatted output.
+
+### Example Dispatch session
+
+From your phone:
+> "How's the build?"
+
+Claude checks git status, diagnostics, and tests, then responds:
+```
+Branch: feature/oauth (3 uncommitted)
+Diagnostics: 0 errors, 2 warnings
+Tests: 142 passed, 0 failed (12s)
+```
+
+From your phone:
+> "Review my changes"
+
+Claude diffs your uncommitted work and responds with a file-by-file summary and an overall assessment.
+
+### Cowork context template
+
+For better Dispatch results, copy `templates/dispatch-context.md` into your Cowork context folder. It maps terse phone commands to bridge tools and sets response formatting guidelines for mobile output.
+
+### Limitations
+
+- **One conversation thread** — Dispatch uses a single persistent thread
+- **Computer must be awake** — if your desktop sleeps, Dispatch goes dark
+- **No push notifications** — check the phone app manually for responses
+- **Best for reads, not writes** — information retrieval (status, tests, review) is highly reliable; multi-file edits from phone messages are not recommended
+
+---
+
+## Agent Teams (Parallel Multi-Agent)
+
+[Agent Teams](https://code.claude.com/docs/en/agent-teams) let multiple Claude Code instances work in parallel on the same project. A team lead assigns tasks, teammates execute them independently, and results are synthesized.
+
+### How it works with the bridge
+
+Each teammate is an independent Claude Code session that connects to the bridge via its own WebSocket/MCP session. The bridge already supports multiple concurrent sessions (`MAX_SESSIONS = 5`), so **agent teams work out of the box** — no additional configuration needed.
+
+```
+Team Lead (Claude Code)
+    ├── Teammate A ──► Bridge Session 1 ──► IDE
+    ├── Teammate B ──► Bridge Session 2 ──► IDE
+    └── Teammate C ──► Bridge Session 3 ──► IDE
+```
+
+All teammates share the same IDE and workspace. Each gets full access to all 124+ bridge tools.
+
+### Setup
+
+1. Enable agent teams: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment
+2. Bridge running: `claude-ide-bridge --watch`
+3. Ask Claude to create a team: *"Create an agent team to review and fix all TypeScript errors"*
+
+### Bridge prompts for team leads
+
+| Prompt | What it does |
+|--------|-------------|
+| `/mcp__bridge__team-status` | Workspace state, active tasks, recent activity across sessions |
+| `/mcp__bridge__health-check` | Full project health: tests, diagnostics, security |
+
+### Best practices
+
+- **Pre-approve tools** — teammates block on permission prompts. Use `--dangerously-skip-permissions` in sandboxed environments or pre-approve common tools.
+- **Avoid file conflicts** — assign teammates to different files/modules. The bridge doesn't lock files across sessions.
+- **Use the team-status prompt** — the lead can call `/mcp__bridge__team-status` to see workspace state and recent activity across all sessions.
+
+---
+
+## Scheduled Tasks (Recurring Workflows)
+
+Claude Desktop's [Scheduled Tasks](https://code.claude.com/docs/en/scheduled-tasks) run recurring autonomous workflows on a cron schedule. Each run fires a fresh Claude session with full MCP access — including all bridge tools.
+
+### How it works with the bridge
+
+When a scheduled task fires, Claude Desktop loads your MCP servers from config. If the bridge's stdio shim is configured (see [Use with Claude Desktop](#use-with-claude-desktop)), the task gets full access to all bridge tools.
+
+```
+Cron trigger (e.g., daily 9am)
+    │
+    ▼
+Claude Desktop (fresh session)
+    │
+    ▼  loads MCP servers
+Bridge Server ──► IDE Extension ──► Your Code
+    │
+    ▼  structured report
+Task history (viewable in Desktop sidebar)
+```
+
+### Ready-made task templates
+
+Copy any of these into `~/.claude/scheduled-tasks/` to set up a recurring workflow:
+
+| Template | Schedule | What it does |
+|----------|----------|-------------|
+| `nightly-review` | Daily | Review uncommitted changes, diagnostics, test status |
+| `health-check` | Hourly/Daily | Full project health: tests, diagnostics, security advisories |
+| `dependency-audit` | Weekly | Scan dependencies for CVEs and outdated packages |
+
+```bash
+# Install a scheduled task template
+cp -r templates/scheduled-tasks/health-check ~/.claude/scheduled-tasks/
+```
+
+Then open Claude Desktop → Schedule → configure the frequency and permissions for the task.
+
+### Bridge prompts for scheduled contexts
+
+The `health-check` MCP prompt (`/mcp__bridge__health-check`) produces the same structured report as the scheduled task template — useful for ad-hoc runs from any MCP client.
+
+### Bridge automation vs. Desktop scheduled tasks
+
+The bridge has its own event-driven automation system (`--automation --automation-policy`). Here's when to use which:
+
+| Feature | Trigger | Persistence | Best for |
+|---------|---------|-------------|----------|
+| **Desktop Scheduled Tasks** | Time-based (cron) | Survives restarts | Nightly reviews, weekly audits, periodic checks |
+| **Bridge Automation Hooks** | Event-driven (file save, diagnostic error) | Requires bridge running | Immediate reactions: auto-fix on error, lint on save |
+
+They're complementary — use scheduled tasks for periodic health checks and bridge automation for real-time reactions.
+
+---
+
 ## Use with Claude.ai Web
 
 Connect the bridge to [claude.ai](https://claude.ai) via a **Custom Connector** — chat with your IDE from the browser without installing anything extra.
@@ -612,36 +817,45 @@ The bridge is now permanently reachable at `https://bridge.yourdomain.com`. The
 
 > **Auto-start:** Run `cloudflared service install` to register the tunnel as a systemd service so it starts on boot alongside the bridge.
 
-### Step 2 — Start the bridge with a fixed token
+### Step 2 — Start the bridge with OAuth enabled
 
 ```bash
-# Generate a token once and keep it — store it somewhere safe
+# Generate a token once — keep it safe, you'll need it to approve connections
 TOKEN=$(uuidgen)
 
-claude-ide-bridge --bind 0.0.0.0 --workspace /path/to/project --fixed-token $TOKEN
+claude-ide-bridge \
+  --bind 0.0.0.0 \
+  --workspace /path/to/project \
+  --fixed-token $TOKEN \
+  --issuer-url https://bridge.yourdomain.com \
+  --cors-origin https://claude.ai
 ```
 
-`--fixed-token` ensures the token never rotates across restarts, so your connector URL stays valid permanently.
+- `--fixed-token` — token never rotates across restarts
+- `--issuer-url` — your public HTTPS URL; activates OAuth 2.0 so claude.ai can authenticate
+- `--cors-origin https://claude.ai` — allows claude.ai's browser requests to reach the bridge
 
 ### Step 3 — Add the Custom Connector on claude.ai
 
 1. Go to **claude.ai → Settings → Integrations → Add custom connector**
-2. Enter the connector URL:
+2. Enter the MCP endpoint URL (no token in the URL — OAuth handles auth):
    ```
-   https://bridge.yourdomain.com/mcp?token=<your-token>
+   https://bridge.yourdomain.com/mcp
    ```
-3. Save — claude.ai verifies the connection and lists all available tools
+3. Click **Connect** — claude.ai redirects you to the bridge's authorization page
+4. Enter your bridge token (`$TOKEN` from Step 2) and click **Authorize**
+5. claude.ai completes the OAuth exchange and lists all available tools
 
-The `?token=` query param is supported alongside `Authorization: Bearer` headers, since the claude.ai connector UI cannot set custom request headers.
+> The bridge token is entered once during authorization. After that, claude.ai holds a short-lived OAuth access token that it refreshes automatically — you don't need to update the connector URL when the bridge restarts.
 
-> **Tool availability:** All 138+ tools are available. VS Code extension-dependent tools (LSP, debugger, editor state) require the extension to be connected on the remote machine. Without the extension, ~80 CLI tools still work (file ops, git, terminal, search, HTTP client).
+> **Tool availability:** All 124+ tools are available. VS Code extension-dependent tools (LSP, debugger, editor state) require the extension to be connected on the remote machine. Without the extension, ~74 CLI tools still work (file ops, git, terminal, search, HTTP client).
 
 ### Alternatives
 
 <details>
 <summary>Reverse proxy with nginx or Caddy (if you already have a domain + TLS setup)</summary>
 
-Put nginx or Caddy in front of the bridge with TLS. See [docs/remote-access.md](docs/remote-access.md) for a ready-made config.
+Put nginx or Caddy in front of the bridge with TLS — proxy **all paths** (not just `/mcp`) so the OAuth discovery and authorization endpoints are reachable. See [docs/remote-access.md](docs/remote-access.md) for a ready-made config.
 
 </details>
 
@@ -705,17 +919,24 @@ claude-ide-bridge gen-claude-md [--write] [--workspace <path>]
 ### Bridge options (default mode)
 
 ```
+--bind <addr>             Bind address (default: 127.0.0.1)
+--fixed-token <uuid>      Stable auth token across restarts (default: random UUID)
+--issuer-url <url>        Public HTTPS URL — activates OAuth 2.0 for remote clients
+--cors-origin <url>       Allow cross-origin requests from this origin (repeatable)
 --workspace <path>        Workspace folder (default: cwd)
 --ide-name <name>         IDE name shown to Claude (default: auto-detect)
 --editor <cmd>            Editor CLI command (default: auto-detect)
 --port <number>           Force specific port (default: random)
 --linter <name>           Enable specific linter (repeatable; default: auto-detect)
+--grace-period <ms>       Reconnect grace period in ms (default: 30000, max: 600000)
 --allow-command <cmd>     Add command to execution allowlist (repeatable)
 --timeout <ms>            Command timeout in ms (default: 30000, max: 120000)
 --max-result-size <KB>    Max output size in KB (default: 512, max: 4096)
+--vps                     VPS/headless mode: adds curl, systemctl, nginx, pm2, docker to allowlist
 --watch                   Supervisor mode: auto-restart on crash (exponential backoff, max 30s)
 --auto-tmux               Re-exec inside a tmux session automatically
 --tool-rate-limit <n>     Max tool calls per minute per session (default: 60)
+--audit-log <path>        Append all tool calls to a JSONL file (persistent audit trail)
 --claude-driver <mode>    Claude subprocess driver: subprocess | api | none (default: none)
 --claude-binary <path>    Path to claude binary (default: claude)
 --automation              Enable event-driven automation
@@ -761,7 +982,7 @@ claude-ide-bridge/
 
 - **`getHandoffNote`** / **`setHandoffNote`** — a persistent scratchpad (10KB, shared across all MCP sessions) stored at `~/.claude/ide/handoff-note.json`. Use it to pass context between a Claude Code CLI session and Claude Desktop, or between sessions on different machines. Ask Claude to write a summary note before closing a session, then read it in the next.
 
-- **`createGithubIssueFromAIComment`** — Claude can scan your code for `// AI:` comments (e.g. `// AI: this function needs error handling`) and file them as GitHub issues automatically. Run `getAIComments` first to populate the cache, then `createGithubIssueFromAIComment` to file them.
+- **`createGithubIssueFromAIComment`** — Claude can scan your code for `// AI:` comments (e.g. `// AI: this function needs error handling`) and file them as GitHub issues automatically. The extension pushes AI comment cache in real time — call `createGithubIssueFromAIComment` directly to file the detected comments as issues.
 
 - **`executeVSCodeCommand`** — run any VS Code command by ID with optional arguments. Requires the command to be on the allowlist (`--vscode-allow-command <id>`). Use `listVSCodeCommands` to discover available command IDs.
 
@@ -800,7 +1021,7 @@ The bridge saves a checkpoint every 30 seconds to `~/.claude/ide/checkpoint-<por
 
 ### Reduce duplicate git instructions
 
-Claude Code ships with its own built-in commit/PR guidance. When using the bridge's dedicated git tools (`gitCommit`, `gitPush`, `gitCreatePR`, etc.), you can suppress the duplicate Claude Code instructions by adding to `~/.claude/settings.json`:
+Claude Code ships with its own built-in commit/PR guidance. When using the bridge's dedicated git tools (`gitCommit`, `gitPush`, `githubCreatePR`, etc.), you can suppress the duplicate Claude Code instructions by adding to `~/.claude/settings.json`:
 
 ```json
 {
@@ -820,7 +1041,7 @@ Production-grade reliability:
 - Circuit breaker with exponential backoff for timeout cascades
 - Generation counter preventing stale handler responses
 - Extension-required tool filtering when extension disconnects
-- 1237 tests (bridge) + 362 extension tests; full WebSocket round-trip integration coverage
+- 1265+ tests (bridge) + 394 extension tests; full WebSocket round-trip integration coverage
 - MCP elicitation support (`elicitation: {}` capability) — bridge can send `elicitation/create` mid-task to request structured user input via Claude Code's interactive dialog (Claude Code 2.1.76+)
 
 ## Building
@@ -829,20 +1050,20 @@ Production-grade reliability:
 # Bridge
 npm run build        # TypeScript compilation
 npm run dev          # Development with tsx
-npm test             # Run 1237 bridge tests
+npm test             # Run 1265+ bridge tests
 
 # Extension
 cd vscode-extension
 npm run build        # esbuild bundle
 npm run package      # Create .vsix
-npm test             # Run 362 extension tests
+npm test             # Run 394 extension tests
 ```
 
 ## Troubleshooting
 
 ### Claude says a tool doesn't exist or tool count seems low
 
-When the VS Code extension is disconnected, tools that require extension access are automatically hidden from Claude's tool list. About 50 tools become unavailable (terminal, LSP, debug, editor state, etc.). Check the "Claude IDE Bridge" output channel in VS Code — if you see a disconnection event, use `Claude IDE Bridge: Reconnect` from the command palette, or reload the window.
+When the VS Code extension is disconnected, tools that require extension access are automatically hidden from Claude's tool list. About 50 tools become unavailable (terminal, LSP, debug, editor state, etc.) — leaving ~74 tools accessible via CLI fallbacks. Check the "Claude IDE Bridge" output channel in VS Code — if you see a disconnection event, use `Claude IDE Bridge: Reconnect` from the command palette, or reload the window.
 
 ### Bridge and extension version mismatch
 
@@ -891,6 +1112,13 @@ tmux kill-server
 env -u CLAUDECODE claude-ide-bridge start-all --workspace /your/project
 ```
 
+## Developer Documentation
+
+See [Documentation](#documentation) above for all guides, ADRs, and reference docs. AI-specific project instructions:
+
+- **[CLAUDE.md](CLAUDE.md)** — Project instructions for AI assistants (Claude Code, Cursor). Covers architecture rules, plugin system, OAuth, remote deployment, security model.
+- **[.cursorrules](.cursorrules)** — Imperative rules for Cursor IDE AI. Condensed mirror of CLAUDE.md.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and how to add new tools.

package/dist/activityLog.d.ts

@@ -1,23 +1,5 @@
-export interface ActivityEntry {
-    id: number;
-    timestamp: string;
-    tool: string;
-    durationMs: number;
-    status: "success" | "error";
-    errorMessage?: string;
-}
-export interface LifecycleEntry {
-    id: number;
-    timestamp: string;
-    event: string;
-    metadata?: Record<string, unknown>;
-}
-export type TimelineEntry = ({
-    kind: "tool";
-} & ActivityEntry) | ({
-    kind: "lifecycle";
-} & LifecycleEntry);
-type ActivityListener = (kind: string, entry: ActivityEntry | LifecycleEntry) => void;
+export type { ActivityEntry, ActivityListener, LifecycleEntry, TimelineEntry, } from "./activityTypes.js";
+import type { ActivityEntry, ActivityListener, TimelineEntry } from "./activityTypes.js";
 export declare class ActivityLog {
     private entries;
     private lifecycleEntries;
@@ -52,4 +34,3 @@ export declare class ActivityLog {
         errors: number;
     }>;
 }
-export {};

package/dist/activityLog.js

@@ -59,13 +59,16 @@ export class ActivityLog {
                         }
                     }
                 }
-                catch {
-                    // skip malformed lines
+                catch (err) {
+                    process.stderr.write(`[activityLog] Skipping malformed JSON line: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             }
         }
-        catch {
-            // file doesn't exist yet, that's fine
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`[activityLog] Failed to load persist file: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
         }
     }
     _appendToDisk(kind, entry) {
@@ -86,13 +89,16 @@ export class ActivityLog {
                         this._rotateDisk();
                     }
                 }
-                catch {
-                    // file doesn't exist yet — nothing to rotate
+                catch (err) {
+                    const code = err.code;
+                    if (code !== "ENOENT") {
+                        process.stderr.write(`[activityLog] Failed to stat persist file for rotation: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
                 }
                 await fs.promises.appendFile(persistPath, line);
             }
-            catch {
-                // Disk persistence is best-effort — never block tool execution
+            catch (err) {
+                process.stderr.write(`[activityLog] Disk persistence failed (best-effort): ${err instanceof Error ? err.message : String(err)}\n`);
             }
         })();
     }
@@ -115,8 +121,8 @@ export class ActivityLog {
             }
             fs.writeFileSync(this.persistPath, `${lines.join("\n")}\n`);
         }
-        catch {
-            // ignore rotation errors
+        catch (err) {
+            process.stderr.write(`[activityLog] Rotation failed: ${err instanceof Error ? err.message : String(err)}\n`);
         }
     }
     record(tool, durationMs, status, errorMessage) {

package/dist/activityLog.js.map

@@ -1 +1 @@
-{"version":3,"file":"activityLog.js","sourceRoot":"","sources":["../src/activityLog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"activityLog.js","sourceRoot":"","sources":["../src/activityLog.ts"],"names":[],"mappings":"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"}

package/dist/activityTypes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared type definitions for the activity log.
+ *
+ * Extracted into a standalone file (no imports) to break the circular
+ * dependency that would arise if server.ts imported from activityLog.ts
+ * directly. Both server.ts and activityLog.ts import from here instead.
+ */
+export interface ActivityEntry {
+    id: number;
+    timestamp: string;
+    tool: string;
+    durationMs: number;
+    status: "success" | "error";
+    errorMessage?: string;
+}
+export interface LifecycleEntry {
+    id: number;
+    timestamp: string;
+    event: string;
+    metadata?: Record<string, unknown>;
+}
+export type TimelineEntry = ({
+    kind: "tool";
+} & ActivityEntry) | ({
+    kind: "lifecycle";
+} & LifecycleEntry);
+export type ActivityListener = (kind: string, entry: ActivityEntry | LifecycleEntry) => void;

package/dist/activityTypes.js

@@ -0,0 +1,9 @@
+/**
+ * Shared type definitions for the activity log.
+ *
+ * Extracted into a standalone file (no imports) to break the circular
+ * dependency that would arise if server.ts imported from activityLog.ts
+ * directly. Both server.ts and activityLog.ts import from here instead.
+ */
+export {};
+//# sourceMappingURL=activityTypes.js.map

package/dist/activityTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activityTypes.js","sourceRoot":"","sources":["../src/activityTypes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/bridge.js

@@ -90,6 +90,10 @@ export class Bridge {
             this.logger.info(`OAuth 2.0 enabled — issuer: ${config.issuerUrl}`);
         }
         this.activityLog = new ActivityLog();
+        if (config.auditLogPath) {
+            this.activityLog.setPersistPath(config.auditLogPath);
+            this.logger.info(`Audit log: ${config.auditLogPath}`);
+        }
         this.extensionClient = new ExtensionClient(this.logger);
         // Handle new Claude Code connections
         this.server.on("connection", (ws) => {