@liy/mote-pi-runtime

Everything a Mote agent loads inside its own process: the Pi RPC bridge, the precompiled Pi extensions, the universal Agent Skills, and the agent-facing orchestrator CLI.

| Binary | Role | | --- | --- | | mote-pi-rpc | Per-run Pi process the orchestrator spawns for each launch | | orchestrator | CLI agents invoke to call back into the orchestrator |

The CLI implementation and authenticated MCP stdio bridge live in this package. orchestrator mcp <server-ref> forwards built-in mote and private connection UUIDs through the same launch-authenticated socket protocol. The CLI never selects upstream URLs or credentials. Private connection discovery runs asynchronously during extension registration; a failed directory lookup leaves built-in Mote available and reports a safe warning.

Pi 1.1.0's native MCP and tool_search extensions are registered by the SDK runtime. Connections are user scoped; no profile or project mcp.json is read or written. Private tools are deferred under stable UUID namespaces; registered descriptions carry quoted connection names into Pi's native mcp_servers section and tool search. Name changes and credential revisions refresh registrations. Private servers connect in the background without delaying ordinary first prompts; discovery waits when their tools are needed. Mote's proposal and inline-widget tools are direct so their structured results reach the timeline. Native logs live under the writable session's debug/ directory.

Internal and compatible private servers use stateless MCP 2025-11-25 with initialization and request-scoped JSON/SSE. The gateway rejects private servers requiring sessions or another revision. Adopt newer revisions when Pi supports them; there is no protocol translator or alternate adapter implementation.

Code Mode is enabled on every fresh or resumed RPC launch. The runtime registers Pi's native extension and adds codemode to the merged profile/project tool selection, preserving explicit selections (including an empty selection). Mode on keeps ordinary selected tools available directly; there is no product toggle. Nested calls use Pi's normal validation and permission hooks, and native events retain parentToolCallId. Tool selection is visibility, not authorization; the JavaScript isolate does not restrict tools' external effects. Existing gateway and OS permission boundaries remain responsible for those effects.

Session event transport

The SDK subscription emits JSONL { type: "pi_event", event, contextSnapshot? } frames. event is the original Pi event. Completed messages and compaction outcomes also carry a context-usage estimate with model identity and sampling time, captured after Pi updates its session. RPC responses remain unwrapped control frames. The orchestrator must support this envelope before this runtime is installed; context usage is not added to or rewritten inside native payloads. Pi's agent_settled.aborted is retained. The orchestrator terminates cancelled runs without handoff reminders or returning them to its idle pool; the channel does not route their last message to another agent.

Anthropic's SDK-selected beta capabilities travel in the HMAC-covered anthropicBetas field, validated against a shared closed vocabulary. The gateway reconstructs the header and injects the API key; arbitrary SDK headers and OAuth betas cannot cross this boundary. Install the updated gateway, Edge, and resident services before this runtime. Existing runtime requests without the field remain valid; application rollback does not rewrite Pi session files.

Why this package exists on its own

ADR-084 tiers the sandbox by what loads an artifact. Nothing resident loads this package: Pi runs as a spawned, detached child. A new version therefore takes effect at the next agent launch and needs no service restart. Publishing an extension fix or a new Pi release costs no downtime; a shipped skill is copied into each profile at its next template write (orchestrator boot or a profile save), so that users can customize an agent's skills.

Dependencies

Pi, pi-web-access and the component catalog CLI are ordinary dependencies pinned to exact versions. They are not peers: this package is the host that starts Pi, so nothing above it supplies an instance.

npm-shrinkwrap.json freezes the entire published production dependency tree, including integrity hashes and optional platform packages. The files manifest explicitly includes it because pnpm otherwise omits it from the tarball. pnpm dependencies:lock regenerates it after dependency/catalog changes; pnpm dependencies:check validates it offline, and prepack runs that check. Version-only release PRs update its root version without resolving dependencies. The workspace's pnpm lock and this published npm lock serve different consumers; validate a clean tarball install when changing the production tree.

Precompiled extensions

scripts/compile-extensions.mjs bundles the provider, prompt composer and web-access extensions at publish time into dist/extensions, so no compiler reaches a Sprite and Pi's loader never transpiles them. Pi's SDK and installed JavaScript dependencies stay external, preserving SDK identity and native assets.

The web-access extension locates assets relative to its installed package. A banner resolves that directory on load rather than baking it in, because the install path is not known at publish time. It resolves the real path first: agent profiles reach this tree through a symlinked extensions directory and Pi's loader keeps that symlinked path, so walking up from import.meta.url alone would escape the package.

Installed layout

/opt/mote/pi-runtime/<version>/            complete npm install root
/opt/mote/pi-runtime/<version>/extensions  -> the compiled extension tree
/opt/mote/pi-runtime/<version>/skills      -> the shipped Agent Skills
/opt/mote/pi-runtime/current               -> <version>

Agent profiles link to the stable current/extensions name and copy their skills from current/skills, so a version swap needs no profile rewrite. The orchestrator resolves current when it spawns, not at boot, which is what lets an update land without restarting anything.

Compatibility with the services

Nothing pairs the two packages by declaration. Semantic versioning carries that judgement, as it does for every published package: a release that changes either direction of the interface says so in its version.

One coupling is checked directly rather than by convention, because its failure is silent: the services refuse to publish a staged version of this package whose extensions and skills names do not resolve, since every agent profile links to the first and copies from the second, and a relocated directory would quietly empty each profile.

Release

pnpm release:pi-runtime:check packs a dry run. Publication is manual dispatch only, through npm trusted publishing.