openclaw/experiments/plugin-sdk-namespaces-plan.md

Plugin SDK Namespaces Plan

TL;DR

OpenClaw should introduce a few clear SDK namespaces like plugin, channel, and provider, instead of keeping so much of the public surface flat.

The safe way to do that is:

• add thin ESM facade entrypoints, not TypeScript namespace
• keep the root openclaw/plugin-sdk surface small
• replace flat registration methods on OpenClawPluginApi with namespace groups
• ship the cutover in one coordinated release instead of dragging old flat APIs along
• forbid leaf modules from importing back through namespace facades

That gives plugin authors a cleaner SDK that feels closer to VS Code, without turning the SDK into a giant barrel or creating circular import problems.

Goal

Introduce public namespaces to the OpenClaw Plugin SDK so the surface feels closer to the VS Code extension API, while keeping the implementation tight, isolated, and resistant to circular imports.

This plan is about the public SDK shape. It is not a proposal to merge everything into one giant barrel.

Why This Is Worth Doing

Today the Plugin SDK has three visible problems:

• The public package export surface is large and mostly flat.
• src/plugin-sdk/core.ts and src/plugin-sdk/index.ts carry too many unrelated meanings.
• OpenClawPluginApi is still a flat registration API even though api.runtime already proves grouped namespaces work well.

The result is harder docs, harder discovery, and too many helper names that look equally important even when they are not.

Current Facts In The Repo

• Package exports are generated from a flat entrypoint list in src/plugin-sdk/entrypoints.ts and scripts/lib/plugin-sdk-entrypoints.json.
• The root openclaw/plugin-sdk entry is intentionally tiny in src/plugin-sdk/index.ts.
• api.runtime is already a successful namespace model. It groups behavior as agent, subagent, media, imageGeneration, webSearch, tools, channel, events, logging, state, tts, mediaUnderstanding, and modelAuth in src/plugins/runtime/index.ts.
• The main plugin registration API is still flat in OpenClawPluginApi in src/plugins/types.ts.
• The concrete API object is assembled in src/plugins/registry.ts, and a second partial copy exists in src/plugins/captured-registration.ts.

Those facts suggest a path that is low-risk:

• keep leaf modules as the source of truth
• add namespace facades on top
• cut docs, examples, and templates over in the same release as the namespace model

Design Principles

1. Do Not Use TypeScript namespace

Use normal ESM modules and package exports.

The SDK already ships as package export subpaths. The namespace model should be implemented as public facade modules, not TypeScript namespace syntax.

2. Keep The Root Tiny

Do not turn openclaw/plugin-sdk into a giant VS Code-style monolith.

The closest safe equivalent is:

• a tiny root for shared types and a few universal values
• a small number of explicit namespace entrypoints
• optional ergonomic aggregation only after the namespace surfaces settle

3. Namespace Facades Must Be Thin

Namespace entrypoints should contain no real business logic.

They should only:

• re-export stable leaves
• assemble small namespace objects

That keeps cycles and accidental coupling down.

4. Types Stay Direct And Easy To Import

Like VS Code, namespaces should mostly group behavior. Common types should stay directly importable from the root or the owning domain surface.

Examples:

• ChannelPlugin
• ProviderPlugin
• OpenClawPluginApi
• PluginRuntime

5. Do Not Namespace Everything At Once

Only namespace areas that already have a clear public identity.

Phase 1 should focus on:

• plugin
• channel
• provider

runtime already has a good public namespace shape on api.runtime and should not be reopened as a giant package-export family in the first pass.

Proposed Public Model

Namespace Entry Points

Canonical public entrypoints:

• openclaw/plugin-sdk/plugin
• openclaw/plugin-sdk/channel
• openclaw/plugin-sdk/provider
• openclaw/plugin-sdk/runtime
• openclaw/plugin-sdk/testing

What each should mean:

• plugin
  • plugin entry helpers
  • shared plugin definition helpers
  • plugin-facing config schema helpers that are truly universal
• channel
  • channel entry helpers
  • chat-channel builders
  • stable channel-facing contracts and helpers
• provider
  • provider entry helpers
  • auth, catalog, models, onboard, stream, usage, and provider registration helpers
• runtime
  • the existing api.runtime story and runtime-related public helpers that are truly stable
• testing
  • plugin author testing helpers

Nested Leaves

Under those namespaces, the long-term canonical leaves should become nested:

• openclaw/plugin-sdk/channel/setup

• openclaw/plugin-sdk/channel/pairing

• openclaw/plugin-sdk/channel/reply-pipeline

• openclaw/plugin-sdk/channel/contract

• openclaw/plugin-sdk/channel/targets

• openclaw/plugin-sdk/channel/actions

• openclaw/plugin-sdk/channel/inbound

• openclaw/plugin-sdk/channel/lifecycle

• openclaw/plugin-sdk/channel/policy

• openclaw/plugin-sdk/channel/feedback

• openclaw/plugin-sdk/channel/config-schema

• openclaw/plugin-sdk/channel/config-helpers

• openclaw/plugin-sdk/provider/auth

• openclaw/plugin-sdk/provider/catalog

• openclaw/plugin-sdk/provider/models

• openclaw/plugin-sdk/provider/onboard

• openclaw/plugin-sdk/provider/stream

• openclaw/plugin-sdk/provider/usage

• openclaw/plugin-sdk/provider/web-search

Not every current flat subpath needs a namespaced replacement. The goal is to promote the stable public domains, not to preserve every current export forever.

What Happens To core

core is overloaded today. In a namespace model it should shrink, not grow.

Target split:

• plugin-wide entry helpers move toward plugin
• channel builders and channel-oriented shared helpers move toward channel
• core stops being a first-class public destination and shrinks to the smallest possible remaining shared surface

Rule: no new public API should be added to core once namespace entrypoints exist.

Proposed OpenClawPluginApi Shape

Keep context fields flat:

• id
• name
• version
• description
• source
• rootDir
• registrationMode
• config
• pluginConfig
• runtime
• logger
• resolvePath

Move registration behavior behind namespaces:

Current flat method	Proposed namespace location
registerTool	api.tool.register
registerHook	api.hook.register
on	api.hook.on
registerHttpRoute	api.http.registerRoute
registerChannel	api.channel.register
registerProvider	api.provider.register
registerSpeechProvider	api.provider.registerSpeech
registerMediaUnderstandingProvider	api.provider.registerMediaUnderstanding
registerImageGenerationProvider	api.provider.registerImageGeneration
registerWebSearchProvider	api.provider.registerWebSearch
registerGatewayMethod	api.gateway.registerMethod
registerCli	api.cli.register
registerService	api.service.register
registerInteractiveHandler	api.interactive.register
registerCommand	api.command.register
registerContextEngine	api.contextEngine.register
registerMemoryPromptSection	api.memory.registerPromptSection

The cutover should replace the flat methods in one coordinated change.

That gives plugin authors a clearer public shape and avoids carrying two public registration models at the same time.

Example Public Usage

Proposed style:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin";
import { channel } from "openclaw/plugin-sdk/channel";
import { provider } from "openclaw/plugin-sdk/provider";
import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";

const chatPlugin: ChannelPlugin = channel.createChatPlugin({
  id: "demo",
  /* ... */
});

export default definePluginEntry({
  id: "demo",
  register(api: OpenClawPluginApi) {
    api.channel.register(chatPlugin);
    api.command.register({
      name: "status",
      description: "Show plugin status",
      run: async () => ({ text: "ok" }),
    });
  },
});

This is close to the VS Code mental model:

• grouped behavior
• direct types
• obvious public areas

without requiring a single monolithic root import.

Optional Ergonomic Surface

If the project later wants the closest possible VS Code feel, add a dedicated opt-in facade such as openclaw/plugin-sdk/sdk.

That facade can assemble:

• plugin
• channel
• provider
• runtime
• testing

It should not be phase 1.

Why:

• it is the highest-risk barrel from a cycle and weight perspective
• it is easier to add once the namespace surfaces already exist
• it preserves the root openclaw/plugin-sdk entry as a small type-oriented surface

Internal Implementation Rules

These rules are the important part. Without them, namespaces will rot into barrels and cycles.

Rule 1: Namespace Facades Are One-Way

Namespace entrypoints may import leaf modules.

Leaf modules may not import their namespace entrypoint.

Examples:

• allowed: src/plugin-sdk/channel.ts importing ./channel-setup.ts
• forbidden: src/plugin-sdk/channel-setup.ts importing ./channel.ts

Rule 1A: Allowed Dependency Directions Must Be Explicit

The allowed directions should be:

• namespace facade -> leaves in the same namespace
• leaf -> local implementation helpers
• leaf -> dedicated shared internal leaf
• leaf -> another leaf in the same namespace only by direct relative import, never through the namespace facade

The forbidden directions should be:

• leaf -> its own namespace facade
• leaf -> another namespace facade
• namespace facade -> another namespace facade
• channel leaf -> provider leaf, or provider leaf -> channel leaf, unless the dependency is first extracted into a shared internal leaf

Short version:

• facades point downward
• leaves never point back upward
• cross-namespace sharing must go sideways through a shared internal leaf, not directly through another public namespace

Rule 1B: If Two Namespaces Need Each Other, Extract A Shared Leaf

If channel and provider start needing each other directly, that is the sign that the seam is wrong.

Do not allow:

• src/plugin-sdk/channel/* importing from src/plugin-sdk/provider/*
• src/plugin-sdk/provider/* importing from src/plugin-sdk/channel/*

Instead:

• extract the shared logic into a dedicated internal leaf
• let both sides depend on that leaf
• keep the public namespaces separate

This is the main cycle-prevention rule. Shared logic moves to a lower layer before it creates a back-edge.

Rule 2: No Public-Specifier Self-Imports Inside The SDK

Files inside src/plugin-sdk/** should never import from openclaw/plugin-sdk/....

They should import local source files directly.

Rule 3: Shared Code Lives In Shared Leaves

If channel and provider need the same implementation detail, move that code to a shared leaf instead of importing one namespace from the other.

Good shared homes:

• a dedicated internal shared leaf
• a very small shared core leaf only if it has a precise, stable reason to exist
• existing domain-neutral helpers

Bad pattern:

• provider/* importing from channel/index
• channel/* importing from provider/index

Rule 4: Assemble The API Surface Once

OpenClawPluginApi should be built by one canonical factory.

src/plugins/registry.ts and src/plugins/captured-registration.ts should stop hand-building separate versions of the API object.

That factory can expose:

• the namespaced shape only

from the same underlying implementation.

Rule 5: Namespace Entry Files Stay Small

Namespace facades should stay close to pure exports. If a namespace file grows real orchestration logic, split that logic back into leaf modules.

Dependency Shape

The intended import graph is:

public facade
  -> same-namespace leaves
    -> local helpers
    -> shared internal leaves

Not this:

channel facade -> provider facade
channel leaf -> channel facade
provider leaf -> channel leaf

Concrete examples:

• allowed: src/plugin-sdk/channel.ts -> ./channel/setup.ts
• allowed: src/plugin-sdk/channel/setup.ts -> ./_internal/channel-shared.ts
• allowed: src/plugin-sdk/provider/auth.ts -> ../_internal/provider-shared.ts
• forbidden: src/plugin-sdk/channel/setup.ts -> ./channel.ts
• forbidden: src/plugin-sdk/channel/setup.ts -> ../provider/index.ts
• forbidden: src/plugin-sdk/channel.ts -> ./provider.ts

Migration Strategy

This should be a cutover, not a long overlap period.

That means:

• one coordinated release
• one migration guide
• one docs/templates/test update
• one public SDK shape after the release

Phase 1: Extract The Canonical API Builder

Do this first, before changing the public surface.

Why:

• it removes duplicated API assembly
• it gives one place to switch the public shape
• it reduces cutover risk

Implementation:

• extract one canonical API builder from src/plugins/registry.ts and src/plugins/captured-registration.ts
• make that builder assemble the new namespaced registration API

Phase 2: Add Canonical Namespace Entrypoints

Add:

• plugin
• channel
• provider

as thin public facades over existing flat leaves.

Implementation detail:

• the first pass can re-export current flat files
• do not move source layout and package exports in the same commit if it can be avoided

Examples:

• src/plugin-sdk/channel/setup.ts can initially re-export from ../channel-setup.js
• src/plugin-sdk/provider/auth.ts can initially re-export from ../provider-auth.js

This lets the public namespace story land before the internal source move, without forcing all implementation files to move in the same commit.

Phase 3: Cut Public API, Docs, And Templates Together

In the same release:

• docs prefer namespaced entrypoints
• templates prefer namespaced imports
• tests and examples switch to the namespaced shape
• OpenClawPluginApi changes to the namespaced registration model
• flat registration methods are removed instead of carried as aliases

Phase 4: Remove The Old Public Story

After the cutover release lands:

• stop documenting superseded flat leaves as public API
• keep only the namespace model in author-facing docs
• remove any leftover flat registration surface that survived only as transitional scaffolding during implementation

What Should Not Be Namespaced In Phase 1

To keep the refactor tight, do not force these into the first milestone:

• every *-runtime helper subpath
• extension-branded public subpaths
• one-off utilities that do not yet have a stable domain home
• the root openclaw/plugin-sdk barrel

If a subpath is only public because history leaked it, namespace work should not promote it.

Guardrails And Validation

The namespace rollout should ship with explicit checks.

Existing Checks To Reuse

• src/plugin-sdk/subpaths.test.ts
• src/plugin-sdk/runtime-api-guardrails.test.ts
• pnpm build for [CIRCULAR_REEXPORT] warnings
• pnpm plugin-sdk:api:check

New Checks To Add

• namespace facade files may only re-export or compose approved leaves
• leaf files under a namespace may not import their parent index facade
• leaf files under one namespace may not import another namespace facade
• cross-namespace leaf imports should fail unless the target is an approved shared internal leaf
• namespace facades may not import other namespace facades
• no new API should be added to core once namespace facades exist
• OpenClawPluginApi must not expose both flat and namespaced registration methods after cutover

Recommended End State

The elegant end state is:

• a tiny root
• a few first-class namespaces
• direct types
• a grouped api registration surface
• stable leaves under each namespace
• no reverse imports from leaves back into namespace facades

That gives OpenClaw a VS Code-like feel where the public SDK has clear domains, but still respects the repo's existing build, lazy-loading, and package-boundary constraints.

Short Recommendation

If this work starts soon, the first implementation step should be:

1. extract one canonical OpenClawPluginApi builder
2. switch that builder to the namespaced registration shape
3. add plugin, channel, and provider facade entrypoints
4. cut docs, templates, and examples over in the same release
5. remove the old flat registration story instead of maintaining dual public APIs

That sequence keeps the refactor elegant and minimizes the chance that namespaces become another layer of accidental coupling.