@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/compaction.d.mts

@@ -1,48 +0,0 @@
-/**
- * Type declarations for `./compaction.mjs`.
- *
- * The runtime module is shipped as plain ESM JavaScript (`.mjs`) per the
- * brief, but its consumers in `index.ts` and `tests/compaction.test.ts`
- * are TypeScript. Without this companion declaration file, TypeScript
- * would type the exports as `any`, which causes cascading `implicitly
- * has 'any' type` errors at call sites (e.g. the `texts` parameter in
- * the test's `summarizer` stubs).
- *
- * The declarations here mirror the contract documented in
- * `./compaction.mjs`. They are NOT loaded at runtime — they exist only
- * for the type-checker.
- */
-
-export interface CompactionResult {
-    compacted: boolean;
-    reason?: "below_threshold";
-    sessionId?: string;
-    threshold?: number;
-    preservedRecent?: number;
-    atMessages?: number;
-    ratio?: number | null;
-}
-
-export interface MaybeCompactSessionOpts {
-    sessionId: string;
-    messageCount: number;
-    currentUsage: { total?: number } | null | undefined;
-    maxContext: number | null | undefined;
-    summarizer: (texts: string[]) => Promise<string>;
-    preserveRecent?: number;
-}
-
-export function shouldCompact(
-    usage: { total?: number } | null | undefined,
-    maxContext: number | null | undefined,
-): boolean;
-
-export function maybeCompactSession(opts: MaybeCompactSessionOpts): Promise<CompactionResult>;
-
-export function getCompactionThreshold(): number;
-
-export function setCompactionThreshold(value: number): void;
-
-export function resetCompactionDefaults(): void;
-
-export function getDefaultPreserveRecent(): number;

package/plugins/bizar/src/compaction.mjs

@@ -1,192 +0,0 @@
-/**
- * compaction.mjs
- *
- * Context-window compaction gate.
- *
- * Monitors a chat session's context-usage ratio and reports whether the
- * session has reached the compaction threshold (default 50% of the model's
- * max-context window). When the ratio crosses the threshold, callers can
- * trigger summarization of the older message history while preserving a
- * configurable recent tail so the model retains short-term continuity.
- *
- * Spec contract:
- *   - The threshold is the *ratio* `usage.total / maxContext`, NOT an
- *     absolute token count. This makes the gate model-agnostic — it works
- *     whether the model has a 32k, 128k, or 1M context window.
- *   - `shouldCompact` is a pure function: same inputs → same output, no I/O.
- *   - `maybeCompactSession` is async to match the real summarizer signature
- *     but performs no I/O itself when below threshold — it short-circuits.
- *   - Threshold is mutable via `setCompactionThreshold` and is validated
- *     against the range [0.1, 1.0]. A throw is the right signal here —
- *     misconfiguration should fail loudly at startup, not silently use a
- *     bad value at runtime.
- *   - Threshold uses `let` (not `const`) so the setter can mutate it.
- *     The reference spec used `const` and would throw a TypeError on
- *     assignment; this implementation keeps the API but fixes the bug.
- */
-
-const PRESERVE_RECENT_MESSAGES_DEFAULT = 10;
-const MIN_THRESHOLD = 0.1;
-const MAX_THRESHOLD = 1.0;
-
-// Module-level threshold. Exposed via get/set for tunability.
-// Exported as a number via getCompactionThreshold(); the underlying binding
-// is private (not exported) so callers cannot bypass validation by writing
-// to it directly.
-let compactionThreshold = 0.5;
-
-/**
- * Returns `true` when `usage.total / maxContext` meets or exceeds the
- * compaction threshold. `false` when below, or when either input is
- * missing/invalid (defensive default).
- *
- * @param {{ total?: number } | null | undefined} usage
- *   Object with a `total` token count, or null/undefined.
- * @param {number | null | undefined} maxContext
- *   Maximum context window size in tokens.
- * @returns {boolean}
- */
-export function shouldCompact(usage, maxContext) {
-  if (!usage || typeof usage.total !== "number") return false;
-  if (typeof maxContext !== "number" || maxContext <= 0) return false;
-  const ratio = usage.total / maxContext;
-  return ratio >= compactionThreshold;
-}
-
-/**
- * Decision-shaped result returned by `maybeCompactSession`.
- *
- * - When below threshold: `{ compacted: false, reason: "below_threshold", ratio }`.
- * - When at/over threshold: `{ compacted: true, sessionId, threshold,
- *   preservedRecent, atMessages, ratio }`.
- *
- * @typedef {Object} CompactionResult
- * @property {boolean} compacted
- * @property {"below_threshold"} [reason]              when compacted=false
- * @property {string} [sessionId]
- * @property {number} [threshold]                     the threshold at decision time
- * @property {number} [preservedRecent]               how many recent messages to keep verbatim
- * @property {number} [atMessages]                    message count at decision time
- * @property {number} [ratio]                         usage.total / maxContext
- */
-
-/**
- * Decide whether to compact and, if so, record the decision. The summarizer
- * is NOT invoked here — that is the caller's responsibility. This function
- * is the decision gate, not the executor. (The summarizer receives an
- * `Array<string>` of older messages and returns a single summary string.)
- *
- * @param {Object}   opts
- * @param {string}   opts.sessionId
- * @param {number}   opts.messageCount                total messages in the session
- * @param {{ total?: number } | null | undefined} opts.currentUsage
- * @param {number | null | undefined} opts.maxContext
- * @param {(texts: string[]) => Promise<string>} opts.summarizer
- *   Async summarizer used by the caller when `compacted === true`. Not invoked
- *   here. Accepting it as a parameter documents the contract for downstream
- *   callers without forcing this function to do I/O.
- * @param {number}   [opts.preserveRecent=10]         how many recent messages to keep verbatim
- * @returns {Promise<CompactionResult>}
- */
-export async function maybeCompactSession({
-  sessionId,
-  messageCount,
-  currentUsage,
-  maxContext,
-  // summarizer is accepted for API symmetry with downstream callers; we do
-  // not invoke it here because compaction execution lives in the plugin
-  // hook layer, not in this pure decision gate.
-  summarizer, // eslint-disable-line no-unused-vars
-  preserveRecent = PRESERVE_RECENT_MESSAGES_DEFAULT,
-}) {
-  if (typeof sessionId !== "string" || sessionId === "") {
-    // Misuse — caller forgot a sessionId. Refuse rather than silently
-    // returning below_threshold, which would mask a real bug upstream.
-    throw new Error("maybeCompactSession: sessionId is required");
-  }
-
-  if (!shouldCompact(currentUsage, maxContext)) {
-    const ratio = computeRatio(currentUsage, maxContext);
-    return { compacted: false, reason: "below_threshold", ratio };
-  }
-
-  const ratio = computeRatio(currentUsage, maxContext);
-  return {
-    compacted: true,
-    sessionId,
-    threshold: compactionThreshold,
-    preservedRecent: preserveRecent,
-    atMessages: messageCount,
-    ratio,
-  };
-}
-
-/**
- * Return the current compaction threshold (0.0–1.0).
- *
- * @returns {number}
- */
-export function getCompactionThreshold() {
-  return compactionThreshold;
-}
-
-/**
- * Set the compaction threshold. Validates the new value is in the range
- * `[0.1, 1.0]` and is a finite number. Throws on invalid input.
- *
- * The minimum of 0.1 prevents pathological "compact at 10%" configurations
- * that would shred the conversation on the first reply. The maximum of 1.0
- * means "compact only when the context is full" — anything above 1.0 would
- * mean "never compact", which `shouldCompact` already handles correctly, so
- * we reject it for clarity.
- *
- * @param {number} value
- * @returns {void}
- */
-export function setCompactionThreshold(value) {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`Invalid compaction threshold: ${value} (must be a finite number)`);
-  }
-  if (value < MIN_THRESHOLD || value > MAX_THRESHOLD) {
-    throw new Error(
-      `Invalid compaction threshold: ${value} (must be in [${MIN_THRESHOLD}, ${MAX_THRESHOLD}])`,
-    );
-  }
-  compactionThreshold = value;
-}
-
-/**
- * Reset the threshold and preserve-count to their defaults. Exposed for
- * tests and for plugin re-init (so a hot-reload doesn't carry stale state).
- *
- * @returns {void}
- */
-export function resetCompactionDefaults() {
-  compactionThreshold = 0.5;
-}
-
-/**
- * Return the number of recent messages that the default policy preserves
- * verbatim when compacting.
- *
- * @returns {number}
- */
-export function getDefaultPreserveRecent() {
-  return PRESERVE_RECENT_MESSAGES_DEFAULT;
-}
-
-// --- Internal helpers -----------------------------------------------------
-
-/**
- * Compute `usage.total / maxContext`, or `null` when either input is
- * missing/invalid. Returns a number in `[0, +Infinity)` for valid inputs.
- *
- * @param {{ total?: number } | null | undefined} usage
- * @param {number | null | undefined} maxContext
- * @returns {number | null}
- */
-function computeRatio(usage, maxContext) {
-  if (!usage || typeof usage.total !== "number") return null;
-  if (typeof maxContext !== "number" || maxContext <= 0) return null;
-  return usage.total / maxContext;
-}

package/plugins/bizar/src/dashboard-client.ts

@@ -1,233 +0,0 @@
-/**
- * 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 { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-// v4.0.0 — SDK is part of the same package at packages/sdk/.
-// The SDK must be built (npm run build:sdk) before the plugin is compiled.
-import { createBizarClient, isBizarError } from "../../../packages/sdk/dist/index.js";
-import type { BizarClient, DashboardEvent } from "../../../packages/sdk/dist/index.js";
-
-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 };
-}