@polderlabs/bizar 6.2.4 → 6.3.0

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

@@ -1,266 +0,0 @@
-/**
- * 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.
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_GET_PLAN_COMMENTS_TOOL_NAME`.
- *   - `inputSchema` is `z.object(...)` over the same fields as before.
- *   - Returns structured `{ ok, comments, planSlug }` / `{ ok: false, error, planSlug }`
- *     instead of `{ output: JSON.stringify(...) }`.
- */
-
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import type { Logger } from "../logger.js";
-
-export const BIZAR_GET_PLAN_COMMENTS_TOOL_NAME = "bizar_get_plan_comments";
-
-export interface BgGetCommentsDeps {
-  /** The project's working directory (e.g. /home/user/proj). `plans/` is here. */
-  worktree: string;
-  logger: Logger;
-}
-
-export type BizarGetPlanCommentsInput = z.infer<typeof bizarGetPlanCommentsSchema>;
-export type BizarGetPlanCommentsOutput =
-  | { ok: true; comments: PlanComment[]; planSlug: string }
-  | { ok: false; error: string; planSlug: string };
-
-const bizarGetPlanCommentsSchema = z.object({
-  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).",
-    ),
-});
-
-// --- 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 `api.registerTool()` from `AgentExtensionApi`. The `deps`
- * closure carries the worktree and logger.
- */
-export function createBgGetCommentsTool(
-  deps: BgGetCommentsDeps,
-): AgentTool<BizarGetPlanCommentsInput, BizarGetPlanCommentsOutput> {
-  return createTool({
-    name: BIZAR_GET_PLAN_COMMENTS_TOOL_NAME,
-    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.",
-    inputSchema: bizarGetPlanCommentsSchema.shape,
-    execute: async (input) => {
-      const result = readPlanComments(deps.worktree, input.planSlug, input.elementId);
-      if (!result.ok) {
-        deps.logger.warn(
-          `bizar: get_plan_comments(${input.planSlug}) failed: ${result.error}`,
-        );
-        return {
-          ok: false as const,
-          error: result.error,
-          planSlug: input.planSlug,
-        };
-      }
-      return {
-        ok: true as const,
-        comments: result.comments,
-        planSlug: result.planSlug,
-      };
-    },
-  });
-}

package/plugins/bizar/src/tools/bg-kill.ts

@@ -1,116 +0,0 @@
-/**
- * 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.
- *
- * v5.5.x — Calls `cline.abort(sessionId)` on the in-process `ClineCore`
- * (Phase 2/3 in-process refactor). The session record is preserved in
- * Cline for history; the running loop is stopped.
- *
- * After abort, the next event for that session is the corresponding
- * agent runtime event. The plugin's `afterTool` hook 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).
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_KILL_TOOL_NAME`.
- *   - `inputSchema` is `z.object(...)` over the same fields as before.
- *   - Returns structured `{ ok, instanceId, status }` instead of
- *     `{ output: JSON.stringify(...) }`.
- *   - `ctx.agent` from OpenCode becomes `agentId`-derived role check
- *     via the runtime metadata; Cline does not surface `agent` on
- *     `AgentToolContext`, so the InstanceManager encodes the role on
- *     each instance and we check there.
- */
-
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-
-import type { InstanceManager } from "../background.js";
-import type { Logger } from "../logger.js";
-
-export const BIZAR_KILL_TOOL_NAME = "bizar_kill";
-
-export interface BgKillDeps {
-  instanceManager: InstanceManager;
-  logger: Logger;
-}
-
-export type BizarKillInput = z.infer<typeof bizarKillSchema>;
-export type BizarKillOutput =
-  | { ok: true; instanceId: string; status: string }
-  | { ok: false; error: string; instanceId?: string };
-
-const bizarKillSchema = z.object({
-  instanceId: z
-    .string()
-    .min(1)
-    .describe("Instance id returned by bizar_spawn_background."),
-});
-
-/**
- * Build the `bizar_kill` tool. The plugin wires the result into
- * `api.registerTool()` from `AgentExtensionApi`. The `deps` closure
- * carries the InstanceManager.
- */
-export function createBgKillTool(
-  deps: BgKillDeps,
-): AgentTool<BizarKillInput, BizarKillOutput> {
-  return createTool({
-    name: BIZAR_KILL_TOOL_NAME,
-    description:
-      "Kill a running background instance. Only Odin may kill. " +
-      "No-op on already-terminal instances.",
-    inputSchema: bizarKillSchema.shape,
-    execute: async (input, context) => {
-      // Odin-only — derive the agent role from the runtime metadata
-      // (`parentAgent` is set on first chat.message of the session)
-      // and from the InstanceManager when possible. Cline's
-      // `AgentToolContext` does not expose `agent` directly, so we
-      // check the persisted state instead.
-      const parentAgent =
-        (context.metadata as { parentAgent?: string } | undefined)?.parentAgent ??
-        null;
-      if (parentAgent !== "odin") {
-        return {
-          ok: false as const,
-          error:
-            "Only Odin can kill background agents. Use bizar_status to inspect or ask Odin to kill.",
-        };
-      }
-      const inst = await deps.instanceManager.get(input.instanceId);
-      if (!inst) {
-        return {
-          ok: false as const,
-          error: "instance_not_found",
-          instanceId: input.instanceId,
-        };
-      }
-      try {
-        await deps.instanceManager.kill(input.instanceId);
-        const after = await deps.instanceManager.get(input.instanceId);
-        return {
-          ok: true as const,
-          instanceId: input.instanceId,
-          status: after?.status ?? "killed",
-        };
-      } catch (err: unknown) {
-        deps.logger.warn(
-          `bizar: kill(${input.instanceId}) failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return {
-          ok: false as const,
-          error: `kill_failed: ${err instanceof Error ? err.message : String(err)}`,
-          instanceId: input.instanceId,
-        };
-      }
-    },
-  });
-}

package/plugins/bizar/src/tools/bg-pause.ts

@@ -1,99 +0,0 @@
-/**
- * plugins/bizar/src/tools/bg-pause.ts
- *
- * v5.x — `bizar_pause` tool. Sends SIGSTOP to a running background
- * agent's subprocess (POSIX only). The InstanceManager flips the
- * in-memory status to `"paused"` and persists the change.
- *
- * The companion tool `bizar_resume` ({@link ./bg-resume.ts}) reverses
- * the action via SIGCONT.
- *
- * Odin-only — same auth model as the rest of the bg tools.
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_PAUSE_TOOL_NAME`.
- *   - `inputSchema` is `z.object(...)` over the same fields as before.
- *   - Returns structured `{ ok, instanceId, status }` instead of
- *     `{ output: JSON.stringify(...) }`.
- *   - `ctx.agent` becomes `context.metadata.parentAgent` look-up.
- */
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-
-import type { InstanceManager } from "../background.js";
-import type { Logger } from "../logger.js";
-
-export const BIZAR_PAUSE_TOOL_NAME = "bizar_pause";
-
-export interface BgPauseDeps {
-  instanceManager: InstanceManager;
-  logger: Logger;
-}
-
-export type BizarPauseInput = z.infer<typeof bizarPauseSchema>;
-export type BizarPauseOutput =
-  | { ok: true; instanceId: string; status: string }
-  | { ok: false; error: string; instanceId?: string };
-
-const bizarPauseSchema = z.object({
-  instanceId: z
-    .string()
-    .min(1)
-    .describe("Instance id returned by bizar_spawn_background."),
-});
-
-/**
- * Build the `bizar_pause` tool. The plugin wires the result into
- * `api.registerTool()` from `AgentExtensionApi`. The `deps` closure
- * carries the InstanceManager.
- */
-export function createBgPauseTool(
-  deps: BgPauseDeps,
-): AgentTool<BizarPauseInput, BizarPauseOutput> {
-  return createTool({
-    name: BIZAR_PAUSE_TOOL_NAME,
-    description:
-      "Pause a running background agent by sending SIGSTOP to its subprocess. " +
-      "Only Odin may pause. No-op on already-paused instances. " +
-      "POSIX only — on Windows this returns an `unsupported_on_win32` error.",
-    inputSchema: bizarPauseSchema.shape,
-    execute: async (input, context) => {
-      const parentAgent =
-        (context.metadata as { parentAgent?: string } | undefined)?.parentAgent ?? null;
-      if (parentAgent !== "odin") {
-        return {
-          ok: false as const,
-          error:
-            "Only Odin can pause background agents. Use bizar_status to inspect or ask Odin to pause.",
-        };
-      }
-      try {
-        const result = await deps.instanceManager.pause(input.instanceId);
-        if (!result.ok) {
-          return {
-            ok: false as const,
-            error: result.error || "pause failed",
-            instanceId: input.instanceId,
-          };
-        }
-        return {
-          ok: true as const,
-          instanceId: input.instanceId,
-          status: "paused",
-        };
-      } catch (err: unknown) {
-        deps.logger.warn(
-          `bizar: pause(${input.instanceId}) threw: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return {
-          ok: false as const,
-          error: `pause threw: ${err instanceof Error ? err.message : String(err)}`,
-          instanceId: input.instanceId,
-        };
-      }
-    },
-  });
-}

package/plugins/bizar/src/tools/bg-report-progress.ts

@@ -1,115 +0,0 @@
-/**
- * plugins/bizar/src/tools/bg-report-progress.ts
- *
- * v5.x — `bizar_report_progress` tool. Lets a running background agent
- * push a structured progress update (step/total/message) into the
- * instance state. The dashboard reads `progress` and renders a
- * progress bar; `progressMessage` shows the free-form status line.
- *
- * Available to ALL agents (the body of a bg agent calls it; not just
- * Odin). The `bizar_*` prefix is reserved; the auth filter is "all",
- * matching the "tools all agents can call" pattern of
- * `bizar_status`.
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_REPORT_PROGRESS_TOOL_NAME`.
- *   - `inputSchema` is `z.object(...)` over the same fields as before.
- *   - Returns structured `{ ok, instanceId, progress }` instead of
- *     `{ output: JSON.stringify(...) }`.
- */
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-
-import type { InstanceManager } from "../background.js";
-import type { Logger } from "../logger.js";
-
-export const BIZAR_REPORT_PROGRESS_TOOL_NAME = "bizar_report_progress";
-
-export interface BgReportProgressDeps {
-  instanceManager: InstanceManager;
-  logger: Logger;
-}
-
-export type BizarReportProgressInput = z.infer<typeof bizarReportProgressSchema>;
-export type BizarReportProgressOutput =
-  | { ok: true; instanceId: string; progress: number | undefined }
-  | { ok: false; error: string; instanceId: string };
-
-const bizarReportProgressSchema = z.object({
-  instanceId: z
-    .string()
-    .min(1)
-    .describe("Instance id (the one returned by bizar_spawn_background)."),
-  step: z
-    .number()
-    .int()
-    .min(0)
-    .describe("Current step (>=0)."),
-  total: z
-    .number()
-    .int()
-    .positive()
-    .describe("Total step count (>0)."),
-  message: z
-    .string()
-    .optional()
-    .describe("Optional human-readable status."),
-  indeterminate: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe("Set true to show an indeterminate (unknown) progress."),
-});
-
-/**
- * Build the `bizar_report_progress` tool. The plugin wires the result
- * into `api.registerTool()` from `AgentExtensionApi`. The `deps`
- * closure carries the InstanceManager.
- */
-export function createBgReportProgressTool(
-  deps: BgReportProgressDeps,
-): AgentTool<BizarReportProgressInput, BizarReportProgressOutput> {
-  return createTool({
-    name: BIZAR_REPORT_PROGRESS_TOOL_NAME,
-    description:
-      "Report progress on the current background instance. " +
-      "Available to all agents. step/total are integers; message is a " +
-      "free-form status hint shown next to the progress bar.",
-    inputSchema: bizarReportProgressSchema.shape,
-    execute: async (input) => {
-      try {
-        const result = await deps.instanceManager.updateProgress(
-          input.instanceId,
-          input.step,
-          input.total,
-          input.message,
-          Boolean(input.indeterminate),
-        );
-        if (!result.ok) {
-          return {
-            ok: false as const,
-            error: result.error || "progress_failed",
-            instanceId: input.instanceId,
-          };
-        }
-        return {
-          ok: true as const,
-          instanceId: input.instanceId,
-          progress: result.progress,
-        };
-      } catch (err: unknown) {
-        deps.logger.warn(
-          `bizar: report-progress(${input.instanceId}) threw: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return {
-          ok: false as const,
-          error: `report-progress threw: ${err instanceof Error ? err.message : String(err)}`,
-          instanceId: input.instanceId,
-        };
-      }
-    },
-  });
-}

package/plugins/bizar/src/tools/bg-resume.ts

@@ -1,94 +0,0 @@
-/**
- * plugins/bizar/src/tools/bg-resume.ts
- *
- * v5.x — `bizar_resume` tool. Sends SIGCONT to a paused background
- * agent's subprocess. Companion to {@link ./bg-pause.ts}.
- *
- * Odin-only.
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_RESUME_TOOL_NAME`.
- *   - `inputSchema` is `z.object(...)` over the same fields as before.
- *   - Returns structured `{ ok, instanceId, status }` instead of
- *     `{ output: JSON.stringify(...) }`.
- *   - `ctx.agent` becomes `context.metadata.parentAgent` look-up.
- */
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-
-import type { InstanceManager } from "../background.js";
-import type { Logger } from "../logger.js";
-
-export const BIZAR_RESUME_TOOL_NAME = "bizar_resume";
-
-export interface BgResumeDeps {
-  instanceManager: InstanceManager;
-  logger: Logger;
-}
-
-export type BizarResumeInput = z.infer<typeof bizarResumeSchema>;
-export type BizarResumeOutput =
-  | { ok: true; instanceId: string; status: string }
-  | { ok: false; error: string; instanceId?: string };
-
-const bizarResumeSchema = z.object({
-  instanceId: z
-    .string()
-    .min(1)
-    .describe("Instance id returned by bizar_spawn_background."),
-});
-
-/**
- * Build the `bizar_resume` tool. The plugin wires the result into
- * `api.registerTool()` from `AgentExtensionApi`. The `deps` closure
- * carries the InstanceManager.
- */
-export function createBgResumeTool(
-  deps: BgResumeDeps,
-): AgentTool<BizarResumeInput, BizarResumeOutput> {
-  return createTool({
-    name: BIZAR_RESUME_TOOL_NAME,
-    description:
-      "Resume a paused background agent by sending SIGCONT to its subprocess. " +
-      "Only Odin may resume. No-op on already-running instances. POSIX only.",
-    inputSchema: bizarResumeSchema.shape,
-    execute: async (input, context) => {
-      const parentAgent =
-        (context.metadata as { parentAgent?: string } | undefined)?.parentAgent ?? null;
-      if (parentAgent !== "odin") {
-        return {
-          ok: false as const,
-          error:
-            "Only Odin can resume background agents. Use bizar_status to inspect or ask Odin to resume.",
-        };
-      }
-      try {
-        const result = await deps.instanceManager.resume(input.instanceId);
-        if (!result.ok) {
-          return {
-            ok: false as const,
-            error: result.error || "resume failed",
-            instanceId: input.instanceId,
-          };
-        }
-        return {
-          ok: true as const,
-          instanceId: input.instanceId,
-          status: "running",
-        };
-      } catch (err: unknown) {
-        deps.logger.warn(
-          `bizar: resume(${input.instanceId}) threw: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return {
-          ok: false as const,
-          error: `resume threw: ${err instanceof Error ? err.message : String(err)}`,
-          instanceId: input.instanceId,
-        };
-      }
-    },
-  });
-}