@snarkipus/opencode-beads 0.8.0

package/src/plugin-core.ts

@@ -0,0 +1,290 @@
+import type { Hooks } from "@opencode-ai/plugin";
+import type {
+  Agent,
+  SessionMessagesResponse,
+  SessionPromptData,
+  TextPart,
+  TextPartInput,
+  UserMessage,
+} from "@opencode-ai/sdk";
+import { PrimeTimeoutError } from "./prime";
+import { beadsGuidance, loadAgent, loadCommands } from "./vendor";
+
+const BEADS_TASK_AGENT = "beads-task-agent";
+
+type ChatMessageInput = Parameters<NonNullable<Hooks["chat.message"]>>[0];
+type SessionMessageResponse = SessionMessagesResponse[number];
+type SessionPromptBody = NonNullable<SessionPromptData["body"]>;
+
+export type ModelContext = NonNullable<ChatMessageInput["model"]>;
+export type MessageContext = Pick<ChatMessageInput, "sessionID" | "agent" | "model">;
+export type ContextSink = (context: string) => void | Promise<void>;
+
+// The controller only needs this projection; the OpenCode adapter validates the full response.
+export type SessionMessage = {
+  info: Pick<SessionMessageResponse["info"], "role"> &
+    Partial<Pick<UserMessage, "agent" | "model" | "system">>;
+  parts?: ReadonlyArray<
+    Pick<SessionMessageResponse["parts"][number], "type"> & Partial<Pick<TextPart, "text">>
+  >;
+};
+
+export type AgentInfo = Pick<Agent, "name" | "mode">;
+
+export type PromptBody = Omit<SessionPromptBody, "noReply" | "parts"> & {
+  noReply: true;
+  parts: Array<TextPartInput & { synthetic: true }>;
+};
+
+export interface PluginRuntime {
+  getMessages(
+    directory: string,
+    sessionID: string,
+    limit?: number
+  ): Promise<ReadonlyArray<SessionMessage> | undefined>;
+  getAgents(directory: string): Promise<ReadonlyArray<AgentInfo> | undefined>;
+  prompt(directory: string, sessionID: string, body: PromptBody): Promise<void>;
+  prime(directory: string): Promise<string>;
+  diagnose(diagnostic: PluginDiagnostic): Promise<void>;
+}
+
+export type DiagnosticCode =
+  | "agents_lookup_failed"
+  | "config_collision"
+  | "messages_lookup_failed"
+  | "prime_failed"
+  | "prime_timeout"
+  | "prompt_failed";
+
+export type PluginDiagnostic =
+  | {
+      code: Exclude<DiagnosticCode, "config_collision">;
+      directory: string;
+      sessionID: string;
+    }
+  | {
+      code: "config_collision";
+      directory: string;
+      surface: "agent" | "command";
+      names: string[];
+    };
+
+export interface ControllerOptions {
+  diagnosticIntervalMs?: number;
+  now?: () => number;
+}
+
+export type MutablePluginConfig = Parameters<NonNullable<Hooks["config"]>>[0];
+
+export interface BeadsController {
+  onMessage(message: MessageContext, sink: ContextSink): Promise<void>;
+  onCompacted(sessionID: string): Promise<void>;
+  configure(config: MutablePluginConfig): Promise<void>;
+}
+
+/** Resolve OpenCode project scope without falling back to the process directory. */
+export function resolveProjectDirectory(directory: string, worktree: string): string {
+  if (directory.trim()) return directory;
+  if (worktree.trim()) return worktree;
+  throw new Error("OpenCode did not provide a project directory or worktree");
+}
+
+/** Select the newest eligible user context from OpenCode's oldest-first message list. */
+function latestSessionContext(messages: ReadonlyArray<SessionMessage> | undefined) {
+  if (!messages) return undefined;
+
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.info.role === "user" && message.info.model) {
+      return { model: message.info.model, agent: message.info.agent };
+    }
+  }
+
+  return undefined;
+}
+
+/** Create the stateful Beads behavior behind the OpenCode hook adapter. */
+export async function createBeadsController(
+  runtime: PluginRuntime,
+  directory: string,
+  options: ControllerOptions = {}
+): Promise<BeadsController> {
+  const [loadedCommands, loadedAgents] = await Promise.all([loadCommands(), loadAgent()]);
+  const commands = loadedCommands ?? {};
+  const agents = loadedAgents ?? {};
+  const injectedSessions = new Set<string>();
+  const injectionAttempts = new Map<string, Promise<void>>();
+  const diagnosticTimes = new Map<string, number>();
+  const diagnosticIntervalMs = options.diagnosticIntervalMs ?? 60_000;
+  const now = options.now ?? Date.now;
+
+  async function diagnose(diagnostic: PluginDiagnostic, key: string): Promise<void> {
+    const currentTime = now();
+    const previousTime = diagnosticTimes.get(key);
+    if (previousTime !== undefined && currentTime - previousTime < diagnosticIntervalMs) return;
+
+    diagnosticTimes.set(key, currentTime);
+    await runtime.diagnose(diagnostic).catch(() => undefined);
+  }
+
+  async function diagnoseSession(
+    code: Exclude<DiagnosticCode, "config_collision">,
+    sessionID: string
+  ): Promise<void> {
+    await diagnose({ code, directory, sessionID }, `${code}:${sessionID}`);
+  }
+
+  async function shouldInject(
+    agentName: string | undefined,
+    sessionID: string
+  ): Promise<boolean> {
+    if (!agentName || agentName === BEADS_TASK_AGENT) return true;
+
+    const availableAgents = await runtime.getAgents(directory).catch(async () => {
+      await diagnoseSession("agents_lookup_failed", sessionID);
+      return undefined;
+    });
+    const agent = availableAgents?.find((candidate) => candidate.name === agentName);
+    return agent ? agent.mode === "primary" || agent.mode === "all" : true;
+  }
+
+  async function renderContext(
+    sessionID: string,
+    context?: { model?: ModelContext; agent?: string }
+  ): Promise<string | undefined> {
+    let output: string;
+    try {
+      output = (await runtime.prime(directory)).trim();
+    } catch (error) {
+      const code = error instanceof PrimeTimeoutError ? "prime_timeout" : "prime_failed";
+      await diagnoseSession(code, sessionID);
+      return undefined;
+    }
+    if (!output) return undefined;
+
+    const audience = context?.agent === BEADS_TASK_AGENT ? "task-agent" : "primary";
+    return `<beads-context>\n${output}\n</beads-context>\n\n${beadsGuidance(audience)}`;
+  }
+
+  async function injectPrompt(
+    sessionID: string,
+    context?: { model?: ModelContext; agent?: string }
+  ): Promise<boolean> {
+    const rendered = await renderContext(sessionID, context);
+    if (!rendered) return false;
+
+    try {
+      await runtime.prompt(directory, sessionID, {
+        noReply: true,
+        model: context?.model,
+        agent: context?.agent,
+        parts: [
+          {
+            type: "text",
+            text: rendered,
+            synthetic: true,
+          },
+        ],
+      });
+      return true;
+    } catch {
+      await diagnoseSession("prompt_failed", sessionID);
+      return false;
+    }
+  }
+
+  async function performInitialInjection(message: MessageContext, sink: ContextSink): Promise<void> {
+    if (!(await shouldInject(message.agent, message.sessionID))) {
+      injectedSessions.add(message.sessionID);
+      return;
+    }
+
+    try {
+      const existing = await runtime.getMessages(directory, message.sessionID);
+      const hasBeadsContext = existing?.some(
+        (item) =>
+          item.info.system?.includes("<beads-context>") ||
+          item.parts?.some(
+            (part) => part.type === "text" && part.text?.includes("<beads-context>")
+          )
+      );
+      if (hasBeadsContext) {
+        injectedSessions.add(message.sessionID);
+        return;
+      }
+    } catch {
+      await diagnoseSession("messages_lookup_failed", message.sessionID);
+      // Message lookup is advisory; injection remains the safe fallback.
+    }
+
+    const rendered = await renderContext(message.sessionID, message);
+    if (!rendered) return;
+
+    try {
+      await sink(rendered);
+      injectedSessions.add(message.sessionID);
+    } catch {
+      await diagnoseSession("prompt_failed", message.sessionID);
+    }
+  }
+
+  return {
+    async onMessage(message, sink) {
+      if (injectedSessions.has(message.sessionID)) return;
+
+      const pending = injectionAttempts.get(message.sessionID);
+      if (pending) return pending;
+
+      const attempt = performInitialInjection(message, sink);
+      injectionAttempts.set(message.sessionID, attempt);
+      try {
+        await attempt;
+      } finally {
+        if (injectionAttempts.get(message.sessionID) === attempt) {
+          injectionAttempts.delete(message.sessionID);
+        }
+      }
+    },
+
+    async onCompacted(sessionID) {
+      const messages = await runtime.getMessages(directory, sessionID, 50).catch(async () => {
+        await diagnoseSession("messages_lookup_failed", sessionID);
+        return undefined;
+      });
+      const context = latestSessionContext(messages);
+      if (await shouldInject(context?.agent, sessionID)) {
+        await injectPrompt(sessionID, context);
+      }
+    },
+
+    async configure(config) {
+      const commandCollisions = Object.keys(config.command ?? {})
+        .filter(
+          (name) =>
+            Object.hasOwn(commands, name) && config.command?.[name] !== commands[name]
+        )
+        .sort();
+      const agentCollisions = Object.keys(config.agent ?? {})
+        .filter(
+          (name) => Object.hasOwn(agents, name) && config.agent?.[name] !== agents[name]
+        )
+        .sort();
+
+      await Promise.all(
+        ([
+          ["command", commandCollisions],
+          ["agent", agentCollisions],
+        ] as const).map(async ([surface, names]) => {
+          if (names.length === 0) return;
+          await diagnose(
+            { code: "config_collision", directory, surface, names },
+            `config_collision:${surface}:${names.join("\0")}`
+          );
+        })
+      );
+
+      config.command = { ...commands, ...config.command };
+      config.agent = { ...agents, ...config.agent };
+    },
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,150 @@
+/** OpenCode adapter for the Beads issue tracker. */
+
+import type { Plugin, PluginInput } from "@opencode-ai/plugin";
+import type { Agent, Part, SessionMessagesResponse } from "@opencode-ai/sdk";
+import {
+  createBeadsController,
+  resolveProjectDirectory,
+  type PluginRuntime,
+} from "./plugin-core";
+import { runBdPrime } from "./prime";
+
+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")
+  );
+}
+
+function isAgent(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    (value.mode === "subagent" || value.mode === "primary" || value.mode === "all")
+  );
+}
+
+/** Prevent the synthetic no-reply prompt from recursively triggering its own injection. */
+function isBeadsContextInjection(parts: ReadonlyArray<Part>): boolean {
+  return parts.some(
+    (part) =>
+      part.type === "text" &&
+      part.synthetic === true &&
+      part.text.includes("<beads-context>")
+  );
+}
+
+/** Adapt the official OpenCode client to the controller's small deterministic boundary. */
+export function createOpenCodeRuntime(client: PluginInput["client"]): PluginRuntime {
+  return {
+    async getMessages(projectDirectory, sessionID, limit) {
+      const response = await client.session.messages({
+        path: { id: sessionID },
+        query: { directory: projectDirectory, limit },
+      });
+      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 client.app.agents({ query: { directory: projectDirectory } });
+      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 client.session.prompt({
+        path: { id: sessionID },
+        query: { directory: projectDirectory },
+        body,
+      });
+      if (response.error !== undefined) throw response.error;
+      if (response.data === undefined) throw new Error("OpenCode returned no prompt result");
+    },
+
+    async prime(projectDirectory) {
+      return runBdPrime(projectDirectory);
+    },
+
+    async diagnose(diagnostic) {
+      const extra =
+        diagnostic.code === "config_collision"
+          ? { surface: diagnostic.surface, names: diagnostic.names }
+          : { sessionID: diagnostic.sessionID };
+      const response = await client.app.log({
+        query: { directory: diagnostic.directory },
+        body: {
+          service: "opencode-beads",
+          level: "warn",
+          message: diagnostic.code,
+          extra,
+        },
+      });
+      if (response.error !== undefined) throw response.error;
+      if (response.data === undefined) throw new Error("OpenCode returned no log result");
+    },
+  };
+}
+
+export const BeadsPlugin: Plugin = async ({ client, directory, worktree }) => {
+  const projectDirectory = resolveProjectDirectory(directory, worktree);
+  const runtime = createOpenCodeRuntime(client);
+
+  const controller = await createBeadsController(runtime, projectDirectory);
+
+  return {
+    "chat.message": async (input, output) => {
+      if (isBeadsContextInjection(output.parts)) return;
+
+      await controller.onMessage(
+        {
+          sessionID: input.sessionID,
+          model: input.model,
+          agent: input.agent,
+        },
+        (context) => {
+          output.message.system = output.message.system
+            ? `${output.message.system}\n\n${context}`
+            : context;
+        }
+      );
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") {
+        await controller.onCompacted(event.properties.sessionID);
+      }
+    },
+
+    config: async (config) => {
+      await controller.configure(config);
+    },
+  };
+};

package/src/prime.ts

@@ -0,0 +1,88 @@
+export const DEFAULT_PRIME_TIMEOUT_MS = 10_000;
+
+export class PrimeTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`bd prime 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}`);
+    this.name = "PrimeProcessError";
+  }
+}
+
+export interface PrimeProcess {
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill(signal?: NodeJS.Signals): void;
+}
+
+export interface PrimeExecutionOptions {
+  timeoutMs?: number;
+  spawn?: (directory: string, args: readonly string[]) => PrimeProcess;
+  scheduleTimeout?: (callback: () => void, delayMs: number) => () => void;
+}
+
+function spawnPrime(directory: string, args: readonly string[]): PrimeProcess {
+  return Bun.spawn(["bd", "prime", ...args], {
+    cwd: directory,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+}
+
+function scheduleTimeout(callback: () => void, delayMs: number): () => void {
+  const timer = setTimeout(callback, delayMs);
+  return () => clearTimeout(timer);
+}
+
+async function runPrimeAttempt(
+  directory: string,
+  args: readonly string[],
+  options: PrimeExecutionOptions = {}
+): Promise<string> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PRIME_TIMEOUT_MS;
+  const process = (options.spawn ?? spawnPrime)(directory, args);
+  const stdout = new Response(process.stdout).text();
+  const stderr = new Response(process.stderr).text();
+
+  let timedOut = false;
+  let rejectTimeout: (error: PrimeTimeoutError) => void = () => {};
+  const timeout = new Promise<never>((_resolve, reject) => {
+    rejectTimeout = reject;
+  });
+  const cancelTimeout = (options.scheduleTimeout ?? scheduleTimeout)(() => {
+    timedOut = true;
+    process.kill("SIGKILL");
+    rejectTimeout(new PrimeTimeoutError(timeoutMs));
+  }, timeoutMs);
+
+  const completion = Promise.all([process.exited, stdout, stderr]).then(
+    ([exitCode, output, errorOutput]) => {
+      if (exitCode !== 0) throw new PrimeProcessError(exitCode, errorOutput);
+      return output;
+    }
+  );
+
+  try {
+    return await Promise.race([completion, timeout]);
+  } finally {
+    cancelTimeout();
+    if (timedOut) {
+      await completion.catch(() => undefined);
+    }
+  }
+}
+
+/** Load the canonical Beads workflow and persistent project memories. */
+export async function runBdPrime(
+  directory: string,
+  options: PrimeExecutionOptions = {}
+): Promise<string> {
+  return runPrimeAttempt(directory, [], options);
+}

package/src/skill-collision-policy.ts

@@ -0,0 +1,133 @@
+import { lstat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const SKILL_ROOTS = [".opencode", ".agents", ".claude"] as const;
+
+export type SkillScope = "global" | "project";
+export type ManagedSkillState = "current" | "modified" | "stale";
+export type SkillLocationState =
+  | "absent"
+  | "differently-managed"
+  | "managed-current"
+  | "managed-modified"
+  | "managed-stale"
+  | "unmanaged";
+
+export interface SkillLocation {
+  path: string;
+  root: (typeof SKILL_ROOTS)[number];
+  scope: SkillScope;
+}
+
+export interface SkillLocationInspection extends SkillLocation {
+  state: SkillLocationState;
+}
+
+export type ManagedSkillInspector = (
+  location: SkillLocation
+) => Promise<ManagedSkillState | "differently-managed" | undefined>;
+
+function isMissing(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+/** Resolve every project and global discovery location for a skill named beads. */
+export function beadsSkillLocations(
+  cwd: string,
+  worktree: string,
+  homeDirectory: string,
+  opencodeConfigDirectory = join(homeDirectory, ".config", "opencode")
+): SkillLocation[] {
+  const canonicalCwd = resolve(cwd);
+  const canonicalWorktree = resolve(worktree);
+  const fromWorktree = relative(canonicalWorktree, canonicalCwd);
+  if (fromWorktree === ".." || fromWorktree.startsWith(`..${sep}`) || isAbsolute(fromWorktree)) {
+    throw new Error(`cwd must be within worktree: ${canonicalCwd}`);
+  }
+
+  const projectDirectories: string[] = [];
+  for (let current = canonicalCwd; ; current = dirname(current)) {
+    projectDirectories.push(current);
+    if (current === canonicalWorktree) break;
+  }
+
+  const locations = [
+    ...projectDirectories.flatMap((directory) =>
+      SKILL_ROOTS.map((root) => ({
+        path: resolve(directory, root, "skills", "beads"),
+        root,
+        scope: "project" as const,
+      }))
+    ),
+    ...SKILL_ROOTS.map((root) => ({
+      path:
+        root === ".opencode"
+          ? join(opencodeConfigDirectory, "skills", "beads")
+          : join(homeDirectory, root, "skills", "beads"),
+      root,
+      scope: "global" as const,
+    })),
+  ];
+  const uniqueLocations: SkillLocation[] = [];
+  const seenPaths = new Set<string>();
+  for (const location of locations) {
+    if (seenPaths.has(location.path)) continue;
+    seenPaths.add(location.path);
+    uniqueLocations.push(location);
+  }
+  return uniqueLocations;
+}
+
+/** Inspect all discovery locations without mutating them. */
+export async function inspectBeadsSkillLocations(
+  cwd: string,
+  worktree: string,
+  homeDirectory: string,
+  inspectManaged: ManagedSkillInspector,
+  opencodeConfigDirectory = join(homeDirectory, ".config", "opencode")
+): Promise<SkillLocationInspection[]> {
+  return Promise.all(
+    beadsSkillLocations(cwd, worktree, homeDirectory, opencodeConfigDirectory).map(
+      async (location) => {
+        let stats;
+        try {
+          stats = await lstat(location.path);
+        } catch (error) {
+          if (isMissing(error)) return { ...location, state: "absent" as const };
+          return { ...location, state: "unmanaged" as const };
+        }
+
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+          return { ...location, state: "unmanaged" as const };
+        }
+
+        const managedState = await inspectManaged(location).catch(() => undefined);
+        let state: SkillLocationState = "unmanaged";
+        if (managedState === "differently-managed") {
+          state = managedState;
+        } else if (managedState) {
+          state = `managed-${managedState}`;
+        }
+        return { ...location, state };
+      }
+    )
+  );
+}
+
+/** Return every location that prevents a managed operation at the requested target. */
+export function blockingSkillCollisions(
+  inspections: ReadonlyArray<SkillLocationInspection>,
+  target: string
+): SkillLocationInspection[] {
+  const resolvedTarget = resolve(target);
+  return inspections.filter((inspection) => {
+    if (inspection.state === "absent") return false;
+    if (resolve(inspection.path) !== resolvedTarget) return true;
+    return inspection.state !== "managed-current" && inspection.state !== "managed-stale";
+  });
+}