@hachej/boring-agent 0.1.89 → 0.1.91

package/docs/ACCESSIBILITY.md

@@ -37,9 +37,8 @@ This runs in CI automatically through the existing `pnpm e2e` job.
 
 ## Known Gaps
 
-1. Storybook a11y pipeline is not present yet.
-   There is no `.storybook` config, no `@storybook/addon-a11y`, and no
-   story-level axe scan.
+1. A registered agent-component UI-review spec is not present yet, so there is
+   no fixture-level axe scan for agent primitives.
 2. Current automated axe gate targets the shipped chat surface only.
    Workspace pane-level a11y checks (file tree, editor panes, dock tabs) are
    outside this package and need dedicated coverage in `@hachej/boring-workspace`.
@@ -47,7 +46,7 @@ This runs in CI automatically through the existing `pnpm e2e` job.
 
 ## Next Increment
 
-1. Stand up Storybook for `@hachej/boring-agent` primitives.
-2. Enable addon-a11y and add story-level CI checks.
+1. Register deterministic agent-primitive checkpoints in `tools/ui-review`.
+2. Add fixture-level axe hard gates to that registered spec.
 3. Extend browser axe checks to `workspace-playground` once pane a11y owners
    land stable selectors/landmarks.

package/docs/API.md

@@ -58,6 +58,9 @@ The Node runtime. Key exports:
   `createVercelProvisioningAdapter`.
 - HTTP/CSP: `applyCspHeaders`; `fileRoutes` for mounting file routes alone.
 - Harness: `createResourceSettingsManager` and the Pi harness option types.
+- Declarative authoring: `compileAgentDirectory()` and
+  `materializeAgentDirectory()`; see [AUTHORING](./AUTHORING.md). The materialized
+  value contains no tools, plugin selectors, paths, or runtime handles.
 - `createLogger`.
 
 ### Trusted workspace agent dispatch

package/docs/AUTHORING.md

@@ -0,0 +1,68 @@
+# Declarative agent authoring
+
+An authored agent directory describes identity, safe display metadata, and
+instructions. It does not select executable behavior.
+
+```text
+my-agent/
+├── agent.json
+└── instructions.md
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "definitionId": "claims-assistant",
+  "version": "2026.07.20",
+  "label": "Claims assistant",
+  "description": "Helps process insurance claims.",
+  "instructionsRef": "instructions.md"
+}
+```
+
+`label` and `description` are optional. Labels are limited to 128 characters;
+descriptions are limited to 1,024 characters. Both must be trimmed, valid
+Unicode without control or bidi-spoofing characters.
+
+The loader:
+
+- reads only `agent.json` and `instructions.md`;
+- requires regular, non-symlink files contained in the directory;
+- limits the manifest to 64 KiB and instructions to 256 KiB before decoding;
+- requires valid UTF-8 and non-whitespace instructions;
+- returns a frozen `AuthoredAgentSourceV1` from
+  `materializeAgentDirectory()` containing only identity, metadata, and
+  instructions.
+
+## Executable behavior belongs to trusted host policy
+
+Tools, capabilities, skills, MCP servers, packages, models, credentials,
+plugins, runtime modes, and Workspace roots are configured by trusted host and
+plugin code. Authored JSON cannot enable them.
+
+Legacy manifests may still contain these keys while being cleaned up:
+
+- `capabilityRequirements`
+- `toolRefs`
+- `skillRefs`
+- `mcpServerRefs`
+
+Absent or empty arrays are accepted and stripped. A non-empty array fails with
+`AUTHORED_AGENT_REFERENCE_UNSUPPORTED`; move the requested behavior to trusted
+host/plugin configuration.
+
+The removed server contracts are `AuthoredAgentToolCatalog`,
+`MaterializeAgentDirectoryInput.toolCatalog`, and the materialized `tools` and
+`declaredToolRefs` fields. This correction removes no HTTP or product endpoint.
+
+## Validation
+
+```bash
+boring-ui agent validate ./my-agent
+boring-ui agent validate ./my-agent --json
+```
+
+Success reports only identity, optional metadata, and instruction byte length.
+It never reports or resolves a tool catalog. Errors are field-specific and
+redacted; unexpected failures return `INTERNAL_ERROR` without local paths or
+secret-like source values.

package/docs/ERROR_CODES.md

@@ -39,6 +39,9 @@ All API failures must use the response envelope:
 | `AGENT_RUNTIME_NOT_READY` | Selected workspace runtime dependencies (`runtime-dependencies` or `runtime:<name>`, e.g. `runtime:python`/`runtime:node`) are still preparing | 503 | retry | warn | stable (public API) |
 | `AGENT_BINDING_DISPOSED` | A caller retained an agent binding after its host retired it | 410 | resolve a fresh binding | warn | stable (trusted API) |
 | `AGENT_CONTROL_RECEIPT_INVALID` | The existing agent runtime returned a malformed interrupt/stop receipt through the trusted dispatcher | 500 | report-bug | error | stable (trusted API) |
+| `AGENT_FLEET_PLUGIN_UNKNOWN` | Agent fleet configuration references a plugin that the app did not load | 500 | fix app configuration | error | stable (trusted API) |
+| `AGENT_FLEET_CONFIG_BINDING_UNKNOWN` | Agent fleet configuration passes a plugin config key outside its declared Agent config contract | 500 | fix app configuration | error | stable (trusted API) |
+| `AGENT_FLEET_MODEL_POLICY_UNCOMPILED` | Agent fleet configuration declares a model policy that the app fleet compiler did not resolve | 500 | configure app fleet compiler | error | stable (trusted API) |
 | `RUNTIME_PROVISIONING_FAILED` | Agent runtime dependency provisioning failed before Level 3 runtime dependencies became ready | 503 | retry/report | error | stable (public API) |
 | `RUNTIME_PROVISIONING_LOCKED` | Agent runtime provisioning is locked by another reconciler | 423 | retry | warn | stable (public API) |
 | `BWRAP_UNAVAILABLE` | `bwrap` binary not found | 500 | report-bug | error | stable (public API) |
@@ -47,6 +50,28 @@ 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_CONFIG_INVALID` | Static remote-worker fleet configuration is invalid or incomplete | 500 | report-bug | error | stable (trusted API) |
+| `REMOTE_WORKER_PROTOCOL_MISMATCH` | Worker protocol or provider-contract version differs from the configured V1 cohort | 502 | operator-fix | error | stable (trusted API) |
+| `REMOTE_WORKER_UNAUTHENTICATED` | Worker rejected the per-box capability or authenticated receipt | 401 | operator-fix | warn | stable (trusted API) |
+| `REMOTE_WORKER_UNAVAILABLE` | The statically owning worker cannot serve the request; no fallback is attempted | 503 | retry | warn | stable (public API) |
+| `REMOTE_WORKER_UNQUALIFIED` | Worker qualification or artifact facts do not match static placement config | 503 | operator-fix | error | stable (trusted API) |
+| `REMOTE_WORKER_REQUEST_INVALID` | A strict remote-worker request schema rejected the request | 400 | report-bug | warn | stable (trusted API) |
+| `REMOTE_WORKER_RESPONSE_INVALID` | A strict remote-worker response schema rejected the worker response | 502 | operator-fix | error | stable (trusted API) |
+| `REMOTE_WORKER_CAPABILITY_EXPIRED` | A short-lived worker capability expired or exceeded its maximum lifetime | 401 | retry | warn | stable (trusted API) |
+| `REMOTE_WORKER_AUTHORIZED_WORKSPACE_REQUIRED` | Remote provider creation lacked an authenticated workspace identity | 403 | report-bug | warn | stable (trusted API) |
+| `REMOTE_WORKER_BINDING_RECEIPT_INVALID` | Create returned an unauthenticated or mismatched sandbox/workspace binding receipt | 502 | operator-fix | error | stable (trusted API) |
+| `REMOTE_WORKER_SANDBOX_WORKSPACE_MISMATCH` | Authorized workspace capability does not match the immutable sandbox lease binding | 404 | report-security | warn | stable (trusted API) |
+| `REMOTE_WORKER_SANDBOX_NOT_FOUND` | Addressed remote sandbox lease does not exist | 404 | reacquire | warn | stable (trusted API) |
+| `REMOTE_WORKER_SANDBOX_EXPIRED` | Addressed remote sandbox lease has expired | 410 | reacquire | warn | stable (trusted API) |
+| `REMOTE_WORKER_SANDBOX_DISPOSED` | Addressed remote sandbox lease was already disposed | 410 | reacquire | warn | stable (trusted API) |
+| `REMOTE_WORKER_CREATE_CONCURRENCY_EXHAUSTED` | Worker create concurrency is exhausted | 429 | retry | warn | stable (trusted API) |
+| `REMOTE_WORKER_EXEC_CONCURRENCY_EXHAUSTED` | Worker execution concurrency is exhausted | 429 | retry | warn | stable (trusted API) |
+| `REMOTE_WORKER_IDEMPOTENCY_CONFLICT` | Reused lease/invocation id has a different request digest | 409 | report-bug | warn | stable (trusted API) |
+| `REMOTE_WORKER_EXEC_IN_PROGRESS` | Duplicate invocation is still executing | 409 | retry | warn | stable (trusted API) |
+| `REMOTE_WORKER_SECRET_INVOCATION_NOT_REPLAYABLE` | Completed secret-bearing invocation cannot replay cached output | 409 | start-new-request | warn | stable (trusted API) |
+| `REMOTE_WORKER_OUTCOME_UNKNOWN` | Worker loss left an effectful invocation outcome unknown; no automatic replay is safe | 502 | inspect-before-retry | error | stable (public API) |
+| `REMOTE_WORKER_INCOMPLETE_CLEANUP` | Provider could not prove remote lease teardown after bounded retries | 502 | operator-fix | error | stable (trusted API) |
+| `REMOTE_WORKER_DOCKER_COMMAND_FAILED` | Worker runtime command failed without exposing infrastructure stderr | 502 | operator-fix | error | stable (trusted 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) |
@@ -62,6 +87,10 @@ All API failures must use the response envelope:
 | `TOOL_NOT_FOUND` | Requested tool name not present in catalog | 404 | user-fix | warn | stable (public API) |
 | `TOOL_INVALID_INPUT` | Tool input fails schema validation | 400 | user-fix | warn | stable (public API) |
 | `TOOL_EXECUTION_ERROR` | Tool threw or returned execution failure | 500 | report-bug | error | stable (public API) |
+| `AUTHORED_AGENT_ID_INVALID` | Authored agent materialization received an agent type id outside the product-safe grammar | 400 | user-fix | warn | stable (trusted API) |
+| `AUTHORED_AGENT_TYPE_MISMATCH` | Trusted host expected one authored agent type but the directory declares another | 409 | user-fix | warn | stable (trusted API) |
+| `AUTHORED_AGENT_REFERENCE_UNSUPPORTED` | Authored source contains a non-empty legacy capability/tool/skill/MCP selector; move behavior to trusted host plugins | 400 | user-fix | warn | stable migration error |
+| `AUTHORED_AGENT_TOOL_COLLISION` | Normal trusted tool composition produced duplicate or colliding tool names | 409 | user-fix | warn | stable (trusted API) |
 | `MCP_AGENT_ARTIFACT_INVALID` | Managed MCP delivery artifact is path-shaped, non-Markdown, binary, malformed UTF-8, or otherwise invalid | 400 | user-fix | warn | stable (public API) |
 | `MCP_AGENT_ARTIFACT_TOO_LARGE` | Managed MCP final text, inline Markdown artifact, or serialized result exceeds the delivery v0 byte cap | 413 | user-fix | warn | stable (public API) |
 | `MCP_AGENT_ARTIFACT_UNAVAILABLE` | Managed MCP artifact is missing, unreadable through the authorized workspace, or changed during read | 409 | retry | warn | stable (public API) |

package/docs/README.md

@@ -67,6 +67,7 @@ the agent ↔ workspace boundary is in
 **Surfaces & integration**
 
 - [API](./API.md) — the four entry points and what each exports.
+- [AUTHORING](./AUTHORING.md) — declarative agent directories, bounds, validation, and legacy catalog migration.
 - [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.

package/docs/RISKS-MULTI-TAB.md

@@ -17,7 +17,7 @@ point at the same workspace and edit the same file.
 This is visible in route code:
 - [file.ts](../src/server/http/routes/file.ts) calls `workspace.writeFile(...)`
   directly.
-- [createNodeWorkspace.ts](../src/server/workspace/createNodeWorkspace.ts)
+- [createNodeWorkspace.ts](../../boring-sandbox/src/providers/node-workspace/createNodeWorkspace.ts)
   calls Node `writeFile(...)` without revision guards.
 
 Behavior is exercised by:

package/docs/runtime-provisioning.md

@@ -152,6 +152,6 @@ Useful smoke/unit checks:
 pnpm --filter @hachej/boring-ui-cli exec vitest run src/__tests__/runtimeProvisioning.test.ts
 pnpm --filter @hachej/boring-workspace exec vitest run src/app/server/__tests__/macroRuntimeProvisioning.test.ts
 pnpm --filter @hachej/boring-workspace exec vitest run src/server/__tests__/createWorkspaceAgentServer.test.ts --testNamePattern "runtime provisioning reload"
-pnpm --filter @hachej/boring-agent exec vitest run src/server/sandbox/vercel-sandbox/__tests__/provisioningAdapter.test.ts
+pnpm --filter @hachej/boring-sandbox exec vitest run src/providers/vercel-sandbox/__tests__/provisioningAdapter.test.ts
 pnpm --filter @hachej/boring-agent exec vitest run src/server/workspace/provisioning/__tests__
 ```

package/docs/runtime.md

@@ -73,7 +73,7 @@ Provisioned runtime artifacts live under the workspace-local `.boring-agent/` di
 
 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
+`@hachej/boring-sandbox/providers/node-workspace`). `.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
@@ -248,8 +248,8 @@ interface RuntimeModeAdapter {
   workspaceFsCapability?: Workspace['fsCapability']
                                               // describes how much host-side fs access exists before create();
                                               // remote backends must not claim strong host visibility
+  runtimeHost?: AgentRuntimeHostOperations     // host-owned workspace/path/bwrap operations
   create(ctx: ModeContext): Promise<RuntimeBundle>
-  createProvisioningAdapter?(runtimeLayout, ctx?): WorkspaceProvisioningAdapter
   dispose?(): Promise<void>
 }
 
@@ -262,15 +262,18 @@ interface RuntimeBundle {
   sandbox: Sandbox                           // your exec adapter — MUST share the workspace's
                                              // filesystem substrate (invariant 5: mixed pairings = split-brain)
   fileSearch: FileSearch                     // createServerFileSearch(workspace, sandbox) usually
+  provisioningAdapter?: WorkspaceProvisioningAdapter
+                                             // provisioning bound to this acquired pair
+  disposeRuntime?: () => Promise<void>       // releases this acquired pair exactly once
 }
 ```
 
-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:
+Reference composition to copy: `packages/workspace/src/app/server/sandboxRuntimeHost.ts`,
+which creates package-owned providers and injects host operations into the
+generic Agent mode factories. 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 +
+absolute, symlink escapes — see `@hachej/boring-sandbox/providers/node-workspace`); Workspace +
 Sandbox swap as a pair; consumers receive `Workspace` as a parameter and never
 see raw paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.1.89",
+  "version": "0.1.91",
   "type": "module",
   "license": "MIT",
   "description": "Pane-embeddable coding agent. Ships direct/local/vercel-sandbox execution modes behind one interface.",
@@ -32,6 +32,11 @@
       "import": "./dist/server/pi-session-readability.js",
       "default": "./dist/server/pi-session-readability.js"
     },
+    "./server/agent-host/testing/gatewayConformance": {
+      "types": "./dist/server/agent-host/testing/gatewayConformance.d.ts",
+      "import": "./dist/server/agent-host/testing/gatewayConformance.js",
+      "default": "./dist/server/agent-host/testing/gatewayConformance.js"
+    },
     "./server/worker": {
       "types": "./dist/server/worker/index.d.ts",
       "import": "./dist/server/worker/index.js",
@@ -71,10 +76,7 @@
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
     "@tanstack/react-query": "^5.101.1",
-    "@vercel/blob": "^2.5.0",
-    "@vercel/sandbox": "2.3.0",
     "ai": "^7.0.9",
-    "chokidar": "^5.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -89,9 +91,12 @@
     "use-stick-to-bottom": "^1.1.6",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "@hachej/boring-ui-kit": "0.1.89"
+    "@hachej/boring-sandbox": "0.1.91",
+    "@hachej/boring-ui-kit": "0.1.91",
+    "@hachej/boring-bash": "0.1.91"
   },
   "devDependencies": {
+    "@vercel/sandbox": "2.3.0",
     "@antithesishq/bombadil": "0.6.1",
     "@opentelemetry/api": "^1.9.1",
     "@tailwindcss/postcss": "^4.3.1",
@@ -100,12 +105,12 @@
     "@types/react-dom": "^19.1.3",
     "@vitejs/plugin-react": "^4.7.0",
     "ajv": "^8.20.0",
-    "esbuild": "^0.25.12",
-    "postcss": "^8.5.15",
+    "esbuild": "^0.28.1",
+    "postcss": "^8.5.19",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "tsup": "^8.4.0",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vite": "^8.1.2",
     "vitest": "^4.1.9"
@@ -113,7 +118,8 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "tailwindcss": ">=3.4.0 || >=4.0.0"
+    "tailwindcss": ">=3.4.0 || >=4.0.0",
+    "vitest": "^4.1.9"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -124,6 +130,9 @@
     },
     "tailwindcss": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "scripts": {

package/dist/chunk-DGRKMMXO.js

@@ -1,8 +0,0 @@
-// src/shared/agentPluginEvents.ts
-var WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT = "boring-ui:agent-plugins-reloaded";
-var WORKSPACE_COMMAND_NOTIFY_EVENT = "boring-ui:command-notify";
-
-export {
-  WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT,
-  WORKSPACE_COMMAND_NOTIFY_EVENT
-};