@plannotator/artifact-server-opencode 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,119 @@
+# @plannotator/artifact-server-opencode
+
+The Artifact Server bridge for [OpenCode](https://opencode.ai). It connects
+an OpenCode instance to an Artifact Server installation so that annotation
+bundles sent from the review UI arrive in the active OpenCode session as
+follow-up prompts, and the agent replies to and resolves each comment thread
+through the `artifact_comments` tool.
+
+## What it does
+
+- Registers this OpenCode instance as an agent (`POST /api/v1/agents`,
+  kind `opencode`, capabilities `{beacon: true, evidence: "native"}`),
+  self-named after the project directory. Restarts 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
+  `client.session.promptAsync` into the most recently active top-level
+  session — follow-up delivery, never steering or interrupt: OpenCode
+  queues the prompt server-side and the running loop picks it up at its
+  next work boundary. Subagent (task) sessions are never targeted.
+- Holds delivery while no top-level session exists yet or while the target
+  session is compacting (`experimental.session.compacting` hook, cleared by
+  the `session.compacted` event, bounded at five minutes).
+- Registers the `artifact_comments` tool (`get_bundle`, `reply`, `resolve`)
+  through OpenCode's plugin tool hook, wrapping the comment HTTP routes with
+  the same credential, so the agent closes the loop without human action.
+- Sends the best-effort activity beacon at the natural work boundaries
+  (bundle accepted → thinking, first reply → replying, last thread
+  resolved → idle).
+- Fails open. A plugin context without the expected surface, or no resolved
+  configuration, leaves the bridge dormant; an unreachable server only
+  produces bounded backoff (1–30 s). No bridge failure is ever thrown into
+  OpenCode. Notices go through `client.tui.showToast` and are dropped
+  silently on headless hosts.
+
+## Install
+
+Add the package to your OpenCode config:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@plannotator/artifact-server-opencode"]
+}
+```
+
+For development inside this repository, copy or symlink `index.ts` into a
+plugin directory (`.opencode/plugins/` or `~/.config/opencode/plugins/`)
+with `@plannotator/agent-bridge` and `zod` resolvable (see OpenCode's
+plugin-dependency docs).
+
+## Configuration
+
+Resolved once when the plugin loads, 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 project 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 bridge notifies once (when a TUI is
+attached) and stays dormant.
+
+## Pinned OpenCode version
+
+Coded and verified against the OpenCode source at version **1.18.18**
+(`@opencode-ai/plugin` 1.18.18, repository commit `ad905f8e6c`, dev branch,
+2026-08-18), using the **V1 plugin API** (`(input) => Promise<Hooks>`). A
+beta V2 plugin API (`@opencode-ai/plugin/v2/*`) exists at that commit; this
+adapter deliberately pins V1, the API OpenCode loads for plain exported
+plugin functions.
+
+## Verified vs. assumed
+
+Verified by reading the pinned source:
+
+- Plugins load in-process and receive `client`, an SDK client bound to the
+  same OpenCode server instance that backs the TUI.
+- `client.session.promptAsync` (`POST /session/:id/prompt_async`) answers
+  204 once the prompt is accepted; while the session is busy the appended
+  user message is picked up at the running loop's boundary — real
+  follow-up semantics. Interrupt would be `session.abort`; this bridge
+  never uses it, and steering is not claimed. The bridge awaits that answer
+  before it reports `delivered`; a refusal reports the dispatch `failed` and
+  leaves the plugin available for later bundles.
+- Plugins register model-callable tools through the `tool` hook (zod
+  argument shapes converted to JSON Schema by OpenCode's tool registry),
+  so `artifact_comments` is a native tool — no MCP fallback needed.
+- `client.tui.showToast` exists as the notification surface.
+- Compaction is observable via the `experimental.session.compacting` hook
+  and the `session.compacted` event.
+
+Verified by the fake plugin context against a real spawned Artifact Server:
+
+- Deleting the target session while `promptAsync` is pending makes that
+  dispatch fail and releases its comments. Selecting another session lets the
+  same bridge deliver the next dispatch without restarting OpenCode.
+
+Assumed (recorded honestly, not proven against a live OpenCode):
+
+- Cross-instance zod interop: this package ships zod `4.4.3` argument
+  schemas; OpenCode composes them with its own zod (`4.1.8` at the pinned
+  commit) through the `_zod` protocol. This is the standard path for every
+  npm plugin, but it is not executed by this repository's tests.
+- The `experimental.*` hook names are marked experimental by OpenCode and
+  may change in later versions; the bridge degrades to "no compaction
+  hold" if they stop firing.
+- No live OpenCode smoke test exists here: the adapter is proven through a
+  fake plugin context driving the real bridge core against a real spawned
+  Artifact Server (`tests/client/opencode-bridge.test.ts`).
+
+## Compatibility
+
+- 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; OpenCode loads plugins with Bun, no build step.

package/index.ts

@@ -0,0 +1,395 @@
+/**
+ * Artifact Server bridge — the thin OpenCode-facing entry.
+ *
+ * Registers the OpenCode instance for this project directory with an
+ * Artifact Server installation, receives annotation bundles as follow-up
+ * prompts 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 OpenCode's plugin API (V1 plugin surface, pinned in the
+ * README): `client.session.promptAsync` is the follow-up injection seam,
+ * `client.tui.showToast` is the notice surface, and hooks track the target
+ * session and its compaction windows.
+ */
+
+import {homedir, hostname} from "node:os";
+
+import {z} from "zod";
+
+import {
+  ActivityBeacon,
+  type BridgeHandle,
+  type BridgeNoticeKind,
+  chooseDisplayName,
+  type CommentOperations,
+  createCommentOperations,
+  type EnvironmentConfiguration,
+  type HostPort,
+  resolveBridgeCredentials,
+  startBridge,
+  ThreadLocationCache,
+} from "@plannotator/agent-bridge";
+
+/**
+ * A compaction flag older than this is treated as expired: an abandoned
+ * compaction whose `session.compacted` event never arrives must not hold
+ * deliveries forever.
+ */
+const compactionFlagLifetimeMilliseconds = 5 * 60 * 1_000;
+
+// ---------------------------------------------------------------------------
+// The narrow, structurally-typed slice of OpenCode's plugin API this entry
+// uses. Typing it locally keeps the package free of a hard dependency on
+// `@opencode-ai/plugin` and `@opencode-ai/sdk` while the real API remains
+// structurally compatible (verified against the pinned version in README).
+// ---------------------------------------------------------------------------
+
+/** One SDK call answer: the OpenCode client reports failures as a value. */
+interface OpencodeCallAnswer {
+  readonly error?: {readonly message?: string};
+}
+
+interface OpencodePromptOptions {
+  readonly body: {
+    readonly parts: readonly {readonly text: string; readonly type: "text"}[];
+  };
+  readonly path: {readonly id: string};
+}
+
+interface OpencodeSessionApi {
+  promptAsync(options: OpencodePromptOptions): Promise<OpencodeCallAnswer>;
+}
+
+interface OpencodeToastOptions {
+  readonly body: {
+    readonly message: string;
+    readonly variant: BridgeNoticeKind;
+  };
+}
+
+interface OpencodeTuiApi {
+  showToast(options: OpencodeToastOptions): Promise<boolean>;
+}
+
+/** The in-process SDK client OpenCode hands every plugin. */
+export interface OpencodeClient {
+  session: OpencodeSessionApi;
+  /** Absent or inert on headless hosts; every use is best-effort. */
+  tui?: OpencodeTuiApi;
+}
+
+/** The V1 plugin context slice this bridge reads. */
+export interface OpencodePluginInput {
+  client: OpencodeClient;
+  directory: string;
+}
+
+/**
+ * A degraded plugin context from an unexpected OpenCode build. The boundary
+ * guard turns it into a dormant bridge instead of a crash inside the host.
+ */
+export interface OpencodePartialPluginContext {
+  readonly client?: undefined;
+  readonly directory?: string;
+}
+
+/** One bus event as the `event` hook receives it; parsed with schemas. */
+export interface OpencodeEvent {
+  readonly properties?: object;
+  readonly type: string;
+}
+
+interface ArtifactCommentsArguments {
+  readonly body?: string;
+  readonly operation: "get_bundle" | "reply" | "resolve";
+  readonly threadId?: string;
+  readonly threadIds?: readonly string[];
+}
+
+/** The `Hooks` slice this plugin returns to OpenCode. */
+export interface OpencodeBridgeHooks {
+  "chat.message"(input: {sessionID: string}): Promise<void>;
+  dispose(): Promise<void>;
+  event(input: {event: OpencodeEvent}): Promise<void>;
+  "experimental.session.compacting"(input: {sessionID: string}): Promise<void>;
+  tool: {
+    artifact_comments: {
+      args: ReturnType<typeof artifactCommentsToolArguments>;
+      description: string;
+      execute(args: ArtifactCommentsArguments): Promise<string>;
+    };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Runtime guards
+// ---------------------------------------------------------------------------
+
+/**
+ * The plugin context surface the bridge needs, checked at the boundary so a
+ * host that lacks it leaves the bridge dormant instead of crashing OpenCode.
+ * Only presence is checked; calls keep going through the original `input`
+ * object so SDK method bindings stay intact.
+ */
+const pluginSurfaceSchema = z.object({
+  client: z.object({
+    session: z.object({promptAsync: z.function()}).loose(),
+  }).loose(),
+  directory: z.string().min(1),
+}).loose();
+
+function isCompletePluginInput(
+  input: OpencodePartialPluginContext | OpencodePluginInput,
+): input is OpencodePluginInput {
+  return pluginSurfaceSchema.safeParse(input).success;
+}
+
+const sessionLifecycleEventSchema = z.object({
+  properties: z.object({
+    info: z.object({
+      id: z.string(),
+      parentID: z.string().optional(),
+    }).loose(),
+  }).loose(),
+  type: z.enum(["session.created", "session.deleted", "session.updated"]),
+}).loose();
+
+const sessionCompactedEventSchema = z.object({
+  properties: z.object({sessionID: z.string()}).loose(),
+  type: z.literal("session.compacted"),
+}).loose();
+
+function artifactCommentsToolArguments() {
+  return {
+    body: z.string().optional()
+      .describe("Reply text (reply operation only)."),
+    operation: z.enum(["get_bundle", "reply", "resolve"]).describe(
+      "get_bundle reads threads with their replies; reply posts one reply; " +
+        "resolve closes one thread.",
+    ),
+    threadId: z.string().optional()
+      .describe("Target thread id (reply and resolve operations)."),
+    threadIds: z.array(z.string()).optional()
+      .describe("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"],
+  };
+}
+
+const noopHooks: OpencodeBridgeHooks["event"] = () => Promise.resolve();
+
+/** The hooks returned when the host context lacks the expected surface. */
+function dormantHooks(): OpencodeBridgeHooks {
+  return {
+    "chat.message": () => Promise.resolve(),
+    dispose: () => Promise.resolve(),
+    event: noopHooks,
+    "experimental.session.compacting": () => Promise.resolve(),
+    tool: {
+      artifact_comments: {
+        args: artifactCommentsToolArguments(),
+        description: artifactCommentsDescription,
+        execute: () =>
+          Promise.reject(
+            new Error(
+              "Artifact Server is not configured; the bridge is dormant.",
+            ),
+          ),
+      },
+    },
+  };
+}
+
+const artifactCommentsDescription =
+  "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.";
+
+// ---------------------------------------------------------------------------
+// The plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Artifact Server bridge plugin for OpenCode. Loaded once per OpenCode
+ * instance; never throws into the host — a context without the expected
+ * surface or without credentials produces a dormant bridge.
+ */
+export async function ArtifactServerBridge(
+  input: OpencodePartialPluginContext | OpencodePluginInput,
+): Promise<OpencodeBridgeHooks> {
+  if (!isCompletePluginInput(input)) return dormantHooks();
+
+  // The most recently active top-level session: bundles inject here.
+  // Subagent (child) sessions never become the target — a bundle delivered
+  // into a task session would vanish with it.
+  let targetSessionId: string | null = null;
+  const childSessionIds = new Set<string>();
+  let compaction: {sessionId: string; startedAt: number} | null = null;
+
+  const environment = environmentConfiguration();
+  const credentials = await resolveBridgeCredentials(environment, homedir());
+  const locations = new ThreadLocationCache();
+  // One beacon per instance: replies and resolves through the tool count
+  // against the bundles this bridge delivered.
+  const beacon = new ActivityBeacon();
+  const comments: CommentOperations | null = credentials === null
+    ? null
+    : createCommentOperations(credentials, fetch, locations, beacon);
+
+  const notify = (message: string, kind: BridgeNoticeKind): void => {
+    try {
+      // Best-effort: a headless host has no TUI and simply drops notices.
+      void input.client.tui?.showToast({body: {message, variant: kind}})
+        .catch(() => undefined);
+    } catch {
+      // A notice may be lost; the bridge must never raise into the host.
+    }
+  };
+
+  // `POST /session/:id/prompt_async` answers once OpenCode accepts the prompt.
+  // The bridge awaits this promise before it reports the dispatch delivered.
+  const injectFollowUp = async (
+    sessionId: string,
+    text: string,
+  ): Promise<void> => {
+    try {
+      const answer = await input.client.session.promptAsync({
+        body: {parts: [{text, type: "text"}]},
+        path: {id: sessionId},
+      });
+      if (answer.error !== undefined) {
+        throw new Error(
+          answer.error.message ?? "OpenCode refused the follow-up prompt.",
+        );
+      }
+    } catch (error) {
+      notify(
+        "Artifact Server: delivering the annotation bundle to the " +
+          "OpenCode session failed.",
+        "warning",
+      );
+      throw error;
+    }
+  };
+
+  const port: HostPort = {
+    // OpenCode queues prompts server-side (`prompt_async` appends a user
+    // message that the running loop picks up at its next boundary), so the
+    // only pre-delivery hold this port needs is: no target session yet, or
+    // the target is inside a bounded compaction window.
+    isCompacting: () =>
+      targetSessionId === null ||
+      (compaction !== null &&
+        compaction.sessionId === targetSessionId &&
+        Date.now() - compaction.startedAt < compactionFlagLifetimeMilliseconds),
+    notify,
+    sendUserMessage: async (text) => {
+      const sessionId = targetSessionId;
+      if (sessionId === null) {
+        // Losing a target between the hold check and this asynchronous handoff
+        // refuses this dispatch without invalidating the OpenCode plugin.
+        throw new Error("No OpenCode session is available for delivery.");
+      }
+      await injectFollowUp(sessionId, text);
+    },
+  };
+
+  const bridge: BridgeHandle = startBridge({
+    agentSessionId: null,
+    beacon,
+    credentials,
+    displayName: chooseDisplayName(environment, input.directory),
+    fetchImplementation: fetch,
+    host: port,
+    hostname: hostname(),
+    kind: "opencode",
+    locations,
+    workingDirectory: input.directory,
+  });
+
+  return {
+    "chat.message": (chat) => {
+      if (!childSessionIds.has(chat.sessionID)) {
+        targetSessionId = chat.sessionID;
+      }
+      return Promise.resolve();
+    },
+    dispose: () => bridge.stop({disconnect: true}),
+    event: (received) => {
+      const lifecycle = sessionLifecycleEventSchema.safeParse(received.event);
+      if (lifecycle.success) {
+        const {id, parentID} = lifecycle.data.properties.info;
+        if (lifecycle.data.type === "session.deleted") {
+          childSessionIds.delete(id);
+          if (targetSessionId === id) targetSessionId = null;
+        } else if (parentID !== undefined) {
+          childSessionIds.add(id);
+        } else if (targetSessionId === null) {
+          // A top-level session appearing before any chat activity is the
+          // best available target; the next chat message refines it.
+          targetSessionId = id;
+        }
+        return Promise.resolve();
+      }
+      const compacted = sessionCompactedEventSchema.safeParse(received.event);
+      if (
+        compacted.success &&
+        compaction?.sessionId === compacted.data.properties.sessionID
+      ) {
+        compaction = null;
+      }
+      return Promise.resolve();
+    },
+    "experimental.session.compacting": (compacting) => {
+      compaction = {sessionId: compacting.sessionID, startedAt: Date.now()};
+      return Promise.resolve();
+    },
+    tool: {
+      artifact_comments: {
+        args: artifactCommentsToolArguments(),
+        description: artifactCommentsDescription,
+        async execute(args) {
+          if (comments === null) {
+            throw new Error(
+              "Artifact Server is not configured; the bridge is dormant.",
+            );
+          }
+          if (args.operation === "get_bundle") {
+            const threadIds = args.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 comments.getThread(threadId));
+            }
+            return JSON.stringify(details, null, 2);
+          }
+          const threadId = args.threadId ?? "";
+          if (threadId === "") {
+            throw new Error(`${args.operation} requires threadId.`);
+          }
+          if (args.operation === "reply") {
+            const body = args.body ?? "";
+            if (body.trim() === "") {
+              throw new Error("reply requires a non-empty body.");
+            }
+            await comments.reply(threadId, body);
+            return `Replied to ${threadId}.`;
+          }
+          await comments.resolve(threadId);
+          return `Resolved ${threadId}.`;
+        },
+      },
+    },
+  };
+}
+
+export default ArtifactServerBridge;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@plannotator/artifact-server-opencode",
+  "version": "0.1.1",
+  "description": "OpenCode plugin bridge for Artifact Server: receives annotation bundles as follow-up prompts and closes them through the comment API.",
+  "type": "module",
+  "keywords": [
+    "opencode-plugin",
+    "artifact-server"
+  ],
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@plannotator/agent-bridge": "^0.1.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "integrations/opencode",
+    "type": "git",
+    "url": "git+https://github.com/plannotator/artifact-server.git"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}