AGENTS.md

1# Plugin SDK Boundary
2 
3This directory is the public contract between plugins and core. Changes here
4can affect bundled plugins and third-party plugins.
5 
6## Source Of Truth
7 
8- Docs:
9  - `docs/plugins/sdk-overview.md`
10  - `docs/plugins/sdk-entrypoints.md`
11  - `docs/plugins/sdk-runtime.md`
12  - `docs/plugins/sdk-migration.md`
13  - `docs/plugins/architecture.md`
14- Definition files:
15  - `package.json`
16  - `scripts/lib/plugin-sdk-entrypoints.json`
17  - `scripts/lib/plugin-sdk-entries.mts`
18  - `src/plugin-sdk/api-baseline.ts`
19  - `src/plugin-sdk/plugin-entry.ts`
20  - `src/plugin-sdk/core.ts`
21  - `src/plugin-sdk/provider-entry.ts`
22 
23## Boundary Rules
24 
25- Host loads plugins; plugins should not reach through the SDK into arbitrary
26  host internals.
27- Prefer a small versioned host/kernel seam plus narrow documented SDK
28  entrypoints over broad convenience barrels.
29- Prefer narrow, purpose-built subpaths over broad convenience re-exports.
30- Do not expose implementation convenience from `src/channels/**`,
31  `src/agents/**`, `src/plugins/**`, or other internals unless you are
32  intentionally promoting a supported public contract.
33- Keep public SDK entrypoints cheap at module load. If a helper is only needed
34  on async paths such as send, monitor, probe, directory-live, login, or setup,
35  prefer a narrow `*.runtime` subpath over re-exporting it through a broad SDK
36  barrel that hot channel entrypoints import on startup.
37- Keep SDK facades acyclic. Do not add back-edge re-exports that route a
38  lightweight contract file back through heavier policy or runtime modules.
39- Do not mix static and dynamic imports for the same runtime surface when
40  shaping SDK seams. If a surface must stay lazy, keep the eager side on a
41  light contract file and the deferred side on a dedicated runtime subpath.
42- Prefer `api.runtime` or a focused SDK facade over telling extensions to reach
43  into host internals directly.
44- When core or tests need bundled plugin helpers, prefer the plugin package
45  `api.ts` or `runtime-api.ts` plus generic SDK capabilities. Do not add a
46  provider-named `src/plugin-sdk/<id>.ts` seam just to make core aware of a
47  bundled channel's private helpers.
48- Resolver/facade loader tests are the exception to broad source API coverage:
49  use generated tiny plugin fixtures for `api.js` / `runtime-api.js` fallback
50  behavior. Do not point those tests at real bundled plugin source APIs.
51- For provider work, prefer family-level seams over provider-specific seams.
52  Shared helpers should describe a reusable behavior such as replay policy,
53  tool-schema compat, payload normalization, stream-wrapper composition, or
54  transport decoration. Avoid adding a new SDK export that only wraps one
55  provider's local implementation unless there is already a second consumer.
56- Prefer named helpers over raw options objects when the options encode a
57  stable contract. Example: export a helper for "OpenAI-style Anthropic tool
58  payload compat" instead of making every plugin pass the same mode flags.
59- Keep transport/runtime policy and plugin-facing helpers aligned. If the same
60  behavior is used in plugin registration and in core runtime paths, expose one
61  shared helper instead of letting the two paths drift.
62- SDK subpaths should help callers resolve one capability or runtime need at a
63  time. Do not grow new surfaces that require broad runtime registry access as
64  the default path.
65- If a proposed SDK export mainly exists to let setup/config/control-plane code
66  execute plugin runtime, that is usually a boundary smell. Prefer metadata or
67  descriptor-driven control-plane seams first.
68 
69## Versioned Required Capabilities
70 
71- Always: when a shipped Plugin SDK parameter contract gains required host authority, introduce a versioned type that requires it. Keep the legacy type source-compatible for its documented deprecation window, and migrate every bundled/internal caller in the same change.
72- Always: keep host capabilities generic and closure-bound. Bind every exposed tool, preparer, callback, approval operation, and native-action surface; retained copies must fail after owner or capability closure, including closure during awaited policy work.
73- Never: treat legacy optionality as a capability-free runtime path, reconstruct host authority inside a plugin, or add provider-specific authority to the generic contract.
74- Never: hand-edit generated SDK baselines, declarations, hashes, or budgets. Regenerate them canonically.
75- Ask first: obtain SDK and security owner acceptance before shortening a compatibility window, making a shipped type source-incompatible, or widening a capability’s trust, authority, or persistence boundary.
76 
77## Verification
78 
79- If you touch SDK seams that affect lazy loading, hot channel entrypoints, or
80  bundled plugin import topology, run `pnpm build`.
81- If the change can alter bundled channel startup cost, also run the isolated
82  entrypoint profiler for the affected plugin:
83  `OPENCLAW_LOCAL_CHECK=0 node --import tsx scripts/profile-extension-memory.mts --extension <id> --skip-combined --concurrency 1`
84 
85## Expanding The Boundary
86 
87- SDK surface is too large. Do not add compat barrels, aliases, or fallback exports for convenience. Replace old entrypoints when cleaner.
88- Public third-party API is the only compat exception: document/version breaks, migrate ALL bundled/internal plugins first, then aggressively deprecate unused exports.
89- When adding or changing a public subpath, keep these aligned:
90  - docs in `docs/plugins/*`
91  - `scripts/lib/plugin-sdk-entrypoints.json`
92  - `scripts/lib/plugin-sdk-entries.mts`
93  - `package.json` exports
94  - API diff and export checks
95- If a bundled channel/helper need crosses package boundaries, first ask
96  whether the need is truly generic. If yes, add a narrow generic subpath. If
97  not, keep it plugin-local through `api.ts` / `runtime-api.ts`.
98- When expanding provider-facing seams, update or add the matching narrow tests
99  that lock the contract: Plugin SDK diff/export checks for public subpaths
100  and the most direct provider/plugin tests for the behavior you are
101  centralizing.
102- Breaking removals or renames are major-version work, not drive-by cleanup.
103