brass-runtime 1.16.0 → 1.17.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,292 @@
+# 🧱 ARCHITECTURE — brass-runtime
+
+This document explains the **architectural structure** of `brass-runtime`, how the layers relate to each other, and the design principles behind them.
+
+The architecture is intentionally inspired by **ZIO 2**, but implemented from scratch in **TypeScript**, without relying on `Promise` as the semantic runtime primitive.
+
+---
+
+## High-level overview
+
+```
+┌────────────────────────────────────────────┐
+│              User Programs                 │
+│  (examples, apps, libraries, tests)        │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│           High-level Modules                │
+│   (HTTP, Streams, Resources, etc.)          │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│        Core Effect Runtime                  │
+│  Async / Effect / Fiber / Scope / Scheduler │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│      JavaScript Host Environment            │
+│   (event loop, timers, fetch, callbacks)   │
+└────────────────────────────────────────────┘
+```
+
+Key idea:
+> **Only the core runtime knows about execution.**  
+> Everything else is *pure descriptions* interpreted by the runtime.
+
+---
+
+## Core principles
+
+### 1. No Promise-based semantics
+- `Promise` is never the semantic primitive.
+- Async work is represented explicitly as data (`Async`).
+- The runtime *interprets* async effects using callbacks and schedulers.
+
+This ensures:
+- Deterministic scheduling
+- Cooperative cancellation
+- Structured concurrency
+- Testability
+
+---
+
+### 2. Lazy by default
+All effects are **lazy**:
+- Nothing runs until interpreted by a `Fiber`
+- Creating an effect is pure and side-effect free
+
+```ts
+const eff = http.getJson<Post>("/posts/1")
+// nothing has happened yet
+```
+
+Execution only begins when:
+- Forked into a fiber
+- Or awaited via `toPromise` (interop helper)
+
+---
+
+### 3. Structured concurrency
+Fibers always belong to a **Scope**.
+
+Rules:
+- Child fibers cannot outlive their parent scope
+- Closing a scope interrupts all children
+- Finalizers run in LIFO order
+
+This prevents:
+- Leaked async tasks
+- Forgotten cleanups
+- Detached background work
+
+---
+
+## Core Runtime Layer
+
+### Main components
+
+```
+Async
+  │
+  ▼
+Fiber ── Scheduler
+  │
+  ▼
+Scope ── Finalizers
+```
+
+#### `Async<R, E, A>`
+- Algebraic data type representing effectful computation
+- Variants: `Succeed | Fail | Sync | Async | FlatMap`
+- Pure data, no execution
+
+#### `Fiber<E, A>`
+- Interpreter of `Async`
+- Owns:
+  - Stack
+  - RunState
+  - Interrupt status
+  - Finalizers
+- Can be:
+  - Joined
+  - Interrupted
+  - Forked
+
+#### `Scheduler`
+- Cooperative task queue
+- Ensures fairness
+- No preemption
+- Explicit scheduling boundaries
+
+#### `Scope`
+- Lifetime manager
+- Owns:
+  - Child fibers
+  - Sub-scopes
+  - Finalizers
+- Deterministic cleanup
+
+---
+
+## Streams Architecture
+
+Streams are **pull-based**, inspired by ZIO Streams.
+
+```
+ZStream
+   │
+   ▼
+ Pull<R, Option<E>, A>
+```
+
+### Characteristics
+- Backpressure-aware
+- Resource-safe
+- Scope-bound
+- Deterministic cleanup
+
+### Why pull-based?
+- Simpler cancellation semantics
+- Natural backpressure
+- Easier reasoning about lifetimes
+
+---
+
+## HTTP Module Architecture (brass-http)
+
+HTTP is **not part of the core runtime**.
+
+It is implemented as a **high-level module** built entirely on `Async`.
+
+```
+HttpRequest
+     │
+     ▼
+HttpClient (Request => Async)
+     │
+     ▼
+ Middlewares
+ (withMeta, logging, retries)
+     │
+     ▼
+ Content helpers
+ (getJson, getText)
+```
+
+### Important properties
+- Fully lazy
+- Cancelable via fiber interruption
+- Composable via middleware functions
+- Environment-aware (baseUrl, headers, auth)
+
+HTTP execution only happens when:
+- The returned `Async` is run by a fiber
+
+---
+
+## Middleware model
+
+Middlewares are pure functions:
+
+```ts
+type Middleware = (client: HttpClient) => HttpClient
+```
+
+They:
+- Do not execute effects
+- Only transform descriptions
+- Compose left-to-right
+
+Examples:
+- `withMeta`
+- logging
+- retries
+- tracing
+- auth injection
+
+---
+
+## Interop Layer
+
+### `toPromise`
+- Thin boundary for examples and DX
+- Not part of core semantics
+- Converts fiber execution into a `Promise`
+
+### `fromPromiseAbortable`
+- Adapts Promise APIs that support `AbortSignal`
+- Preserves cooperative cancellation
+- Integrates cleanly with fibers
+
+Interop is **explicit and contained**.
+
+---
+
+## What is NOT allowed
+
+By design:
+- ❌ Hidden Promises inside effects
+- ❌ Detached async work
+- ❌ Implicit background execution
+- ❌ Fire-and-forget APIs
+
+If something runs:
+> It must be owned by a fiber and a scope.
+
+---
+
+## Extension points
+
+Designed to grow horizontally:
+
+- New modules (HTTP, FS, DB, etc.)
+- New stream combinators
+- New schedulers (priority, test)
+- New runtimes (browser, workers)
+
+Without changing the core semantics.
+
+---
+
+## Mental model (TL;DR)
+
+- **Core** = execution + rules
+- **Async** = description
+- **Fiber** = interpreter
+- **Scope** = lifetime
+- **Modules** = pure libraries on top
+- **Interop** = explicit escape hatch
+
+If you understand this:
+👉 you understand the entire system.
+
+---
+
+## Status
+
+This architecture is:
+- Experimental
+- Intentionally minimal
+- Designed for learning, exploration, and correctness
+
+But:
+> It already enforces stronger guarantees than most Promise-based codebases.
+
+---
+
+MIT License © 2025
+
+
+---
+
+## Further reading
+
+- [Getting started](./getting-started.md)
+- [Modules overview](./modules.md)
+- [Cancellation & interruption](./cancellation.md)
+- [Observability (hooks & events)](./observability.md)
+- [HTTP client](./http.md)

package/docs/README.md

@@ -0,0 +1,65 @@
+# Documentation
+
+Start here:
+
+- **[Getting started](./getting-started.md)** — installation, first effects, and running examples
+- **[Architecture](./ARCHITECTURE.md)** — how the runtime is structured
+- **[Cancellation & interruption](./cancellation.md)** — interruption semantics, scopes, and cancellable `Async`
+- **[Observability](./observability.md)** — hooks, events, sinks, tracing, and HTTP policy context
+- **[Framework integrations](./framework-integrations.md)** — Vanilla, React, Next.js, Angular, Express, Fastify, and Nest patterns
+- **[NestJS integration](./frameworks/nestjs.md)** — Brass module, Grafana/OTLP observability, HTTP client DI, and inbound spans
+- **[HTTP client](./http.md)** — ZIO-style HTTP built on brass-runtime
+- **[HTTP recipes](./http-recipes.md)** — typed clients, custom transports, production adoption, observability, and config validation
+- **[Recipes](./recipes/README.md)** — copyable runtime, layer, HTTP server, testing, and performance paths
+- **[API polish notes](./api-polish.md)** — first-release DX audit and compatibility posture
+- **[First release checklist](./release.md)** — local release gate and perf evidence workflow
+- **[Modules overview](./modules.md)** — map of core modules and where things live
+- **[AI context pack](./ai/PROJECT_MAP.md)** — compact project map, invariants, validation matrix, and public API notes
+- **[Agent module boundaries](./agent-boundaries.md)** — rules for keeping `brass-agent` isolated from the core runtime
+- **[Brass Agent install and configure](./agent-install-and-configure.md)** — end-to-end local setup for CLI, config, providers, and VS Code
+
+- [Agent LLM adapters](./agent-llm-adapters.md)
+- [Agent env files](./agent-env-files.md)
+- [Agent global usage and workspace discovery](./agent-global-usage.md)
+- [Agent apply mode](./agent-apply-mode.md)
+- [Brass Agent CLI](./agent-cli.md)
+- [Agent init](./agent-init.md)
+- [Agent observability](./agent-observability.md)
+- [Agent approvals](./agent-approvals.md)
+- [Agent config and policy files](./agent-config.md)
+- [Agent project command discovery](./agent-project-commands.md)
+- [Agent project intelligence](./agent-project-intelligence.md)
+- [Declarative optimized planning roadmap](./agent-declarative-optimized-planning.md)
+- [Agent context discovery](./agent-context-discovery.md)
+- [Agent patch quality loop](./agent-patch-quality-loop.md)
+- [Agent automatic rollback safety](./agent-rollback-safety.md)
+- [Agent DX surfaces](./agent-dx.md)
+
+- [VS Code patch preview](./agent-vscode-patch-preview.md)
+- [VS Code enhanced diff preview](./agent-vscode-diff-preview.md)
+- [VS Code run history](./agent-vscode-run-history.md)
+- [VS Code batch runner](./agent-vscode-batch-runner.md)
+- [VS Code UX](./agent-vscode-ux.md)
+- [VS Code Project dashboard](./agent-vscode-project-dashboard.md)
+- [VS Code Chat layout / focus mode](./agent-vscode-chat-layout.md)
+- [Copilot-like VS Code DX](./agent-copilot-like-dx.md)
+- [Chat sessions and slash commands](./agent-chat-sessions.md)
+- [Agent follow-up context](./agent-follow-up-context.md)
+- [VS Code code actions](./agent-vscode-code-actions.md)
+- [VS Code problems-aware chat](./agent-vscode-problems.md)
+- [VS Code inline assist](./agent-vscode-inline-assist.md)
+- [Agent release readiness](./agent-release-readiness.md)
+- [VS Code local install](./agent-vscode-install.md)
+- [VS Code auto-discovery](./agent-vscode-auto-discovery.md)
+- [VS Code model setup](./agent-vscode-model-setup.md)
+- [Agent local install and doctor](./agent-local-install.md)
+- [Agent local tests](./agent-local-tests.md)
+
+- [Agent rollback patches](./agent-rollback.md)
+- [Agent redaction](./agent-redaction.md)
+- [Agent run artifacts](./agent-run-artifacts.md)
+- [Agent CI mode](./agent-ci.md)
+- [Agent presets](./agent-presets.md)
+- [Agent batch runs](./agent-batch.md)
+- [VS Code full clean and reinstall](./agent-vscode-clean-install.md)
+- [Agent language and workspace setup UX](agent-language-workspace-ux.md)

package/docs/adr/0001-ai-context-pack.md

@@ -0,0 +1,32 @@
+# ADR 0001: Maintain an AI Context Pack
+
+Status: accepted
+
+## Context
+
+`brass-runtime` contains a core effect runtime, streams, HTTP modules, WASM
+engine pieces, benchmarks, and Brass Agent surfaces. The codebase is still small
+enough to navigate manually, but large enough that a contributor or coding agent
+needs a compact map before making safe changes.
+
+## Decision
+
+Maintain a small context pack:
+
+- `AGENTS.md` for root-level contributor/agent guidance.
+- `docs/ai/PROJECT_MAP.md` for module navigation.
+- `docs/ai/INVARIANTS.md` for semantic rules.
+- `docs/ai/VALIDATION_MATRIX.md` for test selection.
+- `docs/ai/PUBLIC_API.md` for exports and compatibility.
+- `scripts/context-pack.mjs` for generated workspace summaries.
+
+The generated context command prints to stdout and does not create tracked
+artifacts by default.
+
+## Consequences
+
+- Future changes should update the context pack when they move module
+  boundaries, change public API, or add validation expectations.
+- Agents can gather focused context without rereading the entire repository.
+- The context pack is documentation, not a replacement for tests.
+

package/docs/agent-apply-mode.md

@@ -0,0 +1,104 @@
+# Agent apply mode
+
+P3 adds a conservative write path for the experimental agent.
+
+## Goal
+
+Keep the default CLI behavior safe:
+
+- default mode remains `propose`
+- `write` mode must be explicit
+- patch application remains policy-gated and approval-gated
+- patch targets must stay inside the workspace
+- discovered validation commands still go through `PermissionService`
+
+## New pieces
+
+`src/agent` now includes:
+
+- `PatchService`
+- `patch.apply` / `patch.applied`
+- unified-diff extraction helpers
+- a Node patch adapter built on `git apply`
+- CLI flags for `--mode`, `--apply`, and approval strategy
+
+## Modes
+
+```bash
+brass-agent "fix the failing tests"            # propose (default)
+brass-agent --apply "fix the failing tests"         # write, prompts when interactive
+brass-agent --apply --yes "fix the failing tests"   # write, auto-approve
+brass-agent --mode write "fix the failing tests"
+```
+
+## Safety rules
+
+1. The agent only applies unified diffs.
+2. All patch target paths are validated as workspace-relative before apply.
+3. `propose` mode may emit `patch.proposed`, but never `patch.apply`.
+4. `write` mode may apply patches only after approval.
+5. Shell commands remain whitelisted.
+6. After `patch.applied`, the agent re-runs the same discovered validation commands.
+
+## Patch adapter
+
+The Node adapter uses `git apply --check` before the actual apply step.
+
+That gives us a conservative path with a dry-run check first, while keeping the runtime invariant intact:
+all external work is still represented as cancellable `Async`.
+
+## Offline smoke tests
+
+You can drive the fake LLM with a deterministic response:
+
+~~~bash
+export BRASS_LLM_PROVIDER=fake
+export BRASS_FAKE_LLM_RESPONSE='Here is a patch.
+
+```diff
+--- a/hello.txt
++++ b/hello.txt
+@@ -1 +1 @@
+-old
++new
+```'
+
+brass-agent --apply --yes --cwd ./tmp/repro "apply the inferred patch"
+~~~
+
+## Patch quality loop
+
+P13 adds an optional repair loop for normal generated patches in `write` mode.
+After a generated patch is applied, the agent re-runs discovered validation
+commands. If validation fails and repair budget remains, it calls `llm.patch` to
+request an incremental repair diff, applies that diff, and validates again.
+
+The default repair budget is one attempt:
+
+```json
+{
+  "patchQuality": {
+    "enabled": true,
+    "maxRepairAttempts": 1
+  }
+}
+```
+
+Exact patch-file flows remain exact. `--apply-patch-file` does not trigger
+repair attempts, because clients such as the VS Code extension use that path
+after the user approved a specific previewed diff.
+
+See [Agent patch quality loop](./agent-patch-quality-loop.md).
+
+
+## Automatic rollback safety
+
+P14 adds automatic rollback safety for generated patches. If generated patches
+still fail validation after the configured repair attempts are exhausted, the
+agent can schedule `patch.rollback` actions to reverse the generated patch stack.
+
+Rollback is still policy-gated and approval-gated. Exact patch-file flows remain
+protected by default so a VS Code-approved patch is not silently reversed unless
+the project opts in with `rollback.allowForSuppliedPatches`.
+
+See [Agent automatic rollback safety](./agent-rollback-safety.md).

package/docs/agent-approvals.md

@@ -0,0 +1,110 @@
+# Agent approvals
+
+P6 adds interactive approvals to `brass-agent` without moving prompt logic into
+`src/core`.
+
+The boundary remains:
+
+```txt
+src/core
+  ↑
+src/agent PermissionService / ApprovalService
+  ↑
+src/agent/cli prompt UX
+```
+
+## Decision flow
+
+Every action still goes through the same policy pipeline:
+
+```txt
+AgentAction
+  -> PermissionService.check(...)
+  -> allow | deny | ask
+  -> ApprovalService.request(...) when ask
+  -> ToolPolicy timeout/retry
+  -> Async tool effect
+  -> Observation
+```
+
+`PermissionService` decides whether an action needs approval. `ApprovalService`
+decides how to obtain that approval: prompt the human, auto-approve, auto-deny,
+or integrate with another UI.
+
+## Built-in approvals
+
+The agent exports:
+
+```ts
+autoApproveApprovals
+makeAutoDenyApprovals(reason?)
+```
+
+The CLI also provides an interactive implementation that prompts on stderr.
+
+## CLI behavior
+
+```bash
+brass-agent --apply "fix tests"             # prompts when interactive
+brass-agent --apply --yes "fix tests"       # auto-approve
+brass-agent --apply --no-input "fix tests"  # auto-deny
+brass-agent --approval interactive --apply "fix tests"
+```
+
+Environment variables:
+
+```bash
+BRASS_AGENT_APPROVAL=approve|deny|interactive|auto
+BRASS_AGENT_AUTO_APPROVE=true
+```
+
+`auto` is conservative:
+
+```txt
+human TTY session -> interactive prompts
+json/events-json or non-TTY -> deny approval-required actions
+```
+
+Use `--yes` explicitly for non-interactive smoke tests or CI flows that are
+allowed to mutate the workspace.
+
+## Events
+
+Approvals emit typed events:
+
+```txt
+agent.approval.requested
+agent.approval.resolved
+```
+
+These events are available in human output and `--events-json`. They are emitted
+before and after the approval service runs.
+
+## Safety invariants
+
+- Approval prompts are a capability of `src/agent`, not `src/core`.
+- An action that requires approval must not run unless approval is granted.
+- Missing approval service means approval-required actions are rejected.
+- Observability is best-effort and must not change approval semantics.
+- Non-interactive runs deny by default unless explicitly configured to approve.
+
+## Config defaults
+
+P7 allows a project config file to set the default CLI approval strategy:
+
+```json
+{
+  "approval": "auto"
+}
+```
+
+CLI flags still win over config:
+
+```bash
+brass-agent --approval deny "inspect"
+brass-agent --yes --apply "fix tests"
+```
+
+`permissions.patchApply` can also tune whether `patch.apply` is allowed, denied,
+or routed through approval in `write` and `autonomous` modes. See
+[Agent config and policy files](./agent-config.md).