brass-runtime 1.15.0 → 1.16.1

package/docs/agent-config.md

@@ -0,0 +1,480 @@
+# Agent configuration and policy files
+
+> For the end-to-end setup flow, see [Brass Agent install and configure](./agent-install-and-configure.md).
+
+P7 adds a small JSON configuration file for the experimental `brass-agent` CLI.
+The goal is to keep policy out of hardcoded TypeScript while preserving the
+runtime boundary:
+
+```txt
+src/core
+  ↑
+src/agent policy/config
+  ↑
+src/agent/cli loads .brass-agent.json
+```
+
+`src/core` still does not know that the agent exists. The CLI loads config as a
+Node setup step, then passes the resolved policy into `AgentEnv`.
+
+## Discovery
+
+By default, the CLI searches upward from `--cwd` for either file:
+
+```txt
+.brass-agent.json
+brass-agent.config.json
+```
+
+You can force a specific file:
+
+```bash
+brass-agent --config ./agent.policy.json "fix the failing tests"
+```
+
+Or disable config loading entirely:
+
+```bash
+brass-agent --no-config "fix the failing tests"
+```
+
+## Precedence
+
+Configuration is intentionally lower precedence than explicit execution knobs:
+
+```txt
+CLI flags > environment variables > .brass-agent.json > built-in defaults
+```
+
+Examples:
+
+```txt
+--mode write beats config.mode
+--approval deny beats config.approval
+BRASS_LLM_PROVIDER beats config.llm.provider
+BRASS_LLM_MODEL beats config.llm.model
+```
+
+## Minimal config
+
+```json
+{
+  "mode": "propose",
+  "approval": "auto",
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY"
+  }
+}
+```
+
+Do not store API keys in the config file. Use `apiKeyEnv` and keep the secret in
+the environment.
+
+## LLM config
+
+```json
+{
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY",
+    "temperature": 0.2,
+    "maxOutputTokens": 4096
+  }
+}
+```
+
+OpenAI-compatible example:
+
+```json
+{
+  "llm": {
+    "provider": "openai-compatible",
+    "endpoint": "https://api.openai.com/v1/chat/completions",
+    "model": "gpt-4.1",
+    "apiKeyEnv": "BRASS_LLM_API_KEY"
+  }
+}
+```
+
+Offline/fake example:
+
+```json
+{
+  "llm": {
+    "provider": "fake",
+    "fakeResponse": "Fake plan from config"
+  }
+}
+```
+
+## Project command discovery
+
+P8 adds project-aware command discovery. The agent reads `package.json`, checks
+common lockfiles, infers npm/pnpm/yarn/bun, and selects validation commands from
+scripts instead of assuming `npm test`.
+
+Basic example:
+
+```json
+{
+  "project": {
+    "packageManager": "auto",
+    "testScriptNames": ["test", "test:ci", "test:unit"],
+    "includeTypecheck": true,
+    "maxValidationCommands": 2
+  }
+}
+```
+
+Exact validation commands override discovery:
+
+```json
+{
+  "project": {
+    "validationCommands": [
+      "pnpm run test:unit",
+      "pnpm run typecheck"
+    ]
+  }
+}
+```
+
+Use an empty array to disable shell validation:
+
+```json
+{
+  "project": {
+    "validationCommands": []
+  }
+}
+```
+
+Supported `project.packageManager` values are `auto`, `npm`, `pnpm`,
+`yarn`, and `bun`.
+
+See [Agent project command discovery](./agent-project-commands.md).
+
+## Context discovery
+
+P12 adds a bounded context discovery pass before planning. It reads direct files
+mentioned by validation output, searches likely identifiers, and reads a small
+number of matched files before calling the LLM.
+
+```json
+{
+  "context": {
+    "enabled": true,
+    "maxSearchQueries": 3,
+    "maxFiles": 4,
+    "maxSearchResults": 40,
+    "globs": ["*.ts", "*.tsx", "*.json"]
+  }
+}
+```
+
+Disable it when you want the old minimal context behavior:
+
+```json
+{
+  "context": {
+    "enabled": false
+  }
+}
+```
+
+See [Agent context discovery](./agent-context-discovery.md).
+
+## Patch quality loop
+
+P13 adds a bounded repair loop for patches generated by the agent. If a generated patch fails to apply, or if validation still fails after `patch.applied`, the agent can ask the LLM for an incremental repair patch.
+
+```json
+{
+  "patchQuality": {
+    "enabled": true,
+    "maxRepairAttempts": 1
+  }
+}
+```
+
+Set `maxRepairAttempts` to `0` or `enabled` to `false` to keep one-shot apply behavior. Repairs are disabled for exact patch-file runs such as `--apply-patch-file` so the VS Code preview flow still applies exactly the patch the user approved.
+
+See [Agent patch quality loop](./agent-patch-quality-loop.md).
+
+
+## Automatic rollback safety
+
+P14 adds automatic rollback safety for generated patches. After validation fails
+and the patch quality repair budget is exhausted, the agent can reverse-apply
+generated patches through `PatchService.rollback`.
+
+```json
+{
+  "rollback": {
+    "enabled": true,
+    "onFinalValidationFailure": true,
+    "strategy": "all",
+    "maxRollbackDepth": 8,
+    "runValidationAfterRollback": true,
+    "allowForSuppliedPatches": false
+  }
+}
+```
+
+`strategy` can be `last` or `all`. Exact patch-file flows such as
+`--apply-patch-file` are protected by default, so VS Code preview still applies
+exactly the patch the user approved.
+
+See [Agent automatic rollback safety](./agent-rollback-safety.md).
+
+## Batch runs
+
+P21 adds optional default batch goals. The CLI uses `config.batch.goals` only when no explicit goal, `--preset`, `--patch-file`, or `--batch-file` is provided.
+
+```json
+{
+  "batch": {
+    "stopOnFailure": true,
+    "goals": [
+      { "preset": "inspect" },
+      { "preset": "typecheck" },
+      { "preset": "lint" }
+    ]
+  }
+}
+```
+
+See [Agent batch runs](./agent-batch.md).
+
+## Permission config
+
+Shell commands are matched against the command array joined with spaces. Patterns
+support `*` as a simple wildcard.
+
+Built-in safe validation commands remain allowed by default for npm, pnpm, yarn,
+and bun, along with read-only git commands. Examples include:
+
+```txt
+npm test
+npm run test*
+npm run typecheck
+pnpm test
+pnpm run test*
+yarn run lint*
+bun run check
+git status
+git diff
+git log
+```
+
+You can extend them:
+
+```json
+{
+  "permissions": {
+    "shell": {
+      "allow": [
+        "npm run typecheck",
+        "npm run lint",
+        "pnpm test *"
+      ],
+      "ask": [
+        {
+          "pattern": "npm run build",
+          "reason": "Build can be slow; confirm before running it.",
+          "risk": "medium",
+          "defaultAnswer": "approve"
+        }
+      ],
+      "deny": [
+        "rm *",
+        "git push *"
+      ]
+    }
+  }
+}
+```
+
+For a strict allowlist, disable inherited defaults:
+
+```json
+{
+  "permissions": {
+    "shell": {
+      "inheritDefaults": false,
+      "allow": ["npm test"]
+    }
+  }
+}
+```
+
+Deny rules win over ask rules, and ask rules win over allow rules.
+
+## Patch apply policy
+
+`patch.apply` is still denied in `read-only` and `propose` modes. In `write` and
+`autonomous` modes, you can configure the decision:
+
+```json
+{
+  "permissions": {
+    "patchApply": {
+      "decision": "ask",
+      "reason": "Apply the generated diff to the workspace.",
+      "risk": "high",
+      "defaultAnswer": "reject"
+    }
+  }
+}
+```
+
+Short form:
+
+```json
+{
+  "permissions": {
+    "patchApply": "ask"
+  }
+}
+```
+
+Supported values are `allow`, `ask`, and `deny`.
+
+## Tool policy overrides
+
+Tool policies let a project tune timeouts and retries without changing code.
+Keys are `AgentAction.type` strings:
+
+```json
+{
+  "tools": {
+    "fs.readFile": {
+      "timeoutMs": 10000,
+      "retries": 1
+    },
+    "fs.exists": {
+      "timeoutMs": 5000,
+      "retries": 1
+    },
+    "llm.complete": {
+      "timeoutMs": 90000,
+      "retries": 3
+    },
+    "shell.exec": {
+      "timeoutMs": 180000,
+      "retries": 0
+    },
+    "patch.apply": {
+      "timeoutMs": 30000,
+      "retries": 0
+    }
+  }
+}
+```
+
+Retryability is still controlled in code by error class. Config can tune counts
+and timeouts, but it cannot make unsafe errors retryable.
+
+## Full example
+
+```json
+{
+  "mode": "propose",
+  "approval": "auto",
+  "llm": {
+    "provider": "google",
+    "model": "gemini-2.5-flash",
+    "apiKeyEnv": "GEMINI_API_KEY",
+    "temperature": 0.2,
+    "maxOutputTokens": 4096
+  },
+  "project": {
+    "packageManager": "auto",
+    "testScriptNames": ["test", "test:ci", "test:unit"],
+    "includeTypecheck": true,
+    "maxValidationCommands": 2
+  },
+  "patchQuality": {
+    "enabled": true,
+    "maxRepairAttempts": 1
+  },
+  "rollback": {
+    "enabled": true,
+    "strategy": "all",
+    "maxRollbackDepth": 8
+  },
+  "permissions": {
+    "shell": {
+      "inheritDefaults": true,
+      "allow": [
+        "npm run typecheck",
+        "npm run lint"
+      ],
+      "ask": [
+        {
+          "pattern": "npm run build",
+          "reason": "Build may take a while.",
+          "risk": "medium",
+          "defaultAnswer": "approve"
+        }
+      ],
+      "deny": [
+        "git push *",
+        "rm *"
+      ]
+    },
+    "patchApply": {
+      "decision": "ask",
+      "risk": "high",
+      "defaultAnswer": "reject"
+    }
+  },
+  "tools": {
+    "llm.complete": {
+      "timeoutMs": 90000,
+      "retries": 2
+    },
+    "shell.exec": {
+      "timeoutMs": 180000,
+      "retries": 0
+    }
+  }
+}
+```
+
+
+## Context exclude globs
+
+```json
+{
+  "context": {
+    "excludeGlobs": [".env*", "secrets/**", "*.pem", "*.key"]
+  }
+}
+```
+
+These globs reduce what context discovery reads or searches before prompting the LLM.
+
+## Language config
+
+Natural-language responses can match the user's prompt automatically, or be fixed per workspace:
+
+```json
+{
+  "language": {
+    "response": "es"
+  }
+}
+```
+
+Supported values are `auto`, `match-user`, `en`, `es`, `pt`, `fr`, `de`, `it`, and `custom`.
+Use `custom` with `language.custom` for a human-readable language name.
+
+The language policy affects explanations and summaries only. Code, identifiers,
+file paths, shell commands, logs, and unified diffs remain unchanged.
+
+The VS Code extension can create or update this section through **Brass Agent:
+Configure Workspace** or `/workspace` in the Chat view.

package/docs/agent-context-discovery.md

@@ -0,0 +1,159 @@
+# Agent context discovery
+
+P12 adds a small context discovery pass before the first LLM planning call.
+The goal is to give the model the files that are most likely connected to the
+failure, instead of sending only `package.json` and validation output.
+
+The boundary remains unchanged:
+
+```txt
+src/core
+  ↑
+src/agent context discovery
+  ↑
+src/agent/cli config loading
+```
+
+Context discovery is pure agent logic. It inspects existing observations and
+chooses normal `AgentAction` values:
+
+```txt
+fs.searchText
+fs.readFile
+```
+
+It does not bypass `PermissionService`, does not run shell commands directly,
+and does not require changes to the runtime core.
+
+## Flow
+
+Before `llm.complete`, the agent now does this:
+
+```txt
+read package.json
+check package-manager lockfiles
+discover validation commands
+run allowed validation commands
+extract path and identifier signals from goal + validation output
+read direct files mentioned by failures
+search likely identifiers with rg through fs.searchText
+read top matched files
+ask LLM with command + context discovery summary
+```
+
+Examples of signals:
+
+```txt
+src/user/UserService.ts:12:3
+Cannot find name AuthClient
+Expected getUserById to return ...
+```
+
+From those, the agent may read `src/user/UserService.ts`, search for
+`AuthClient`, and read the most relevant matches.
+
+## Defaults
+
+```txt
+enabled: true
+maxSearchQueries: 3
+maxFiles: 4
+maxSearchResults: 40
+globs: TypeScript, JavaScript, JSON, Markdown, YAML files
+```
+
+The step budget was raised to leave room for the extra discovery work.
+
+## Config
+
+You can tune or disable context discovery from `.brass-agent.json`:
+
+```json
+{
+  "context": {
+    "enabled": true,
+    "maxSearchQueries": 3,
+    "maxFiles": 4,
+    "maxSearchResults": 40,
+    "globs": ["*.ts", "*.tsx", "*.json"]
+  }
+}
+```
+
+Disable it entirely:
+
+```json
+{
+  "context": {
+    "enabled": false
+  }
+}
+```
+
+Use smaller budgets for very large repositories:
+
+```json
+{
+  "context": {
+    "maxSearchQueries": 1,
+    "maxFiles": 2
+  }
+}
+```
+
+## Search semantics
+
+The Node filesystem adapter uses ripgrep in fixed-string mode:
+
+```txt
+rg --fixed-strings --line-number --no-heading --max-count 5 ...
+```
+
+This keeps generated searches safe and predictable. Query strings are derived
+from simple path and identifier signals; they are not treated as regexes.
+
+## Prompting
+
+The planning prompt now includes a context summary alongside the project command
+summary:
+
+```txt
+Project commands: ...
+Context discovery: searched queries: ...
+Discovered paths: ...
+Read context files: ...
+```
+
+Large observations are compacted before prompting. Search results are capped in
+prompt context so a broad query cannot flood the model.
+
+## Safety
+
+Context discovery is intentionally bounded:
+
+```txt
+- fixed number of searches
+- fixed number of files read
+- ignored generated/vendor directories
+- workspace-relative paths only
+- no direct shell execution from discovery logic
+```
+
+`fs.searchText` is still interpreted by the configured `FileSystem` service, and
+`fs.readFile` still goes through the same workspace path validation used by other
+agent actions.
+
+
+## Excluding sensitive paths
+
+P17 adds `context.excludeGlobs`. Excluded paths are filtered from direct error-path reads and are also passed to `rg` as negative globs.
+
+```json
+{
+  "context": {
+    "excludeGlobs": [".env*", "secrets/**", "*.pem", "*.key"]
+  }
+}
+```
+
+This is a context-discovery guard. It does not replace redaction, shell permissions, or workspace path validation.