From f05d35b986cabbb936663774f0cd52a7fca5ef9d Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sun, 15 Mar 2026 22:29:56 +0000 Subject: [PATCH] Docs: refresh extension host module layout --- ...capability-catalog-and-arbitration-spec.md | 68 +++++++++--------- ...claw-extension-contribution-schema-spec.md | 66 +++++++++--------- ...law-extension-host-implementation-guide.md | 69 ++++++++++--------- ...ension-host-lifecycle-and-security-spec.md | 64 ++++++++--------- .../openclaw-kernel-event-pipeline-spec.md | 16 ++--- ...w-kernel-extension-host-transition-plan.md | 69 ++++++++++--------- 6 files changed, 177 insertions(+), 175 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 b8e1c1f5580..a0e0eefd91a 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 @@ -35,43 +35,43 @@ What has been implemented: - channel catalog package metadata parsing now routes through host-owned schema helpers - host-owned resolved-extension records now carry the static metadata needed for install, onboarding, and lightweight operator UX - config doc baseline generation now uses the same host-owned resolved-extension metadata path -- 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` -- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts` -- loader provenance helpers now route through `src/extension-host/loader-provenance.ts` -- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts` -- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts` -- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts` -- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts` -- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts` -- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` -- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` -- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader host process state now routes through `src/extension-host/loader-host-state.ts` -- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts` -- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts` -- loader execution setup composition now routes through `src/extension-host/loader-execution.ts` -- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts` -- loader mutable activation state now routes through `src/extension-host/loader-session.ts` -- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts` -- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values -- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts` -- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts` +- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts` +- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts` +- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts` +- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts` +- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts` +- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts` +- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts` +- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts` +- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts` +- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts` +- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts` +- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts` +- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts` +- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts` +- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts` +- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts` +- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts` +- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts` +- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts` +- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts` +- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts` +- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts` - channel, provider, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now has a host-owned helper boundary for future catalog migration - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts` ahead of broader catalog-backed registry ownership - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` ahead of broader catalog-backed ownership -- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` ahead of broader catalog-backed arbitration ownership +- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` ahead of broader catalog-backed arbitration ownership - ACP backend registration and runtime resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` ahead of broader catalog-backed backend ownership -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade -- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts` ahead of broader catalog-backed registry ownership -- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts` ahead of broader catalog-backed registry ownership -- 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 +- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts` ahead of broader catalog-backed registry ownership +- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts` ahead of broader catalog-backed registry ownership +- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts` ahead of broader catalog-backed registry ownership +- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts` ahead of broader catalog-backed registry ownership +- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts` ahead of broader catalog-backed registry ownership - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts` ahead of broader catalog-backed registry ownership, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now route through `src/extension-host/command-runtime.ts` ahead of broader catalog-backed 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 @@ -103,7 +103,7 @@ How it has been implemented: - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before catalog publication work - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before catalog publication work - by moving mutable activation state into a host-owned loader session before catalog publication work -- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation +- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before catalog publication work - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before catalog publication work - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before catalog publication work @@ -618,7 +618,7 @@ Capability selection must emit structured events for: - channel capabilities from `extensions/discord/src/channel.ts:74`, `extensions/slack/src/channel.ts:107`, and `extensions/telegram/src/channel.ts:120` collapse into canonical messaging action families - 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 -- catalog-backed runtime-family descriptors for embeddings, media, and TTS now route through `src/extension-host/runtime-backend-catalog.ts`; embedding shared backend definitions in `src/extension-host/embedding-runtime-backends.ts`, media shared backend definitions in `src/extension-host/media-runtime-backends.ts`, TTS shared backend definitions in `src/extension-host/tts-runtime-backends.ts`, initial runtime-family arbitration in `src/extension-host/runtime-backend-arbitration.ts`, and shared default and preferred backend ordering plus fallback chaining in `src/extension-host/runtime-backend-policy.ts`; the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also route through that shared backend-policy layer; embedding auto-provider selection, embedding local setup guidance, memory doctor guidance for embedding auto-provider order, and explicit embedding fallback policy in `src/extension-host/embedding-runtime-policy.ts`, media provider candidate ordering plus default-model fallback selection in `src/extension-host/media-runtime-policy.ts`, and TTS request setup, status, compatibility provider-order exports, plus explicit TTS configured-fallback policy in `src/extension-host/tts-runtime-policy.ts` already consume that catalog-backed arbitration and backend-policy data, and broader consumer adoption and arbitration should continue moving those subsystem runtimes toward runtime-internal registries rather than leaving them as a universal plugin-provider API shape +- catalog-backed runtime-family descriptors for embeddings, media, and TTS now route through `src/extension-host/runtime-backend-catalog.ts`; embedding shared backend definitions in `src/extension-host/embedding-runtime-backends.ts`, media shared backend definitions in `src/extension-host/media-runtime-backends.ts`, TTS shared backend definitions in `src/extension-host/tts-runtime-backends.ts`, initial runtime-family arbitration in `src/extension-host/policy/runtime-backend-arbitration.ts`, and shared default and preferred backend ordering plus fallback chaining in `src/extension-host/policy/runtime-backend-policy.ts`; the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also route through that shared backend-policy layer; embedding auto-provider selection, embedding local setup guidance, memory doctor guidance for embedding auto-provider order, and explicit embedding fallback policy in `src/extension-host/policy/embedding-runtime-policy.ts`, media provider candidate ordering plus default-model fallback selection in `src/extension-host/policy/media-runtime-policy.ts`, and TTS request setup, status, compatibility provider-order exports, plus explicit TTS configured-fallback policy in `src/extension-host/policy/tts-runtime-policy.ts` already consume that catalog-backed arbitration and backend-policy data, and broader consumer adoption and arbitration should continue moving those subsystem runtimes toward runtime-internal registries rather than leaving them as a universal plugin-provider API shape - 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 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 b4a02e45f19..201d2b5d6f1 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 @@ -41,16 +41,16 @@ What has been implemented: - the first runtime registration normalization helpers now exist in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook writes - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts` - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade -- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade +- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade - ACP backend registration and runtime resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface and result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface and result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade -- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts` -- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts` -- 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` +- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts` +- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts` +- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts` +- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts` +- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts` - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` - CLI duplicate detection, registrar invocation, and async failure logging now route through `src/extension-host/cli-lifecycle.ts` - gateway method-id aggregation, plugin diagnostic shaping, and extra-handler composition now route through `src/extension-host/gateway-methods.ts` @@ -64,30 +64,30 @@ What has been implemented: - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts` - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts` - provider post-selection hook lookup and invocation now route through `src/extension-host/provider-model-selection.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` -- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts` -- loader provenance helpers now route through `src/extension-host/loader-provenance.ts` -- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts` -- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts` -- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts` -- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts` -- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts` -- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` -- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` -- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader host process state now routes through `src/extension-host/loader-host-state.ts` -- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts` -- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts` -- loader execution setup composition now routes through `src/extension-host/loader-execution.ts` -- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts` -- loader mutable activation state now routes through `src/extension-host/loader-session.ts` -- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts` -- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values -- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts` -- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts` +- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts` +- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts` +- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts` +- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts` +- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts` +- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts` +- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts` +- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts` +- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts` +- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts` +- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts` +- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts` +- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts` +- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts` +- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts` +- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts` +- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts` +- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts` +- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts` +- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts` +- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts` +- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts` How it has been implemented: @@ -108,7 +108,7 @@ How it has been implemented: - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before broadening the schema-driven host lifecycle model - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before broadening the schema-driven host lifecycle model - by moving mutable activation state into a host-owned loader session before broadening the schema-driven host lifecycle model -- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation +- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before broadening the schema-driven host lifecycle model - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before broadening the schema-driven host lifecycle model - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before broadening the schema-driven host lifecycle model 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 ef0ed7faa9f..bccbebda462 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 @@ -60,40 +60,40 @@ What has been implemented so far: - `src/plugins/manifest-registry.ts` now carries a normalized `resolvedExtension` alongside the legacy flat manifest record - `src/extension-host/resolved-registry.ts` now exposes a host-owned resolved-extension registry view - an initial Phase 0 inventory now exists in `src/extension-host/cutover-inventory.md` -- 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` -- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts` -- loader provenance helpers now route through `src/extension-host/loader-provenance.ts` -- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts` -- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts` -- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts` -- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts` -- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts` -- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` -- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` -- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader host process state now routes through `src/extension-host/loader-host-state.ts` -- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts` -- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts` -- loader execution setup composition now routes through `src/extension-host/loader-execution.ts` -- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts` -- loader mutable activation state now routes through `src/extension-host/loader-session.ts` -- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts` -- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values -- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts` -- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts` +- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts` +- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts` +- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts` +- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts` +- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts` +- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts` +- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts` +- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts` +- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts` +- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts` +- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts` +- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts` +- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts` +- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts` +- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts` +- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts` +- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts` +- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts` +- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts` +- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts` +- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts` +- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts` - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts` - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade -- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade +- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade - ACP backend registration and resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade -- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts` -- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts` -- 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` +- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts` +- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts` +- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts` +- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts` +- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts` - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` - CLI duplicate detection, registrar invocation, and async failure logging now route through `src/extension-host/cli-lifecycle.ts` @@ -102,12 +102,13 @@ What has been implemented so far: - plugin provider projection from registry entries into runtime provider objects now routes through `src/extension-host/provider-runtime.ts` - plugin provider discovery filtering, order grouping, and result normalization now route through `src/extension-host/provider-discovery.ts` - provider matching, auth-method selection, config-patch merging, and default-model application now route through `src/extension-host/provider-auth.ts` -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts` - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts` - provider post-selection hook lookup and invocation now route through `src/extension-host/provider-model-selection.ts` +- the first filesystem-layout pass has also landed: activation helpers now live under `src/extension-host/activation/`, host-owned policy seams now live under `src/extension-host/policy/`, and compatibility facades now live under `src/extension-host/compat/`, matching the module layout already called for in the transition plan without changing the underlying ownership split - several static and lookup consumers now read through the host boundary or resolved-extension model: - channel registry and dock lookups - message-channel normalization @@ -161,7 +162,7 @@ How it has been done: - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before shrinking the remaining orchestrator surface - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before shrinking the remaining orchestrator surface - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session instead of leaving them in top-level loader variables -- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation +- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes instead of leaving them inline in the loader flow - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them @@ -297,7 +298,7 @@ Recent plan refinements: - it now explicitly treats interactive callback routing, namespace ownership, dedupe, and fallback behavior as first-class migration surfaces - 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 in-progress host-owned subsystem runtimes, with embedding backend definitions now shared between `src/extension-host/embedding-runtime-backends.ts`, `src/extension-host/embedding-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, shared default and preferred runtime-backend ordering plus fallback chaining now landing in `src/extension-host/runtime-backend-policy.ts`, the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also routing through that shared backend-policy layer, embedding selection, fallback routing, explicit fallback policy in `src/extension-host/embedding-runtime-policy.ts`, public runtime surface, result typing, manager-side batch and fallback policy, sync plus reindex planning, sync plus reindex orchestration, reindex sync-body execution plus unsafe reset, safe-reindex temp-db creation, file swap, reopen, and cleanup, plus runtime-backend catalog descriptors now extracted and embedding auto-provider selection, local setup guidance, and memory doctor guidance already consuming the catalog-backed embedding backend-policy order, media backend definitions now shared between `src/extension-host/media-runtime-backends.ts`, `src/extension-host/media-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with media registry, explicit selection policy in `src/extension-host/media-runtime-policy.ts`, execution, auto-entry selection, orchestration, planning helpers, remaining API composition, lazy entrypoint wiring, plus runtime-backend catalog descriptors now extracted and media provider candidate ordering plus default-model fallback lookup already consuming that catalog-backed backend-policy order, TTS backend definitions now shared between `src/extension-host/tts-runtime-backends.ts`, `src/extension-host/tts-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with TTS registry, execution, request setup, config normalization, preferences, payload planning, shared status state, API composition, plus runtime-backend catalog descriptors now extracted, initial runtime-family arbitration now landing in `src/extension-host/runtime-backend-arbitration.ts`, explicit configured-fallback policy now landing in `src/extension-host/tts-runtime-policy.ts`, and TTS request setup, status, plus compatibility provider-order exports already consuming that arbitration-backed backend-policy order, and broader consumer adoption and arbitration on top of those catalog-backed runtime-family descriptors still pending, all with capability routing, typed request envelopes, provider-id normalization, and fallback policy +- it now explicitly treats embeddings, media understanding, and TTS as in-progress host-owned subsystem runtimes, with embedding backend definitions now shared between `src/extension-host/embedding-runtime-backends.ts`, `src/extension-host/embedding-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, shared default and preferred runtime-backend ordering plus fallback chaining now landing in `src/extension-host/policy/runtime-backend-policy.ts`, the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also routing through that shared backend-policy layer, embedding selection, fallback routing, explicit fallback policy in `src/extension-host/policy/embedding-runtime-policy.ts`, public runtime surface, result typing, manager-side batch and fallback policy, sync plus reindex planning, sync plus reindex orchestration, reindex sync-body execution plus unsafe reset, safe-reindex temp-db creation, file swap, reopen, and cleanup, plus runtime-backend catalog descriptors now extracted and embedding auto-provider selection, local setup guidance, and memory doctor guidance already consuming the catalog-backed embedding backend-policy order, media backend definitions now shared between `src/extension-host/media-runtime-backends.ts`, `src/extension-host/media-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with media registry, explicit selection policy in `src/extension-host/policy/media-runtime-policy.ts`, execution, auto-entry selection, orchestration, planning helpers, remaining API composition, lazy entrypoint wiring, plus runtime-backend catalog descriptors now extracted and media provider candidate ordering plus default-model fallback lookup already consuming that catalog-backed backend-policy order, TTS backend definitions now shared between `src/extension-host/tts-runtime-backends.ts`, `src/extension-host/tts-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with TTS registry, execution, request setup, config normalization, preferences, payload planning, shared status state, API composition, plus runtime-backend catalog descriptors now extracted, initial runtime-family arbitration now landing in `src/extension-host/policy/runtime-backend-arbitration.ts`, explicit configured-fallback policy now landing in `src/extension-host/policy/tts-runtime-policy.ts`, and TTS request setup, status, plus compatibility provider-order exports already consuming that arbitration-backed backend-policy order, and broader consumer adoption and arbitration on top of those catalog-backed runtime-family descriptors still pending, all 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 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 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 11f9e70c904..f0800bbc972 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 @@ -40,16 +40,16 @@ What has been implemented: - channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now delegates through `src/extension-host/runtime-registrations.ts` - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now delegate through `src/extension-host/registry-writes.ts` - context-engine registration and runtime resolution now delegate through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade -- exclusive-slot selection and default-slot resolution now delegate through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade +- exclusive-slot selection and default-slot resolution now delegate through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade - ACP backend registration and runtime resolution now delegate through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now delegate through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now delegates through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now delegate through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now delegate through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now delegate through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now delegate through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now delegate through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now delegate through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now delegate through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now delegate through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now delegate through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now delegate through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now delegate through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now delegate through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now delegate through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain the compatibility facades +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now delegate through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now delegates through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now delegate through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now delegate through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now delegate through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now delegate through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now delegate through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now delegate through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now delegate through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now delegate through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now delegate through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now delegate through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now delegate through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now delegate through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now delegate through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain the compatibility facades - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now delegate through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now delegate through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now delegate through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now delegate through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now delegate through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now delegate through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now delegate through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade -- legacy internal-hook bridging and typed prompt-injection compatibility policy now delegate through `src/extension-host/hook-compat.ts` -- compatibility `OpenClawPluginApi` composition and logger shaping now delegate through `src/extension-host/plugin-api.ts` -- 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` +- legacy internal-hook bridging and typed prompt-injection compatibility policy now delegate through `src/extension-host/compat/hook-compat.ts` +- compatibility `OpenClawPluginApi` composition and logger shaping now delegate through `src/extension-host/compat/plugin-api.ts` +- compatibility plugin-registry facade ownership now delegates through `src/extension-host/compat/plugin-registry.ts` +- compatibility plugin-registry policy now delegates through `src/extension-host/compat/plugin-registry-compat.ts` +- compatibility plugin-registry registration actions now delegate through `src/extension-host/compat/plugin-registry-registrations.ts` - host-owned runtime registry accessors now delegate through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now delegate through `src/extension-host/command-runtime.ts` - service startup, stop ordering, service-context creation, and failure logging now delegate through `src/extension-host/service-lifecycle.ts` @@ -62,29 +62,29 @@ What has been implemented: - provider onboarding option building, model-picker entry building, and provider-method choice resolution now delegate through `src/extension-host/provider-wizard.ts` - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now delegate through `src/extension-host/provider-auth-flow.ts` - provider post-selection hook lookup and invocation now delegate through `src/extension-host/provider-model-selection.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` -- loader provenance helpers now route through `src/extension-host/loader-provenance.ts` -- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts` -- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts` -- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts` -- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts` -- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts` -- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` -- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` -- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader host process state now routes through `src/extension-host/loader-host-state.ts` -- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts` -- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts` -- loader execution setup composition now routes through `src/extension-host/loader-execution.ts` -- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts` -- loader mutable activation state now routes through `src/extension-host/loader-session.ts` -- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts` -- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values -- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts` -- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts` +- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts` +- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts` +- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts` +- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts` +- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts` +- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts` +- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts` +- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts` +- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts` +- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts` +- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts` +- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts` +- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts` +- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts` +- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts` +- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts` +- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts` +- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts` +- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts` +- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts` +- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts` How it has been implemented: @@ -117,7 +117,7 @@ How it has been implemented: - by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before enforcing the loader lifecycle state machine - by promoting successfully registered plugins to `ready` during host-owned finalization while leaving broader activation-state semantics for later phases - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session before broader activation-state semantics move -- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation +- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before broader policy semantics move - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them 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 d6608e559df..9968c036a63 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 @@ -37,10 +37,10 @@ Relevant prerequisite work that has landed: - config doc baseline generation now uses the same host-owned resolved-extension data path - channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now has a host-owned helper boundary - context-engine registration and runtime resolution now have a host-owned helper boundary in `src/extension-host/context-engine-runtime.ts` -- exclusive-slot selection and default-slot resolution now have a host-owned helper boundary in `src/extension-host/slot-arbitration.ts` +- exclusive-slot selection and default-slot resolution now have a host-owned helper boundary in `src/extension-host/policy/slot-arbitration.ts` - ACP backend registration and runtime resolution now have a host-owned helper boundary in `src/extension-host/acp-runtime-backend-registry.ts` -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now have a host-owned helper boundary in `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now has a host-owned helper boundary in `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now have host-owned boundaries in `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now have a host-owned helper boundary in `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now have a host-owned helper boundary in `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now has a host-owned helper boundary in `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now have a host-owned helper boundary in `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now have a host-owned helper boundary in `src/extension-host/embedding-safe-reindex.ts` -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now have a host-owned helper boundary in `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now have a host-owned helper boundary in `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now have a host-owned helper boundary in `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now have a host-owned helper boundary in `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now have a host-owned helper boundary in `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now have host-owned helper boundaries in `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now have host-owned helper boundaries in `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now have a host-owned helper boundary in `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now has a host-owned helper boundary in `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now have host-owned boundaries in `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now have a host-owned helper boundary in `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now have a host-owned helper boundary in `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now has a host-owned helper boundary in `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now have a host-owned helper boundary in `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now have a host-owned helper boundary in `src/extension-host/embedding-safe-reindex.ts` +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now have a host-owned helper boundary in `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now have a host-owned helper boundary in `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now have a host-owned helper boundary in `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now have a host-owned helper boundary in `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now have a host-owned helper boundary in `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now have host-owned helper boundaries in `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now have host-owned helper boundaries in `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now have a host-owned helper boundary in `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now have a host-owned helper boundary in `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now have a host-owned helper boundary in `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now have a host-owned helper boundary in `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now have a host-owned helper boundary in `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now have a host-owned helper boundary in `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now have a host-owned helper boundary in `src/extension-host/tts-status.ts` - loader cache key construction and registry cache control now have a host-owned helper boundary - loader provenance helpers now have a host-owned helper boundary @@ -66,11 +66,11 @@ Relevant prerequisite work that has landed: - loader finalization policy outcomes now have a host-owned helper boundary - loader final cache, readiness promotion, and activation finalization now has a host-owned helper boundary - low-risk channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook compatibility writes now have a host-owned helper boundary in `src/extension-host/registry-writes.ts` -- legacy internal-hook bridging and typed prompt-injection compatibility policy now have a host-owned helper boundary in `src/extension-host/hook-compat.ts` -- compatibility `OpenClawPluginApi` composition and logger shaping now have a host-owned helper boundary in `src/extension-host/plugin-api.ts` -- 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` +- legacy internal-hook bridging and typed prompt-injection compatibility policy now have a host-owned helper boundary in `src/extension-host/compat/hook-compat.ts` +- compatibility `OpenClawPluginApi` composition and logger shaping now have a host-owned helper boundary in `src/extension-host/compat/plugin-api.ts` +- compatibility plugin-registry facade ownership now has a host-owned helper boundary in `src/extension-host/compat/plugin-registry.ts` +- compatibility plugin-registry policy now has a host-owned helper boundary in `src/extension-host/compat/plugin-registry-compat.ts` +- compatibility plugin-registry registration actions now have a host-owned helper boundary in `src/extension-host/compat/plugin-registry-registrations.ts` - host-owned runtime registry accessors now have a host-owned helper boundary in `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now have a host-owned helper boundary in `src/extension-host/command-runtime.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` 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 05bc9b8f001..678fa95ccc8 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 @@ -45,40 +45,40 @@ What has landed: - plugin manifest records now carry a normalized `resolvedExtension` - a host-owned resolved-extension registry view now exists for static consumers - an initial Phase 0 cutover inventory now exists in `src/extension-host/cutover-inventory.md` -- 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` -- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts` -- loader provenance helpers now route through `src/extension-host/loader-provenance.ts` -- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts` -- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts` -- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts` -- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts` -- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts` -- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` -- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` -- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader host process state now routes through `src/extension-host/loader-host-state.ts` -- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts` -- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts` -- loader execution setup composition now routes through `src/extension-host/loader-execution.ts` -- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts` -- loader mutable activation state now routes through `src/extension-host/loader-session.ts` -- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts` -- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values -- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts` -- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts` +- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts` +- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts` +- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts` +- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts` +- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts` +- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts` +- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts` +- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts` +- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts` +- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts` +- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts` +- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts` +- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts` +- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts` +- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts` +- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts` +- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts` +- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts` +- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts` +- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts` +- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts` +- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts` - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts` - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade -- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade +- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade - ACP backend registration and resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade -- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts` -- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts` -- 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` +- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts` +- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts` +- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts` +- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts` +- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts` - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now route through `src/extension-host/command-runtime.ts` - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` @@ -88,8 +88,8 @@ What has landed: - plugin provider projection from registry entries into runtime provider objects now routes through `src/extension-host/provider-runtime.ts` - plugin provider discovery filtering, order grouping, and result normalization now route through `src/extension-host/provider-discovery.ts` - provider matching, auth-method selection, config-patch merging, and default-model application now route through `src/extension-host/provider-auth.ts` -- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade -- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades +- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade +- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts` - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts` @@ -148,7 +148,7 @@ How it was done: - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before shrinking the remaining orchestrator surface - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before shrinking the remaining orchestrator surface - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session instead of leaving them in top-level loader variables -- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation +- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes instead of leaving them inline in the loader flow - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them @@ -1494,6 +1494,7 @@ Current implementation status: - package metadata and manifest metadata now converge into host-owned normalized records - discovery and install metadata parsing now go through host schema helpers - partial explicit compatibility now exists through host-owned loader-compat and loader-runtime helpers, but a versioned minimal SDK compatibility layer still does not exist +- the first filesystem-layout pass has landed too: activation seams now live under `src/extension-host/activation/`, policy seams now live under `src/extension-host/policy/`, and compatibility facades now live under `src/extension-host/compat/`, matching the planned host module layout without changing the current boundary ownership model ## Phase 2: Extension Host Lifecycle And Registries @@ -1532,7 +1533,7 @@ Current implementation status: - partially implemented in a compatibility-preserving form - the host now owns active registry state - the host now exposes resolved static registries for static consumers -- activation, loader cache control, loader policy, loader discovery-policy outcomes, loader activation-policy outcomes, loader finalization-policy outcomes, loader runtime decisions, loader top-level load orchestration, loader session state, loader record-state helpers, and loader finalization now route through `src/extension-host/*` +- activation, loader cache control, loader policy, loader discovery-policy outcomes, loader activation-policy outcomes, loader finalization-policy outcomes, loader runtime decisions, loader top-level load orchestration, loader session state, loader record-state helpers, and loader finalization now route through `src/extension-host/*`, with activation helpers organized under `src/extension-host/activation/`, policy helpers under `src/extension-host/policy/`, and compatibility facades under `src/extension-host/compat/` - broader lifecycle ownership beyond the loader state machine, registration surfaces, policy gates, and activation-state management are still pending ## Phase 3: Broader Legacy Compatibility Bridges