Docs: tighten migration plan wording

This commit is contained in:
Gustavo Madeira Santana 2026-03-15 18:26:54 +00:00
parent 8dbef2c431
commit 3a0b7ecb40
No known key found for this signature in database
4 changed files with 14 additions and 14 deletions

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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