AGENTS.md

1# Plugins Boundary
2 
3This directory owns plugin discovery, manifest validation, loading, registry
4assembly, and contract enforcement.
5 
6## Public Contracts
7 
8- Docs:
9  - `docs/plugins/architecture.md`
10  - `docs/plugins/manifest.md`
11  - `docs/plugins/sdk-overview.md`
12  - `docs/plugins/sdk-entrypoints.md`
13- Definition files:
14  - `src/plugins/types.ts`
15  - `src/plugins/runtime/types.ts`
16  - `src/plugins/contracts/registry.ts`
17  - `src/plugins/public-surface-loader.ts`
18  - `src/plugins/public-surface-runtime.ts`
19  - `src/plugins/provider-public-artifacts.ts`
20  - `src/plugins/web-provider-public-artifacts.ts`
21 
22## Boundary Rules
23 
24- Keep control-plane and runtime-plane concerns separate:
25  discovery, manifest parsing, config validation, setup/onboarding hints, and
26  activation planning belong to the control plane; actual plugin execution
27  belongs to runtime resolution.
28- Preserve manifest-first behavior: discovery, config validation, and setup
29  should work from metadata before plugin runtime executes.
30- Cache concept: gateway plugin metadata is stable while gateway runs. Reuse
31  current snapshots, install records, discovery, lookup tables, and bounded
32  process caches; avoid per-call stat/read/hash freshness. Plugin metadata
33  changes require restart or explicit plugin owner reload/install/doctor flow.
34  No broad persistent caches; lifecycle-owned facts only, test-clearable.
35- Keep loader behavior aligned with the documented Plugin SDK and manifest
36  contracts. Do not create private backdoors that bundled plugins can use but
37  external plugins cannot.
38- Preserve laziness in discovery and activation flows. Loader, registry, and
39  public-artifact changes must not eagerly import bundled plugin runtime barrels
40  when metadata, light exports, or typed contracts are sufficient.
41- If a plugin exposes separate light and heavy runtime surfaces, keep discovery,
42  inventory, and setup-state checks on the light path until actual execution
43  needs the heavy module.
44- If a loader or registry change affects plugin authors, update the public SDK,
45  docs, and contract tests instead of relying on incidental internals.
46- Prefer explicit activation planning from manifest/descriptor ownership over
47  “load everything in this scope” behavior. Broad registry materialization
48  should be the exception, not the design center.
49- Do not normalize "plugin-owned" into "core-owned" by scattering direct reads
50  of `plugins.entries.<id>.config` through unrelated core paths. Prefer generic
51  helpers, plugin runtime hooks, manifest metadata, and explicit auto-enable
52  wiring.
53- When plugin-owned tools or provider fallbacks need core participation, keep
54  the contract generic and honor plugin disablement plus SecretRef semantics.
55- Keep contract loading and contract tests on the dedicated bundled registry
56  path. Do not make contract validation depend on activating providers through
57  unrelated production resolution flows.
58- Prefer shared provider-family helpers over ad hoc policy in plugin registry
59  hooks. If multiple providers need the same replay policy, tool compat, stream
60  wrapper composition, or payload patch behavior, centralize that helper before
61  adding another plugin-local lambda.
62- Keep provider policy layers separated:
63  auth/catalog/onboarding stay plugin-owned,
64  transport/replay/tool compat families belong in shared helpers,
65  registry/runtime code should compose those layers rather than re-encoding
66  policy inline.
67- When a provider hook grows a nested chain of wrapper composition or repeated
68  compat flags, treat that as a regression signal. Extract the shared helper or
69  composer instead of letting one more plugin carry a near-copy.
70- Treat mutable global runtime registry state as compatibility scaffolding, not
71  the desired source of truth for request-time execution. Prefer immutable or
72  request-scoped handles when adding new runtime flows.
73- If setup, discovery, or doctor flows need plugin runtime, make that need
74  explicit and narrow. Do not let cold control-plane paths quietly import broad
75  runtime surfaces.
76- Resolver and public-surface loader tests must use generated tiny plugin
77  fixtures for broad `api.js` / `runtime-api.js` fallback behavior. Do not point
78  those tests at real bundled plugin source APIs just to prove path resolution.
79 
80## Verification
81 
82- If you touch loader, registry, activation, or public-artifact code that can
83  change bundled plugin import fanout, run `pnpm build`.
84- If the change can alter bundled plugin startup cost, re-profile the affected
85  plugin entrypoint with:
86  `OPENCLAW_LOCAL_CHECK=0 node scripts/profile-extension-memory.mjs --extension <id> --skip-combined --concurrency 1`
87