@polderlabs/bizar 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {

package/packages/sdk/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@polderlabs/bizar-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./opencode": "./dist/opencode.js"
+  },
+  "files": ["dist"],
+  "peerDependencies": {
+    "@opencode-ai/sdk": "*"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/sdk": {
+      "optional": true
+    }
+  }
+}

package/packages/sdk/src/client.ts

@@ -67,6 +67,8 @@ export interface BizarClient {
   plans: PlansResource;
   events: EventsResource;
   health: HealthResource;
+  /** Change the base URL after the client was created. */
+  setBaseUrl(url: string): void;
 }
 
 export function createBizarClient(config: BizarClientConfig): BizarClient {
@@ -168,6 +170,9 @@ export function createBizarClient(config: BizarClientConfig): BizarClient {
         }
       },
     },
+    setBaseUrl(url: string) {
+      config.baseUrl = url;
+    },
   };
 }
 

package/packages/sdk/src/errors.ts

@@ -51,7 +51,15 @@ export type APIError = {
   };
 };
 
-export type BizarError = PluginError | DashboardError | ConnectionError | APIError;
+export type OpencodeConnectionError = {
+  name: "OpencodeConnectionError";
+  data: {
+    message: string;
+    cause?: unknown;
+  };
+};
+
+export type BizarError = PluginError | DashboardError | ConnectionError | APIError | OpencodeConnectionError;
 
 /**
  * Type guard: narrows `unknown` to `BizarError`.
@@ -64,7 +72,8 @@ export function isBizarError(value: unknown): value is BizarError {
     v.name === "PluginError" ||
     v.name === "DashboardError" ||
     v.name === "ConnectionError" ||
-    v.name === "APIError"
+    v.name === "APIError" ||
+    v.name === "OpencodeConnectionError"
   );
 }
 

package/packages/sdk/src/index.ts

@@ -27,6 +27,7 @@ export type {
   DashboardError,
   ConnectionError,
   APIError,
+  OpencodeConnectionError,
 } from "./errors.js";
 
 export type {
@@ -61,3 +62,21 @@ export type {
 } from "./types.js";
 
 export { SDK_VERSION } from "./version.js";
+
+// Opencode SDK — wraps the opencode serve child with a typed interface.
+// Tries `@opencode-ai/sdk` first; falls back to a thin fetch wrapper.
+export { createOpencodeSdk } from "./opencode.js";
+export type { OpencodeSdk, OpencodeSdkConfig } from "./opencode.js";
+
+export { subscribeOpencodeEvents } from "./opencode-events.js";
+export type {
+  OpencodeEventEnvelope,
+  OpencodeEventSubscribeOptions,
+} from "./opencode-events.js";
+
+export type {
+  OpencodeSession,
+  OpencodeMessage,
+  OpencodePart,
+  OpencodeEvent,
+} from "./opencode-types.js";

package/packages/sdk/src/opencode-events.ts

@@ -0,0 +1,134 @@
+/**
+ * SSE event iteration helper for the opencode serve child.
+ *
+ * Subscribes to the opencode SSE stream at `/event?directory=…`, filters
+ * by `sessionID` when provided, and yields parsed typed events.
+ *
+ * This module is consumed by the SDK's `events.subscribe()` and by the
+ * dashboard's chat SSE bridge.
+ */
+
+import { parseSseStream } from "./events.js";
+import type { EventSubscription } from "./events.js";
+
+/**
+ * Options for subscribing to the opencode event stream.
+ */
+export interface OpencodeEventSubscribeOptions {
+  /** AbortSignal to cancel the subscription early. */
+  signal?: AbortSignal;
+  /**
+   * When provided, only events whose `sessionID` matches are yielded.
+   * When omitted, all events are yielded.
+   */
+  sessionID?: string;
+  /**
+   * Optional baseUrl override (defaults to the SDK's configured baseUrl).
+   */
+  baseUrl?: string;
+  /**
+   * Optional auth header override.
+   */
+  authHeader?: string;
+  /**
+   * Injectable fetch. Defaults to global `fetch`.
+   */
+  fetch?: typeof fetch;
+}
+
+/**
+ * A single parsed opencode SSE event envelope.
+ */
+export interface OpencodeEventEnvelope {
+  type: string;
+  sessionID?: string;
+  messageID?: string;
+  part?: object;
+  data?: object;
+}
+
+/**
+ * Subscribe to opencode's SSE `/event` endpoint.
+ *
+ * @param baseUrl  e.g. "http://127.0.0.1:4097"
+ * @param authHeader  `Authorization: Basic …` value
+ * @param opts
+ */
+export async function subscribeOpencodeEvents(
+  baseUrl: string,
+  authHeader: string,
+  opts: OpencodeEventSubscribeOptions = {},
+): Promise<EventSubscription> {
+  const fetchImpl = opts.fetch ?? fetch;
+  const controller = new AbortController();
+  if (opts.signal) {
+    opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+
+  const url = new URL("/event", baseUrl);
+
+  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(`opencode event subscribe failed: ${response.status} ${response.statusText}`);
+  }
+
+  // Cast through unknown so the AsyncIterable<OpencodeEventEnvelope> satisfies
+  // the AsyncIterable<DashboardEvent> constraint from the existing EventSubscription type.
+  // The actual events flowing through are OpencodeEventEnvelope-shaped.
+  const filteredStream = filterOpencodeSseStream(response.body, controller, opts.sessionID);
+  return {
+    stream: filteredStream as unknown as EventSubscription["stream"],
+    close: () => controller.abort(),
+  };
+}
+
+/**
+ * Wrap `parseSseStream` with optional sessionID filtering.
+ */
+async function* filterOpencodeSseStream(
+  body: ReadableStream<Uint8Array>,
+  controller: AbortController,
+  sessionID?: string,
+): AsyncIterable<OpencodeEventEnvelope> {
+  for await (const raw of parseSseStream<OpencodeEventEnvelope>(body, controller)) {
+    if (!raw || typeof raw !== "object") continue;
+    const evt = raw as unknown as Record<string, unknown>;
+    // Unwrap sync envelope if present (mirrors serve-info.mjs:unwrapOpencodeSseEvent)
+    let unwrapped = evt;
+    if (evt.type === "sync" && evt.syncEvent && typeof evt.syncEvent === "object") {
+      const se = evt.syncEvent as Record<string, unknown>;
+      if (typeof se.type === "string") {
+        if (se.data && typeof se.data === "object") {
+          unwrapped = se.data as Record<string, unknown>;
+        }
+      }
+    }
+    const type = typeof unwrapped.type === "string" ? unwrapped.type : null;
+    if (!type) continue;
+    const evtSessionID = pickString(unwrapped, ["sessionID", "sessionId", "session_id"]);
+    if (sessionID && evtSessionID !== sessionID) continue;
+    yield {
+      type,
+      sessionID: evtSessionID,
+      messageID: pickString(unwrapped, ["messageID", "messageId", "message_id"]),
+      part: unwrapped.part && typeof unwrapped.part === "object" ? (unwrapped.part as object) : undefined,
+      data: unwrapped,
+    };
+  }
+}
+
+function pickString(obj: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return undefined;
+}

package/packages/sdk/src/opencode-types.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed wrappers for opencode SDK entities.
+ *
+ * We declare shapes structurally so that:
+ *   1. The package compiles even when `@opencode-ai/sdk` is not installed.
+ *   2. The shapes are stable regardless of which version of the upstream
+ *      SDK is installed (the upstream types are very complex and couple us
+ *      to internal class structure we don't need).
+ */
+
+export interface OpencodeSession {
+  id: string;
+  slug?: string;
+  projectID?: string;
+  workspaceID?: string;
+  directory?: string;
+  path?: string;
+  parentID?: string;
+  title?: string;
+  agent?: string;
+  model?: {
+    id: string;
+    providerID: string;
+    variant?: string;
+  };
+  time?: {
+    created: number;
+    updated: number;
+    compacting?: number;
+    archived?: number;
+  };
+}
+
+export interface OpencodeMessage {
+  info?: {
+    id?: string;
+    role?: string;
+    time?: {
+      created?: number;
+    };
+  };
+  id?: string;
+  role?: string;
+  parts?: OpencodePart[];
+  text?: string;
+  content?: string;
+}
+
+export type OpencodePart =
+  | { type: "text"; text: string }
+  | { type: "reasoning"; text: string }
+  | { type: "tool_call"; name: string; input: unknown }
+  | { type: "tool_result"; toolCallId: string; result: unknown }
+  | { type: "agent"; text: string }
+  | { type: "subtask"; text: string }
+  | { type: "file"; path: string; content?: string }
+  | { type: "step_start" | "step_finish" | "snapshot" | "patch" | "retry" | "compaction"; [key: string]: unknown };
+
+export interface OpencodeEvent {
+  type: string;
+  sessionID?: string;
+  messageID?: string;
+  part?: OpencodePart;
+  data?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+}

package/packages/sdk/src/opencode.ts

@@ -0,0 +1,335 @@
+/**
+ * Opencode SDK factory.
+ *
+ * Tries to load `@opencode-ai/sdk` dynamically. If the package is
+ * installed, `createOpencodeClient` from that package is used and its
+ * result is re-wrapped. If the import fails (package not installed), a
+ * thin fetch-based fallback is returned that hits the same REST endpoints.
+ *
+ * Auth: `Basic base64("opencode:<password>")` — matches the convention
+ * used by the opencode serve child.
+ *
+ * Reference: https://opencode.ai/docs/sdk/
+ */
+
+import { parseSseStream } from "./events.js";
+import { connectionErrorFrom, type BizarError } from "./errors.js";
+import type { EventSubscription } from "./events.js";
+import type { OpencodeEventEnvelope } from "./opencode-events.js";
+
+export interface OpencodeSdkConfig {
+  baseUrl: string;
+  /** Password for the opencode serve child. */
+  password?: string;
+  /** Injectable fetch for testing. */
+  fetch?: typeof fetch;
+  /** When true, errors are thrown; default false (return BizarError). */
+  throwOnError?: boolean;
+}
+
+/**
+ * Thin fetch-based opencode client, used when `@opencode-ai/sdk` is not
+ * installed in the consumer's project.
+ */
+interface FallbackOpencodeClient {
+  sessions: {
+    list(): Promise<unknown[]>;
+    get(input: { sessionId: string }): Promise<unknown>;
+    create(input: { title: string; agent: string }): Promise<{ id: string }>;
+    abort(input: { sessionId: string }): Promise<null>;
+    messages(input: { sessionId: string }): Promise<unknown[]>;
+    prompt(input: {
+      sessionId: string;
+      body: { text: string };
+      messageId?: string;
+    }): Promise<{ messageId: string }>;
+    promptAsync(input: { sessionId: string; body: { text: string } }): Promise<null>;
+  };
+  events: {
+    subscribe(opts?: {
+      signal?: AbortSignal;
+      sessionID?: string;
+      since?: number;
+    }): Promise<EventSubscription & { sessionID?: string }>;
+  };
+  health: {
+    check(): Promise<{ ok: boolean } | BizarError>;
+  };
+  server: {
+    close?(): void;
+  };
+}
+
+/**
+ * The SDK instance returned by `createOpencodeSdk`.
+ */
+export interface OpencodeSdk {
+  sessions: FallbackOpencodeClient["sessions"];
+  events: FallbackOpencodeClient["events"];
+  health: FallbackOpencodeClient["health"];
+  server: FallbackOpencodeClient["server"];
+}
+
+function makeAuthHeader(password: string): string {
+  const encoded = Buffer.from(`opencode:${password}`, "utf-8").toString("base64");
+  return `Basic ${encoded}`;
+}
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  fetchImpl: typeof fetch,
+  throwOnError: boolean,
+): Promise<T | BizarError> {
+  let response: Response;
+  try {
+    response = await fetchImpl(url, init);
+  } catch (err) {
+    const e = connectionErrorFrom(err);
+    if (throwOnError) throw e;
+    return e;
+  }
+  if (response.status === 204) return null as T;
+  const text = await response.text();
+  if (!response.ok) {
+    const err: BizarError = {
+      name: "APIError",
+      data: {
+        statusCode: response.status,
+        isRetryable: response.status >= 500 || response.status === 429,
+        message: `opencode API returned ${response.status}`,
+        responseBody: text,
+      },
+    };
+    if (throwOnError) throw err;
+    return err;
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null as T;
+  }
+}
+
+function createFallbackClient(config: OpencodeSdkConfig): FallbackOpencodeClient {
+  const { baseUrl, password = "", fetch: fetchImpl = fetch, throwOnError = false } = config;
+  const auth = makeAuthHeader(password);
+
+  async function request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T | BizarError> {
+    const url = `${baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: auth,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+    return fetchJson<T>(
+      url,
+      {
+        method,
+        headers,
+        body: body != null ? JSON.stringify(body) : undefined,
+      },
+      fetchImpl,
+      throwOnError,
+    );
+  }
+
+  return {
+    sessions: {
+      list: () => request<unknown[]>("GET", "/api/session") as Promise<unknown[]>,
+      get: ({ sessionId }) =>
+        request<unknown>("GET", `/api/session/${encodeURIComponent(sessionId)}`),
+      create: (input) =>
+        request<{ id: string }>("POST", "/api/session", input) as Promise<{ id: string }>,
+      abort: ({ sessionId }) =>
+        request<null>(
+          "POST",
+          `/api/session/${encodeURIComponent(sessionId)}/abort`,
+        ) as Promise<null>,
+      messages: ({ sessionId }) =>
+        request<unknown[]>(
+          "GET",
+          `/api/session/${encodeURIComponent(sessionId)}/message`,
+        ) as Promise<unknown[]>,
+      prompt: ({ sessionId, body, messageId }) =>
+        request<{ messageId: string }>(
+          "POST",
+          `/api/session/${encodeURIComponent(sessionId)}/prompt`,
+          { id: messageId, prompt: body },
+        ) as Promise<{ messageId: string }>,
+      promptAsync: ({ sessionId, body }) =>
+        request<null>(
+          "POST",
+          `/api/session/${encodeURIComponent(sessionId)}/prompt_async`,
+          body,
+        ) as Promise<null>,
+    },
+    events: {
+      subscribe: async (opts = {}) => {
+        const { signal, sessionID, since } = opts;
+        const url = new URL("/event", baseUrl);
+        if (typeof since === "number") {
+          url.searchParams.set("since", String(since));
+        }
+        const controller = new AbortController();
+        if (signal) {
+          signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        const response = await fetchImpl(url.toString(), {
+          method: "GET",
+          headers: {
+            Authorization: auth,
+            Accept: "text/event-stream",
+          },
+          signal: controller.signal,
+        });
+        if (!response.ok || !response.body) {
+          throw new Error(`event subscribe failed: ${response.status}`);
+        }
+        const sub: EventSubscription & { sessionID?: string } = {
+          sessionID,
+          // Cast through unknown to satisfy the AsyncIterable<DashboardEvent> constraint
+          // from the existing events.ts EventSubscription type. The actual yielded
+          // values are OpencodeEventEnvelope objects which are compatible.
+          stream: parseSseStream<OpencodeEventEnvelope>(
+            response.body,
+            controller,
+          ) as unknown as EventSubscription["stream"],
+          close: () => controller.abort(),
+        };
+        return sub;
+      },
+    },
+    health: {
+      check: async () => {
+        const url = `${baseUrl}/health`;
+        try {
+          const r = await fetchImpl(url, { method: "GET" });
+          if (!r.ok) {
+            const text = await r.text().catch(() => "");
+            const err: BizarError = {
+              name: "APIError",
+              data: {
+                statusCode: r.status,
+                isRetryable: r.status >= 500 || r.status === 429,
+                message: `opencode health check returned ${r.status}`,
+                responseBody: text,
+              },
+            };
+            if (throwOnError) throw err;
+            return err;
+          }
+          return { ok: true } as const;
+        } catch (err) {
+          const e = connectionErrorFrom(err);
+          if (throwOnError) throw e;
+          return e;
+        }
+      },
+    },
+    server: {},
+  };
+}
+
+/**
+ * Create an opencode SDK instance.
+ *
+ * Tries to use `@opencode-ai/sdk`'s `createOpencodeClient` if installed;
+ * falls back to a thin fetch-based client otherwise.
+ *
+ * @param opts  `{ baseUrl, password?, fetch?, throwOnError? }`
+ */
+export async function createOpencodeSdk(
+  opts: OpencodeSdkConfig,
+): Promise<OpencodeSdk> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = await import("@opencode-ai/sdk/v2/client") as any;
+    const createClient = mod.createOpencodeClient;
+    if (typeof createClient !== "function") throw new Error("not a function");
+
+    const headers: Record<string, string> = {};
+    if (opts.password) {
+      headers["Authorization"] = makeAuthHeader(opts.password);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const inner = createClient({
+      baseUrl: opts.baseUrl,
+      fetch: opts.fetch as any,
+      headers,
+      // The upstream SDK accepts different options; ignore unknown ones.
+    } as any) as any;
+
+    // The @opencode-ai/sdk client has a very different internal structure
+    // (HeyApi pattern with .session.list(), .session.create(), etc.).
+    // We wrap it to match the FallbackOpencodeClient interface expected
+    // by the dashboard.
+    const wrapped: OpencodeSdk = {
+      sessions: {
+        list: async () => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const r = await (inner.session?.list?.() ?? inner.sessions?.list?.()) as any;
+          return r ?? [];
+        },
+        get: async ({ sessionId }) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return (await (inner.session?.get?.({ sessionID: sessionId } as any) ?? inner.sessions?.get?.({ sessionId } as any))) as unknown;
+        },
+        create: async (input) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const r = await (inner.session?.create?.(input as any) ?? inner.sessions?.create?.(input as any)) as any;
+          return { id: r?.data?.id ?? r?.id ?? "" };
+        },
+        abort: async ({ sessionId }) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return (await (inner.session?.abort?.({ sessionID: sessionId } as any) ?? inner.sessions?.abort?.({ sessionId } as any))) as null;
+        },
+        messages: async ({ sessionId }) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const r = await (inner.session?.messages?.({ sessionID: sessionId } as any) ?? inner.sessions?.messages?.({ sessionId } as any)) as any;
+          return r?.data ?? r ?? [];
+        },
+        prompt: async ({ sessionId, body, messageId }) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const r = await (inner.session?.prompt?.({ sessionID: sessionId, prompt: body, id: messageId } as any) ?? inner.sessions?.prompt?.({ sessionId, body, messageId } as any)) as any;
+          return { messageId: r?.messageId ?? messageId ?? "" };
+        },
+        promptAsync: async ({ sessionId, body }) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return (await (inner.session?.promptAsync?.({ sessionID: sessionId, prompt: body } as any) ?? inner.sessions?.promptAsync?.({ sessionId, body } as any))) as null;
+        },
+      },
+      events: {
+        subscribe: async (opts = {}) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const sub = await (inner.event?.subscribe?.(opts as any) ?? inner.events?.subscribe?.(opts as any)) as any;
+          return {
+            stream: sub?.stream as EventSubscription["stream"],
+            close: () => sub?.close?.(),
+          };
+        },
+      },
+      health: {
+        check: async () => {
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const r = await (inner.global?.health?.() ?? inner.health?.check?.()) as any;
+            return { ok: r?.ok !== false };
+          } catch {
+            return { ok: false };
+          }
+        },
+      },
+      server: inner.server ?? {},
+    };
+    return wrapped;
+  } catch {
+    // `@opencode-ai/sdk` not installed or incompatible — use the fallback.
+    return createFallbackClient(opts);
+  }
+}