@plannotator/artifact-server-pi 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backnotprop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @plannotator/artifact-server-pi
+
+The Artifact Server bridge for the [Pi coding agent](https://pi.dev). 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
+
+```bash
+pi install npm:@plannotator/artifact-server-pi
+```
+
+or in `settings.json`:
+
+```json
+{
+  "packages": ["npm:@plannotator/artifact-server-pi"]
+}
+```
+
+For development inside this repository:
+
+```bash
+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.

package/index.ts

@@ -0,0 +1,273 @@
+/**
+ * Artifact Server bridge — the thin Pi-facing entry.
+ *
+ * Registers this Pi session with an Artifact Server installation, receives
+ * annotation bundles as follow-up work through the claim loop in
+ * `@plannotator/agent-bridge`, and registers the `artifact_comments` tool the
+ * agent uses to reply to and resolve each thread. All logic lives in the
+ * shared core; this file only wires it to the live extension API.
+ */
+
+import {homedir, hostname} from "node:os";
+
+import {Type} from "typebox";
+
+import {
+  ActivityBeacon,
+  type BridgeHandle,
+  type BridgeNoticeKind,
+  chooseDisplayName,
+  type CommentOperations,
+  createCommentOperations,
+  type EnvironmentConfiguration,
+  type FollowUpDelivery,
+  type HostPort,
+  resolveBridgeCredentials,
+  startBridge,
+  ThreadLocationCache,
+} from "@plannotator/agent-bridge";
+
+/**
+ * A compaction flag older than this is treated as expired: a cancelled
+ * compaction never emits `session_compact`, so the hold must not stick.
+ */
+const compactionFlagLifetimeMilliseconds = 5 * 60 * 1_000;
+
+// ---------------------------------------------------------------------------
+// The narrow, structurally-typed slice of Pi's extension API this entry uses.
+// Typing it locally keeps the package free of a hard dependency on Pi's own
+// type package while the real API remains structurally compatible.
+// ---------------------------------------------------------------------------
+
+interface PiNotifier {
+  notify(message: string, kind?: BridgeNoticeKind): void;
+}
+
+interface PiSessionManagerLike {
+  getSessionId(): string;
+}
+
+interface PiExtensionContextLike {
+  cwd: string;
+  sessionManager: PiSessionManagerLike;
+  ui: PiNotifier;
+}
+
+interface PiSessionStartEventLike {
+  reason: string;
+}
+
+interface PiToolTextContent {
+  text: string;
+  type: "text";
+}
+
+interface ArtifactCommentsDetails {
+  operation: string;
+  threadIds: readonly string[];
+}
+
+interface PiToolResultLike {
+  content: PiToolTextContent[];
+  details: ArtifactCommentsDetails;
+}
+
+interface ArtifactCommentsParams {
+  body?: string;
+  operation: "get_bundle" | "reply" | "resolve";
+  threadId?: string;
+  threadIds?: string[];
+}
+
+interface PiToolDefinitionLike {
+  description: string;
+  execute(
+    toolCallId: string,
+    params: ArtifactCommentsParams,
+    signal: AbortSignal | undefined,
+  ): Promise<PiToolResultLike>;
+  label: string;
+  name: string;
+  parameters: ReturnType<typeof artifactCommentsParameters>;
+}
+
+interface PiExtensionApi {
+  on(
+    event: "session_start",
+    handler: (
+      event: PiSessionStartEventLike,
+      ctx: PiExtensionContextLike,
+    ) => Promise<void>,
+  ): void;
+  on(event: "session_before_compact", handler: () => void): void;
+  on(event: "session_compact", handler: () => void): void;
+  on(
+    event: "session_shutdown",
+    handler: (event?: PiSessionShutdownEventLike) => Promise<void>,
+  ): void;
+  registerTool(tool: PiToolDefinitionLike): void;
+  sendUserMessage(text: string, delivery: FollowUpDelivery): void;
+}
+
+function artifactCommentsParameters() {
+  return Type.Object({
+    body: Type.Optional(Type.String({
+      description: "Reply text (reply operation only).",
+    })),
+    operation: Type.Union([
+      Type.Literal("get_bundle"),
+      Type.Literal("reply"),
+      Type.Literal("resolve"),
+    ], {
+      description:
+        "get_bundle reads threads with their replies; reply posts one reply; " +
+        "resolve closes one thread.",
+    }),
+    threadId: Type.Optional(Type.String({
+      description: "Target thread id (reply and resolve operations).",
+    })),
+    threadIds: Type.Optional(Type.Array(Type.String(), {
+      description: "Thread ids to read (get_bundle operation).",
+    })),
+  });
+}
+
+function environmentConfiguration(): EnvironmentConfiguration {
+  return {
+    agentDisplayName: process.env["ARTIFACT_SERVER_AGENT_NAME"],
+    agentToken: process.env["ARTIFACT_SERVER_AGENT_TOKEN"],
+    origin: process.env["ARTIFACT_SERVER_ORIGIN"],
+  };
+}
+
+function textResult(
+  operation: string,
+  threadIds: readonly string[],
+  text: string,
+): PiToolResultLike {
+  return {
+    content: [{text, type: "text"}],
+    details: {operation, threadIds},
+  };
+}
+
+/** The shutdown reasons Pi emits; only a real quit is a departure. */
+interface PiSessionShutdownEventLike {
+  readonly reason?: string;
+}
+
+/** Artifact Server bridge extension factory. */
+export default function artifactServerBridge(pi: PiExtensionApi): void {
+  let bridge: BridgeHandle | null = null;
+  let comments: CommentOperations | null = null;
+  let compactionStartedAt: number | null = null;
+  const locations = new ThreadLocationCache();
+
+  const stopBridge = async (disconnect: boolean): Promise<void> => {
+    const active = bridge;
+    bridge = null;
+    if (active !== null) await active.stop({disconnect});
+  };
+
+  // Compaction is tracked from events because the extension context exposes
+  // no probe; the timestamp bounds the flag so a cancelled compaction (which
+  // never emits session_compact) cannot hold deliveries forever.
+  pi.on("session_before_compact", () => {
+    compactionStartedAt = Date.now();
+  });
+  pi.on("session_compact", () => {
+    compactionStartedAt = null;
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    await stopBridge(false);
+    const environment = environmentConfiguration();
+    const credentials = await resolveBridgeCredentials(environment, homedir());
+    // One beacon per session: replies and resolves through the tool count
+    // against the bundles this session's bridge delivered.
+    const beacon = new ActivityBeacon();
+    comments = credentials === null
+      ? null
+      : createCommentOperations(credentials, fetch, locations, beacon);
+
+    const port: HostPort = {
+      isCompacting: () =>
+        compactionStartedAt !== null &&
+        Date.now() - compactionStartedAt < compactionFlagLifetimeMilliseconds,
+      notify: (message, kind) => {
+        ctx.ui.notify(message, kind);
+      },
+      sendUserMessage: (text, delivery) => {
+        // Always named follow-up delivery: safe while idle (delivery mode is
+        // ignored and a run starts) and queued to the work boundary while
+        // streaming. Never "steer", and never omitted.
+        pi.sendUserMessage(text, delivery);
+      },
+    };
+
+    bridge = startBridge({
+      agentSessionId: ctx.sessionManager.getSessionId(),
+      beacon,
+      credentials,
+      displayName: chooseDisplayName(environment, ctx.cwd),
+      fetchImplementation: fetch,
+      host: port,
+      hostname: hostname(),
+      kind: "pi",
+      locations,
+      workingDirectory: ctx.cwd,
+    });
+  });
+
+  pi.on("session_shutdown", async (event) => {
+    await stopBridge(event?.reason === "quit");
+  });
+
+  pi.registerTool({
+    description:
+      "Read, reply to, and resolve Artifact Server comment threads that were " +
+      "sent to this agent. Use get_bundle to read threads, reply to record " +
+      "what you did on a thread, and resolve to close it when done.",
+    async execute(_toolCallId, params) {
+      const operations = comments;
+      if (operations === null) {
+        throw new Error(
+          "Artifact Server is not configured; the bridge is dormant.",
+        );
+      }
+      if (params.operation === "get_bundle") {
+        const threadIds = params.threadIds ?? [];
+        if (threadIds.length === 0) {
+          throw new Error("get_bundle requires threadIds.");
+        }
+        const details = [];
+        for (const threadId of threadIds) {
+          // eslint-disable-next-line no-await-in-loop
+          details.push(await operations.getThread(threadId));
+        }
+        return textResult(
+          "get_bundle",
+          threadIds,
+          JSON.stringify(details, null, 2),
+        );
+      }
+      const threadId = params.threadId ?? "";
+      if (threadId === "") {
+        throw new Error(`${params.operation} requires threadId.`);
+      }
+      if (params.operation === "reply") {
+        const body = params.body ?? "";
+        if (body.trim() === "") {
+          throw new Error("reply requires a non-empty body.");
+        }
+        await operations.reply(threadId, body);
+        return textResult("reply", [threadId], `Replied to ${threadId}.`);
+      }
+      await operations.resolve(threadId);
+      return textResult("resolve", [threadId], `Resolved ${threadId}.`);
+    },
+    label: "Artifact comments",
+    name: "artifact_comments",
+    parameters: artifactCommentsParameters(),
+  });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@plannotator/artifact-server-pi",
+  "version": "0.1.1",
+  "description": "Pi coding-agent bridge for Artifact Server: receives annotation bundles as follow-up work and closes them through the comment API.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "artifact-server"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@plannotator/agent-bridge": "^0.1.1"
+  },
+  "peerDependencies": {
+    "typebox": "^1.3.7"
+  },
+  "devDependencies": {
+    "typebox": "1.3.7",
+    "typescript": "7.0.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "integrations/pi",
+    "type": "git",
+    "url": "git+https://github.com/plannotator/artifact-server.git"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}