@hachej/boring-agent 0.1.40 → 0.1.42

package/README.md

@@ -7,291 +7,70 @@
 
 </div>
 
-A pane-embeddable coding agent with three execution modes behind one interface. Ships as a standalone CLI (`npx @hachej/boring-agent`) and composes into any app shell.
+A pane-embeddable coding agent: an LLM agent loop, a tool catalog, and a chat UI
+behind one interface, with three swappable execution modes. The same agent,
+tools, and UI run in `direct` (host process), `local` (bwrap sandbox), or
+`vercel-sandbox` (Firecracker microVM) mode.
 
-```bash
-npx @hachej/boring-agent
-```
-
----
-
-## TL;DR
-
-**The Problem**: You want a coding agent in the browser — but also as a CLI — and you need it to run your code somewhere safe (or not). Existing solutions force you into one deployment model and one UI.
-
-**The Solution**: One package that ships a full LLM agent loop, tool catalog, and chat UI — with swappable execution backends. Same agent, same tools, same UI. Three modes. Zero config to start.
-
-### Why Use @hachej/boring-agent?
-
-| Feature | What It Does |
-|---------|--------------|
-| **Three execution modes** | `direct` (no isolation, macOS dev) / `local` (bwrap sandbox) / `vercel-sandbox` (Firecracker microVM) |
-| **CLI + embeddable** | `npx @hachej/boring-agent` works standalone; `<ChatPanel />` composes into any layout |
-| **7 standard tools** | `bash`, `read`, `write`, `edit`, `find`, `grep`, `ls` — ported from pi-coding-agent |
-| **Workspace-local runtime provisioning** | Generates `.boring-agent` inside the selected workspace for mirrored skills, SDKs, CLIs, and templates |
-| **Workspace-agnostic FS** | `Workspace` interface — agent tools and HTTP routes share the same filesystem view |
-| **Session management** | List, create, switch, delete sessions with streamed history hydration |
-| **UI bridge** | Agent opens files, panels, and surfaces in the workbench via typed commands |
-| **Model picker + thinking toggle** | Inline in the composer — switch models and reasoning depth per message |
-
-### Quick Example
+## Install
 
 ```bash
-# Start the agent in your current directory — zero setup
-npx @hachej/boring-agent
-
-# Or run with a specific workspace root
-BORING_AGENT_WORKSPACE_ROOT=/path/to/project npx @hachej/boring-agent
-
-# Set the API key
-ANTHROPIC_API_KEY=sk-ant-... npx @hachej/boring-agent
-
-# Run in local sandbox mode (Linux + bubblewrap)
-BORING_AGENT_MODE=local npx @hachej/boring-agent
-```
-
-In the browser chat, try:
-```
-read the README and summarize it
-find all TypeScript files that import "react"
-write a test for src/utils.ts
-```
-
----
-
-## Workspace-local runtime provisioning
-
-Boring UI keeps generated runtime state in the selected workspace at
-`$BORING_AGENT_WORKSPACE_ROOT/.boring-agent`. Plugin skills are mirrored to
-`.boring-agent/skills`, runtime CLIs live under `.boring-agent/node` or
-`.boring-agent/venv`, and templates seed only missing workspace files. The
-folder is generated/disposable and should not be hand-edited or committed.
-
-See [docs/runtime-provisioning.md](docs/runtime-provisioning.md) for the full
-user and plugin-author contract, including package metadata shape,
-`provisionWorkspace: false`, `/api/v1/agent/reload`, and direct/local/Vercel
-mode behavior.
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────┐
-│         Chat UI (browser)           │
-│  Composer · Messages · SessionBar    │
-└──────────────────┬──────────────────┘
-                   │ UIMessage stream (SSE)
-┌──────────────────▼──────────────────┐
-│          Agent Harness              │
-│  (pi-coding-agent loop)             │
-└──────────────────┬──────────────────┘
-                   │ AgentTool[]
-┌──────────────────▼──────────────────┐
-│         Tool Catalog                │
-│  bash · read · write · edit         │
-│  find · grep · ls                   │
-└──────┬──────────────┬───────────────┘
-       │              │
-┌──────▼─────┐ ┌──────▼─────┐
-│ Workspace   │ │  Sandbox   │
-│ (fs ops)   │ │  (exec)    │
-│ read/write │ │  bwrap     │
-│ readdir    │ │  vercel    │
-└────────────┘ └────────────┘
-```
-
-**Two layers, clear boundary:**
-
-- **Layer 1 (Core runtime):** `AgentHarness` · `Catalog` · `Workspace` · `Sandbox` — interfaces locked; adapters swap per mode.
-- **Layer 2 (Integration):** `SessionStore` · `UiBridge` · `Provisioning` — replaceable plumbing, independent evolution.
-
-### Execution Modes
-
-| Mode | Workspace | Sandbox | Isolation | Use Case |
-|------|-----------|---------|-----------|----------|
-| `direct` | `NodeWorkspace` | `DirectSandbox` | None | macOS/Windows dev, quick tests |
-| `local` | `NodeWorkspace` | `BwrapSandbox` | bwrap process jail | Linux deployments, safer default |
-| `vercel-sandbox` | `VercelSandboxWorkspace` | `VercelSandboxExec` | Firecracker microVM | Multi-tenant, remote execution |
-
-**Pairing invariant:** Workspace + Sandbox must target the same filesystem substrate. The adapter factory enforces this at construction — mismatched pairs are impossible.
-
----
-
-## Installation
-
-```bash
-# npm
-npm install @hachej/boring-agent
-
-# pnpm
 pnpm add @hachej/boring-agent
-
-# standalone (no install needed)
-npx @hachej/boring-agent
-```
-
-### From Source
-
-```bash
-git clone https://github.com/hachej/boring-ui.git
-cd boring-ui
-pnpm install
-pnpm --filter @hachej/boring-agent build
-```
-
----
-
-## Quick Start
-
-### 1. As a CLI
-
-```bash
-# Set your API key
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Run in your project directory
-cd /path/to/project
-npx @hachej/boring-agent
+# or: npm install @hachej/boring-agent
 ```
 
-Opens `http://localhost:5200` with a full agent workspace pointed at your cwd.
+Peer deps (optional): `react`, `react-dom`, `tailwindcss`.
 
-### 2. Embedded in an App
+## Usage
 
-**Server:**
+**Server** — standalone Fastify app:
 
 ```ts
 import { createAgentApp } from "@hachej/boring-agent/server"
 
 const app = await createAgentApp({
-  mode: "local",              // "direct" | "local" | "vercel-sandbox"
+  mode: "local",                 // "direct" | "local" | "vercel-sandbox"
   workspaceRoot: process.cwd(),
-  apiBaseUrl: "http://localhost:3000",
 })
 await app.listen({ port: 3001 })
 ```
 
-**Frontend:**
-
-```tsx
-import { ChatPanel, useAgentChat } from "@hachej/boring-agent"
-import "@hachej/boring-agent/front/styles.css"
-
-function App() {
-  return <ChatPanel apiBaseUrl="http://localhost:3000" />
-}
-```
+To embed routes into an existing Fastify instance, use `registerAgentRoutes`
+instead. The full IDE shell (file tree, panes, UI-bridge tools) lives in
+`@hachej/boring-workspace`, which mounts this agent.
 
-### 3. Composed with Workspace
+**Frontend** — the chat panel:
 
 ```tsx
-import { WorkspaceProvider, IdeLayout } from "@hachej/boring-workspace"
 import { ChatPanel } from "@hachej/boring-agent"
+import "@hachej/boring-agent/front/styles.css"
 
 function App() {
-  return (
-    <WorkspaceProvider chatPanel={ChatPanel} workspaceId="proj-1">
-      <IdeLayout />
-    </WorkspaceProvider>
-  )
+  return <ChatPanel apiBaseUrl="http://localhost:3001" />
 }
 ```
 
----
-
-## Package Surfaces
-
-| Import | Environment | What You Get |
-|--------|-------------|--------------|
-| `@hachej/boring-agent` | Browser | `ChatPanel`, `SessionToolbar`, primitives, hooks, `theme.css` |
-| `@hachej/boring-agent/server` | Node | `createAgentApp`, routes, harness, sandbox, workspace adapters |
-| `@hachej/boring-agent/front` | Browser | Frontend-specific (same as top-level, explicit subpath) |
-| `@hachej/boring-agent/shared` | Any | `AgentHarness`, `Workspace`, `Sandbox`, `AgentTool`, `SessionStore` interfaces |
-| `@hachej/boring-agent/front/styles.css` | Browser | CSS custom properties for theming |
-| `@hachej/boring-agent/eval` | Node | Evaluation toolkit for agent behavior |
-
----
-
 ## Configuration
 
-### Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `ANTHROPIC_API_KEY` | Yes | — | Anthropic API key for Claude |
-| `BORING_AGENT_MODE` | No | `direct` | `direct`, `local`, or `vercel-sandbox` |
-| `BORING_AGENT_WORKSPACE_ROOT` | No | `.` | Root directory for workspace |
-| `BORING_AGENT_DEFAULT_MODEL_PROVIDER` | No | `anthropic` | Default model provider |
-| `BORING_AGENT_DEFAULT_MODEL_ID` | No | `claude-sonnet-4-6` | Default model ID |
-| `VERCEL_OIDC_TOKEN` | Remote only | — | Required for `vercel-sandbox` mode |
-| `PORT` | No | `5200` | Server port |
-| `HOST` | No | `localhost` | Server host |
-
-### Config File
-
-`boring.app.toml` (optional, for embedded mode):
-
-```toml
-[runtime]
-mode = "local"           # direct | local | vercel-sandbox
-
-[model]
-default_provider = "anthropic"
-default_id = "claude-sonnet-4-6"
-```
-
----
-
-## Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ANTHROPIC_API_KEY not set` | Missing API key | `export ANTHROPIC_API_KEY=sk-ant-...` |
-| `bwrap not found` (local mode) | bubblewrap not installed | `sudo apt install bubblewrap` (Debian/Ubuntu) |
-| `port already in use` | Port 5200 occupied | `PORT=5201 npx @hachej/boring-agent` |
-| `workspace root not found` | Invalid `BORING_AGENT_WORKSPACE_ROOT` | Point to an existing directory |
-| `Vercel sandbox auth failed` (remote mode) | Missing/invalid OIDC token | Set `VERCEL_OIDC_TOKEN` |
-| `model provider not supported` | Unknown provider in config | Use `anthropic` (only supported provider in v1) |
-
----
-
-## Limitations
-
-- **Single model provider**: Only Anthropic (Claude) is supported in v1. The harness interface is designed to accept others, but only `anthropic` is wired.
-- **No multi-user auth**: The agent is single-workspace-per-instance. Multi-user auth, billing, and workspace CRUD belong to `@hachej/boring-core`.
-- **No git UI**: The agent runs git via `bash`, but there's no status bar, diff pane, or branch picker. When git UI lands, thin routes will be added.
-- **Plugin loading is local-only**: Pi plugins load in the backend Node process. They're disabled in `vercel-sandbox` mode for security.
-- **No browser-agent mode yet**: The `AgentHarness` interface has a `placement: "browser"` option, but no browser harness is implemented.
-- **No MCP tool integration**: Not in scope for v1.
-
----
-
-## FAQ
-
-**Q: What's the difference between `direct` and `local` mode?**  
-A: `direct` runs bash commands with no sandbox — the agent has full access to your machine. `local` wraps commands in bubblewrap (`bwrap`), which provides filesystem and process isolation on Linux. Use `direct` for macOS dev; use `local` on Linux servers.
-
-**Q: Can I use OpenAI or other model providers?**  
-A: Not in v1. Only Anthropic's Claude is wired up. The harness interface is provider-agnostic — community PRs for other providers are welcome.
-
-**Q: How do sessions persist?**  
-A: Via pi-coding-agent's JSONL session files under `${workdir}/.pi/sessions/`. The `PiSessionStore` reads and manages lifecycle. SQLite and IndexedDB implementations are planned.
-
-**Q: Can I add custom tools to the agent?**  
-A: Yes. Use the `CatalogDeps` pattern to build tools that bind to `Workspace` and `Sandbox`. For pi-native tools, register them via pi's extension system (`pi.extensions` in config). In `vercel-sandbox` mode, extensions are disabled.
-
-**Q: What's the UI bridge for?**  
-A: It lets the agent programmatically open files, panels, and surfaces in the workbench. The agent calls `exec_ui({ kind: "openFile", params: { path: "src/index.ts" } })` and the panel opens. It's a typed pubsub bus between backend and frontend.
+Set an API key for the model provider (e.g. `ANTHROPIC_API_KEY`). Common env
+vars: `BORING_AGENT_MODE` (default `direct`), `BORING_AGENT_WORKSPACE_ROOT`
+(default cwd), `BORING_AGENT_PORT`, and the `BORING_AGENT_DEFAULT_MODEL*` /
+`BORING_AGENT_CUSTOM_MODEL*` / `BORING_AGENT_INFOMANIAK*` provider settings. See
+[docs/runtime.md](./docs/runtime.md) and [docs/API.md](./docs/API.md).
 
-**Q: How does stream resumption work?**  
-A: The server wraps the harness's event stream in a per-turn ring buffer. Disconnected clients reconnect via `GET /api/v1/agent/pi-chat/:sessionId/events?from=<seq>`; the replay buffer serves missed events.
+## Documentation
 
----
+See [docs/README.md](./docs/README.md) for the full doc index — architecture,
+the export surfaces (`/front`, `/server`, `/shared`, `/eval`), runtime modes and
+provisioning, theming, plugins, error codes, and risk/cost notes.
 
-*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+## Contributions
 
----
+I do not accept outside contributions for my projects: I don't have the
+bandwidth to review them, and it's my name on the result. Issues and bug reports
+are welcome; PRs may be used to illustrate a fix, but I won't merge them
+directly — I'll have Claude or Codex review submissions via `gh` and
+independently decide whether and how to address them.
 
 ## License
 

package/dist/{agentPluginEvents-CKrZLW3g.d.ts → agentPluginEvents-ZoOjcb5J.d.ts}

@@ -215,6 +215,20 @@ interface WorkspaceChangeEvent {
     oldPath?: string;
     mtimeMs?: number;
 }
+/**
+ * Result of a watcher's readiness probe. `ok: false` means the
+ * implementation decided it cannot observe this workspace (e.g. the
+ * tree is too large to watch without harming the host process) —
+ * hosts should tell clients to fall back rather than wait for events
+ * that will never come.
+ */
+type WorkspaceWatcherReadiness = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    message?: string;
+};
 interface WorkspaceWatcher {
     /**
      * Add a listener for change events. Returns an unsubscribe fn —
@@ -223,6 +237,13 @@ interface WorkspaceWatcher {
      * does NOT tear down the watcher.
      */
     subscribe(listener: (event: WorkspaceChangeEvent) => void): () => void;
+    /**
+     * Optional readiness probe. Implementations with a startup guard
+     * (workspace-size check, native module availability, …) resolve it
+     * once the underlying source is observing — or with `ok: false`
+     * when observation was refused. Absent → assume always ready.
+     */
+    whenReady?(): Promise<WorkspaceWatcherReadiness>;
     /**
      * Tear down the underlying observation source (chokidar instance,
      * sandbox emitter binding, …). Idempotent. Subscribers added after

package/dist/front/index.d.ts

@@ -535,6 +535,8 @@ interface PiChatPanelProps {
     serverResourcesEnabled?: boolean;
     mentionedFiles?: string[] | (() => string[]);
     commands?: SlashCommand[];
+    /** Built-in slash command names to omit from the composer command registry. */
+    excludeBuiltinCommands?: string[];
     toolRenderers?: ToolRendererOverrides;
     createRemoteSession?: (options: RemotePiSessionOptions) => RemotePiSession;
     remoteSessionOptions?: UsePiSessionsOptions['remoteSessionOptions'];
@@ -552,7 +554,7 @@ interface PiChatPanelProps {
     onComposerStop?: () => void;
     onComposerBlockerAction?: (blocker: ComposerBlocker, action: string) => void;
 }
-declare function PiChatPanel({ sessionId, extraCommands, apiBaseUrl, workspaceId, storageScope, requestHeaders, storage, fetch, className, chrome, debug, showSessions, hotReloadEnabled, suggestions, emptyState, emptyPlacement, composerPlaceholder, initialDraft, autoSubmitInitialDraft, onDraftRestored, onAutoSubmitInitialDraftAccepted, onAutoSubmitInitialDraftSettled, model, defaultModel, availableModels, thinkingLevel, thinkingControl, serverResourcesEnabled, mentionedFiles, commands, toolRenderers, createRemoteSession, remoteSessionOptions, hydrateMessages, workspaceWarmupStatus, onSessionReset, onBeforeSubmit, onReloadAgentPlugins, onCommandResult, onComposerWarning, onMentionedFilesConsumed, onData, onOpenArtifact, composerBlockers, onComposerStop, onComposerBlockerAction, }: PiChatPanelProps): react_jsx_runtime.JSX.Element;
+declare function PiChatPanel({ sessionId, extraCommands, apiBaseUrl, workspaceId, storageScope, requestHeaders, storage, fetch, className, chrome, debug, showSessions, hotReloadEnabled, suggestions, emptyState, emptyPlacement, composerPlaceholder, initialDraft, autoSubmitInitialDraft, onDraftRestored, onAutoSubmitInitialDraftAccepted, onAutoSubmitInitialDraftSettled, model, defaultModel, availableModels, thinkingLevel, thinkingControl, serverResourcesEnabled, mentionedFiles, commands, excludeBuiltinCommands, toolRenderers, createRemoteSession, remoteSessionOptions, hydrateMessages, workspaceWarmupStatus, onSessionReset, onBeforeSubmit, onReloadAgentPlugins, onCommandResult, onComposerWarning, onMentionedFilesConsumed, onData, onOpenArtifact, composerBlockers, onComposerStop, onComposerBlockerAction, }: PiChatPanelProps): react_jsx_runtime.JSX.Element;
 
 interface DebugDrawerProps {
     apiBaseUrl?: string;

package/dist/front/index.js

@@ -8534,7 +8534,7 @@ function SlashCommandPicker({ query, commands, onSelect, onDismiss }) {
         autoComplete: "off"
       }
     ),
-    groups.length > 1 && /* @__PURE__ */ jsx30("div", { className: "flex flex-wrap gap-1 border-b border-border/50 px-2 py-1.5", role: "tablist", "aria-label": "Filter by plugin", children: [ALL_PLUGINS, ...groups].map((g) => {
+    /* @__PURE__ */ jsx30("div", { className: "flex flex-wrap gap-1 border-b border-border/50 px-2 py-1.5", role: "tablist", "aria-label": "Filter by plugin", children: [ALL_PLUGINS, ...groups].map((g) => {
       const selected = plugin === g;
       return /* @__PURE__ */ jsx30(
         "button",
@@ -9173,6 +9173,7 @@ function errorMessage2(error, fallback) {
 import { jsx as jsx33, jsxs as jsxs31 } from "react/jsx-runtime";
 var DebugDrawer2 = lazy(() => import("../DebugDrawer-2PUDZ2RL.js").then((m) => ({ default: m.DebugDrawer })));
 var EMPTY_COMMANDS = [];
+var EMPTY_COMMAND_NAMES = [];
 var EMPTY_BLOCKERS = [];
 function PiChatPanel({
   sessionId,
@@ -9205,6 +9206,7 @@ function PiChatPanel({
   serverResourcesEnabled = true,
   mentionedFiles,
   commands = EMPTY_COMMANDS,
+  excludeBuiltinCommands = EMPTY_COMMAND_NAMES,
   toolRenderers,
   createRemoteSession,
   remoteSessionOptions,
@@ -9363,12 +9365,16 @@ function PiChatPanel({
     setLocalSubmittedSessionId(void 0);
   }, []);
   const registry = useMemo12(() => {
-    const effectiveBuiltins = hotReloadEnabled ? builtinCommands : builtinCommands.filter((command) => command.name !== "reload");
+    const excludedBuiltins = new Set(excludeBuiltinCommands);
+    const effectiveBuiltins = builtinCommands.filter((command) => {
+      if (!hotReloadEnabled && command.name === "reload") return false;
+      return !excludedBuiltins.has(command.name);
+    });
     const next = createCommandRegistry(effectiveBuiltins);
     for (const command of extraCommands ?? []) next.register(command);
     for (const command of commands) next.register(command);
     return next;
-  }, [apiBaseUrl, commands, extraCommands, hotReloadEnabled, normalizedRequestHeaders, serverResourcesEnabled, serverSkillsRefreshKey, storageScope]);
+  }, [apiBaseUrl, commands, excludeBuiltinCommands, extraCommands, hotReloadEnabled, normalizedRequestHeaders, serverResourcesEnabled, serverSkillsRefreshKey, storageScope]);
   const commandsStamp = useServerCommands({
     registry,
     requestHeaders: normalizedRequestHeaders,

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { o as WorkspaceRuntimeContext, S as Sandbox, g as SandboxHandleStore, f as SandboxHandleRecord, W as Workspace, j as TelemetrySink, F as FileSearch, P as PluginRestartWarning, A as AgentTool, q as AgentHarnessFactory } from '../agentPluginEvents-CKrZLW3g.js';
-export { r as AgentHarnessFactoryInput } from '../agentPluginEvents-CKrZLW3g.js';
+import { o as WorkspaceRuntimeContext, S as Sandbox, g as SandboxHandleStore, f as SandboxHandleRecord, W as Workspace, j as TelemetrySink, F as FileSearch, P as PluginRestartWarning, A as AgentTool, q as AgentHarnessFactory } from '../agentPluginEvents-ZoOjcb5J.js';
+export { r as AgentHarnessFactoryInput } from '../agentPluginEvents-ZoOjcb5J.js';
 import { Sandbox as Sandbox$1 } from '@vercel/sandbox';
 import { FastifyInstance, FastifyRequest, FastifyPluginAsync } from 'fastify';
 import { PackageSource, ExtensionFactory, SettingsManager } from '@mariozechner/pi-coding-agent';