@hachej/boring-agent 0.1.111 → 0.2.0

package/docs/README.md

@@ -1,98 +0,0 @@
-# @hachej/boring-agent Docs
-
-`@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.
-
-## Architecture
-
-```
-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)
-```
-
-- **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.
-
-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).
-
-## 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.
-- [AUTHORING](./AUTHORING.md) — declarative agent directories, bounds, validation, and legacy catalog migration.
-- [AGENT_PACKAGES](./AGENT_PACKAGES.md) — install, seat, update, unseat, and remove plugin-shaped agent packages in a workspace.
-- [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**
-
-- [SESSION_IDENTITY](./SESSION_IDENTITY.md) — durable session stream key, owner attributes, and v1→v2 migration contract.
-- [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

@@ -1,46 +0,0 @@
-# Multi-Tab Concurrency Risk
-
-## Scope
-
-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)
-
-- There is no workspace-level lock and no per-file lock.
-- `POST /api/v1/files` performs an unconditional write.
-- There is no optimistic concurrency precondition (no ETag/version check,
-  no `If-Match` handling).
-- Result: writes are silent last-write-wins. A stale tab can overwrite a newer
-  edit without a conflict response.
-
-This is visible in route code:
-- [file.ts](../src/server/http/routes/file.ts) calls `workspace.writeFile(...)`
-  directly.
-- [createNodeWorkspace.ts](../../boring-sandbox/src/providers/node-workspace/createNodeWorkspace.ts)
-  calls Node `writeFile(...)` without revision guards.
-
-Behavior is exercised by:
-- [file.test.ts](../src/server/http/routes/__tests__/file.test.ts)
-  `multi-tab stale write overwrites newer content (last write wins)`.
-
-## Session Semantics
-
-- Tabs are not treated as exclusive owners of a workspace.
-- Session identity is driven by `sessionId`; multiple tabs can operate against
-  the same workspace concurrently.
-
-## Known User Impact
-
-- Lost-update risk for simultaneous edits on the same path.
-- No explicit error or merge prompt when overwrite happens.
-
-## Future Mitigation Seam
-
-Introduce optimistic write preconditions:
-
-1. `GET /api/v1/files` returns a version token (for example ETag/content hash +
-   mtime).
-2. `POST /api/v1/files` accepts `If-Match` and rejects mismatched versions with
-   `409 Conflict`.
-3. Frontend handles `409` with refresh/retry UX instead of silent overwrite.

package/docs/SESSION_IDENTITY.md

@@ -1,91 +0,0 @@
-# Session stream identity
-
-This contract governs durable agent event-stream addressing. The code in
-`src/shared/events.ts` is authoritative when this document and the
-implementation disagree.
-
-## Durable key
-
-A session stream is keyed by `(workspaceScopeId, sessionId)`. Its path is:
-
-```text
-sessions/<enc(workspaceScopeId)>/<enc(sessionId)>
-```
-
-`enc` percent-encodes every byte outside `[A-Za-z0-9._-]`, using uppercase
-hex. Both fields are opaque, non-empty, well-formed Unicode strings; session
-ids need not be UUIDs.
-`sessionStreamPath(identity)` is the only constructor and
-`parseSessionStreamPath(path)` accepts only the canonical encoding.
-The value helpers are server-internal and are not exported from the package's
-shared public barrel; only the `SessionStreamIdentity` type is public there.
-
-The process-local Pi cache may still use a JSON tuple, but it is not a durable
-key. Gateway host maps use `(workspaceScopeId, agentTypeId, sessionId)`, and
-Pi transcript directories use their existing agent and workspace namespace.
-Neither grammar may be embedded into a durable stream path.
-
-When no event store is configured, legacy/headless callers may omit
-`workspaceId`. The service preserves their pre-durability JSON cache key and
-never constructs or validates a durable path. Once an event store is present,
-both identity fields are required and invalid identity or durable-read errors
-surface instead of being treated as a missing transcript.
-
-## Owner attributes
-
-`boring_event_stream_owners` stores one row for each addressed session stream:
-
-- `path` is the primary key.
-- `workspace_scope_id` and `session_id` repeat the durable identity and are
-  indexed together.
-- `agent_type_id` is required for newly opened channels but is an attribute,
-  not part of the stream key.
-- `auth_subject_id` is execution attribution, never ownership.
-- `seat_id` and `thread_id` are reserved nullable columns; A1 defines no
-  semantics or foreign keys for them.
-- `key_version` is `2` for streams created with this grammar and `1` for
-  migrated rows.
-
-There is deliberately no foreign key. SQLite foreign-key enforcement is not
-enabled on this connection; migration validation and store transactions enforce
-the relationship instead.
-
-`auth_subject_id` uses first-writer semantics: the first successful
-`createSessionStream` claim records it, and later opens do not replace it.
-This is attribution for the opening execution, not a durable authorization or
-ownership decision.
-
-## Schema v1 to v2
-
-Opening a v1 database runs one `BEGIN IMMEDIATE` migration. It preflights every
-old stream into `boring_event_stream_migration_v2` by parent `rowid`, raw
-`path`, and `typeof(path)`, validates unique targets, every parent's path and
-metadata, per-stream row counts and maximum sequence values, every owner row,
-and every child row before swapping paths across all three event tables.
-
-The collision rules are exhaustive:
-
-1. A single old row rekeys to its v2 path.
-2. For an empty-user row colliding with user-bearing rows, the empty-user row
-   wins and the others are quarantined.
-3. If several user-bearing rows collide without an empty-user row, all are
-   quarantined because their sequence spaces cannot be merged safely.
-4. Non-matching, malformed, or otherwise ambiguous old paths are quarantined.
-
-Legacy identities containing ill-formed Unicode are quarantined with reason
-`unencodable-identity`. Non-TEXT parent paths (including SQL `NULL`) use a
-rowid-safe quarantine destination; their raw original value/type remains in
-the manifest. No encoding failure aborts migration of the remaining rows.
-
-Ordinary quarantine destinations are `quarantine/v1/<enc(oldPath)>`; rowid-safe
-destinations cover values that cannot be encoded. Rows are never dropped. The
-swap is validated again before `schema_version` becomes `2`.
-Concurrent openers serialize on the immediate transaction, re-read the version
-under the lock, and only one migrates. A migrated owner has
-`agent_type_id = NULL` until the next legitimate channel open backfills it from
-the composition's explicit agent type.
-
-The migration is a rollback fence, not a reversible downgrade. Disable
-`BORING_CHAT_DURABLE_STREAM` before running an old binary; an old binary pointed
-at a v2 file refuses it with `EventStreamSchemaVersionError` rather than writing
-mixed path grammars.

package/docs/STYLING.md

@@ -1,73 +0,0 @@
-# STYLING
-
-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
-
-Consumers import the precompiled package stylesheet once, after host/workspace
-base CSS and before app overrides:
-
-```ts
-import "@hachej/boring-workspace/globals.css"
-import "@hachej/boring-agent/front/styles.css"
-import "./app.css"
-```
-
-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
-
-Agent surfaces expose a package namespace root and stable part attributes:
-
-```css
-[data-boring-agent] {}
-[data-boring-agent-part="chat"] {}
-[data-boring-agent-part="composer"] {}
-[data-boring-agent-part="tool-card"] {}
-[data-boring-agent-message-role="assistant"] {}
-[data-boring-state="selected"] {}
-```
-
-`data-boring-agent-*` is the public selector namespace for agent UI. Workspace
-uses `data-boring-workspace-*`; do not style agent internals through workspace
-selectors.
-
-## Token contract
-
-Workspace owns the public visual tokens (`--boring-*`). Agent consumes those
-host tokens and provides standalone fallbacks under `[data-boring-agent]`.
-
-Common tokens:
-
-- `--boring-background`
-- `--boring-foreground`
-- `--boring-card`
-- `--boring-muted`
-- `--boring-muted-foreground`
-- `--boring-accent`
-- `--boring-border`
-- `--boring-radius`
-- `--boring-font-sans`
-- `--boring-font-mono`
-
-Example app override:
-
-```css
-[data-boring-agent-part="composer"] {
-  --boring-accent: oklch(0.64 0.18 250);
-}
-
-[data-boring-agent-message-role="assistant"] {
-  --boring-card: oklch(0.98 0.01 250);
-}
-```
-
-## Invariants
-
-- Keep reusable primitives driven by semantic CSS variables and public data
-  attributes, not package-internal DOM structure.
-- Keep styling decisions out of `src/shared/**` and server runtime modules.
-- Published package CSS must remain precompiled and consumer-safe.

package/docs/UI-SHADCN.md

@@ -1,56 +0,0 @@
-# Agent UI
-
-`@hachej/boring-agent` exports the pane-embeddable `ChatPanel` and its frontend
-primitives. The default styled surface is packaged with precompiled CSS.
-
-## Quickstart
-
-```tsx
-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" />
-}
-```
-
-Import app overrides after the package CSS when customizing:
-
-```ts
-import "@hachej/boring-workspace/globals.css"
-import "@hachej/boring-agent/front/styles.css"
-import "./app.css"
-```
-
-## Styling model
-
-| Concern | Contract |
-|---|---|
-| 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"]` |
-| State | `[data-boring-state="selected"]`, `[data-boring-state="disabled"]`, etc. |
-| Tokens | Consumes host `--boring-*` tokens with standalone fallbacks |
-
-The built stylesheet has no Tailwind `@source` directives, no Tailwind imports,
-and no repo-relative source paths.
-
-## Dark mode
-
-Add `class="dark"` to an ancestor. Workspace owns the dark `--boring-*` token
-values; agent inherits them and falls back when embedded standalone.
-
-## Custom tool renderers
-
-Same API as `ChatPanel`:
-
-```tsx
-<ChatPanel
-  sessionId="sess"
-  toolRenderers={{
-    write: ({ toolCall }) => <div>Wrote {toolCall.input.path}</div>,
-  }}
-/>
-```

package/docs/VERCEL_COSTS.md

@@ -1,103 +0,0 @@
-# Vercel Sandbox Cost Model
-
-Date: 2026-04-23
-
-## Inputs
-
-### Pricing + limits (official)
-
-Source: Vercel Sandbox pricing and limits (last updated March 14, 2026):
-<https://vercel.com/docs/vercel-sandbox/pricing>
-
-| Metric | Rate / Limit |
-|---|---|
-| Active CPU | `$0.128 / vCPU-hour` |
-| Provisioned Memory | `$0.0212 / GB-hour` |
-| Sandbox creations | `$0.60 / 1M` (`$0.0000006 / create`) |
-| Data transfer | `$0.15 / GB` |
-| Snapshot storage | `$0.08 / GB-month` |
-| Default vCPU | `2` |
-| Memory per vCPU | `2 GB` |
-| Max runtime | Hobby `45 min`, Pro/Enterprise `5h` |
-| vCPU allocation rate limit | Hobby `40 vCPU / 10 min`, Pro `200 / min`, Ent `400 / min` |
-
-Snapshot defaults (official):
-- <https://vercel.com/docs/vercel-sandbox/concepts/snapshots>
-- Default snapshot expiration is `30 days` unless configured otherwise.
-
-### Measured workload inputs (this repo)
-
-- Cold-start benchmark (`96h`): [PERFORMANCE.md](./PERFORMANCE.md)
-- FS + exec latency benchmark (`f4f`): historical raw JSON artifact removed; see the root `docs/PERFORMANCE.md` rollup.
-- Measured snapshot sizes from benchmark project: ~`279 MB` each (`0.2606 GB`).
-
-Observations:
-- 96h: cold-start p95 is below `3s`, so we do not need a large warm pool to hide startup.
-- f4f + 96h traces are I/O-heavy; CPU-active share is much lower than wall-clock. Model uses `30%` CPU-active as the baseline.
-
-## Model
-
-For one workspace/day:
-
-```text
-daily_cost =
-  (active_cpu_vcpu_hours * 0.128) +
-  (memory_gb * wall_clock_hours * 0.0212) +
-  (creates_per_day * 0.0000006) +
-  (snapshot_gb * snapshots_kept * 0.08 / 30)
-```
-
-Baseline assumptions used below:
-- `2 vCPU`, `4 GB` memory.
-- one active user session/day: `30 min` wall-clock, `30%` CPU-active.
-- this gives `active_cpu_vcpu_hours = 2 * 0.5 * 0.3 = 0.3` vCPU-hours/day.
-- `1` creation/day.
-- snapshot retention `keep-last-2`.
-- idle policy changes runtime billed for memory, but not active CPU time.
-
-## Cost per Workspace per Day
-
-Historical companion CSV artifacts were removed from the package tree; the table below preserves the cost model.
-
-| Idle policy | Runtime billed/day | CPU $/day | Memory $/day | Snapshot $/day | Create $/day | Total $/day |
-|---|---:|---:|---:|---:|---:|---:|
-| Stop on session end | 0.5 h | 0.0384 | 0.0424 | 0.0014 | 0.0000006 | **0.0822** |
-| Idle-stop after 60 min | 1.0 h | 0.0384 | 0.0848 | 0.0014 | 0.0000006 | **0.1246** |
-| No explicit stop (5h timeout) | 5.0 h | 0.0384 | 0.4240 | 0.0014 | 0.0000006 | **0.4638** |
-| Pinned 24h workspace | 24.0 h | 0.0384 | 2.0352 | 0.0014 | 0.0000006 | **2.0750** |
-
-Implication:
-- Memory wall-clock billing dominates cost. Idle lifetime policy matters far more than creation count.
-
-## Snapshot Retention Trade-off
-
-With measured snapshot size `0.2606 GB`:
-
-| Retention | Storage/workspace/month |
-|---|---:|
-| Keep 1 | `$0.0209` |
-| Keep 2 (current) | `$0.0417` |
-| Keep 5 | `$0.1043` |
-| Keep 10 | `$0.2085` |
-
-Conclusion:
-- **Keep-last-2 is still the right default.**
-- Storage cost is tiny at small scale but scales linearly with workspace count.
-
-## Idle Pool Sizing
-
-If we keep a warm 2 vCPU / 4 GB sandbox running for 24h, per slot:
-- Memory-only floor: `4 GB * 24h * 0.0212 = $2.0352/day`.
-- At 1% CPU-active overhead, total is about `~$2.10/day` per warm slot.
-
-Because 96h cold-start p95 is already `<3s`, default should be **no prewarmed idle pool**.
-
-## Policy Recommendation
-
-1. Keep `BORING_AGENT_SNAPSHOT_KEEP=2` (confirmed).
-2. Stop sandbox proactively on session end; do not rely on timeout.
-3. Add/keep idle-stop guardrail at `<= 60 min` idle.
-4. Add stale-handle cleanup: force destroy after `24h` idle as a safety backstop if stop hooks are missed.
-5. Keep idle pool size at `0` by default; only enable a tiny pool behind feature flag if product latency goals tighten.
-
-This policy minimizes spend while keeping current UX targets achievable.