brass-runtime 1.15.0 → 1.16.1

package/docs/agent-project-commands.md

@@ -0,0 +1,237 @@
+# Agent project command discovery
+
+P8 makes the experimental `brass-agent` project-aware enough to stop assuming
+`npm test` for every workspace.
+
+The agent still follows the same boundary rule:
+
+```txt
+src/core
+  ↑
+src/agent project command discovery
+  ↑
+src/agent/cli config loading
+```
+
+Command discovery is pure agent logic. It reads observations such as
+`package.json` and lockfile existence, then chooses `AgentAction` values. The
+runtime core does not know about JavaScript package managers.
+
+## Discovery flow
+
+Before planning, the agent now does this:
+
+```txt
+read package.json
+check pnpm-lock.yaml
+check yarn.lock
+check bun.lockb
+check bun.lock
+check package-lock.json
+check npm-shrinkwrap.json
+discover validation commands
+run discovered validation commands when allowed
+run bounded context discovery
+ask LLM with command-discovery and context-discovery summaries
+```
+
+In `read-only` mode, it still reads/checks files and asks the LLM, but it does
+not run shell validation.
+
+## Package manager inference
+
+The package manager is selected in this order:
+
+```txt
+config.project.packageManager, when set to npm/pnpm/yarn/bun
+package.json packageManager field
+lockfiles
+npm fallback
+```
+
+Lockfiles map as follows:
+
+```txt
+pnpm-lock.yaml        -> pnpm
+yarn.lock             -> yarn
+bun.lockb / bun.lock  -> bun
+package-lock.json     -> npm
+npm-shrinkwrap.json   -> npm
+```
+
+## Validation command discovery
+
+If `config.project.validationCommands` is present, the agent uses those exact
+commands and skips script discovery.
+
+Otherwise, it parses `package.json.scripts` and selects up to two validation
+commands by default:
+
+```txt
+1. first usable test script from test, test:ci, test:unit
+2. typecheck/check script when the goal mentions types, or when no test exists
+3. lint script when the goal mentions lint, or when no other validation exists
+```
+
+The default `test` script generated by `npm init` is skipped:
+
+```json
+{
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}
+```
+
+## Package-manager-specific commands
+
+Script names are converted to command arrays:
+
+```txt
+npm  test       -> npm test
+npm  typecheck  -> npm run typecheck
+pnpm test       -> pnpm test
+pnpm typecheck  -> pnpm run typecheck
+yarn test       -> yarn test
+yarn typecheck  -> yarn run typecheck
+bun  test       -> bun run test
+bun  typecheck  -> bun run typecheck
+```
+
+The shell still executes command arrays with `shell: false`; this avoids
+smuggling arbitrary shell syntax through discovered commands.
+
+## Config examples
+
+Force a package manager:
+
+```json
+{
+  "project": {
+    "packageManager": "pnpm"
+  }
+}
+```
+
+Use exact validation commands:
+
+```json
+{
+  "project": {
+    "validationCommands": [
+      "pnpm run test:unit",
+      "pnpm run typecheck"
+    ]
+  }
+}
+```
+
+Prefer custom test script names:
+
+```json
+{
+  "project": {
+    "testScriptNames": ["test:unit", "test:ci", "test"],
+    "includeTypecheck": true,
+    "maxValidationCommands": 2
+  }
+}
+```
+
+Disable validation commands explicitly:
+
+```json
+{
+  "project": {
+    "validationCommands": []
+  }
+}
+```
+
+That lets the agent read context and ask the LLM without running package scripts.
+
+## Permission interaction
+
+Discovery does not bypass `PermissionService`.
+
+Every discovered command still goes through:
+
+```txt
+AgentAction(shell.exec)
+  -> PermissionService
+  -> ApprovalService when ask
+  -> ToolPolicy
+  -> Async shell tool
+  -> Observation(shell.result)
+```
+
+P8 expands the built-in safe shell patterns to cover common validation scripts
+for npm, pnpm, yarn, and bun, such as:
+
+```txt
+npm run test*
+pnpm run typecheck
+yarn run lint*
+bun run check
+```
+
+Projects can still tighten this with:
+
+```json
+{
+  "permissions": {
+    "shell": {
+      "inheritDefaults": false,
+      "allow": ["pnpm run test:unit"]
+    }
+  }
+}
+```
+
+## After apply
+
+When `--apply` / `write` mode successfully applies a patch, the agent reruns the
+same discovered validation commands after `patch.applied`.
+
+The completion summary includes the package manager, selected commands, and the
+post-apply exit codes.
+
+## P43 health/check script discovery
+
+P43 extends this beyond conventional `test` / `typecheck` / `lint` scripts.
+When no usable test script exists, the agent also considers project-health script names such as:
+
+```txt
+repo:check
+check
+*:check
+*:doctor
+*:health
+*:verify
+*:validate
+*:ci
+```
+
+For example, this package no longer looks like it has no validation command:
+
+```json
+{
+  "scripts": {
+    "repo:check": "npm run desktop:build && npm run bridge:doctor"
+  }
+}
+```
+
+The discovered command becomes:
+
+```bash
+npm run repo:check
+```
+
+If a root `Cargo.toml` is detected and no package script is useful, the agent can fall back to:
+
+```bash
+cargo check
+```
+
+The project profile summary is included in the planning prompt so the model can reason about mixed workspaces such as npm + Rust + Tauri.

package/docs/agent-project-intelligence.md

@@ -0,0 +1,156 @@
+# Brass Agent project intelligence
+
+Brass Agent tries to understand the shape of the workspace before asking the LLM for a plan.
+
+This is separate from VS Code UI. It runs in the agent core and works from CLI, VS Code, batch runs, and any future client.
+
+## What it detects
+
+The agent now probes common project markers after reading `package.json` and lockfiles:
+
+- Node package markers: `package.json`, npm/pnpm/yarn/bun lockfiles
+- Rust markers: `Cargo.toml`, `Cargo.lock`
+- Tauri markers: `src-tauri/tauri.conf.json`, `apps/desktop/src-tauri/tauri.conf.json`
+- Workspace markers: `apps/`, `packages/`, `bridges/`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`
+- Bridge markers: `bridges/whatsmeow-bridge/Cargo.toml`, `bridges/whatsmeow-bridge/package.json`
+
+From those markers it builds a compact profile such as:
+
+```text
+Project profile: tauri; workspace: mixed; stacks: node, rust, tauri, desktop, bridge, monorepo
+```
+
+The profile is included in planning and patch-repair prompts, so the model can reason about real workspaces instead of assuming a single npm package.
+
+## Better validation discovery
+
+Before this change, validation discovery was mostly based on scripts like:
+
+```text
+test
+typecheck
+lint
+```
+
+Real repos often use names like:
+
+```text
+repo:check
+bridge:doctor
+health
+verify
+validate
+ci
+```
+
+The agent now classifies these as health/check scripts and can pick them as validation commands when no usable test script exists.
+
+Example:
+
+```json
+{
+  "scripts": {
+    "repo:check": "npm run desktop:build && npm run bridge:doctor"
+  }
+}
+```
+
+Can produce:
+
+```text
+Validation commands: npm run repo:check
+```
+
+If a Rust root is detected and no package scripts are useful, the agent can fall back to:
+
+```bash
+cargo check
+```
+
+## Permissions
+
+The built-in safe validation allowlist now includes common health checks:
+
+```text
+npm run *check*
+npm run *doctor*
+npm run *health*
+npm run *verify*
+npm run *validate*
+npm run repo:check
+cargo check
+cargo test
+cargo fmt --check
+cargo clippy
+```
+
+The same patterns exist for `pnpm`, `yarn`, and `bun` where applicable.
+
+Projects can still override this with `.brass-agent.json`:
+
+```json
+{
+  "permissions": {
+    "shell": {
+      "inheritDefaults": false,
+      "allow": ["npm run repo:check"]
+    }
+  }
+}
+```
+
+## Recommended config for mixed repos
+
+For a workspace with Node + Rust + Tauri, a good starting point is:
+
+```json
+{
+  "language": {
+    "response": "es"
+  },
+  "project": {
+    "packageManager": "npm",
+    "validationCommands": ["npm run repo:check"],
+    "maxValidationCommands": 1
+  },
+  "permissions": {
+    "shell": {
+      "inheritDefaults": true,
+      "allow": [
+        "npm run repo:check",
+        "npm run bridge:doctor",
+        "cargo check"
+      ]
+    },
+    "patchApply": {
+      "decision": "ask",
+      "risk": "high",
+      "defaultAnswer": "reject"
+    }
+  }
+}
+```
+
+## Why this matters
+
+For a repo like:
+
+```text
+apps/desktop/
+bridges/whatsmeow-bridge/
+Cargo.toml
+package.json
+package-lock.json
+```
+
+The agent should not blindly say “no test script found”. It should understand that the repo may be validated through a repo-level check, bridge doctor, Tauri build, or Cargo check.
+
+Project intelligence keeps that knowledge in the agent core so every surface benefits:
+
+```text
+CLI
+VS Code Chat
+Code Actions
+Batch runs
+Run History
+```

package/docs/agent-redaction.md

@@ -0,0 +1,18 @@
+# Brass Agent redaction
+
+P16 adds a prompt-safety redaction pass. The agent redacts likely secrets before building LLM prompts and before summaries derived from LLM observations.
+
+Default redaction covers common token shapes such as API keys, bearer tokens, GitHub tokens, Slack tokens, JWTs, and `key=value`-style secrets.
+
+Project config:
+
+```json
+{
+  "redaction": {
+    "enabled": true,
+    "additionalPatterns": ["ACME_[A-Z0-9]{24}"]
+  }
+}
+```
+
+Set `enabled` to `false` only in tightly controlled local debugging sessions.

package/docs/agent-release-readiness.md

@@ -0,0 +1,76 @@
+# Agent release readiness
+
+The current Brass Agent work is suitable for an experimental branch or alpha
+release. It is not yet a stable release candidate. CI/release automation is intentionally deferred until the end; local install and doctor commands are the current readiness path.
+
+## Good enough to publish to a repo
+
+The code is organized around stable boundaries:
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI protocol
+  ↑
+VS Code extension
+```
+
+It is reasonable to push it to a repository as an experimental feature branch,
+for example:
+
+```txt
+feat/brass-agent-alpha
+```
+
+or tag it as:
+
+```txt
+0.1.0-alpha.0
+```
+
+
+## GitHub source checklist
+
+Before the first public push, keep the repository source-first:
+
+- commit `.gitignore`, `README.md`, `SECURITY.md`, docs, `src/`, `scripts/`, and extension source,
+- do not commit `node_modules/`, root `dist/`, extension `out/`, extension `bundled/`, or generated `.vsix` files,
+- keep real secrets out of `.env`; commit only `.env.example`,
+- package VSIX artifacts from a release process or local packaging command, not from source control,
+- use an explicit preview version such as `0.1.0-alpha.0` for the VS Code extension.
+
+## Stable release checklist
+
+Before calling it stable, the project should have:
+
+- boring local install via `npm run agent:vscode:install`
+- clean local diagnostics via `npm run agent:doctor`
+- clean, repeatable `npm ci && npm run build` in CI, added later
+- unit tests for `src/agent/core` decisions, patch extraction, rollback, config,
+  redaction, batch parsing, and CI exit codes
+- integration tests for CLI flows with fake LLM and temporary git workspaces
+- extension compile/package CI for `extensions/vscode-brass-agent`
+- `.vsix` artifact generation in GitHub Releases
+- documented security model for command allowlists, approvals, redaction,
+  context exclusions, patch storage, and rollback
+- config schema validation with helpful errors
+- a public compatibility statement for Node.js, VS Code, package managers, and
+  model providers
+- a release workflow for runtime package, CLI, and VS Code extension versioning
+- marketplace readiness only after local `.vsix` installs are boring and reliable
+
+## Recommended versioning
+
+Suggested path:
+
+```txt
+0.1.0-alpha.0  internal alpha / local VSIX
+0.1.0-alpha.1  dogfood in real repos
+0.1.0-beta.0   CI + tests + release artifacts
+0.1.0          first stable CLI + VSIX release
+```
+
+Stable should mean the tool fails safely, can be installed repeatedly, has docs
+for the happy path and recovery path, and has tests covering the risky flows.

package/docs/agent-rollback-safety.md

@@ -0,0 +1,162 @@
+# Agent automatic rollback safety
+
+P14 adds automatic rollback safety for generated patches.
+
+This is different from the manual exact rollback command from P15:
+
+```bash
+brass-agent --rollback-patch-file ./approved.diff --yes "rollback approved patch"
+```
+
+P14 is part of the normal generated-patch loop:
+
+```txt
+llm.plan
+  -> patch.apply
+  -> validation commands
+  -> optional llm.patch repair attempts
+  -> if validation still fails: patch.rollback
+  -> optional validation after rollback
+```
+
+## Boundary rule
+
+Rollback safety lives in `src/agent`, not in `src/core`:
+
+```txt
+src/core
+  ↑
+src/agent rollback policy / patch ledger
+  ↑
+src/agent/cli config
+```
+
+The core runtime still only owns effects, fibers, scopes, cancellation, and
+resource safety. The agent owns policy and workspace semantics.
+
+## What is rolled back
+
+When `patch.apply` succeeds, the resulting `patch.applied` observation now keeps
+an internal copy of the exact unified diff that was applied. If the final
+validation still fails and the repair budget is exhausted, the agent can schedule
+`patch.rollback` with that same diff.
+
+Rollback uses the existing `PatchService.rollback(...)` primitive, which runs:
+
+```txt
+git apply --reverse --check
+git apply --reverse
+```
+
+So rollback still uses the same path checks, approval flow, policy flow, and
+cancellable shell execution as normal patch application.
+
+## Defaults
+
+Rollback safety is enabled by default for generated patches:
+
+```json
+{
+  "rollback": {
+    "enabled": true,
+    "onFinalValidationFailure": true,
+    "strategy": "all",
+    "maxRollbackDepth": 8,
+    "runValidationAfterRollback": true,
+    "allowForSuppliedPatches": false
+  }
+}
+```
+
+The default strategy is `all`, meaning the agent restores the generated patch
+stack in reverse order. For a more conservative single-step rollback:
+
+```json
+{
+  "rollback": {
+    "strategy": "last"
+  }
+}
+```
+
+To disable automatic rollback:
+
+```json
+{
+  "rollback": {
+    "enabled": false
+  }
+}
+```
+
+## Exact supplied patches
+
+Automatic rollback is disabled by default for exact patch-file flows:
+
+```bash
+brass-agent --apply-patch-file ./approved.diff --yes "apply approved patch"
+```
+
+That preserves the VS Code patch-preview guarantee:
+
+```txt
+preview patch A
+  -> user approves patch A
+  -> brass-agent applies exactly patch A
+```
+
+The agent will not silently generate a new patch or automatically reverse the
+approved patch unless the project explicitly opts in:
+
+```json
+{
+  "rollback": {
+    "allowForSuppliedPatches": true
+  }
+}
+```
+
+## Approvals still apply
+
+Automatic rollback schedules a `patch.rollback` action. It does not bypass
+permissions or approvals:
+
+```txt
+patch.rollback
+  -> PermissionService
+  -> ApprovalService when policy asks
+  -> ToolPolicy timeout/retry
+  -> PatchService.rollback
+```
+
+In an interactive terminal this can prompt. In CI/non-interactive output, the
+approval strategy controls whether the rollback is allowed. For example:
+
+```bash
+brass-agent --apply --yes "fix the failing tests"
+```
+
+allows both apply and rollback prompts. Without `--yes`, non-interactive runs
+will reject approval-required rollback actions by default.
+
+## Validation after rollback
+
+By default, the agent re-runs discovered validation commands after rollback:
+
+```json
+{
+  "rollback": {
+    "runValidationAfterRollback": true
+  }
+}
+```
+
+Disable it when rollback should be a pure restore step:
+
+```json
+{
+  "rollback": {
+    "runValidationAfterRollback": false
+  }
+}
+```

package/docs/agent-rollback.md

@@ -0,0 +1,23 @@
+# Brass Agent rollback patches
+
+P15 adds a manual rollback path for approved unified diffs.
+
+```bash
+brass-agent --rollback-patch-file ./approved.diff --yes "rollback approved patch"
+```
+
+The CLI does not edit files directly. It passes the supplied diff through the same `PatchService` boundary used by normal apply mode:
+
+```txt
+initialPatch
+  -> patch.rollback
+  -> PermissionService
+  -> ApprovalService
+  -> PatchService.rollback
+  -> git apply --reverse --check
+  -> git apply --reverse
+```
+
+This intentionally supports exact rollback of a patch that was previously previewed/applied.
+
+P14 builds on the same primitive for automatic rollback safety when generated patches still fail validation after repair attempts are exhausted. See [Agent automatic rollback safety](./agent-rollback-safety.md).

package/docs/agent-run-artifacts.md

@@ -0,0 +1,16 @@
+# Brass Agent run artifacts
+
+P18 adds a small persistence surface for local DX and CI debugging.
+
+```bash
+brass-agent --save-run .brass-agent/runs "fix the failing tests"
+```
+
+The CLI writes two files:
+
+```txt
+.brass-agent/runs/<run-id>-<goal>.json
+.brass-agent/runs/<run-id>-<goal>.md
+```
+
+The JSON artifact uses the same compacted state representation used by protocol output, so large file contents, shell output, and patches are bounded unless a future trusted mode opts into full payloads.