@polderlabs/bizar-plugin 0.6.1 → 0.8.0

package/src/dashboard-client.ts

@@ -0,0 +1,235 @@
+/**
+ * dashboard-client.ts
+ *
+ * v0.7.0-alpha.1 — Plugin-side bridge to the Bizar dashboard via the
+ * @polderlabs/bizar-sdk. Replaces (does not remove) the file-based
+ * `serve-info.ts` bridge.
+ *
+ * Usage:
+ *   import { createDashboardPublisher } from "./dashboard-client.js";
+ *
+ *   const publisher = createDashboardPublisher({
+ *     logger: myLogger,
+ *   });
+ *   await publisher.start();
+ *   publisher.publish({
+ *     type: "session.created",
+ *     properties: { sessionId: "ses_1", agent: "mimir" },
+ *   });
+ *
+ * Behavior:
+ *   - Reads `BIZAR_DASHBOARD_URL` (default http://127.0.0.1:4098).
+ *   - Reads `BIZAR_DASHBOARD_PASSWORD` first, then falls back to
+ *     `~/.cache/bizarharness/dash-auth.json` (the file written by the
+ *     dashboard on first start).
+ *   - `publish()` is fire-and-forget: returns a Promise that resolves
+ *     after one HTTP round-trip or rejects on failure. NEVER throws
+ *     into the caller — failures are logged and swallowed (the plugin
+ *     must keep running even when the dashboard is down).
+ *   - `publish()` queues events if the dashboard is unreachable and
+ *     drains the queue on reconnect (best-effort).
+ */
+
+import {
+  createBizarClient,
+  isBizarError,
+  type BizarClient,
+  type DashboardEvent,
+} from "@polderlabs/bizar-sdk";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const DEFAULT_DASHBOARD_URL = "http://127.0.0.1:4098";
+const DEFAULT_AUTH_FILE_PATHS = [
+  join(homedir(), ".cache", "bizarharness", "dash-auth.json"),
+  join(homedir(), ".cache", "bizar", "dash-auth.json"),
+];
+/**
+ * The auth file paths to search. Override at test-time via
+ * `process.env.BIZAR_DASHBOARD_AUTH_FILE` (single file) or
+ * `process.env.BIZAR_DASHBOARD_AUTH_FILES` (colon-separated list).
+ */
+function getAuthFilePaths(): string[] {
+  const single = process.env.BIZAR_DASHBOARD_AUTH_FILE;
+  if (single) return [single];
+  const multi = process.env.BIZAR_DASHBOARD_AUTH_FILES;
+  if (multi) return multi.split(":").filter(Boolean);
+  return DEFAULT_AUTH_FILE_PATHS;
+}
+
+export interface Logger {
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+export interface DashboardPublisherOptions {
+  logger: Logger;
+  baseUrl?: string;
+  password?: string;
+  /** Disable the publisher entirely (e.g. BIZAR_DASHBOARD_DISABLE=1). */
+  disabled?: boolean;
+  /** Max queued events while the dashboard is unreachable. */
+  queueLimit?: number;
+}
+
+/**
+ * Read the dashboard auth record from one of the candidate paths.
+ * Returns null if no usable file exists. Never throws.
+ */
+function readDashboardAuth(): { password: string; baseUrl?: string; port?: number } | null {
+  for (const candidate of getAuthFilePaths()) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const raw = readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw) as {
+        password?: unknown;
+        baseUrl?: unknown;
+        port?: unknown;
+      };
+      if (typeof parsed.password !== "string" || parsed.password.length < 16) continue;
+      return {
+        password: parsed.password,
+        baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : undefined,
+        port: typeof parsed.port === "number" ? parsed.port : undefined,
+      };
+    } catch {
+      // ignore malformed file
+    }
+  }
+  return null;
+}
+
+export interface DashboardPublisher {
+  start(): Promise<void>;
+  publish(event: DashboardEvent): Promise<void>;
+  stop(): void;
+  /** Whether the publisher is currently configured and ready. */
+  isReady(): boolean;
+}
+
+export function createDashboardPublisher(
+  options: DashboardPublisherOptions,
+): DashboardPublisher {
+  const { logger, disabled = false, queueLimit = 100 } = options;
+
+  let client: BizarClient | null = null;
+  const queue: DashboardEvent[] = [];
+  let flushing = false;
+
+  function resolveConfig(): { baseUrl: string; password: string } | null {
+    let baseUrl = options.baseUrl ?? process.env.BIZAR_DASHBOARD_URL;
+    if (!baseUrl) {
+      const port = process.env.BIZAR_DASHBOARD_PORT;
+      baseUrl = port ? `http://127.0.0.1:${port}` : DEFAULT_DASHBOARD_URL;
+    }
+    const password =
+      options.password ??
+      process.env.BIZAR_DASHBOARD_PASSWORD ??
+      readDashboardAuth()?.password;
+
+    if (!password) {
+      return null;
+    }
+    return { baseUrl, password };
+  }
+
+  function isReady(): boolean {
+    return client !== null;
+  }
+
+  async function start(): Promise<void> {
+    if (disabled) {
+      logger.debug("bizar: dashboard publisher disabled by config");
+      return;
+    }
+    const cfg = resolveConfig();
+    if (!cfg) {
+      logger.debug(
+        "bizar: dashboard publisher not started (no password in env or auth file)",
+      );
+      return;
+    }
+    client = createBizarClient({
+      baseUrl: cfg.baseUrl,
+      password: cfg.password,
+    });
+    logger.info(
+      `bizar: dashboard publisher started (url=${cfg.baseUrl}, password len=${cfg.password.length})`,
+    );
+
+    // Verify the dashboard is reachable. Non-fatal — publish() will retry
+    // and surface connection errors as warnings.
+    try {
+      const health = await client.health.check();
+      if (isBizarError(health)) {
+        logger.warn(
+          `bizar: dashboard unreachable at ${cfg.baseUrl} (${health.name}); publish events will be queued`,
+        );
+      }
+    } catch (err) {
+      logger.warn(
+        `bizar: dashboard health check failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    void flushQueue();
+  }
+
+  async function publish(event: DashboardEvent): Promise<void> {
+    if (!client) {
+      logger.debug(
+        `bizar: dashboard publisher not ready — dropping event ${event.type}`,
+      );
+      return;
+    }
+    if (queue.length >= queueLimit) {
+      queue.shift();
+      logger.warn(
+        `bizar: dashboard publisher queue full (${queueLimit}); dropping oldest event`,
+      );
+    }
+    queue.push(event);
+    if (!flushing) {
+      void flushQueue();
+    }
+  }
+
+  async function flushQueue(): Promise<void> {
+    if (flushing || !client) return;
+    flushing = true;
+    try {
+      while (queue.length > 0 && client) {
+        const next = queue.shift()!;
+        try {
+          const result = await client.events.publish(next);
+          if (isBizarError(result)) {
+            logger.warn(
+              `bizar: dashboard publish failed (${result.name}); requeueing ${next.type}`,
+            );
+            queue.unshift(next);
+            break;
+          }
+        } catch (err) {
+          logger.warn(
+            `bizar: dashboard publish threw: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          queue.unshift(next);
+          break;
+        }
+      }
+    } finally {
+      flushing = false;
+    }
+  }
+
+  function stop(): void {
+    client = null;
+    queue.length = 0;
+    logger.debug("bizar: dashboard publisher stopped");
+  }
+
+  return { start, publish, stop, isReady };
+}

package/src/event-stream.ts

@@ -120,6 +120,8 @@ export class EventStream {
   private _logger: Logger;
   private _http: HttpClient;
   private _handlers = new Map<string, Set<SessionEventHandler>>();
+  /** Global handler invoked for every event regardless of session (v0.7.0). */
+  private _globalHandler: SessionEventHandler | null = null;
   private _connected = false;
   private _aborted = false;
   private _abortController: AbortController | null = null;
@@ -128,6 +130,21 @@ export class EventStream {
   private _reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private _connectPromise: Promise<void> | null = null;
 
+  /**
+   * Register a global handler invoked for every event (regardless of
+   * session). Used to forward events to the dashboard publisher. Returns
+   * an unsubscribe function. (v0.7.0-alpha.1 — wired into the v2
+   * SDK dashboard-client.ts bridge.)
+   */
+  onEvent(handler: SessionEventHandler): () => void {
+    this._globalHandler = handler;
+    return () => {
+      if (this._globalHandler === handler) {
+        this._globalHandler = null;
+      }
+    };
+  }
+
   constructor(opts: {
     baseUrl: string;
     directory: string;
@@ -439,6 +456,21 @@ export class EventStream {
   }
 
   private dispatchToHandlers(sessionID: string, event: StreamEvent): void {
+    // v0.7.0-alpha.1 — Forward every event to the global handler
+    // (typically the dashboard publisher) BEFORE the per-session dispatch.
+    // Failures here are isolated so one bad handler doesn't break the
+    // dispatch chain for other subscribers.
+    if (this._globalHandler) {
+      try {
+        this._globalHandler(event);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this._logger.warn(
+          `bizar: SSE global handler threw for session ${sessionID} (type=${event.type}): ${msg}`,
+        );
+      }
+    }
+
     const set = this._handlers.get(sessionID);
     if (!set || set.size === 0) {
       this._logger.debug(

package/src/opencode-runner.ts

@@ -0,0 +1,362 @@
+/**
+ * plugins/bizar/src/opencode-runner.ts
+ *
+ * v0.8.0 — Process-based background agent runner.
+ *
+ * Replaces the v0.4–v0.7 `opencode serve` HTTP path. The HTTP API is
+ * passive — see the opencode docs:
+ *   "When you run opencode it starts a TUI and a server. Where the
+ *    TUI is the client that talks to the server."
+ *
+ * `opencode run <prompt>` is the active path: it spawns the agent
+ * loop in-process, drives it to completion, and exits. This module
+ * gives the plugin a clean way to spawn one `opencode run` per
+ * background agent, capture its output to the LogWriter's log file,
+ * track the PID for status/kill, and extract the opencode session
+ * id from the structured log stream.
+ *
+ * ─────────────────────────────────────────────────────────────────
+ * Why this exists (v0.7.0-alpha.1 → v0.8.0)
+ * ─────────────────────────────────────────────────────────────────
+ * Pre-v0.8.0, the plugin POSTed to `/api/session/{id}/prompt` on the
+ * opencode serve child. The server admitted the prompt
+ * (`session.next.prompt.admitted` event) but no agent loop processed
+ * it. The result: a session record was created, a tmux pane was
+ * spawned, and nothing happened. The user saw "spawns but does
+ * nothing" and was right.
+ *
+ * This module fixes that by spawning `opencode run` directly.
+ *
+ * ─────────────────────────────────────────────────────────────────
+ * Wire format
+ * ─────────────────────────────────────────────────────────────────
+ * `opencode run` writes structured logs to stderr, one log per line:
+ *
+ *   timestamp=2026-06-24T01:25:13.537Z level=INFO run=<uuid> message="creating instance" directory=/tmp
+ *   timestamp=2026-06-24T01:25:16.555Z level=INFO run=<uuid> message=created id=ses_… title="…" agent=…
+ *   timestamp=2026-06-24T01:25:16.951Z level=INFO run=<uuid> message=loop session.id=ses_… step=0
+ *   timestamp=2026-06-24T01:25:21.253Z level=INFO run=<uuid> message="exiting loop" session.id=ses_…
+ *
+ * The `message=created id=ses_<id>` line is how we recover the
+ * sessionId (the agent generated it; we don't pre-allocate). We
+ * parse the line with `message=created id=(ses_[A-Za-z0-9_]+)`.
+ *
+ * Both stdout and stderr are piped to `logPath` so the operator's
+ * tmux pane (and the dashboard's log viewer) can watch the agent
+ * work in real time. We prefix each line with the stream name
+ * ([stdout] / [stderr]) for human readability; downstream parsers
+ * can split on the first `] `.
+ */
+import { createWriteStream, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Subprocess } from "bun";
+
+export type AgentState = "starting" | "running" | "done" | "failed" | "killed";
+
+export interface AgentStatus {
+  state: AgentState;
+  sessionId?: string;
+  processId: number;
+  startedAt: number;
+  endedAt?: number;
+  exitCode?: number;
+  error?: string;
+}
+
+export interface SpawnAgentOptions {
+  /** The prompt to send. */
+  prompt: string;
+  /** Agent name (mimir, thor, …) — used as the session title prefix. */
+  agent: string;
+  /** Optional model override in "providerID/modelID" format. */
+  model?: { providerID: string; modelID: string };
+  /** Working directory for the opencode run. */
+  worktree: string;
+  /** Absolute path to the log file (the LogWriter's output path). */
+  logPath: string;
+  /** Optional session title (defaults to `bgr:<agent>`). */
+  title?: string;
+  /** Extra env vars to pass through. */
+  env?: Record<string, string>;
+  /** How long to wait for the sessionId to appear in stderr (ms). */
+  sessionIdTimeoutMs?: number;
+}
+
+export interface SpawnAgentResult {
+  ok: boolean;
+  sessionId?: string;
+  processId?: number;
+  error?: string;
+}
+
+type ExitCallback = (status: AgentStatus) => void;
+
+interface AgentRecord {
+  status: AgentStatus;
+  proc: Subprocess;
+  onExit: ExitCallback[];
+  // Resolvers for the spawn promise. Consumed when the sessionId
+  // arrives (or the process exits before that).
+  spawnResolvers: Array<(result: SpawnAgentResult) => void>;
+}
+
+// Module-level registry of running agents.
+const agents = new Map<number, AgentRecord>();
+
+// --- Public API -----------------------------------------------------------
+
+/**
+ * Spawn a single `opencode run` process. The promise resolves once
+ * the opencode child has reported its session id in the structured
+ * log stream (or once the process exits before that — typically
+ * because of an early error like a missing API key).
+ *
+ * @param opts
+ * @returns Promise resolving with `{ ok, sessionId?, processId? }` or `{ ok: false, error }`
+ */
+export async function spawnAgent(opts: SpawnAgentOptions): Promise<SpawnAgentResult> {
+  // 1. Pre-flight: log dir must exist so the stream can open.
+  const logDir = dirname(opts.logPath);
+  if (!existsSync(logDir)) {
+    try {
+      mkdirSync(logDir, { recursive: true });
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        error: `cannot create log dir ${logDir}: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  // 2. Build argv. Note: opencode run takes the prompt as a positional
+  // arg. `--dir` sets the worktree. `--print-logs` ensures the
+  // structured log stream goes to stderr.
+  const args: string[] = [
+    "opencode",
+    "run",
+    "--dir", opts.worktree,
+    "--print-logs",
+    "--log-level", "INFO",
+    "--title", opts.title || `bgr:${opts.agent}:${Date.now()}`,
+  ];
+  if (opts.model) {
+    args.push("--model", `${opts.model.providerID}/${opts.model.modelID}`);
+  }
+  // `--` separates flags from positional so a prompt starting with
+  // `-` is treated as a message.
+  args.push("--", opts.prompt);
+
+  // 3. Spawn the process.
+  let proc: Subprocess;
+  try {
+    proc = Bun.spawn(args, {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, ...(opts.env || {}) },
+    });
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      error: `failed to spawn opencode run: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // 4. Track the agent.
+  const rec: AgentRecord = {
+    status: {
+      state: "starting",
+      processId: proc.pid,
+      startedAt: Date.now(),
+    },
+    proc,
+    onExit: [],
+    spawnResolvers: [],
+  };
+  agents.set(proc.pid, rec);
+
+  // 5. Pipe stdout+stderr to the log file. Both go to the same file;
+  //    lines are prefixed [stdout] / [stderr] for readability.
+  const logStream = createWriteStream(opts.logPath, { flags: "a" });
+  const decoder = new TextDecoder("utf-8");
+  const sessionIdRegex = /message=created id=(ses_[A-Za-z0-9_]+)/;
+  let sessionId: string | undefined;
+
+  const resolveSpawnIfReady = (forceError?: string) => {
+    const resolvers = rec.spawnResolvers.splice(0);
+    if (resolvers.length === 0) return;
+    if (forceError) {
+      for (const r of resolvers) {
+        r({ ok: false, processId: proc.pid, error: forceError });
+      }
+      return;
+    }
+    if (sessionId) {
+      rec.status.state = "running";
+      for (const r of resolvers) {
+        r({ ok: true, sessionId, processId: proc.pid });
+      }
+    }
+  };
+
+  const readStream = async (
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+    label: "stderr" | "stdout",
+  ): Promise<void> => {
+    let buf = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = decoder.decode(value, { stream: true });
+        logStream.write(`[${label}] ${text}`);
+        if (label === "stderr" && !sessionId) {
+          buf += text;
+          const m = buf.match(sessionIdRegex);
+          if (m && m[1]) {
+            sessionId = m[1];
+            rec.status.sessionId = sessionId;
+            resolveSpawnIfReady();
+          }
+        }
+      }
+    } finally {
+      try { reader.releaseLock(); } catch { /* ignore */ }
+    }
+  };
+
+  // 6. Stream readers + exit handler — install BEFORE returning the
+  //    promise so a fast-exiting process still produces a clean
+  //    resolution.
+  const stderrReader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
+  const stdoutReader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+  void readStream(stderrReader, "stderr");
+  void readStream(stdoutReader, "stdout");
+
+  proc.exited
+    .then((exitCode: number | null) => {
+      const code = exitCode ?? -1;
+      rec.status.exitCode = exitCode ?? undefined;
+      rec.status.endedAt = Date.now();
+      if (rec.status.state !== "killed") {
+        rec.status.state = code === 0 ? "done" : "failed";
+        if (code !== 0 && !rec.status.error) {
+          rec.status.error = `opencode run exited with code ${code}`;
+        }
+      }
+      // Resolve any unresolved spawn promises.
+      if (!sessionId) {
+        resolveSpawnIfReady(rec.status.error || "opencode run exited before reporting session id");
+      }
+      // Fire subscribers.
+      const cbs = rec.onExit.splice(0);
+      for (const cb of cbs) {
+        try { cb({ ...rec.status }); } catch { /* ignore */ }
+      }
+      // Best-effort flush + close of the log stream.
+      try { logStream.end(); } catch { /* ignore */ }
+    })
+    .catch(() => {
+      // proc.exited only rejects if the proc was already awaited or
+      // never spawned; safe to ignore.
+    });
+
+  // 7. Race the spawn promise against a timeout. The default is 10s
+  //    which is plenty for opencode to print the "created" line on
+  //    a warm host (<500ms in practice).
+  const sessionIdTimeoutMs = opts.sessionIdTimeoutMs ?? 10_000;
+  return new Promise<SpawnAgentResult>((resolve) => {
+    rec.spawnResolvers.push(resolve);
+    setTimeout(() => {
+      if (!sessionId) {
+        resolveSpawnIfReady(
+          `opencode run did not report a session id within ${sessionIdTimeoutMs}ms`,
+        );
+      }
+    }, sessionIdTimeoutMs);
+  });
+}
+
+/**
+ * Snapshot the current status of an agent. Returns null if the
+ * processId is not tracked (e.g. the plugin restarted and lost its
+ * in-memory map).
+ */
+export function getStatus(processId: number): AgentStatus | null {
+  const rec = agents.get(processId);
+  if (!rec) return null;
+  return { ...rec.status };
+}
+
+/**
+ * Subscribe to the exit event. The callback fires exactly once when
+ * the process exits (whether naturally or via signal). Multiple
+ * subscribers are allowed; all of them fire in registration order.
+ *
+ * @returns unsubscribe function
+ */
+export function onExit(processId: number, cb: ExitCallback): () => void {
+  const rec = agents.get(processId);
+  if (!rec) return () => undefined;
+  rec.onExit.push(cb);
+  // If the agent has already exited, fire the callback immediately
+  // (next microtask) so the caller doesn't have to special-case
+  // pre-exited agents.
+  if (rec.status.endedAt !== undefined) {
+    queueMicrotask(() => {
+      try { cb({ ...rec.status }); } catch { /* ignore */ }
+    });
+  }
+  return () => {
+    const i = rec.onExit.indexOf(cb);
+    if (i >= 0) rec.onExit.splice(i, 1);
+  };
+}
+
+/**
+ * Kill the agent. Sends the requested signal (default SIGTERM),
+ * waits up to 5s, then SIGKILL. Idempotent.
+ */
+export function killAgent(
+  processId: number,
+  signal: "SIGTERM" | "SIGKILL" = "SIGTERM",
+): { ok: boolean; error?: string } {
+  const rec = agents.get(processId);
+  if (!rec) {
+    return { ok: true, error: "no such process tracked" };
+  }
+  if (rec.status.endedAt !== undefined) {
+    return { ok: true, error: "process already exited" };
+  }
+  rec.status.state = "killed";
+  try {
+    rec.proc.kill(signal);
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      error: `kill(${signal}) failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  // Schedule a forced kill after 5s in case SIGTERM is ignored.
+  setTimeout(() => {
+    if (rec.status.endedAt === undefined) {
+      try { rec.proc.kill("SIGKILL"); } catch { /* ignore */ }
+    }
+  }, 5_000);
+  return { ok: true };
+}
+
+/**
+ * List every tracked agent. Used by the plugin's startup to reconcile
+ * state and by tests.
+ */
+export function list(): AgentStatus[] {
+  return Array.from(agents.values()).map((r) => ({ ...r.status }));
+}
+
+/**
+ * For tests: clear the in-memory registry. Does NOT kill running
+ * processes — callers must `killAgent()` first if they want that.
+ */
+export function _resetForTests(): void {
+  agents.clear();
+}