brass-runtime 1.16.0 → 1.17.0

package/docs/agent-vscode-auto-discovery.md

@@ -0,0 +1,137 @@
+# VS Code auto-discovery for `brass-agent`
+
+The VS Code extension can now run Brass Agent from any workspace without requiring you to manually set an absolute CLI path in each repo.
+
+The recommended setting is:
+
+```json
+{
+  "brassAgent.command": "auto",
+  "brassAgent.preferBundledCli": true
+}
+```
+
+With `auto`, the extension resolves the CLI in this order:
+
+1. `BRASS_AGENT_COMMAND`, if set in the VS Code extension host environment.
+2. The CLI bundled inside the installed VSIX, when available.
+3. `node_modules/.bin/brass-agent` inside the current workspace.
+4. A nearby `brass-runtime` checkout with `dist/agent/cli/main.cjs`, useful for extension development.
+5. `brass-agent` from `PATH` as a fallback.
+
+When the resolved CLI is a JavaScript entrypoint such as `main.cjs`, the extension prefers launching it with `node`. If `node` is not discoverable, it falls back to VS Code Electron-as-Node with `ELECTRON_RUN_AS_NODE=1`.
+
+The extension still passes `--cwd <workspace>` to the CLI. The CLI then runs its own workspace discovery, so you can open any repo or package folder and the agent will resolve the actual workspace root.
+
+## Install flow
+
+From the `brass-runtime` checkout:
+
+```bash
+npm run agent:vscode:install
+```
+
+That flow now:
+
+```txt
+builds the root CLI
+bundles dist/ into the VS Code extension
+packages the VSIX
+installs the VSIX
+writes brassAgent.command = auto
+```
+
+After installation:
+
+```txt
+Developer: Reload Window
+Brass Agent -> Chat
+/inspect
+```
+
+## Use in any repo
+
+Open any project in VS Code and use the Brass Agent sidebar:
+
+```txt
+Brass Agent -> Chat -> /inspect
+Brass Agent -> Chat -> /fix-tests
+Brass Agent -> Chat -> /fix-problems
+```
+
+No terminal setup is required as long as the extension has a bundled CLI.
+
+## Configure from VS Code
+
+Use:
+
+```txt
+Brass Agent: Configure CLI
+```
+
+Options:
+
+```txt
+Auto-discover CLI
+Prefer bundled CLI
+Use global brass-agent
+Select CLI file...
+Show resolved CLI
+```
+
+If you want to force a global command:
+
+```json
+{
+  "brassAgent.command": "brass-agent",
+  "brassAgent.preferBundledCli": false
+}
+```
+
+If you want to force a local checkout:
+
+```json
+{
+  "brassAgent.command": "/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```
+
+## Debugging
+
+Open the Output panel:
+
+```txt
+Brass Agent: Show Output
+```
+
+Each run logs the resolved CLI, for example:
+
+```txt
+CLI: node /home/me/.vscode/extensions/.../bundled/dist/agent/cli/main.cjs (bundled VS Code extension CLI)
+```
+
+You can also run:
+
+```txt
+Brass Agent: Doctor
+```
+
+or:
+
+```txt
+Brass Agent: Configure CLI -> Show resolved CLI
+```
+
+## Node command
+
+If your Node binary is not named `node`, configure it from VS Code settings:
+
+```json
+{
+  "brassAgent.nodeCommand": "/absolute/path/to/node"
+}
+```
+
+This only affects JavaScript CLI entrypoints bundled with the extension or selected manually. Global commands such as `brass-agent` still run directly.
+
+When the extension launches the CLI, it passes `BRASS_AGENT_VSCODE_EXTENSION=1` and `BRASS_AGENT_VSCODE_CLI_SOURCE` so `brass-agent --doctor` can explain that no workspace-level `brassAgent.command` setting is required.

package/docs/agent-vscode-batch-runner.md

@@ -0,0 +1,100 @@
+# VS Code batch runner
+
+P22 adds a VS Code surface for Brass Agent batch runs.
+
+The extension remains a thin client:
+
+```txt
+VS Code command
+  -> brass-agent --protocol-json --batch-file ...
+  -> protocol JSON Lines
+  -> OutputChannel progress
+  -> Runs TreeView history
+```
+
+The extension does not interpret batch policy, approvals, validation, patches, or
+rollback rules. Those remain inside `brass-agent` and `src/agent`.
+
+## Commands
+
+The extension contributes two batch commands:
+
+- `Brass Agent: Run Batch File`
+- `Brass Agent: Run Configured Batch`
+
+`Run Batch File` opens a VS Code file picker and passes the selected file to the
+CLI:
+
+```bash
+brass-agent --protocol-json --protocol-full-patches --cwd <workspace> --batch-file <file>
+```
+
+`Run Configured Batch` runs the workspace config batch, if the project has one:
+
+```json
+{
+  "batch": {
+    "stopOnFailure": true,
+    "goals": [
+      { "preset": "inspect" },
+      { "preset": "typecheck" },
+      { "preset": "lint" },
+      { "preset": "fix-tests", "mode": "propose" }
+    ]
+  }
+}
+```
+
+## History representation
+
+Batch runs are stored as a parent run in the `Brass Agent` activity-bar view.
+Each `final-state` message emitted by the CLI becomes a child run under that
+batch entry.
+
+```txt
+Brass Agent
+  Runs
+    ✓ batch: brass-agent.batch.json
+      ✓ inspect this workspace
+      ✓ run typecheck discovery and fix type errors if possible
+      ! run lint discovery and fix lint errors if possible
+      Batch completed: 3/4
+      Batch failed: 1
+```
+
+Child runs can still expose summaries, errors, patches, and details using the
+same run-history UI from P11.
+
+## Rerun behavior
+
+Rerunning a batch history entry launches the batch again:
+
+- batch entries created from a file rerun the same file path
+- configured-batch entries rerun the current workspace config batch
+
+As with every other VS Code flow, the editor does not execute agent logic
+directly. It always calls the CLI protocol boundary.
+
+## Packaging the extension
+
+From the extension folder:
+
+```bash
+cd extensions/vscode-brass-agent
+npm install
+npm run compile
+npm run package:vsix
+```
+
+That creates a `.vsix` file that can be installed locally in VS Code.
+
+The extension expects the `brass-agent` CLI to be available on PATH, or for the
+workspace/user setting `brassAgent.command` to point to the built CLI.
+
+Example local setting:
+
+```json
+{
+  "brassAgent.command": "/absolute/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```

package/docs/agent-vscode-chat-layout.md

@@ -0,0 +1,90 @@
+# VS Code Chat layout / focus mode
+
+Brass Agent can run in two VS Code layouts:
+
+- **Sidebar chat** — compact, good for quick prompts and slash commands.
+- **Editor chat** — larger focus-mode webview tab, good for long sessions, patch review follow-ups, or keeping code visible in another editor group.
+
+The agent logic is the same in both layouts. Both surfaces share the same chat session, last run context, last patch preview, model configuration, and slash commands.
+
+## Open chat in the editor
+
+From VS Code:
+
+```txt
+Brass Agent: Open Chat in Editor
+```
+
+Or from the Chat view:
+
+```txt
+/focus
+```
+
+You can also use the **Open in editor** button in the Chat header.
+
+The editor chat opens as a normal editor tab, so you can move it between editor groups, split it beside code, or keep it open while the left sidebar shows Explorer.
+
+## Recommended layout
+
+A comfortable layout is:
+
+```txt
+Left sidebar:
+  Explorer
+
+Editor area:
+  Code tab + Brass Agent Chat tab / split group
+
+Bottom panel:
+  Terminal, Problems, Output
+
+Brass Agent sidebar:
+  Project and Run History collapsed unless needed
+```
+
+This avoids stacking Project, Chat, and Run History in one narrow sidebar.
+
+## Make editor chat the default
+
+You can make `Brass Agent: Open Chat` and selection/code-action flows open the larger editor chat by default:
+
+```json
+{
+  "brassAgent.chat.defaultLocation": "editor"
+}
+```
+
+Use `sidebar` to keep the previous behavior:
+
+```json
+{
+  "brassAgent.chat.defaultLocation": "sidebar"
+}
+```
+
+## Project dashboard in the editor
+
+The Project dashboard can also open as a larger editor tab:
+
+```txt
+Brass Agent: Open Project Dashboard in Editor
+```
+
+This is useful when inspecting a repo profile, validation command, model state, and warnings without compressing the Chat view.
+
+## Focus Chat Layout
+
+`Brass Agent: Focus Chat Layout` opens the editor chat and focuses the editor group. It is a quick way to move from the sidebar into a larger working area.
+
+## Safety
+
+Changing the layout does not change agent behavior:
+
+```txt
+VS Code UI
+  -> brass-agent CLI protocol
+  -> permissions / approvals / patch preview / apply / rollback
+```
+
+The extension still does not apply patches directly. Apply and rollback continue to go through the `brass-agent` CLI.

package/docs/agent-vscode-clean-install.md

@@ -0,0 +1,147 @@
+# VS Code full clean and reinstall
+
+Use this when the Brass Agent sidebar looks stale, the Chat view is missing, or
+VS Code still shows an older extension after rebuilding.
+
+## Where the UI is
+
+After installing the extension, reload VS Code:
+
+```txt
+Developer: Reload Window
+```
+
+Then open the Brass Agent activity-bar icon.
+
+The expected layout is:
+
+```txt
+Brass Agent
+  Chat
+  Run History
+```
+
+If you only see `Run History`, or the toolbar still looks like an older build,
+you are probably running an old VSIX. Do a full clean reinstall.
+
+You can also open the chat directly from the Command Palette:
+
+```txt
+Brass Agent: Open Chat
+```
+
+## Full clean reinstall
+
+From the repository root:
+
+```bash
+npm run agent:vscode:reinstall
+```
+
+That runs:
+
+```txt
+agent:vscode:clean
+agent:vscode:install
+```
+
+Then reload VS Code again:
+
+```txt
+Developer: Reload Window
+```
+
+## Clean only
+
+```bash
+npm run agent:vscode:clean
+```
+
+This removes:
+
+```txt
+- the installed VS Code extension
+- installed extension folders under ~/.vscode*/extensions when present
+- VS Code globalStorage for the extension when present
+- generated .vsix files
+- brassAgent.* keys from workspace .vscode/settings.json
+```
+
+It intentionally keeps the root build output and source files.
+
+## Uninstall only
+
+```bash
+npm run agent:vscode:uninstall
+```
+
+This only asks VS Code to uninstall the extension. It does not delete generated
+VSIX packages, workspace settings, or extension storage.
+
+## Global uninstall
+
+If you installed the extension in global-command mode:
+
+```bash
+npm run agent:vscode:install:global
+```
+
+use the matching global uninstall:
+
+```bash
+npm run agent:vscode:uninstall:global
+```
+
+That runs the VS Code clean flow and then removes the global `brass-runtime` npm link/install, so `brass-agent` should no longer resolve from `PATH`.
+
+For a full clean reinstall in global-command mode:
+
+```bash
+npm run agent:vscode:reinstall:global
+```
+
+## Preview the cleanup
+
+```bash
+node scripts/clean-vscode-extension.mjs --dry-run
+```
+
+The script refuses destructive file deletion unless you pass `--yes`; the npm
+scripts include `--yes` because they are explicit clean/uninstall scripts.
+
+## Useful variants
+
+Clean a different workspace settings file:
+
+```bash
+node scripts/clean-vscode-extension.mjs --yes --workspace ../other-project
+```
+
+Use VS Code Insiders:
+
+```bash
+node scripts/clean-vscode-extension.mjs --yes --code code-insiders
+node scripts/install-vscode-extension.mjs --code code-insiders
+```
+
+Delete the compiled extension output too:
+
+```bash
+node scripts/clean-vscode-extension.mjs --yes --extension-build
+```
+
+## After reinstall
+
+Run:
+
+```txt
+Brass Agent: Doctor
+```
+
+Then try:
+
+```txt
+Brass Agent: Open Chat
+/help
+/inspect
+```

package/docs/agent-vscode-code-actions.md

@@ -0,0 +1,70 @@
+# VS Code Code Actions / Lightbulb
+
+Brass Agent can expose native VS Code code actions so common workflows are available from the editor lightbulb and Quick Fix menu.
+
+This keeps the editor UX closer to Copilot-style usage without changing the architecture:
+
+```txt
+VS Code CodeAction
+  -> Brass Agent Chat draft
+  -> brass-agent CLI protocol
+  -> patch preview / approval
+```
+
+The extension still does not apply patches directly.
+
+## Problem actions
+
+When VS Code reports diagnostics for the current range, the lightbulb can show:
+
+```txt
+Fix problem with Brass Agent
+Explain problem with Brass Agent
+```
+
+These actions open the Brass Agent Chat with a prompt containing:
+
+```txt
+file path
+language id
+range
+diagnostics
+relevant code snippet
+```
+
+`Fix problem` uses apply-after-preview mode, so any generated diff is shown before it can be applied.
+
+## Selection actions
+
+When text is selected, the lightbulb can show:
+
+```txt
+Explain selection with Brass Agent
+Fix selection with Brass Agent
+Refactor selection with Brass Agent
+Generate tests with Brass Agent
+```
+
+These actions prefill the Chat view with the selected code and an appropriate task.
+
+## Slash commands still work
+
+The Chat view still supports:
+
+```txt
+/inspect
+/fix-tests
+/typecheck
+/lint
+/explain-last
+/apply-last
+/rollback-last
+```
+
+Use code actions for local editor context, and slash commands for workspace-level tasks.
+
+## Notes
+
+- Code actions are registered for `file` documents.
+- Patch application remains mediated by `brass-agent`.
+- Problem actions depend on diagnostics from installed language extensions, such as TypeScript or ESLint.

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

@@ -0,0 +1,45 @@
+# VS Code enhanced diff preview
+
+P35 improves the patch preview Webview used by Brass Agent.
+
+The extension still does not apply patches directly. The Webview is only a review and approval surface; applying still goes through `brass-agent --apply-patch-file`.
+
+## What the preview shows
+
+The preview now groups unified diffs by file and shows:
+
+```txt
+file count
+added / removed lines
+per-file hunks
+per-file patch sections
+```
+
+Each file section can be expanded or collapsed.
+
+## Actions
+
+The preview supports:
+
+```txt
+Apply Patch
+Copy Full Patch
+Collapse All
+Expand All
+Open file
+Copy file patch
+Close
+```
+
+`Open file` resolves the path inside the workspace before opening it. Paths outside the workspace are rejected.
+
+## Safety
+
+The apply flow is unchanged:
+
+```txt
+Patch Preview
+  -> user approves exact diff
+  -> brass-agent --apply-patch-file <temp.diff> --yes
+  -> PermissionService / PatchService / git apply --check / git apply
+```

package/docs/agent-vscode-inline-assist.md

@@ -0,0 +1,56 @@
+# VS Code Inline Assist
+
+P34 adds a lightweight Inline Assist flow for editor-first usage.
+
+It is not ghost-text autocomplete. It is a quick editor command that uses the current selection, or a configurable number of surrounding lines around the cursor, and opens the Brass Agent Chat with a focused prompt.
+
+## Command
+
+```txt
+Brass Agent: Inline Assist...
+```
+
+You can also access it from the editor context menu.
+
+## Available intents
+
+Inline Assist offers:
+
+```txt
+Ask about this code
+Explain this code
+Fix this code
+Refactor this code
+Generate tests
+Custom instruction...
+```
+
+Read-only intents open the Chat in Ask mode. Patch-producing intents open the Chat in apply-after-preview mode, so any diff still goes through patch preview and exact apply via `brass-agent`.
+
+## Selection vs cursor context
+
+If text is selected, Inline Assist includes that exact selection.
+
+If there is no selection, it includes surrounding lines around the cursor.
+
+Configure the number of surrounding lines:
+
+```json
+{
+  "brassAgent.inlineAssistSurroundingLines": 20
+}
+```
+
+Set it to `0` to include only the current line when there is no selection.
+
+## Safety
+
+Inline Assist does not edit files directly. The flow is:
+
+```txt
+editor selection/cursor context
+  -> Chat draft
+  -> brass-agent run
+  -> patch preview if any
+  -> exact patch apply via CLI only after approval
+```