@snarkipus/opencode-beads 0.9.4 → 1.0.0

package/src/plugin-core.ts

@@ -1,347 +0,0 @@
-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" | "synthetic">>
-  >;
-};
-
-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>;
-  onSessionDeleted(sessionID: string): void;
-  configure(config: MutablePluginConfig): Promise<void>;
-}
-
-type InjectionAudience = "primary" | "task-agent";
-const BEADS_CONTEXT_HEADER = /^<beads-context(?: audience="(primary|task-agent)")?>\n/;
-
-/** Recognize only the complete envelope emitted by this plugin. */
-export function isBeadsContextEnvelope(text: string): boolean {
-  const trimmed = text.trim();
-  return BEADS_CONTEXT_HEADER.test(trimmed) && trimmed.includes("\n</beads-context>");
-}
-
-function beadsContextAudience(text: string): InjectionAudience | undefined {
-  const audience = text.trim().match(BEADS_CONTEXT_HEADER)?.[1];
-  return audience === "primary" || audience === "task-agent" ? audience : undefined;
-}
-
-function injectionAudience(agentName: string | undefined): InjectionAudience {
-  return agentName === BEADS_TASK_AGENT ? "task-agent" : "primary";
-}
-
-/** 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 injectedAudiences = new Map<string, Set<InjectionAudience>>();
-  const injectionAttempts = new Map<string, { promise: Promise<void>; cancelled: boolean }>();
-  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);
-    void Promise.resolve()
-      .then(() => 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 = injectionAudience(context?.agent);
-    return `<beads-context audience="${audience}">\n${output}\n</beads-context>\n\n${beadsGuidance(audience)}`;
-  }
-
-  function markInjected(sessionID: string, audience: InjectionAudience): void {
-    const audiences = injectedAudiences.get(sessionID) ?? new Set<InjectionAudience>();
-    audiences.add(audience);
-    injectedAudiences.set(sessionID, audiences);
-  }
-
-  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,
-    isActive: () => boolean
-  ): Promise<void> {
-    if (!(await shouldInject(message.agent, message.sessionID))) return;
-
-    const audience = injectionAudience(message.agent);
-    const knownAudiences = injectedAudiences.get(message.sessionID);
-    if (knownAudiences?.has(audience)) return;
-
-    // On plugin reload there is no local audience state, so consult persisted envelopes.
-    if (!knownAudiences) {
-      try {
-        const existing = await runtime.getMessages(directory, message.sessionID);
-        const hasBeadsContext = existing?.some(
-          (item) =>
-            (item.info.system !== undefined &&
-              beadsContextAudience(item.info.system) === audience) ||
-            item.parts?.some(
-              (part) =>
-                part.type === "text" &&
-                part.synthetic === true &&
-                part.text !== undefined &&
-                beadsContextAudience(part.text) === audience
-            )
-        );
-        if (hasBeadsContext) {
-          if (isActive()) markInjected(message.sessionID, audience);
-          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);
-      if (isActive()) markInjected(message.sessionID, audience);
-    } catch {
-      await diagnoseSession("prompt_failed", message.sessionID);
-    }
-  }
-
-  return {
-    async onMessage(message, sink) {
-      const audience = injectionAudience(message.agent);
-      if (injectedAudiences.get(message.sessionID)?.has(audience)) return;
-
-      const attemptKey = `${message.sessionID}\0${audience}`;
-      const pending = injectionAttempts.get(attemptKey);
-      if (pending) return pending.promise;
-
-      const attempt = { promise: Promise.resolve(), cancelled: false };
-      attempt.promise = performInitialInjection(message, sink, () => !attempt.cancelled);
-      injectionAttempts.set(attemptKey, attempt);
-      try {
-        await attempt.promise;
-      } finally {
-        if (injectionAttempts.get(attemptKey) === attempt) {
-          injectionAttempts.delete(attemptKey);
-        }
-      }
-    },
-
-    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);
-      }
-    },
-
-    onSessionDeleted(sessionID) {
-      injectedAudiences.delete(sessionID);
-      for (const [key, attempt] of injectionAttempts) {
-        if (key.startsWith(`${sessionID}\0`)) {
-          attempt.cancelled = true;
-          injectionAttempts.delete(key);
-        }
-      }
-      for (const key of diagnosticTimes.keys()) {
-        if (key.endsWith(`:${sessionID}`)) diagnosticTimes.delete(key);
-      }
-    },
-
-    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-hooks.ts

@@ -1,56 +0,0 @@
-import type { Hooks } from "@opencode-ai/plugin";
-import type { Part } from "@opencode-ai/sdk";
-import {
-  createBeadsController,
-  isBeadsContextEnvelope,
-  type PluginRuntime,
-} from "./plugin-core";
-
-/** 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 &&
-      isBeadsContextEnvelope(part.text)
-  );
-}
-
-/** Build OpenCode hooks around an explicit runtime boundary. */
-export async function createBeadsHooks(
-  runtime: PluginRuntime,
-  projectDirectory: string
-): Promise<Hooks> {
-  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);
-      } else if (event.type === "session.deleted") {
-        controller.onSessionDeleted(event.properties.info.id);
-      }
-    },
-
-    config: async (config) => {
-      await controller.configure(config);
-    },
-  };
-}

package/src/vendor-adaptations.ts

@@ -1,146 +0,0 @@
-interface Replacement {
-  from: string;
-  to: string;
-}
-
-const replacements: Readonly<Record<string, readonly Replacement[]>> = {
-  "agents/task-agent.md": [
-    { from: "Use the `ready` MCP tool to get unblocked tasks", to: "Run `bd ready --json` via bash to get unblocked tasks" },
-    { from: "Use the `show` tool to get full task details", to: "Run `bd show <id> --json` via bash to get full task details" },
-    { from: "Use the `claim` tool for atomic start-work semantics", to: "Run `bd update <id> --claim --json` via bash for atomic start-work semantics" },
-    { from: "Use `create` tool to file new issues", to: "Run `bd create \"<title>\" ... --json` via bash to file new issues" },
-    { from: "Use `dep` tool with `discovered-from` to link them", to: "Run `bd dep add <new-id> <current-id> --type discovered-from --json` via bash to link them" },
-    { from: "Use `close` tool with a clear completion message", to: "Run `bd close <id> --reason \"<message>\" --json` via bash" },
-    { from: "Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done", to: "Always claim with `bd update <id> --claim --json` before working and close when done" },
-    { from: "If blocked, use `update` to set status to `blocked` and explain why", to: "If blocked, run `bd update <id> --status blocked --json` and explain why" },
-    {
-      from: `# Available Tools
-
-Via beads MCP server:
-- \`ready\` - Find unblocked tasks
-- \`show\` - Get task details
-- \`claim\` - Atomically claim task for work
-- \`update\` - Update task status/fields
-- \`create\` - Create new issues
-- \`dep\` - Manage dependencies
-- \`close\` - Complete tasks
-- \`blocked\` - Check blocked issues
-- \`stats\` - View project stats`,
-      to: `# Available Commands
-
-Run the \`bd\` CLI via bash. Use \`--json\` when structured output improves reliability:
-- \`bd ready --json\` - Find unblocked tasks
-- \`bd show <id> --json\` - Get task details
-- \`bd update <id> --claim --json\` - Atomically claim task for work
-- \`bd create ... --json\` - Create new issues
-- \`bd dep ... --json\` - Manage dependencies
-- \`bd close <id> --reason \"...\" --json\` - Complete tasks
-- \`bd blocked --json\` - Check blocked issues
-- \`bd stats --json\` - View project stats`,
-    },
-  ],
-  "commands/close.md": [
-    { from: "Use the beads MCP `close` tool to close the issue.", to: "Run `bd close <id> --reason \"<reason>\" --json` via bash to close the issue." },
-    { from: "(use `ready` tool)", to: "(run `bd ready --json`)" },
-    { from: "(use `create` tool with `discovered-from` link)", to: "(run `bd create ... --deps discovered-from:<id> --json`)" },
-  ],
-  "commands/create.md": [
-    { from: "Use the beads MCP `create` tool to create the issue.", to: "Run `bd create \"<title>\" --type <type> --priority <priority> --description \"<description>\" --json` via bash." },
-  ],
-  "commands/init.md": [
-    { from: "Use the beads MCP `init` tool with the prefix parameter (if provided) to set up a new beads database.", to: "Run `bd init [--prefix <prefix>]` via bash to set up a new beads database." },
-    { from: "show project stats using the `stats` tool", to: "show project stats by running `bd stats --json`" },
-  ],
-  "commands/ready.md": [
-    { from: "Use the beads MCP server to find tasks that are ready to work on (no blocking dependencies).", to: "Run `bd ready --json` via bash to find tasks that are ready to work on (no blocking dependencies)." },
-    { from: "Call the `ready` tool to get a list of unblocked issues.", to: "Use the command output to get a list of unblocked issues." },
-    { from: "use the `claim` tool to start work atomically", to: "run `bd update <id> --claim --json` via bash to start work atomically" },
-    { from: "checking `blocked` issues or creating a new issue with the `create` tool", to: "running `bd blocked --json` or creating a new issue with `bd create ... --json`" },
-  ],
-  "commands/search.md": [
-    { from: "when accessed via MCP", to: "when using structured CLI output" },
-    { from: "You're using an LLM/MCP and want to minimize context usage", to: "You're using an LLM and want to minimize context usage" },
-  ],
-  "commands/show.md": [
-    { from: "Use the beads MCP `show` tool to retrieve issue details", to: "Run `bd show <id> --json` via bash to retrieve issue details" },
-  ],
-  "commands/stats.md": [
-    { from: "Use the beads MCP `stats` tool to retrieve project metrics", to: "Run `bd stats --json` via bash to retrieve project metrics" },
-  ],
-  "commands/update.md": [
-    { from: "Use the beads MCP `update` tool to apply the changes.", to: "Run the appropriate `bd update <id> ... --json` command via bash." },
-  ],
-  "commands/version.md": [
-    {
-      from: `Check the installed versions of beads components and verify compatibility.
-
-**Note:** The MCP server automatically checks bd CLI version >= 0.9.0 on startup. This command provides detailed version info and update instructions.
-
-Use the beads MCP tools to:
-1. Run \`bd version\` via bash to get the CLI version
-2. Check the plugin version (0.9.2)
-3. Compare versions and report any mismatches
-
-Display:
-- bd CLI version (from \`bd version\`)
-- Plugin version (0.9.2)
-- MCP server version (0.9.2)
-- MCP server status (from \`stats\` tool or connection test)
-- Compatibility status (✓ compatible or ⚠️ update needed)
-
-If versions are mismatched, provide instructions:
-- Update bd CLI: \`curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash\`
-- Update plugin: \`/plugin update beads\`
-- Restart Claude Code after updating
-
-Suggest checking for updates if the user is on an older version.`,
-      to: `Check the installed Beads and OpenCode versions against this plugin's documented compatibility range.
-
-Run \`bd version\` and \`opencode --version\` via bash. Report both versions and point to the opencode-beads README compatibility table. Do not infer compatibility from unrelated integration or upstream plugin versions.
-
-If \`bd\` is outdated, link to the current Beads installation guide. If opencode-beads is pinned in the OpenCode configuration, explain that updating requires changing the pinned package version and restarting OpenCode.`,
-    },
-  ],
-  "commands/workflow.md": [
-    { from: "Use `/beads:ready` or the `ready` MCP tool", to: "Use `/beads:ready` or run `bd ready --json`" },
-    { from: "- Via MCP tool: `claim` with `issue_id: \"<id>\"`", to: "- Via CLI: `bd update <id> --claim --json`" },
-    { from: "- Create issues: `/beads:create` or `create` MCP tool", to: "- Create issues: `/beads:create` or `bd create ... --json`" },
-    { from: "- Link them: Use `dep` MCP tool with `type: \"discovered-from\"`", to: "- Link them: `bd dep add <new-id> <current-id> --type discovered-from --json`" },
-    { from: "- Via MCP tool: `close` with reason", to: "- Via CLI: `bd close <id> --reason \"<summary>\" --json`" },
-    {
-      from: `## MCP Tools Available
-Use these via the beads MCP server:
-- \`ready\`, \`list\`, \`show\`, \`create\`, \`claim\`, \`update\`, \`close\`
-- \`dep\` (manage dependencies), \`blocked\`, \`stats\`
-- \`init\` (initialize bd in a project)`,
-      to: `## CLI Access
-Run the \`bd\` CLI via bash for operations not covered by a slash command. Use \`bd <command> --help\` for current syntax and \`--json\` when structured output improves reliability.`,
-    },
-  ],
-};
-
-const unsupportedPattern = /\bmcp\b|claude code|\/plugin update beads/i;
-
-/** Paths with explicit OpenCode adaptations, used as the expected inventory. */
-export const adaptedVendorPaths = Object.freeze(Object.keys(replacements).sort());
-
-/** Apply strict, reviewable OpenCode adaptations to one upstream prompt body. */
-export function adaptVendorPrompt(relativePath: string, content: string): string {
-  let adapted = content;
-
-  for (const replacement of replacements[relativePath] ?? []) {
-    const first = adapted.indexOf(replacement.from);
-    const last = adapted.lastIndexOf(replacement.from);
-    if (first === -1 || first !== last) {
-      throw new Error(`Expected exactly one adaptation source in ${relativePath}: ${replacement.from}`);
-    }
-    adapted = adapted.replace(replacement.from, replacement.to);
-  }
-
-  const unsupported = adapted.match(unsupportedPattern)?.[0];
-  if (unsupported) {
-    throw new Error(`Unsupported ${unsupported} instruction remains in ${relativePath}`);
-  }
-
-  return adapted;
-}