@polderlabs/bizar 3.23.1 → 4.2.0

package/packages/sdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DrB0rk / BizarHarness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/sdk/README.md

@@ -0,0 +1,80 @@
+# @polderlabs/bizar-sdk
+
+Typed SDK for the BizarHarness plugin ↔ dashboard communication protocol.
+
+This package is the **shared types + client library** used by both:
+- The Bizar opencode plugin (`@polderlabs/bizar-plugin`) — publishes events to the dashboard.
+- The Bizar dashboard (`@polderlabs/bizar-dash`) — exposes REST + SSE endpoints and consumes events.
+
+It replaces the legacy file-based `serve.json` bridge with a typed HTTP + SSE protocol sourced from an OpenAPI 3.1 spec.
+
+## Install
+
+```bash
+npm install @polderlabs/bizar-sdk
+```
+
+## Usage
+
+```ts
+import { createBizarClient, SDK_VERSION } from "@polderlabs/bizar-sdk";
+
+const client = createBizarClient({
+  baseUrl: process.env.BIZAR_DASHBOARD_URL ?? "http://127.0.0.1:4098",
+  password: process.env.BIZAR_DASHBOARD_PASSWORD ?? readPasswordFromAuthFile(),
+});
+
+// REST — resource-grouped methods
+const sessions = await client.sessions.list({ status: "running" });
+const session = await client.sessions.create({
+  agent: "mimir",
+  prompt: "Research the latest opencode serve API.",
+});
+
+// SSE — async iterable
+const sub = await client.events.subscribe();
+for await (const event of sub.stream) {
+  // event.type is a discriminated string: "session.created" | "session.updated" | …
+  // event.properties is the typed payload
+  console.log(event.type, event.properties);
+}
+
+// Errors are returned by default (not thrown). Discriminated by `name`.
+const result = await client.sessions.get({ sessionId: "ses_xyz" });
+if ("name" in result && result.name === "DashboardError") {
+  console.error("dashboard error:", result.data);
+}
+```
+
+## Architecture
+
+```
+                ┌────────────────────────────┐
+                │ opencode + Bizar plugin    │
+                │  (publishes events)        │
+                └──────────────┬─────────────┘
+                               │ HTTP + SSE
+                               │ (this SDK)
+                ┌──────────────▼─────────────┐
+                │ Bizar dashboard server     │
+                │  (subscribes, exposes UI)  │
+                └────────────────────────────┘
+```
+
+## Transport
+
+- **REST (JSON)** for request/response CRUD operations.
+- **SSE (`text/event-stream`)** for live events — single endpoint at `GET /event`.
+- **No WebSocket** anywhere in the protocol.
+
+## Auth
+
+HTTP basic with the dashboard-generated password. The dashboard writes the password to `~/.cache/bizarharness/dash-auth.json` (mode 0600) on first start. The plugin reads this file or accepts `BIZAR_DASHBOARD_PASSWORD` env var override.
+
+## Source of Truth
+
+The API surface is defined in [OPENAPI_SPEC.yaml](../../.bizar/research/OPENAPI_SPEC.yaml). TypeScript types in `src/types.ts` are hand-written to match the spec exactly. In v0.7.1, types will be auto-generated via `@hey-api/openapi-ts` from that spec.
+
+## License
+
+MIT

package/packages/sdk/src/client.ts

@@ -0,0 +1,183 @@
+/**
+ * BizarHarness SDK client factory.
+ *
+ * Mirrors the opencode SDK pattern: a single `createBizarClient(config)`
+ * call returns a typed client with resource-grouped methods. The client
+ * handles auth header injection, response unwrapping, and error mapping
+ * via the discriminated BizarError union.
+ *
+ * Reference: https://opencode.ai/docs/sdk/ (createOpencodeClient).
+ */
+
+import {
+  apiErrorFrom,
+  connectionErrorFrom,
+  dashboardErrorFrom,
+  type BizarError,
+} from "./errors.js";
+import { subscribeEvents, type EventSubscription } from "./events.js";
+import type {
+  DashboardEvent,
+  Health,
+  Plan,
+  Project,
+  Session,
+  SessionCreate,
+  SessionListQuery,
+} from "./types.js";
+
+export interface BizarClientConfig {
+  baseUrl: string;
+  password: string;
+  /** Injectable fetch for testing. Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+  /** When true, errors are thrown. Default false (return BizarError). */
+  throwOnError?: boolean;
+  /** Extra headers to attach to every request. */
+  headers?: Record<string, string>;
+}
+
+export interface SessionsResource {
+  list(query?: SessionListQuery): Promise<Session[] | BizarError>;
+  get(input: { sessionId: string }): Promise<Session | BizarError>;
+  create(input: SessionCreate): Promise<Session | BizarError>;
+  abort(input: { sessionId: string }): Promise<null | BizarError>;
+}
+
+export interface ProjectsResource {
+  list(): Promise<Project[] | BizarError>;
+}
+
+export interface PlansResource {
+  list(): Promise<Plan[] | BizarError>;
+}
+
+export interface EventsResource {
+  subscribe(opts?: { signal?: AbortSignal; since?: number }): Promise<EventSubscription>;
+  publish(event: DashboardEvent): Promise<null | BizarError>;
+}
+
+export interface HealthResource {
+  check(): Promise<Health | BizarError>;
+}
+
+export interface BizarClient {
+  sessions: SessionsResource;
+  projects: ProjectsResource;
+  plans: PlansResource;
+  events: EventsResource;
+  health: HealthResource;
+}
+
+export function createBizarClient(config: BizarClientConfig): BizarClient {
+  const fetchImpl = config.fetch ?? fetch;
+  const authHeader = makeAuthHeader(config.password);
+  const baseHeaders: Record<string, string> = {
+    Authorization: authHeader,
+    Accept: "application/json",
+    ...(config.headers ?? {}),
+  };
+
+  async function request<T>(
+    method: string,
+    path: string,
+    init?: { body?: unknown; query?: Record<string, string | number | undefined> },
+  ): Promise<T | BizarError> {
+    const url = new URL(path, config.baseUrl);
+    if (init?.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== undefined) url.searchParams.set(k, String(v));
+      }
+    }
+
+    const headers: Record<string, string> = { ...baseHeaders };
+    let body: string | undefined;
+    if (init?.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(init.body);
+    }
+
+    let response: Response;
+    try {
+      response = await fetchImpl(url.toString(), {
+        method,
+        headers,
+        body,
+      });
+    } catch (err) {
+      const error = connectionErrorFrom(err);
+      if (config.throwOnError) throw error;
+      return error;
+    }
+
+    if (response.status === 204) {
+      return null as T;
+    }
+
+    const text = await response.text();
+
+    if (!response.ok) {
+      // 5xx and 429 → APIError (retryable); everything else → DashboardError.
+      const error =
+        response.status >= 500 || response.status === 429
+          ? apiErrorFrom(response.status, text)
+          : dashboardErrorFrom(response.status, text);
+      if (config.throwOnError) throw error;
+      return error;
+    }
+
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      // Empty body or non-JSON; return null for caller to handle.
+      return null as T;
+    }
+  }
+
+  return {
+    sessions: {
+      list: (query) =>
+        request<Session[]>("GET", "/sessions", { query: query as Record<string, string | number | undefined> }),
+      get: ({ sessionId }) =>
+        request<Session>("GET", `/sessions/${encodeURIComponent(sessionId)}`),
+      create: (input) => request<Session>("POST", "/sessions", { body: input }),
+      abort: ({ sessionId }) =>
+        request<null>("DELETE", `/sessions/${encodeURIComponent(sessionId)}`),
+    },
+    projects: {
+      list: () => request<Project[]>("GET", "/projects"),
+    },
+    plans: {
+      list: () => request<Plan[]>("GET", "/plans"),
+    },
+    events: {
+      subscribe: (opts) => subscribeEvents(config.baseUrl, authHeader, opts, fetchImpl),
+      publish: (event) => request<null>("POST", "/event", { body: event }),
+    },
+    health: {
+      check: async () => {
+        const url = new URL("/health", config.baseUrl);
+        try {
+          const r = await fetchImpl(url.toString(), { method: "GET" });
+          if (!r.ok) return dashboardErrorFrom(r.status, await r.text());
+          return (await r.json()) as Health;
+        } catch (err) {
+          const e = connectionErrorFrom(err);
+          if (config.throwOnError) throw e;
+          return e;
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Build the `Authorization: Basic …` header value.
+ * Username is `opencode` per the opencode convention used by BizarHarness.
+ */
+function makeAuthHeader(password: string): string {
+  const credentials = `opencode:${password}`;
+  // Buffer.from is available in both Node (≥ 16) and Bun.
+  const encoded = Buffer.from(credentials, "utf-8").toString("base64");
+  return `Basic ${encoded}`;
+}

package/packages/sdk/src/errors.ts

@@ -0,0 +1,120 @@
+/**
+ * Discriminated error model for the BizarHarness SDK.
+ *
+ * Errors are RETURNED (not thrown) by default, matching the opencode SDK
+ * pattern. Set `throwOnError: true` in the client config to opt into
+ * throwing.
+ *
+ * Discriminate via the `name` field:
+ *
+ *   const result = await client.sessions.get({ sessionId });
+ *   if (isBizarError(result)) {
+ *     switch (result.name) {
+ *       case "DashboardError": ...
+ *       case "ConnectionError": ...
+ *       case "APIError": ...
+ *     }
+ *   }
+ */
+
+export type PluginError = {
+  name: "PluginError";
+  data: {
+    code: string;
+    message: string;
+  };
+};
+
+export type DashboardError = {
+  name: "DashboardError";
+  data: {
+    statusCode: number;
+    message: string;
+  };
+};
+
+export type ConnectionError = {
+  name: "ConnectionError";
+  data: {
+    message: string;
+    cause?: unknown;
+  };
+};
+
+export type APIError = {
+  name: "APIError";
+  data: {
+    statusCode: number;
+    isRetryable: boolean;
+    message: string;
+    responseBody?: string;
+  };
+};
+
+export type BizarError = PluginError | DashboardError | ConnectionError | APIError;
+
+/**
+ * Type guard: narrows `unknown` to `BizarError`.
+ */
+export function isBizarError(value: unknown): value is BizarError {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { name?: unknown };
+  if (typeof v.name !== "string") return false;
+  return (
+    v.name === "PluginError" ||
+    v.name === "DashboardError" ||
+    v.name === "ConnectionError" ||
+    v.name === "APIError"
+  );
+}
+
+/**
+ * Convenience: build a ConnectionError from a thrown fetch failure.
+ */
+export function connectionErrorFrom(err: unknown): ConnectionError {
+  if (err instanceof Error) {
+    return {
+      name: "ConnectionError",
+      data: { message: err.message, cause: err },
+    };
+  }
+  return {
+    name: "ConnectionError",
+    data: { message: String(err), cause: err },
+  };
+}
+
+/**
+ * Convenience: build a DashboardError from a non-OK HTTP response.
+ */
+export function dashboardErrorFrom(status: number, body: string): DashboardError {
+  let message = `HTTP ${status}`;
+  try {
+    const parsed = JSON.parse(body) as { data?: { message?: string }; message?: string };
+    if (parsed.data?.message) message = parsed.data.message;
+    else if (parsed.message) message = parsed.message;
+  } catch {
+    // body wasn't JSON; fall back to status-only message
+  }
+  return {
+    name: "DashboardError",
+    data: { statusCode: status, message },
+  };
+}
+
+/**
+ * Convenience: build an APIError from a 5xx or specific 4xx response.
+ * 5xx and 429 are retryable.
+ */
+export function apiErrorFrom(status: number, body: string): APIError {
+  const isRetryable = status >= 500 || status === 429;
+  return {
+    name: "APIError",
+    data: {
+      statusCode: status,
+      isRetryable,
+      message: `Dashboard API returned ${status}`,
+      responseBody: body,
+    },
+  };
+}

package/packages/sdk/src/events.ts

@@ -0,0 +1,153 @@
+/**
+ * SSE event subscriber for the BizarHarness SDK.
+ *
+ * Wraps the opencode-style SSE format:
+ *
+ *   event: <type>
+ *   data: {"type": "<type>", "properties": { ... }}
+ *
+ * Returns an async iterable + close handle.
+ *
+ * Reference: opencode SDK pattern (`for await (const event of events.stream)`).
+ */
+
+import type { DashboardEvent } from "./types.js";
+
+export interface EventSubscriptionOptions {
+  signal?: AbortSignal;
+  /** Replay events from this sequence number (buffered by dashboard). */
+  since?: number;
+}
+
+export interface EventSubscription {
+  stream: AsyncIterable<DashboardEvent>;
+  close(): void;
+}
+
+/**
+ * Subscribe to dashboard events. The returned stream yields parsed
+ * `DashboardEvent` instances.
+ *
+ * If `signal` aborts, the underlying fetch is aborted and the stream ends.
+ */
+export async function subscribeEvents(
+  baseUrl: string,
+  authHeader: string,
+  opts: EventSubscriptionOptions = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<EventSubscription> {
+  const url = new URL("/event", baseUrl);
+  if (typeof opts.since === "number") {
+    url.searchParams.set("since", String(opts.since));
+  }
+
+  const controller = new AbortController();
+  if (opts.signal) {
+    opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+
+  const response = await fetchImpl(url.toString(), {
+    method: "GET",
+    headers: {
+      Authorization: authHeader,
+      Accept: "text/event-stream",
+    },
+    signal: controller.signal,
+  });
+
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `SSE subscribe failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const stream = parseSseStream<DashboardEvent>(response.body, controller);
+  return {
+    stream,
+    close: () => controller.abort(),
+  };
+}
+
+/**
+ * Parse an SSE byte stream into a typed async iterable.
+ *
+ * Handles the opencode SSE format: lines starting with `event:` and `data:`.
+ * Lines beginning with `:` are comments (ignored). Empty lines delimit events.
+ *
+ * Yields parsed events as `{ type, properties, ... }` objects (the JSON
+ * decoded value of the `data:` line).
+ */
+export async function* parseSseStream<T extends { type: string }>(
+  body: ReadableStream<Uint8Array>,
+  controller: AbortController,
+): AsyncIterable<T> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // SSE events are delimited by a blank line.
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const raw = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const parsed = parseSseEvent(raw);
+        if (parsed !== null) {
+          yield parsed as T;
+        }
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+
+    // Flush any trailing event without a blank line terminator.
+    if (buffer.trim().length > 0) {
+      const parsed = parseSseEvent(buffer);
+      if (parsed !== null) yield parsed as T;
+    }
+  } finally {
+    reader.releaseLock();
+    controller.abort();
+  }
+}
+
+function parseSseEvent(raw: string): unknown | null {
+  let eventType: string | null = null;
+  const dataLines: string[] = [];
+
+  for (const line of raw.split("\n")) {
+    if (line.length === 0) continue;
+    if (line.startsWith(":")) continue; // comment
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const field = line.slice(0, colonIdx);
+    let value = line.slice(colonIdx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    if (field === "event") {
+      eventType = value;
+    } else if (field === "data") {
+      dataLines.push(value);
+    }
+  }
+
+  if (dataLines.length === 0) return null;
+  const data = dataLines.join("\n");
+
+  try {
+    const parsed = JSON.parse(data) as { type?: string; properties?: unknown };
+    // Prefer the SSE `event:` line; fall back to JSON's `type` field.
+    if (eventType && parsed.type !== eventType) {
+      return { ...parsed, type: eventType };
+    }
+    return parsed;
+  } catch {
+    // Malformed JSON — skip this event rather than crash the stream.
+    return null;
+  }
+}

package/packages/sdk/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Public API for @polderlabs/bizar-sdk.
+ */
+
+export { createBizarClient } from "./client.js";
+export type {
+  BizarClient,
+  BizarClientConfig,
+  SessionsResource,
+  ProjectsResource,
+  PlansResource,
+  EventsResource,
+  HealthResource,
+} from "./client.js";
+
+export type { EventSubscription, EventSubscriptionOptions } from "./events.js";
+
+export {
+  isBizarError,
+  connectionErrorFrom,
+  dashboardErrorFrom,
+  apiErrorFrom,
+} from "./errors.js";
+export type {
+  BizarError,
+  PluginError,
+  DashboardError,
+  ConnectionError,
+  APIError,
+} from "./errors.js";
+
+export type {
+  // Session
+  Session,
+  SessionStatus,
+  SessionCreate,
+  SessionListQuery,
+  // Project
+  Project,
+  // Plan
+  Plan,
+  PlanStatus,
+  // Part
+  Part,
+  TextPart,
+  ToolCallPart,
+  ToolResultPart,
+  ReasoningPart,
+  // Event
+  DashboardEvent,
+  DashboardConnectedEvent,
+  SessionCreatedEvent,
+  SessionUpdatedEvent,
+  SessionIdleEvent,
+  SessionErrorEvent,
+  MessagePartUpdatedEvent,
+  ToolExecutedEvent,
+  PlanUpdatedEvent,
+  // Health
+  Health,
+} from "./types.js";
+
+export { SDK_VERSION } from "./version.js";