feat(agents): portable harness extensions (agents/harness/extensions)

.changeset/portable-harness-extensions.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Add `agents/harness/extensions` (experimental): one extension format for every harness. An extension is a function of its context. It can add tools (including deferred tools a session activates), hook tool calls (edit, block, or ask the user), set system prompt sections, add skills and slash commands, observe session events, keep durable state with `ctx.storage`, and drive sessions. Transforms rebuild from scratch on every reload. `PiHarness` takes them as `extensions`, hands its factory the `registry` to open pi with, and adds `commands()`, `requests()`, `reply()` and `extensions()`.

design/AGENTS.md

@@ -109,6 +109,7 @@ Keep it concise. A few paragraphs is fine. These are records, not essays.
 | `rfc-fibers.md`                          | RFC        | Tasks (née Fibers) — durable replayable execution as one Lifecycle capability: named definitions, journaled steps, sleeps, optional recovery callback (accepted, amended)       |
 | `rfc-streams.md`                         | RFC        | Streams — durable incremental output as a Lifecycle capability: chunk log, cursor, replay-then-tail reads, composed with Tasks via checkpointed cursors (proposed)              |
 | `rfc-pi-harness-example.md`              | RFC        | pi-durable as an example-local Lifecycle capability with a per-session wake job and a pi session store; what must land before it becomes a package export (proposed)            |
+| `rfc-portable-harness-extensions.md`     | RFC        | One code-first extension format for Pi, OpenCode, Think and container harnesses; the Pi adapter and ports of the top five pi packages (proposed)                                |
 | `rfc-self-modifying-harness.md`          | RFC        | Editable harness source in Workspace, activation through Worker Bundler, and one fresh Dynamic Worker per turn (proposed)                                                       |
 | `browser-sessions.md`                    | design doc | Persistent `Browser` behind `browserTool` — one browser per object, reattach-or-create, restart signaling                                                                       |
 

design/README.md

@@ -22,3 +22,4 @@ The goal is to give contributors (and future-us) a quick way to understand _why_
 | [rfc-harness-model-provider-boundary.md](./rfc-harness-model-provider-boundary.md) | RFC: LanguageModelV4 for Codex and pi-ai providers for Pi in v1               |
 | [test-coverage-matrix.md](./test-coverage-matrix.md)                               | Feature × test-layer coverage rollup, CI mapping, skipped-test debt, hygiene  |
 | [rfc-pi-harness-example.md](./rfc-pi-harness-example.md)                           | RFC: pi-durable as an example-local Lifecycle capability                      |
+| [rfc-portable-harness-extensions.md](./rfc-portable-harness-extensions.md)         | RFC: one extension format for every harness                                   |

packages/agents/AGENTS.md

@@ -12,6 +12,7 @@ Each export maps to a public entry point that users `import` from. These are the
 | `agents/client`                           | `src/client.ts`                               | Browser/Node WebSocket client (`AgentClient`) via partysocket                                    |
 | `agents/lifecycle`                        | `src/lifecycle/index.ts`                      | Composable Durable Object lifecycle and hibernating connections                                  |
 | `agents/harness/ai-sdk`                   | `src/harness/ai-sdk/index.ts`                 | Experimental: `AiSdkHarness`, AI SDK turn conversions and `createSendMessageTool`                |
+| `agents/harness/extensions`               | `src/harness/extensions/index.ts`             | Experimental: portable harness extensions (`defineExtension`, `ExtensionHost`)                   |
 | `agents/harness/pi`                       | `src/harness/pi/index.ts`                     | Experimental: pi-durable hosted in a Durable Object (`PiHarness`)                                |
 | `agents/react`                            | `src/react.tsx`                               | `useAgent` React hook, state sync, RPC from components                                           |
 | `agents/chat`                             | `src/chat/index.ts`                           | Shared chat primitives used by `@cloudflare/ai-chat` and `@cloudflare/think`                     |

packages/agents/package.json

@@ -177,6 +177,11 @@
       "import": "./dist/harness/ai-sdk/index.js",
       "require": "./dist/harness/ai-sdk/index.js"
     },
+    "./harness/extensions": {
+      "types": "./dist/harness/extensions/index.d.ts",
+      "import": "./dist/harness/extensions/index.js",
+      "require": "./dist/harness/extensions/index.js"
+    },
     "./harness/pi": {
       "types": "./dist/harness/pi/index.d.ts",
       "import": "./dist/harness/pi/index.js",

packages/agents/scripts/build.ts

@@ -11,6 +11,7 @@ const entries = [
   "src/skills/compile.ts",
   "src/lifecycle/index.ts",
   "src/harness/ai-sdk/index.ts",
+  "src/harness/extensions/index.ts",
   "src/harness/pi/index.ts",
   "src/routing/index.ts",
   "src/chat/index.ts",