brass-runtime 1.16.0 → 1.17.0

package/docs/agent-copilot-like-dx.md

@@ -0,0 +1,126 @@
+# Brass Agent Copilot-like DX
+
+Brass Agent started as a CLI-first coding agent. That is still the canonical execution surface, but VS Code users should not need to remember flags or switch to a terminal for normal usage.
+
+P29 adds a Copilot-like VS Code surface around the existing CLI protocol.
+
+## Mental model
+
+Brass Agent is not an inline autocomplete engine yet.
+
+It is a task agent:
+
+```txt
+you ask for a goal
+  -> brass-agent inspects the workspace
+  -> runs allowed validation commands
+  -> discovers context
+  -> calls the configured LLM
+  -> proposes a patch
+  -> VS Code previews the exact diff
+  -> you approve before writing
+```
+
+The VS Code chat view makes that flow feel like a normal editor assistant.
+
+## Chat view
+
+Open the Brass Agent activity bar and use the **Chat** view.
+
+You can ask things like:
+
+```txt
+inspect this workspace
+fix the failing tests
+explain the current type errors
+refactor this module to reduce duplication
+add tests for the selected function
+```
+
+The chat has three modes:
+
+| Mode | What it does |
+| --- | --- |
+| Ask | `read-only`; no shell writes, no patch apply |
+| Propose patch | generates a plan and patch preview, but does not write |
+| Apply after preview | still generates a proposal first; writes only after you approve the exact diff |
+
+## Selection-aware commands
+
+Select code in an editor and right-click. Brass Agent contributes:
+
+```txt
+Ask About Selection
+Explain Selection
+Fix Selection
+```
+
+These commands open the chat with a prefilled prompt containing:
+
+```txt
+file path
+language id
+selected code
+```
+
+They do not directly edit the selection. `Fix Selection` asks the agent to generate a workspace patch and then uses the normal patch preview / approval flow.
+
+## Why not inline autocomplete first?
+
+Inline autocomplete is useful for short completions while typing. Brass Agent's strongest path is different:
+
+```txt
+multi-file context
+validation commands
+typed permissions
+patch preview
+rollback safety
+run history
+```
+
+That maps better to chat + code actions than to token-by-token inline completion.
+
+A future inline completion provider can still be added, but it should be a separate lightweight layer for small edits, not the main agent loop.
+
+## Architecture
+
+The boundary remains unchanged:
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI protocol
+  ↑
+VS Code Chat / TreeView / Webview clients
+```
+
+The chat view does not reimplement agent planning, permissions, approvals, context discovery, patch apply, or rollback. It calls:
+
+```bash
+brass-agent --protocol-json --protocol-full-patches --cwd <workspace> <goal>
+```
+
+and renders protocol events.
+
+## Recommended daily flow
+
+1. Open the Brass Agent sidebar.
+2. Use **Chat** for normal questions.
+3. Select code and use **Ask About Selection** or **Fix Selection**.
+4. Review patch previews before applying.
+5. Check **Run History** for past runs, details, patches, and reruns.
+
+## Safety notes
+
+- `Apply after preview` still applies only after exact diff approval.
+- Secrets should live in `.env`, `.env.local`, or `.brass-agent.env`; doctor verifies provider setup.
+- Redaction and context exclude globs still run before LLM prompts.
+- VS Code does not apply patches directly; it delegates back to `brass-agent`.
+
+## P30: sessions and slash commands
+
+The Chat view now stores a workspace-local conversation, supports slash commands such as `/inspect`, `/fix-tests`, `/explain-last`, and `/apply-last`, and composes follow-up goals using the previous run summary, latest validation output, and patch stats.
+
+See [Chat sessions and slash commands](./agent-chat-sessions.md).

package/docs/agent-declarative-optimized-planning.md

@@ -0,0 +1,138 @@
+# Declarative optimized planning roadmap
+
+This note tracks the design goal:
+
+> Keep the user-facing layer declarative and flexible, but internally convert
+> work into optimized plans that execute with batches, compact memory, and the
+> least practical overhead.
+
+## Does Brass Agent do this today?
+
+Partially.
+
+Brass Agent already has several pieces of the model:
+
+- declarative user requests through CLI goals, VS Code chat, presets, and batch
+  files,
+- `AgentAction -> Observation` execution through explicit capabilities,
+- bounded context discovery before planning,
+- compact protocol/events for editor integrations,
+- sequential batch runs for multi-goal workflows,
+- patch quality loops and rollback safety,
+- project intelligence for mixed stacks.
+
+However, the current agent still uses a mostly sequential decision loop. It does
+not yet compile user intent into a first-class optimized plan IR, batch tool
+calls aggressively, maintain a compact long-lived memory model, or minimize
+runtime overhead through cost-aware scheduling.
+
+## What is missing for the full design?
+
+### 1. A first-class plan IR
+
+Introduce an internal representation such as:
+
+```ts
+type AgentPlan = {
+  readonly id: string;
+  readonly goal: string;
+  readonly steps: readonly PlanStep[];
+  readonly budgets: PlanBudgets;
+};
+
+type PlanStep =
+  | { readonly type: "read"; readonly paths: readonly string[] }
+  | { readonly type: "search"; readonly queries: readonly string[] }
+  | { readonly type: "validate"; readonly commands: readonly string[][] }
+  | { readonly type: "llm"; readonly purpose: "plan" | "patch" | "explain" }
+  | { readonly type: "patch"; readonly mode: "propose" | "apply" | "rollback" };
+```
+
+The user keeps writing natural requests, but the agent compiles them into a
+small, inspectable, optimizable plan before execution.
+
+### 2. Plan optimization passes
+
+Before execution, run optimization passes:
+
+- deduplicate repeated reads/searches,
+- merge compatible searches,
+- avoid reading files already in compact memory,
+- skip validation commands that are irrelevant to the goal,
+- cap expensive operations by budget,
+- split independent work into parallel or batched groups.
+
+### 3. Batched tool execution
+
+Add tool-level batching:
+
+- `fs.readFiles(paths)` instead of repeated single reads,
+- `fs.existsMany(paths)` for marker discovery,
+- `search.batch(queries)` with shared `rg` invocation when possible,
+- validation command groups with explicit ordering and concurrency rules.
+
+The public agent API can remain declarative while the executor runs fewer tool
+calls internally.
+
+### 4. Compact memory
+
+Separate memory into layers:
+
+```txt
+working memory     current run, exact observations
+compact memory     summaries, file digests, validation summaries
+persistent memory  optional workspace-local cache, never required
+```
+
+The LLM should receive compact summaries first, exact contents only when needed.
+This reduces token usage, repeated file reads, and noisy follow-up prompts.
+
+### 5. Cost and overhead budgets
+
+Every plan should carry budgets:
+
+```txt
+max tool calls
+max files read
+max bytes read
+max search queries
+max validation commands
+max LLM calls
+max wall-clock time
+```
+
+The planner and executor can then prefer lower-overhead plans and explain when a
+budget prevented more exploration.
+
+### 6. Runtime lanes and scheduling
+
+Use the runtime more directly for optimized execution lanes:
+
+```txt
+FS lane          bounded concurrency
+Search lane      low concurrency, deduped
+LLM lane         strict concurrency, retry/backoff
+Validation lane  serial by default
+Patch lane       exclusive
+```
+
+This matches the original brass-runtime idea: a coding agent is a concurrent,
+cancelable, observable effect program.
+
+## Suggested implementation path
+
+1. `P49`: introduce `AgentPlan` and log/preview plans without changing behavior.
+2. `P50`: compile current `decideNextAction` flow into a simple sequential plan.
+3. `P51`: add plan optimization passes for dedupe and budget caps.
+4. `P52`: add batched FS/exists/search tools.
+5. `P53`: add compact memory summaries for files, validation output, and patches.
+6. `P54`: add lane-based executor with bounded concurrency.
+7. `P55`: expose a VS Code “Plan Preview” so users can see what the agent is
+   about to do before it runs.
+
+## Short answer
+
+Brass Agent currently supports the declarative UX and some compact/batch pieces,
+but it is not yet a fully optimized internal planner. To get there, the next big
+step is to introduce a first-class `AgentPlan` IR and then optimize/execute that
+plan with batching, compact memory, budgets, and runtime lanes.

package/docs/agent-dx.md

@@ -0,0 +1,224 @@
+# Brass Agent DX surfaces
+
+This document defines how `brass-agent` should be exposed to developers without
+letting UI concerns leak into the runtime or agent core.
+
+## Decision
+
+Start with a strong CLI and make editor integrations thin clients over a stable
+machine protocol.
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI
+  ↑
+VS Code / other IDE clients
+```
+
+The VS Code extension should not reimplement the agent loop. It should call the
+CLI with `--protocol-json`, parse JSON Lines, and render the run in editor UI.
+
+## Why CLI-first
+
+The CLI is the canonical developer surface because it is:
+
+- easy to run in any repo
+- easy to use in CI and smoke tests
+- easy to debug with `--json` and `--protocol-json`
+- independent of a particular editor
+- the best place to stabilize permissions, approvals, config, and event output
+
+The CLI remains thin. It wires Node capabilities, config, approvals, LLM adapters,
+and output formatting around `runAgent(...)`.
+
+## Why the VS Code extension is a thin client
+
+The extension should use VS Code for editor-native UX:
+
+- Command Palette commands
+- workspace folder discovery
+- input boxes for goals
+- modal confirmation before write/apply runs
+- output channel rendering
+- cancellation from VS Code progress UI
+- status bar updates
+
+But the extension should not own:
+
+- planning logic
+- tool policy
+- approvals semantics
+- patch extraction/application
+- project command discovery
+- LLM adapter behavior
+
+Those stay in `src/agent` and the CLI.
+
+## Protocol
+
+Use:
+
+```bash
+brass-agent --protocol-json "fix the failing tests"
+```
+
+The CLI prints newline-delimited protocol messages:
+
+```jsonl
+{"protocol":"brass-agent","version":1,"type":"event","event":{"type":"agent.run.started"}}
+{"protocol":"brass-agent","version":1,"type":"event","event":{"type":"agent.action.started"}}
+{"protocol":"brass-agent","version":1,"type":"final-state","state":{"phase":"done"}}
+```
+
+`--events-json` remains useful for quick event-only streams. Integrations should
+prefer `--protocol-json` because it includes both events and the final compact
+state.
+
+## Current VS Code scaffold
+
+The first extension scaffold lives in:
+
+```txt
+extensions/vscode-brass-agent/
+```
+
+It contributes commands:
+
+```txt
+Brass Agent: Propose Fix
+Brass Agent: Apply Fix
+Brass Agent: Inspect Workspace
+Brass Agent: Show Output
+Brass Agent: Cancel Current Run
+```
+
+The extension invokes the configured CLI command, defaulting to:
+
+```txt
+brass-agent
+```
+
+Settings:
+
+```json
+{
+  "brassAgent.command": "brass-agent",
+  "brassAgent.extraArgs": [],
+  "brassAgent.environment": {}
+}
+```
+
+Development:
+
+```bash
+cd extensions/vscode-brass-agent
+npm install
+npm run compile
+```
+
+Then open the extension folder in VS Code and run the Extension Development Host.
+
+## Apply behavior
+
+The VS Code `Apply Fix` command intentionally asks for one editor-level
+confirmation before launching the CLI with:
+
+```bash
+brass-agent --protocol-json --apply --yes ...
+```
+
+That means the agent can apply a valid patch only after the user confirms in VS
+Code. Deeper per-action approvals can be added later by extending the protocol
+with request/response messages, but the first scaffold keeps the extension simple
+and safe.
+
+## Future DX slices
+
+Recommended next DX slices:
+
+1. Rich sidebar TreeView for run history and current actions.
+2. Webview panel for patch preview and approval.
+3. Chat Participant integration so users can invoke `@brass` from VS Code chat.
+4. Language Model Tool integration so VS Code/Copilot agent mode can call Brass tools.
+5. Import-mode extension that calls `runAgent(...)` directly with VS Code-native
+   file system, terminal, and approval services.
+
+The invariant stays the same: editor integrations are consumers of the agent,
+not owners of the agent semantics.
+
+## P10: VS Code patch preview
+
+The VS Code extension now previews proposed diffs in a webview before applying
+anything. The apply path uses a second CLI invocation with `--apply-patch-file`,
+so the extension never applies patches itself. P13 patch repair is disabled for this exact apply path, preserving preview approval semantics.
+
+```txt
+propose run -> patch.proposed -> webview preview -> approve -> apply supplied patch
+```
+
+For trusted local clients, `--protocol-full-patches` keeps only patch payloads
+untruncated in protocol output.
+
+## P11: VS Code run history
+
+The VS Code extension now contributes a `Brass Agent` activity-bar view with a
+persistent `Runs` TreeView. The view stores compact run metadata in VS Code
+`workspaceState`, can reopen stored patch previews, can rerun previous goals,
+and can clear history for the current workspace.
+
+This remains client-side UX over the CLI protocol. The runtime and agent core do
+not know about VS Code, TreeViews, or editor persistence.
+
+## VS Code batch runner
+
+The VS Code extension can run batch files through the same CLI protocol boundary:
+
+```txt
+VS Code
+  -> brass-agent --protocol-json --protocol-full-patches --batch-file <file>
+  -> protocol events / final states / batch summary
+  -> sidebar history parent with child runs
+```
+
+This keeps batching in the CLI and keeps the extension as a UI client. See
+[VS Code batch runner](./agent-vscode-batch-runner.md).
+
+## P23: local install and doctor
+
+CI/release automation is intentionally deferred. The current DX path is local:
+
+```bash
+npm run agent:vscode:install
+npm run agent:doctor
+```
+
+The VS Code extension also exposes:
+
+```txt
+Brass Agent: Doctor
+```
+
+This keeps the workflow human-driven while the CLI, protocol, VS Code client,
+configuration, and safety model continue to stabilize.
+
+## 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.
+
+## Copilot-like chat surface
+
+See [Copilot-like VS Code DX](./agent-copilot-like-dx.md) for the chat view, selection-aware commands, and why Brass Agent uses chat/code actions before inline autocomplete.
+
+## P30: chat sessions
+
+The VS Code chat view now persists a lightweight workspace-local session, supports slash commands, and composes follow-up prompts from the last run summary, validation output, and patch stats. See [Chat sessions and slash commands](./agent-chat-sessions.md).

package/docs/agent-env-files.md

@@ -0,0 +1,126 @@
+# Brass Agent env files
+
+`brass-agent` can read local environment files for agent-specific variables.
+This is useful for VS Code and local dogfooding because editor-launched commands do
+not always inherit the same shell environment as your terminal.
+
+## Load order
+
+By default, the CLI checks these files in `--cwd`:
+
+```txt
+.brass-agent.env
+.env.local
+.env
+```
+
+All existing files are parsed in that order. Exported shell variables win: the
+loader never overwrites keys that are already present in `process.env`.
+
+To load a specific file:
+
+```bash
+brass-agent --env-file .env --doctor
+```
+
+To disable env-file loading completely:
+
+```bash
+brass-agent --no-env-file --doctor
+```
+
+## What gets loaded
+
+For safety, the loader only imports known Brass Agent keys, plus the custom
+`config.llm.apiKeyEnv` key when configured. Other application secrets in `.env`
+are ignored and are not copied into `process.env` by the loader.
+
+Supported built-in keys include:
+
+```txt
+BRASS_LLM_PROVIDER
+BRASS_FAKE_LLM_RESPONSE
+
+GEMINI_API_KEY
+GOOGLE_API_KEY
+BRASS_GOOGLE_API_KEY
+BRASS_GOOGLE_MODEL
+BRASS_GOOGLE_API_VERSION
+BRASS_GOOGLE_BASE_URL
+BRASS_GOOGLE_ENDPOINT
+BRASS_GOOGLE_SYSTEM_INSTRUCTION
+BRASS_GOOGLE_TEMPERATURE
+BRASS_GOOGLE_TOP_P
+BRASS_GOOGLE_TOP_K
+BRASS_GOOGLE_MAX_OUTPUT_TOKENS
+
+BRASS_LLM_ENDPOINT
+BRASS_LLM_API_KEY
+BRASS_LLM_MODEL
+
+BRASS_AGENT_APPROVAL
+BRASS_AGENT_AUTO_APPROVE
+BRASS_CODE_CMD
+```
+
+The doctor prints key names only, never values.
+
+## Google / Gemini example
+
+`.brass-agent.json`:
+
+```json
+{
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY"
+  }
+}
+```
+
+`.env` or `.brass-agent.env`:
+
+```bash
+BRASS_LLM_PROVIDER=google
+GEMINI_API_KEY=...
+BRASS_GOOGLE_MODEL=gemini-2.5-flash
+```
+
+Then:
+
+```bash
+brass-agent --doctor
+```
+
+Expected doctor output includes:
+
+```txt
+✓ Agent env file: Loaded ... keys: BRASS_LLM_PROVIDER, GEMINI_API_KEY, BRASS_GOOGLE_MODEL
+✓ LLM provider: Google/Gemini provider is configured (google).
+```
+
+## Why `.env` alone used to fail
+
+A shell does not automatically export variables from a `.env` file. Before the
+env-file loader, this worked only when you did something like:
+
+```bash
+set -a
+source .env
+set +a
+brass-agent --doctor
+```
+
+With the loader, keeping agent keys in `.env` or `.brass-agent.env` is enough for
+the CLI and VS Code extension.
+
+## Safety notes
+
+- Do not commit real API keys.
+- Prefer `.brass-agent.env` when you want to keep agent credentials separate from
+  app/runtime `.env` files.
+- The loader ignores non-agent keys in `.env` so app secrets are not imported
+  just because the agent is running.
+- If a key was exposed publicly or pasted into a chat/log, revoke it and create a
+  new one.

package/docs/agent-follow-up-context.md

@@ -0,0 +1,43 @@
+# Brass Agent follow-up context
+
+Brass Agent chat keeps a lightweight memory of the last run so the user can ask follow-up questions such as:
+
+```text
+why did that fail?
+try again but keep the public API unchanged
+explain the last patch
+```
+
+Follow-up context is intentionally gated. Slash commands such as `/inspect`, `/fix-tests`, `/typecheck`, and `/lint` start from a clean request instead of automatically embedding the previous run summary. This prevents a repeated `/inspect` from re-sending an old inspection summary as if it were the current request.
+
+The chat only includes previous run context when one of these is true:
+
+- the command explicitly asks for previous context, such as `/explain-last` or patch actions;
+- the prompt looks like a follow-up, for example “why did that fail?” or “try again”;
+- the caller explicitly forces context for a specific integration flow.
+
+When context is included, the extension compactly sends:
+
+- previous goal;
+- previous mode/status;
+- a truncated previous summary;
+- a truncated error or validation output;
+- patch stats, and optionally the last patch diff when requested.
+
+This keeps model prompts smaller and avoids polluting context discovery with generic words from previous summaries.
+
+## LLM errors
+
+If the model call fails, Brass Agent now surfaces the underlying provider message when available. Instead of only showing:
+
+```text
+Agent stopped with LLMError.
+```
+
+it reports a more actionable summary such as:
+
+```text
+Agent stopped because the model call failed: Google Gemini request failed with 429: ...
+```
+
+Secrets are still passed through the agent redaction layer before appearing in summaries.