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.
- 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. 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.
- 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.
- 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.
- 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.