From 3a0b7ecb403dcc657cc5fb7fa9dbbdc08dd42f8e Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sun, 15 Mar 2026 18:26:54 +0000 Subject: [PATCH] Docs: tighten migration plan wording --- ...openclaw-capability-catalog-and-arbitration-spec.md | 8 ++++---- .../openclaw-extension-contribution-schema-spec.md | 8 ++++---- .../openclaw-extension-host-implementation-guide.md | 2 +- .../openclaw-kernel-extension-host-transition-plan.md | 10 +++++----- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md b/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md index d006d915714..99bafe23045 100644 --- a/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md @@ -552,7 +552,7 @@ The same model should be available for other subsystem runtimes discovered durin - video understanding - text-to-speech -Selection rules for these subsystem runtimes should preserve the useful parts of provider-capability prototypes: +Selection rules for these subsystem runtimes should preserve these required behaviors: - capability-based selection - normalized provider ids @@ -563,7 +563,7 @@ Architecture rule: - keep those selection and envelope rules inside host-owned subsystem runtime registries for typed backend families - do not widen provider-integration or legacy plugin-provider APIs into a universal surface for unrelated runtime subsystems -- if search is agent-visible, publish it through canonical tool catalogs; reserve runtime-backend modeling for search backends that are consumed internally by the host or another subsystem +- if search is agent-visible, publish it through canonical tool catalogs; reserve `capability.runtime-backend` for search backends that are consumed internally by the host or another subsystem ## Catalog Publication @@ -609,7 +609,7 @@ Capability selection must emit structured events for: - diffs becomes an agent-visible tool family plus a host-managed route surface from `extensions/diffs/index.ts:27` - provider integration from `extensions/google-gemini-cli-auth/index.ts:24` becomes operator-visible setup and auth capabilities - embedding, media-understanding, and TTS provider overrides should become runtime-internal subsystem registries rather than remaining part of a universal plugin-provider API -- extension-backed web search should become an agent-visible tool family unless it is only an internal backend feeding another host-owned surface +- extension-backed web search should become an agent-visible tool family unless it is only a runtime-internal backend feeding another host-owned surface - voice-call from `extensions/voice-call/index.ts:230` becomes a mix of agent-visible actions, runtime providers, and operator surfaces - ACP backend registration from `extensions/acpx/src/service.ts:55` becomes runtime-internal backend arbitration - context-engine registration becomes runtime-internal slot arbitration from `src/context-engine/registry.ts:60` @@ -626,7 +626,7 @@ Capability selection must emit structured events for: 7. Add provider selection logic for the broader messaging action family before migrating all channels. 8. Add runtime-backend and context-engine arbitration using the same rank and slot model where appropriate. 9. Add host-owned embedding, media-understanding, and TTS subsystem registries with explicit capability routing and built-in fallback policy. -10. Decide whether extension-backed search needs only canonical tool publication or also a host-owned internal search-backend registry, and keep those two cases distinct. +10. Decide whether extension-backed search needs only canonical tool publication or also a host-owned runtime registry for internal search backends, and keep those two cases distinct. 11. Ensure lightweight setup catalogs can be built from static descriptors alone. 12. Add a reviewed core registry for canonical action families and document how new ids are introduced. 13. Record catalog and arbitration parity for `thread-ownership` first and `telegram` second before broader rollout. diff --git a/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md b/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md index 6a99bfed129..95c2fff3871 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md @@ -536,7 +536,7 @@ Scope rule: - this family is specifically for chat or model-provider discovery, setup, auth, and post-selection lifecycle - agent-visible search should not be folded into this family only because it may call remote providers under the hood - non-chat subsystem providers such as embeddings, transcription, image understanding, video understanding, and TTS should not be folded into this family only because they also use remote providers -- those subsystem runtimes should use typed runtime contributions or `capability.runtime-backend` with subsystem-specific capability metadata +- those subsystem runtimes should use typed runtime contributions registered in host-owned runtime registries, usually under `capability.runtime-backend` with subsystem-specific capability metadata ### `capability.memory` @@ -642,8 +642,8 @@ Required descriptor metadata: First-cut constraint: -- the first interactive runtime cut may be validated on Telegram and Discord because those are the immediate proven needs -- that is a rollout choice only; the contract itself must stay generic, host-owned, and kernel-agnostic rather than becoming Telegram- or Discord-specific handler APIs +- the first interactive runtime cut should be validated on Telegram and Discord if they remain the highest-priority channels for parity +- that is rollout order only; the contract itself must stay generic, host-owned, and kernel-agnostic rather than becoming Telegram- or Discord-specific handler APIs Ownership rule: @@ -707,7 +707,7 @@ Required metadata for these subsystem runtimes: - fallback policy - override policy when a built-in implementation already exists -Useful harvested behavior: +Retained behavior requirements: - capability-based routing is worth keeping - typed host-injected request fields such as `apiKey`, `baseUrl`, `headers`, `timeoutMs`, and `fetchFn` are worth keeping diff --git a/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md b/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md index beaf9d9a79e..a405df50d94 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md @@ -228,7 +228,7 @@ Recent plan refinements: - it now explicitly treats inbound claim as a canonical ingress-stage concern rather than a permanent plugin-era hook shape - it now explicitly treats Telegram and Discord as the first validated rollout targets for interactive control surfaces while keeping the underlying contracts generic, host-owned, and kernel-agnostic - it now explicitly treats embeddings, media understanding, and TTS as host-owned subsystem runtimes with capability routing, typed request envelopes, provider-id normalization, and fallback policy -- it now explicitly rejects widening the legacy `registerProvider(...)` or `ProviderPlugin` surface into a universal runtime API, even when harvesting useful capability-routing ideas from provider-capability prototypes +- it now explicitly rejects widening the legacy `registerProvider(...)` or `ProviderPlugin` surface into a universal runtime API while retaining capability routing, typed request envelopes, provider-id normalization, and fallback behavior where those are part of the target model - it now explicitly treats extension-backed search as either a canonical tool contribution or a host-owned runtime backend depending on whether the search surface is agent-visible ## Implementation Order diff --git a/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md b/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md index b02b3590e34..b2cfa3a1f23 100644 --- a/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md +++ b/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md @@ -548,9 +548,9 @@ Suggested mapping: - `registerChannel(...)` -> `adapter.runtime` plus lightweight dock metadata and optional `surface.config`, `surface.status`, `surface.setup` - `registerProvider(...)` -> `capability.provider-integration` plus optional setup and auth surfaces -- plugin-provided embeddings, transcription, image or video understanding, and TTS -> typed subsystem runtime contributions or `capability.runtime-backend`, not a widened `registerProvider(...)` end state +- plugin-provided embeddings, transcription, image or video understanding, and TTS -> typed subsystem runtime contributions registered in host-owned runtime registries, usually under `capability.runtime-backend`, not a widened `registerProvider(...)` end state - extension-backed search exposed to the agent -> `capability.agent-tool` -- extension-backed search consumed only by a host or subsystem -> typed runtime contribution or `capability.runtime-backend` +- extension-backed search consumed only by a host or subsystem -> typed runtime contribution registered in a host-owned runtime registry, usually under `capability.runtime-backend` - `registerTool(...)` -> `capability.agent-tool` - `registerCommand(...)` -> `capability.control-command` - `on(...)` returning context or side effects -> `capability.context-augmenter` or `capability.event-handler` @@ -588,7 +588,7 @@ Additional migration rule: - conversation binding, interactive callback routing, and inbound claim are real runtime needs, but they must not be solved by turning `src/plugins/*` into the permanent public architecture - bind approvals, callback namespace routing, and bound-ingress short-circuit behavior belong to host-owned surfaces and canonical pipeline stages -- first-cut interactive channel controls may be validated first on Telegram and Discord, but the long-term contract must remain generic, adapter-runtime, host-owned, and kernel-agnostic rather than product-shaped kernel APIs +- first-cut interactive channel controls should be validated first on Telegram and Discord if they remain the highest-priority parity targets, but the long-term contract must remain generic, adapter-runtime, host-owned, and kernel-agnostic rather than product-shaped kernel APIs ## 1d. Lightweight descriptors and distribution metadata @@ -835,9 +835,9 @@ Scope rule: - `capability.provider-integration` is for chat or model-provider discovery, setup, auth, and post-selection lifecycle - agent-visible search should not be folded into that family only because it may call remote services - embeddings, transcription, image understanding, video understanding, and TTS should not be folded into that family just because they also use remote providers -- those subsystem runtimes should use host-owned capability routing and typed runtime registries or runtime-backend families instead +- those subsystem runtimes should use host-owned capability routing plus typed runtime contributions registered in host-owned runtime registries, usually under `capability.runtime-backend` -Useful ideas harvested from provider-capability validation: +Retained behavior requirements for subsystem runtimes: - capability-based selection is good - typed request envelopes with host-injected `apiKey`, `baseUrl`, `headers`, `timeoutMs`, and `fetchFn` are good