From 565f9bf2bd8a613de2768b01a0e589705c766b9e Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sun, 15 Mar 2026 17:26:14 +0000 Subject: [PATCH] Docs: refresh extension host migration status --- .../openclaw-capability-catalog-and-arbitration-spec.md | 4 +++- .../openclaw-extension-contribution-schema-spec.md | 2 ++ .../openclaw-extension-host-implementation-guide.md | 5 ++++- .../openclaw-extension-host-lifecycle-and-security-spec.md | 6 ++++-- .../openclaw-kernel-event-pipeline-spec.md | 3 ++- .../openclaw-kernel-extension-host-transition-plan.md | 3 +++ src/extension-host/cutover-inventory.md | 6 +++--- 7 files changed, 21 insertions(+), 8 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 10f0c79e89f..2dbc30a25a3 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 @@ -27,7 +27,7 @@ Host-managed install, onboarding, and lightweight channel catalogs remain separa Current status against this spec: - canonical catalogs and arbitration have not started -- only the earliest host-managed static metadata work has landed +- host-managed static metadata work and early runtime/lifecycle boundary extraction have landed What has been implemented: @@ -66,6 +66,7 @@ What has been implemented: - compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts` ahead of broader catalog-backed registry ownership - compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts` ahead of broader catalog-backed registry ownership - compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts` ahead of broader catalog-backed registry ownership +- service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` ahead of broader catalog-backed lifecycle ownership How it has been implemented: @@ -94,6 +95,7 @@ How it has been implemented: - by extracting the remaining compatibility plugin-registry facade into a host-owned helper so `src/plugins/registry.ts` becomes a thin wrapper instead of the real owner - by extracting provider normalization, command duplicate enforcement, and registry-local diagnostic shaping into a host-owned registry-compat helper while leaving the underlying provider-validation and plugin-command subsystems unchanged - by extracting low-risk registry registration actions into a host-owned registry-registrations helper so the compatibility facade composes host-owned actions instead of implementing them inline +- by extracting service startup, stop ordering, service-context creation, and failure logging into a host-owned service-lifecycle helper before broader catalog-backed service ownership What remains pending: 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 3da89ad7e8b..a14a77a1888 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 @@ -45,6 +45,7 @@ What has been implemented: - compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts` - compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts` - compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts` +- service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` - plugin SDK alias resolution now routes through `src/extension-host/loader-compat.ts` - loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts` - loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts` @@ -98,6 +99,7 @@ How it has been implemented: - by extracting the remaining compatibility plugin-registry facade into a host-owned helper so `src/plugins/registry.ts` becomes a thin wrapper instead of the real owner - by extracting provider normalization, command duplicate enforcement, and registry-local diagnostic shaping into a host-owned registry-compat helper while leaving the underlying provider-validation and plugin-command subsystems unchanged - by extracting low-risk registry registration actions into a host-owned registry-registrations helper so the compatibility facade composes host-owned actions instead of implementing them inline +- by extracting service startup, stop ordering, service-context creation, and failure logging into a host-owned service-lifecycle helper while `src/plugins/services.ts` remains the compatibility entry point What remains pending: 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 1b1d315d953..f2a0d0fc7f9 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 @@ -91,6 +91,7 @@ What has been implemented so far: - compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts` - compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts` - compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts` +- service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` - several static and lookup consumers now read through the host boundary or resolved-extension model: - channel registry and dock lookups - message-channel normalization @@ -141,6 +142,7 @@ How it has been done: - by extracting the remaining compatibility plugin-registry facade into a host-owned helper so `src/plugins/registry.ts` becomes a thin wrapper instead of the real owner - by extracting provider normalization, command duplicate enforcement, and registry-local diagnostic shaping into a host-owned registry-compat helper while leaving the underlying provider-validation and plugin-command subsystems unchanged - by extracting low-risk registry registration actions into a host-owned registry-registrations helper so the compatibility facade composes host-owned actions instead of implementing them inline +- by extracting service startup, stop ordering, service-context creation, and failure logging into a host-owned service-lifecycle helper while `src/plugins/services.ts` remains the compatibility entry point - by moving central readers first, so later lifecycle and compatibility work can land on one boundary instead of many ad hoc call sites - by adding focused tests for each extracted seam before widening the boundary further @@ -177,13 +179,14 @@ Committed implementation slices so far: - `0e190d64d4` `Plugins: extract registry compatibility facade` - `944d787df1` `Plugins: extract registry compatibility policy` - `4ca9cd7e5e` `Plugins: extract registry registration actions` +- `6b24e65719` `Plugins: extract service lifecycle` - `89414ed857` `Docs: track extension host migration internally` - `d8af1eceaf` `Docs: refresh extension host migration status` What is still missing for these phases: - keeping the cutover inventory current as more surfaces move -- broader lifecycle ownership beyond the loader state machine, session-owned activation state, and explicit discovery-policy, activation-policy, and finalization-policy outcomes, remaining policy gate ownership, and broad host-owned registries described for Phase 2 +- broader lifecycle ownership beyond the loader state machine, service-lifecycle boundary, session-owned activation state, and explicit discovery-policy, activation-policy, and finalization-policy outcomes, remaining policy gate ownership, and broad host-owned registries described for Phase 2 - minimal SDK compatibility work beyond preserving current behavior indirectly through existing loading - any pilot migration, event pipeline, canonical catalog, or arbitration implementation diff --git a/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md b/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md index 0471a6dcd38..925dcc9c719 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md @@ -27,7 +27,7 @@ Current status against this spec: - registry ownership and the first compatibility-preserving loader slices have landed - a loader-scoped lifecycle state machine has landed -- broader lifecycle orchestration, policy gates, and activation-state management have not landed +- broader lifecycle orchestration, policy gates, and activation-state management beyond the current loader and service seams have not landed What has been implemented: @@ -44,6 +44,7 @@ What has been implemented: - compatibility plugin-registry facade ownership now delegates through `src/extension-host/plugin-registry.ts` - compatibility plugin-registry policy now delegates through `src/extension-host/plugin-registry-compat.ts` - compatibility plugin-registry registration actions now delegate through `src/extension-host/plugin-registry-registrations.ts` +- service startup, stop ordering, service-context creation, and failure logging now delegate through `src/extension-host/service-lifecycle.ts` - loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts` - loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts` - loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts` @@ -108,10 +109,11 @@ How it has been implemented: - by extracting the remaining compatibility plugin-registry facade into a host-owned helper so `src/plugins/registry.ts` becomes a thin wrapper instead of the real owner - by extracting provider normalization, command duplicate enforcement, and registry-local diagnostic shaping into a host-owned registry-compat helper while leaving the underlying provider-validation and plugin-command subsystems unchanged - by extracting low-risk registry registration actions into a host-owned registry-registrations helper so the compatibility facade composes host-owned actions instead of implementing them inline +- by extracting service startup, stop ordering, service-context creation, and failure logging into a host-owned service-lifecycle helper while `src/plugins/services.ts` remains the compatibility entry point What is still pending from this spec: -- broader extension-host lifecycle ownership beyond the loader state machine, session-owned activation state, and explicit discovery-policy, activation-policy, and finalization-policy outcomes +- broader extension-host lifecycle ownership beyond the loader state machine, service-lifecycle boundary, session-owned activation state, and explicit discovery-policy, activation-policy, and finalization-policy outcomes - activation pipeline ownership - host-owned registries for setup, CLI, routes, services, slots, and backends - permission-mode enforcement diff --git a/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md b/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md index 07652cc8170..527ce1b1421 100644 --- a/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md @@ -65,11 +65,12 @@ Relevant prerequisite work that has landed: - compatibility plugin-registry facade ownership now has a host-owned helper boundary in `src/extension-host/plugin-registry.ts` - compatibility plugin-registry policy now has a host-owned helper boundary in `src/extension-host/plugin-registry-compat.ts` - compatibility plugin-registry registration actions now have a host-owned helper boundary in `src/extension-host/plugin-registry-registrations.ts` +- service startup, stop ordering, service-context creation, and failure logging now have a host-owned helper boundary in `src/extension-host/service-lifecycle.ts` Why this matters for this spec: - event work should land on top of a host-owned boundary and normalized contribution model rather than on top of more plugin-era runtime seams -- the current implementation has deliberately not started canonical bridge or stage work before those earlier boundaries were in place, including the first loader-runtime, record-state, discovery-policy, activation-policy, finalization-policy, low-risk registry-write, hook-compat, plugin-api, plugin-registry, plugin-registry-compat, and plugin-registry-registrations seams +- the current implementation has deliberately not started canonical bridge or stage work before those earlier boundaries were in place, including the first loader-runtime, record-state, discovery-policy, activation-policy, finalization-policy, low-risk registry-write, hook-compat, plugin-api, plugin-registry, plugin-registry-compat, plugin-registry-registrations, and service-lifecycle seams ## Design Goals 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 10de7247502..dfe8a304ef8 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 @@ -76,6 +76,7 @@ What has landed: - compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts` - compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts` - compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts` +- service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` - several existing consumers now read host-owned normalized data instead of plugin-era manifest or runtime state directly: - channel and dock lookup surfaces - message-channel normalization @@ -127,6 +128,7 @@ How it was done: - by extracting the remaining compatibility plugin-registry facade into a host-owned helper so `src/plugins/registry.ts` becomes a thin wrapper instead of the real owner - by extracting provider normalization, command duplicate enforcement, and registry-local diagnostic shaping into a host-owned registry-compat helper while leaving the underlying provider-validation and plugin-command subsystems unchanged - by extracting low-risk registry registration actions into a host-owned registry-registrations helper so the compatibility facade composes host-owned actions instead of implementing them inline +- by extracting service startup, stop ordering, service-context creation, and failure logging into a host-owned service-lifecycle helper while `src/plugins/services.ts` remains the compatibility entry point - by moving static and lookup-heavy consumers first, where the ownership boundary matters but runtime risk is lower Committed implementation slices so far: @@ -162,6 +164,7 @@ Committed implementation slices so far: - `0e190d64d4` `Plugins: extract registry compatibility facade` - `944d787df1` `Plugins: extract registry compatibility policy` - `4ca9cd7e5e` `Plugins: extract registry registration actions` +- `6b24e65719` `Plugins: extract service lifecycle` - `89414ed857` `Docs: track extension host migration internally` - `d8af1eceaf` `Docs: refresh extension host migration status` diff --git a/src/extension-host/cutover-inventory.md b/src/extension-host/cutover-inventory.md index 877e8cc99b4..5f88c1acbad 100644 --- a/src/extension-host/cutover-inventory.md +++ b/src/extension-host/cutover-inventory.md @@ -74,14 +74,14 @@ This is an implementation checklist, not a future-design spec. | Gateway method registration writes | `src/plugins/registry.ts` | host-owned runtime contribution registry | `partial` | Duplicate detection and normalized method registration now delegate to `src/extension-host/runtime-registrations.ts`, and compatibility writes now route through `src/extension-host/registry-writes.ts`. | | Tool registration writes | `src/plugins/registry.ts` | host-owned tool registry | `partial` | Tool-name normalization and tool-factory shaping delegate through `src/extension-host/runtime-registrations.ts`, and low-risk compatibility writes now route through `src/extension-host/registry-writes.ts`; duplicate handling still follows the legacy tool path. | | CLI registration writes | `src/plugins/registry.ts` | host-owned CLI registry | `partial` | CLI command-name normalization delegates through `src/extension-host/runtime-registrations.ts`, and compatibility writes now route through `src/extension-host/registry-writes.ts`; the legacy plugin API still remains the call surface. | -| Service registration writes | `src/plugins/registry.ts` | host-owned service registry | `partial` | Service-id normalization delegates through `src/extension-host/runtime-registrations.ts`, and compatibility writes now route through `src/extension-host/registry-writes.ts`; lifecycle remains legacy-owned. | +| Service registration writes | `src/plugins/registry.ts` | host-owned service registry | `partial` | Service-id normalization delegates through `src/extension-host/runtime-registrations.ts`, compatibility writes now route through `src/extension-host/registry-writes.ts`, and broader lifecycle ownership now starts in `src/extension-host/service-lifecycle.ts`. | | Command registration writes | `src/plugins/registry.ts` | host-owned command registry | `partial` | Command-name normalization, duplicate-enforcement diagnostics, and legacy plugin-command registry bridging now delegate through `src/extension-host/plugin-registry-compat.ts`; the final compatibility write still routes through `src/extension-host/registry-writes.ts`. | | Context-engine registration writes | `src/plugins/registry.ts` | host-owned context-engine registry | `partial` | Context-engine id normalization now delegates to `src/extension-host/runtime-registrations.ts`, and the compatibility write now routes through `src/extension-host/registry-writes.ts`; the actual context-engine registry remains legacy-owned. | | Legacy hook registration writes | `src/plugins/registry.ts` | host-owned hook registry | `partial` | Hook-entry construction and event normalization now delegate to `src/extension-host/runtime-registrations.ts`, and the compatibility write now routes through `src/extension-host/registry-writes.ts`; internal-hook bridging still remains in the legacy plugin registry. | | Typed-hook registration writes | `src/plugins/registry.ts` | host-owned typed-hook registry | `partial` | Typed-hook record construction and hook-name validation now delegate to `src/extension-host/runtime-registrations.ts`, and the compatibility write now routes through `src/extension-host/registry-writes.ts`; prompt-injection policy and execution semantics remain legacy-owned. | | Hook compatibility policy and bridging | `src/plugins/registry.ts` | `src/extension-host/hook-compat.ts` | `partial` | Legacy internal-hook bridging and typed prompt-injection compatibility policy now delegate through a host-owned helper; actual hook execution ownership remains legacy-owned. | | Hook execution and global runner | `src/plugins/hook-runner-global.ts`, `src/hooks/internal-hooks.ts`, plugin hook registration in `src/plugins/registry.ts` | canonical kernel event stages + host bridges | `not started` | No canonical event-stage migration has landed yet. | -| Service lifecycle | `src/plugins/services.ts` and plugin service registration | extension host lifecycle | `not started` | Service startup and teardown still depend on legacy plugin registry/service ownership. | +| Service lifecycle | `src/plugins/services.ts` and plugin service registration | `src/extension-host/service-lifecycle.ts` | `partial` | Service startup, stop ordering, service-context creation, and failure logging now delegate through a host-owned service-lifecycle helper while `src/plugins/services.ts` remains the compatibility entry point. | | CLI registration | plugin CLI registration in `src/plugins/registry.ts` and CLI loaders | extension host registry + static descriptors where possible | `not started` | No host-owned CLI registry exists yet. | | Gateway/server methods | `src/plugins/registry.ts` gateway handler registration | host-owned runtime contribution registry | `not started` | Still registered directly into the legacy plugin registry. | | Slot arbitration | `src/plugins/slots.ts` | host-owned arbitration model | `not started` | Current slot selection remains plugin-era logic. | @@ -105,6 +105,7 @@ That pattern has been used for: - normalized extension schema and resolved-extension records - static consumers such as skills, validation, auto-enable, and config baseline generation - loader compatibility, cache control, initial candidate planning, entry-path import, explicit discovery-policy outcomes, explicit activation-policy outcomes, runtime decisions, post-import register flow, per-candidate orchestration, top-level load orchestration, session-owned activation state, explicit loader lifecycle transitions, explicit finalization-policy results, and final cache plus activation finalization +- service startup, stop ordering, and failure logging ## Immediate Next Targets @@ -125,7 +126,6 @@ The following remain legacy-owned today: - activation ordering - policy gates - typed and legacy hook execution -- service lifecycle - CLI registration - gateway/server method registration - slot arbitration