@oai404iao/pi-codex-runtime 0.1.0-alpha.1

package/models.schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@oai404iao/pi-codex-minimal-tools@1/models.schema.json",
+  "title": "@oai404iao/pi-codex-minimal-tools model catalog overrides",
+  "description": "Per-model Codex protocol and tool capability profiles. User entries override bundled entries by exact provider/model id.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "models"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema URL used by editors for validation and completion.",
+      "default": "https://unpkg.com/@oai404iao/pi-codex-minimal-tools@1/models.schema.json"
+    },
+    "version": {
+      "const": 1,
+      "description": "Model catalog format version.",
+      "default": 1
+    },
+    "models": {
+      "type": "array",
+      "description": "Exact per-model profiles. Duplicate ids in one user file are rejected.",
+      "items": {
+        "$ref": "#/$defs/model"
+      },
+      "default": []
+    }
+  },
+  "$defs": {
+    "modelId": {
+      "type": "string",
+      "pattern": "^[^\\s/]+/\\S+$"
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/modelId",
+          "description": "Exact provider/model id, for example openai/gpt-5.5."
+        },
+        "extends": {
+          "$ref": "#/$defs/modelId",
+          "description": "Optional parent profile. The parent is deep-merged first; arrays are replaced."
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether this profile can activate extension behavior."
+        },
+        "responses": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "providerShim": {
+              "type": "boolean",
+              "description": "Use this extension's Codex Responses serializer/parser. The Pi model must use api openai-responses or openai-codex-responses."
+            },
+            "endpoint": {
+              "enum": ["auto", "openai", "codex"],
+              "description": "Endpoint and authentication shape."
+            },
+            "mode": {
+              "enum": ["standard", "lite"],
+              "description": "Standard Responses or the internal Codex Responses Lite envelope."
+            },
+            "reasoningSummary": {
+              "enum": ["auto", "concise", "detailed", "none"],
+              "description": "Reasoning summary mode. none omits reasoning.summary; absent defaults to auto in Standard mode and none in Lite mode."
+            },
+            "systemPromptPlacement": {
+              "enum": ["instructions", "developer"],
+              "description": "Standard-mode prompt placement. Lite always uses a developer message."
+            },
+            "transport": {
+              "enum": ["sse", "websocket", "websocket-cached", "auto"],
+              "description": "Responses transport and continuation strategy."
+            },
+            "websocketPrewarm": {
+              "type": "boolean",
+              "description": "At session startup, schedule one best-effort generate:false prewarm request containing only the stable system/tool envelope."
+            }
+          }
+        },
+        "tools": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "parallelCalls": {
+              "type": "boolean",
+              "description": "Whether the request permits parallel tool calls. Lite always forces false."
+            },
+            "applyPatch": {
+              "description": "Disable apply_patch, expose a JSON function tool, or use the Codex freeform custom tool.",
+              "enum": [false, "function", "custom"],
+              "enumDescriptions": [
+                "Do not expose an apply_patch tool.",
+                "Expose apply_patch as a regular JSON function tool.",
+                "Expose apply_patch as the Codex freeform custom tool."
+              ]
+            },
+            "webSearch": {
+              "description": "Disable web search or choose hosted Responses search versus standalone Codex web.run.",
+              "if": {
+                "type": "boolean"
+              },
+              "then": {
+                "const": false
+              },
+              "else": {
+                "type": "object"
+              },
+              "defaultSnippets": [
+                {
+                  "label": "Disable web search",
+                  "description": "Do not expose web search for this model.",
+                  "body": false
+                },
+                {
+                  "label": "Hosted web search",
+                  "description": "Use the server-executed Responses web_search tool.",
+                  "body": {
+                    "implementation": "hosted"
+                  }
+                },
+                {
+                  "label": "Standalone web search",
+                  "description": "Expose web.run and call the Codex alpha/search endpoint.",
+                  "body": {
+                    "implementation": "standalone"
+                  }
+                }
+              ],
+              "additionalProperties": false,
+              "required": ["implementation"],
+              "properties": {
+                "implementation": {
+                  "enum": ["hosted", "standalone"],
+                  "enumDescriptions": [
+                    "Use the server-executed Responses web_search tool.",
+                    "Expose web.run and call the Codex alpha/search endpoint."
+                  ]
+                },
+                "contentTypes": {
+                  "type": "array",
+                  "description": "Search modalities advertised or accepted by this model.",
+                  "minItems": 1,
+                  "items": {
+                    "enum": ["text", "image"]
+                  },
+                  "uniqueItems": true
+                }
+              }
+            },
+            "imageGeneration": {
+              "description": "Disable image generation, use hosted Responses image_generation, or use standalone Codex Images endpoints.",
+              "enum": [false, "hosted", "standalone"],
+              "enumDescriptions": [
+                "Do not expose an image-generation tool.",
+                "Use the hosted Responses image_generation tool.",
+                "Expose image_gen.imagegen and call the standalone Codex Images endpoints."
+              ]
+            },
+            "viewImage": {
+              "type": "boolean",
+              "description": "Expose the local view_image tool when the Pi model accepts image input."
+            }
+          }
+        },
+        "compaction": {
+          "enum": ["pi", "responses", "responses-compact"],
+          "description": "Pi summary compaction, Codex remote compaction v2, or the legacy /responses/compact endpoint."
+        },
+        "fast": {
+          "description": "Disable Fast mode for this model or configure its service tier and optional usage-cost multiplier.",
+          "if": {
+            "type": "boolean"
+          },
+          "then": {
+            "const": false
+          },
+          "else": {
+            "type": "object"
+          },
+          "defaultSnippets": [
+            {
+              "label": "Disable Fast mode",
+              "description": "Do not enable a Fast service tier for this model.",
+              "body": false
+            },
+            {
+              "label": "Configure Fast mode",
+              "description": "Configure the Responses service tier used by the global Fast toggle.",
+              "body": {
+                "serviceTier": "priority"
+              }
+            }
+          ],
+          "additionalProperties": false,
+          "required": ["serviceTier"],
+          "properties": {
+            "serviceTier": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Responses service_tier value sent when the global Fast toggle is enabled."
+            },
+            "costMultiplier": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "description": "Optional multiplier applied to Pi's reported request cost for this tier."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@oai404iao/pi-codex-runtime",
+  "version": "0.1.0-alpha.1",
+  "private": false,
+  "description": "Unpublished pi-codex-runtime workspace for the staged Codex split",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oai404iao/omp.git",
+    "directory": "pi-extensions/pi-codex-runtime"
+  },
+  "homepage": "https://github.com/oai404iao/omp/tree/main/pi-extensions/pi-codex-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/oai404iao/omp/issues"
+  },
+  "keywords": [
+    "pi-codex-runtime"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./internal/*": "./src/*.ts",
+    "./subagent-inline": "./src/subagent-inline.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.2",
+    "@earendil-works/pi-coding-agent": ">=0.84.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "^26.2.0",
+    "tsx": "^4.20.6",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "check": "npm run typecheck && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "LICENSES/",
+    "THIRD_PARTY_NOTICES.md",
+    "provenance/",
+    "README.md",
+    "config.schema.json",
+    "models.schema.json"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "gitHead": "32ba01f3c08b7fd63d09e9b2373cf081c4525533"
+}

package/provenance/openai-codex-eb9dceba-reserved-tools.json

@@ -0,0 +1,140 @@
+{
+  "schemaVersion": 1,
+  "upstream": {
+    "repository": "https://github.com/openai/codex",
+    "revision": "eb9dceba1a2e658142a456c5898836774835616b",
+    "commitUrl": "https://github.com/openai/codex/commit/eb9dceba1a2e658142a456c5898836774835616b",
+    "license": "Apache-2.0"
+  },
+  "files": {
+    "LICENSE": {
+      "role": "upstream Apache-2.0 license",
+      "gitBlobSha": "4606e72e042564097e8780d66c1d4dcb611869bd",
+      "sha256": "d17f227e4df5da1600391338865ce0f3055211760a36688f816941d58232d8dc",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/LICENSE"
+    },
+    "NOTICE": {
+      "role": "upstream NOTICE",
+      "gitBlobSha": "2805899d56d0332d175cfc613c67d45d6f006db7",
+      "sha256": "9d71575ecfd9a843fc1677b0efb08053c6ba9fd686a0de1a6f5382fd3c220915",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/NOTICE"
+    },
+    "codex-rs/ext/web-search/web_run_description.md": {
+      "role": "exact web.run function description",
+      "gitBlobSha": "77be9a0a03e6e2e2760651e903ead2dce9996a57",
+      "sha256": "1f3879b44690eb7aad9ba97351acda16c4d0c26847bcb4af2964d5989404407e",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/web-search/web_run_description.md"
+    },
+    "codex-rs/ext/web-search/src/tool.rs": {
+      "role": "web namespace and tool construction",
+      "gitBlobSha": "9747b75eddd1052ee4d75e868a644de7fd4135c1",
+      "sha256": "6ce56d7705c4b29b91d9d39af5468788a04dd925b414c7b44de67014f3329cb3",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/web-search/src/tool.rs"
+    },
+    "codex-rs/ext/web-search/src/schema.rs": {
+      "role": "web parameter-schema generation",
+      "gitBlobSha": "2f71f1595c3b75d21cf78f35877f75b9314a3737",
+      "sha256": "6371391751d2a5dddad546aa810a6c64f770498702cec8153df74d1d7dff6f9b",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/web-search/src/schema.rs"
+    },
+    "codex-rs/codex-api/src/search.rs": {
+      "role": "web SearchCommands input types",
+      "gitBlobSha": "237e7a7ebff4a0eeaa6dbb7b94c457d23dfc09de",
+      "sha256": "a83fd7ddd41c86985cce2aa899a2907ca820c226d5e7337949cc7e47a35c5f4f",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/codex-api/src/search.rs"
+    },
+    "codex-rs/ext/image-generation/imagegen_description.md": {
+      "role": "exact image_gen.imagegen function description",
+      "gitBlobSha": "368aa10ea8f1909f9171b7a7b701bba6321f6f89",
+      "sha256": "77a992a7c90e45fcd11623a1efa34bfd4c7870697e0aa54ce9b28f690877170e",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/image-generation/imagegen_description.md"
+    },
+    "codex-rs/ext/image-generation/src/lib.rs": {
+      "role": "image namespace and function names",
+      "gitBlobSha": "fd9db419309e5b06acb944a553f5ef144c8a261d",
+      "sha256": "c710abe1967cd3f7faaf78c0a35de0f5e6cc5c461f130b79d2b25d27ba8df9de",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/image-generation/src/lib.rs"
+    },
+    "codex-rs/ext/image-generation/src/tool.rs": {
+      "role": "image namespace-tool construction and ImagegenArgs schema",
+      "gitBlobSha": "ab973da74cec4de053cbe943171bb9ad5703bad6",
+      "sha256": "8b8abe637c63e1fa8f52340a4609d96f37a5089364c4d82f0e695fd6731b2206",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/ext/image-generation/src/tool.rs"
+    },
+    "codex-rs/tools/src/responses_api.rs": {
+      "role": "namespace serialization and descriptions",
+      "gitBlobSha": "e450dcf35f93ab4af7bf3f34956755066114ccae",
+      "sha256": "7af0354e43c3fa7f052d86df5ae0c6ce276569243af6f6ea5fe00abcb15bd244",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/tools/src/responses_api.rs"
+    },
+    "codex-rs/tools/src/tool_spec.rs": {
+      "role": "Responses Lite namespace-tool serialization",
+      "gitBlobSha": "530da1be164ce3c6aa4b128ccb878bda7025e217",
+      "sha256": "af8b5286fb6d2eb3574c484b25076f515bca2d4350ecb5059e436966ecdd519d",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/tools/src/tool_spec.rs"
+    },
+    "codex-rs/core/src/client.rs": {
+      "role": "Responses Lite additional_tools placement",
+      "gitBlobSha": "da3b6dad382fd4520026ac447c270e5cc11fa887",
+      "sha256": "4b4d00234a7fb649525fdcc913ffe288e4ef3348a916acbd265c22607fd8652d",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/core/src/client.rs"
+    },
+    "codex-rs/Cargo.toml": {
+      "role": "pinned workspace dependency manifest for schema generation",
+      "gitBlobSha": "f23232e3d0b8246330d2409fc7fe9690062075c2",
+      "sha256": "2e8122fdd528a4d648d9417865153827dc5f7b45ee3afd86bfb129a1e01dcdb8",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/Cargo.toml"
+    },
+    "codex-rs/Cargo.lock": {
+      "role": "pinned schema-generator dependency lockfile",
+      "gitBlobSha": "a67d1f3d7b062424d881a612f4cfd8b14e0ac630",
+      "sha256": "3a4a5361f289227c1ce09dc072811a1e7d1c7b599c58dd91dce6758d187c993d",
+      "rawUrl": "https://raw.githubusercontent.com/openai/codex/eb9dceba1a2e658142a456c5898836774835616b/codex-rs/Cargo.lock"
+    }
+  },
+  "localCompatibilitySerialization": {
+    "path": "src/codex-reserved-tools.ts",
+    "classification": "modified TypeScript compatibility serialization",
+    "boundary": "This local compatibility path uses an internal Codex Responses Lite shape and does not claim a stable or OpenAI-supported public API contract.",
+    "canonicalization": "SHA-256 of recursively lexicographically sorted JSON object keys; arrays retain their order and no whitespace is emitted.",
+    "namespaces": {
+      "web_search": {
+        "namespace": "web",
+        "function": "run",
+        "description": {
+          "sourcePath": "codex-rs/ext/web-search/web_run_description.md",
+          "relationship": "byte-for-byte",
+          "sha256": "1f3879b44690eb7aad9ba97351acda16c4d0c26847bcb4af2964d5989404407e"
+        },
+        "parameters": {
+          "sourcePaths": [
+            "codex-rs/ext/web-search/src/tool.rs",
+            "codex-rs/ext/web-search/src/schema.rs",
+            "codex-rs/codex-api/src/search.rs"
+          ],
+          "relationship": "compatibility serialization",
+          "canonicalJsonSha256": "de3be87e7abfe9b67ba757f27804d4206b51c2a8de9e9799fa7db9ef4abe3539"
+        },
+        "canonicalJsonSha256": "f67597d3df3f3a77cb517646508e7305804ea029c6f8b1c1c1f241f0de0b214f"
+      },
+      "image_generation": {
+        "namespace": "image_gen",
+        "function": "imagegen",
+        "description": {
+          "sourcePath": "codex-rs/ext/image-generation/imagegen_description.md",
+          "relationship": "byte-for-byte",
+          "sha256": "77a992a7c90e45fcd11623a1efa34bfd4c7870697e0aa54ce9b28f690877170e"
+        },
+        "parameters": {
+          "sourcePaths": [
+            "codex-rs/ext/image-generation/src/lib.rs",
+            "codex-rs/ext/image-generation/src/tool.rs"
+          ],
+          "relationship": "compatibility serialization",
+          "canonicalJsonSha256": "b4fea7c38ae74635e0072643ac2030899db242657071271e13cdd192a7377a27"
+        },
+        "canonicalJsonSha256": "ccc508cff0a216bbdf368be8c98be94134a1aed0479cddd28c77d8e004f5b73e"
+      }
+    }
+  }
+}

package/src/activation.ts

@@ -0,0 +1,56 @@
+import type { ModelLike } from "./capabilities.js";
+import { listResolvedModelProfiles, resolveModelProfile } from "./model-catalog/catalog.js";
+import type { CodexMinimalToolsSettings } from "./settings.js";
+
+export interface ModelRegistryLike {
+	getAll?: () => unknown;
+	getAvailable?: () => unknown;
+	find?: (provider: string, id: string) => unknown;
+}
+
+export interface ActivationContextLike {
+	model?: ModelLike;
+	modelRegistry?: ModelRegistryLike;
+}
+
+export function registryModels(registry: ModelRegistryLike | undefined): ModelLike[] {
+	if (!registry) return [];
+	for (const method of [registry.getAll, registry.getAvailable]) {
+		if (typeof method !== "function") continue;
+		try {
+			const value = method.call(registry);
+			if (Array.isArray(value)) return value.filter((model): model is ModelLike => Boolean(model) && typeof model === "object");
+		} catch {
+			// Try the next registry shape.
+		}
+	}
+	return [];
+}
+
+export function hasConfiguredModelsLoaded(
+	ctx: ActivationContextLike,
+	settings?: CodexMinimalToolsSettings,
+): boolean {
+	const current = resolveModelProfile(ctx.model, { settings });
+	if (current?.effective.enabled) return true;
+	const configured = new Set(
+		listResolvedModelProfiles({ settings })
+			.filter((profile) => profile.effective.enabled)
+			.map((profile) => profile.id.toLowerCase()),
+	);
+	if (registryModels(ctx.modelRegistry).some((model) => {
+		const provider = model.provider?.trim().toLowerCase();
+		const id = model.id?.trim().toLowerCase();
+		return Boolean(provider && id && configured.has(`${provider}/${id}`));
+	})) {
+		return true;
+	}
+	try {
+		return [...configured].some((fullId) => {
+			const slash = fullId.indexOf("/");
+			return Boolean(ctx.modelRegistry?.find?.(fullId.slice(0, slash), fullId.slice(slash + 1)));
+		});
+	} catch {
+		return false;
+	}
+}

package/src/broker.ts

@@ -0,0 +1,133 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createRequire } from "node:module";
+import type { PackageToolName } from "./capabilities.js";
+import type { ProviderPresentation } from "./extension/provider-presentation.js";
+
+export const CODEX_BROKER_CHANNEL = "@oai404iao/pi-codex:broker";
+export const CODEX_RUNTIME_VERSION: string = createRequire(import.meta.url)("../package.json").version;
+const CACHE = Symbol.for("@oai404iao/pi-codex/broker/v1");
+
+export interface InstalledTool {
+	register(): void;
+	registered: boolean;
+}
+
+export interface CodexBroker {
+	readonly version: 1;
+	readonly runtimeVersion: string;
+	readonly closed: boolean;
+	readonly tools: Map<PackageToolName, InstalledTool>;
+	coreEnabled: boolean;
+	claim(name: string): boolean;
+	addPresentation(name: string, presentation: ProviderPresentation): void;
+	presentation: ProviderPresentation;
+}
+
+function createBroker(): CodexBroker & { close(): void } {
+	const claims = new Set<string>();
+	const tools = new Map<PackageToolName, InstalledTool>();
+	const presentations = new Map<string, ProviderPresentation>();
+	const rendered = new Set<string>();
+	let closed = false;
+	const ordered = () => [...presentations].sort(([a], [b]) => a.localeCompare(b));
+	return {
+		version: 1,
+		runtimeVersion: CODEX_RUNTIME_VERSION,
+		get closed() { return closed; },
+		coreEnabled: false,
+		tools,
+		claim(name) {
+			if (closed) throw new Error("Codex broker belongs to a closed session");
+			if (claims.has(name)) return false;
+			claims.add(name);
+			return true;
+		},
+		addPresentation(name, presentation) {
+			if (closed) throw new Error("Codex broker belongs to a closed session");
+			if (presentations.has(name)) throw new Error(`Duplicate Codex presentation: ${name}`);
+			presentations.set(name, presentation);
+		},
+		presentation: {
+			clear() { for (const [, p] of ordered()) p.clear(); },
+			flush() { for (const [, p] of ordered()) p.flush(); },
+			scheduleFlush() { for (const [, p] of ordered()) p.scheduleFlush(); },
+			registerRenderers() {
+				for (const [name, p] of ordered()) {
+					if (rendered.has(name)) continue;
+					p.registerRenderers();
+					rendered.add(name);
+				}
+			},
+			streamEffects() {
+				// Capture contributions and their session-owned sinks before I/O.
+				const effects = ordered().map(([, p]) => p.streamEffects());
+				return {
+					createEventObserver(context) {
+						const observers = effects.map(p => p.createEventObserver?.(context)).filter(
+							(observer): observer is NonNullable<typeof observer> => !!observer,
+						);
+						return async event => { for (const observe of observers) await observe(event); };
+					},
+				};
+			},
+		},
+		close() { closed = true; },
+	};
+}
+
+function isCompatible(candidate: CodexBroker): boolean {
+	return candidate?.version === 1 && candidate.runtimeVersion === CODEX_RUNTIME_VERSION
+		&& typeof candidate.claim === "function"
+		&& typeof candidate.addPresentation === "function"
+		&& typeof candidate.tools?.get === "function"
+		&& typeof candidate.tools?.set === "function"
+		&& typeof candidate.closed === "boolean"
+		&& typeof candidate.coreEnabled === "boolean"
+		&& ["clear", "flush", "scheduleFlush", "registerRenderers", "streamEffects"].every(
+			name => typeof (candidate.presentation as unknown as Record<string, unknown>)?.[name] === "function",
+		);
+}
+
+function incompatibleBroker(): Error {
+	return new Error(`Incompatible or duplicate Codex capability broker: requires ABI v1 and runtime ${CODEX_RUNTIME_VERSION}`);
+}
+
+/**
+ * Pi gives each extension a separate API/module root. Synchronous event-bus
+ * discovery shares the v1 service across those roots; no module-global registry
+ * or equality of pi.events wrapper objects is assumed. The cached property is
+ * only a fast path (and supports minimal ExtensionAPI test doubles).
+ */
+export function getCodexBroker(pi: ExtensionAPI): CodexBroker {
+	const api = pi as ExtensionAPI & { [CACHE]?: CodexBroker };
+	const cached = api[CACHE];
+	if (cached && cached.closed !== true) {
+		// Different runtime copies can receive the same API object.
+		if (!isCompatible(cached)) throw incompatibleBroker();
+		return cached;
+	}
+	let found: CodexBroker | undefined;
+	let incompatible = false;
+	pi.events?.emit(CODEX_BROKER_CHANNEL, {
+		version: 1,
+		accept(candidate: CodexBroker) {
+			if (!isCompatible(candidate)) incompatible = true;
+			else if (!candidate.closed) {
+				if (found && found !== candidate) incompatible = true;
+				found = candidate;
+			}
+		},
+	});
+	if (incompatible) throw incompatibleBroker();
+	if (found) return (api[CACHE] = found);
+	const broker = createBroker();
+	const unsubscribe = pi.events?.on(CODEX_BROKER_CHANNEL, value => {
+		const request = value as { accept?: (broker: CodexBroker) => void } | undefined;
+		if (!broker.closed && typeof request?.accept === "function") request.accept(broker);
+	});
+	pi.on("session_shutdown", () => {
+		broker.close();
+		unsubscribe?.();
+	});
+	return (api[CACHE] = broker);
+}