docs(agents): tighten provider boundary guidance

extensions/AGENTS.md

@@ -36,6 +36,21 @@ third-party plugins see.
   matching `src/plugin-sdk/<id>.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
 

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

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