brass-runtime 1.16.0 → 1.17.0

package/docs/agent-vscode-install.md

@@ -0,0 +1,186 @@
+# Installing the VS Code extension locally
+
+> For the end-to-end setup flow, see [Brass Agent install and configure](./agent-install-and-configure.md).
+
+The easiest local path for developing inside the `brass-runtime` checkout is:
+
+```bash
+npm run agent:vscode:install
+```
+
+That builds the CLI, packages the VSIX, installs it into VS Code, and writes a local `.vscode/settings.json` pointing `brassAgent.command` at `dist/agent/cli/main.cjs`.
+
+If you want to use the same agent from many projects, prefer the global-command flow:
+
+```bash
+npm run agent:vscode:install:global
+```
+
+That command links the CLI globally and installs the extension configured to call `brass-agent`. It writes:
+
+```json
+{
+  "brassAgent.command": "brass-agent"
+}
+```
+
+To remove that global setup:
+
+```bash
+npm run agent:vscode:uninstall:global
+```
+
+See [Agent global usage and workspace discovery](./agent-global-usage.md) and [Agent local install and doctor](./agent-local-install.md) for details.
+
+
+The VS Code extension is designed to be installed as a `.vsix` while the project
+is still pre-marketplace.
+
+## Build the CLI first
+
+From the repository root:
+
+```bash
+npm install
+npm run build
+```
+
+This should produce the CLI entrypoint used by the extension:
+
+```txt
+dist/agent/cli/main.cjs
+```
+
+You can either put the `brass-agent` binary on PATH, or configure the extension
+to call this file directly.
+
+## Package the extension
+
+From the extension folder:
+
+```bash
+cd extensions/vscode-brass-agent
+npm install
+npm run compile
+npm run package:vsix
+```
+
+This creates a file like:
+
+```txt
+vscode-brass-agent-0.0.1.vsix
+```
+
+The extension manifest includes `repository`, `homepage`, and `bugs` metadata so
+`vsce` can package it without the missing-repository warning. If you publish from
+a fork, update those fields in `extensions/vscode-brass-agent/package.json` first.
+
+## Install in VS Code
+
+Using the command line:
+
+```bash
+code --install-extension vscode-brass-agent-0.0.1.vsix
+```
+
+Or from VS Code:
+
+```txt
+Extensions view
+  -> Views and More Actions...
+  -> Install from VSIX...
+```
+
+## Configure the CLI path
+
+For local development, point the extension to the built CLI:
+
+```json
+{
+  "brassAgent.command": "/absolute/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```
+
+For a globally installed package, keep the default:
+
+```json
+{
+  "brassAgent.command": "brass-agent"
+}
+```
+
+
+## If the UI is missing or stale
+
+After installing, run:
+
+```txt
+Developer: Reload Window
+```
+
+Then open the Brass Agent activity-bar icon. You should see:
+
+```txt
+Chat
+Run History
+```
+
+If you only see `Run History`, or the toolbar looks like an older build, run:
+
+```bash
+npm run agent:vscode:reinstall
+```
+
+See [VS Code full clean and reinstall](./agent-vscode-clean-install.md).
+
+## Doctor
+
+After installing, run:
+
+```bash
+npm run agent:doctor
+```
+
+or from the VS Code command palette:
+
+```txt
+Brass Agent: Doctor
+```
+
+## Notes
+
+The VS Code extension is a client for the CLI. Installing the extension alone is
+not enough unless `brass-agent` is also available to the editor process.
+
+## 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.
+
+
+## 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).
+
+
+## Configure the model from VS Code
+
+After installing the extension, run `Brass Agent: Configure Model` or `/model` from the Chat view. API keys are stored in VS Code Secret Storage and injected into VS Code-launched agent runs. See [VS Code model setup](./agent-vscode-model-setup.md).
+
+## Node used by the bundled CLI
+
+When the extension uses its bundled CLI, it launches `main.cjs` with `node` by default. If your Node executable has a custom path, set:
+
+```json
+{
+  "brassAgent.nodeCommand": "/absolute/path/to/node"
+}
+```
+
+If `node` cannot be found, the extension falls back to VS Code Electron-as-Node automatically.

package/docs/agent-vscode-model-setup.md

@@ -0,0 +1,97 @@
+# Brass Agent VS Code model setup
+
+The VS Code extension can configure the model used by `brass-agent` without requiring a terminal or a repository-local `.env` file.
+
+## Why configure from VS Code?
+
+When the extension launches the bundled `brass-agent` CLI, it can inject provider environment variables into that child process. This means you can open any workspace and use the Brass Agent Chat without first exporting keys in your shell.
+
+Secrets are stored with VS Code Secret Storage, not in `.brass-agent.json`, `.env`, `settings.json`, or source control. VS Code exposes `ExtensionContext.secrets` for sensitive information; the implementation stores secrets encrypted and does not sync them across machines. [VS Code docs](https://code.visualstudio.com/api/extension-capabilities/common-capabilities)
+
+## First run
+
+Open the Brass Agent sidebar and run:
+
+```txt
+Brass Agent: Configure Model
+```
+
+Or from the Chat view:
+
+```txt
+/model
+```
+
+You can choose:
+
+- **Google / Gemini** — stores a Gemini API key and model name.
+- **OpenAI-compatible** — stores an API key plus endpoint/model settings.
+- **Fake / offline** — no API key; useful for smoke tests and UI testing.
+- **Auto-detect** — lets workspace config/env decide, while still injecting stored VS Code secrets when available.
+
+## Google / Gemini
+
+The extension stores the key in VS Code Secret Storage and passes these variables only to runs launched from VS Code:
+
+```txt
+BRASS_LLM_PROVIDER=google
+GEMINI_API_KEY=<secret>
+GOOGLE_API_KEY=<secret>
+BRASS_GOOGLE_API_KEY=<secret>
+BRASS_GOOGLE_MODEL=gemini-2.5-flash
+```
+
+The key value is not printed in Doctor output and is not written to the workspace.
+
+## OpenAI-compatible
+
+For OpenAI-compatible providers, the extension passes:
+
+```txt
+BRASS_LLM_PROVIDER=openai-compatible
+BRASS_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
+BRASS_LLM_API_KEY=<secret>
+BRASS_LLM_MODEL=gpt-4.1
+```
+
+Use a custom endpoint/model when configuring the provider.
+
+## Doctor
+
+After setup, run:
+
+```txt
+Brass Agent: Doctor
+```
+
+or in Chat:
+
+```txt
+/doctor
+```
+
+Doctor runs through the extension, so it can see secrets stored by the extension. A terminal command like `brass-agent --doctor` will not see VS Code Secret Storage unless the same key is also exported in your shell or configured via `.env`.
+
+## Clearing stored keys
+
+Run:
+
+```txt
+Brass Agent: Configure Model
+```
+
+and choose:
+
+```txt
+Clear stored model secrets
+```
+
+This deletes the keys stored by the Brass Agent extension.
+
+## Recommended daily flow
+
+1. Install/reinstall the extension.
+2. Open any repository in VS Code.
+3. Run `Brass Agent: Configure Model` once.
+4. Run `Brass Agent: Doctor`.
+5. Use `Brass Agent → Chat` with `/inspect`, `/fix-tests`, `/fix-problems`, or natural language.

package/docs/agent-vscode-patch-preview.md

@@ -0,0 +1,92 @@
+# Brass Agent VS Code patch preview
+
+P10 adds the first editor-native write flow for Brass Agent.
+
+The VS Code extension remains a thin client over the CLI. It does not apply
+patches directly and does not duplicate agent semantics.
+
+```txt
+VS Code command
+  -> brass-agent --protocol-json --protocol-full-patches --mode propose
+  -> patch.proposed observation
+  -> VS Code Webview preview
+  -> user clicks Apply Patch
+  -> brass-agent --apply-patch-file <temp.diff> --yes
+  -> PatchService / permissions / validation stay in src/agent
+```
+
+## Why two runs?
+
+The extension first asks the agent to propose a patch. The proposed unified diff
+is shown in a webview. If the user approves that exact diff, the extension writes
+it to a temporary file and asks the CLI to apply that file.
+
+This avoids the unsafe UX of previewing one patch and then asking the LLM to
+regenerate a possibly different patch during apply.
+
+## CLI flags added for editor clients
+
+```bash
+brass-agent --protocol-json --protocol-full-patches "fix the failing tests"
+```
+
+`--protocol-full-patches` keeps patch payloads untruncated while still compacting
+large file contents, prompts, shell output, and LLM responses.
+
+```bash
+brass-agent --apply-patch-file ./approved.diff --yes "apply approved patch"
+```
+
+`--apply-patch-file` supplies a precomputed unified diff to the agent and runs in
+write mode. P13 deliberately disables repair attempts for this exact patch-file path, so the approved diff remains the only diff applied. The diff still flows through:
+
+```txt
+AgentGoal.initialPatch
+  -> decideNextAction
+  -> patch.apply
+  -> PermissionService
+  -> ApprovalService
+  -> PatchService
+  -> git apply --check
+  -> git apply
+  -> validation command discovery
+```
+
+`--patch-file PATH` is the lower-level variant that supplies a patch but respects
+the selected `--mode`. In `propose` mode it records `patch.proposed`; in `write`
+mode it applies through the normal policy path.
+
+## VS Code commands
+
+The extension now contributes:
+
+```txt
+Brass Agent: Propose Fix
+Brass Agent: Apply Fix
+Brass Agent: Inspect Workspace
+Brass Agent: Show Last Patch Preview
+Brass Agent: Show Output
+Brass Agent: Cancel Current Run
+```
+
+`Apply Fix` no longer gives the CLI immediate write permissions. It generates a
+proposal first, then opens the patch preview. The actual apply only happens after
+the user clicks `Apply Patch` in the webview and confirms the modal prompt.
+
+`Show Last Patch Preview` reopens the most recent proposed patch for the current
+extension session.
+
+## Boundary invariant
+
+The extension may render and approve a patch, but the CLI remains the authority
+for applying it.
+
+```txt
+extensions/vscode-brass-agent
+  -> temporary diff file
+  -> brass-agent --apply-patch-file
+  -> src/agent PatchService
+  -> src/core runtime
+```
+
+The extension never shells out to `git apply` directly.

package/docs/agent-vscode-problems.md

@@ -0,0 +1,79 @@
+# VS Code problems-aware chat
+
+P33 teaches the VS Code client to use the editor's current diagnostics as first-class context.
+
+The agent still runs through the normal `brass-agent` CLI boundary. VS Code only gathers diagnostics and includes them in the chat prompt; it does not bypass permissions, approvals, patch preview, rollback, or validation.
+
+## Chat slash commands
+
+The Chat view supports these problem-aware commands:
+
+```txt
+/problems
+/explain-problems
+/fix-problems
+/current-file-problems
+/explain-current-file
+/fix-current-file
+```
+
+Examples:
+
+```txt
+/fix-problems
+```
+
+```txt
+/fix-current-file prefer a minimal patch
+```
+
+`/fix-problems` uses diagnostics from the whole workspace. `/fix-current-file` only uses diagnostics from the active editor.
+
+## Command Palette
+
+The extension also contributes:
+
+```txt
+Brass Agent: Explain Workspace Problems
+Brass Agent: Fix Workspace Problems
+Brass Agent: Fix Current File Problems
+```
+
+These commands open the Chat view with a prompt that includes VS Code diagnostics.
+
+## Context chips
+
+The Chat view shows diagnostic count chips when VS Code has problems available:
+
+```txt
+problems 12
+file problems 3
+```
+
+These counts come from `vscode.languages.getDiagnostics()` and update when diagnostics or the active editor change.
+
+## Configuration
+
+Limit how many diagnostics are included in a prompt:
+
+```json
+{
+  "brassAgent.problemContextLimit": 40
+}
+```
+
+If there are more diagnostics, the prompt includes the first `problemContextLimit` diagnostics and notes how many were omitted.
+
+## Safety
+
+Diagnostics are treated as context only. A problem-aware run still follows:
+
+```txt
+VS Code diagnostics
+  -> Chat prompt
+  -> brass-agent --protocol-json
+  -> PermissionService
+  -> ApprovalService when needed
+  -> Patch preview
+  -> exact patch apply via CLI
+```

package/docs/agent-vscode-project-dashboard.md

@@ -0,0 +1,106 @@
+# VS Code Project Dashboard
+
+P44 adds a **Project** view to the Brass Agent VS Code sidebar.
+
+The dashboard answers the question:
+
+```txt
+What does Brass Agent know about this workspace right now?
+```
+
+It is intentionally read-mostly. The view does not run the full agent loop unless you click **Inspect Workspace**. It uses `brass-agent --doctor --json` plus VS Code settings and workspace config to show a compact readiness summary.
+
+## What it shows
+
+The dashboard shows:
+
+```txt
+Status
+  Ready: ok | warn | fail
+  Workspace path
+  Doctor status
+  Resolved CLI
+
+Model
+  Provider/model
+  Whether a key is configured for VS Code-launched runs
+
+Workspace config
+  .brass-agent.json path, if present
+  Response language
+  Validation command
+  Package manager
+
+Project profile
+  Detected stacks and markers
+  Likely validation command
+  Env file status
+
+Warnings
+  Important doctor warnings/failures
+```
+
+For a mixed workspace, this might look like:
+
+```txt
+Profile: stacks: node, rust, tauri, desktop, bridge, monorepo
+Validation: npm run repo:check
+Model: Google/Gemini (gemini-2.5-flash)
+Language: es
+Config: .brass-agent.json
+```
+
+## Opening it
+
+From the sidebar:
+
+```txt
+Brass Agent → Project
+```
+
+From Command Palette:
+
+```txt
+Brass Agent: Open Project Dashboard
+```
+
+From Chat:
+
+```txt
+/project
+```
+
+## Actions
+
+The Project view includes quick actions:
+
+```txt
+Refresh
+Run Doctor
+Open Chat
+Configure Model
+Configure Workspace
+Open Config
+Inspect Workspace
+Show Output
+```
+
+`Configure Workspace` is the quickest way to create or update `.brass-agent.json` from VS Code. Use it when the dashboard shows no validation command or the wrong language.
+
+## Boundary
+
+The dashboard is still a thin VS Code UI:
+
+```txt
+VS Code Project view
+  -> brass-agent --doctor --json
+  -> VS Code settings / Secret Storage
+  -> .brass-agent.json summary
+```
+
+It does not duplicate project intelligence, patching, permissions, or validation logic. Those remain in the CLI/agent layer.
+
+
+## Larger dashboard layout
+
+Use `Brass Agent: Open Project Dashboard in Editor` to inspect the same dashboard in a wider editor tab. This keeps the sidebar available for Chat or Explorer while reviewing model, validation, config, and project profile details.

package/docs/agent-vscode-run-history.md

@@ -0,0 +1,92 @@
+# VS Code run history
+
+P11 adds a persistent VS Code sidebar for Brass Agent runs.
+
+The extension remains a thin client:
+
+```txt
+brass-agent CLI --protocol-json
+  -> VS Code process runner
+  -> workspace run history
+  -> TreeView / patch preview / rerun commands
+```
+
+The extension does not reimplement planning, permissions, approvals, patch
+application, or validation. Those still live behind the CLI and `src/agent`.
+
+## Sidebar
+
+The extension contributes a `Brass Agent` activity-bar view with a `Runs`
+TreeView.
+
+Each run entry shows:
+
+- goal
+- mode
+- status
+- start time
+- workspace
+- duration
+- step count
+- patch stats when a patch was proposed or applied
+
+Selecting a run opens a Markdown details document. Runs with stored patches can
+reopen the patch preview webview.
+
+## Commands
+
+New commands:
+
+```txt
+Brass Agent: Open Run Details
+Brass Agent: Show History Patch
+Brass Agent: Rerun History Run
+Brass Agent: Refresh History
+Brass Agent: Clear History
+```
+
+The view title includes refresh and clear actions. Run items expose context-menu
+commands for details, patch preview, and rerun.
+
+## Persistence
+
+History is stored in VS Code `workspaceState` under a versioned key. This keeps
+history local to the workspace and avoids adding persistence concerns to the
+runtime or agent core.
+
+Configuration:
+
+```json
+{
+  "brassAgent.historyLimit": 50,
+  "brassAgent.storePatchesInHistory": true
+}
+```
+
+`historyLimit` controls how many runs are retained.
+
+`storePatchesInHistory` controls whether unified diff payloads are stored in VS
+Code workspace storage. Disable it if you do not want patch contents persisted
+by the editor client.
+
+## Rerun behavior
+
+Rerunning a normal run invokes the same goal and mode through the CLI again.
+
+Rerunning an `apply-approved-patch` history entry reapplies the stored patch via
+`brass-agent --apply-patch-file`, preserving the invariant that VS Code never
+applies patches directly.
+
+## Boundary rule
+
+The sidebar is editor state, not agent state.
+
+```txt
+src/core                     no knowledge of VS Code
+src/agent                    no knowledge of VS Code history
+brass-agent CLI protocol     stable boundary
+VS Code extension            client-side history and UX
+```
+
+If a future UX needs richer history, prefer extending the CLI protocol before
+teaching the VS Code extension about internal agent implementation details.