pi-mosaico

The official Pi extension for Mosaico. It gives Pi agents durable Mosaico identity, awareness context, lifecycle observation, and project-boundary guardrails.

Install Mosaico first, then add the package to Pi:

pi install npm:pi-mosaico

mosaico setup installs the same extension bundle under Pi's global extension directory. Both Pi's interactive PTY mode and Mosaico's native Pi RPC transport use this one extension; RPC owns its managed turn lifecycle while the extension owns lifecycle observation for PTY and manually launched sessions.

The integration fails open when Mosaico is unavailable and never changes Pi's project trust policy. It connects directly to Mosaico's existing local daemon: the extension registers its Pi-native session, leases exact directed inbox work, injects it as Pi custom context, and acknowledges only after Pi accepts it. Ambient channel chat is supplied as normal turn awareness rather than waking an agent by itself.

In interactive Pi, the extension paints its own session-status chip into the footer from the mosaico_session snapshot: handle, workspace, public title, and unhosted/headless when those change delivery. The chip is hidden when the daemon is down.

Native agent tools

The extension registers native Pi tools for ordinary agent coordination:

Tool	Purpose
mosaico_session	Read the agent's fabric identity and complete awareness
mosaico_wait	Wait once for a matching message without polling
mosaico_channel_list	List the agent-visible channel forest
mosaico_channel_read	Read recent messages or one complete message
mosaico_channel_search	Search observed messages
mosaico_send	Send a message, attachments, tags, and optionally await a reply
mosaico_reply	Reply substantively to one message
mosaico_react	Acknowledge one message non-disruptively
mosaico_channel_create	Create and join a leaf task channel
mosaico_channel_join	Join an existing channel
mosaico_channel_leave	Leave a passively joined channel
mosaico_dispatch	Start an agent session when no existing session owns the work

Operator and administration operations are intentionally absent.

Tools do not scrape or spawn Mosaico's human CLI. Each call uses the daemon's versioned UDS JSON protocol with Pi's native session ID and cwd, and receives a structured Pi tool result. Expected tool failures are returned to the model; lifecycle observation remains fail-open.