@hachej/boring-agent 0.1.110 → 0.2.0

package/docs/ACCESSIBILITY.md

@@ -1,52 +0,0 @@
-# Accessibility Audit
-
-This document tracks accessibility status for `@hachej/boring-agent` UI surfaces.
-
-## Scope
-
-- `packages/agent/src/front/chat/PiChatPanel.tsx` (the `ChatPanel` export)
-- `packages/agent/src/front/primitives/*` (chat primitives)
-- CI browser check via the `apps/agent-playground` dev frontend
-
-## Current Coverage
-
-### Landmarks and live regions
-
-- The ChatPanel root exposes `role="region"` with
-  `aria-label="Agent assistant"`.
-- Message streams expose `role="log"` and `aria-live="polite"` as
-  `aria-label="Agent conversation"`.
-- Error states are announced with `role="alert"`.
-
-### Interactive control names
-
-- Icon-only conversation controls expose explicit names:
-  - `Scroll to latest message`
-  - `Download conversation`
-
-### Automated checks
-
-- Unit checks:
-  - `src/front/chat/__tests__/PiChatPanel.test.tsx`
-- Browser axe check:
-  - `packages/agent/e2e/a11y.spec.ts`
-  - Fails on any **serious** or **critical** violation inside
-    `[data-boring-agent]`.
-
-This runs in CI automatically through the existing `pnpm e2e` job.
-
-## Known Gaps
-
-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`.
-3. Manual screen-reader validation (VoiceOver/NVDA) is still pending.
-
-## Next Increment
-
-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/AGENT_GATEWAY_V0.md

@@ -1,212 +0,0 @@
-# AgentGateway v0 — the session contract
-
-**Kind:** technical contract. **Governs:** the gateway surface only.
-**Does not govern:** sequencing (see `docs/DIRECTION.md`), architecture rulings
-(see `docs/DECISIONS.md`), or history (see `docs/issues/909/plan.md`).
-
-This file supersedes `docs/issues/909/plan.md` §6 as the binding description of
-the gateway contract. §6 was written before implementation and drifted; it is
-retained there as a historical record, not as a build target.
-
-Source of truth is the code: `packages/agent/src/shared/gateway/types.ts` and
-`errors.ts`. If this file and those files disagree, the code wins and this file
-is a bug. Keep them together — that colocation is the point. The v0 contract
-lived in an issue folder nobody updated, and it silently stopped matching the
-types within one release.
-
-## Scope discipline
-
-`AuthorizedAgentScope` is an **issuer-owned runtime capability, not a transport
-DTO**. It carries a `unique symbol` brand, so it cannot be forged by spreading
-an object across a boundary. It must be re-checked against issuer identity and
-current membership on every use — possession is not authorization.
-
-```ts
-interface AuthorizedAgentScope {
-  readonly workspaceScopeId: WorkspaceScopeId
-  readonly authSubjectId: AuthSubjectId
-  readonly [authorizedAgentScope]: true   // brand
-}
-```
-
-Only the app-owned verifier returns identity facts, as
-`VerifiedAgentScopeClaim`. `AgentSessionRef` deliberately carries **no
-`hostId`** — session refs are `{ agentTypeId, sessionId }` and nothing else.
-
-## The 8 methods (+ close, plus optional authorization hook)
-
-```ts
-interface AgentGateway {
-  authorizeAgentAccess?(input: { scope; agentTypeId; operation }): Promise<void>
-  listAgents(input: ListAgentsInput): Promise<readonly AgentSummary[]>
-  listSessions(input: AuthorizedAgentSessionQuery): Promise<AgentSessionPage>
-  createSession(input: CreateAgentSessionInput): Promise<AgentSessionRef>
-  connectSession(input: ConnectAgentSessionInput): Promise<AgentSessionConnection>
-  readSessionState(input: ReadAgentSessionStateInput): Promise<AgentSessionStateSnapshot>
-  renameSession(input: RenameAgentSessionInput): Promise<AgentSessionSummary>
-  setSessionArchived(input: SetAgentSessionArchivedInput): Promise<AgentSessionSummary>
-  deleteSession(input: DeleteAgentSessionInput): Promise<void>
-  close(): Promise<void>
-}
-```
-
-### Input DTOs — scope is NESTED
-
-**This is the correction.** §6 froze the scope fields as inherited
-(`interface CreateAgentSessionInput extends AuthorizedAgentScope`). The shipped
-contract nests scope under its own field on **every** input:
-
-```ts
-interface ListAgentsInput            { scope }
-interface AuthorizedAgentSessionQuery{ scope; agentTypeId?; cursor?; limit? }
-interface CreateAgentSessionInput    { scope; agentTypeId; requestId; title? }
-interface ConnectAgentSessionInput   { scope; ref; cursor? }
-interface ReadAgentSessionStateInput { scope; ref }
-interface RenameAgentSessionInput    { scope; ref; requestId; title }
-interface SetAgentSessionArchivedInput { scope; ref; requestId; archived }
-interface DeleteAgentSessionInput    { scope; ref; requestId }
-```
-
-Nesting keeps the branded capability a single indivisible value instead of
-scattering its fields across every DTO, which is why callers adopted it. Code
-written against §6's inherited form does not typecheck.
-
-Note `listAgents` takes `ListAgentsInput`, not a bare `AuthorizedAgentScope`.
-
-### Output DTOs
-
-`AgentSummary` (`agentTypeId`, `label`, `description?`, `definition?{version,digest?}`),
-where `version` is the exact package declaration and `digest`, when available,
-is the computed compiled-definition identity (not a re-hash of the response DTO),
-`AgentSessionSummary` (`ref`, `title`, `status`, `createdAt`, `updatedAt`),
-`AgentSessionPage` (`sessions`, `nextCursor?`), and the receipts
-(`CommandReceipt`, `AgentSendReceipt`, `QueueClearReceipt`, `StopReceipt`) are
-unchanged from §6, field for field.
-
-Session activity is the extracted alias `AgentSessionActivity`:
-`'idle' | 'running' | 'aborting' | 'error'`.
-
-`AgentSessionStateSnapshot.state` is **`JsonSafe<PiChatSnapshot>`**, not the raw
-snapshot §6 named — the transport boundary is expressed in the type.
-
-`JsonSafe<T>` itself differs from §6's version: it hoists `unknown extends T` to
-the top, maps functions to `never`, and terminates non-object/non-array at
-`never`. Read it from `types.ts`; do not reimplement it from memory.
-
-### Commands
-
-`AgentPromptCommand` and `AgentFollowUpCommand` both require
-**`{ requestId, clientNonce, content }`** — there is no `text` or `kind:'user'`
-shorthand. Prompts add `displayContent?`, `model?`, `thinkingLevel?`,
-`attachments?`; follow-ups add `clientSeq`.
-
-## Error codes
-
-Seventeen, exhaustive, order-stable, exported as both a const map and
-`AGENT_GATEWAY_ERROR_CODES`:
-
-`AGENT_TYPE_UNKNOWN` · `AGENT_SESSION_NOT_FOUND` · `AGENT_SCOPE_DENIED` ·
-`AGENT_ENTITLEMENT_REQUIRED` · `AGENT_ACCESS_FORBIDDEN` ·
-`AGENT_ACCESS_POLICY_UNAVAILABLE` ·
-`AGENT_SESSION_REPLAY_GAP` · `AGENT_SESSION_CURSOR_AHEAD` ·
-`AGENT_SESSION_CURSOR_EXPIRED` · `AGENT_SESSION_CURSOR_INVALID` ·
-`AGENT_REQUEST_CONFLICT` · `AGENT_REQUEST_IN_PROGRESS` ·
-`AGENT_REQUEST_OUTCOME_UNKNOWN` · `AGENT_RUNTIME_RESTART_REQUIRED` ·
-`AGENT_COMMAND_INVALID_STATE` ·
-`AGENT_SHARED_ENVIRONMENT_UNAVAILABLE` · `AGENT_GATEWAY_CLOSED`
-
-HTTP mapping lives in `server/agent-host/httpProjection.ts`
-(`statusForGatewayError`). Note `AGENT_REQUEST_CONFLICT`, `AGENT_REQUEST_IN_PROGRESS`,
-`AGENT_RUNTIME_RESTART_REQUIRED`, and `AGENT_COMMAND_INVALID_STATE` project to
-**409**.
-
-## Conformance levels
-
-- **Level B** — bounded replay within a process lifetime, plus snapshot
-  rehydrate. This is what ships. A cursor older than the replay window, or one
-  from before a restart, yields `REPLAY_GAP` / `CURSOR_AHEAD` and the client
-  refetches state. Never a silent gap.
-- **Level D** — durable replay across restarts and processes. Specified,
-  deliberately skipped, and owner-annotated in
-  `server/agent-host/testing/gatewayConformance.ts`. Owned by the streaming
-  lane (#1009).
-
-The suite is parameterized by `replayLevel`/`paginationLevel`; a Level D host
-must pass the same file with the flag raised.
-
-## Keyset pagination
-
-Cursors are HMAC-signed and bound to scope and filter; tampering or reuse under
-a different filter yields `AGENT_SESSION_CURSOR_INVALID`. Ordering is total, so
-a session mutated between pages shifts predictably rather than vanishing.
-
-## Known descope
-
-§10 of the 909 plan carries an unchecked acceptance box demanding recursive
-JSON/size/depth validation of attachment and path leaves on the transport
-boundary. §6.4 descoped exactly that to v2, and the conformance suite skips it
-(`v2 remote wire validates JSON event leaves, paths, depth, and size`). The
-plan is internally inconsistent on this point; the descope is what shipped.
-Anything relying on recursive leaf validation must not assume it exists.
-
-## Construction
-
-`createAgentHost()` is the single construction funnel — see
-`server/agent-host/createAgentHost.ts` and Decision 29. It is a
-deployment-static composition helper that returns a gateway and a `close()`; it
-is **not** the AgentHost deployment/publication machinery that Decisions 25–28
-rejected. Future internal/external host tiers belong to #905, not here.
-
-`scripts/check-alignment-invariants.mjs` enforces that nothing outside an
-allowlist calls it.
-
-## Private backend seam
-
-The session-runtime path below `EmbeddedAgentGateway` is the server-only
-`AgentHarnessBackend`. It is private to the `createAgentHost()` construction
-funnel: consumers still inject only `harnessFactory`, and there is no public
-backend factory or second session path.
-
-`AgentPromptPayload` is exposed from the shared chat barrel as a type only. Its
-“server-only” contract means browser schemas never accept the `requireIdle`
-selector.
-
-`PiSessionHarnessBackend` is the sole production implementation today. It
-adapts the unchanged `HarnessPiChatService` and owns the mapping from the
-workspace-scoped backend address and attribution context into the legacy Pi
-request context. The backend carries no credentials, membership authority, or
-model catalog. Reload and slash-command host effects continue to use the
-composition harness directly; they are host capabilities, not session-runtime
-operations.
-
-The Gateway request ledger is the only idempotency authority. A backend method
-may be invoked again after a crash only through a ledger-admitted request; the
-backend itself promises no deduplication. A runtime load failure before the
-effect begins records a retryable state, so the same request key and payload can
-atomically reclaim admission after recovery; completed, rejected, in-flight, and
-outcome-unknown records retain their normal replay behavior. P1-B substitutes the adapter-private
-replay source below `HarnessPiChatService`, not this interface. Later operations
-may extend the interface only in their named slices (`resumePausedToolCall` in
-A3b and `markTurnInterrupted` in A4); neither is part of the current seam.
-
-An explicit retryable admission result, or a returned prompt-state guard denial,
-releases its pending claim before any effect. The ledger persists
-`pending-admission` with `retryable: true`; `prepare` must atomically consume
-that marker before returning `ownership: 'reclaimed'`. The original key and
-payload digest stay binding, and overlapping requests still receive
-`AGENT_REQUEST_IN_PROGRESS`. This applies to both ordinary and strict-idle
-prompt guards, with their existing idle/error admission policies.
-
-Custom `AgentRequestLedger` implementations must implement
-`markAdmissionRetryable` and atomic reclaim, and refuse `acceptAdmission` until
-the released claim has been reclaimed. A thrown admission/guard error does not
-release ownership. Reopening a durable ledger permits only an explicitly marked
-retry; unmarked pending, admission-accepted, in-flight and outcome-unknown rows
-are never automatically re-executed. This is not general crash reconciliation.
-
-CI pins the boundary in three directions: Agent Host production code cannot
-import a Pi runtime, only `harnessBackend/**` can reference the concrete Pi chat
-service, and Workspace/Core/CLI/playground consumers cannot name the private
-backend interface or module path. Retire the legacy `PiChatSessionService` when
-the legacy `core/createAgent` path is removed; it is intentionally not widened
-or migrated here.

package/docs/AGENT_PACKAGES.md

@@ -1,90 +0,0 @@
-# Workspace agent packages
-
-With `BORING_AGENT_FLEET=1`, a single-workspace host may discover an agent
-definition from either the trusted repository's `.agents/personas/` packages
-or a local package path registered in that workspace's
-`.pi/settings.json#packages`. Registration makes an agent package discoverable.
-It does not activate the agent: the class-B `.agents/factory/fleet.yaml` roster
-must also seat the package's `boring.agent.definitionId`.
-
-Agent fleet changes are boot-time changes. `/reload` can refresh ordinary
-plugin resources, but installing, updating, seating, unseating, or removing an
-agent requires restarting the workspace/CLI host.
-
-The CLI workspaces hub has one Agent Host shared by every registered workspace.
-Its global fleet therefore admits only personas from the trusted repository's
-`.agents/personas/`; it does not admit agent definitions from any workspace's
-local package registrations. Local packages keep their ordinary plugin
-surfaces in their owning workspace. Seating workspace-local agent definitions
-in workspaces mode requires a future workspace-scoped fleet boundary.
-
-## Install and seat
-
-From the workspace root, register a local package directory:
-
-```bash
-boring-ui-plugin install --local --workspace . ../agent-packages/my-agent
-```
-
-The package keeps all of its normal plugin surfaces. Its agent contribution is
-still inert until the fleet roster names its definition id:
-
-```yaml
-seats:
-  - seat: my-agent
-    agentTypeId: my-agent-definition
-    skills: []
-```
-
-Restart a single-workspace host with `BORING_AGENT_FLEET=1`. A valid seated
-package appears in the agent catalog with its exact declared
-`boring.agent.version` and computed definition digest. The Host `describe()`
-inventory exposes the same values as `definitionVersion` and
-`definitionDigest`. An installed package without a matching
-seat remains inert and reports `AGENT_DEFINITION_UNSEATED` during fleet
-composition. The shared CLI workspaces hub never admits the local agent
-contribution, even when the global roster names its definition id.
-
-## Update
-
-1. Update the source directory and bump both package/agent versions as needed.
-2. For repository personas under `.agents/personas/`, run
-   `pnpm write:skill-digests` from the repository root.
-3. Restart the workspace/CLI host.
-
-Digest refresh is intentionally repository-local in v1. The script reads only
-`.agents/personas/`; it does not rewrite pins for agent packages installed from
-another local directory. Such packages must already have matching
-seat-authoritative skill pins. A package with a schema, preflight, conflict,
-materialization, or digest mismatch is excluded with its stable diagnostic (for
-example `AGENT_FLEET_SEAT_SKILL_DIGEST_MISMATCH`) while valid sibling seats
-continue to boot. Invalid unseated discovery is likewise excluded because it
-has no activation authority. A missing fleet file means no authored roster and
-boots only the regular default Agent; a present but malformed fleet or policy
-file remains a whole-fleet configuration error.
-
-## Unseat or remove
-
-To make a package inert but keep it installed, remove its seat from
-`.agents/factory/fleet.yaml` and restart.
-
-To remove its workspace registration as well:
-
-```bash
-boring-ui-plugin remove --local --workspace . my-agent-plugin-id
-```
-
-Then restart. Remove the roster seat before removing its registration. If the
-roster still names the removed definition, that Agent is excluded with
-`AGENT_FLEET_SEAT_PERSONA_INVALID` while the default and valid sibling seats
-continue to boot.
-
-## v1 distribution boundary
-
-Repository personas may contribute agents to any fleet in v1. A
-workspace-registered local package path may contribute an agent only to a
-single-workspace host; it never enters the CLI workspaces hub's global fleet.
-Git/npm package sources — including their materialized `.pi/git/` and
-`.pi/npm/` directories — cannot contribute an agent until the
-remote-distribution trust gate ships. All excluded packages' non-agent plugin
-surfaces continue through the normal plugin pipeline unchanged.

package/docs/API.md

@@ -1,123 +0,0 @@
-# API
-
-Browser code imports the top-level (or `/front`) barrel; Node servers import
-`/server`; both share types from `/shared`. The eval toolkit ships under
-`/eval`. Narrow server utilities use dedicated subpaths so they do not widen
-the main server module graph.
-
-## Entry Points
-
-| Import | Environment | Source barrel |
-|---|---|---|
-| `@hachej/boring-agent` | Browser | `src/front/index.ts` (alias of `/front`) |
-| `@hachej/boring-agent/front` | Browser | `src/front/index.ts` |
-| `@hachej/boring-agent/front/styles.css` | Browser | precompiled CSS |
-| `@hachej/boring-agent/server` | Node | `src/server/index.ts` |
-| `@hachej/boring-agent/server/pi-session-readability` | Node | offline production-loader transcript validation |
-| `@hachej/boring-agent/shared` | Any | `src/shared/index.ts` |
-| `@hachej/boring-agent/eval` | Node | `src/eval/index.ts` |
-
-## `@hachej/boring-agent/front`
-
-The styled chat UI and its building blocks. Key exports:
-
-- `ChatPanel` (alias of `PiChatPanel`) — the pane-embeddable chat component.
-  Props include `apiBaseUrl`, `sessionId`, and `toolRenderers`. See
-  `src/front/chat/PiChatPanel.tsx`.
-- `usePiSessions` and session helpers (`readActiveSessionId`,
-  `writeActiveSessionId`, `PiSessionList`, `PiSessionBrowser`).
-- Slash-command surface: `builtinCommands`, `createCommandRegistry`,
-  `parseSlashCommand`, `getAgentCommands`.
-- Tool renderers: `defaultToolRenderers`, `mergeToolRenderers`,
-  `resolveToolRenderer`, `mergeShadcnToolRenderers`, `ToolCallGroup`.
-- Primitives (`Message`, `Conversation`, `Reasoning`, `CodeBlock`,
-  `PromptInput`, …) and the `cn` class helper.
-- `DebugDrawer`, `ChatEmptyState`, `ArtifactOpenProvider`/`useOpenArtifact`,
-  `uploadFile`.
-
-> Note: there is no `useAgentChat` hook. The chat lifecycle lives inside
-> `ChatPanel`/`PiChatPanel` and the `usePiSessions` hook.
-
-## `@hachej/boring-agent/server`
-
-The Node runtime. Key exports:
-
-- `createAgentApp(opts)` — standalone Fastify factory. Zero dependency on
-  `@hachej/boring-core` or `@hachej/boring-workspace`. See
-  `src/server/createAgentApp.ts`.
-- `registerAgentRoutes(app, opts)` — mounts the agent HTTP routes onto an
-  existing Fastify instance (used by `@hachej/boring-workspace`). Paths are
-  absolute under `/api/v1/agent/*`, `/api/v1/files`, etc.
-- Sandbox adapters: `createDirectSandbox`, `createBwrapSandbox`, plus the
-  Vercel sandbox/snapshot helpers (`createVercelSandboxWorkspace`,
-  `bakeSnapshotIfNeeded`, deployment-snapshot providers, `FileHandleStore`).
-- Workspace adapters: `createNodeWorkspace`, `createVercelSandboxWorkspace`.
-- Mode resolution: `autoDetectMode`, `resolveMode`, `hasBwrap`. Custom execution backends are injected via the `runtimeModeAdapter` option — see [runtime.md §Adding a custom runtime mode](./runtime.md#adding-a-custom-runtime-mode).
-- Provisioning: `provisionRuntimeWorkspace`, `provisionWorkspaceRuntime`,
-  `getBoringAgentRuntimePaths`, `getBoringAgentRuntimeEnv`,
-  `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
-
-`registerAgentRoutes` (and standalone `createAgentApp`) can publish a
-`WorkspaceAgentDispatcherResolver` through the explicit
-`onWorkspaceAgentDispatcher` composition callback. This is a trusted,
-in-process host capability—not an HTTP endpoint—and resolves the same
-workspace-scoped `Agent` and runtime binding used by the normal agent routes.
-It does not expose runtime bindings, services, or filesystem paths.
-
-The resolver and bound dispatcher do **no authorization**. A verified host
-caller must authorize membership or service-principal access first, then pass
-the verified `{ workspaceId, userId }`. Resolution fails closed when context is
-missing, conflicts with an already-resolved request workspace, or cannot resolve
-that workspace through the host's explicit `getTrustedWorkspaceRoot` callback.
-Hosts with request-scoped root resolution must provide that separate requestless
-callback for verified background callers; the dispatcher never falls back to a
-raw workspace header.
-
-The bound dispatcher injects its trusted context into `Agent.send()`,
-`interrupt()`, and `stop()`. `send()` keeps normal session creation when no
-`sessionId` is supplied, forwards model selection, and yields the full stream
-through usage and terminal events. Control methods validate the legacy agent's
-interrupt/stop receipts before returning the typed dispatcher contract and fail
-with `AGENT_CONTROL_RECEIPT_INVALID` if the runtime violates it.
-Runtime/generated plugins do not receive this
-capability; app-owned composition may inject it only into trusted integrations.
-
-## `@hachej/boring-agent/shared`
-
-Platform-agnostic contracts (types + zod schemas). Source of truth for the
-public interfaces:
-
-- `harness.ts` — `AgentHarness`, `SendMessageInput`, `RunContext`,
-  `AgentHarnessFactory`.
-- `tool.ts` / `tool-ui.ts` — `AgentTool`, `ToolExecContext`, `ToolResult`,
-  `JSONSchema`, `ToolUiMetadata`.
-- `workspace.ts` — `Workspace`, `Entry`, `Stat`.
-- `sandbox.ts` — `Sandbox`, `SandboxCapability`, `ExecOptions`, `ExecResult`.
-- `catalog.ts` — `CatalogDeps`, `ToolCatalog`.
-- `session.ts` — `SessionStore`, `SessionSummary`, `SessionDetail`.
-- `config-schema.ts` — `ConfigSchema`, `EnvSchema`, `RuntimeModeSchema`,
-  `validateConfig`.
-- `error-codes.ts` — `ErrorCode`, `ERROR_CODES`, error-envelope schemas
-  (see [ERROR_CODES.md](./ERROR_CODES.md)).
-- `chat.ts` — `BoringChatMessage`, `PiChatEvent`, stream/snapshot frames and
-  their zod schemas.
-- `capabilities.ts`, `telemetry.ts`, `runtime.ts`, `sandbox-handle-store.ts`,
-  `validateTool.ts`, `agentPluginEvents.ts`.
-
-> There is no `ui-bridge.ts` or `message.ts` in `shared/`. UI-bridge tools
-> (`exec_ui`, `get_ui_state`) and their types now live in
-> `@hachej/boring-workspace` — `createAgentApp` ships zero UI tools by design.
-
-## Deferred HTTP Git Surface
-
-`/api/v1/git/*` routes exist but are intentionally thin/minimal: there is no
-first-party git UI consumer in the agent today, so git operations run through
-the `bash` tool. See [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md).

package/docs/AUTHORING.md

@@ -1,68 +0,0 @@
-# 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/CSP.md

@@ -1,41 +0,0 @@
-# CSP Compatibility
-
-`@hachej/boring-agent` is compatible with a strict CSP, with one required exception:
-`style-src` must allow inline styles for editor/runtime integrations that do
-not support nonces end-to-end.
-
-## Recommended Policy
-
-```http
-Content-Security-Policy:
-  default-src 'self';
-  script-src 'self';
-  style-src 'self' 'unsafe-inline';
-  connect-src 'self';
-  img-src 'self' data: blob:;
-  font-src 'self';
-```
-
-## Notes
-
-- `script-src` does **not** require `'unsafe-eval'`.
-- No `eval()` or `new Function()` usage is expected in audited agent UI surfaces
-  (`ChatPanel` + example apps).
-- Server helper `applyCspHeaders` lives at `src/server/http/csp.ts` (exported
-  from `@hachej/boring-agent/server`); example servers consume it via
-  `examples/csp.ts`.
-
-## Audited Scope
-
-- `src/front/chat/PiChatPanel.tsx`
-- `examples/with-custom-tool/*`
-- `apps/agent-playground/*`
-
-## Remaining Caveat
-
-Even with this cleanup, downstream consumers that enable rich editor stacks
-(for example CodeMirror/Tiptap integrations in workspace-oriented shells) should
-keep `style-src 'unsafe-inline'` until upstream libraries expose nonce-safe
-style injection across the full stack. The primitive stack
-(`src/front/primitives/*`) also still relies on inline style attributes, so
-`style-src 'unsafe-inline'` remains required there as well.