brass-runtime 1.16.0 → 1.17.0

package/docs/agent-cli.md

@@ -0,0 +1,405 @@
+# Brass Agent CLI
+
+## Initialize a workspace
+
+```bash
+brass-agent --init
+```
+
+This creates `.brass-agent.json`, `brass-agent.batch.json`, `.env.example`, and `BRASS_AGENT.md` in the workspace. Existing files are skipped unless `--force` is passed.
+
+Useful variants:
+
+```bash
+brass-agent --init --init-dry-run
+brass-agent --init --init-profile google
+brass-agent --init --init-profile fake --force
+```
+
+See [Agent init](./agent-init.md) for the generated config and recommended first-run flow.
+
+
+`brass-agent` is the development CLI for the experimental `src/agent` module.
+It wires the agent environment together, runs `runAgent(...)`, and prints either a
+human-readable run summary, streamed event JSON, protocol JSON Lines, or the raw `AgentState` JSON.
+
+The CLI is intentionally thin:
+
+```txt
+CLI
+  -> parse flags
+  -> load .brass-agent.json if present
+  -> choose LLM provider
+  -> choose context discovery budget
+  -> choose approval strategy
+  -> create AgentEnv
+  -> create Runtime
+  -> runAgent(...)
+  -> print result
+```
+
+The runtime and agent invariants still live below the CLI. The CLI must not run
+side effects directly except for reading process arguments/environment, prompting
+for approvals, and printing output.
+
+## Install/build entry
+
+The package exposes a binary after build:
+
+```bash
+npm run build
+npm run agent:link
+brass-agent "fix the failing tests"
+```
+
+For local development without building:
+
+```bash
+npm run agent:dev -- "fix the failing tests"
+# or
+npx tsx src/agent/cli/main.ts "fix the failing tests"
+```
+
+## Usage
+
+```bash
+brass-agent [options] "goal"
+```
+
+Options:
+
+```txt
+--mode read-only|propose|write|autonomous
+    Agent permission mode. Default: propose.
+
+--apply
+    Alias for --mode write.
+
+--cwd PATH
+    Starting directory for workspace discovery. Default: current directory.
+
+--where, --print-workspace
+    Print the resolved workspace root and exit.
+
+--no-discover-workspace
+    Use --cwd exactly instead of searching upward for package.json, .brass-agent.json, workspace markers, or .git.
+
+--config PATH
+    Load a specific .brass-agent.json policy/config file.
+
+--batch-file PATH
+    Run multiple goals sequentially from a JSON or line-based file.
+
+--batch-stop-on-failure
+    Stop a batch after the first failed run.
+
+--batch-continue-on-failure
+    Continue a batch even when one run fails.
+
+--no-config
+    Do not discover or load an agent config file.
+
+--json
+    Print the full AgentState JSON instead of human-readable output.
+
+--events-json
+    Stream compact AgentEvent objects as JSON Lines and do not print final AgentState.
+
+--protocol-json
+    Stream Brass Agent protocol JSON Lines. This includes event messages and a final-state message for editor integrations.
+
+--yes, -y
+    Auto-approve approval prompts. Useful for CI and smoke tests.
+
+--no-input
+    Do not prompt; reject any action that requires approval.
+
+--approval auto|interactive|approve|deny
+    Approval strategy. Default: auto.
+
+--help, -h
+    Show help.
+```
+
+
+## Batch runs
+
+P21 adds sequential batch execution:
+
+```bash
+brass-agent --batch-file ./brass-agent.batch.json --ci
+```
+
+Batch files can be JSON arrays, JSON objects with a `goals` array, or line-based
+text files. Each item becomes a normal `runAgent(...)` invocation, so policy,
+approvals, redaction, rollback safety, and CI exit code handling still apply.
+
+See [Agent batch runs](./agent-batch.md).
+
+## Config files
+
+By default, the CLI first resolves a workspace root by searching upward from `--cwd` for:
+
+```txt
+.brass-agent.json
+brass-agent.config.json
+package.json
+pnpm-workspace.yaml
+turbo.json
+nx.json
+.git
+```
+
+Then it searches upward from that resolved workspace root for config files:
+
+```txt
+.brass-agent.json
+brass-agent.config.json
+```
+
+Use `brass-agent --where` to see the resolved root.
+
+Use `--config PATH` to force a specific file, or `--no-config` to run with
+only built-in defaults and environment variables. Config can set default mode,
+approval strategy, LLM provider/model, project command discovery, context discovery,
+shell command policy, patch apply policy, and tool timeouts/retries.
+
+Precedence is:
+
+```txt
+CLI flags > environment variables > .brass-agent.json > built-in defaults
+```
+
+See [Agent config and policy files](./agent-config.md).
+
+## Context discovery
+
+Before calling the LLM, the CLI-driven agent now runs a bounded context pass by
+default. It extracts paths and identifiers from the goal and validation output,
+then uses `fs.searchText` / `fs.readFile` to gather likely relevant files.
+
+Tune it in config:
+
+```json
+{
+  "context": {
+    "maxSearchQueries": 3,
+    "maxFiles": 4
+  }
+}
+```
+
+Or disable it:
+
+```json
+{
+  "context": {
+    "enabled": false
+  }
+}
+```
+
+See [Agent context discovery](./agent-context-discovery.md).
+
+## Modes
+
+### `propose`
+
+Default mode. The agent can inspect the workspace, discover project-aware
+validation commands from `package.json`/lockfiles/config, run whitelisted
+validation commands, discover a bounded set of relevant context files, ask the
+LLM, and record `patch.proposed`. It does not
+apply changes.
+
+```bash
+brass-agent "fix the failing tests"
+```
+
+### `write`
+
+Writable mode. The agent can apply an extracted unified diff through the
+`PatchService`, then rerun validation. If a generated patch fails to apply or
+validation still fails, P13 can ask `llm.patch` for a bounded repair diff and
+validate again. Applying a patch still requires approval.
+In an interactive terminal the CLI prompts by default; in CI/non-interactive
+contexts use `--yes` to approve or `--no-input` to reject.
+
+```bash
+brass-agent --apply "fix the failing tests"
+# equivalent:
+brass-agent --mode write "fix the failing tests"
+# non-interactive approval:
+brass-agent --apply --yes "fix the failing tests"
+```
+
+### `read-only`
+
+Inspection mode. The agent reads workspace context, checks project metadata such
+as lockfiles, and asks the LLM without running shell validation or applying
+patches.
+
+```bash
+brass-agent --mode read-only "inspect this repo"
+```
+
+### `autonomous`
+
+Reserved for future work. It currently has the broadest policy surface, but P6
+still routes sensitive actions such as `patch.apply` through approvals.
+
+## Output
+
+Human-readable output is the default:
+
+```txt
+brass-agent propose
+workspace: /repo
+goal: fix the failing tests
+
+✓ read package.json
+! pnpm test exited 1
+✓ llm.plan responded
+✓ patch proposed
+✓ done
+
+phase: done
+steps: 5
+patch: proposed only; rerun with --apply to apply it
+
+summary:
+...
+```
+
+Use `--json` when debugging the state machine or tests:
+
+```bash
+brass-agent --json "fix the failing tests"
+```
+
+Use `--events-json` for quick event-only streams:
+
+```bash
+brass-agent --events-json "fix the failing tests"
+```
+
+Use `--protocol-json` for editor integrations and other clients that need both live events and the final compact state:
+
+```bash
+brass-agent --protocol-json "fix the failing tests"
+```
+
+The protocol is newline-delimited JSON:
+
+```jsonl
+{"protocol":"brass-agent","version":1,"type":"event","event":{"type":"agent.run.started"}}
+{"protocol":"brass-agent","version":1,"type":"final-state","state":{"phase":"done"}}
+```
+
+See [Agent DX surfaces](./agent-dx.md).
+
+## Project command discovery
+
+The CLI passes `config.project` into `runAgent(...)`. The agent uses it to
+select validation commands instead of hardcoding `npm test`.
+
+Default discovery reads `package.json`, checks common lockfiles, infers
+`npm`/`pnpm`/`yarn`/`bun`, and selects scripts like `test`,
+`test:ci`, `typecheck`, or `lint` when relevant.
+
+Examples:
+
+```json
+{
+  "project": {
+    "packageManager": "pnpm",
+    "validationCommands": ["pnpm run test:unit", "pnpm run typecheck"]
+  }
+}
+```
+
+See [Agent project command discovery](./agent-project-commands.md).
+
+## Approvals
+
+Actions can be allowed, denied, or marked as requiring approval by
+`PermissionService`. In P6, `patch.apply` requires approval in `write` and
+`autonomous` modes.
+
+Approval strategy is chosen by CLI flags/environment:
+
+```txt
+--approval auto         Interactive only when stdin/stderr/stdout are TTYs; otherwise deny.
+--approval interactive  Always prompt on stderr.
+--approval approve      Auto-approve all approval requests.
+--approval deny         Auto-reject all approval requests.
+--yes, -y               Alias for --approval approve.
+--no-input              Alias for --approval deny.
+```
+
+Environment knobs:
+
+```bash
+BRASS_AGENT_APPROVAL=approve|deny|interactive|auto
+BRASS_AGENT_AUTO_APPROVE=true
+```
+
+Prompts are written to stderr, so `--json --approval interactive` can still keep
+final JSON on stdout. The default remains conservative: non-interactive runs deny
+approval-required actions unless `--yes` or `BRASS_AGENT_AUTO_APPROVE=true` is
+set.
+
+## LLM providers
+
+The CLI chooses a provider from environment variables.
+
+Fake/offline:
+
+```bash
+BRASS_LLM_PROVIDER=fake brass-agent "inspect"
+```
+
+Google Gemini:
+
+```bash
+BRASS_LLM_PROVIDER=google \
+GEMINI_API_KEY="..." \
+BRASS_GOOGLE_MODEL="gemini-2.5-flash" \
+brass-agent "fix the failing tests"
+```
+
+OpenAI-compatible:
+
+```bash
+BRASS_LLM_PROVIDER=openai-compatible \
+BRASS_LLM_ENDPOINT="https://api.openai.com/v1/chat/completions" \
+BRASS_LLM_API_KEY="..." \
+BRASS_LLM_MODEL="gpt-4.1" \
+brass-agent "fix the failing tests"
+```
+
+If `BRASS_LLM_PROVIDER` is not set, the CLI tries Google, then
+OpenAI-compatible, then falls back to the fake LLM.
+
+The CLI also auto-loads supported agent environment keys from `.brass-agent.env`,
+`.env.local`, and `.env` in `--cwd`. Use `--env-file PATH` to choose a specific
+file, or `--no-env-file` to disable this behavior. The loader never prints secret
+values and ignores non-agent keys. See [Agent env files](./agent-env-files.md).
+
+## Applying a reviewed patch file
+
+Editor integrations can apply an already-reviewed unified diff without asking
+the model to regenerate it. This exact patch-file path does not run the patch
+quality repair loop, so the diff being applied is the diff the user reviewed:
+
+```bash
+brass-agent --apply-patch-file ./approved.diff --yes "apply approved patch"
+```
+
+For preview integrations, use:
+
+```bash
+brass-agent --protocol-json --protocol-full-patches "fix the failing tests"
+```
+
+`--protocol-full-patches` is intended for trusted local clients that need the
+full `patch.proposed` payload. Other large payloads remain compacted.