diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 9d6457112..3227ca199 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
{
"repository": "openclaw/openclaw",
- "sha": "c018e7347542aa963095de1ca704b943476856fe",
- "syncedAt": "2026-04-25T01:11:43.237Z"
+ "sha": "0bd8d0bba08b386ca975510235e00df2139b3e70",
+ "syncedAt": "2026-04-25T01:15:06.736Z"
}
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index c258f2848..d9316d62c 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -1,2 +1,2 @@
-f74435d49aa0af2509264d8581e12ffc624b1d6542d250d608ee5c3b41a234f3 plugin-sdk-api-baseline.json
-df33bbe47bb092ed11814576b5386253140f7aa6f8479a5334aff9b988125afc plugin-sdk-api-baseline.jsonl
+1b8ce6687d91267f78f589ee29d4cca0809fde73ea47c82ddbd14ecf54f1803a plugin-sdk-api-baseline.json
+55c48203fe5d6409f690f4d27abde41502feec1bfb63d9096cd9958fcf45c2c2 plugin-sdk-api-baseline.jsonl
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index 036d37f24..4759be5cc 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -431,7 +431,7 @@ Each list is optional:
| Field | Type | What it means |
| -------------------------------- | ---------- | --------------------------------------------------------------------- |
-| `embeddedExtensionFactories` | `string[]` | Deprecated embedded extension factory ids. |
+| `embeddedExtensionFactories` | `string[]` | Codex app-server extension factory ids, currently `codex-app-server`. |
| `agentToolResultMiddleware` | `string[]` | Runtime ids a bundled plugin may register tool-result middleware for. |
| `externalAuthProviders` | `string[]` | Provider ids whose external auth profile hook this plugin owns. |
| `speechProviders` | `string[]` | Speech provider ids this plugin owns. |
@@ -445,12 +445,12 @@ Each list is optional:
| `webSearchProviders` | `string[]` | Web-search provider ids this plugin owns. |
| `tools` | `string[]` | Agent tool names this plugin owns for bundled contract checks. |
-`contracts.embeddedExtensionFactories` is retained for bundled compatibility
-code that still needs direct Pi embedded-runner events. New bundled
-tool-result transforms should declare `contracts.agentToolResultMiddleware`
-and register with `api.registerAgentToolResultMiddleware(...)` instead.
-External plugins cannot register tool-result middleware because the seam can
-rewrite high-trust tool output before the model sees it.
+`contracts.embeddedExtensionFactories` is retained for bundled Codex
+app-server-only extension factories. Bundled tool-result transforms should
+declare `contracts.agentToolResultMiddleware` and register with
+`api.registerAgentToolResultMiddleware(...)` instead. External plugins cannot
+register tool-result middleware because the seam can rewrite high-trust tool
+output before the model sees it.
Provider plugins that implement `resolveExternalAuthProfiles` should declare
`contracts.externalAuthProviders`. Plugins without the declaration still run
diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md
index b1b5f9cdb..9f3d8f106 100644
--- a/docs/plugins/sdk-agent-harness.md
+++ b/docs/plugins/sdk-agent-harness.md
@@ -155,9 +155,8 @@ tool output back into the model.
Legacy bundled plugins can still use
`api.registerCodexAppServerExtensionFactory(...)` for Codex app-server-only
middleware, but new result transforms should use the runtime-neutral API.
-The Pi-only `api.registerEmbeddedExtensionFactory(...)` hook is deprecated for
-tool-result transforms; keep it only for bundled compatibility code that still
-needs direct Pi embedded-runner events.
+The Pi-only `api.registerEmbeddedExtensionFactory(...)` hook has been removed;
+Pi tool-result transforms must use runtime-neutral middleware.
### Native Codex harness mode
diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md
index 262c1ad1d..2e824ddbf 100644
--- a/docs/plugins/sdk-migration.md
+++ b/docs/plugins/sdk-migration.md
@@ -5,7 +5,7 @@ sidebarTitle: "Migrate to SDK"
read_when:
- You see the OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED warning
- You see the OPENCLAW_EXTENSION_API_DEPRECATED warning
- - You use api.registerEmbeddedExtensionFactory
+ - You used api.registerEmbeddedExtensionFactory before OpenClaw 2026.4.24
- You are updating a plugin to the modern plugin architecture
- You maintain an external OpenClaw plugin
---
@@ -24,12 +24,14 @@ anything they needed from a single entry point:
new plugin architecture was being built.
- **`openclaw/extension-api`** — a bridge that gave plugins direct access to
host-side helpers like the embedded agent runner.
-- **`api.registerEmbeddedExtensionFactory(...)`** — a Pi-only bundled extension
- hook that could observe embedded-runner events such as `tool_result`.
+- **`api.registerEmbeddedExtensionFactory(...)`** — a removed Pi-only bundled
+ extension hook that could observe embedded-runner events such as
+ `tool_result`.
-These surfaces are now **deprecated**. They still work at runtime, but new
-plugins must not use them, and existing plugins should migrate before the next
-major release removes them.
+The broad import surfaces are now **deprecated**. They still work at runtime,
+but new plugins must not use them, and existing plugins should migrate before
+the next major release removes them. The Pi-only embedded extension factory
+registration API has been removed; use tool-result middleware instead.
OpenClaw does not remove or reinterpret documented plugin behavior in the same
change that introduces a replacement. Breaking contract changes must first go
@@ -40,6 +42,7 @@ registration behavior.
The backwards-compatibility layer will be removed in a future major release.
Plugins that still import from these surfaces will break when that happens.
+ Pi-only embedded extension factory registrations already no longer load.
## Why this changed
@@ -91,19 +94,12 @@ releases.
- Bundled plugins should replace Pi-only
+ Bundled plugins must replace Pi-only
`api.registerEmbeddedExtensionFactory(...)` tool-result handlers with
runtime-neutral middleware.
```typescript
- // Before: Pi-only compatibility hook
- api.registerEmbeddedExtensionFactory((pi) => {
- pi.on("tool_result", async (event) => {
- return compactToolResult(event);
- });
- });
-
- // After: Pi and Codex runtime dynamic tools
+ // Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
return compactToolResult(event);
}, {
@@ -121,10 +117,8 @@ releases.
}
```
- Keep `contracts.embeddedExtensionFactories` only for bundled compatibility
- code that still needs direct Pi embedded-runner events. External plugins
- cannot register tool-result middleware because it can rewrite high-trust
- tool output before the model sees it.
+ External plugins cannot register tool-result middleware because it can
+ rewrite high-trust tool output before the model sees it.
@@ -624,8 +618,8 @@ canonical replacement.
Covered in "How to migrate → Migrate Pi tool-result extensions to
- middleware" above. Included here for completeness: the Pi-only
- `api.registerEmbeddedExtensionFactory(...)` path is deprecated in favor of
+ middleware" above. Included here for completeness: the removed Pi-only
+ `api.registerEmbeddedExtensionFactory(...)` path is replaced by
`api.registerAgentToolResultMiddleware(...)` with an explicit runtime
list in `contracts.agentToolResultMiddleware`.
diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md
index f1671fe09..b96e58c2c 100644
--- a/docs/plugins/sdk-overview.md
+++ b/docs/plugins/sdk-overview.md
@@ -96,19 +96,18 @@ methods:
### Infrastructure
-| Method | What it registers |
-| ----------------------------------------------- | --------------------------------------- |
-| `api.registerHook(events, handler, opts?)` | Event hook |
-| `api.registerHttpRoute(params)` | Gateway HTTP endpoint |
-| `api.registerGatewayMethod(name, handler)` | Gateway RPC method |
-| `api.registerGatewayDiscoveryService(service)` | Local Gateway discovery advertiser |
-| `api.registerCli(registrar, opts?)` | CLI subcommand |
-| `api.registerService(service)` | Background service |
-| `api.registerInteractiveHandler(registration)` | Interactive handler |
-| `api.registerAgentToolResultMiddleware(...)` | Runtime tool-result middleware |
-| `api.registerEmbeddedExtensionFactory(factory)` | Deprecated PI extension factory |
-| `api.registerMemoryPromptSupplement(builder)` | Additive memory-adjacent prompt section |
-| `api.registerMemoryCorpusSupplement(adapter)` | Additive memory search/read corpus |
+| Method | What it registers |
+| ---------------------------------------------- | --------------------------------------- |
+| `api.registerHook(events, handler, opts?)` | Event hook |
+| `api.registerHttpRoute(params)` | Gateway HTTP endpoint |
+| `api.registerGatewayMethod(name, handler)` | Gateway RPC method |
+| `api.registerGatewayDiscoveryService(service)` | Local Gateway discovery advertiser |
+| `api.registerCli(registrar, opts?)` | CLI subcommand |
+| `api.registerService(service)` | Background service |
+| `api.registerInteractiveHandler(registration)` | Interactive handler |
+| `api.registerAgentToolResultMiddleware(...)` | Runtime tool-result middleware |
+| `api.registerMemoryPromptSupplement(builder)` | Additive memory-adjacent prompt section |
+| `api.registerMemoryCorpusSupplement(adapter)` | Additive memory search/read corpus |
Reserved core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`,
@@ -126,14 +125,8 @@ methods:
Bundled plugins must declare `contracts.agentToolResultMiddleware` for each
targeted runtime, for example `["pi", "codex"]`. External plugins
cannot register this middleware; keep normal OpenClaw plugin hooks for work
-that does not need pre-model tool-result timing.
-
-
-
- `api.registerEmbeddedExtensionFactory(...)` is deprecated. It remains a
- compatibility seam for bundled plugins that still need direct Pi
- embedded-runner events. New tool-result transforms should use
- `api.registerAgentToolResultMiddleware(...)` instead.
+that does not need pre-model tool-result timing. The old Pi-only embedded
+extension factory registration path has been removed.
### Gateway discovery registration