brass-runtime 1.15.0 → 1.16.1

package/docs/agent-install-and-configure.md

@@ -0,0 +1,516 @@
+# Brass Agent install and configuration
+
+This guide is the shortest path from a fresh checkout to a working local
+`brass-agent` CLI and VS Code extension.
+
+`brass-agent` is still an experimental module that lives on top of
+`brass-runtime`. Treat this as an alpha install flow: good for local dogfooding,
+not yet a stable release process.
+
+## What gets installed
+
+There are two pieces:
+
+```txt
+brass-agent CLI
+  The canonical runner. It owns config loading, policy, approvals, LLM adapters,
+  patch application, rollback safety, context discovery, and batch execution.
+
+VS Code extension
+  A thin client. It calls the CLI through --protocol-json, renders progress,
+  patch previews, history, and batch runs. It does not apply patches directly.
+```
+
+The boundary remains:
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI
+  ↑
+VS Code extension / editor clients
+```
+
+## Prerequisites
+
+You need these available locally:
+
+```txt
+Node.js + npm
+Git
+ripgrep (`rg`) for context search
+```
+
+Optional but recommended:
+
+```txt
+VS Code CLI (`code`) if you want one-command VS Code extension installation
+A Gemini or OpenAI-compatible API key if you want a real model
+```
+
+Check your machine with:
+
+```bash
+brass-agent --doctor
+```
+
+or, before globally linking the CLI:
+
+```bash
+npm run agent:doctor
+```
+
+## Install the CLI from source
+
+From the `brass-runtime` checkout:
+
+```bash
+npm install
+npm run build
+```
+
+Smoke test the built CLI directly:
+
+```bash
+node dist/agent/cli/main.cjs --doctor
+```
+
+To expose `brass-agent` on your shell path during local development:
+
+```bash
+npm run agent:link
+brass-agent --doctor
+```
+
+This lets you run `brass-agent` from any project, not just the
+`brass-runtime` checkout. To verify which project root will be used:
+
+```bash
+cd /path/to/my-project/some/subfolder
+brass-agent --where
+```
+
+The CLI auto-discovers the nearest workspace root by searching upward for
+`.brass-agent.json`, `brass-agent.config.json`, `package.json`, workspace
+markers, or `.git`. Use `--no-discover-workspace` when you intentionally want
+`--cwd` to be exact.
+
+To remove only the global CLI link/install:
+
+```bash
+npm run agent:unlink
+```
+
+To remove the VS Code global-command setup and the global CLI link/install together:
+
+```bash
+npm run agent:vscode:uninstall:global
+```
+
+If you do not want to link it globally, use one of these instead:
+
+```bash
+npm run agent:dev -- --doctor
+node /absolute/path/to/brass-runtime/dist/agent/cli/main.cjs --doctor
+```
+
+## Initialize a workspace
+
+In the project where you want to use the agent:
+
+```bash
+cd /path/to/my-project
+brass-agent --init
+```
+
+This creates:
+
+```txt
+.brass-agent.json
+brass-agent.batch.json
+.env.example
+BRASS_AGENT.md
+```
+
+Existing files are skipped. To preview without writing:
+
+```bash
+brass-agent --init --init-dry-run
+```
+
+To overwrite generated files intentionally:
+
+```bash
+brass-agent --init --force
+```
+
+### Provider-specific init
+
+For Gemini / Google:
+
+```bash
+brass-agent --init --init-profile google
+```
+
+For OpenAI-compatible APIs:
+
+```bash
+brass-agent --init --init-profile openai-compatible
+```
+
+For offline smoke tests:
+
+```bash
+brass-agent --init --init-profile fake
+```
+
+## Configure an LLM provider
+
+Secrets should live in environment variables, not in `.brass-agent.json`.
+The config file should reference the variable name through `apiKeyEnv`.
+
+### Google / Gemini
+
+`.brass-agent.json`:
+
+```json
+{
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY"
+  }
+}
+```
+
+Shell:
+
+```bash
+export GEMINI_API_KEY="..."
+brass-agent --doctor
+```
+
+Or `.env` / `.brass-agent.env` in the workspace:
+
+```bash
+BRASS_LLM_PROVIDER=google
+GEMINI_API_KEY="..."
+BRASS_GOOGLE_MODEL=gemini-2.5-flash
+```
+
+`brass-agent --doctor` auto-loads supported agent keys from those files.
+
+### OpenAI-compatible
+
+`.brass-agent.json`:
+
+```json
+{
+  "llm": {
+    "provider": "openai-compatible",
+    "endpoint": "https://api.openai.com/v1/chat/completions",
+    "model": "gpt-4.1",
+    "apiKeyEnv": "BRASS_LLM_API_KEY"
+  }
+}
+```
+
+Shell:
+
+```bash
+export BRASS_LLM_API_KEY="..."
+brass-agent --doctor
+```
+
+Or `.env` / `.brass-agent.env` in the workspace:
+
+```bash
+BRASS_LLM_PROVIDER=openai-compatible
+BRASS_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
+BRASS_LLM_API_KEY="..."
+BRASS_LLM_MODEL=gpt-4.1
+```
+
+### Fake / offline
+
+`.brass-agent.json`:
+
+```json
+{
+  "llm": {
+    "provider": "fake",
+    "fakeResponse": "Fake plan from local config."
+  }
+}
+```
+
+or per command:
+
+```bash
+BRASS_LLM_PROVIDER=fake brass-agent --preset inspect
+```
+
+## Recommended `.brass-agent.json`
+
+A conservative starting point:
+
+```json
+{
+  "mode": "propose",
+  "approval": "auto",
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY"
+  },
+  "project": {
+    "packageManager": "auto",
+    "includeTypecheck": true,
+    "includeLint": true,
+    "maxValidationCommands": 2
+  },
+  "context": {
+    "enabled": true,
+    "maxSearchQueries": 3,
+    "maxFiles": 4,
+    "maxSearchResults": 40,
+    "excludeGlobs": [
+      ".env*",
+      "secrets/**",
+      "*.pem",
+      "*.key",
+      "node_modules/**",
+      "dist/**",
+      "build/**"
+    ]
+  },
+  "redaction": {
+    "enabled": true
+  },
+  "patchQuality": {
+    "enabled": true,
+    "maxRepairAttempts": 1
+  },
+  "rollback": {
+    "enabled": true,
+    "onFinalValidationFailure": true,
+    "strategy": "all",
+    "runValidationAfterRollback": true,
+    "allowForSuppliedPatches": false
+  },
+  "permissions": {
+    "patchApply": {
+      "decision": "ask",
+      "reason": "Apply generated code changes to this workspace.",
+      "risk": "high",
+      "defaultAnswer": "reject"
+    },
+    "shell": {
+      "inheritDefaults": true,
+      "deny": [
+        "rm *",
+        "git push *",
+        "git reset *",
+        "git clean *"
+      ]
+    }
+  }
+}
+```
+
+Important defaults:
+
+```txt
+mode: propose
+  The agent can inspect, validate, and propose patches, but does not write by default.
+
+approval: auto
+  Interactive terminal prompts when possible; non-interactive runs reject approval-required actions unless --yes is used.
+
+patchApply: ask
+  Generated patches require approval before being applied.
+
+redaction.enabled: true
+  Prompt context is redacted before LLM calls.
+```
+
+## First commands to run
+
+After `--init` and provider setup:
+
+```bash
+brass-agent --doctor
+brass-agent --preset inspect
+brass-agent --preset typecheck
+brass-agent --preset lint
+brass-agent --preset fix-tests
+```
+
+Default runs are safe/propose-oriented. To allow writes:
+
+```bash
+brass-agent --apply "fix the failing tests"
+```
+
+In an interactive terminal, approval is requested before `patch.apply`.
+For local smoke tests where you intentionally want to auto-approve:
+
+```bash
+brass-agent --apply --yes "fix the failing tests"
+```
+
+## Batch runs
+
+`--init` creates `brass-agent.batch.json`. Run it with:
+
+```bash
+brass-agent --batch-file brass-agent.batch.json
+```
+
+For a configured batch in `.brass-agent.json`:
+
+```bash
+brass-agent
+```
+
+only uses the configured batch when no explicit goal, preset, patch file, or
+batch file is provided.
+
+## Save run artifacts
+
+To keep a local JSON and Markdown record of a run:
+
+```bash
+brass-agent --save-run .brass-agent/runs --preset fix-tests
+```
+
+Generated artifacts are local files and may include compacted observations and
+summaries. Review before committing them.
+
+## Use the same CLI in many projects
+
+For many projects, the easiest setup is:
+
+```bash
+cd /path/to/brass-runtime
+npm run agent:vscode:install:global
+```
+
+To remove or reinstall that setup later:
+
+```bash
+npm run agent:vscode:uninstall:global
+npm run agent:vscode:reinstall:global
+```
+
+Then any VS Code workspace can use:
+
+```json
+{
+  "brassAgent.command": "brass-agent"
+}
+```
+
+See [Agent global usage and workspace discovery](./agent-global-usage.md).
+
+## Install the VS Code extension locally
+
+From the `brass-runtime` checkout:
+
+```bash
+npm run agent:vscode:install
+```
+
+This packages and installs the local extension and writes workspace settings so
+VS Code knows which `brass-agent` command to call.
+
+Manual packaging:
+
+```bash
+npm run agent:vscode:package
+```
+
+Then install the generated `.vsix` from VS Code with **Extensions: Install from
+VSIX...**.
+
+Useful VS Code commands:
+
+```txt
+Brass Agent: Initialize Workspace
+Brass Agent: Doctor
+Brass Agent: Inspect Workspace
+Brass Agent: Propose Fix
+Brass Agent: Apply Fix
+Brass Agent: Fix Tests
+Brass Agent: Typecheck
+Brass Agent: Lint
+Brass Agent: Run Batch File
+Brass Agent: Run Configured Batch
+```
+
+If VS Code cannot find the CLI, set:
+
+```json
+{
+  "brassAgent.command": "/absolute/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```
+
+or use the global linked command:
+
+```json
+{
+  "brassAgent.command": "brass-agent"
+}
+```
+
+## Common troubleshooting
+
+Run:
+
+```bash
+brass-agent --doctor
+```
+
+Common fixes:
+
+| Symptom | Fix |
+|---|---|
+| `brass-agent: command not found` | Run `npm run build && npm link`, or use `node dist/agent/cli/main.cjs`. |
+| VS Code cannot run the agent | Set `brassAgent.command` to the absolute CLI path. |
+| Context discovery does not find files | Install `ripgrep` and confirm `rg --version` works. |
+| LLM calls use fake provider unexpectedly | Check `brass-agent --doctor` and verify provider env vars. |
+| Writes are rejected in scripts/CI | Use interactive approval locally, or pass `--yes` intentionally. |
+| Patch apply fails | Check `git apply --check` output in the run details; the agent does not force patches. |
+| Secrets appear in repo files | Add globs to `context.excludeGlobs` and keep `redaction.enabled: true`. |
+
+## Safety checklist before dogfooding
+
+Before using `--apply` on a real project:
+
+```txt
+- commit or stash your current work
+- run brass-agent --doctor
+- review .brass-agent.json permissions
+- keep mode=propose as the default
+- use VS Code patch preview or CLI approval before applying changes
+- avoid --yes except for local smoke tests or intentional automation
+```
+
+## Related docs
+
+- [Brass Agent CLI](./agent-cli.md)
+- [Agent init](./agent-init.md)
+- [Agent config and policy files](./agent-config.md)
+- [Agent local install and doctor](./agent-local-install.md)
+- [VS Code local install](./agent-vscode-install.md)
+- [Agent LLM adapters](./agent-llm-adapters.md)
+- [Agent approvals](./agent-approvals.md)
+- [Agent automatic rollback safety](./agent-rollback-safety.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-language-workspace-ux.md

@@ -0,0 +1,99 @@
+# Agent language and workspace setup UX
+
+Brass Agent supports two setup paths:
+
+- **Model setup**: stored by the VS Code extension in Secret Storage.
+- **Workspace setup**: stored in the repository as `.brass-agent.json`.
+
+The VS Code extension exposes both from the Chat view:
+
+```txt
+/model       configure the LLM provider and API keys
+/workspace   create or update .brass-agent.json
+/config      alias for /workspace
+```
+
+## Response language
+
+By default, Brass Agent tries to answer in the same language as the user's latest goal. For example, Spanish prompts should get Spanish explanations.
+
+The behavior can be forced per workspace:
+
+```json
+{
+  "language": {
+    "response": "es"
+  }
+}
+```
+
+Supported values:
+
+```txt
+auto        infer from the latest user goal
+match-user  same intent as auto, explicit in config
+en          English
+es          Spanish
+pt          Portuguese
+fr          French
+de          German
+it          Italian
+custom      custom language name, via language.custom
+```
+
+When Brass Agent is launched from VS Code, the extension can also pass a language preference through the `brassAgent.language.response` setting. Workspace config still remains the best place when a project should consistently answer in one language.
+
+Language policy only affects natural-language responses. Code, identifiers, paths, shell commands, logs, and unified diffs are kept unchanged.
+
+## Create `.brass-agent.json` from VS Code
+
+Use either:
+
+```txt
+Brass Agent: Configure Workspace
+```
+
+or in the Chat view:
+
+```txt
+/workspace
+```
+
+The wizard asks for:
+
+1. response language
+2. validation command behavior
+
+For validation commands, it can:
+
+- auto-discover from `package.json`
+- disable validation commands
+- choose a detected script, such as `npm run repo:check`
+- accept a custom command
+
+When a specific validation command is selected, the extension adds it to:
+
+```json
+{
+  "project": {
+    "validationCommands": ["npm run repo:check"]
+  },
+  "permissions": {
+    "shell": {
+      "allow": ["npm run repo:check"]
+    }
+  }
+}
+```
+
+That means future runs can execute the command through the normal Brass Agent permission pipeline.
+
+## CLI usage
+
+The CLI also accepts a temporary language override:
+
+```bash
+brass-agent --language es "explicame este repo"
+```
+
+This does not modify config. For persistent behavior, use `.brass-agent.json`.