brass-runtime 1.15.0 → 1.16.1

package/docs/agent-llm-adapters.md

@@ -0,0 +1,123 @@
+# Agent LLM adapters
+
+`src/agent` keeps LLM providers behind the small `LLM` capability:
+
+```ts
+export type LLM = {
+  readonly complete: (request: LLMRequest) => Async<unknown, AgentError, LLMResponse>;
+};
+```
+
+Adapters must return `Async` and must be cancelable. They should not leak provider-specific request or response shapes into the agent loop.
+
+## Provider selection in the CLI
+
+The local CLI chooses a provider from environment variables:
+
+```bash
+BRASS_LLM_PROVIDER=google          # or gemini
+BRASS_LLM_PROVIDER=openai-compatible
+BRASS_LLM_PROVIDER=fake
+```
+
+If `BRASS_LLM_PROVIDER` is omitted, the CLI auto-detects providers in this order:
+
+1. Google Gemini, when `BRASS_GOOGLE_API_KEY`, `GOOGLE_API_KEY`, or `GEMINI_API_KEY` exists.
+2. OpenAI-compatible, when both `BRASS_LLM_ENDPOINT` and `BRASS_LLM_API_KEY` exist.
+3. Fake LLM, as a no-network fallback.
+
+## Google Gemini / Generative Language API
+
+Use the native Google adapter:
+
+```ts
+import { makeGoogleGenerativeAILLM } from "brass-runtime/agent";
+
+const llm = makeGoogleGenerativeAILLM({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "gemini-2.5-flash",
+});
+```
+
+CLI example:
+
+```bash
+export BRASS_LLM_PROVIDER=google
+export GEMINI_API_KEY="..."
+export BRASS_GOOGLE_MODEL="gemini-2.5-flash"
+
+npx tsx src/agent/cli/main.ts "fix the failing tests"
+```
+
+The same keys can live in `.env` or `.brass-agent.env` in the workspace; the
+CLI auto-loads supported agent env keys before choosing the provider.
+
+Supported Google-specific variables:
+
+```bash
+BRASS_GOOGLE_API_KEY              # preferred explicit key for brass-agent
+GOOGLE_API_KEY                    # supported by Google SDKs; also accepted here
+GEMINI_API_KEY                    # supported by Google SDKs; also accepted here
+BRASS_GOOGLE_MODEL                # defaults to gemini-2.5-flash
+BRASS_GOOGLE_API_VERSION          # defaults to v1beta
+BRASS_GOOGLE_BASE_URL             # defaults to https://generativelanguage.googleapis.com
+BRASS_GOOGLE_ENDPOINT             # full generateContent endpoint override
+BRASS_GOOGLE_SYSTEM_INSTRUCTION
+BRASS_GOOGLE_TEMPERATURE
+BRASS_GOOGLE_TOP_P
+BRASS_GOOGLE_TOP_K
+BRASS_GOOGLE_MAX_OUTPUT_TOKENS
+```
+
+The adapter uses `models.generateContent` with the `x-goog-api-key` header and maps Gemini `candidates[].content.parts[].text` into `LLMResponse.content`.
+
+## OpenAI-compatible
+
+Use the existing adapter:
+
+```bash
+export BRASS_LLM_PROVIDER=openai-compatible
+export BRASS_LLM_ENDPOINT="https://.../chat/completions"
+export BRASS_LLM_API_KEY="..."
+export BRASS_LLM_MODEL="..."
+```
+
+## Fake
+
+Use this for offline smoke tests:
+
+```bash
+export BRASS_LLM_PROVIDER=fake
+npx tsx src/agent/cli/main.ts "fix the failing tests"
+```
+
+You can also force a deterministic fake response, including a fenced diff block:
+
+~~~bash
+export BRASS_LLM_PROVIDER=fake
+export BRASS_FAKE_LLM_RESPONSE='```diff
+--- a/hello.txt
++++ b/hello.txt
+@@ -1 +1 @@
+-old
++new
+```'
+~~~
+
+## Config-file selection
+
+P7 also lets the CLI select an adapter through `.brass-agent.json`:
+
+```json
+{
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY"
+  }
+}
+```
+
+Environment variables still override config values. Secrets should stay in the
+environment; the config loader rejects `llm.apiKey` and expects `llm.apiKeyEnv`
+instead.

package/docs/agent-local-install.md

@@ -0,0 +1,190 @@
+# Brass Agent local install and doctor
+
+> For the end-to-end setup flow, see [Brass Agent install and configure](./agent-install-and-configure.md).
+
+P23 intentionally avoids CI/release automation. It focuses on making local DX
+boring: build the CLI, package/install the VS Code extension, point the extension
+at the local CLI, and diagnose the setup.
+
+## One-command local VS Code install
+
+From the repository root:
+
+```bash
+npm run agent:vscode:install
+```
+
+That script performs the local install flow:
+
+```txt
+npm install                 # only if root node_modules is missing
+npm run build               # builds dist/agent/cli/main.cjs
+npm install                 # inside extensions/vscode-brass-agent, if needed
+npm run compile             # extension TypeScript
+npm run package:vsix        # creates vscode-brass-agent-*.vsix
+code --install-extension    # installs the VSIX locally
+write .vscode/settings.json # points brassAgent.command at the built local CLI
+```
+
+The setting it writes is:
+
+```json
+{
+  "brassAgent.command": "/absolute/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```
+
+That means the extension can run the exact local CLI build without requiring a
+global npm install.
+
+## Global CLI for many projects
+
+To use `brass-agent` outside the `brass-runtime` checkout:
+
+```bash
+npm run agent:link
+```
+
+Then from any project:
+
+```bash
+brass-agent --where
+brass-agent --doctor
+brass-agent --preset inspect
+```
+
+To make VS Code work through that global command instead of an absolute local path:
+
+```bash
+npm run agent:vscode:install:global
+```
+
+That command runs the global link flow and installs the VS Code extension with `brassAgent.command = "brass-agent"`.
+
+To remove only the global CLI link/install:
+
+```bash
+npm run agent:unlink
+```
+
+To remove the VS Code extension, workspace settings/storage, generated VSIX files, and the global CLI link/install:
+
+```bash
+npm run agent:vscode:uninstall:global
+```
+
+To do a clean global reinstall:
+
+```bash
+npm run agent:vscode:reinstall:global
+```
+
+## Package only
+
+To build/package the extension without installing it into VS Code:
+
+```bash
+npm run agent:vscode:package
+```
+
+This is useful when you want to manually install from VS Code via:
+
+```txt
+Extensions view
+  -> Views and More Actions...
+  -> Install from VSIX...
+```
+
+## Install script options
+
+The underlying script is:
+
+```bash
+node scripts/install-vscode-extension.mjs
+```
+
+Useful options:
+
+```bash
+node scripts/install-vscode-extension.mjs --dry-run
+node scripts/install-vscode-extension.mjs --no-code-install
+node scripts/install-vscode-extension.mjs --no-settings
+node scripts/install-vscode-extension.mjs --workspace ../some-project
+node scripts/install-vscode-extension.mjs --use-global-command
+node scripts/install-vscode-extension.mjs --command brass-agent
+node scripts/install-vscode-extension.mjs --code "code-insiders"
+```
+
+Use `--workspace` when you want the script to write `.vscode/settings.json` into
+a different project than the `brass-runtime` checkout. Use `--use-global-command`
+when `brass-agent` is available on PATH and you do not want workspace settings to
+point at an absolute `dist/agent/cli/main.cjs` path.
+
+## Doctor
+
+Run:
+
+```bash
+npm run agent:doctor
+```
+
+or after building/installing:
+
+```bash
+brass-agent --doctor
+```
+
+The doctor checks:
+
+```txt
+Node.js / npm
+git
+ripgrep / rg
+workspace package.json and scripts
+inferred package manager
+LLM provider environment
+.brass-agent.json / brass-agent.config.json discovery
+VS Code `code` CLI
+VS Code workspace setting brassAgent.command
+local CLI build artifact
+VS Code extension build / VSIX package
+```
+
+JSON output is available for scripts:
+
+```bash
+brass-agent --doctor --json
+```
+
+## Why this is not CI
+
+This is deliberately local-first. It gives us repeatable commands that a person
+can run before we add workflows:
+
+```bash
+npm run agent:vscode:install
+npm run agent:doctor
+```
+
+Later, CI can reuse the same install/build/doctor concepts, but P23 does not add
+GitHub Actions or release automation.
+
+## Initialize a workspace first
+
+For a new project, bootstrap local config before deeper DX setup:
+
+```bash
+brass-agent --init
+brass-agent --doctor
+```
+
+The VS Code extension also contributes `Brass Agent: Initialize Workspace`, which runs the same init flow from the command palette.
+
+## Env files
+
+`brass-agent --doctor` auto-loads supported agent keys from `.brass-agent.env`, `.env.local`, and `.env` in the workspace. Use `--env-file PATH` to choose a file or `--no-env-file` to disable this behavior. See [Agent env files](./agent-env-files.md).
+
+
+## VS Code auto-discovery
+
+The VS Code extension can now use `brassAgent.command = "auto"` and prefer its bundled CLI, so you can open any repo and use Brass Agent without linking the CLI globally. See [VS Code auto-discovery](./agent-vscode-auto-discovery.md).

package/docs/agent-local-tests.md

@@ -0,0 +1,51 @@
+# Brass Agent local tests
+
+P36 adds local smoke-test scripts for dogfooding without CI.
+
+These tests are intentionally local-first. They do not publish artifacts, do not require a real LLM provider, and do not need GitHub Actions.
+
+## Smoke test
+
+Build first, then run:
+
+```bash
+npm run agent:test:smoke
+```
+
+Or run the full local flow:
+
+```bash
+npm run agent:test:local
+```
+
+`agent:test:local` runs:
+
+```txt
+npm run build
+node scripts/agent-local-smoke.mjs
+```
+
+## What the smoke test validates
+
+The smoke test creates a temporary project and checks:
+
+```txt
+- the built CLI exists
+- read-only inspect can finish with fake LLM
+- apply mode can use fake LLM diff output
+- patch preview/apply plumbing can update a file through the CLI
+- validation can pass after the patch
+```
+
+It uses:
+
+```txt
+BRASS_LLM_PROVIDER=fake
+BRASS_FAKE_LLM_RESPONSE=<controlled unified diff>
+```
+
+No real API key is required.
+
+## Why no CI yet
+
+This is a local stabilization step only. CI and release automation remain intentionally deferred until the agent UX has been dogfooded more heavily.

package/docs/agent-observability.md

@@ -0,0 +1,155 @@
+# Brass Agent observability
+
+`brass-agent` emits a typed event stream while the agent loop runs.
+
+The event stream is intentionally modeled as a capability of the agent environment:
+
+```ts
+type AgentEnv = {
+  fs: FileSystem;
+  shell: Shell;
+  llm: LLM;
+  patch: PatchService;
+  permissions: PermissionService;
+  approvals?: ApprovalService;
+  events?: AgentEventSink;
+};
+```
+
+The core runtime does not know about the agent. The agent depends on the runtime and exposes its own higher-level observability events.
+
+## Invariant
+
+Observability must never change agent semantics.
+
+If an event sink throws, the agent ignores the sink failure and continues. Event sinks are best-effort and should not be used for control flow.
+
+## Event lifecycle
+
+A normal run emits events in this order:
+
+```txt
+agent.run.started
+agent.action.started
+agent.action.completed
+agent.observation.recorded
+...
+agent.run.completed
+```
+
+If a tool fails, the action emits:
+
+```txt
+agent.action.started
+agent.action.failed
+agent.observation.recorded
+```
+
+Some important failures also emit specialized events:
+
+```txt
+agent.tool.timeout
+agent.permission.denied
+agent.approval.requested
+agent.approval.resolved
+```
+
+Approval events are emitted around `ApprovalService.request(...)`. They report
+that an action asked for human or policy approval and whether that approval was
+granted or rejected.
+
+When a patch is applied, the stream also emits:
+
+```txt
+agent.patch.applied
+```
+
+## CLI output
+
+Human output now uses the live event stream by default:
+
+```bash
+brass-agent "fix the failing tests"
+```
+
+Example shape:
+
+```txt
+brass-agent propose
+workspace: /repo
+goal: fix the failing tests
+
+→ read package.json
+✓ read package.json 3ms
+→ check pnpm-lock.yaml
+✓ found pnpm-lock.yaml 2ms
+→ pnpm test
+! pnpm test exited 1 1234ms
+→ llm.plan
+✓ llm.plan responded 2400ms
+→ propose patch
+✓ patch proposed 1ms
+→ finish
+✓ done 1ms
+
+phase: done
+steps: 5
+```
+
+The old full-state debug output is still available:
+
+```bash
+brass-agent --json "fix the failing tests"
+```
+
+For quick machine-readable streaming, use event-only JSON Lines:
+
+```bash
+brass-agent --events-json "fix the failing tests"
+```
+
+This prints one compact `AgentEvent` per line.
+
+For editor integrations and other clients, prefer the protocol stream:
+
+```bash
+brass-agent --protocol-json "fix the failing tests"
+```
+
+This prints newline-delimited messages with `protocol: "brass-agent"`, `version: 1`, event messages, and a final-state message. See [Agent DX surfaces](./agent-dx.md).
+
+## Programmatic usage
+
+```ts
+import {
+  runAgent,
+  type AgentEnv,
+  type AgentEventSink,
+} from "brass-runtime/agent";
+
+const events: AgentEventSink = {
+  emit(event) {
+    console.log(event.type, event);
+  },
+};
+
+const env: AgentEnv = {
+  fs,
+  shell,
+  patch,
+  llm,
+  permissions,
+  approvals,
+  events,
+};
+```
+
+## Privacy and output size
+
+The CLI compacts large payloads in `--events-json` mode, including file contents, LLM prompts, LLM responses, shell output, and patches.
+
+Programmatic event sinks receive the typed event values directly. If you forward them to logs, apply your own redaction policy.
+
+## Boundary rule
+
+`src/core` must not import agent events. Agent observability lives in `src/agent` and is built on top of runtime semantics.

package/docs/agent-patch-quality-loop.md

@@ -0,0 +1,162 @@
+# Agent patch quality loop
+
+P13 adds a bounded repair loop for generated patches.
+
+The previous apply flow was one-shot:
+
+```txt
+llm.plan
+  -> patch.apply
+  -> validation commands
+  -> finish
+```
+
+The new flow can perform one or more repair attempts when the generated patch
+fails to apply or when validation still fails after apply:
+
+```txt
+llm.plan
+  -> patch.apply
+  -> validation commands
+  -> if validation fails: llm.patch
+  -> patch.apply
+  -> validation commands
+  -> finish
+```
+
+The loop is intentionally small and bounded. It is a quality pass, not an
+unbounded autonomous edit loop.
+
+## Exact patch safety
+
+Runs started with an explicit patch file stay exact:
+
+```bash
+brass-agent --apply-patch-file ./approved.diff --yes "apply approved patch"
+```
+
+For these runs, repair is disabled. That preserves the VS Code patch preview
+invariant:
+
+```txt
+preview patch A
+  -> approve patch A
+  -> apply exactly patch A
+```
+
+The agent must not silently generate and apply patch B after the user approved
+patch A. To allow the agent to repair its own generated patches, use normal
+write mode instead:
+
+```bash
+brass-agent --apply "fix the failing tests"
+```
+
+## Configuration
+
+Configure the loop in `.brass-agent.json`:
+
+```json
+{
+  "patchQuality": {
+    "enabled": true,
+    "maxRepairAttempts": 1
+  }
+}
+```
+
+Defaults:
+
+```txt
+enabled: true
+maxRepairAttempts: 1
+```
+
+Disable repairs entirely:
+
+```json
+{
+  "patchQuality": {
+    "enabled": false
+  }
+}
+```
+
+Allow two repair calls after the initial generated patch:
+
+```json
+{
+  "patchQuality": {
+    "maxRepairAttempts": 2
+  }
+}
+```
+
+A value of `0` means “apply once, validate once, do not ask for repairs.”
+
+## What counts as a repair attempt?
+
+Only LLM calls with purpose `patch` count as repair attempts.
+
+The initial planning call is still `llm.plan`:
+
+```txt
+llm.plan      # initial diagnosis / patch proposal
+llm.patch     # repair attempt 1
+llm.patch     # repair attempt 2, if configured
+```
+
+## What triggers a repair?
+
+A repair can be requested when all of these are true:
+
+1. the agent is in `write` or `autonomous` mode
+2. the patch came from the agent, not from `--apply-patch-file`
+3. `patchQuality.enabled` is not `false`
+4. remaining repair budget is greater than zero
+5. either:
+   - `patch.apply` failed, or
+   - validation commands ran after `patch.applied` and at least one failed
+
+Permission denials, approval rejections, and non-patch tool failures do not
+trigger patch repair.
+
+## Boundaries
+
+The repair loop does not change the core runtime boundary:
+
+```txt
+src/core
+  ↑
+src/agent decides llm.patch / patch.apply
+  ↑
+src/agent/cli configures patchQuality
+```
+
+Repair is just more agent logic expressed as normal actions:
+
+```txt
+AgentAction(llm.complete purpose=patch)
+  -> LLM capability
+  -> Observation(llm.response purpose=patch)
+  -> AgentAction(patch.apply)
+  -> PermissionService / ApprovalService
+  -> PatchService
+  -> validation commands
+```
+
+No side effects are executed outside the `Async` tool pipeline.
+
+
+## Relationship with rollback safety
+
+P14 runs after the patch quality loop. If validation still fails and no repair
+attempts remain, rollback safety can reverse generated patches through
+`patch.rollback`. This keeps repair and restore as separate decisions:
+
+```txt
+repair budget remains -> llm.patch
+repair budget exhausted -> optional patch.rollback
+```
+
+See [Agent automatic rollback safety](./agent-rollback-safety.md).

package/docs/agent-presets.md

@@ -0,0 +1,22 @@
+# Brass Agent presets
+
+P20 adds built-in DX presets for common developer workflows.
+
+```bash
+brass-agent --preset fix-tests
+brass-agent --preset inspect
+brass-agent --preset typecheck
+brass-agent --preset lint
+```
+
+A preset only supplies a default goal and, for `inspect`, defaults to `read-only` when no `--mode` was explicitly provided. Explicit goal text and flags still win.
+
+VS Code also exposes preset commands:
+
+```txt
+Brass Agent: Fix Tests
+Brass Agent: Typecheck
+Brass Agent: Lint
+```
+
+The VS Code commands still use the preview-first flow: generate patch proposal, show Webview, then apply the exact reviewed patch through `brass-agent`.