Host support: Pi — package manifest, native extension factory, and skill projection

[ScriptedAlchemy]

Scope and evidence

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Documentation/source research only; no native Pi test was run. This is the Pi coding-agent harness, not Raspberry Pi or another product named Pi.

The upstream badlogic/pi-mono documentation currently redirects to earendil-works/pi and uses @earendil-works/* package names. Do not copy old @mariozechner/* imports from older examples without checking the version being supported.

Authoritative references

• Package structure, install, resources, dependencies, scope
• Extension API, events, tools, rendering, lifecycle
• Official project / harness
• Official extension examples
• Package gallery
• Ponytail package manifest — consumer example only

The live upstream documents are the research references. Implementation must record an immutable upstream revision and supported CLI/package versions before turning these notes into a compatibility guarantee.

Native contract

Pi packages bundle extensions, skills, prompt templates and themes. package.json.pi supplies root-relative resource paths; without the manifest, conventional resource directories are discovered. An extension default-exports a factory receiving ExtensionAPI; it registers commands/tools and subscribes to events. Local .pi/extensions/ and global ~/.pi/agent/extensions/ are distinct scopes and support /reload.

Tools have host schemas and an execute callback with tool-call identity, parameters, abort signal, updates, and context. Events such as before_agent_start, tool_call, tool_result, and session lifecycle have different modification/blocking capabilities. A lifecycle notification must not be treated as an authorization hook merely because its name resembles another host's event.

The upstream guide explicitly warns that factories may run without a session: defer background resources until needed and close them idempotently on session_shutdown. Noninteractive modes do not offer the same UI methods; never require an interactive confirmation dialog from a print/JSON invocation without an honest unsupported outcome.

Illustrative package layout

composite-root/
  package.json
  pi-extension/index.js
  skills/review/SKILL.md
  prompts/review.md
  runtime/                  # compiled implementation only when required

{
  "name": "@example/plugin",
  "type": "module",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./pi-extension/index.js"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

This is proposed generated metadata, not a new author-facing configuration requirement. Explicit paths avoid accidentally loading another host's extensions/ directory. Do not include theme/prompt fields when those resources were not authored.

Installation and developer workflow

Host-documented commands include:

pi install npm:@example/plugin@1.0.0
pi install git:github.com/example/plugin@v1.0.0
pi install ./composite-root
pi install -l ./composite-root
pi -e ./composite-root/pi-extension/index.js
pi list
pi remove npm:@example/plugin

Global package settings live in ~/.pi/agent/settings.json; -l uses .pi/settings.json. Local-path installations are references rather than copies, and relative paths resolve from the settings location. Git/npm installs have separate host-managed stores. Pinning, updating, local references, and removal therefore require separate tests. Do not leave a setting pointing at a deleted temporary build directory.

Build/dependency implications

Pi's official package guide says its host packages and typebox are supplied by the harness and must not be bundled into the extension; ordinary runtime dependencies belong in dependencies. This differs from an executable intended to run under bare Node with only builtins external.

Define explicit host-provided import evidence for this adapter, scoped to the Pi entry. Do not loosen self-containment for all Agent Bundle executables or label an arbitrary package external as a Node builtin. Avoid copying an entire second Pi harness into the plugin. Preserve a distinct package-only/native-extension record in the canonical manifest/evidence.

Native tool schemas must derive from the canonical operation contract. Do not force authors to maintain parallel Zod/TypeBox definitions; prove the supported conversion subset or use a runtime-safe adapter with clear unsupported diagnostics.

No native MCP manifest was established by these package/extension references. Do not invent pi.mcp.json or require an additional MCP bridge merely to support Pi-native tools. MCP integration can only be advertised after pinning a separate supported host contract.

Acceptance

• Pin upstream repository SHA and actual host-provided import package names/ranges; reject unsupported major API combinations.
• Build one static skills package and one native tool/event package using public Agent Bundle authoring APIs.
• Validate pi resource paths from the installed package root, with source checkout removed.
• Factory registration must not start unnecessary workers, timers or sockets; shutdown/reload must dispose each session-owned resource once.
• Test tool inputs, results/errors, progress, cancellation, before-tool block and after-tool observation.
• Test interactive, print/JSON and RPC behavior without pretending UI calls work identically.
• Test global/project package precedence, explicitly empty resource filters, local reference removal, and no duplicate activation.
• Install an actual npm tarball and a relocated local composite, then verify canonical operation/result parity.
• Composite conformance includes Pi convention discovery and does not expose another host's commands/helpers accidentally.
• Host-provided imports have explicit evidence and do not weaken build: AB7014 from consumer-runtime evidence (option A); gate the generated-JS walk on the compile evidence record (#619 steps b–d) #634/build: persist compile evidence beside emitted files (#619 step 4) #638 policy for standalone entries.

Integration / non-goals

Use existing adapters, manifest, compiler-evidence, package-build and #651/#652 tests. Current custom-host AB4106 isolation remains until the new composite contract is tested. No alternative agent loop, model provider management, TUI framework, domain persistence, or mandatory React/MCP runtime for a static package.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

Pi — observed npm probed 2026-09-06; no installable release exists. Not supported as published: this client loads nothing from the emitted package.

Surface	State	Evidence
manifest	unavailable	2026-09-06: no installable Pi release exists on npm, so no manifest handling can be established.
skills	unavailable	2026-09-06: unproven. Pi's repository documents project and global .agents/skills/ roots, but no installable release exists to exercise the emitted skill tree against.
mcp	unavailable	2026-09-06: Pi's own documentation states it has no MCP support at all, so the emitted mcp.json has no reader there.
placeholders	unavailable	2026-09-06: with no document of this artifact read, no placeholder of Agent Plugins 1.0.0 §9.1 is expanded.
hooks	unavailable	2026-09-06: Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for Pi to read.

Paths it reads: none.
No install command is recorded, because nothing this bundle emits installs there.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.

[ScriptedAlchemy]

Correction to the preceding closeout — Pi is a skills-tier reader

The earlier closeout saying that no installable Pi release exists and that it reads nothing is superseded. It reflected the stale duplicate record that #727 removed.

Current main b5cf7575e0bcfa6da23e12d2c5628146bdbe5cb1 retains the live-probed record from #723: @mariozechner/pi-coding-agent@0.73.1, skills-tier compatibility, with the registration action:

pi --skill <plugin-directory>/skills

See #723's recorded probe, #727's duplicate-key correction, and the current capability table. #727 also adds a test rejecting repeated authored client keys, so JSON last-key-wins cannot silently replace this record again.

This proves the scoped skill registration described by those records, not delivery of a generated Pi native extension or an authenticated model turn. Preserve the package identity/version actually probed; do not substitute another repository/package family from the original exploratory research without its own validation. MCP/hook claims remain restricted to the recorded installed-release contract.

No reopening is required for the fixed duplicate/stale-record bug. This correction updates the issue's outcome and leaves the historical probe discussion visible.