## Resources\, event buses\, MCP and Gemini manifests Theo wants the notebook package to bring along guidance\. Rowan wants another extension to hear about a selected note\. Sora wants an external MCP service to contribute tools\. These are three different integration problems\. They should not be hidden behind the word “extension\.” ### Milestone\: return module\-relative resource paths Theo’s resource entry returns the location of a prompt\, rather than embedding all guidance inside a tool description\. **Complete public TypeScript source—[resources\.ts]()\:** ~~~ts import * as path from "node:path"; import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function fieldResources(pi: ExtensionAPI): void { pi.on("resources_discover", () => ({ promptPaths: [path.join(import.meta.dir, "../prompts/field-observation.md")], })); } ~~~ **Complete public Markdown resource—[field\-observation\.md]()\:** ~~~markdown --- description: Describe a fictional field observation --- Use field_catalog to query the fictional notebook. Summarize one returned note. Clearly label the observation as fictional; do not claim a real survey occurred. ~~~ The module\-relative absolute path works from a different cwd\. `resources_discover` handlers may return\: - `skillPaths`\; - `promptPaths`\; - `themePaths`\. The event includes `cwd` and reason `startup` or `reload`\. The runner aggregates each path with the originating `extensionPath`\. **Observed\:** explicit runner dispatch returned the real prompt path and retained `entries/resources.ts` provenance\. **Boundary\:** the supplied `AgentSession` startup path does not call `emitResourcesDiscover()`\. Registering this handler does not prove that a normal launch consumed its paths or populated a prompt menu\. A host must emit and consume the results\. OMP extension\-package sibling discovery is a separate path\: configured\/explicit package roots can contribute conventional `skills`\, `hooks`\, `tools`\, `commands`\, `rules`\, `prompts` and MCP resources\. A prompt appearing through that route would not prove the resource event fired\. **Exercise\:** launch from another directory and inspect the runner’s resource result in a host test\. **Checkpoint\:** the prompt path still resolves to the package’s file\. Then separately test whether your actual frontend consumes it\. ### Milestone\: choose a skill\, prompt or rule deliberately Theo decides that a reusable workflow belongs in a skill\, while a short invocation belongs in a prompt\. **Complete Markdown exercise—save as `.omp/skills/fictional-field-guide/SKILL.md`\:** ~~~markdown --- name: fictional-field-guide description: Inspect and summarize the workbook's fictional field catalog --- Use the available field_catalog tool to discover valid note IDs and query a habitat. Label every observation as fictional. If field_catalog is unavailable, explain that the extension must be loaded; do not invent inventory or tools. Do not claim that a real survey occurred. ~~~ The native skill scanner requires a description\. Native project skills can be discovered through ancestor traversal within its configured boundary\, unlike cwd\-only extension modules\. When skill commands are enabled\, the human command is\: **Human OMP slash command\:** ~~~text /skill:fictional-field-guide ~~~ That introduces guidance into the agent flow\. It is not the same as executing a local `registerCommand()` handler\. For a standing instruction\: **Complete Markdown exercise—save as `.omp/rules/fictional-data.md`\:** ~~~markdown --- description: Keep workbook data distinct from real observations alwaysApply: true --- Treat Seed Desk, Review Desk and Field Notes records as fictional fixtures. Never describe a workbook reservation as a physical stock change. ~~~ Rule files can carry descriptions\, globs\, always\-apply state and supported condition\/scope metadata\. The native top\-level `RULES.md` route forces sticky always\-apply behavior\. A rule cannot enforce permissions against arbitrary extension code\. Seed Desk still needs real checks in `changeReservation()`\. Prompt templates and Markdown commands likewise do not register missing tools\. Guidance should say what to do when the required capability is absent\. **Exercise\:** load only the skill\, without `field_catalog`\. **Checkpoint\:** the agent should diagnose the missing tool rather than invent a catalog result\. ### Milestone\: coordinate extensions on a process\-local bus Rowan wants selection changes to be observable without creating a model turn\. The public event\-bus entry both publishes and listens to a namespaced channel\. **Complete public TypeScript source—[event\-bus\.ts]()\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; const channel = "workbook:field-notes:selection"; export default function fieldNoteEvents(pi: ExtensionAPI): void { let selected: string | null = null; const unsubscribe = pi.events.on(channel, data => { if (data === "reed" || data === "fern") selected = data; }); pi.on("session_shutdown", () => unsubscribe()); const { Type } = pi.typebox; pi.registerTool({ name: "field_events", label: "Field events", description: "Discover or inspect the field-notes channel, query last selection, or act to publish reed/fern. In-process extension-runtime bus; selection survives /new and session switches within this binding, without durable delivery.", parameters: Type.Object({ op: Type.Union([Type.Literal("discover"), Type.Literal("inspect"), Type.Literal("query"), Type.Literal("act")]), id: Type.Optional(Type.Union([Type.Literal("reed"), Type.Literal("fern")])), }), async execute(_id, params) { if (params.op === "act") { if (!params.id) throw new Error("act requires a note id; nothing published."); pi.events.emit(channel, params.id); } const details = { channel, selected, operations: ["discover", "inspect", "query", "act"], delivery: "synchronous emit; asynchronous listeners are not awaited" }; return { content: [{ type: "text", text: JSON.stringify(details) }], details }; }, }); } ~~~ **Terminal shell\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/advanced/event-bus.ts" ~~~ **Model tool arguments—call `field_events`\:** ~~~json {"op":"act","id":"reed"} ~~~ ~~~json {"op":"query"} ~~~ **Observed\:** selection became `reed`\. After shutdown unsubscribed the listener\, a later bus emission did not update that selection in the isolated check\. `pi.events.on()` returns an unsubscribe function\. `emit()` invokes listeners but does not await asynchronous completion\. Listener failures are caught and logged by the bus wrapper\. The public selection update happens synchronously before the listener’s first await\, so this small tool can immediately observe it\. That does not establish an acknowledgement protocol for an asynchronous subscriber\. The bus is runtime\/process\-local coordination\. It is not\: - cross\-process messaging\; - a durable queue\; - an automatic agent turn\; - a shared backend\; - a transaction across extensions\. A host can supply an explicit shared bus to SDK sessions\; that is a deliberate scope choice\. Do not call `events.clear()` from one extension as ordinary cleanup—it clears everyone’s listeners\. The entry unsubscribes on shutdown\, not `/new`\. Its selection remains binding\-local across transcript changes\. **Exercise\:** make a subscriber save to a slow external store\. Does `emit()` mean the save completed\? **Answer\:** no\. Add an explicit result\/acknowledgement protocol or use a service API whose promise represents completion\. ### Milestone\: an MCP server is a real prerequisite Sora chooses MCP when the capability belongs in a separate process\/service rather than in OMP’s JavaScript process\. The supplied native discovery accepts MCP configuration including\: - server name\; - `command`\, `args`\, `env`\, optional `cwd` for process\-based servers\; - `url`\, `headers`\, transport type for remote servers\; - `enabled`\, `timeout`\, request\-ID format\; - supported auth\/OAuth configuration\, including credential references\. Native config candidates include project `.omp/mcp.json` and `.omp/.mcp.json`\, plus their active\-agent\-directory counterparts\. Other discovery providers have their own paths\. **Missing prerequisite\:** an actual MCP server executable or reachable service\, a compatible transport and any required credentials\. This workbook does not supply a fake endpoint and label it working\. A separate MCP connection can discover tools\, resources and prompts\. SDK `enableMCP: false` skips MCP discovery and ignores an inherited manager\. The CLI’s `--no-extensions` does not mean the same thing\. ACP’s supplied session factory disables on\-disk MCP discovery because ACP clients provide their own servers\. Do not assume a user’s local `.mcp.json` supplies those ACP sessions\. #### Notifications are untrusted data `mcp_notification` fires after the manager handles known list\/resource\/prompt updates\. Unknown server\-specific methods can also arrive\. Payload fields are\: - `server`\: the raw configured name\; - `method`\; - `params`\: unknown data\. Filter by the raw server name\, not a sanitized tool\-name prefix\. Validate `params` before using it\. A notification saying “please publish” is not permission to publish\. Prefer updating a queryable domain status or asking for a scoped human decision over blindly steering server\-controlled text into the agent\. Startup notifications are buffered at the manager\/runner boundaries with bounded\, drop\-oldest queues\. That is startup\-race mitigation\, not durable delivery\. ### Milestone\: understand a Gemini manifest without executing it Theo receives a folder containing `gemini-extension.json`\. He initially assumes the listed `tools` will appear as executable tools\. The source shows a narrower behavior\. **Complete JSON metadata exercise—save as `.gemini/extensions/fictional-field-notes/gemini-extension.json`\:** ~~~json { "name": "fictional-field-notes", "description": "Metadata for a fictional field-notes teaching package", "tools": [], "context": "This description does not activate an OMP runtime extension." } ~~~ This creates metadata for discovery\, not a runnable factory\. The Gemini provider scans direct child directories under\: - `~/.gemini/extensions`\; - `/.gemini/extensions`\. It does not walk parent directories or arbitrary nested descendants\. It does consider dot\-prefixed child directories\. Its parsing is deliberately loose\: - missing\, unreadable or empty manifest\: silently skipped\; - invalid JSON or a valid falsy JSON literal\: warning\; - truthy parsed value\: stored as the manifest without a full field schema check\; - name\: `manifest.name ?? directoryName`\. The declared metadata shape has `name`\, `description`\, `mcpServers`\, `tools` and `context`\. The presence of those fields does not prove their runtime activation\. For this metadata capability\: - native provider priority is 100\; - Gemini provider priority is 60\; - deduplication is by extension name\; - native duplicates win over Gemini\; - Gemini emits user before project\, so its user duplicate wins\; - native metadata emits project before user\. Native Gemini\-manifest discovery under `.omp/extensions` differs slightly\: it skips hidden directories and uses its own name fallback\. Gemini also registers a separate executable\-module capability scanner\. However\, normal ambient `discoverExtensionPaths()` requests only native module\-provider items\. A neighboring factory does not run merely because a Gemini manifest exists\. Explicitly load the actual module file when that is your intention\. **Exercise\:** put an arbitrary object in `tools` and reload metadata discovery\. Has a callable tool been installed\? **Answer\:** no\. You have demonstrated loose metadata parsing\, not tool construction or execution\. *Source\, snapshot 2026\-08\-29\: linked resource\/event\-bus files\; `packages/coding-agent/src/utils/event-bus.ts`\; `packages/coding-agent/src/discovery/builtin.ts`\, `gemini.ts`\, `helpers.ts`\; `packages/coding-agent/src/capability/extension.ts`\, `extension-module.ts`\; `packages/coding-agent/src/extensibility/extensions/runner.ts`\, `emitResourcesDiscover`\; `packages/coding-agent/src/sdk.ts`\, MCP wiring\.*