From 75fb29ffe6338c4ab9eb2535c08fdab43aee2ab9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 11:38:25 +0100 Subject: [PATCH] docs: refresh provider sdk hook docs --- docs/plugins/sdk-overview.md | 5 +- docs/plugins/sdk-provider-plugins.md | 92 +++++++++++++++++++--------- 2 files changed, 67 insertions(+), 30 deletions(-) diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index c876dfd2a57..b9ced18bd08 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -79,10 +79,11 @@ subpaths is in `scripts/lib/plugin-sdk-entrypoints.json`. | --- | --- | | `plugin-sdk/cli-backend` | CLI backend defaults + watchdog constants | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` | - | `plugin-sdk/provider-model-shared` | `normalizeModelCompat` | + | `plugin-sdk/provider-model-shared` | `normalizeModelCompat`, `buildProviderReplayFamilyHooks` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog` | + | `plugin-sdk/provider-tools` | `buildProviderToolCompatFamilyHooks`, Gemini schema helpers | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` and similar | - | `plugin-sdk/provider-stream` | Stream wrapper types | + | `plugin-sdk/provider-stream` | Stream wrapper types + provider stream wrappers | | `plugin-sdk/provider-onboard` | Onboarding config patch helpers | | `plugin-sdk/global-singleton` | Process-local singleton/map/cache helpers | diff --git a/docs/plugins/sdk-provider-plugins.md b/docs/plugins/sdk-provider-plugins.md index b032c8d28d6..4a98a39f17a 100644 --- a/docs/plugins/sdk-provider-plugins.md +++ b/docs/plugins/sdk-provider-plugins.md @@ -242,6 +242,36 @@ API key auth, and dynamic model resolution. Most providers only need `catalog` + `resolveDynamicModel`. Add hooks incrementally as your provider requires them. + Shared helper builders now cover the most common replay/tool-compat + families, so plugins usually do not need to hand-wire each hook one by one: + + ```typescript + import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; + import { buildProviderToolCompatFamilyHooks } from "openclaw/plugin-sdk/provider-tools"; + import { createGoogleThinkingPayloadWrapper } from "openclaw/plugin-sdk/provider-stream"; + + const GOOGLE_FAMILY_HOOKS = { + ...buildProviderReplayFamilyHooks({ family: "google-gemini" }), + wrapStreamFn: (ctx) => + createGoogleThinkingPayloadWrapper(ctx.streamFn, ctx.thinkingLevel), + ...buildProviderToolCompatFamilyHooks("gemini"), + }; + + api.registerProvider({ + id: "acme-gemini-compatible", + // ... + ...GOOGLE_FAMILY_HOOKS, + }); + ``` + + Available replay families today: + + - `openai-compatible` + - `anthropic-by-model` + - `google-gemini` + - `passthrough-gemini` + - `hybrid-anthropic-openai` + For providers that need a token exchange before each inference call: @@ -320,34 +350,40 @@ API key auth, and dynamic model resolution. | 1 | `catalog` | Model catalog or base URL defaults | | 2 | `applyConfigDefaults` | Provider-owned global defaults during config materialization | | 3 | `normalizeConfig` | Normalize `models.providers.` config | - | 4 | `resolveDynamicModel` | Accept arbitrary upstream model IDs | - | 5 | `prepareDynamicModel` | Async metadata fetch before resolving | - | 6 | `normalizeResolvedModel` | Transport rewrites before the runner | - | 7 | `capabilities` | Transcript/tooling metadata (data, not callable) | - | 8 | `prepareExtraParams` | Default request params | - | 9 | `wrapStreamFn` | Custom headers/body wrappers | - | 10 | `resolveTransportTurnState` | Native per-turn headers/metadata | - | 11 | `resolveWebSocketSessionPolicy` | Native WS session headers/cool-down | - | 12 | `formatApiKey` | Custom runtime token shape | - | 13 | `refreshOAuth` | Custom OAuth refresh | - | 14 | `buildAuthDoctorHint` | Auth repair guidance | - | 15 | `matchesContextOverflowError` | Provider-owned overflow detection | - | 16 | `classifyFailoverReason` | Provider-owned rate-limit/overload classification | - | 17 | `isCacheTtlEligible` | Prompt cache TTL gating | - | 18 | `buildMissingAuthMessage` | Custom missing-auth hint | - | 19 | `suppressBuiltInModel` | Hide stale upstream rows | - | 20 | `augmentModelCatalog` | Synthetic forward-compat rows | - | 21 | `isBinaryThinking` | Binary thinking on/off | - | 22 | `supportsXHighThinking` | `xhigh` reasoning support | - | 23 | `resolveDefaultThinkingLevel` | Default `/think` policy | - | 24 | `isModernModelRef` | Live/smoke model matching | - | 25 | `prepareRuntimeAuth` | Token exchange before inference | - | 26 | `resolveUsageAuth` | Custom usage credential parsing | - | 27 | `fetchUsageSnapshot` | Custom usage endpoint | - | 28 | `onModelSelected` | Post-selection callback (e.g. telemetry) | - | 29 | `buildReplayPolicy` | Custom transcript policy (e.g. thinking-block stripping) | - | 30 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup | - | 31 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner | + | 4 | `applyNativeStreamingUsageCompat` | Native streaming-usage compat rewrites for config providers | + | 5 | `resolveConfigApiKey` | Provider-owned env-marker auth resolution | + | 6 | `resolveDynamicModel` | Accept arbitrary upstream model IDs | + | 7 | `prepareDynamicModel` | Async metadata fetch before resolving | + | 8 | `normalizeResolvedModel` | Transport rewrites before the runner | + | 9 | `capabilities` | Legacy static capability bag; compatibility only | + | 10 | `buildReplayPolicy` | Custom transcript replay/compaction policy | + | 11 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup | + | 12 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner | + | 13 | `normalizeToolSchemas` | Provider-owned tool-schema cleanup before registration | + | 14 | `inspectToolSchemas` | Provider-owned tool-schema diagnostics | + | 15 | `resolveReasoningOutputMode` | Tagged vs native reasoning-output contract | + | 16 | `prepareExtraParams` | Default request params | + | 17 | `createStreamFn` | Fully custom StreamFn transport | + | 18 | `wrapStreamFn` | Custom headers/body wrappers on the normal stream path | + | 19 | `resolveTransportTurnState` | Native per-turn headers/metadata | + | 20 | `resolveWebSocketSessionPolicy` | Native WS session headers/cool-down | + | 21 | `formatApiKey` | Custom runtime token shape | + | 22 | `refreshOAuth` | Custom OAuth refresh | + | 23 | `buildAuthDoctorHint` | Auth repair guidance | + | 24 | `matchesContextOverflowError` | Provider-owned overflow detection | + | 25 | `classifyFailoverReason` | Provider-owned rate-limit/overload classification | + | 26 | `isCacheTtlEligible` | Prompt cache TTL gating | + | 27 | `buildMissingAuthMessage` | Custom missing-auth hint | + | 28 | `suppressBuiltInModel` | Hide stale upstream rows | + | 29 | `augmentModelCatalog` | Synthetic forward-compat rows | + | 30 | `isBinaryThinking` | Binary thinking on/off | + | 31 | `supportsXHighThinking` | `xhigh` reasoning support | + | 32 | `resolveDefaultThinkingLevel` | Default `/think` policy | + | 33 | `isModernModelRef` | Live/smoke model matching | + | 34 | `prepareRuntimeAuth` | Token exchange before inference | + | 35 | `resolveUsageAuth` | Custom usage credential parsing | + | 36 | `fetchUsageSnapshot` | Custom usage endpoint | + | 37 | `onModelSelected` | Post-selection callback (e.g. telemetry) | For detailed descriptions and real-world examples, see [Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).