brass-runtime 1.16.0 → 1.17.0

package/docs/agent-batch.md

@@ -0,0 +1,185 @@
+# Agent batch runs
+
+P21 adds sequential batch execution to `brass-agent`.
+
+The goal is to make common DX/CI workflows composable without introducing a new
+scheduler or breaking the existing boundary:
+
+```txt
+src/core
+  ↑
+src/agent runAgent(...)
+  ↑
+brass-agent CLI batch runner
+```
+
+A batch run is just multiple normal agent runs executed one after another. Each
+run still goes through the same pipeline:
+
+```txt
+AgentAction
+  -> PermissionService
+  -> ApprovalService when ask
+  -> ToolPolicy timeout/retry
+  -> Async tool effect
+  -> Observation
+```
+
+Batch mode does not bypass policy, approvals, redaction, rollback safety, CI exit
+codes, or artifact export.
+
+## CLI
+
+Run a batch from a file:
+
+```bash
+brass-agent --batch-file ./brass-agent.batch.json
+```
+
+In CI:
+
+```bash
+brass-agent --batch-file ./brass-agent.batch.json --ci --batch-stop-on-failure
+```
+
+`--batch-stop-on-failure` stops after the first run whose CI status is non-zero.
+`--batch-continue-on-failure` forces the opposite.
+
+When neither flag is provided, the default is:
+
+```txt
+--ci      -> stop on failure
+not --ci  -> continue
+```
+
+## Batch file formats
+
+### JSON array
+
+```json
+[
+  "inspect this workspace",
+  { "preset": "typecheck" },
+  { "preset": "lint" },
+  { "preset": "fix-tests", "mode": "propose" }
+]
+```
+
+### JSON object
+
+```json
+{
+  "goals": [
+    { "preset": "inspect" },
+    { "goal": "explain the failing tests", "mode": "read-only" },
+    { "goal": "fix the failing tests", "mode": "propose" }
+  ]
+}
+```
+
+### Plain text
+
+If the file is not valid JSON, `brass-agent` treats it as a line-based goal file.
+Blank lines and `#` comments are ignored.
+
+```txt
+# brass-agent.batch.txt
+inspect this workspace
+run typecheck discovery and explain failures
+fix the failing tests
+```
+
+## Per-goal fields
+
+JSON batch items support:
+
+```ts
+{
+  goal?: string;
+  preset?: "fix-tests" | "inspect" | "typecheck" | "lint";
+  mode?: "read-only" | "propose" | "write" | "autonomous";
+  cwd?: string;
+  patchFile?: string;
+  patchFileMode?: "apply" | "rollback";
+  saveRunDir?: string;
+}
+```
+
+`preset` fills in a standard goal. `goal` wins when both are present.
+
+`cwd` lets one batch file target multiple workspaces, but the same loaded config
+and CLI environment are reused for the full batch. Use separate invocations when
+different workspaces need different config files.
+
+## Config default batch
+
+A project can define a default batch:
+
+```json
+{
+  "batch": {
+    "stopOnFailure": true,
+    "goals": [
+      { "preset": "inspect" },
+      { "preset": "typecheck" },
+      { "preset": "lint" }
+    ]
+  }
+}
+```
+
+Then run:
+
+```bash
+brass-agent --ci
+```
+
+The config batch is used only when the CLI does not receive an explicit goal,
+`--preset`, `--patch-file`, or `--batch-file`.
+
+## Outputs
+
+Human output prints each normal run and then a final batch summary:
+
+```txt
+batch summary:
+completed: 3/3
+failed: 0
+exit code: 0
+```
+
+`--json` prints a batch object:
+
+```json
+{
+  "type": "batch",
+  "summary": {
+    "total": 3,
+    "completed": 3,
+    "failed": 0,
+    "exitCode": 0,
+    "stoppedEarly": false
+  },
+  "results": []
+}
+```
+
+`--protocol-json` emits normal event messages and a `final-state` message per
+run, followed by a `batch-summary` message.
+
+## Exit codes
+
+In `--ci` mode, batch exit code is aggregated from individual runs:
+
+```txt
+1 if any run failed or latest validation failed
+2 if no run failed but at least one run proposed an unapplied patch with --fail-on-patch-proposed
+0 otherwise
+```
+
+## VS Code
+
+P22 adds a VS Code command, `Brass Agent: Run Batch File`, which invokes the CLI
+with `--protocol-json --batch-file`. The extension stores the batch as a parent
+history entry and each CLI `final-state` message as a child run. See
+[VS Code batch runner](./agent-vscode-batch-runner.md).

package/docs/agent-boundaries.md

@@ -0,0 +1,112 @@
+# Agent Module Boundaries
+
+These rules keep the experimental agent layer useful without letting it leak into the runtime core.
+
+## Dependency direction
+
+```txt
+core runtime
+  ↑
+agent module
+  ↑
+cli / UX
+```
+
+Rules:
+
+1. `src/core` must not know that `src/agent` exists.
+2. `src/agent` may depend on `src/core` runtime primitives.
+3. Agent-specific shortcuts must not be added to `Runtime`, `Fiber`, `Scope`, or the scheduler.
+4. If the agent reveals a missing semantic in the core, fix the core as a runtime invariant first.
+5. Keep the agent as an experimental consumer of the runtime until the shape is stable.
+
+## Agent execution model
+
+The agent does not perform side effects directly.
+
+It must follow this pipeline:
+
+```txt
+Goal
+  -> decideNextAction
+  -> PermissionService
+  -> ApprovalService when permission decision is ask
+  -> ToolPolicy
+  -> AgentAction interpreted as Async
+  -> Observation
+  -> reducer
+  -> next AgentState
+```
+
+Rules:
+
+1. The planner produces `AgentAction` values.
+2. Every `AgentAction` is interpreted into `Async<AgentEnv, AgentError, Observation>`.
+3. All external work goes through capabilities in `AgentEnv`.
+4. All tool execution goes through permissions first.
+5. Approval-required actions must be approved before tool execution.
+6. All tool execution goes through timeout/retry policy.
+7. No detached background work by default.
+8. Every async tool that touches external work must be cancellable.
+9. Any patch-application path must validate that every target path stays inside the workspace.
+
+
+## Configuration boundary
+
+Project policy may be loaded from `.brass-agent.json`, but config is still an
+agent-layer concern:
+
+```txt
+src/core
+  ↑
+src/agent policy/config
+  ↑
+src/agent/cli Node config loader
+```
+
+Rules:
+
+1. Config loading must not move into `src/core`.
+2. Config is resolved before constructing `AgentEnv`.
+3. Config may tune permissions, approvals, LLM provider/model, and tool policies.
+4. Config must not store secrets; adapters should read API keys from environment variables.
+5. Config must not bypass the `AgentAction -> PermissionService -> ApprovalService -> ToolPolicy -> Async -> Observation` pipeline.
+
+## Runtime invariants the agent relies on
+
+The agent assumes these runtime semantics:
+
+1. `Scope.close()` interrupts child fibers.
+2. `Scope.closeAsync(...)` can be awaited.
+3. Closing a parent scope propagates to subscopes.
+4. Interrupted fibers run their finalizers exactly once.
+5. `Async` work that registers external IO returns a canceler.
+6. Race-like operators close their internal scopes and cancel losing branches.
+7. If a tool cannot be cancelled, it is a bug in the tool adapter.
+
+## Safety defaults
+
+Initial agent modes should be conservative:
+
+1. `read-only`: read/search/model only.
+2. `propose`: read/search/model plus whitelisted read-only commands and patch proposals.
+3. `write`: may apply patches only after approval.
+4. `autonomous`: reserved for later; sensitive actions still require approval.
+
+The initial CLI should default to `propose`.
+
+## Extraction rule
+
+Keep the agent in `src/agent` while validating the vertical slice.
+Extract to packages only after the design stabilizes:
+
+```txt
+packages/
+  brass-runtime/
+  brass-agent/
+  brass-node/
+  brass-llm/
+  brass-cli/
+```
+
+Until then, `src/agent` is allowed to be experimental, but `src/core` is not.

package/docs/agent-chat-sessions.md

@@ -0,0 +1,160 @@
+# Brass Agent chat sessions
+
+P30 turns the VS Code Chat view from a one-shot launcher into a lightweight
+conversation surface.
+
+The CLI remains the canonical execution boundary. The VS Code extension still
+calls:
+
+```bash
+brass-agent --protocol-json --protocol-full-patches --cwd <workspace> <goal>
+```
+
+The new session behavior lives entirely in the extension.
+
+## What is stored
+
+The VS Code extension stores a compact chat session in `workspaceState`:
+
+```txt
+messages
+last run summary
+last validation output
+last patch stats
+last patch body, only when brassAgent.storePatchesInHistory is true
+```
+
+This is editor-local state. It is not written to the repository and it is not
+owned by `src/core` or `src/agent`.
+
+The message history length is controlled by:
+
+```json
+{
+  "brassAgent.chatHistoryLimit": 80
+}
+```
+
+Disable patch persistence with:
+
+```json
+{
+  "brassAgent.storePatchesInHistory": false
+}
+```
+
+## Follow-up context
+
+After a run, follow-up messages can use the previous run as context.
+
+For example:
+
+```txt
+fix the failing tests
+why did that fail?
+try again but do not change the public API
+explain the patch
+```
+
+The extension composes the next agent goal with a compact context block that may
+include:
+
+```txt
+previous goal
+previous status
+previous summary/error
+latest validation command output
+last patch stats
+last patch diff, only for explicit explain-last style requests
+```
+
+The agent is instructed to ignore previous context if the new request is
+unrelated.
+
+## Slash commands
+
+The chat supports slash commands to avoid menus and flags:
+
+```txt
+/inspect
+/fix-tests
+/typecheck
+/lint
+/ask <question>
+/propose <task>
+/apply <task>
+/explain-last
+/apply-last
+/rollback-last
+/doctor
+/output
+/clear
+/help
+```
+
+### Safety behavior
+
+`/apply <task>` still uses the safe apply-preview flow:
+
+```txt
+chat request
+  -> propose run
+  -> patch preview
+  -> user approval
+  -> brass-agent --apply-patch-file <exact diff>
+```
+
+`/apply-last` reopens the last patch preview. It does not silently write.
+
+`/rollback-last` calls the CLI rollback path:
+
+```bash
+brass-agent --rollback-patch-file <temp.diff> --yes ...
+```
+
+It asks for VS Code confirmation first, and the CLI still goes through the normal
+patch rollback service.
+
+## Quick actions
+
+Assistant messages can include buttons such as:
+
+```txt
+Open patch preview
+Explain last
+Rollback last
+Show output
+```
+
+These buttons send slash commands back through the same chat handler.
+
+## Boundary
+
+The boundary remains unchanged:
+
+```txt
+src/core
+  ↑
+src/agent
+  ↑
+brass-agent CLI protocol
+  ↑
+VS Code chat session UI
+```
+
+The extension owns conversation memory and UX. The agent owns execution,
+permissions, validation, redaction, patch application, rollback, and protocol
+semantics.
+
+## Explain last behavior
+
+`/explain-last` is intentionally local and deterministic. It summarizes the last
+stored run from VS Code workspace state instead of launching a new agent run.
+
+That keeps the button useful even when the previous run stopped before the LLM
+step, for example because a context file disappeared or a tool returned `FsError`.
+For an AI follow-up using the same context, use:
+
+```txt
+/ask why did that fail?
+```

package/docs/agent-ci.md

@@ -0,0 +1,17 @@
+# Brass Agent CI mode
+
+P19 adds explicit CI-oriented exit codes.
+
+```bash
+brass-agent --ci --json "fix the failing tests"
+```
+
+Exit codes:
+
+```txt
+0  run completed and latest validation command passed
+1  agent error or latest validation command failed
+2  patch was proposed but not applied, when --fail-on-patch-proposed is set
+```
+
+`--ci` does not force an output format. Combine it with `--json`, `--events-json`, or `--protocol-json` depending on the consumer.