docs: update meta files for unified sidecar bundle
Updated all docs, CLAUDE.md files, README, and CHANGELOG to reflect the consolidated sidecar approach (single agent-runner.mjs for both Deno and Node.js). Removed references to agent-runner-deno.ts as active runner. Added progress log entry for 2026-03-07 session.
This commit is contained in:
Hibryda
parent
2409642925
commit
f97e7391a9
7 changed files with 27 additions and 12 deletions
|
|
@ -26,7 +26,7 @@
|
|||
|
||||
- WebKit2GTK has no WebGL — xterm.js must use Canvas addon explicitly.
|
||||
- Agent sessions use `@anthropic-ai/claude-agent-sdk` query() function (migrated from raw CLI spawning due to piped stdio hang bug). SDK handles subprocess management internally. All output goes through the adapter layer (`src/lib/adapters/sdk-messages.ts`) — SDK message format matches CLI stream-json.
|
||||
- Sidecar uses Deno-first + Node.js fallback (`sidecar/agent-runner-deno.ts` preferred, `sidecar/agent-runner.ts` fallback). SidecarCommand struct in sidecar.rs abstracts runtime. Communicates with Rust via stdio NDJSON. Both runners MUST strip ALL `CLAUDE*` prefixed env vars via SDK's `env` option — without this, nesting detection triggers when BTerminal is launched from a Claude Code terminal. Session stop uses AbortController.abort() (not process.kill()).
|
||||
- Sidecar uses a single pre-built bundle (`sidecar/dist/agent-runner.mjs`) that runs on both Deno and Node.js. SidecarCommand struct in sidecar.rs abstracts runtime (Deno preferred for faster startup, Node.js fallback). Communicates with Rust via stdio NDJSON. The sidecar MUST strip ALL `CLAUDE*` prefixed env vars via SDK's `env` option — without this, nesting detection triggers when BTerminal is launched from a Claude Code terminal. Session stop uses AbortController.abort() (not process.kill()).
|
||||
- AgentPane does NOT stop agents in onDestroy — onDestroy fires on layout remounts, not just explicit close. Stop-on-close is handled by TilingGrid.svelte's onClose handler (checks pane type + session status before calling stopAgent).
|
||||
- Agent dispatcher (`src/lib/agent-dispatcher.ts`) is a singleton that routes sidecar events to the agent store. Also handles subagent pane spawning (SUBAGENT_TOOL_NAMES detection, toolUseToChildPane routing map).
|
||||
- AgentQueryOptions supports `permission_mode` field (flows Rust -> sidecar -> SDK). Defaults to 'bypassPermissions', supports 'default' mode. allowDangerouslySkipPermissions is conditionally set.
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
- Sidecar resolution unified: single pre-built `agent-runner.mjs` bundle replaces separate `agent-runner-deno.ts` + `agent-runner.ts` lookup; same `.mjs` file runs under both Deno and Node.js
|
||||
- `resolve_sidecar_command()` in sidecar.rs now checks deno/node availability upfront before searching paths, improved error message with runtime availability note
|
||||
- Removed `agent-runner-deno.ts` from tauri.conf.json bundled resources (only `dist/agent-runner.mjs` shipped)
|
||||
|
||||
### Added
|
||||
- `@anthropic-ai/claude-agent-sdk` ^0.2.70 npm dependency for sidecar agent session management
|
||||
- `build:sidecar` npm script for esbuild bundling of agent-runner.ts (SDK bundled in, no external dependency at runtime)
|
||||
|
|
|
|||
|
|
@ -67,8 +67,8 @@ Terminal emulator with SSH and Claude Code session management. v1 (GTK3+VTE Pyth
|
|||
| `v2/src/lib/components/Settings/SettingsDialog.svelte` | Settings modal (shell, cwd, max panes, theme) |
|
||||
| `v2/src/lib/adapters/session-bridge.ts` | Session/layout/group persistence IPC wrapper |
|
||||
| `v2/src/lib/components/Markdown/MarkdownPane.svelte` | Markdown file viewer (marked.js + shiki, live reload) |
|
||||
| `v2/sidecar/agent-runner.ts` | Node.js sidecar (uses @anthropic-ai/claude-agent-sdk) |
|
||||
| `v2/sidecar/agent-runner-deno.ts` | Deno sidecar (preferred, uses npm:@anthropic-ai/claude-agent-sdk) |
|
||||
| `v2/sidecar/agent-runner.ts` | Sidecar source (compiled to .mjs by esbuild) |
|
||||
| `v2/sidecar/dist/agent-runner.mjs` | Bundled sidecar (runs on both Deno and Node.js) |
|
||||
| `v2/src/lib/adapters/sdk-messages.test.ts` | Vitest tests for SDK message adapter (25 tests) |
|
||||
| `v2/src/lib/adapters/agent-bridge.test.ts` | Vitest tests for agent IPC bridge (11 tests) |
|
||||
| `v2/src/lib/agent-dispatcher.test.ts` | Vitest tests for agent dispatcher (28 tests) |
|
||||
|
|
@ -88,7 +88,7 @@ Terminal emulator with SSH and Claude Code session management. v1 (GTK3+VTE Pyth
|
|||
- Cargo workspace: bterminal-core (shared), bterminal-relay (remote binary), src-tauri (Tauri app)
|
||||
- xterm.js with Canvas addon (no WebGL on WebKit2GTK)
|
||||
- Agent sessions via `@anthropic-ai/claude-agent-sdk` query() function (migrated from raw CLI spawning)
|
||||
- Sidecar uses SDK internally (Deno-first + Node.js fallback, stdio NDJSON to Rust)
|
||||
- Sidecar uses SDK internally (single .mjs bundle, Deno-first + Node.js fallback, stdio NDJSON to Rust)
|
||||
- portable-pty for terminal management (in bterminal-core)
|
||||
- Multi-machine: bterminal-relay WebSocket server + RemoteManager WebSocket client
|
||||
- SQLite session persistence (rusqlite, WAL mode) + layout restore on startup
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Terminal with session panel (MobaXterm-style), built with GTK 3 + VTE. Catppuccin Mocha theme.
|
||||
|
||||
> **v2 Phases 1-7 + Multi-Machine (A-D) complete:** Multi-session Claude agent dashboard using Tauri 2.x + Svelte 5. Features: multi-pane terminal with PTY backend and copy/paste, agent panes with structured output, tree visualization with subtree cost and session resume, **subagent/agent-teams support** (auto-spawns child panes for subagents with parent/child navigation and recursive cost aggregation), **multi-machine support** (bterminal-relay WebSocket server + RemoteManager for managing agents/terminals on remote machines), session groups/folders with collapsible sidebar headers, SSH session management, ctx context database viewer, SQLite session persistence with layout restore, live markdown file viewer with Shiki syntax highlighting, global status bar with cost tracking, toast notifications, settings dialog with theme flavors (Catppuccin Latte/Frappe/Macchiato/Mocha) and live hot-swap, detached pane mode (pop-out windows), pane drag-resize handles, auto-updater plugin with signing key configured, @anthropic-ai/claude-agent-sdk integration, Deno-first sidecar with Node.js fallback, CSS Grid tiling, .deb + AppImage packaging, GitHub Actions CI, 114 vitest + 29 cargo tests. Branch `v2-mission-control`. See [docs/task_plan.md](docs/task_plan.md) for architecture and [docs/phases.md](docs/phases.md) for implementation plan.
|
||||
> **v2 Phases 1-7 + Multi-Machine (A-D) complete:** Multi-session Claude agent dashboard using Tauri 2.x + Svelte 5. Features: multi-pane terminal with PTY backend and copy/paste, agent panes with structured output, tree visualization with subtree cost and session resume, **subagent/agent-teams support** (auto-spawns child panes for subagents with parent/child navigation and recursive cost aggregation), **multi-machine support** (bterminal-relay WebSocket server + RemoteManager for managing agents/terminals on remote machines), session groups/folders with collapsible sidebar headers, SSH session management, ctx context database viewer, SQLite session persistence with layout restore, live markdown file viewer with Shiki syntax highlighting, global status bar with cost tracking, toast notifications, settings dialog with theme flavors (Catppuccin Latte/Frappe/Macchiato/Mocha) and live hot-swap, detached pane mode (pop-out windows), pane drag-resize handles, auto-updater plugin with signing key configured, @anthropic-ai/claude-agent-sdk integration, unified sidecar bundle (Deno-first, Node.js fallback), CSS Grid tiling, .deb + AppImage packaging, GitHub Actions CI, 114 vitest + 29 cargo tests. Branch `v2-mission-control`. See [docs/task_plan.md](docs/task_plan.md) for architecture and [docs/phases.md](docs/phases.md) for implementation plan.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ bterminal-v2/
|
|||
src/
|
||||
main.rs # Tauri app entry
|
||||
pty.rs # PTY management (portable-pty, not plugin)
|
||||
sidecar.rs # Sidecar lifecycle (Deno-first + Node.js fallback, SidecarCommand)
|
||||
sidecar.rs # Sidecar lifecycle (unified .mjs bundle, Deno-first + Node.js fallback)
|
||||
watcher.rs # File watcher for markdown viewer
|
||||
session.rs # Session + SSH session persistence (SQLite via rusqlite)
|
||||
ctx.rs # Read-only ctx context DB access
|
||||
|
|
@ -74,10 +74,10 @@ bterminal-v2/
|
|||
themes.ts # All 4 Catppuccin flavor definitions
|
||||
app.css
|
||||
sidecar/
|
||||
agent-runner.ts # Node.js sidecar entry point
|
||||
agent-runner-deno.ts # Deno sidecar (preferred when deno available)
|
||||
agent-runner.ts # Sidecar source (compiled to .mjs by esbuild)
|
||||
dist/
|
||||
agent-runner.mjs # Bundled sidecar (runs on both Deno and Node.js)
|
||||
package.json # Agent SDK dependency
|
||||
esbuild.config.ts # Bundle to single file
|
||||
package.json
|
||||
svelte.config.js
|
||||
vite.config.ts
|
||||
|
|
|
|||
|
|
@ -391,6 +391,16 @@ Design: No separate sidecar process per subagent. Parent's sidecar handles all;
|
|||
- [x] Removed `--external:@anthropic-ai/claude-agent-sdk` from esbuild build:sidecar script in package.json
|
||||
- [x] SDK is now bundled into sidecar/dist/agent-runner.mjs (no external dependency at runtime)
|
||||
|
||||
### Session: 2026-03-07 — Unified Sidecar Bundle
|
||||
|
||||
#### Sidecar Resolution Simplification
|
||||
- [x] Consolidated sidecar from two runners (agent-runner-deno.ts + agent-runner.ts) to single pre-built bundle (dist/agent-runner.mjs)
|
||||
- [x] resolve_sidecar_command() in bterminal-core/src/sidecar.rs: checks deno/node availability upfront, searches for dist/agent-runner.mjs only
|
||||
- [x] Removed agent-runner-deno.ts from tauri.conf.json resources array (only agent-runner.mjs bundled)
|
||||
- [x] Same .mjs bundle runs under both Deno and Node.js — no separate TS source needed at runtime
|
||||
- [x] Error message now includes runtime availability note when neither deno nor node found
|
||||
- [x] agent-runner-deno.ts file retained in repo for reference but no longer used by SidecarManager
|
||||
|
||||
### Next Steps
|
||||
- [ ] Real-world relay testing (2 machines)
|
||||
- [ ] TLS/certificate pinning for relay connections
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ The Agent SDK cannot run in Rust or the webview. Solution:
|
|||
- SDK messages forwarded as-is via NDJSON — same format as CLI stream-json
|
||||
- If sidecar crashes: detect via process exit, show error in UI, offer restart
|
||||
- **Packaging:** Bundle the sidecar JS + SDK as a single file (esbuild bundle, SDK included). Require Node.js 20+ as system dependency. Document in install.sh.
|
||||
- **Deno-first:** SidecarCommand struct abstracts runtime. Deno preferred (runs TS directly, no build step). Falls back to Node.js if Deno not in PATH.
|
||||
- **Unified bundle:** Single pre-built agent-runner.mjs works with both Deno and Node.js. SidecarCommand struct abstracts runtime. Deno preferred (faster startup). Falls back to Node.js.
|
||||
|
||||
### SDK Abstraction Layer
|
||||
|
||||
|
|
@ -139,7 +139,7 @@ See [phases.md](phases.md) for the full phased implementation plan.
|
|||
| Vitest for frontend tests | Vitest over Jest — zero-config with Vite, same transform pipeline, faster. Test config in vite.config.ts. | 2026-03-06 |
|
||||
| Deno sidecar evaluation | Proof-of-concept agent-runner-deno.ts created. Deno compiles to single binary (better packaging). Same NDJSON protocol. Not yet integrated. | 2026-03-06 |
|
||||
| Splitter overlays for pane resize | Fixed-position divs outside CSS Grid (avoids layout interference). Mouse drag updates customColumns/customRows state. Resets on preset change. | 2026-03-06 |
|
||||
| Deno-first sidecar with Node.js fallback | SidecarCommand struct abstracts runtime. resolve_sidecar_command() checks Deno first (runs TS directly, no build step), falls back to Node.js. Both bundled in tauri.conf.json resources. | 2026-03-06 |
|
||||
| Unified sidecar bundle | Single agent-runner.mjs works with both Deno and Node.js. resolve_sidecar_command() checks runtime availability upfront, prefers Deno (faster startup). Only .mjs bundled in tauri.conf.json resources. agent-runner-deno.ts removed from bundle. | 2026-03-07 |
|
||||
| Session groups/folders | group_name column in sessions table with ALTER TABLE migration. Pane.group field in layout store. Collapsible group headers in sidebar. Right-click to set group. | 2026-03-06 |
|
||||
| Auto-update signing key | Generated minisign keypair. Pubkey set in tauri.conf.json. Private key for TAURI_SIGNING_PRIVATE_KEY GitHub secret. | 2026-03-06 |
|
||||
| Agent teams: frontend routing only | Subagent panes created by frontend dispatcher, not separate sidecar processes. Parent sidecar handles all messages; routing uses SDK's parentId field. Avoids process explosion for nested subagents. | 2026-03-06 |
|
||||
|
|
@ -155,7 +155,7 @@ See [phases.md](phases.md) for the full phased implementation plan.
|
|||
|
||||
## Open Questions
|
||||
|
||||
1. **Node.js or Deno for sidecar?** Resolved: Deno-first with Node.js fallback. SidecarCommand struct in sidecar.rs abstracts the choice. Deno preferred (runs TS directly, compiles to single binary). Falls back to Node.js if Deno not in PATH. Both now use `@anthropic-ai/claude-agent-sdk` query() instead of raw CLI spawning.
|
||||
1. **Node.js or Deno for sidecar?** Resolved: Single pre-built agent-runner.mjs runs on both Deno and Node.js. SidecarCommand struct in sidecar.rs abstracts the runtime choice. Deno preferred (faster startup). Falls back to Node.js. Both use `@anthropic-ai/claude-agent-sdk` query() bundled into the .mjs file.
|
||||
2. **Multi-machine support?** Resolved: Implemented (Phases A-D complete). See [multi-machine.md](multi-machine.md) for architecture. bterminal-core crate extracted, bterminal-relay binary built, RemoteManager + frontend integration done. Reconnection with exponential backoff implemented. Remaining: real-world testing, TLS.
|
||||
3. **Agent Teams integration?** Phase 7 — frontend routing implemented (subagent pane spawning, parent/child navigation). Needs real-world testing with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
|
||||
4. **Electron escape hatch threshold?** If Canvas xterm.js proves >50ms latency on target system with 4 panes, switch to Electron. Benchmark in Phase 2.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue