@hachej/boring-agent 0.1.41 → 0.1.43

package/docs/ERROR_CODES.md

@@ -1,6 +1,6 @@
 # ERROR_CODES
 
-Canonical registry for stable `@boring/agent` error codes.
+Canonical registry for stable `@hachej/boring-agent` error codes.
 
 All API failures must use the response envelope:
 
@@ -21,6 +21,7 @@ All API failures must use the response envelope:
 
 | Code | When it fires | HTTP status | Suggested client action | Log level | Stability |
 | --- | --- | --- | --- | --- | --- |
+| `UNAUTHORIZED` | Request reached a protected path (e.g. credit metering) without an authenticated user | 401 | re-auth | warn | stable (public API) |
 | `MISSING_API_KEY` | Required provider API key missing from runtime config | 500 | report-bug | error | stable (public API) |
 | `INVALID_API_KEY` | Provider rejects API key as malformed/invalid | 401 | re-auth | warn | stable (public API) |
 | `OIDC_REFRESH_FAILED` | OIDC refresh token exchange fails | 401 | re-auth | warn | stable (public API) |
@@ -43,8 +44,11 @@ All API failures must use the response envelope:
 | `SANDBOX_NOT_READY` | Remote sandbox cold start / provisioning | 503 | retry | warn | stable (public API) |
 | `SANDBOX_EXPIRED` | Remote sandbox TTL elapsed | 410 | retry | warn | stable (public API) |
 | `VERCEL_API_ERROR` | Generic upstream Vercel SDK/API failure | 502 | retry | error | stable (public API) |
+| `REMOTE_WORKER_TIMEOUT` | Remote worker request exceeded its client-side timeout before a response arrived | 504 | retry | warn | stable (public API) |
+| `REMOTE_WORKER_STREAM_CLOSED` | Remote worker filesystem event stream closed unexpectedly | 502 | retry | warn | stable (public API) |
 | `CIRCUIT_OPEN` | Circuit breaker open; request fast-failed | 503 | retry | warn | stable (public API) |
 | `ABORTED` | Request cancelled via `AbortSignal` | 499 | retry | warn | stable (public API) |
+| `PAYMENT_REQUIRED` | Billing/metering sink rejected the run (e.g. credits exhausted) | 402 | user-fix | warn | stable (public API) |
 | `SESSION_NOT_FOUND` | Session id does not exist | 404 | user-fix | warn | stable (public API) |
 | `SESSION_LOCKED` | Session currently locked by concurrent writer | 409 | retry | warn | stable (public API) |
 | `STREAM_BUFFER_EVICTED` | Resume cursor evicted from in-memory stream buffer | 410 | retry | warn | stable (public API) |

package/docs/KNOWN_LIMITATIONS.md

@@ -2,7 +2,7 @@
 
 ## Abandoned Vercel sandboxes (xzr)
 
-`@boring/agent` v1 intentionally does **not** implement a session-close release hook.
+`@hachej/boring-agent` v1 intentionally does **not** implement a session-close release hook.
 If a process crashes or a client disappears before cleanup, the sandbox may remain
 alive until Vercel timeout/TTL.
 
@@ -68,8 +68,8 @@ v1 status: **accepted risk**, documented and monitored.
 
 ## GitHub Connect + `/api/v1/git/*` deferred to v1.x (nfx)
 
-Git HTTP routes are intentionally not shipped in v1. Both `@boring/agent` v1
-and `@boring/workspace` v1 dropped git UI consumers, so `/api/v1/git/*` would
+Git HTTP routes are intentionally not shipped in v1. Both `@hachej/boring-agent` v1
+and `@hachej/boring-workspace` v1 dropped git UI consumers, so `/api/v1/git/*` would
 be dead code today.
 
 ### Current v1 behavior

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # MIGRATION
 
 Migration notes for moving from legacy monorepo-integrated agent flows to
-`@boring/agent` in v2.
+`@hachej/boring-agent` in v2.
 
 ## What Changes
 
@@ -14,37 +14,37 @@ v1-style app code typically mixed these concerns in one place:
 
 In v2, split responsibilities are intentional:
 
-- `@boring/agent`: runtime contracts + tool/harness/sandbox layers.
-- `@boring/workspace`: IDE-style layout package (frontend-only).
+- `@hachej/boring-agent`: agent runtime, tool catalog, harness, sandbox/workspace
+  adapters, and the chat UI (`ChatPanel`).
+- `@hachej/boring-workspace`: IDE-style layout/panes plus the UI-bridge tools
+  (`exec_ui`, `get_ui_state`) and `/api/v1/ui/*` routes.
 - App shell: final composition, mode selection, and product policy.
 
 ## Practical Migration Steps
 
-1. Move chat/runtime logic into `@boring/agent` integration points.
-2. Keep editor/file-tree/layout code in `@boring/workspace` or your own UI.
+1. Move chat/runtime logic into `@hachej/boring-agent` integration points.
+2. Keep editor/file-tree/layout code in `@hachej/boring-workspace` or your own UI.
 3. Route all filesystem and command execution through runtime mode adapters.
-4. Replace ad-hoc shared types with imports from `@boring/agent/shared`.
+4. Replace ad-hoc shared types with imports from `@hachej/boring-agent/shared`.
 5. Keep server-only code in server entry points; avoid server imports in
    frontend/shared paths.
 
 ## Runtime Mode Migration
 
-Current scaffold status:
-
-- `direct` mode is available.
-- `local` (`bwrap`) and `vercel-sandbox` are planned.
-
-If you are migrating today, target `direct` first and keep your integration
-surface mode-agnostic so later adapter swaps are non-breaking.
+All three modes ship: `direct`, `local` (`bwrap`), and `vercel-sandbox`. Select
+via `mode` in `createAgentApp` or the `BORING_AGENT_MODE` env var. Keep your
+integration surface mode-agnostic so adapter swaps are non-breaking. See
+[runtime.md](./runtime.md).
 
 ## Contract Hygiene Checklist
 
 - No `node:*` imports in `src/shared/**`.
 - No `Buffer` in shared contracts (`Uint8Array` only).
-- Keep UI commands flowing through `UiBridge.postCommand`.
-- Keep session/tool/workspace behavior aligned with `@boring/agent/shared`.
+- Keep session/tool/workspace behavior aligned with `@hachej/boring-agent/shared`.
 
 ## References
 
-- Agent spec + migration design rationale: `docs/plans/agent-package-spec.md`
+- Runtime modes: [runtime.md](./runtime.md)
+- API surface: [API.md](./API.md)
 - README quickstart/context: `../README.md`
+- Historical design notes: `docs/plans/archive/` (archival; not current truth)

package/docs/PERFORMANCE.md

@@ -18,7 +18,7 @@
 Command used:
 
 ```bash
-pnpm --filter @boring/agent run bench:vercel-cold-start -- \
+pnpm --filter @hachej/boring-agent run bench:vercel-cold-start -- \
   --iterations 10 \
   --runtime python3.13 \
   --snapshot-id <snapshot-id>

package/docs/PLUGINS.md

@@ -1,22 +1,27 @@
 # PLUGINS
 
-Plugin and extension notes for `@boring/agent`.
+Plugin and extension notes for `@hachej/boring-agent`.
 
-## Current Status
+## Two extension paths
 
-The full plugin runtime is not shipped yet in this scaffold.
+There are two ways to extend the agent, depending on host integration:
 
-Today:
+1. **Pi-native resources** (`package.json#pi`: `extensions`, `skills`,
+   `prompts`, `systemPrompt`) — discovered by the Pi harness in `direct`/`local`
+   mode and reloadable through `/reload`. This is the right place for portable,
+   hot-reloadable tools and skills. See [tools.md](./tools.md).
+2. **Trusted server plugins** (`@hachej/boring-workspace` `defineServerPlugin`)
+   — static/boot-time `agentTools`, routes, and provisioning declared by trusted
+   server code. See [tools.md](./tools.md) and
+   [runtime-provisioning.md](./runtime-provisioning.md).
 
-- Tool contracts are defined in `src/shared/tool.ts`.
-- Runtime catalog/harness integration is still under active implementation.
+Both paths converge on the same `AgentTool` contract
+(`src/shared/tool.ts`). The standalone `createAgentApp` ships no UI tools;
+`exec_ui`/`get_ui_state` and UI routes are owned by `@hachej/boring-workspace`.
 
-## Planned Integration Model
+## Tool contract
 
-The intended extension seam is "register additional tools into the catalog"
-without modifying core runtime internals.
-
-Each tool should provide:
+Each tool provides:
 
 - Stable `name`
 - Clear `description`
@@ -29,6 +34,22 @@ Each tool should provide:
 - `toolCallId`
 - Optional progress callbacks (`onUpdate`)
 
+Optional fields:
+
+- `readinessRequirements?: ToolReadinessRequirement[]` — gates the tool on
+  runtime readiness. `mergeTools` assigns `['workspace-fs']` to plugin tools
+  that omit it (built-in/`extraTools` tools keep whatever they declare).
+- `promptSnippet?` — extra guidance injected into the system prompt when the
+  tool is registered.
+
+## Trust & runtime modes
+
+Plugin tools' `execute()` run in the **host Node process** and bypass the
+sandbox by design — treat plugin code as trusted local/workspace code. Plugin
+auto-discovery is local-mode-only (see the `vercel-sandbox` caveat below). For
+the full internal-vs-external plugin trust model, see
+`packages/workspace/docs/PLUGIN_SYSTEM.md` §1.1.
+
 ## Safety + Compatibility Rules
 
 - Validate all plugin input against schema before execution.
@@ -63,6 +84,12 @@ previous tool came from built-ins, `extraTools`, or another plugin.
 
 ## Discovery Sources (direct/local)
 
+This section describes **Pi-native resource discovery** at the harness level.
+Workspace runtime/generated plugins are a higher-level package format under
+`.pi/extensions/<id>/package.json` documented in
+`packages/workspace/docs/PLUGIN_SYSTEM.md`; those packages may themselves
+declare `pi.extensions` resources.
+
 In `direct` and `local` mode, plugin discovery can load tools from:
 
 - `~/.pi/agent/extensions/*.js|*.mjs` (global)
@@ -104,5 +131,8 @@ When porting plugins from host modes to `vercel-sandbox`, expect differences:
 
 ## References
 
-- Canonical design: `docs/plans/agent-package-spec.md`
+- Adding tools: [tools.md](./tools.md)
+- Chat `/slash` commands as a plugin surface:
+  `packages/workspace/docs/PLUGIN_SYSTEM.md` §4.7
 - Minimal integration sketch: `examples/with-custom-tool/README.md`
+- Historical design notes: `docs/plans/archive/` (archival; not current truth)

package/docs/README.md

@@ -1,18 +1,95 @@
-# @boring/agent Docs
+# @hachej/boring-agent Docs
 
-This folder contains user-facing package docs for `@boring/agent`.
+`@hachej/boring-agent` is a pane-embeddable coding agent: an LLM agent loop, a
+tool catalog, and a chat UI, with swappable execution backends. The same agent,
+tools, and UI run in three modes — `direct` (host process), `local` (bwrap
+sandbox), and `vercel-sandbox` (Firecracker microVM) — selected at construction.
+It is consumed two ways: standalone via `createAgentApp` (Fastify server +
+`ChatPanel`), or mounted into `@hachej/boring-workspace` for the full IDE shell.
 
-## Start Here
+## Architecture
 
-- [API](./API.md) — current export surface and contract status.
-- [STYLING](./STYLING.md) — CSS-variable theming contract and guardrails.
-- [PLUGINS](./PLUGINS.md) — extension model and runtime-mode caveats.
-- [runtime](./runtime.md) — runtime cwd contract, `.boring-agent/` layout, provisioning examples, and doctor diagnostics.
-- [MIGRATION](./MIGRATION.md) — migration guidance for v1-style integrations.
+```
+Chat UI (ChatPanel / front)
+   │  pi-chat SSE stream
+Agent HTTP routes (registerAgentRoutes / createAgentApp)
+   │
+Agent harness (pi-coding-agent loop)  ── Tool catalog (AgentTool[])
+   │                                          │
+Workspace (filesystem)            Sandbox (command execution)
+```
 
-## Scope
+- **front** (`src/front`) — `ChatPanel` (= `PiChatPanel`), primitives, slash
+  commands, tool renderers, session hooks. Browser-only.
+- **server** (`src/server`) — `createAgentApp`, `registerAgentRoutes`, the Pi
+  harness adapter, sandbox/workspace adapters, runtime provisioning, model
+  config, HTTP routes. Node-only.
+- **shared** (`src/shared`) — platform-agnostic contracts and zod schemas
+  (`AgentHarness`, `Workspace`, `Sandbox`, `AgentTool`, `SessionStore`, chat
+  frames, error codes).
+- **eval** (`src/eval`) — agent-behavior evaluation toolkit.
 
-These docs track the implementation status of the v2 scaffold and call out
-roadmap-only APIs explicitly to avoid over-promising.
+Data flow: the browser opens a pi-chat SSE stream; the server drives the
+pi-coding-agent harness; tools resolve filesystem ops through the `Workspace`
+adapter and shell/exec through the `Sandbox` adapter. Workspace + Sandbox must
+target the same filesystem substrate (the mode adapter enforces the pairing).
 
-For canonical design context, see `./plans/agent-package-spec.md`.
+## Key abstractions
+
+The public surfaces a consumer or extender touches (all in
+`@hachej/boring-agent/shared` unless noted):
+
+- `AgentHarness` — the agent loop interface; pi-coding-agent is the v1 impl.
+- `Workspace` / `Sandbox` — filesystem and command-execution adapters, swapped
+  per mode.
+- `AgentTool` + `CatalogDeps` — the tool contract and the deps tools bind to.
+- `SessionStore` — session listing/lifecycle.
+- `createAgentApp` / `registerAgentRoutes` (`/server`) — entry points to run or
+  embed the server.
+- `ChatPanel` (`/front`) — the embeddable UI.
+
+## Architectural decisions
+
+Locked decisions live in the root [`docs/DECISIONS.md`](../../../docs/DECISIONS.md);
+the agent ↔ workspace boundary is in
+[`docs/WORKSPACE_CONTRACT.md`](../../../docs/WORKSPACE_CONTRACT.md). Highlights:
+
+- Standalone CLI-shaped product; same code embeds into a host shell — decision 1.
+- pi-coding-agent as the v1 harness behind a generic `AgentHarness` — decisions 4–5.
+- `mode = direct | local | vercel-sandbox`; Workspace+Sandbox pairing invariant — decisions 7a–7f.
+- Single Anthropic provider by default, but the model layer also supports custom
+  OpenAI-compatible and Infomaniak providers — decision 10.
+- Plugins extend via Pi resources or trusted server plugins, not core edits — decision 8.
+- Four export surfaces: top-level/`front`, `/server`, `/shared`, `/eval` — decision 15.
+
+## Documentation
+
+**Surfaces & integration**
+
+- [API](./API.md) — the four entry points and what each exports.
+- [STYLING](./STYLING.md) — CSS-variable theming contract and public selectors.
+- [UI-SHADCN](./UI-SHADCN.md) — `ChatPanel` styling model and tool-renderer overrides.
+- [tools](./tools.md) — built-in tools, package-added tools, and how to add custom tools.
+- [PLUGINS](./PLUGINS.md) — the two extension paths and tool-collision rules.
+- [MIGRATION](./MIGRATION.md) — moving legacy integrations to the v2 split.
+
+**Runtime & provisioning**
+
+- [runtime](./runtime.md) — the three modes, the cwd invariant, and `.boring-agent/` layout.
+- [runtime-provisioning](./runtime-provisioning.md) — when provisioning runs, package-authoring shape, trusted server provisioning.
+
+**Contracts & operations**
+
+- [ERROR_CODES](./ERROR_CODES.md) — the stable API error-code registry.
+- [CSP](./CSP.md) — Content-Security-Policy compatibility.
+- [ACCESSIBILITY](./ACCESSIBILITY.md) — a11y coverage and known gaps.
+
+**Risk & cost notes**
+
+- [KNOWN_LIMITATIONS](./KNOWN_LIMITATIONS.md) — accepted risks (orphaned sandboxes, deferred git routes).
+- [RISKS-MULTI-TAB](./RISKS-MULTI-TAB.md) — last-write-wins behavior for concurrent edits.
+- [VERCEL_COSTS](./VERCEL_COSTS.md) — Vercel sandbox cost model.
+- [PERFORMANCE](./PERFORMANCE.md) — historical Vercel cold-start benchmark.
+
+Historical plans and specs live under `docs/plans/archive/` — archival context only, not
+current truth; verify against code before relying on them.

package/docs/RISKS-MULTI-TAB.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-This note documents current `@boring/agent` behavior when two browser tabs
+This note documents current `@hachej/boring-agent` behavior when two browser tabs
 point at the same workspace and edit the same file.
 
 ## Observed Behavior (v1)

package/docs/STYLING.md

@@ -1,6 +1,8 @@
 # STYLING
 
-Styling contract for `@boring/agent` frontend surfaces.
+Styling contract for `@hachej/boring-agent` frontend surfaces. For the full
+agent/workspace Tailwind isolation model, see
+[`docs/TAILWIND-V4-STYLE-ISOLATION.md`](../../../docs/TAILWIND-V4-STYLE-ISOLATION.md).
 
 ## Package CSS
 
@@ -8,12 +10,12 @@ Consumers import the precompiled package stylesheet once, after host/workspace
 base CSS and before app overrides:
 
 ```ts
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
 import "./app.css"
 ```
 
-The published `@boring/agent/front/styles.css` is consumer-safe: it contains no
+The published `@hachej/boring-agent/front/styles.css` is consumer-safe: it contains no
 Tailwind `@source`, no Tailwind imports, and no repo-relative source paths.
 
 ## Public selectors

package/docs/UI-SHADCN.md

@@ -1,14 +1,14 @@
 # Agent UI
 
-`@boring/agent` exports the pane-embeddable `ChatPanel` and its frontend
+`@hachej/boring-agent` exports the pane-embeddable `ChatPanel` and its frontend
 primitives. The default styled surface is packaged with precompiled CSS.
 
 ## Quickstart
 
 ```tsx
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
-import { ChatPanel } from "@boring/agent"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
+import { ChatPanel } from "@hachej/boring-agent"
 
 function App() {
   return <ChatPanel sessionId="my-session" />
@@ -18,8 +18,8 @@ function App() {
 Import app overrides after the package CSS when customizing:
 
 ```ts
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
 import "./app.css"
 ```
 
@@ -27,7 +27,7 @@ import "./app.css"
 
 | Concern | Contract |
 |---|---|
-| Package CSS | `@boring/agent/front/styles.css` |
+| Package CSS | `@hachej/boring-agent/front/styles.css` |
 | Root selector | `[data-boring-agent]` |
 | Parts | `[data-boring-agent-part="composer"]`, `[data-boring-agent-part="tool-card"]`, etc. |
 | Message role | `[data-boring-agent-message-role="assistant"]` |

package/docs/runtime-provisioning.md

@@ -15,11 +15,15 @@ $BORING_AGENT_WORKSPACE_ROOT/.boring-agent/
 ├── skills/          # generated mirror of plugin skills
 ├── node/            # npm prefix for runtime Node CLIs
 ├── venv/            # Python virtualenv for runtime Python CLIs/SDKs
-├── sdk/uv/          # optional workspace-local uv fallback
-├── cache/           # adapter/package cache
-└── fingerprints/    # runtime skip hints
+├── sdk/             # staged local SDK/package sources (sdk/uv = workspace-local uv)
+├── cache/           # npm/uv/pip caches
+└── tmp/             # staged venvs, tarballs, temp files
 ```
 
+Provisioning skip state is tracked via ownership markers and fingerprints stored
+alongside managed directories (see `runtimeLayout.ts`), not a separate
+`fingerprints/` directory.
+
 `.boring-agent` is generated and disposable. Do not hand-edit it; delete it to
 force a full local reprovision. The directory writes its own `.gitignore` and
 should not be committed.

package/docs/runtime.md

@@ -59,17 +59,23 @@ Provisioned runtime artifacts live under the workspace-local `.boring-agent/` di
 
 ```txt
 .boring-agent/
-  bin/       # command shims exposed on PATH: python, pip, app CLIs, ...
-  node/      # npm prefix for provisioned node packages
-  venv/      # Python virtual environment
-  sdk/       # staged local SDK/package sources used for runtime-visible installs
-  state/     # provisioning marker/fingerprint and managed-bin manifests
-  cache/     # npm/pip/uv caches
+  bin/       # managed shims for provisioned CLIs
+  node/      # npm prefix for provisioned node packages (bins at node/node_modules/.bin)
+  venv/      # Python virtualenv (console scripts at venv/bin)
+  sdk/       # staged local SDK/package sources; sdk/uv holds the workspace-local uv
+  skills/    # mirror of plugin skills
+  cache/     # npm/uv/pip caches
   tmp/       # staged venvs, tarballs, temp files
-  logs/      # runtime logs
 ```
 
-The provisioner writes ownership markers for managed runtime directories. Do not hand-edit managed files as an app integration mechanism; declare provisioning contributions instead.
+PATH entries exposed to the harness are `node/node_modules/.bin`, `venv/bin`,
+and `sdk/uv/bin` (see `getBoringAgentPathEntries` in
+`src/server/workspace/runtimeLayout.ts`). `.boring-agent/bin` is a managed shim
+location written by the provisioner; it is not the canonical PATH source
+described by `getBoringAgentPathEntries`. The provisioner writes ownership
+markers (`.boring-agent-owned.json`) for managed runtime directories. Do not
+hand-edit managed files as an app integration mechanism; declare provisioning
+contributions instead.
 
 ## Runtime provisioning
 
@@ -112,7 +118,7 @@ provisioning: {
 }
 ```
 
-The provisioner stages each project under `.boring-agent/sdk/python/<id>`, installs it into `.boring-agent/venv`, and exposes console scripts from `.boring-agent/bin`. File URL env values must point inside the Python project and are converted to runtime-visible SDK paths.
+The provisioner stages each project under `.boring-agent/sdk/python/<id>`, installs it into `.boring-agent/venv`, and may write managed shims under `.boring-agent/bin`. The harness-visible executables still come from the runtime PATH entries above. File URL env values must point inside the Python project and are converted to runtime-visible SDK paths.
 
 Reserved env keys (`BORING_AGENT_WORKSPACE_ROOT`, `VIRTUAL_ENV`, `HOME`, `PYTHONHOME`) cannot be set by plugins.
 
@@ -133,7 +139,7 @@ provisioning: {
 }
 ```
 
-Local packages are packed/installed into `.boring-agent/node`; managed bin shims are written to `.boring-agent/bin`. Multiple node packages are installed together so later packages do not prune earlier ones.
+Local packages are packed/installed into `.boring-agent/node`; managed bin shims may also be written to `.boring-agent/bin`. The harness-visible executables still come from `node/node_modules/.bin`. Multiple node packages are installed together so later packages do not prune earlier ones.
 
 ## vercel-sandbox
 
@@ -162,10 +168,12 @@ Linux only. Wraps tool execution in a `bubblewrap` sandbox. The workspace root i
 
 ```bash
 BORING_AGENT_MODE=local
-BORING_AGENT_WORKSPACE_ROOT=/home/ubuntu/projects/my-app
+BORING_AGENT_WORKSPACE_ROOT=/home/ubuntu/projects/my-app   # host config input
 ```
 
-The host workspace path is adapter-private. Model-facing cwd, file-tree root, and `BORING_AGENT_WORKSPACE_ROOT` should all be `/workspace`.
+The host workspace path is adapter-private. Inside the runtime/model-visible
+namespace, cwd, file-tree root, and `BORING_AGENT_WORKSPACE_ROOT` should all be
+`/workspace`.
 
 ## direct
 
@@ -180,8 +188,55 @@ In direct mode, host paths are expected: `runtimeCwd` is the real `BORING_AGENT_
 
 ## Workspace root
 
+Config input:
+
 ```bash
 BORING_AGENT_WORKSPACE_ROOT=/absolute/path/to/workspace
 ```
 
-When unset, defaults to the current working directory at server start.
+When unset, it defaults to the current working directory at server start.
+In `direct` mode this is also the model-visible workspace root. In isolated
+modes, the adapter maps that host path into the public runtime namespace
+(`/workspace`).
+
+## Adding a custom runtime mode
+
+A mode is a `RuntimeModeAdapter` (defined in `src/server/runtime/mode.ts`).
+There is no registry to edit: pass your adapter as the `runtimeModeAdapter`
+option to `createAgentApp(opts)` or `registerAgentRoutes(app, opts)` — it takes
+precedence over `mode`/auto-detection (`createAgentApp.ts`,
+`registerAgentRoutes.ts`). `resolveMode()` only knows the three built-ins and
+throws for unknown ids, telling you to pass `runtimeModeAdapter`.
+
+```ts
+interface RuntimeModeAdapter {
+  id: string                                  // built-ins: 'direct' | 'local' | 'vercel-sandbox'
+  workspaceFsCapability?: Workspace['fsCapability']
+                                              // describes how much host-side fs access exists before create();
+                                              // remote backends must not claim strong host visibility
+  create(ctx: ModeContext): Promise<RuntimeBundle>
+  createProvisioningAdapter?(runtimeLayout, ctx?): WorkspaceProvisioningAdapter
+  dispose?(): Promise<void>
+}
+
+interface RuntimeBundle {
+  runtimeContext?: WorkspaceRuntimeContext   // e.g. { runtimeCwd: '/workspace' }
+  storageRoot?: string                       // host path for host-fs tools; required unless the
+                                             // workspace itself resolves a host root. NOT the
+                                             // agent-visible cwd — Workspace.root stays the public namespace
+  workspace: Workspace                       // your filesystem adapter
+  sandbox: Sandbox                           // your exec adapter — MUST share the workspace's
+                                             // filesystem substrate (invariant 5: mixed pairings = split-brain)
+  fileSearch: FileSearch                     // createServerFileSearch(workspace, sandbox) usually
+}
+```
+
+Reference implementation to copy: `src/server/runtime/modes/local.ts` (~35
+lines: mkdir + template copy + `createNodeWorkspace` + `createBwrapSandbox`,
+paired on the same root). Tests to extend:
+`src/server/runtime/__tests__/resolveMode.test.ts`.
+
+Rules that must hold: the adapter owns path validation (reject `../`,
+absolute, symlink escapes — see `src/server/workspace/paths.ts`); Workspace +
+Sandbox swap as a pair; consumers receive `Workspace` as a parameter and never
+see raw paths.

package/docs/tools.md

@@ -4,7 +4,10 @@
 
 The agent runtime ships a catalog of tools for interacting with the workspace filesystem and shell.
 
-## Built-in tools
+## Filesystem + shell tools
+
+These are adapted from `@earendil-works/pi-coding-agent` and bound to the
+selected runtime mode (see [runtime.md](./runtime.md)):
 
 | tool | description |
 |---|---|
@@ -15,24 +18,42 @@ The agent runtime ships a catalog of tools for interacting with the workspace fi
 | `find` | Find files by name pattern |
 | `grep` | Search file contents |
 | `ls` | List directory contents |
-| `exec_ui` | Post a command to the workspace UI (open panels, navigate, etc.) |
-| `get_ui_state` | Read what panels are currently open |
 
-## exec_ui
+## Tools added by this package
 
-The primary tool for interacting with the workspace frontend. See [bridge.md](../../workspace/docs/bridge.md) for the full command reference.
+| tool | description |
+|---|---|
+| `execute_isolated_code` | Run code in an isolated sandbox capability |
+| `upload_file` | Upload a workspace file to blob storage |
+| `plugin_diagnostics` | Report loaded plugins and any load errors |
 
-```json
-{
-  "kind": "openSurface",
-  "params": { "kind": "my-plugin.open", "target": "item-123" }
-}
-```
+## UI-bridge tools (workspace-owned)
+
+`exec_ui` and `get_ui_state` are **not** part of the standalone agent. They are
+contributed by `@hachej/boring-workspace` when the agent is mounted via the
+workspace-composed server surfaces (typically `createWorkspaceAgentServer`).
+Standalone `createAgentApp` ships no UI tools. For the UI command reference see
+`packages/workspace/docs/PLUGIN_SYSTEM.md`.
 
 ## Adding custom tools
 
-For statically composed app/server integrations, contribute tools from a
-workspace server plugin:
+Three paths — pick by who owns the tool and how it should update:
+
+| Path | Use when | Lifecycle |
+| --- | --- | --- |
+| `createAgentApp({ extraTools })` | App shell owns the tool, standalone agent | Boot-time |
+| `defineServerPlugin({ agentTools })` | A workspace plugin package contributes it | Boot-time |
+| Pi resources (`package.json#pi`, often in runtime plugins under `.pi/extensions/<name>/`) | Tool/skill/chat behavior should hot-reload with `/reload` | Hot-reloadable |
+
+**App-shell `extraTools`** — the simplest path for a standalone agent: pass
+`extraTools: [myTool]` to `createAgentApp(...)` (or `registerAgentRoutes`).
+Runnable example with a custom renderer:
+[`examples/with-custom-tool`](../examples/with-custom-tool/README.md).
+Collision precedence is built-in → `extraTools` → plugin tools, last wins
+(see [PLUGINS.md](./PLUGINS.md)).
+
+**Workspace server plugin** — for statically composed app/server integrations,
+contribute tools from a workspace server plugin:
 
 ```ts
 import { defineServerPlugin } from "@hachej/boring-workspace/server"
@@ -63,8 +84,10 @@ export default defineServerPlugin({
 Expose that entry with `package.json#boring.server` or pass the plugin object to
 `createWorkspaceAgentServer({ plugins: [...] })`. This is static/boot-time
 server composition; restart the host process after changing routes or tools.
+`execute(params, ctx)` also receives a context (`abortSignal`, `toolCallId`,
+`onUpdate`) — full contract in [PLUGINS.md](./PLUGINS.md#tool-contract).
 
-For hot-reloadable chat behavior in user plugin packages, prefer Pi-native
+**Pi-native resources** — for hot-reloadable chat behavior in user plugin packages, prefer Pi-native
 resources declared in `package.json#pi` (`extensions`, `skills`, `prompts`, and
 `systemPrompt`). Those participate in the `/reload` path and are the right
 place for tools/skills that should update without restarting the workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "type": "module",
   "license": "MIT",
   "description": "Pane-embeddable coding agent. Ships direct/local/vercel-sandbox execution modes behind one interface.",
@@ -74,7 +74,7 @@
     "use-stick-to-bottom": "^1.1.3",
     "yaml": "^2.8.3",
     "zod": "^3.25.76",
-    "@hachej/boring-ui-kit": "0.1.41"
+    "@hachej/boring-ui-kit": "0.1.43"
   },
   "devDependencies": {
     "@antithesishq/bombadil": "0.5.0",