@snarkipus/opencode-beads 0.10.0 → 1.0.0

package/src/guidance.ts

@@ -0,0 +1,53 @@
+/**
+ * Fork-owned guidance for OpenCode: the shared context layer and the bounded task-agent prompt.
+ *
+ * Upstream Beads ships its task agent only for Claude Code, as an autonomous multi-task loop. This
+ * adapter deliberately diverges (one bead per invocation), so the prompt and description live here.
+ */
+
+/** Shown when OpenCode lists subagents; describes the one-bead worker contract. */
+export const BEADS_TASK_AGENT_DESCRIPTION =
+  "Bounded Beads worker: analyzes the issue graph read-only, or claims, completes, and closes or blocks exactly one bead per invocation.";
+
+const BEADS_HOST_GUIDANCE = `## CLI Safety
+
+There is no native \`bd\` or Beads MCP tool in OpenCode. Run \`bd\` through \`bash\`.
+Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd <command> --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures.
+
+Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it.`;
+
+const BEADS_DELEGATION_GUIDANCE = `## Delegation
+
+Delegate multi-command Beads work and issue-graph analysis to the \`beads-task-agent\` subagent through the \`subagent\` tool; perform only single atomic operations directly.`;
+
+/** Fork-owned system prompt for the bounded one-bead task agent. */
+export const BEADS_TASK_AGENT_PROMPT = `## Beads Task Agent
+
+Full \`bd prime\` workflow context is injected with each request. Use \`bd\` via \`bash\`; rerun prime if context is missing or stale.
+
+For status or graph analysis, never claim, update, close, or modify a bead. Return the analysis and stop.
+
+For completion, process exactly one bead. Use a caller-supplied ID; otherwise choose one highest-priority ready bead. First run \`bd show <id> --json\`; confirm it is open, actionable, and appropriate; then claim with \`bd update <id> --claim --json\`. If an assigned bead is closed, blocked, unsuitable, missing, or otherwise not actionable, report and return without mutation or substitution.
+
+Implement and validate it. Create discoveries with \`discovered-from:<current-id>\` and a parent only when structurally obvious. Never claim or implement work created this invocation; it may be eligible later. Close or block the current bead, report discoveries, and return without seeking more work. Return concise results, not raw JSON.`;
+
+/** Shown instead of context when `bd prime` fails, as upstream's Codex hook reports refresh failures. */
+export function primeFailureNotice(reason: "failed" | "timed out"): string {
+  return `<beads-notice>
+Beads workflow context could not be loaded: \`bd prime\` ${reason}. Beads may still work; run \`bd prime\` to load the workflow and see the error, and tell the user if it keeps failing.
+</beads-notice>`;
+}
+
+/** Added to compaction requests so the summary keeps the Beads work in flight. */
+export const BEADS_COMPACTION_GUIDANCE = `<beads-compaction>
+This session tracks work in Beads (bd). In the summary, preserve every bead ID mentioned, which bead is claimed or in progress and its current status, discovered follow-up beads and how they were linked, blockers, and validation still pending. Fresh \`bd prime\` context is attached again after compaction, so do not restate the Beads workflow itself.
+</beads-compaction>`;
+
+/** Build the single shared guidance layer for one injected audience. */
+export function beadsGuidance(
+  audience: "primary" | "task-agent"
+): string {
+  const sections = [BEADS_HOST_GUIDANCE];
+  if (audience === "primary") sections.push(BEADS_DELEGATION_GUIDANCE);
+  return `<beads-guidance>\n${sections.join("\n\n")}\n</beads-guidance>`;
+}

package/src/host.ts

@@ -0,0 +1,140 @@
+import type { Plugin } from "@opencode/plugin";
+import { applyBeadsAgents, beadsAgents } from "./agents";
+import { BEADS_COMPACTION_GUIDANCE } from "./guidance";
+import {
+  createContextController,
+  type AgentMode,
+  type ContextDiagnostic,
+  type ContextRuntime,
+} from "./context";
+import { checkBeadsStore, createGuardRuntime } from "./guard";
+import { minimizeSystemParts } from "./instructions";
+import { runBd, runBdPrime } from "./prime";
+
+/** The slice of the OpenCode V2 plugin context this adapter uses. */
+export type HostContext = Pick<Plugin.Context, "location" | "options" | "event"> & {
+  agent: Pick<Plugin.Context["agent"], "get" | "transform">;
+  session: Pick<Plugin.Context["session"], "hook">;
+};
+
+export interface HostDependencies {
+  /** Override process-backed Beads calls, mainly for tests. */
+  runtime?: Partial<Pick<ContextRuntime, "guard" | "prime">>;
+  /** Override the `bd prime` runner (receives extra flags such as `--stealth`). */
+  runPrime?: (directory: string, flags: readonly string[]) => Promise<string>;
+  /** Override the bounded `bd` runner used by the store guard. */
+  bd?: (directory: string, args: readonly string[]) => Promise<string>;
+  warn?: (message: string) => void;
+  diagnosticIntervalMs?: number;
+  now?: () => number;
+  retryMs?: number;
+}
+
+const DEFAULT_DIAGNOSTIC_INTERVAL_MS = 60_000;
+
+function eventSessionID(event: unknown): string | undefined {
+  if (typeof event !== "object" || event === null) return undefined;
+  const data = (event as { data?: unknown }).data;
+  if (typeof data !== "object" || data === null) return undefined;
+  const sessionID = (data as { sessionID?: unknown }).sessionID;
+  return typeof sessionID === "string" ? sessionID : undefined;
+}
+
+/** Wire Beads context into an OpenCode V2 plugin context; returns the plugin cleanup. */
+export async function setupBeads(
+  ctx: HostContext,
+  deps: HostDependencies = {}
+): Promise<() => void> {
+  const directory = ctx.location.directory;
+  const autoMigrate = ctx.options?.autoMigrate === true;
+  // Mirrors `bd setup claude --stealth`: prime without git operations in the session-close protocol.
+  const stealth = ctx.options?.stealth === true;
+  const now = deps.now ?? Date.now;
+  const warn = deps.warn ?? ((message: string) => console.warn(message));
+  const diagnosticIntervalMs = deps.diagnosticIntervalMs ?? DEFAULT_DIAGNOSTIC_INTERVAL_MS;
+  const diagnosticTimes = new Map<string, number>();
+
+  const guardRuntime = createGuardRuntime(deps.bd ?? ((cwd, args) => runBd(cwd, args)));
+  const runtime: ContextRuntime = {
+    guard: deps.runtime?.guard ?? ((cwd) => checkBeadsStore(cwd, guardRuntime, { autoMigrate })),
+    prime:
+      deps.runtime?.prime ??
+      ((cwd) => (deps.runPrime ?? ((dir, flags) => runBdPrime(dir, {}, flags)))(cwd, stealth ? ["--stealth"] : [])),
+    async agentMode(agentID): Promise<AgentMode | undefined> {
+      const response = await ctx.agent.get({ agentID });
+      return response.data.mode;
+    },
+    diagnose(code: ContextDiagnostic, sessionID: string) {
+      const key = `${code}:${sessionID}`;
+      const previous = diagnosticTimes.get(key);
+      const current = now();
+      if (previous !== undefined && current - previous < diagnosticIntervalMs) return;
+      diagnosticTimes.set(key, current);
+      try {
+        warn(`[opencode-beads] ${code} session=${sessionID} directory=${directory}`);
+      } catch {
+        // Diagnostics never affect model requests.
+      }
+    },
+  };
+
+  const stepsOption = ctx.options?.taskAgentSteps;
+  const agents = beadsAgents({
+    luna: ctx.options?.luna === true,
+    steps: typeof stepsOption === "number" && Number.isInteger(stepsOption) && stepsOption >= 0 ? stepsOption : undefined,
+  });
+  await ctx.agent.transform((editor) => applyBeadsAgents(editor, agents));
+
+  const idleMinutes = ctx.options?.refreshAfterIdleMinutes;
+  const controller = createContextController(runtime, directory, {
+    now: deps.now,
+    retryMs: deps.retryMs,
+    idleRefreshMs:
+      typeof idleMinutes === "number" && Number.isFinite(idleMinutes) && idleMinutes >= 0
+        ? idleMinutes * 60_000
+        : undefined,
+  });
+
+  // Sessions that have received Beads context; their compaction summaries should keep Beads state.
+  const beadsSessions = new Set<string>();
+
+  await ctx.session.hook("context", async (event) => {
+    const text = await controller.systemFor(event.sessionID, event.agent);
+    if (!text) return;
+    if (text.startsWith("<beads-context")) {
+      beadsSessions.add(event.sessionID);
+      // With prime attached, bd's full AGENTS.md sections only repeat it (Claude Code gets a pointer).
+      minimizeSystemParts(event.system);
+    }
+    event.system.push({ type: "text", text });
+  });
+
+  await ctx.session.hook("compaction", (event) => {
+    if (beadsSessions.has(event.sessionID)) {
+      event.system.push({ type: "text", text: BEADS_COMPACTION_GUIDANCE });
+    }
+  });
+
+  const abort = new AbortController();
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: abort.signal })) {
+        const type = (event as { type?: unknown }).type;
+        const sessionID = eventSessionID(event);
+        if (!sessionID) continue;
+        if (type === "session.compaction.ended") controller.invalidate(sessionID);
+        else if (type === "session.deleted") {
+          controller.forget(sessionID);
+          beadsSessions.delete(sessionID);
+          for (const key of diagnosticTimes.keys()) {
+            if (key.endsWith(`:${sessionID}`)) diagnosticTimes.delete(key);
+          }
+        }
+      }
+    } catch {
+      // The stream ends on cleanup; lost events only delay a cache refresh.
+    }
+  })();
+
+  return () => abort.abort();
+}

package/src/instructions.ts

@@ -0,0 +1,49 @@
+/**
+ * Minimal Beads instructions while prime is attached, matching Claude Code's integration.
+ *
+ * `bd setup claude` writes only a short pointer into CLAUDE.md because its hooks run `bd prime`.
+ * OpenCode projects instead get bd's full-profile AGENTS.md section (and often a Codex section),
+ * which repeats what injected prime already provides on every request. When this plugin attaches
+ * prime, those bd-managed blocks are replaced in the outgoing system text only; files are untouched.
+ */
+
+/** Replaces bd-managed blocks whose content duplicates injected prime. */
+export const MINIMAL_BEADS_POINTER =
+  "Beads (bd) workflow context for this project is provided by the opencode-beads plugin in the <beads-context> block, from `bd prime`.";
+
+// bd's full-profile integration block and its Codex setup block. Minimal-profile blocks are already
+// equivalent to Claude Code's pointer and are left alone.
+const DUPLICATE_BLOCKS: readonly RegExp[] = [
+  /<!-- BEGIN BEADS INTEGRATION\b[^>]*\bprofile:full\b[^>]*-->[\s\S]*?<!-- END BEADS INTEGRATION -->/g,
+  /<!-- BEGIN BEADS CODEX SETUP\b[^>]*-->[\s\S]*?<!-- END BEADS CODEX SETUP -->/g,
+];
+
+/** Return `text` with duplicate bd blocks collapsed into one pointer, and how many were replaced. */
+export function minimizeBeadsInstructions(text: string): { text: string; replaced: number } {
+  let replaced = 0;
+  let pointerPlaced = false;
+  let result = text;
+  for (const pattern of DUPLICATE_BLOCKS) {
+    result = result.replace(pattern, () => {
+      replaced++;
+      if (pointerPlaced) return "";
+      pointerPlaced = true;
+      return MINIMAL_BEADS_POINTER;
+    });
+  }
+  return { text: result, replaced };
+}
+
+/** Apply {@link minimizeBeadsInstructions} to each text system part in place. */
+export function minimizeSystemParts(parts: Array<{ type: string; text?: string }>): number {
+  let replaced = 0;
+  for (const part of parts) {
+    if (part.type !== "text" || typeof part.text !== "string") continue;
+    const minimized = minimizeBeadsInstructions(part.text);
+    if (minimized.replaced > 0) {
+      part.text = minimized.text;
+      replaced += minimized.replaced;
+    }
+  }
+  return replaced;
+}

package/src/plugin.ts

@@ -1,12 +1,12 @@
-/** OpenCode adapter for the Beads issue tracker. */
+/** OpenCode V2 adapter for the Beads issue tracker. */
 
-import type { Plugin } from "@opencode-ai/plugin";
-import { resolveProjectDirectory } from "./plugin-core";
-import { createBeadsHooks } from "./plugin-hooks";
-import { createOpenCodeRuntime } from "./opencode-runtime";
+import type { Plugin } from "@opencode/plugin";
+import { setupBeads } from "./host";
 
-export const BeadsPlugin: Plugin = async ({ client, directory, worktree }) => {
-  const projectDirectory = resolveProjectDirectory(directory, worktree);
-  const runtime = createOpenCodeRuntime(client);
-  return createBeadsHooks(runtime, projectDirectory);
+// A plain object satisfies Plugin.define's identity contract without a runtime import.
+const BeadsPlugin: Plugin.Plugin = {
+  id: "opencode-beads",
+  setup: (ctx) => setupBeads(ctx),
 };
+
+export default BeadsPlugin;

package/src/prime.ts

@@ -4,15 +4,15 @@ export const DEFAULT_PRIME_TIMEOUT_MS = 10_000;
 export const DEFAULT_PRIME_DRAIN_TIMEOUT_MS = 1_000;
 
 export class PrimeTimeoutError extends Error {
-  constructor(timeoutMs: number) {
-    super(`bd prime timed out after ${timeoutMs}ms`);
+  constructor(timeoutMs: number, command = "bd prime") {
+    super(`${command} timed out after ${timeoutMs}ms`);
     this.name = "PrimeTimeoutError";
   }
 }
 
 export class PrimeProcessError extends Error {
-  constructor(readonly exitCode: number, readonly stderr: string) {
-    super(`bd prime exited with code ${exitCode}`);
+  constructor(readonly exitCode: number, readonly stderr: string, command = "bd prime") {
+    super(`${command} exited with code ${exitCode}`);
     this.name = "PrimeProcessError";
   }
 }
@@ -34,8 +34,8 @@ export interface PrimeExecutionOptions {
   scheduleDrainTimeout?: (callback: () => void, delayMs: number) => () => void;
 }
 
-function spawnPrime(directory: string, args: readonly string[]): PrimeProcess {
-  const child = Bun.spawn(["bd", "prime", ...args], {
+function spawnBd(directory: string, args: readonly string[]): PrimeProcess {
+  const child = Bun.spawn(["bd", ...args], {
     cwd: directory,
     stdin: "ignore",
     stdout: "pipe",
@@ -100,14 +100,15 @@ async function drainAfterKill(
   });
 }
 
-async function runPrimeAttempt(
+async function runBdAttempt(
   directory: string,
   args: readonly string[],
   options: PrimeExecutionOptions = {}
 ): Promise<string> {
   const timeoutMs = options.timeoutMs ?? DEFAULT_PRIME_TIMEOUT_MS;
   const drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_PRIME_DRAIN_TIMEOUT_MS;
-  const child = (options.spawn ?? spawnPrime)(directory, args);
+  const command = ["bd", ...args].join(" ");
+  const child = (options.spawn ?? spawnBd)(directory, args);
   const stdout = new Response(child.stdout).text();
   const stderr = new Response(child.stderr).text();
 
@@ -119,12 +120,12 @@ async function runPrimeAttempt(
   const cancelTimeout = (options.scheduleTimeout ?? scheduleTimeout)(() => {
     timedOut = true;
     terminateProcessTree(child);
-    rejectTimeout(new PrimeTimeoutError(timeoutMs));
+    rejectTimeout(new PrimeTimeoutError(timeoutMs, command));
   }, timeoutMs);
 
   const completion = Promise.all([child.exited, stdout, stderr]).then(
     ([exitCode, output, errorOutput]) => {
-      if (exitCode !== 0) throw new PrimeProcessError(exitCode, errorOutput);
+      if (exitCode !== 0) throw new PrimeProcessError(exitCode, errorOutput, command);
       return output;
     }
   );
@@ -143,10 +144,20 @@ async function runPrimeAttempt(
   }
 }
 
+/** Run one bounded `bd` invocation in the project directory and return its stdout. */
+export async function runBd(
+  directory: string,
+  args: readonly string[],
+  options: PrimeExecutionOptions = {}
+): Promise<string> {
+  return runBdAttempt(directory, args, options);
+}
+
 /** Load the canonical Beads workflow and persistent project memories. */
 export async function runBdPrime(
   directory: string,
-  options: PrimeExecutionOptions = {}
+  options: PrimeExecutionOptions = {},
+  flags: readonly string[] = []
 ): Promise<string> {
-  return runPrimeAttempt(directory, [], options);
+  return runBd(directory, ["prime", ...flags], options);
 }

package/src/opencode-runtime.ts

@@ -1,156 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-import type { Agent, SessionMessagesResponse } from "@opencode-ai/sdk";
-import type { PluginRuntime } from "./plugin-core";
-import { runBdPrime } from "./prime";
-
-export const DEFAULT_OPENCODE_REQUEST_TIMEOUT_MS = 5_000;
-export const DEFAULT_OPENCODE_DIAGNOSTIC_TIMEOUT_MS = 1_000;
-
-export class OpenCodeTimeoutError extends Error {
-  constructor(readonly operation: string, readonly timeoutMs: number) {
-    super(`OpenCode ${operation} timed out after ${timeoutMs}ms`);
-    this.name = "OpenCodeTimeoutError";
-  }
-}
-
-export interface OpenCodeRuntimeOptions {
-  requestTimeoutMs?: number;
-  diagnosticTimeoutMs?: number;
-  prime?: PluginRuntime["prime"];
-}
-
-async function withDeadline<T>(
-  operation: string,
-  timeoutMs: number,
-  execute: (signal: AbortSignal) => Promise<T>
-): Promise<T> {
-  const controller = new AbortController();
-  let rejectTimeout: (error: OpenCodeTimeoutError) => void = () => {};
-  const timeout = new Promise<never>((_resolve, reject) => {
-    rejectTimeout = reject;
-  });
-  const timer = setTimeout(() => {
-    const error = new OpenCodeTimeoutError(operation, timeoutMs);
-    controller.abort(error);
-    rejectTimeout(error);
-  }, timeoutMs);
-
-  try {
-    return await Promise.race([execute(controller.signal), timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function isSessionMessage(value: unknown): boolean {
-  if (
-    !isRecord(value) ||
-    !isRecord(value.info) ||
-    (value.info.role !== "user" && value.info.role !== "assistant") ||
-    (value.info.agent !== undefined && typeof value.info.agent !== "string") ||
-    (value.info.system !== undefined && typeof value.info.system !== "string") ||
-    (value.info.model !== undefined &&
-      (!isRecord(value.info.model) ||
-        typeof value.info.model.providerID !== "string" ||
-        typeof value.info.model.modelID !== "string"))
-  ) {
-    return false;
-  }
-  if (!Array.isArray(value.parts)) return false;
-
-  return value.parts.every(
-    (part) =>
-      isRecord(part) &&
-      typeof part.type === "string" &&
-      (part.text === undefined || typeof part.text === "string") &&
-      (part.synthetic === undefined || typeof part.synthetic === "boolean")
-  );
-}
-
-function isAgent(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    typeof value.name === "string" &&
-    (value.mode === "subagent" || value.mode === "primary" || value.mode === "all")
-  );
-}
-
-/** Adapt the official OpenCode client to the controller's small deterministic boundary. */
-export function createOpenCodeRuntime(
-  client: PluginInput["client"],
-  options: OpenCodeRuntimeOptions = {}
-): PluginRuntime {
-  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_OPENCODE_REQUEST_TIMEOUT_MS;
-  const diagnosticTimeoutMs =
-    options.diagnosticTimeoutMs ?? DEFAULT_OPENCODE_DIAGNOSTIC_TIMEOUT_MS;
-
-  return {
-    async getMessages(projectDirectory, sessionID, limit) {
-      const response = await withDeadline("session.messages", requestTimeoutMs, (signal) =>
-        client.session.messages({
-          path: { id: sessionID },
-          query: { directory: projectDirectory, limit },
-          signal,
-        })
-      );
-      if (response.error !== undefined) throw response.error;
-      if (!Array.isArray(response.data) || !response.data.every(isSessionMessage)) {
-        throw new Error("OpenCode returned malformed session messages");
-      }
-      return response.data satisfies SessionMessagesResponse;
-    },
-
-    async getAgents(projectDirectory) {
-      const response = await withDeadline("app.agents", requestTimeoutMs, (signal) =>
-        client.app.agents({ query: { directory: projectDirectory }, signal })
-      );
-      if (response.error !== undefined) throw response.error;
-      if (!Array.isArray(response.data) || !response.data.every(isAgent)) {
-        throw new Error("OpenCode returned malformed agents");
-      }
-      return response.data satisfies Agent[];
-    },
-
-    async prompt(projectDirectory, sessionID, body) {
-      const response = await withDeadline("session.prompt", requestTimeoutMs, (signal) =>
-        client.session.prompt({
-          path: { id: sessionID },
-          query: { directory: projectDirectory },
-          body,
-          signal,
-        })
-      );
-      if (response.error !== undefined) throw response.error;
-      if (response.data === undefined) throw new Error("OpenCode returned no prompt result");
-    },
-
-    async prime(projectDirectory) {
-      return (options.prime ?? runBdPrime)(projectDirectory);
-    },
-
-    async diagnose(diagnostic) {
-      const extra =
-        diagnostic.code === "config_collision"
-          ? { surface: diagnostic.surface, names: diagnostic.names }
-          : { sessionID: diagnostic.sessionID };
-      const response = await withDeadline("app.log", diagnosticTimeoutMs, (signal) =>
-        client.app.log({
-          query: { directory: diagnostic.directory },
-          body: {
-            service: "opencode-beads",
-            level: "warn",
-            message: diagnostic.code,
-            extra,
-          },
-          signal,
-        })
-      );
-      if (response.error !== undefined) throw response.error;
-      if (response.data === undefined) throw new Error("OpenCode returned no log result");
-    },
-  };
-}