@snarkipus/opencode-beads 0.9.1 → 0.9.3

package/src/plugin.ts

@@ -1,150 +1,12 @@
 /** 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");
-    },
-  };
-}
+import type { Plugin } from "@opencode-ai/plugin";
+import { resolveProjectDirectory } from "./plugin-core";
+import { createBeadsHooks } from "./plugin-hooks";
+import { createOpenCodeRuntime } from "./opencode-runtime";
 
 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);
-    },
-  };
+  return createBeadsHooks(runtime, projectDirectory);
 };

package/src/prime.ts

@@ -1,4 +1,7 @@
+import { kill as killProcess } from "node:process";
+
 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) {
@@ -15,25 +18,55 @@ export class PrimeProcessError extends Error {
 }
 
 export interface PrimeProcess {
+  pid: number;
   stdout: ReadableStream<Uint8Array>;
   stderr: ReadableStream<Uint8Array>;
   exited: Promise<number>;
   kill(signal?: NodeJS.Signals): void;
+  killTree?(signal?: NodeJS.Signals): void;
 }
 
 export interface PrimeExecutionOptions {
   timeoutMs?: number;
+  drainTimeoutMs?: number;
   spawn?: (directory: string, args: readonly string[]) => PrimeProcess;
   scheduleTimeout?: (callback: () => void, delayMs: number) => () => void;
+  scheduleDrainTimeout?: (callback: () => void, delayMs: number) => () => void;
 }
 
 function spawnPrime(directory: string, args: readonly string[]): PrimeProcess {
-  return Bun.spawn(["bd", "prime", ...args], {
+  const child = Bun.spawn(["bd", "prime", ...args], {
     cwd: directory,
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
+    detached: true,
   });
+  let processGroupID: number | undefined;
+  if (process.platform !== "win32") {
+    const group = Bun.spawnSync(["ps", "-o", "pgid=", "-p", String(child.pid)], {
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: 100,
+    });
+    const parsed = Number.parseInt(new TextDecoder().decode(group.stdout).trim(), 10);
+    if (group.exitCode === 0 && parsed === child.pid && parsed > 1) processGroupID = parsed;
+  }
+
+  return {
+    pid: child.pid,
+    stdout: child.stdout,
+    stderr: child.stderr,
+    exited: child.exited,
+    kill: (signal) => child.kill(signal),
+    killTree: (signal) => {
+      if (processGroupID !== undefined) {
+        killProcess(-processGroupID, signal);
+      } else {
+        child.kill(signal);
+      }
+    },
+  };
 }
 
 function scheduleTimeout(callback: () => void, delayMs: number): () => void {
@@ -41,15 +74,42 @@ function scheduleTimeout(callback: () => void, delayMs: number): () => void {
   return () => clearTimeout(timer);
 }
 
+function terminateProcessTree(child: PrimeProcess): void {
+  try {
+    (child.killTree ?? child.kill)("SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Timeout remains authoritative if the process exited concurrently.
+    }
+  }
+}
+
+async function drainAfterKill(
+  completion: Promise<unknown>,
+  timeoutMs: number,
+  scheduler: (callback: () => void, delayMs: number) => () => void
+): Promise<void> {
+  await new Promise<void>((resolve) => {
+    const cancelTimeout = scheduler(resolve, timeoutMs);
+    void completion.finally(() => {
+      cancelTimeout();
+      resolve();
+    });
+  });
+}
+
 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();
+  const drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_PRIME_DRAIN_TIMEOUT_MS;
+  const child = (options.spawn ?? spawnPrime)(directory, args);
+  const stdout = new Response(child.stdout).text();
+  const stderr = new Response(child.stderr).text();
 
   let timedOut = false;
   let rejectTimeout: (error: PrimeTimeoutError) => void = () => {};
@@ -58,11 +118,11 @@ async function runPrimeAttempt(
   });
   const cancelTimeout = (options.scheduleTimeout ?? scheduleTimeout)(() => {
     timedOut = true;
-    process.kill("SIGKILL");
+    terminateProcessTree(child);
     rejectTimeout(new PrimeTimeoutError(timeoutMs));
   }, timeoutMs);
 
-  const completion = Promise.all([process.exited, stdout, stderr]).then(
+  const completion = Promise.all([child.exited, stdout, stderr]).then(
     ([exitCode, output, errorOutput]) => {
       if (exitCode !== 0) throw new PrimeProcessError(exitCode, errorOutput);
       return output;
@@ -74,7 +134,11 @@ async function runPrimeAttempt(
   } finally {
     cancelTimeout();
     if (timedOut) {
-      await completion.catch(() => undefined);
+      await drainAfterKill(
+        completion.catch(() => undefined),
+        drainTimeoutMs,
+        options.scheduleDrainTimeout ?? scheduleTimeout
+      );
     }
   }
 }

package/vendor/commands/audit.md

@@ -1,6 +1,6 @@
 ---
 description: Log and label agent interactions (append-only JSONL)
-argument-hint: record|label
+argument-hint: "record|label"
 ---
 
 Append-only audit logging for agent interactions (prompts, responses, tool calls) in `.beads/interactions.jsonl`.
@@ -25,4 +25,3 @@ Each line is one event. Labeling is done by appending a new `"label"` event refe
 - Audit entries are **append-only** (no in-place edits).
 - `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.
 
-

package/vendor/commands/blocked.md

@@ -1,6 +1,6 @@
 ---
 description: Show blocked issues
-argument-hint: []
+argument-hint: ""
 ---
 
 Show all issues that are blocked by dependencies.

package/vendor/commands/close.md

@@ -1,6 +1,6 @@
 ---
 description: Close a completed issue
-argument-hint: [issue-id] [reason]
+argument-hint: "[issue-id] [reason]"
 ---
 
 Close a beads issue that's been completed.

package/vendor/commands/comments.md

@@ -1,6 +1,6 @@
 ---
 description: View or manage comments on an issue
-argument-hint: [issue-id]
+argument-hint: "[issue-id]"
 ---
 
 View or add comments to a beads issue.

package/vendor/commands/compact.md

@@ -1,6 +1,6 @@
 ---
 description: Compact old closed issues using semantic summarization
-argument-hint: [--all] [--id issue-id] [--dry-run]
+argument-hint: "[--all] [--id issue-id] [--dry-run]"
 ---
 
 Reduce database size by summarizing closed issues no longer actively referenced.

package/vendor/commands/create.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new issue interactively
-argument-hint: [title] [type] [priority]
+argument-hint: "[title] [type] [priority]"
 ---
 
 Create a new beads issue. If arguments are provided:

package/vendor/commands/decision.md

@@ -1,6 +1,6 @@
 ---
 description: Record, list, and manage project decisions with rationale tracking
-argument-hint: record|list|show|supersede
+argument-hint: "record|list|show|supersede"
 ---
 
 Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.
@@ -9,7 +9,7 @@ Decisions use `--type decision`. The description field holds the structured deci
 
 ## Record a Decision
 
-When the user wants to record a decision (or you invoke `bd decision record`):
+When the user wants to record a decision (i.e. the `record` action of this command):
 
 1. Gather the following (ask if not provided):
    - **Title**: Short summary of what was decided (required)

package/vendor/commands/delete.md

@@ -1,6 +1,6 @@
 ---
 description: Delete issues and clean up references
-argument-hint: [issue-ids...] [--force]
+argument-hint: "[issue-ids...] [--force]"
 ---
 
 Delete one or more issues and clean up all references.

package/vendor/commands/dep.md

@@ -1,6 +1,6 @@
 ---
 description: Manage dependencies between issues
-argument-hint: [command] [from-id] [to-id]
+argument-hint: "[command] [from-id] [to-id]"
 ---
 
 Manage dependencies between beads issues.

package/vendor/commands/epic.md

@@ -1,6 +1,6 @@
 ---
 description: Epic management commands
-argument-hint: [command]
+argument-hint: "[command]"
 ---
 
 Manage epics (large features composed of multiple issues).
@@ -21,6 +21,9 @@ Manage epics (large features composed of multiple issues).
 1. Create epic: `bd create "Large Feature" -t epic -p 1`
 2. Link subtasks: `bd dep add bd-20 bd-10 --type parent-child` (task bd-20 is child of epic bd-10)
    - Or at creation: `bd create "Subtask title" -t task --parent bd-10`
+   - Children inherit parent labels by default. If the epic uses size/effort
+     labels and children should have their own, add `--no-inherit-labels`
+     (GH#4562).
 3. Track progress: `bd epic status`
 4. Auto-close when done: `bd epic close-eligible`
 

package/vendor/commands/export.md

@@ -1,6 +1,6 @@
 ---
 description: Export issues to JSONL format
-argument-hint: [-o output-file]
+argument-hint: "[-o output-file]"
 ---
 
 Export all issues to JSON Lines format (one JSON object per line).
@@ -9,7 +9,7 @@ Export all issues to JSON Lines format (one JSON object per line).
 
 - **To stdout**: `bd export`
 - **To file**: `bd export -o issues.jsonl`
-- **Filter by status**: `bd export --status open`
+- **Include all records**: `bd export --all -o full.jsonl`
 
 Issues are sorted by ID for consistent diffs, making git diffs readable.
 

package/vendor/commands/import.md

@@ -1,18 +1,84 @@
 ---
-description: Import issues from JSONL format (removed)
-argument-hint: (removed)
+description: Import issues and memories from JSONL
+argument-hint: "[file|-] [--input file] [--dry-run] [--dedup] [--allow-stale]"
 ---
 
-`bd import` has been **removed**.
+`bd import` imports newline-delimited JSON into an existing Beads database.
+Issues with new IDs are created and existing IDs use guarded upsert semantics.
+The command is not supported in proxied-server mode.
 
-## Migration
-
-If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
+## Usage
 
 ```bash
-bd init <prefix> --from-jsonl issues.jsonl
+bd import                         # Read .beads/<import.path>
+bd import backup.jsonl            # Read a specific file
+bd import --input backup.jsonl    # Same as -i backup.jsonl
+bd import -                       # Read JSONL from stdin
+bd export --include-memories | bd import - # Round-trip issues and memories
+bd import --dry-run backup.jsonl  # Parse and report without writing
+bd import --json backup.jsonl     # Return a structured result
 ```
 
-## Note
+With no file argument, the source is the `import.path` file under `.beads/`;
+`import.path` defaults to `issues.jsonl`. Use either a positional file or
+`--input`/`-i`, not both. The special path `-` reads stdin. With `--global` and
+no file, the source is `global-issues.jsonl` in the active Beads directory.
+
+Each non-empty line must be a JSON object. Issue records accept the schema
+emitted by `bd export`; `title` is the only required issue field. Records with
+`"_type":"memory"` and non-empty `key` and `value` fields are imported as
+persistent memories. Optional export header records are ignored, and tombstone
+rows are skipped. `bd export` omits memories by default; add
+`--include-memories` or `--all` when they should be carried into an import.
+
+## Merge and Safety Semantics
+
+For records that supply `updated_at`, an incoming row rewrites an existing
+issue only when its timestamp is strictly newer. Older records are skipped
+wholesale, including their labels, comments, and dependencies. When timestamps
+are equal, the local issue row wins, while those auxiliary records still merge.
+The stale check is repeated inside the upsert so a concurrent newer local update
+is not overwritten.
+
+If `updated_at` is omitted, the importer fills it with the current time during
+the write. A record naming an existing ID can therefore overwrite local state;
+include the exported timestamp when stale protection matters.
+
+Use `--allow-stale` only when deliberately restoring an older snapshot: it
+disables that guard and can overwrite newer local issue state. Imports are
+upserts, and labels, comments, and dependencies are deduplicated. Re-running
+canonical export data or other input with stable issue IDs and preserved
+`updated_at` values is safe and converges. Without a preserved timestamp, each
+run can appear newer and rewrite the row. An issue record without an ID is
+assigned one; re-importing it can create another issue instead of targeting the
+first.
+
+Large issue imports use bounded SQL transaction chunks. If one fails, the
+command exits nonzero and keeps the already committed prefix in the Dolt working
+set; no final import-summary Dolt commit is created. Re-run stable-ID input to
+resume only when its `updated_at` values are also preserved.
+
+After a successful non-dry import with accepted issue or memory records, the
+command calls `store.Commit` with an import summary regardless of the
+`dolt.auto-commit` policy. That commit can include unrelated pending working-set
+changes; in direct server mode, config (including memories) is excluded from
+this commit. When commit isolation matters, run `bd doctor` before importing and
+proceed only when its Dolt Status check reports a clean working set.
+
+The database must already exist; initialize or bootstrap it before importing.
+Use `--dry-run` to parse the input, apply optional title deduplication, and
+report issue and memory counts without writing. It does not run write-time field
+validation or predict stale skips and updates.
+
+## Flags
 
-Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.
+- `--input`, `-i <file>`: read a specific file instead of a positional path.
+- `--dry-run`: report parsed record counts without writing.
+- `--dedup`: skip an input issue whose title exactly matches, ignoring case, an
+  existing non-closed issue. Input rows are not compared with one another; if
+  the existing-issue search fails, title filtering is skipped.
+- `--allow-stale`: import older rows too, allowing newer local state to be
+  overwritten.
+- `--json`: use global JSON-output mode for structured counts and IDs. The
+  `created` count is accepted issue rows, including existing rows, not only new
+  inserts.

package/vendor/commands/init.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize beads in the current project
-argument-hint: [prefix]
+argument-hint: "[prefix]"
 ---
 
 Initialize beads issue tracking in the current directory.

package/vendor/commands/label.md

@@ -1,6 +1,6 @@
 ---
 description: Manage issue labels
-argument-hint: [command] [issue-id] [label]
+argument-hint: "[command] [issue-id] [label]"
 ---
 
 Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type).

package/vendor/commands/list.md

@@ -1,6 +1,6 @@
 ---
 description: List issues with optional filters
-argument-hint: [--status] [--priority] [--type] [--assignee] [--label]
+argument-hint: "[--status] [--priority] [--type] [--assignee] [--label]"
 ---
 
 List beads issues with optional filtering.

package/vendor/commands/quickstart.md

@@ -1,9 +1,9 @@
 ---
 description: Quick start guide for bd workflows (deprecated)
-argument-hint: []
+argument-hint: ""
 ---
 
-**Note:** The `bd quickstart` command is deprecated. See the [Quick Start](https://gastownhall.github.io/beads/getting-started/quickstart) on the documentation site, or the repo pointer [docs/QUICKSTART.md](../docs/QUICKSTART.md).
+**Note:** The `bd quickstart` command is deprecated. See the [Quick Start](https://beads.gascity.com/getting-started/quickstart) on the documentation site, or the in-repo source [docs/getting-started/quickstart.md](https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md).
 
 The quickstart documentation covers:
 - Getting started with bd

package/vendor/commands/rename-prefix.md

@@ -1,6 +1,6 @@
 ---
 description: Rename the issue prefix for all issues
-argument-hint: <new-prefix> [--dry-run]
+argument-hint: "<new-prefix> [--dry-run]"
 ---
 
 Rename the issue prefix for all issues in the database.
@@ -9,7 +9,6 @@ Updates all issue IDs and all text references across all fields.
 
 ## Prefix Rules
 
-- Max length: 8 characters
 - Allowed: lowercase letters, numbers, hyphens
 - Must start with a letter
 - Must end with a hyphen (e.g., 'kw-', 'work-')

package/vendor/commands/reopen.md

@@ -1,6 +1,6 @@
 ---
 description: Reopen closed issues
-argument-hint: [issue-ids...] [--reason]
+argument-hint: "[issue-ids...] [--reason]"
 ---
 
 Reopen one or more closed issues.

package/vendor/commands/restore.md

@@ -1,6 +1,6 @@
 ---
 description: Restore full history of compacted issue from git
-argument-hint: <issue-id>
+argument-hint: "<issue-id>"
 ---
 
 Restore full history of a compacted issue from git version control.

package/vendor/commands/search.md

@@ -1,6 +1,6 @@
 ---
 description: Search issues by text query
-argument-hint: <query> [--status] [--label] [--assignee]
+argument-hint: "<query> [--status] [--label] [--assignee]"
 ---
 
 Search issues across title, description, and ID with a simple text query.

package/vendor/commands/show.md

@@ -1,6 +1,6 @@
 ---
 description: Show detailed information about an issue
-argument-hint: [issue-id]
+argument-hint: "[issue-id]"
 ---
 
 Display detailed information about a beads issue.