@hachej/boring-agent 0.1.40 → 0.1.42

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.40",
+  "version": "0.1.42",
   "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.40"
+    "@hachej/boring-ui-kit": "0.1.42"
   },
   "devDependencies": {
     "@antithesishq/bombadil": "0.5.0",