From 35e31ed35154df6731d0684a4811f20ce1d3c8a4 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sat, 18 Apr 2026 16:09:13 -0400 Subject: [PATCH] Docs: capture test performance guardrails --- src/agents/AGENTS.md | 8 ++++++++ src/channels/AGENTS.md | 11 +++++++++++ src/gateway/AGENTS.md | 7 +++++++ src/infra/outbound/AGENTS.md | 27 +++++++++++++++++++++++++++ test/helpers/channels/AGENTS.md | 7 +++++++ 5 files changed, 60 insertions(+) create mode 100644 src/infra/outbound/AGENTS.md diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index 0c8fb308d66..c1d96061b82 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -14,6 +14,14 @@ signals, not just runner noise. - 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. - 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. diff --git a/src/channels/AGENTS.md b/src/channels/AGENTS.md index 8a964673061..b224f546e05 100644 --- a/src/channels/AGENTS.md +++ b/src/channels/AGENTS.md @@ -32,6 +32,17 @@ import from this tree directly. - For core discovery paths used by Gateway or agent tools, prefer lightweight bundled-plugin artifacts first and full channel plugin loading only as a fallback. +- When a caller only needs already-registered plugin fixtures in a test, offer a + loaded-plugin-only mode instead of silently falling back to bundled runtime + materialization. +- Put target parsing, thread-binding hints, native command descriptors, message + tool descriptors, gateway auth bypass paths, and setup-promotion hints in + small plugin-owned helpers reused by both the full channel plugin and any + lightweight artifact. +- If a helper is called repeatedly by tests, install/reset the test plugin + registry in the same lifecycle scope as the runtime reset. A `beforeAll` + registry with `afterEach` runtime reset is a signal that later tests may fall + through to bundled/default runtime loading. - Do not mix static and dynamic imports for the same heavy module family across a channel boundary change. If the path should stay lazy, keep it lazy end to end. diff --git a/src/gateway/AGENTS.md b/src/gateway/AGENTS.md index 943b875b2e6..8341e39f132 100644 --- a/src/gateway/AGENTS.md +++ b/src/gateway/AGENTS.md @@ -14,6 +14,13 @@ runtime when they only need plugin-owned static descriptors. just to answer static questions. - If adding a new plugin-owned Gateway descriptor, add the core resolver, plugin artifact, and mirrored full-plugin export in the same change. +- In Gateway server tests, reuse suite-level servers, authenticated contexts, + and clients when the behavior under test does not require a fresh + connect/auth handshake. Reset runtime state explicitly instead of restarting + the whole server per case. +- Keep schedulers, pollers, and background loops disabled in manual-RPC tests + unless the test is specifically proving automatic scheduling or lifecycle + behavior. ## Verification diff --git a/src/infra/outbound/AGENTS.md b/src/infra/outbound/AGENTS.md new file mode 100644 index 00000000000..5839ea013b2 --- /dev/null +++ b/src/infra/outbound/AGENTS.md @@ -0,0 +1,27 @@ +# Outbound Test Performance + +Outbound helpers sit on hot reply, action, media, and channel contract paths. +Keep argument and payload tests narrow unless they are intentionally exercising +real delivery. + +## Guardrails + +- Prefer pure param/spec/normalization helpers for send-argument, media-source, + alias, and payload-shape coverage. Do not import real delivery runtimes when + the test only asserts normalized arguments. +- Avoid partial-real mocks with `importActual()` around broad outbound delivery + modules. Mock the exact seam under test, then cover the real delivery runtime + in a focused integration test. +- Before discovering plugin-owned media/action metadata, first check whether the + call actually includes plugin-owned params. Standard send params should not + trigger bundled channel message-tool discovery. +- Contract tests should reuse SDK/public helpers or narrow plugin-owned route + modules. Do not deep-load `runtime-api.ts` or `test-api.ts` barrels just to + access chunking, target parsing, or payload formatting helpers. + +## Verification + +- Benchmark the affected outbound test file before/after with + `pnpm test `. +- Run the closest media/action/payload contract test when changing a shared + outbound helper. diff --git a/test/helpers/channels/AGENTS.md b/test/helpers/channels/AGENTS.md index 9fcc4d89517..d1d4c2692f0 100644 --- a/test/helpers/channels/AGENTS.md +++ b/test/helpers/channels/AGENTS.md @@ -18,6 +18,13 @@ This file adds channel-specific rules on top of `test/helpers/AGENTS.md`. - If `vi.mock(...)` hoisting would evaluate the module id too early, use `vi.doMock(...)` with the resolved module id instead of falling back to a hardcoded path. +- For contract helpers, prefer minimal in-memory channel/plugin fixtures when + the contract only needs capabilities, session binding hooks, routing metadata, + or outbound payload helpers. Do not load broad `api.ts`, `runtime-api.ts`, or + `test-api.ts` barrels for incidental setup. +- If a bundled plugin parser is the contract under test, load the narrow module + that owns that parser or promote a small public artifact. Avoid pulling a full + extension barrel just to parse a target id. ## Intent