@plannotator/artifact-server-pi

The Artifact Server bridge for the Pi coding agent. It connects a live Pi session to an Artifact Server installation so that annotation bundles sent from the review UI arrive in Pi as follow-up work, and Pi replies to and resolves each comment thread through the artifact_comments tool.

What it does

• Registers this Pi session as an agent (POST /api/v1/agents), self-named after the working directory. Restarts, /new, and /resume reclaim the same agent identity, so pending bundles survive.
• Long-polls the dispatch mailbox (POST /api/v1/agents/:id/claims?wait=25). Each claimed bundle is rendered as one message and injected with pi.sendUserMessage(text, {deliverAs: "followUp"}) — always follow-up delivery, never steering: Pi finishes its current work first, then receives exactly one bundle per work boundary.
• Holds delivery while the session is compacting, and reports delivered only after Pi accepted the message.
• Registers the artifact_comments tool with get_bundle, reply, and resolve operations wrapping the comment HTTP routes with the same credential, so the agent can close the loop without any human action.
• Fails open. Without configuration it stays dormant after one notice. With the server unreachable it backs off between 1 s and 30 s and Pi continues normally. No bridge failure is ever thrown into Pi.

Install

pi install npm:@plannotator/artifact-server-pi

or in settings.json:

{
  "packages": ["npm:@plannotator/artifact-server-pi"]
}

For development inside this repository:

pi -e integrations/pi/index.ts

Configuration

Resolved once per session start, in order:

| Source | Setting | Meaning | | --- | --- | --- | | Environment | ARTIFACT_SERVER_ORIGIN | Server origin, e.g. https://artifacts.example.com. Used together with the token below. | | Environment | ARTIFACT_SERVER_AGENT_TOKEN | Bearer credential. Needs agent:connect plus comment read/write for the tool; the local API token carries everything. | | Environment | ARTIFACT_SERVER_AGENT_NAME | Optional display-name override (default: the working directory's basename). | | Local discovery | ~/.artifact-server/local-service.json | The managed local server's discovery record (loopback origin). | | Local discovery | ~/.artifact-server/local-api-token | The local installation's private API credential. |

If neither source resolves, the extension notifies once and stays dormant for the session. It never blocks a Pi event handler on the network.

Compatibility

• Pi extension API: tested against @earendil-works/pi-coding-agent 0.84.x. The bridge fails soft on missing API surface (dormant plus one notice, never a crash).
• The package version tracks Artifact Server releases; it is a client of the server's dispatch API (project/spec/agent-dispatch-spec.md).
• Ships TypeScript source; Pi loads extensions through jiti with no build step.