vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 13:50:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(plugins): remove Pi tool result compat

Browse Source
This commit is contained in:
Vincent Koc
2026-04-24 18:09:49 -07:00
parent ea168c22ce
commit 0bd8d0bba0
22 changed files with 50 additions and 427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/plugins/manifest.md
View File

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

5
docs/plugins/sdk-agent-harness.md
View File

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

36
docs/plugins/sdk-migration.md
View File

@@ -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.
<Warning>
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.
</Warning>
## Why this changed
@@ -91,19 +94,12 @@ releases.
<Steps>
<Step title="Migrate Pi tool-result extensions to middleware">
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.
</Step>
@@ -624,8 +618,8 @@ canonical replacement.
<Accordion title="Embedded extension factories → agent tool-result middleware">
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`.
</Accordion>

35
docs/plugins/sdk-overview.md
View File

@@ -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 |
<Note>
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.
</Accordion>
<Accordion title="Legacy Pi extension factories">
`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.
</Accordion>
### Gateway discovery registration