@plannotator/artifact-server-pi

Pi coding-agent bridge for Artifact Server: receives annotation bundles as follow-up work and closes them through the comment API.

Packages

Package details

extension

Install @plannotator/artifact-server-pi from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@plannotator/artifact-server-pi
Package
@plannotator/artifact-server-pi
Version
0.1.2
Published
Sep 24, 2026
Downloads
292/mo · 292/wk
Author
backnotprop
License
MIT
Types
extension
Size
13.1 KB
Dependencies
1 dependency · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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.