From e07d8fd20b954ffcacac7c4c480f73bcf8f39430 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sat, 4 Apr 2026 14:13:46 +0900 Subject: [PATCH] docs(agents): tighten provider boundary guidance --- extensions/AGENTS.md | 15 +++++++++++++++ src/plugin-sdk/AGENTS.md | 15 +++++++++++++++ src/plugins/AGENTS.md | 12 ++++++++++++ 3 files changed, 42 insertions(+) diff --git a/extensions/AGENTS.md b/extensions/AGENTS.md index 2ee72ff767a..1c2dcff51bc 100644 --- a/extensions/AGENTS.md +++ b/extensions/AGENTS.md @@ -36,6 +36,21 @@ third-party plugins see. matching `src/plugin-sdk/.ts` facade. - If core or core tests need a bundled plugin helper, export it from `api.ts` first instead of letting them deep-import extension internals. +- For provider plugins, keep auth, onboarding, catalog selection, and + vendor-only product behavior local to the plugin. Do not move those into + core just because two providers look similar. +- Before adding a new provider-local `wrapStreamFn`, `buildReplayPolicy`, + `normalizeToolSchemas`, `inspectToolSchemas`, or compat patch helper, check + whether the same behavior already exists through `openclaw/plugin-sdk/*`. + Reuse shared family helpers first. +- If two bundled providers share the same replay policy shape, tool-schema + compat rewrite, payload patch, or stream-wrapper chain, stop copying the + logic. Extract one shared helper and migrate both call sites in the same + change. +- Prefer named provider-family helpers over repeating raw option bags. If a + provider needs OpenAI-style Anthropic tool payload compat, Gemini schema + cleanup, or an XAI compat patch, use a named shared helper instead of + inlining the policy knobs again. ## Expanding The Boundary diff --git a/src/plugin-sdk/AGENTS.md b/src/plugin-sdk/AGENTS.md index 1603675eaea..d91b125886a 100644 --- a/src/plugin-sdk/AGENTS.md +++ b/src/plugin-sdk/AGENTS.md @@ -41,6 +41,17 @@ can affect bundled plugins and third-party plugins. `api.ts` or `runtime-api.ts` plus generic SDK capabilities. Do not add a provider-named `src/plugin-sdk/.ts` seam just to make core aware of a bundled channel's private helpers. +- For provider work, prefer family-level seams over provider-specific seams. + Shared helpers should describe a reusable behavior such as replay policy, + tool-schema compat, payload normalization, stream-wrapper composition, or + transport decoration. Avoid adding a new SDK export that only wraps one + provider's local implementation unless there is already a second consumer. +- Prefer named helpers over raw options objects when the options encode a + stable contract. Example: export a helper for "OpenAI-style Anthropic tool + payload compat" instead of making every plugin pass the same mode flags. +- Keep transport/runtime policy and plugin-facing helpers aligned. If the same + behavior is used in plugin registration and in core runtime paths, expose one + shared helper instead of letting the two paths drift. ## Verification @@ -62,4 +73,8 @@ can affect bundled plugins and third-party plugins. - If a bundled channel/helper need crosses package boundaries, first ask whether the need is truly generic. If yes, add a narrow generic subpath. If not, keep it plugin-local through `api.ts` / `runtime-api.ts`. +- When expanding provider-facing seams, update or add the matching narrow tests + that lock the contract: Plugin SDK baseline/export checks for public subpaths + and the most direct provider/plugin tests for the behavior you are + centralizing. - Breaking removals or renames are major-version work, not drive-by cleanup. diff --git a/src/plugins/AGENTS.md b/src/plugins/AGENTS.md index efba8d85a2f..a414a5db256 100644 --- a/src/plugins/AGENTS.md +++ b/src/plugins/AGENTS.md @@ -40,6 +40,18 @@ assembly, and contract enforcement. - Keep contract loading and contract tests on the dedicated bundled registry path. Do not make contract validation depend on activating providers through unrelated production resolution flows. +- Prefer shared provider-family helpers over ad hoc policy in plugin registry + hooks. If multiple providers need the same replay policy, tool compat, stream + wrapper composition, or payload patch behavior, centralize that helper before + adding another plugin-local lambda. +- Keep provider policy layers separated: + auth/catalog/onboarding stay plugin-owned, + transport/replay/tool compat families belong in shared helpers, + registry/runtime code should compose those layers rather than re-encoding + policy inline. +- When a provider hook grows a nested chain of wrapper composition or repeated + compat flags, treat that as a regression signal. Extract the shared helper or + composer instead of letting one more plugin carry a near-copy. ## Verification