@polderlabs/bizar-plugin 0.5.4

package/src/tools/bg-collect.ts

@@ -0,0 +1,104 @@
+/**
+ * bg-collect.ts
+ *
+ * `bizar_collect` tool (v0.4.2 spec §7.1, §4.4).
+ *
+ * Odin-only — only Odin may collect. Blocks until the instance reaches a
+ * terminal state or `timeoutMs` elapses. On timeout, returns
+ * `status: "running"` with the last known `resultPreview`.
+ *
+ * Returns:
+ *   `{ instanceId, status, result, toolCallCount, durationMs, error? }`
+ *
+ * The `result` field is the concatenated text of all assistant messages
+ * (TextPart only). If the instance ended with a threshold-12 loop-guard
+ * error, the marker `[loop guard: 12 identical calls to <tool>]` is
+ * prepended (MEDIUM-30).
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+
+import type { InstanceManager } from "../background.js";
+import type { Logger } from "../logger.js";
+
+const TIMEOUT_MIN_MS = 1000;
+const TIMEOUT_MAX_MS = 1_800_000;
+const TIMEOUT_DEFAULT_MS = 60_000;
+
+export interface BgCollectDeps {
+  instanceManager: InstanceManager;
+  logger: Logger;
+}
+
+/**
+ * Build the `bizar_collect` tool.
+ */
+export function createBgCollectTool(deps: BgCollectDeps) {
+  return tool({
+    description:
+      "Wait for a background instance to complete and return its result. " +
+      "Only Odin may collect. Blocks until the instance reaches a terminal state or the timeout fires.",
+    args: {
+      instanceId: z
+        .string()
+        .min(1)
+        .describe("Instance id returned by bizar_spawn_background."),
+      timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Collect-time timeout in ms (1s..30min, default 60s)."),
+    },
+    execute: async (rawArgs, ctx) => {
+      // Odin-only (§6.3).
+      if (ctx.agent !== "odin") {
+        return {
+          output: JSON.stringify({
+            error:
+              "Only Odin can collect background agent results. Use bizar_status to inspect or ask Odin to collect.",
+          }),
+        };
+      }
+      const args = rawArgs as { instanceId: string; timeoutMs?: number };
+
+      // Clamp timeoutMs (MEDIUM-33 / §7.3).
+      const requested = args.timeoutMs ?? TIMEOUT_DEFAULT_MS;
+      if (requested < TIMEOUT_MIN_MS || requested > TIMEOUT_MAX_MS) {
+        return {
+          output: JSON.stringify({
+            error: `timeoutMs must be between ${TIMEOUT_MIN_MS} (1s) and ${TIMEOUT_MAX_MS} (30min). Got ${requested}.`,
+          }),
+        };
+      }
+      const timeoutMs = requested;
+
+      try {
+        const result = await deps.instanceManager.collect(args.instanceId, timeoutMs);
+        return {
+          output: JSON.stringify({
+            instanceId: args.instanceId,
+            status: result.status,
+            result: result.result,
+            toolCallCount: result.toolCallCount,
+            durationMs: result.durationMs,
+            ...(result.error !== undefined ? { error: result.error } : {}),
+          }),
+        };
+      } catch (err: unknown) {
+        deps.logger.warn(
+          `bizar: collect(${args.instanceId}) failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        return {
+          output: JSON.stringify({
+            error: `collect failed: ${err instanceof Error ? err.message : String(err)}`,
+            instanceId: args.instanceId,
+          }),
+        };
+      }
+    },
+  });
+}

package/src/tools/bg-get-comments.ts

@@ -0,0 +1,239 @@
+/**
+ * bg-get-comments.ts
+ *
+ * `bizar_get_plan_comments` tool — read-only access to the comments on a
+ * Bizar Plan canvas.
+ *
+ * Background agents (Thor, Tyr, Mimir, etc.) call this to pick up user
+ * feedback pinned to specific elements they are working on. The tool
+ * reads `plans/<slug>/plan.json` from disk and returns the comments
+ * array, optionally filtered to a specific element.
+ *
+ * The schema on disk is the v2 canvas shape:
+ *
+ *   {
+ *     schemaVersion: 2,
+ *     title: "...",
+ *     elements: [...],
+ *     connections: [...],
+ *     comments: [
+ *       {
+ *         id: "c_xxx",
+ *         x: 100, y: 200,
+ *         elementId: "el_yyy" | null,
+ *         author: "DrB0rk",
+ *         text: "Make this button bigger",
+ *         created: "2026-06-18T...",
+ *         thread: [
+ *           { id: "r_xxx", author: "ai", text: "Done", created: "..." }
+ *         ]
+ *       }
+ *     ],
+ *     viewport: { x, y, zoom }
+ *   }
+ *
+ * If the file does not exist, has an older shape, or the elementId filter
+ * yields zero results, the tool returns an empty array — never an error.
+ * This matches the principle that a missing plan is not the agent's
+ * problem; it just means "no feedback on file".
+ *
+ * Returns (on success):
+ *   `Array<{ id, x, y, elementId, author, text, created, thread: [...] }>`
+ *
+ * Returns (on error):
+ *   `{ error: string, planSlug: string }`
+ *
+ * Read-only — available to ALL agents (Vör, Frigg, Mimir, Odin, Thor,
+ * Tyr, Heimdall, etc.). The function is pure: no side effects, no
+ * network calls, no process spawning.
+ *
+ * The "worktree" passed in via deps is the directory the plugin was
+ * loaded for; `plans/` lives at the root of the project.
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Logger } from "../logger.js";
+
+export interface BgGetCommentsDeps {
+  /** The project's working directory (e.g. /home/user/proj). `plans/` is here. */
+  worktree: string;
+  logger: Logger;
+}
+
+// --- On-disk shapes ---------------------------------------------------------
+
+/** A single thread reply on a canvas comment. */
+interface PlanCommentReply {
+  id?: string;
+  author?: string;
+  text?: string;
+  created?: string;
+}
+
+/** A single canvas comment as stored in plan.json. */
+interface PlanComment {
+  id: string;
+  x?: number;
+  y?: number;
+  elementId?: string | null;
+  author?: string;
+  text?: string;
+  created?: string;
+  thread?: PlanCommentReply[];
+}
+
+/** The minimum subset of plan.json the tool reads. */
+interface PlanCanvasFile {
+  schemaVersion?: number;
+  title?: string;
+  elements?: Array<{ id?: string; title?: string }>;
+  connections?: unknown[];
+  comments?: PlanComment[];
+  viewport?: unknown;
+}
+
+// --- Validation helpers -----------------------------------------------------
+
+/** Same slug rule used by `cli/plan.mjs`. Lowercase, hyphens, 1–64 chars. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+function isValidSlug(s: string): boolean {
+  return SLUG_REGEX.test(s);
+}
+
+// --- Core read function (extracted for testability) --------------------------
+
+/**
+ * Read the plan.json from disk, parse it, and return the filtered comments.
+ *
+ * Exported (named) so the test file can drive the same code path the
+ * real tool uses, without needing a tool framework.
+ *
+ * Errors are swallowed and returned as a result — a missing plan should
+ * never break an agent session. The only fatal error is "invalid slug",
+ * which is a programming error rather than a runtime condition.
+ */
+export function readPlanComments(
+  worktree: string,
+  planSlug: string,
+  elementId: string | undefined,
+): { ok: true; comments: PlanComment[]; planSlug: string } | { ok: false; error: string; planSlug: string } {
+  if (!isValidSlug(planSlug)) {
+    return { ok: false, error: `Invalid planSlug: "${planSlug}". Must match ^[a-z0-9][a-z0-9-]{0,63}$.`, planSlug };
+  }
+
+  const planPath = join(worktree, "plans", planSlug, "plan.json");
+  if (!existsSync(planPath)) {
+    // No plan.json — this is a v1 plan, or the plan was never created.
+    // We return an empty array; the agent should treat it as "no feedback".
+    return { ok: true, comments: [], planSlug };
+  }
+
+  let parsed: PlanCanvasFile;
+  try {
+    const raw = readFileSync(planPath, "utf-8");
+    parsed = JSON.parse(raw) as PlanCanvasFile;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `Failed to read plan.json: ${msg}`, planSlug };
+  }
+
+  // Guard against the JSON being null or a non-object (e.g. "null" or "[]"
+  // at the top level). The v2 schema requires an object; anything else is
+  // a programmer error rather than a runtime condition.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      ok: false,
+      error: `plan.json is not a v2 canvas object (got ${Array.isArray(parsed) ? "array" : typeof parsed})`,
+      planSlug,
+    };
+  }
+
+  const all = Array.isArray(parsed.comments) ? parsed.comments : [];
+
+  // Filter by elementId if requested. Note: we keep elementId === null
+  // (canvas-pinned, no element) separate from elementId === undefined
+  // (malformed comment). The latter is filtered out as "not a comment".
+  let filtered: PlanComment[];
+  if (elementId === undefined) {
+    filtered = all.filter((c) => c && typeof c === "object" && typeof c.id === "string");
+  } else if (elementId === "nil" || elementId === "null") {
+    // explicit "canvas-pinned only"
+    filtered = all.filter(
+      (c) => c && typeof c === "object" && typeof c.id === "string" && c.elementId == null,
+    );
+  } else if (elementId === "") {
+    // empty string means "all comments" (used by the v2 viewer's
+    // "show me everything" GET with ?elementId=)
+    filtered = all.filter((c) => c && typeof c === "object" && typeof c.id === "string");
+  } else {
+    filtered = all.filter(
+      (c) => c && typeof c === "object" && typeof c.id === "string" && c.elementId === elementId,
+    );
+  }
+
+  // Sort by created time (oldest first) so the agent sees a chronological
+  // thread. Missing/empty timestamps are pushed to the end.
+  filtered.sort((a, b) => {
+    const at = String(a.created || "");
+    const bt = String(b.created || "");
+    if (at === bt) return 0;
+    if (at === "") return 1;
+    if (bt === "") return -1;
+    return at.localeCompare(bt);
+  });
+
+  return { ok: true, comments: filtered, planSlug };
+}
+
+// --- Tool factory -----------------------------------------------------------
+
+/**
+ * Build the `bizar_get_plan_comments` tool. The plugin wires the result
+ * into `Hooks.tool`. The `deps` closure carries the worktree and logger.
+ */
+export function createBgGetCommentsTool(deps: BgGetCommentsDeps) {
+  return tool({
+    description:
+      "Read the comments pinned to elements on a Bizar Plan canvas. " +
+      "Use this to pick up user feedback while implementing changes. " +
+      "Read-only; available to all agents. " +
+      "Returns an array of comment objects with id, x, y, elementId, " +
+      "author, text, created, and a thread of replies.",
+    args: {
+      planSlug: z
+        .string()
+        .min(1)
+        .max(64)
+        .describe(
+          "The plan's slug (lowercase, hyphens, e.g. 'my-feature'). " +
+            "Matches the directory under plans/<slug>/.",
+        ),
+      elementId: z
+        .string()
+        .optional()
+        .describe(
+          "Optional element id (e.g. 'el_abc123'). If provided, only " +
+            "comments pinned to that element are returned. Omit to " +
+            "get all comments on the plan. Pass an empty string, " +
+            "'nil', or 'null' to get comments pinned to the canvas " +
+            "(no element).",
+        ),
+    },
+    execute: async (rawArgs) => {
+      const args = rawArgs as { planSlug: string; elementId?: string };
+      const result = readPlanComments(deps.worktree, args.planSlug, args.elementId);
+      if (!result.ok) {
+        deps.logger.warn(
+          `bizar: get_plan_comments(${args.planSlug}) failed: ${result.error}`,
+        );
+        return { output: JSON.stringify({ error: result.error, planSlug: args.planSlug }) };
+      }
+      return { output: JSON.stringify(result.comments) };
+    },
+  });
+}

package/src/tools/bg-kill.ts

@@ -0,0 +1,87 @@
+/**
+ * bg-kill.ts
+ *
+ * `bizar_kill` tool (v0.4.2 spec §1.5, §7.1, HIGH-4, MEDIUM-40).
+ *
+ * Odin-only — only Odin may kill background instances.
+ *
+ * Calls `POST /session/{id}/abort` (NOT `DELETE /session/{id}`). The
+ * session record is preserved in opencode for history; the running
+ * loop is stopped.
+ *
+ * After abort, the next event for that session is `EventSessionIdle`
+ * or `EventSessionError`. The plugin's event handler updates the
+ * instance status; `bizar_kill` itself also stamps `status: "killed"`
+ * synchronously so the caller gets immediate feedback.
+ *
+ * No-op on already-terminal instances (returns the current status).
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+
+import type { InstanceManager } from "../background.js";
+import type { Logger } from "../logger.js";
+
+export interface BgKillDeps {
+  instanceManager: InstanceManager;
+  logger: Logger;
+}
+
+export function createBgKillTool(deps: BgKillDeps) {
+  return tool({
+    description:
+      "Kill a running background instance via POST /session/{id}/abort. " +
+      "Only Odin may kill. No-op on already-terminal instances.",
+    args: {
+      instanceId: z
+        .string()
+        .min(1)
+        .describe("Instance id returned by bizar_spawn_background."),
+    },
+    execute: async (rawArgs, ctx) => {
+      if (ctx.agent !== "odin") {
+        return {
+          output: JSON.stringify({
+            error:
+              "Only Odin can kill background agents. Use bizar_status to inspect or ask Odin to kill.",
+          }),
+        };
+      }
+      const args = rawArgs as { instanceId: string };
+      const inst = await deps.instanceManager.get(args.instanceId);
+      if (!inst) {
+        return {
+          output: JSON.stringify({
+            error: `instance not found`,
+            instanceId: args.instanceId,
+          }),
+        };
+      }
+      try {
+        await deps.instanceManager.kill(args.instanceId);
+        // After kill, the in-memory state should be "killed". Re-read so
+        // the caller sees the final status.
+        const after = await deps.instanceManager.get(args.instanceId);
+        return {
+          output: JSON.stringify({
+            instanceId: args.instanceId,
+            status: after?.status ?? "killed",
+          }),
+        };
+      } catch (err: unknown) {
+        deps.logger.warn(
+          `bizar: kill(${args.instanceId}) failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        return {
+          output: JSON.stringify({
+            error: `kill failed: ${err instanceof Error ? err.message : String(err)}`,
+            instanceId: args.instanceId,
+          }),
+        };
+      }
+    },
+  });
+}

package/src/tools/bg-spawn.ts

@@ -0,0 +1,263 @@
+/**
+ * bg-spawn.ts
+ *
+ * `bizar_spawn_background` tool (v0.4.2 spec §1, §6.3, §7.1).
+ *
+ * Odin-only — any other agent calling this tool receives a clear error
+ * (MEDIUM-26). The caller's `ctx.agent` is the source of truth.
+ *
+ * Args:
+ *   - `agent: string` — the agent to spawn (e.g. "mimir", "thor", "tyr").
+ *   - `prompt: string` — the user prompt; sent verbatim via
+ *     `parts: [{ type: "text", text: prompt }]`.
+ *   - `model?: string` — `"<providerID>/<modelID>"` override (LOW-34).
+ *   - `timeoutMs?: number` — collect-time timeout, clamped to [1000, 1800000].
+ *
+ * Returns on success:
+ *   `{ instanceId, sessionId, status: "pending" }`
+ *
+ * The "Track BEFORE HTTP" invariant (spec §2.2 / HIGH-21):
+ *   1. Validate inputs.
+ *   2. Generate `instanceId` and `messageID`.
+ *   3. `InstanceManager.add()` — atomic cap check + insert; map entry
+ *      exists BEFORE any HTTP call.
+ *   4. `POST /session` — returns the opencode `sessionId`.
+ *   5. `POST /session/{id}/prompt_async` — fire the prompt.
+ *   6. On either HTTP failure, mark the instance `failed` and return the
+ *      error. The map is never left in a half-state.
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+
+import type { InstanceManager } from "../background.js";
+import { generateInstanceId, generateMessageId } from "../background.js";
+import type { HttpClient, ModelOverride } from "../http-client.js";
+import type { Logger } from "../logger.js";
+
+// --- Spec §1.4 / LOW-34: model parameter parsing -------------------------
+
+/**
+ * Parse the `model?: string` argument.
+ *   - "provider/model"  → { providerID, modelID }
+ *   - "model"           → null (no slash)
+ *   - "a/b/c"           → null (multiple slashes)
+ *   - "provider/"       → null (empty half)
+ *   - "/model"          → null (empty half)
+ */
+function parseModel(raw: string): ModelOverride | null {
+  if (raw === "") return null;
+  const parts = raw.split("/");
+  if (parts.length !== 2) return null;
+  const providerID = parts[0];
+  const modelID = parts[1];
+  if (!providerID || !modelID) return null;
+  return { providerID, modelID };
+}
+
+// --- Tool factory ---------------------------------------------------------
+
+/** Spec §7.3: `timeoutMs` clamped to [1000, 1800000] (1s..30min). */
+const TIMEOUT_MIN_MS = 1000;
+const TIMEOUT_MAX_MS = 1_800_000;
+const TIMEOUT_DEFAULT_MS = 300_000;
+
+export interface BgSpawnDeps {
+  instanceManager: InstanceManager;
+  http: HttpClient;
+  worktree: string;
+  logger: Logger;
+}
+
+/**
+ * Build the `bizar_spawn_background` tool. The plugin wires the result
+ * into `Hooks.tool`. The `deps` closure carries the per-process state
+ * (InstanceManager, HttpClient, worktree, logger).
+ */
+export function createBgSpawnTool(deps: BgSpawnDeps) {
+  return tool({
+    description:
+      "Spawn a background agent that runs asynchronously. Only Odin may call this tool. " +
+      "Returns an instanceId; use bizar_status / bizar_collect / bizar_kill to manage the instance.",
+    args: {
+      agent: z.string().min(1).describe("Agent name to spawn (e.g. 'mimir', 'thor', 'tyr')."),
+      prompt: z.string().min(1).describe("User prompt for the background session."),
+      model: z
+        .string()
+        .optional()
+        .describe("Optional model override in 'providerID/modelID' format."),
+      timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Collect-time timeout in ms (1s..30min, default 5min)."),
+    },
+    execute: async (rawArgs, ctx) => {
+      // 1. Odin-only (MEDIUM-26).
+      if (ctx.agent !== "odin") {
+        return {
+          output: JSON.stringify({
+            error:
+              "Only Odin can spawn background agents. Use the task tool for sync work, or ask Odin to spawn a background agent.",
+          }),
+        };
+      }
+
+      const args = rawArgs as {
+        agent: string;
+        prompt: string;
+        model?: string;
+        timeoutMs?: number;
+      };
+
+      // 2. Validate the model parameter (LOW-34 / §1.4).
+      let modelOverride: ModelOverride | undefined;
+      if (args.model !== undefined && args.model !== "") {
+        const m = parseModel(args.model);
+        if (m === null) {
+          return {
+            output: JSON.stringify({
+              error: `model must be in "providerID/modelID" format (e.g. "minimax/MiniMax-M3"). Omit to use the agent's default.`,
+            }),
+          };
+        }
+        modelOverride = m;
+      }
+
+      // 3. Clamp timeoutMs (MEDIUM-33 / §7.3).
+      const requested = args.timeoutMs ?? TIMEOUT_DEFAULT_MS;
+      if (requested < TIMEOUT_MIN_MS || requested > TIMEOUT_MAX_MS) {
+        return {
+          output: JSON.stringify({
+            error: `timeoutMs must be between ${TIMEOUT_MIN_MS} (1s) and ${TIMEOUT_MAX_MS} (30min). Got ${requested}.`,
+          }),
+        };
+      }
+      const timeoutMs = requested;
+
+      // 4. Generate the instanceId and seed the manager (track BEFORE HTTP).
+      const instanceId = generateInstanceId();
+      const draft = {
+        instanceId,
+        sessionId: "", // filled in by POST /session response
+        agent: args.agent,
+        model: modelOverride
+          ? `${modelOverride.providerID}/${modelOverride.modelID}`
+          : "agent-default",
+        promptPreview: args.prompt.slice(0, 200),
+        parentAgent: ctx.agent,
+        logPath: buildLogPath(deps.worktree, instanceId),
+        timeoutMs,
+        toolCallCount: 0,
+      };
+      const addRes = await deps.instanceManager.add(draft);
+      if (addRes === "cap_reached") {
+        return {
+          output: JSON.stringify({
+            error: `Max concurrent instances reached. Wait for one to finish or call bizar_kill.`,
+          }),
+        };
+      }
+
+      // 5. POST /session. The in-memory entry already exists.
+      const sessionRes = await deps.http.createSession(
+        {
+          parentID: ctx.sessionID,
+          title: `bgr:${args.agent}:${instanceId}`,
+          agent: args.agent,
+          ...(modelOverride ? { model: modelOverride } : {}),
+        },
+        deps.worktree,
+      );
+      if (!sessionRes.ok) {
+        await deps.instanceManager.update(instanceId, {
+          status: "failed",
+          error: `POST /session failed: ${sessionRes.error}`,
+          completedAt: Date.now(),
+        });
+        return {
+          output: JSON.stringify({
+            error: `spawn failed: ${sessionRes.error}`,
+            instanceId,
+            sessionId: null,
+            status: "failed",
+          }),
+        };
+      }
+
+      // 6. Persist the sessionId in the in-memory state.
+      await deps.instanceManager.update(instanceId, {
+        sessionId: sessionRes.value.id,
+        status: "running",
+      });
+
+      // 6b. BUGFIX (v0.5.1): Now that the real sessionId is known,
+      // attach the SSE event handler for this instance. The track-BEFORE-
+      // HTTP invariant is preserved (instance is in the map from step 4),
+      // but the per-session event subscription is deferred to here so it
+      // can be registered against the real sessionId rather than "".
+      // Re-read the instance so the SSE handler sees the updated sessionId.
+      const freshInstance = await deps.instanceManager.get(instanceId);
+      if (freshInstance) {
+        try {
+          deps.instanceManager.attachEventHandler(freshInstance);
+        } catch (err: unknown) {
+          // Event handler attachment is best-effort. If it fails (e.g. the
+          // SSE stream is disconnected) the instance is still tracked and
+          // can be re-attached later via a reconnect.
+          deps.logger.warn(
+            `bizar: attachEventHandler failed for ${instanceId}: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        }
+      }
+
+      // 7. POST /session/{id}/prompt_async.
+      const messageID = generateMessageId();
+      const sendRes = await deps.http.sendPrompt(
+        {
+          sessionId: sessionRes.value.id,
+          messageID,
+          agent: args.agent,
+          ...(modelOverride ? { model: modelOverride } : {}),
+          parts: [{ type: "text", text: args.prompt }],
+        },
+        deps.worktree,
+      );
+      if (!sendRes.ok) {
+        await deps.instanceManager.update(instanceId, {
+          status: "failed",
+          error: `POST /session/{id}/prompt_async failed: ${sendRes.error}`,
+          completedAt: Date.now(),
+        });
+        return {
+          output: JSON.stringify({
+            error: `spawn failed: ${sendRes.error}`,
+            instanceId,
+            sessionId: sessionRes.value.id,
+            status: "failed",
+          }),
+        };
+      }
+
+      return {
+        output: JSON.stringify({
+          instanceId,
+          sessionId: sessionRes.value.id,
+          status: "pending",
+        }),
+      };
+    },
+  });
+}
+
+// --- Helpers --------------------------------------------------------------
+
+function buildLogPath(worktree: string, instanceId: string): string {
+  // The log file is owned by the opencode serve child (not by us). The
+  // plugin doesn't write to it. We still record the conventional path so
+  // the user can `cat` the per-session log for diagnostics.
+  return `${worktree}/.opencode/log/${instanceId}.log`;
+}