brass-runtime 1.16.0 → 1.17.0

package/docs/agent-vscode-ux.md

@@ -0,0 +1,73 @@
+# Brass Agent VS Code UX
+
+The VS Code extension is intentionally a thin client over the `brass-agent` CLI, but the editor surface should still feel guided and uncluttered.
+
+## Runs sidebar
+
+The Activity Bar contributes a **Brass Agent** container with a **Run History** view.
+
+When the history is empty, the view shows a welcome state with links to:
+
+- **New Run** — guided quick pick for common actions.
+- **Initialize Workspace** — writes `.brass-agent.json`, `brass-agent.batch.json`, `.env.example`, and `BRASS_AGENT.md`.
+- **Doctor** — checks CLI, workspace, model, package manager, and VS Code setup.
+
+## Toolbar design
+
+The view title toolbar is intentionally small:
+
+- **New Run** — primary action.
+- **Cancel Current Run** — only visible while a run is active.
+- **Refresh History** — always visible.
+
+Everything else lives in the overflow menu:
+
+- Show Output
+- Initialize Workspace
+- Doctor
+- Run Configured Batch
+- Run Batch File
+- Show Last Patch Preview
+- Clear History
+
+This prevents the toolbar from turning into a row of long command labels.
+
+## New Run flow
+
+`Brass Agent: New Run...` opens a Quick Pick with the most common workflows:
+
+- Inspect Workspace
+- Propose Fix
+- Apply Fix
+- Fix Tests
+- Typecheck
+- Lint
+- Run Configured Batch
+- Run Batch File
+- Doctor
+- Initialize Workspace
+- Show Output
+
+`Apply Fix`, `Fix Tests`, `Typecheck`, and `Lint` still use the safe patch preview flow. VS Code never applies patches directly.
+
+## Running state
+
+While a CLI process is active, the extension sets the `brassAgent.running` VS Code context key. That controls whether the cancel action appears in the Run History toolbar.
+
+The Status Bar also shows run state and links to the output channel.
+
+## Command Palette
+
+Command Palette commands are grouped under the `Brass Agent` category, so users see names such as:
+
+```txt
+Brass Agent: New Run...
+Brass Agent: Doctor
+Brass Agent: Initialize Workspace
+```
+
+Argument-only commands such as `Open Run Details`, `Show History Patch`, and `Rerun History Run` are hidden from the Command Palette because they are meant to be invoked from the Run History tree context menu.
+
+## Chat view
+
+P29 adds a persistent Chat view to the Brass Agent sidebar. It provides a lower-friction, Copilot-like way to ask questions, request patch proposals, and run apply-after-preview flows without memorizing CLI commands. See [Copilot-like VS Code DX](./agent-copilot-like-dx.md).

package/docs/ai/INVARIANTS.md

@@ -0,0 +1,84 @@
+# Invariants
+
+These are the rules that make `brass-runtime` understandable. Treat them as
+stronger than local convenience.
+
+## Core effect invariants
+
+- Effects are values. Constructing an effect must not run the side effect.
+- `Async<R, E, A>` is the semantic async representation.
+- `Promise` is an interop boundary, not the runtime primitive.
+- Public helpers may expose `toPromise` for DX, but execution still belongs to
+  the runtime/fiber interpreter.
+- Synchronous loops must respect fiber/scheduler budgets.
+- Failure must remain typed where the API promises typed errors.
+
+## Cancellation and scopes
+
+- Async operations should be cancelable whenever the host API allows it.
+- If a host operation returns a canceler, the fiber must detach it when the
+  operation completes.
+- Child fibers belong to a scope or parent relationship.
+- Closing a scope interrupts owned children and runs finalizers.
+- Finalizers run exactly once and in reverse registration order.
+- Await `closeAsync` when completion matters; `close` is fire-and-forget.
+
+## Scheduler and fibers
+
+- All normal async resumption goes back through the scheduler/fiber machinery.
+  The no-hooks/no-lane native top-level fast path may resume via its own
+  microtask loop, but only when it preserves runtime/fiber-local semantics and
+  is disabled for hooks, custom schedulers, lanes, and WASM mode.
+- Fibers must not notify joiners more than once.
+- Interrupt must be cooperative and idempotent.
+- Runtime hooks must observe events without changing semantics.
+- Lane/caller scheduling is metadata for fairness and observability, not a
+  behavior change for user effects.
+
+## Streams
+
+- Streams are pull-based and lazy.
+- End-of-stream is modeled separately from failure.
+- Buffering must preserve the selected backpressure/drop strategy.
+- Stream finalizers must cancel readers/producers.
+- Fusion optimizations must not change ordering, failure, or cancellation.
+
+## HTTP
+
+- HTTP is built on top of runtime primitives; it is not part of the core.
+- Request construction must stay lazy.
+- Fetch cancellation must be wired to fiber interruption through
+  `AbortController`.
+- Keep wire, content, and metadata layers separate.
+- Middleware transforms clients; it should not execute requests while being
+  composed.
+- Retry must respect method safety, retry budgets, aborts, pool rejection, and
+  explicit per-request overrides.
+- Compression/decompression must keep headers and body semantics explicit.
+- Lifecycle cache/dedup/priority code must preserve cancellation ownership.
+
+## WASM
+
+- WASM mode is strict. If WASM is requested and unavailable, fail clearly.
+- TypeScript and WASM engines should have parity tests for shared behavior.
+- Generated `wasm/pkg` output is build output; source changes live in `crates/`
+  and TypeScript bridge files.
+
+## Agent
+
+- `src/agent` may depend on runtime primitives.
+- Core runtime must not depend on agent code.
+- Discovery and patch application go through agent services and permission
+  policies.
+- Workspace reads/writes stay workspace-relative and policy-aware.
+- Prompt/context helpers should be bounded and redaction-aware.
+
+## When unsure
+
+Before changing behavior, answer these:
+
+- What owns this async operation?
+- What cancels it?
+- Which scope/fiber runs its finalizer?
+- Is this public API or internal plumbing?
+- Which tests encode the invariant I am touching?

package/docs/ai/PROJECT_MAP.md

@@ -0,0 +1,338 @@
+# Project Map
+
+This is the compact map for understanding `brass-runtime` quickly.
+
+## Package entry points
+
+- `src/index.ts` -> package root export `brass-runtime`.
+- `src/http/index.ts` -> subpath export `brass-runtime/http`.
+- `src/observability/index.ts` -> subpath export `brass-runtime/observability`.
+- `src/perf/index.ts` -> subpath export `brass-runtime/perf`.
+- `src/perf/cli.ts` -> CLI binary `brass-perf`.
+- `src/agent/index.ts` -> subpath export `brass-runtime/agent`.
+- `src/agent/cli/main.ts` -> CLI binary `brass-agent`.
+- `tsup.config.ts` -> CJS, ESM, and JS bundle entries.
+- `package.json` -> scripts, exports, package files, CLI bin.
+
+## Core runtime
+
+Paths:
+
+- `src/core/types`
+- `src/core/runtime`
+- `src/core/runtime/engine`
+
+Purpose:
+
+- Define `Effect`, `Async`, `Exit`, `Cause`, and cancellation types.
+- Interpret `Async` values in fibers.
+- Provide first-release DX helpers (`runPromise`, `runExit`, `makeRuntime`) on
+  top of the existing runtime.
+- Own scheduler, scopes, finalizers, runtime hooks, layers, metrics, tracing,
+  schedules, supervisors, semaphores, resources, worker pools, and engine
+  selection.
+
+Read first:
+
+- `src/core/types/asyncEffect.ts`
+- `src/core/runtime/runtime.ts`
+- `src/core/runtime/dx.ts`
+- `src/core/runtime/fiber.ts`
+- `src/core/runtime/scope.ts`
+- `src/core/runtime/scheduler.ts`
+- `src/core/runtime/supervisor.ts`
+- `src/core/runtime/resource.ts`
+- `src/core/runtime/schedule.ts`
+
+Tests:
+
+- `src/core/types/__tests__`
+- `src/core/runtime/__tests__`
+
+Docs:
+
+- `docs/ARCHITECTURE.md`
+- `docs/cancellation.md`
+- `docs/observability.md`
+- `docs/guides/testing.md`
+- `docs/guides/resource-management.md`
+- `docs/guides/retry.md`
+- `docs/guides/supervisors.md`
+- `docs/recipes`
+- `docs/api-polish.md`
+- `docs/release.md`
+
+## Streams
+
+Paths:
+
+- `src/core/stream`
+
+Purpose:
+
+- Provide pull-based streams, buffering, queues, hubs, pipelines, chunks,
+  fusion, and stream operators.
+- Preserve backpressure, cancellation, and resource safety.
+
+Read first:
+
+- `src/core/stream/stream.ts`
+- `src/core/stream/buffer.ts`
+- `src/core/stream/queue.ts`
+- `src/core/stream/pipeline.ts`
+
+Tests:
+
+- `src/core/stream/__tests__`
+
+Docs:
+
+- `docs/guides/streams.md`
+- `agent.md` stream and pipeline sections
+
+## HTTP
+
+Paths:
+
+- `src/http`
+- `src/http/defaultClient.ts`
+- `src/http/server.ts`
+- `src/http/retry`
+- `src/http/lifecycle`
+- `src/http/compression`
+- `src/http/adaptiveLimiter`
+- `src/http/prewarm`
+- `src/http/optics`
+
+Purpose:
+
+- Provide a lazy, cancelable HTTP client on top of `Async`.
+- Expose `makeDefaultHttpClient` as the one-stop default entrypoint.
+- Provide a first-party HTTP server MVP with a Node adapter, effect router,
+  schema validation, observability integration, and `Resource` lifecycle.
+- Keep wire, content, metadata, lifecycle, retry, compression, batching,
+  pre-warming, adaptive concurrency, tracing, server, and validation concerns
+  separated.
+
+Read first:
+
+- `src/http/client.ts`
+- `src/http/httpClient.ts`
+- `src/http/defaultClient.ts`
+- `src/http/server.ts`
+- `src/http/index.ts`
+- `src/http/lifecycle/lifecycleClient.ts`
+- `src/http/lifecycle/batch.ts`
+- `src/http/retry/retry.ts`
+- `src/http/compression/middleware.ts`
+- `src/http/adaptiveLimiter/adaptiveLimiter.ts`
+- `src/http/prewarm/prewarmManager.ts`
+
+Tests:
+
+- `src/http/__tests__`
+- `src/http/lifecycle/__tests__`
+- `src/http/prewarm/__tests__`
+- `src/http/adaptiveLimiter/__tests__`
+
+Docs:
+
+- `docs/http.md`
+- `docs/production-readiness.md`
+- `src/http/README.md`
+- `src/http/lifecycle/README.md`
+- `src/http/prewarm/README.md`
+
+## Observability Export
+
+Paths:
+
+- `src/observability`
+- `src/core/runtime/events.ts`
+- `src/core/runtime/tracingSink.ts`
+
+Purpose:
+
+- Export runtime metrics, logs, and spans out of process.
+- Keep Prometheus/OTLP formatting dependency-free and backend-neutral.
+- Provide effect-level span/log-context helpers on top of fiber context.
+
+Read first:
+
+- `src/observability/index.ts`
+- `src/observability/metrics.ts`
+- `src/observability/logs.ts`
+- `src/observability/traces.ts`
+- `src/observability/traceContext.ts`
+- `src/observability/request.ts`
+- `src/observability/exportPipeline.ts`
+- `src/observability/sampling.ts`
+- `src/observability/redaction.ts`
+- `src/observability/cardinality.ts`
+- `src/observability/adapters.ts`
+- `src/observability/config.ts`
+- `src/observability/server.ts`
+
+Tests:
+
+- `src/observability/__tests__`
+
+Docs:
+
+- `docs/observability.md`
+- `docs/observability-framework-examples.md`
+- `docs/observability-collector-smoke.md`
+- `docs/otel-collector-smoke.yaml`
+
+## Performance Profiler
+
+Paths:
+
+- `src/perf`
+- `docs/performance-profiler.md`
+
+Purpose:
+
+- Profile runtime primitives, HTTP layer overhead, memory retention, and
+  observability cost using dependency-free local workloads.
+- Provide importable report APIs plus `npm run perf`, `npm run perf:json`,
+  `npm run perf:history`, `npm run benchmark:perf`, and the `brass-perf`
+  package binary.
+- Persist compact perf history to `.brass/perf-history/runs.jsonl` and named
+  baselines to `.brass/perf-history/baselines`.
+- Keep profiler code outside core because it depends on runtime, HTTP, and
+  observability modules.
+
+Read first:
+
+- `src/perf/index.ts`
+- `src/perf/report.ts`
+- `src/perf/httpProfiler.ts`
+- `src/perf/httpMemoryLab.ts`
+- `src/perf/history.ts`
+- `src/perf/runtimeProfiler.ts`
+- `src/perf/runtimeAb.ts`
+- `src/perf/runtimeSoak.ts`
+- `src/perf/runtimeDiagnostics.ts`
+- `src/perf/budget.ts`
+- `src/perf/recommendations.ts`
+
+Tests:
+
+- `src/perf/__tests__`
+
+Docs:
+
+- `docs/performance-profiler.md`
+
+## Brass Agent
+
+Paths:
+
+- `src/agent/cli`
+- `src/agent/core`
+- `src/agent/node`
+- `src/agent/tools`
+- `src/agent/llm`
+- `extensions/vscode-brass-agent`
+
+Purpose:
+
+- Inspect workspaces, discover commands/context, ask an LLM for patches, apply
+  or roll back changes under policy, and expose CLI/VS Code surfaces.
+
+Read first:
+
+- `src/agent/core/runAgent.ts`
+- `src/agent/core/contextDiscovery.ts`
+- `src/agent/core/projectCommands.ts`
+- `src/agent/core/projectProfile.ts`
+- `src/agent/cli/main.ts`
+
+Docs:
+
+- `docs/agent-boundaries.md`
+- `docs/agent-project-intelligence.md`
+- `docs/agent-context-discovery.md`
+- `docs/agent-cli.md`
+- `docs/agent-vscode-install.md`
+
+## WASM
+
+Paths:
+
+- `crates/brass-runtime-wasm-engine`
+- `src/core/runtime/engine/WasmFiberEngine.ts`
+- `src/core/runtime/wasmModule.ts`
+- `src/http/wasmPermitPool.ts`
+- `src/http/retry/wasmRetryPlanner.ts`
+- `wasm/pkg` generated package output
+
+Purpose:
+
+- Provide strict WASM-backed state machines/engine pieces.
+- Do not silently fall back to TypeScript when a caller requests WASM.
+
+Docs:
+
+- `docs/wasm-fiber-engine.md`
+- `docs/wasm-scheduler-state-machine.md`
+- `docs/wasm-bounded-queues.md`
+- `docs/wasm-engine-observability-benchmarks.md`
+
+## Benchmarks
+
+Paths:
+
+- `src/benchmarks`
+- `src/core/runtime/bench`
+
+Purpose:
+
+- Track runtime and HTTP lifecycle overhead.
+- Run the standard benchmark surface, including heap-per-suspended-fiber, from
+  `npm run benchmark`.
+- Run the focused Runtime Performance Track with `npm run benchmark:runtime`
+  and its regression budget with `npm run benchmark:runtime:budget`.
+- Run the complete performance profiler JSON surface with
+  `npm run benchmark:perf`.
+- Run runtime-only A/B and soak checks with `npm run perf:runtime:ab`,
+  `npm run perf:runtime:soak`, and `npm run perf:runtime:budget`.
+- Run HTTP retained-memory checks with `npm run perf:http:memory`.
+- Record comparable local profiler history with `npm run perf:history` or
+  `npm run perf -- --record-history --save-baseline NAME`.
+- Keep benchmark thresholds separate from correctness tests.
+
+Commands:
+
+- `npm run benchmark`
+- `npm run benchmark:json`
+- `npm run benchmark:runtime`
+- `npm run benchmark:runtime:budget`
+- `npm run benchmark:perf`
+- `npm run perf:runtime:ab`
+- `npm run perf:runtime:soak`
+- `npm run perf:runtime:budget`
+- `npm run perf:http:memory`
+- `npm run perf:history`
+
+## Where to start by task
+
+- Runtime semantics: start in `docs/ai/INVARIANTS.md`, then `asyncEffect.ts`,
+  `fiber.ts`, `runtime.ts`, and adjacent tests.
+- Cancellation bug: start in `scope.ts`, `fiber.ts`, `runtime.ts`, and
+  `docs/cancellation.md`.
+- Stream bug: start in `stream.ts`, `queue.ts`, `buffer.ts`, and stream tests.
+- HTTP behavior: start in `client.ts`, `httpClient.ts`, relevant middleware,
+  and `src/http/__tests__`.
+- HTTP compression: start in `src/http/compression/middleware.ts` and
+  `src/http/__tests__/compression.property.test.ts`.
+- HTTP batching: start in `src/http/lifecycle/batch.ts` and
+  `src/http/lifecycle/__tests__/batch.property.test.ts`.
+- HTTP prewarm: start in `src/http/prewarm/prewarmManager.ts` and
+  `src/http/prewarm/__tests__/prewarmManager.test.ts`.
+- HTTP adaptive concurrency: start in `src/http/adaptiveLimiter/adaptiveLimiter.ts`
+  and `src/http/adaptiveLimiter/__tests__/`.
+- Agent behavior: start in `src/agent/core`, then CLI/node adapters.
+- Export/package issue: start in `package.json`, `tsup.config.ts`, `src/index.ts`,
+  `src/http/index.ts`, and `src/agent/index.ts`.