@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/tool-discipline.ts

@@ -1,105 +0,0 @@
-/**
- * tool-discipline.ts
- *
- * v6.0.1 — Tool-call discipline + preference directive injected into
- * every Cline system prompt produced by the Bizar harness.
- *
- * Why this exists:
- *
- *   Cline's runtime aborts sessions when the model emits consecutive
- *   tool calls that fail Zod schema validation (e.g. `editor({ new_text:
- *   undefined })`, `ask_question({ options: null })`,
- *   `run_commands({ ... })`). The defaults in `mistake-recovery.ts` keep
- *   the session alive — but the cheaper fix is preventing the bad tool
- *   calls in the first place.
- *
- *   We also steer the model away from over-using `run_commands` for
- *   things that have a dedicated built-in tool. Built-in tools give
- *   better diffs, easier approval, richer error context, and don't
- *   require shell quoting. Bash is for things that genuinely need a
- *   shell — anything else should hit a specialized tool.
- *
- *   This directive is appended to the system prompt by the harness's
- *   `beforeModel` hook (idempotent: detected via a marker). It is short
- *   enough to stay cheap (~220 tokens) and only fires once per session,
- *   so it does not bloat every turn's context.
- */
-
-export const TOOL_DISCIPLINE_MARKER = "BIZAR_TOOL_DISCIPLINE_v0.6.3";
-
-/**
- * The directive body. Kept compact; details are in the linked recovery
- * notice so we don't duplicate instructions between the system prompt
- * and the recovery callback.
- */
-export const TOOL_DISCIPLINE_DIRECTIVE = [
-  TOOL_DISCIPLINE_MARKER,
-  "",
-  "## Tool-call discipline",
-  "",
-  "• Required fields are required. Populate every field declared in the",
-  "  tool's input schema, with a value of the right type. Do not omit",
-  "  fields; Cline rejects the call before any side effect runs.",
-  "• `editor.new_text` must be a non-empty string. To clear content, use",
-  "  `applyPatch` or `delete_file`. To create a new file, pass the",
-  "  full intended contents as `new_text`.",
-  "• `ask_question.options` must be an array of ≥2 non-empty strings.",
-  "  Passing `null`, `undefined`, or arrays of length <2 fails schema",
-  "  validation.",
-  "• `run_commands.commands` must be a non-empty array of strings.",
-  "• If a tool call fails validation twice in a row, switch tools or",
-  "  describe the problem in plain text before retrying. Do not loop on",
-  "  the same mistake.",
-  "",
-  "## Prefer built-in tools over bash",
-  "",
-  "Cline ships dedicated tools for most file/shell work. Reach for them",
-  "before reaching for `run_commands`:",
-  "",
-  "| If you want to…                       | Use this, not bash           |",
-  "| ------------------------------------- | ---------------------------- |",
-  "| read a file                           | `read_file`                  |",
-  "| search a workspace                    | `search_codebase` / `search` |",
-  "| edit a file in place                  | `editor` or `apply_patch`    |",
-  "| create a new file                     | `editor` (new_text = full)   |",
-  "| list a directory                      | `list_files`                 |",
-  "| fetch a URL                           | `web_fetch`                  |",
-  "| run a build / test / lint / script    | `run_commands`               |",
-  "",
-  "Reaching for bash first creates two problems:",
-  "  1. Shell quoting bugs (quotes-in-quotes-in-quotes) are the most",
-  "     common cause of malformed tool calls.",
-  "  2. Each bash command lands in tool history as opaque output; a",
-  "     dedicated tool keeps diffs, error context, and approval gates",
-  "     intact.",
-  "",
-  "When you DO call `run_commands`, keep it small:",
-  "",
-  "• One logical command per call. Do not chain unrelated segments with",
-  "  `&&`. Use multiple `run_commands` turns instead — each turn's output",
-  "  is easier to debug and re-run.",
-  "• Pass file paths via the tool's structured fields (`editor.path`,",
-  "  `read_file.path`) — never as `cd ... && <cmd>` chdir hacks.",
-  "• Hard cap: do not emit a single command longer than ~600 chars. If",
-  "  the command doesn't fit, it's a sign you should use a built-in tool",
-  "  or split it across turns.",
-  "• No `for i in $(seq 1 100)` loops for batching work that has a tool",
-  "  (`read_file`, `editor`). Loops in bash hide per-file failures.",
-  "• No `xargs`, no `sed -i`, no heredocs to write files — these all",
-  "  have a dedicated tool that produces a richer record.",
-  "",
-  "These conventions avoid both the consecutive-mistake abort and the",
-  "common shell-quoting trap.",
-].join("\n");
-
-/**
- * Bump this constant when the directive body changes in a way that
- * warrants re-injection into existing sessions. The harness uses the
- * marker to detect "already injected", so an updated directive will
- * only land if a fresh session starts (or marker changes).
- */
-export const TOOL_DISCIPLINE_VERSION = "0.6.3";
-
-export function hasToolDiscipline(systemPrompt: string | undefined): boolean {
-  return typeof systemPrompt === "string" && systemPrompt.includes(TOOL_DISCIPLINE_MARKER);
-}

package/plugins/bizar/src/tools/agent-browser.ts

@@ -1,315 +0,0 @@
-/**
- * agent-browser.ts — v6.0.0 agent-browser CLI wrapper tools.
- *
- * Replaces the v5.x `browser-harness` (Python CDP wrapper) with
- * agent-browser (native Rust CLI from vercel-labs).
- *
- * Pattern: thin wrappers around `agent-browser <cmd> ...`. The CLI
- * is installed via npm (`npm install -g agent-browser`) and exposes
- * 100+ typed commands. The MCP stdio server (`agent-browser mcp`)
- * is exposed separately at the Cline level via `.cline/mcp.json`.
- *
- * Six tools:
- *   - bizar_browser_open         open a URL (auto-launches daemon)
- *   - bizar_browser_snapshot     accessibility tree with refs (@e1..)
- *   - bizar_browser_click        click by ref @e2 or selector
- *   - bizar_browser_fill         fill an input by ref or selector
- *   - bizar_browser_screenshot   screenshot to a file (returned by path)
- *   - bizar_browser_command      escape hatch for any agent-browser command
- *
- * The plugin invokes `agent-browser ...` via execFile (no shell, no
- * injection). All tool calls go through `checkDangerous()` for the
- * DANGEROUS_PATTERNS approval gate.
- *
- * The browser-primary agent that uses these tools lives at
- * config/agents/agent-browser.md.
- */
-
-import { createTool, type AgentTool } from "@cline/sdk";
-import { z } from "zod";
-
-import type { Logger } from "../logger.js";
-
-export const BIZAR_BROWSER_OPEN_TOOL_NAME = "bizar_browser_open";
-export const BIZAR_BROWSER_SNAPSHOT_TOOL_NAME = "bizar_browser_snapshot";
-export const BIZAR_BROWSER_CLICK_TOOL_NAME = "bizar_browser_click";
-export const BIZAR_BROWSER_FILL_TOOL_NAME = "bizar_browser_fill";
-export const BIZAR_BROWSER_SCREENSHOT_TOOL_NAME = "bizar_browser_screenshot";
-export const BIZAR_BROWSER_COMMAND_TOOL_NAME = "bizar_browser_command";
-
-export interface AgentBrowserDeps {
-  logger: Logger;
-  /** Override the agent-browser binary path. Default: "agent-browser" on PATH. */
-  bin?: string;
-  /** Default browser profile directory. */
-  profile?: string;
-  /** Default daemon host. */
-  host?: string;
-  /** Default daemon port. */
-  port?: number;
-}
-
-function resolveBin(deps: AgentBrowserDeps): string {
-  if (deps.bin) return deps.bin;
-  return process.env.AGENT_BROWSER_BIN ?? "agent-browser";
-}
-
-/**
- * Run an agent-browser CLI subcommand and capture stdout/stderr/exitCode.
- *
- * Returns the parsed JSON object when `--json` is passed and the output
- * is valid JSON; otherwise returns a `{ stdout, stderr, exitCode }`
- * envelope.
- */
-async function runAgentBrowser(
-  deps: AgentBrowserDeps,
-  args: string[],
-  opts: { json?: boolean; cwd?: string; timeoutMs?: number } = {},
-): Promise<{ ok: boolean; exitCode: number; stdout: string; stderr: string; json?: unknown }> {
-  const bin = resolveBin(deps);
-  const json = opts.json ?? args.includes("--json");
-  const finalArgs = json && !args.includes("--json") ? [...args, "--json"] : args;
-
-  const { execFile } = await import("node:child_process");
-  const { promisify } = await import("node:util");
-  const pExecFile = promisify(execFile);
-
-  try {
-    const { stdout, stderr } = await pExecFile(bin, finalArgs, {
-      cwd: opts.cwd ?? process.cwd(),
-      timeout: opts.timeoutMs ?? 30_000,
-      maxBuffer: 16 * 1024 * 1024,
-    });
-    if (json) {
-      try {
-        return { ok: true, exitCode: 0, stdout, stderr, json: JSON.parse(stdout) };
-      } catch {
-        return { ok: true, exitCode: 0, stdout, stderr };
-      }
-    }
-    return { ok: true, exitCode: 0, stdout, stderr };
-  } catch (err) {
-    const e = err as { code?: number | string; stdout?: string; stderr?: string };
-    return {
-      ok: false,
-      exitCode: typeof e.code === "number" ? e.code : 1,
-      stdout: e.stdout ?? "",
-      stderr: e.stderr ?? (err instanceof Error ? err.message : String(err)),
-    };
-  }
-}
-
-// ─── tool: bizar_browser_open ────────────────────────────────────────────
-export type BizarBrowserOpenInput = z.infer<typeof bizarBrowserOpenSchema>;
-export type BizarBrowserOpenOutput =
-  | { ok: true; url: string; snapshot?: unknown; stdout: string }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserOpenSchema = z.object({
-  url: z.string().url().describe("URL to open in the browser."),
-  headless: z.boolean().optional().describe("Default true. Set false for visual debugging."),
-  profile: z.string().optional().describe("Override profile dir for this session."),
-});
-
-export function createBrowserOpenTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserOpenInput, BizarBrowserOpenOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_OPEN_TOOL_NAME,
-    description:
-      "Launch agent-browser and navigate to a URL. Auto-starts the daemon if not running. " +
-      "Returns the initial accessibility-tree snapshot as JSON for immediate element discovery.",
-    inputSchema: bizarBrowserOpenSchema.shape,
-    execute: async (input) => {
-      const args = ["open", input.url];
-      if (input.headless === false) args.push("--headed");
-      if (input.profile ?? deps.profile) args.push("--profile", input.profile ?? deps.profile!);
-      const r = await runAgentBrowser(deps, args, { json: true });
-      if (!r.ok) {
-        deps.logger.warn(`bizar_browser_open failed: ${r.stderr}`);
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return { ok: true as const, url: input.url, snapshot: r.json, stdout: r.stdout };
-    },
-  });
-}
-
-// ─── tool: bizar_browser_snapshot ────────────────────────────────────────
-export type BizarBrowserSnapshotInput = z.infer<typeof bizarBrowserSnapshotSchema>;
-export type BizarBrowserSnapshotOutput =
-  | { ok: true; snapshot: unknown; stdout: string }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserSnapshotSchema = z.object({
-  max_depth: z.number().int().positive().optional().describe("Optional subtree depth limit."),
-  format: z.enum(["json", "ai"]).optional().describe("Output format. Default: json."),
-});
-
-export function createBrowserSnapshotTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserSnapshotInput, BizarBrowserSnapshotOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_SNAPSHOT_TOOL_NAME,
-    description:
-      "Get the current page's accessibility tree with stable refs (@e1, @e2, …). " +
-      "Ref-based selectors survive page-snapshot churn better than CSS selectors. " +
-      "Returns structured JSON by default; pass format='ai' for a compact text variant.",
-    inputSchema: bizarBrowserSnapshotSchema.shape,
-    execute: async (input) => {
-      const format = input.format ?? "json";
-      const args = ["snapshot", format === "ai" ? "--ai" : "--json"];
-      if (input.max_depth) args.push("--max-depth", String(input.max_depth));
-      const r = await runAgentBrowser(deps, args, { json: true });
-      if (!r.ok) {
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return { ok: true as const, snapshot: r.json, stdout: r.stdout };
-    },
-  });
-}
-
-// ─── tool: bizar_browser_click ──────────────────────────────────────────
-export type BizarBrowserClickInput = z.infer<typeof bizarBrowserClickSchema>;
-export type BizarBrowserClickOutput =
-  | { ok: true; clicked: string; stdout: string }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserClickSchema = z.object({
-  selector: z.string().min(1).describe("Element to click. Prefer a ref from snapshot (e.g. '@e2'); CSS selectors and role/name tuples also accepted."),
-  new_tab: z.boolean().optional().describe("Open the link in a new tab."),
-});
-
-export function createBrowserClickTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserClickInput, BizarBrowserClickOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_CLICK_TOOL_NAME,
-    description:
-      "Click an element identified by ref (preferred) or selector. " +
-      "Ref-based selectors (@e2) are stable across snapshots; CSS selectors and " +
-      "role/name tuples are also accepted. Pass new_tab=true to open link targets in a new tab.",
-    inputSchema: bizarBrowserClickSchema.shape,
-    execute: async (input) => {
-      const args = ["click", input.selector];
-      if (input.new_tab) args.push("--new-tab");
-      const r = await runAgentBrowser(deps, args);
-      if (!r.ok) {
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return { ok: true as const, clicked: input.selector, stdout: r.stdout };
-    },
-  });
-}
-
-// ─── tool: bizar_browser_fill ───────────────────────────────────────────
-export type BizarBrowserFillInput = z.infer<typeof bizarBrowserFillSchema>;
-export type BizarBrowserFillOutput =
-  | { ok: true; filled: string; value: string; stdout: string }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserFillSchema = z.object({
-  selector: z.string().min(1).describe("Element to fill (ref like '@e3' or CSS selector)."),
-  value: z.string().describe("Value to fill."),
-  submit: z.boolean().optional().describe("If true, press Enter after filling."),
-});
-
-export function createBrowserFillTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserFillInput, BizarBrowserFillOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_FILL_TOOL_NAME,
-    description:
-      "Clear and fill an input. Uses ref or selector. The agent-browser " +
-      "fill command replaces text content (unlike `type` which appends).",
-    inputSchema: bizarBrowserFillSchema.shape,
-    execute: async (input) => {
-      const args = ["fill", input.selector, input.value];
-      if (input.submit) args.push("--submit");
-      const r = await runAgentBrowser(deps, args);
-      if (!r.ok) {
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return { ok: true as const, filled: input.selector, value: input.value, stdout: r.stdout };
-    },
-  });
-}
-
-// ─── tool: bizar_browser_screenshot ─────────────────────────────────────
-export type BizarBrowserScreenshotInput = z.infer<typeof bizarBrowserScreenshotSchema>;
-export type BizarBrowserScreenshotOutput =
-  | { ok: true; path: string; bytes?: number; stdout: string }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserScreenshotSchema = z.object({
-  path: z.string().min(1).describe("Output file path (relative paths resolve to the worktree)."),
-  full_page: z.boolean().optional().describe("Capture the entire scrollable area."),
-  element: z.string().optional().describe("Capture only this ref (e.g. '@e4')."),
-});
-
-export function createBrowserScreenshotTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserScreenshotInput, BizarBrowserScreenshotOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_SCREENSHOT_TOOL_NAME,
-    description:
-      "Take a screenshot of the current page (or an element) and save it to `path`. " +
-      "Use full_page=true to capture the entire scrollable area, or pass element='@eN' " +
-      "to capture a single element. Returns the absolute path of the written file.",
-    inputSchema: bizarBrowserScreenshotSchema.shape,
-    execute: async (input) => {
-      const args = ["screenshot", input.path];
-      if (input.full_page) args.push("--full-page");
-      if (input.element) args.push("--element", input.element);
-      const r = await runAgentBrowser(deps, args);
-      if (!r.ok) {
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return { ok: true as const, path: input.path, stdout: r.stdout };
-    },
-  });
-}
-
-// ─── tool: bizar_browser_command (escape hatch) ─────────────────────────
-export type BizarBrowserCommandInput = z.infer<typeof bizarBrowserCommandSchema>;
-export type BizarBrowserCommandOutput =
-  | { ok: true; stdout: string; stderr: string; exitCode: number; json?: unknown }
-  | { ok: false; error: string; stderr: string };
-
-const bizarBrowserCommandSchema = z.object({
-  args: z.array(z.string()).describe(
-    "Argv to pass to agent-browser (e.g. ['eval', 'document.title']). " +
-    "Use this escape hatch for the 100+ commands not exposed as dedicated tools " +
-    "(eval, wait, press, find role, hover, scroll, tab list/open/switch, etc.)."
-  ),
-  json: z.boolean().optional().describe("If true, agent-browser is invoked with --json and stdout is parsed as JSON."),
-  timeoutMs: z.number().int().positive().optional().describe("Max execution time, default 30s."),
-});
-
-export function createBrowserCommandTool(
-  deps: AgentBrowserDeps,
-): AgentTool<BizarBrowserCommandInput, BizarBrowserCommandOutput> {
-  return createTool({
-    name: BIZAR_BROWSER_COMMAND_TOOL_NAME,
-    description:
-      "Escape hatch: invoke any agent-browser CLI command by argv. Returns stdout, stderr, " +
-      "and exit code. Use the dedicated tools (bizar_browser_open/snapshot/click/fill/screenshot) " +
-      "for common operations; this is for the 100+ commands they don't cover.",
-    inputSchema: bizarBrowserCommandSchema.shape,
-    execute: async (input) => {
-      const r = await runAgentBrowser(deps, input.args, {
-        json: input.json,
-        timeoutMs: input.timeoutMs,
-      });
-      if (!r.ok) {
-        return { ok: false as const, error: `agent-browser exited ${r.exitCode}`, stderr: r.stderr };
-      }
-      return {
-        ok: true as const,
-        stdout: r.stdout,
-        stderr: r.stderr,
-        exitCode: r.exitCode,
-        json: r.json,
-      };
-    },
-  });
-}

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

@@ -1,131 +0,0 @@
-/**
- * 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).
- *
- * Cline SDK port (Phase 2):
- *   - Uses `createTool` from `@cline/sdk` directly.
- *   - Adds `name: BIZAR_COLLECT_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";
-
-const TIMEOUT_MIN_MS = 1000;
-const TIMEOUT_MAX_MS = 1_800_000;
-const TIMEOUT_DEFAULT_MS = 60_000;
-
-export const BIZAR_COLLECT_TOOL_NAME = "bizar_collect";
-
-export interface BgCollectDeps {
-  instanceManager: InstanceManager;
-  logger: Logger;
-}
-
-export type BizarCollectInput = z.infer<typeof bizarCollectSchema>;
-export type BizarCollectOutput =
-  | {
-      ok: true;
-      instanceId: string;
-      status: string;
-      result: string;
-      toolCallCount: number;
-      durationMs: number;
-      error?: string;
-    }
-  | { ok: false; error: string; instanceId?: string };
-
-const bizarCollectSchema = z.object({
-  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)."),
-});
-
-/**
- * Build the `bizar_collect` tool. The plugin wires the result into
- * `api.registerTool()` from `AgentExtensionApi`. The `deps` closure
- * carries the InstanceManager.
- */
-export function createBgCollectTool(
-  deps: BgCollectDeps,
-): AgentTool<BizarCollectInput, BizarCollectOutput> {
-  return createTool({
-    name: BIZAR_COLLECT_TOOL_NAME,
-    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.",
-    inputSchema: bizarCollectSchema.shape,
-    execute: async (input, context) => {
-      // Odin-only (§6.3).
-      const parentAgent =
-        (context.metadata as { parentAgent?: string } | undefined)?.parentAgent ?? null;
-      if (parentAgent !== "odin") {
-        return {
-          ok: false as const,
-          error:
-            "Only Odin can collect background agent results. Use bizar_status to inspect or ask Odin to collect.",
-        };
-      }
-
-      // Clamp timeoutMs (MEDIUM-33 / §7.3).
-      const requested = input.timeoutMs ?? TIMEOUT_DEFAULT_MS;
-      if (requested < TIMEOUT_MIN_MS || requested > TIMEOUT_MAX_MS) {
-        return {
-          ok: false as const,
-          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(input.instanceId, timeoutMs);
-        return {
-          ok: true as const,
-          instanceId: input.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(${input.instanceId}) failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return {
-          ok: false as const,
-          error: `collect failed: ${err instanceof Error ? err.message : String(err)}`,
-          instanceId: input.instanceId,
-        };
-      }
-    },
-  });
-}