src/agents/AGENTS.md

# Agent Runtime And Tests

This directory owns agent assembly, run authority, and their focused tests.
Agent tests are often import-bound; treat slow files as architecture signals,
not just runner noise.

## Guardrails

- Benchmark before and after performance edits. Prefer existing grouped
  artifacts when comparing suites, or use `/usr/bin/time -l pnpm test <file>`
  for a scoped hotspot.
- If a test only needs schema, capability, routing, or static discovery data,
  do not cold-load full bundled plugin/channel/provider runtime. Add or reuse a
  lightweight typed artifact and keep full runtime as a fallback.
- Keep expensive bootstrap, embedded runner, provider, plugin, and channel
  runtime work behind dependency injection or narrow helpers so tests can cover
  behavior without starting the whole runtime.
- Treat channel/plugin lookups inside agent hot paths as suspect. If the code
  only needs target parsing, peer-kind inference, setup hints, or static
  descriptors, use a local pure helper or lightweight public artifact before
  reaching for `getChannelPlugin()` / bundled runtime fallback.
- In spawn/session/requester-origin logic, keep routing and delivery-context
  normalization deterministic and runtime-free. Add explicit parser coverage for
  channel-specific prefixes instead of loading a channel plugin just to classify
  a target.
- Prepared model/tool selection follows the plugin owner's
  [availability and selection contract](../plugins/AGENTS.md#availability-and-selection).
  Keep network discovery outside repeated selection; this does not forbid the
  model or tool request that the user actually asked to execute.
- If moving coverage out of a slow integration test, preserve the exact
  production composition in a named helper and test that helper. Do not remove
  the behavior proof just because the old proof was slow.
- Avoid broad `importOriginal()` partial mocks and module resets in hot agent
  tests. Use explicit mock factories, one-time imports, and reset only the
  state the test mutates.

## Client Capability Scope

- Tools that act through an attached client derive availability from the current
  connection/session capability contract. Backend process flags describe the
  host, not what a remote client supports; one backend can serve different clients.
- Keep client-dependent capability caches within their connection/session
  lifecycle. Process-stable provider metadata can be shared; a cached answer for
  one client's capabilities cannot select another client's tool set.
- Availability is not authorization. Preserve server validation, tool grants,
  and live execution authority. Backend-owned tools that produce portable
  artifacts do not require a client merely because the UI can display the result.
- Verify differing clients on one backend and a supported remote client without
  a backend-local UI flag. Retired client capabilities must not survive through
  a cached tool selection.

## Run Authority

- Prepare one admitted run context after runtime selection. Retries and fallbacks reuse that exact context; they do not mint replacement authority.
- The lifecycle owner closes admission in `finally`. Terminal, error, cancellation, and unsupported recovery paths must all release it.
- Harness host capabilities capture the exact admitted authority. Gate tool binding, preparation, execution, hooks, and approvals, and revalidate after awaited work before an allowed result crosses the action boundary.
- Retained tools, preparers, callbacks, and approval handles must fail after close, replacement, release, abort, claim loss, or lifecycle rotation.

## Verification

- For agent performance changes, record seconds and RSS before/after in the
  handoff or benchmark report.
- If the change touches lazy-loading, plugin runtime imports, or bundled
  artifacts, run `pnpm build`.