brass-runtime 1.15.0 → 1.16.1

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).

package/docs/agent-batch.md

@@ -0,0 +1,185 @@
+# Agent batch runs
+
+P21 adds sequential batch execution to `brass-agent`.
+
+The goal is to make common DX/CI workflows composable without introducing a new
+scheduler or breaking the existing boundary:
+
+```txt
+src/core
+  ↑
+src/agent runAgent(...)
+  ↑
+brass-agent CLI batch runner
+```
+
+A batch run is just multiple normal agent runs executed one after another. Each
+run still goes through the same pipeline:
+
+```txt
+AgentAction
+  -> PermissionService
+  -> ApprovalService when ask
+  -> ToolPolicy timeout/retry
+  -> Async tool effect
+  -> Observation
+```
+
+Batch mode does not bypass policy, approvals, redaction, rollback safety, CI exit
+codes, or artifact export.
+
+## CLI
+
+Run a batch from a file:
+
+```bash
+brass-agent --batch-file ./brass-agent.batch.json
+```
+
+In CI:
+
+```bash
+brass-agent --batch-file ./brass-agent.batch.json --ci --batch-stop-on-failure
+```
+
+`--batch-stop-on-failure` stops after the first run whose CI status is non-zero.
+`--batch-continue-on-failure` forces the opposite.
+
+When neither flag is provided, the default is:
+
+```txt
+--ci      -> stop on failure
+not --ci  -> continue
+```
+
+## Batch file formats
+
+### JSON array
+
+```json
+[
+  "inspect this workspace",
+  { "preset": "typecheck" },
+  { "preset": "lint" },
+  { "preset": "fix-tests", "mode": "propose" }
+]
+```
+
+### JSON object
+
+```json
+{
+  "goals": [
+    { "preset": "inspect" },
+    { "goal": "explain the failing tests", "mode": "read-only" },
+    { "goal": "fix the failing tests", "mode": "propose" }
+  ]
+}
+```
+
+### Plain text
+
+If the file is not valid JSON, `brass-agent` treats it as a line-based goal file.
+Blank lines and `#` comments are ignored.
+
+```txt
+# brass-agent.batch.txt
+inspect this workspace
+run typecheck discovery and explain failures
+fix the failing tests
+```
+
+## Per-goal fields
+
+JSON batch items support:
+
+```ts
+{
+  goal?: string;
+  preset?: "fix-tests" | "inspect" | "typecheck" | "lint";
+  mode?: "read-only" | "propose" | "write" | "autonomous";
+  cwd?: string;
+  patchFile?: string;
+  patchFileMode?: "apply" | "rollback";
+  saveRunDir?: string;
+}
+```
+
+`preset` fills in a standard goal. `goal` wins when both are present.
+
+`cwd` lets one batch file target multiple workspaces, but the same loaded config
+and CLI environment are reused for the full batch. Use separate invocations when
+different workspaces need different config files.
+
+## Config default batch
+
+A project can define a default batch:
+
+```json
+{
+  "batch": {
+    "stopOnFailure": true,
+    "goals": [
+      { "preset": "inspect" },
+      { "preset": "typecheck" },
+      { "preset": "lint" }
+    ]
+  }
+}
+```
+
+Then run:
+
+```bash
+brass-agent --ci
+```
+
+The config batch is used only when the CLI does not receive an explicit goal,
+`--preset`, `--patch-file`, or `--batch-file`.
+
+## Outputs
+
+Human output prints each normal run and then a final batch summary:
+
+```txt
+batch summary:
+completed: 3/3
+failed: 0
+exit code: 0
+```
+
+`--json` prints a batch object:
+
+```json
+{
+  "type": "batch",
+  "summary": {
+    "total": 3,
+    "completed": 3,
+    "failed": 0,
+    "exitCode": 0,
+    "stoppedEarly": false
+  },
+  "results": []
+}
+```
+
+`--protocol-json` emits normal event messages and a `final-state` message per
+run, followed by a `batch-summary` message.
+
+## Exit codes
+
+In `--ci` mode, batch exit code is aggregated from individual runs:
+
+```txt
+1 if any run failed or latest validation failed
+2 if no run failed but at least one run proposed an unapplied patch with --fail-on-patch-proposed
+0 otherwise
+```
+
+## VS Code
+
+P22 adds a VS Code command, `Brass Agent: Run Batch File`, which invokes the CLI
+with `--protocol-json --batch-file`. The extension stores the batch as a parent
+history entry and each CLI `final-state` message as a child run. See
+[VS Code batch runner](./agent-vscode-batch-runner.md).

package/docs/agent-boundaries.md

@@ -0,0 +1,112 @@
+# Agent Module Boundaries
+
+These rules keep the experimental agent layer useful without letting it leak into the runtime core.
+
+## Dependency direction
+
+```txt
+core runtime
+  ↑
+agent module
+  ↑
+cli / UX
+```
+
+Rules:
+
+1. `src/core` must not know that `src/agent` exists.
+2. `src/agent` may depend on `src/core` runtime primitives.
+3. Agent-specific shortcuts must not be added to `Runtime`, `Fiber`, `Scope`, or the scheduler.
+4. If the agent reveals a missing semantic in the core, fix the core as a runtime invariant first.
+5. Keep the agent as an experimental consumer of the runtime until the shape is stable.
+
+## Agent execution model
+
+The agent does not perform side effects directly.
+
+It must follow this pipeline:
+
+```txt
+Goal
+  -> decideNextAction
+  -> PermissionService
+  -> ApprovalService when permission decision is ask
+  -> ToolPolicy
+  -> AgentAction interpreted as Async
+  -> Observation
+  -> reducer
+  -> next AgentState
+```
+
+Rules:
+
+1. The planner produces `AgentAction` values.
+2. Every `AgentAction` is interpreted into `Async<AgentEnv, AgentError, Observation>`.
+3. All external work goes through capabilities in `AgentEnv`.
+4. All tool execution goes through permissions first.
+5. Approval-required actions must be approved before tool execution.
+6. All tool execution goes through timeout/retry policy.
+7. No detached background work by default.
+8. Every async tool that touches external work must be cancellable.
+9. Any patch-application path must validate that every target path stays inside the workspace.
+
+
+## Configuration boundary
+
+Project policy may be loaded from `.brass-agent.json`, but config is still an
+agent-layer concern:
+
+```txt
+src/core
+  ↑
+src/agent policy/config
+  ↑
+src/agent/cli Node config loader
+```
+
+Rules:
+
+1. Config loading must not move into `src/core`.
+2. Config is resolved before constructing `AgentEnv`.
+3. Config may tune permissions, approvals, LLM provider/model, and tool policies.
+4. Config must not store secrets; adapters should read API keys from environment variables.
+5. Config must not bypass the `AgentAction -> PermissionService -> ApprovalService -> ToolPolicy -> Async -> Observation` pipeline.
+
+## Runtime invariants the agent relies on
+
+The agent assumes these runtime semantics:
+
+1. `Scope.close()` interrupts child fibers.
+2. `Scope.closeAsync(...)` can be awaited.
+3. Closing a parent scope propagates to subscopes.
+4. Interrupted fibers run their finalizers exactly once.
+5. `Async` work that registers external IO returns a canceler.
+6. Race-like operators close their internal scopes and cancel losing branches.
+7. If a tool cannot be cancelled, it is a bug in the tool adapter.
+
+## Safety defaults
+
+Initial agent modes should be conservative:
+
+1. `read-only`: read/search/model only.
+2. `propose`: read/search/model plus whitelisted read-only commands and patch proposals.
+3. `write`: may apply patches only after approval.
+4. `autonomous`: reserved for later; sensitive actions still require approval.
+
+The initial CLI should default to `propose`.
+
+## Extraction rule
+
+Keep the agent in `src/agent` while validating the vertical slice.
+Extract to packages only after the design stabilizes:
+
+```txt
+packages/
+  brass-runtime/
+  brass-agent/
+  brass-node/
+  brass-llm/
+  brass-cli/
+```
+
+Until then, `src/agent` is allowed to be experimental, but `src/core` is not.

package/docs/agent-chat-sessions.md

@@ -0,0 +1,160 @@
+# Brass Agent chat sessions
+
+P30 turns the VS Code Chat view from a one-shot launcher into a lightweight
+conversation surface.
+
+The CLI remains the canonical execution boundary. The VS Code extension still
+calls:
+
+```bash
+brass-agent --protocol-json --protocol-full-patches --cwd <workspace> <goal>
+```
+
+The new session behavior lives entirely in the extension.
+
+## What is stored
+
+The VS Code extension stores a compact chat session in `workspaceState`:
+
+```txt
+messages
+last run summary
+last validation output
+last patch stats
+last patch body, only when brassAgent.storePatchesInHistory is true
+```
+
+This is editor-local state. It is not written to the repository and it is not
+owned by `src/core` or `src/agent`.
+
+The message history length is controlled by:
+
+```json
+{
+  "brassAgent.chatHistoryLimit": 80
+}
+```
+
+Disable patch persistence with:
+
+```json
+{
+  "brassAgent.storePatchesInHistory": false
+}
+```
+
+## Follow-up context
+
+After a run, follow-up messages can use the previous run as context.
+
+For example:
+
+```txt
+fix the failing tests
+why did that fail?
+try again but do not change the public API
+explain the patch
+```
+
+The extension composes the next agent goal with a compact context block that may
+include:
+
+```txt
+previous goal
+previous status
+previous summary/error
+latest validation command output
+last patch stats
+last patch diff, only for explicit explain-last style requests
+```
+
+The agent is instructed to ignore previous context if the new request is
+unrelated.
+
+## Slash commands
+
+The chat supports slash commands to avoid menus and flags:
+
+```txt
+/inspect
+/fix-tests
+/typecheck
+/lint
+/ask <question>
+/propose <task>
+/apply <task>
+/explain-last
+/apply-last
+/rollback-last
+/doctor
+/output
+/clear
+/help
+```
+
+### Safety behavior
+
+`/apply <task>` still uses the safe apply-preview flow:
+
+```txt
+chat request
+  -> propose run
+  -> patch preview
+  -> user approval
+  -> brass-agent --apply-patch-file <exact diff>
+```
+
+`/apply-last` reopens the last patch preview. It does not silently write.
+
+`/rollback-last` calls the CLI rollback path:
+
+```bash
+brass-agent --rollback-patch-file <temp.diff> --yes ...
+```
+
+It asks for VS Code confirmation first, and the CLI still goes through the normal
+patch rollback service.
+
+## Quick actions
+
+Assistant messages can include buttons such as:
+
+```txt
+Open patch preview
+Explain last
+Rollback last
+Show output
+```
+
+These buttons send slash commands back through the same chat handler.
+
+## Boundary
+
+The boundary remains unchanged:
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI protocol
+  ↑
+VS Code chat session UI
+```
+
+The extension owns conversation memory and UX. The agent owns execution,
+permissions, validation, redaction, patch application, rollback, and protocol
+semantics.
+
+## Explain last behavior
+
+`/explain-last` is intentionally local and deterministic. It summarizes the last
+stored run from VS Code workspace state instead of launching a new agent run.
+
+That keeps the button useful even when the previous run stopped before the LLM
+step, for example because a context file disappeared or a tool returned `FsError`.
+For an AI follow-up using the same context, use:
+
+```txt
+/ask why did that fail?
+```