pi-bifrost 0.1.0

package/debug.ts

@@ -0,0 +1,169 @@
+// ── Structured debug logging with Performance API ──────────────────
+// Buffered async writes. No sync I/O on the hot path — events are
+// queued in memory and flushed via setImmediate. On process exit the
+// remaining buffer is flushed synchronously.
+//
+// Configure: { "debug": { "enabled": true, "path": ".pi/bifrost-debug.jsonl" } }
+
+import { existsSync, mkdirSync } from "node:fs";
+import { appendFile, rename, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { performance } from "node:perf_hooks";
+import { appendFileSync } from "node:fs";
+
+export interface DebugConfig {
+  enabled?: boolean;
+  path?: string;
+}
+
+const DEFAULT_MAX_SIZE_MB = 10;
+
+let debugEnabled = false;
+let debugPath: string | null = null;
+const maxSizeBytes: number = DEFAULT_MAX_SIZE_MB * 1024 * 1024;
+let startupDone = false;
+
+// ── Async write buffer ────────────────────────────────────────────
+
+let buffer: string[] = [];
+let flushScheduled = false;
+let flushing = false;
+
+async function rotateIfNeeded(): Promise<void> {
+  if (!debugPath) return;
+  try {
+    const info = await stat(debugPath).catch(() => null);
+    if (info && info.size > maxSizeBytes) {
+      await rename(debugPath, debugPath.replace(/\.jsonl$/, ".old.jsonl")).catch(() => {});
+    }
+  } catch { /* ignore */ }
+}
+
+async function flushBuffer(): Promise<void> {
+  // Write lock: only one flush runs at a time. Prevents interleaved
+  // appendFile calls that would corrupt JSONL.
+  if (flushing) return;
+  flushing = true;
+  flushScheduled = false;
+
+  while (buffer.length > 0 && debugPath) {
+    const lines = buffer.join("\n") + "\n";
+    buffer = [];
+    try {
+      await rotateIfNeeded();
+      await appendFile(debugPath, lines, "utf-8");
+    } catch (err) {
+      try {
+        process.stderr.write(`[bifrost] debug write failed: ${err}\n`);
+      } catch { /* silence */ }
+    }
+  }
+
+  flushing = false;
+  // New entries may have arrived during the await.
+  if (buffer.length > 0) scheduleFlush();
+}
+
+function scheduleFlush(): void {
+  if (!flushScheduled && !flushing) {
+    flushScheduled = true;
+    setImmediate(flushBuffer);
+  }
+  // If already flushing, the running flush will drain the buffer
+  // and re-schedule if more entries arrive.
+}
+
+/** Synchronous flush for process.exit (must be sync). */
+function flushSync(): void {
+  if (buffer.length === 0 || !debugPath) return;
+  const lines = buffer.join("\n") + "\n";
+  buffer = [];
+  try {
+    appendFileSync(debugPath, lines, "utf-8");
+  } catch { /* silence */ }
+}
+
+// ── Setup ─────────────────────────────────────────────────────────
+
+export function setupDebug(cfg: DebugConfig, cwd: string) {
+  debugEnabled = cfg.enabled ?? false;
+  if (cfg.path) {
+    debugPath = cfg.path.startsWith("/") || cfg.path.startsWith("~")
+      ? cfg.path.replace(/^~/, process.env.HOME ?? "/tmp")
+      : `${cwd}/${cfg.path}`;
+  } else {
+    debugPath = `${cwd}/.pi/bifrost-debug.jsonl`;
+  }
+
+  if (debugEnabled && !startupDone) {
+    startupDone = true;
+    try {
+      const dir = dirname(debugPath);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    } catch (err) {
+      process.stderr.write(`[bifrost] debug: cannot create log dir: ${err}\n`);
+      debugEnabled = false;
+      return;
+    }
+
+    // Flush remaining on exit (sync — exit hook cannot do async I/O).
+    process.on("exit", () => {
+      buffer.push(JSON.stringify({ ts: new Date().toISOString(), module: "bifrost", event: "shutdown", entryType: "event" }));
+      flushSync();
+    });
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────
+
+/** Log a discrete event. Async — queued and flushed via setImmediate. */
+export function debug(
+  module: string,
+  event: string,
+  meta?: Record<string, unknown>,
+) {
+  if (!debugEnabled) return;
+  try {
+    buffer.push(JSON.stringify({ ts: new Date().toISOString(), module, event, entryType: "event", ...meta }));
+  } catch {
+    buffer.push(JSON.stringify({ ts: new Date().toISOString(), module, event, entryType: "event", _meta_error: "unserializable" }));
+  }
+  scheduleFlush();
+}
+
+/**
+ * Start a performance measure. Returns a stop function that records
+ * a measure entry via the Performance API. Async — queued like debug().
+ */
+export function debugMeasure(module: string, event: string) {
+  if (!debugEnabled) return (_meta?: Record<string, unknown>) => {};
+  const name = `bifrost:${module}:${event}`;
+  performance.mark(`${name}:start`);
+  return (meta?: Record<string, unknown>) => {
+    try {
+      performance.mark(`${name}:end`);
+      performance.measure(name, `${name}:start`, `${name}:end`);
+      const entry = performance.getEntriesByName(name, "measure")[0];
+      if (entry) {
+        const data: Record<string, unknown> = {
+          ts: new Date().toISOString(),
+          module,
+          event,
+          entryType: "measure",
+          duration_ms: +entry.duration.toFixed(3),
+          ...meta,
+        };
+        try {
+          buffer.push(JSON.stringify(data));
+        } catch {
+          buffer.push(JSON.stringify({ ...data, _meta_error: "unserializable" }));
+        }
+      }
+    } finally {
+      performance.clearMarks(`${name}:start`);
+      performance.clearMarks(`${name}:end`);
+      performance.clearMeasures(name);
+    }
+    scheduleFlush();
+  };
+}

package/docs/adr/0001-dual-classifier.md

@@ -0,0 +1,14 @@
+# Dual classifier: LLM-first with regex fallback
+
+pi-bifrost uses two classification systems: an LLM classifier (tried first) and regex rules (fallback). The LLM reads the prompt and returns a tier name; regex rules are simple pattern→tier mappings.
+
+**Why not LLM-only?** The classifier model can be unavailable (local server down, API outage, rate limit). A silent model router that breaks when a sidecar is down is worse than no router at all. The regex fallback ensures routing always works.
+
+**Why not regex-only?** Regex rules are rigid. "Help me design a rate limiter" and "what's a rate limiter?" both contain "rate limiter" but need different tiers. An LLM can distinguish intent — regex cannot.
+
+**Why LLM first, not regex first?** The LLM is more accurate. If it's available, use it. Regex is the safety net, not the primary path. Running regex first and only falling back to LLM would mean paying for LLM tokens only when regex fails — but regex never truly "fails," it just matches or doesn't. The current order means: try the accurate thing, fall back to the reliable thing.
+
+**Consequences:**
+- Every cache miss costs LLM tokens (mitigated by using cheap classifier models and a fuzzy cache)
+- The classifier model must understand the tier names — custom tiers need a custom system prompt
+- Two classification paths to test and maintain

package/docs/adr/0002-subprocess-classifier.md

@@ -0,0 +1,15 @@
+# Subprocess classifier invocation alongside direct HTTP
+
+The LLM classifier supports two invocation methods: `direct` (OpenAI-compatible HTTP POST to the model's base URL) and `subprocess` (spawns a fresh `pi --no-extensions` process).
+
+**Why two methods?** Direct HTTP is fast but only works for OpenAI-compatible APIs. Many pi providers use non-OpenAI protocols (Anthropic Messages, Codex Responses) or require custom auth flows that pi handles internally. The subprocess method delegates to pi itself — any model pi can use, the classifier can use.
+
+**Why not subprocess-only?** Subprocess spawn is slow — cold start, config loading, model resolution. Direct HTTP is a single fetch. For local LM Studio/Ollama servers (the common classifier case), direct HTTP is near-instant.
+
+**Why not direct-only?** Would lock the classifier out of many providers. A user whose only cheap model is an Anthropic Haiku key couldn't use the classifier.
+
+**Consequences:**
+- Two code paths to maintain in `classifier.ts` (direct HTTP ~50 lines, subprocess ~50 lines)
+- Subprocess method is a recursive pi invocation — pi-bifrost loaded in the subprocess must not interfere (handled via `--no-extensions` in the subprocess)
+- `auto` method tries direct first, then subprocess — doubles latency on failure but maximizes availability
+- The `endpoint` config field forces `direct` mode since there's no pi process to delegate to for arbitrary endpoints

package/index.ts

@@ -0,0 +1,259 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
+import { classifyWithLLM as invokeClassifier, type ClassifierModel } from "./classifier.js";
+import {
+  createPipeline,
+  type ClassificationPipeline,
+} from "./classification-pipeline.js";
+import {
+  cachePath,
+  lookupCache,
+  touchCacheEntry,
+  loadCache,
+  saveCache,
+  updateCache,
+  DEFAULT_MAX_ENTRIES,
+  DEFAULT_THRESHOLD,
+  type CacheEntry,
+} from "./cache.js";
+import {
+  loadConfig,
+  loadRules,
+  type BifrostConfig,
+} from "./config.js";
+import {
+  findCandidates,
+  getStrategy,
+  modelKey,
+  resolveModel,
+} from "./routing.js";
+import { createCommandRouter, log, uiBusy, uiDone, type BifrostState } from "./commands.js";
+import { setupDebug, debug, debugMeasure } from "./debug.js";
+
+// ── Pipeline builder (composition root) ────────────────────────
+
+function resolveClassifierModels(
+  ctx: ExtensionContext,
+  config: BifrostConfig,
+): ClassifierModel[] {
+  const pattern = config.classifier?.model;
+  if (!pattern) return [];
+  return findCandidates(ctx, pattern)
+    .slice(0, 3)
+    .map((model) => ({ kind: "registry" as const, model }));
+}
+
+function endpointClassifier(id: string, endpoint: string): ClassifierModel {
+  return { kind: "endpoint", id, baseUrl: endpoint };
+}
+
+function buildPipeline(
+  ctx: ExtensionContext,
+  config: BifrostConfig,
+  cacheEntries: CacheEntry[],
+  classifierEnabled: boolean,
+): ClassificationPipeline {
+  const tiers = Object.keys(config.models ?? {});
+  const cacheCfg = config.cache;
+  const cacheEnabled = cacheCfg?.enabled ?? true;
+  const threshold = cacheCfg?.threshold ?? DEFAULT_THRESHOLD;
+
+  // Resolve classifier models once at pipeline construction.
+  // If classifier is disabled, pass empty array — pipeline skips LLM stage.
+  let classifierModels: ClassifierModel[] = [];
+  if (classifierEnabled && tiers.length > 0) {
+    const classifierEndpoint = config.classifier?.endpoint;
+    if (classifierEndpoint) {
+      const rawModel = config.classifier?.model;
+      const modelId = Array.isArray(rawModel)
+        ? rawModel[0]
+        : (rawModel ?? "classifier");
+      classifierModels = [endpointClassifier(modelId, classifierEndpoint)];
+    } else {
+      classifierModels = resolveClassifierModels(ctx, config);
+    }
+  }
+
+  return createPipeline({
+    cacheLookup: (text) => {
+      if (!cacheEnabled) return undefined;
+      const entry = lookupCache(cacheEntries, text, threshold);
+      if (entry) {
+        touchCacheEntry(entry);
+        return entry.category;
+      }
+      return undefined;
+    },
+    classifierModels,
+    classifyWithLLM: (model, text, tiers) =>
+      invokeClassifier(ctx, model, tiers, text, {
+        systemPrompt: config.classifier?.systemPrompt,
+        maxTokens: config.classifier?.maxTokens,
+        temperature: config.classifier?.temperature,
+        method: config.classifier?.method,
+      }),
+    regexRules: loadRules(process.cwd(), config),
+    defaultTier: config.default,
+    tiers,
+  });
+}
+
+export default function bifrostExtension(pi: ExtensionAPI) {
+  const extensionDir = fileURLToPath(new URL(".", import.meta.url));
+
+  // Setup debug logging first — so startup errors are captured.
+  const bootConfig = loadConfig(process.cwd(), extensionDir);
+  if (bootConfig.debug?.enabled) {
+    setupDebug(bootConfig.debug, process.cwd());
+    debug("bifrost", "startup", { extensionDir });
+  }
+
+  const config = bootConfig;
+  const cacheEntries = loadCache(cachePath(process.cwd(), config.cache?.path));
+  let selfSelecting = false;
+  let pipeline: ClassificationPipeline | undefined;
+
+  function getPipeline(ctx: ExtensionContext): ClassificationPipeline {
+    if (!pipeline) {
+      pipeline = buildPipeline(ctx, state.config, state.cacheEntries, state.classifierEnabled);
+    }
+    return pipeline;
+  }
+
+  function invalidatePipeline() {
+    debug("bifrost", "pipeline.invalidate");
+    pipeline = undefined;
+  }
+
+  // Mutable state shared with command handlers.
+  const state: BifrostState = {
+    config,
+    enabled: config.enabled ?? true,
+    classifierEnabled: config.classifier?.enabled ?? true,
+    pinned: false,
+    cacheEntries,
+    extensionDir,
+    getPipeline,
+    invalidatePipeline,
+  };
+
+  const handleCommand = createCommandRouter(state);
+
+  pi.registerCommand("bifrost", {
+    description: "Bifrost model router control",
+    handler: async (args, ctx) => {
+      await handleCommand(args, ctx);
+    },
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    if (selfSelecting) {
+      selfSelecting = false;
+      return;
+    }
+    if (!state.enabled) return;
+
+    state.pinned = true;
+    debug("bifrost", "model_select", { model: modelKey(ctx.model) });
+    log(
+      ctx,
+      `Model manually changed to ${modelKey(ctx.model)}; Bifrost pinned.`,
+    );
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (event.source === "extension") return { action: "continue" };
+    if (!state.enabled || state.pinned) {
+      debug("input", "bypass", { enabled: state.enabled, pinned: state.pinned });
+      return { action: "continue" };
+    }
+
+    const text = event.text.trim();
+    if (text.startsWith("/")) return { action: "continue" };
+
+    const endInput = debugMeasure("input", "total");
+    debug("input", "prompt", { length: text.length });
+
+    if (state.classifierEnabled) {
+      const endRefresh = debugMeasure("input", "registry.refresh");
+      try {
+        await ctx.modelRegistry.refresh();
+        invalidatePipeline();
+        endRefresh();
+      } catch (err) {
+        debug("input", "registry.refresh.error", { error: String(err) });
+        console.error(`[bifrost] model registry refresh failed: ${err}`);
+      }
+    }
+
+    uiBusy(ctx, "Bifrost classifying...");
+    const endClassify = debugMeasure("input", "classify");
+    const classification = await getPipeline(ctx).classify(text);
+    endClassify({ kind: classification.kind, tier: classification.kind !== "unclassified" ? classification.tier : undefined });
+    uiDone(ctx);
+
+    if (classification.kind === "unclassified") {
+      log(ctx, "Bifrost: no tier matched — using default model", "warning");
+      debug("input", "unclassified");
+      endInput();
+      return { action: "continue" };
+    }
+
+    const tier = classification.tier;
+    const source = classification.kind === "classified"
+      ? classification.source
+      : "fallback";
+    const pattern = state.config.models?.[tier] ?? tier;
+    const strategy = getStrategy(state.config.categoryStrategies, state.config.strategy, tier);
+    const model = resolveModel(ctx, pattern, strategy);
+    if (!model) {
+      debug("input", "no_model", { tier });
+      log(ctx, `Bifrost: tier "${tier}" matched but no model available`, "warning");
+      endInput();
+      return { action: "continue" };
+    }
+
+    // Only cache LLM classifier results (regex is deterministic).
+    if (
+      classification.kind === "classified" &&
+      classification.source === "classifier"
+    ) {
+      const maxEntries = state.config.cache?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+      if (state.config.cache?.enabled ?? true) {
+        const endCacheSave = debugMeasure("input", "cacheSave");
+        state.cacheEntries = updateCache(state.cacheEntries, text, tier, maxEntries);
+        saveCache(cachePath(process.cwd(), state.config.cache?.path), state.cacheEntries);
+        invalidatePipeline();
+        endCacheSave({ entries: state.cacheEntries.length });
+      }
+    }
+
+    if (modelKey(model) === modelKey(ctx.model)) {
+      uiDone(ctx);
+      log(ctx, `Bifrost: ${tier} → ${modelKey(model)} (already active, ${source})`);
+      debug("input", "model_unchanged", { model: modelKey(model) });
+      endInput({ model: modelKey(model), tier, strategy, source });
+      return { action: "continue" };
+    }
+
+    uiBusy(ctx, `Bifrost routing to ${modelKey(model)}...`);
+    selfSelecting = true;
+    const endSwitch = debugMeasure("input", "setModel");
+    const ok = await pi.setModel(model);
+    endSwitch({ model: modelKey(model), ok });
+    uiDone(ctx);
+    if (!ok) {
+      selfSelecting = false;
+      log(ctx, `Bifrost: no API key for ${modelKey(model)}`, "error");
+      endInput({ model: modelKey(model), ok: false });
+      return { action: "continue" };
+    }
+
+    const doneMsg = classification.kind === "classified"
+      ? `Bifrost: ${tier} → ${modelKey(model)} (${classification.source})`
+      : `Bifrost: ${tier} → ${modelKey(model)} (fallback)`;
+    log(ctx, doneMsg);
+    endInput({ model: modelKey(model), tier, strategy, source });
+    return { action: "continue" };
+  });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-bifrost",
+  "version": "0.1.0",
+  "description": "query-aware model router for the pi",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "model-router"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "minPiVersion": "0.80.8"
+  },
+  "scripts": {
+    "test": "node --test --experimental-strip-types tests/cache.test.ts tests/classifier.test.ts tests/routing.test.ts tests/pipeline.test.ts tests/commands.test.ts",
+    "test:integration": "cd .. && node --test pi-bifrost/tests/integration.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1"
+  }
+}

package/probe.ts

@@ -0,0 +1,144 @@
+// ── Model probe: availability testing ────────────────────────────
+// Sends a tiny prompt to every available model and records results.
+// Used by /bifrost probe to surface real-world model health.
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface ProbeResult {
+  provider: string;
+  model: string;
+  cost_input: number;
+  cost_output: number;
+  status: "ok" | "error" | "timeout" | "skipped";
+  duration_ms: number;
+  error?: string;
+  tokens?: number;
+}
+
+const PROBE_PROMPT = "1+1=";
+export const PROBE_PROMPT_TEXT = PROBE_PROMPT;
+const PROBE_TIMEOUT_MS = 10_000;
+const PROBE_MAX_TOKENS = 5;
+
+export async function runProbe(
+  ctx: ExtensionContext,
+  onProgress?: (done: number, total: number, last: ProbeResult) => void,
+): Promise<{ results: ProbeResult[]; path: string }> {
+  const available = ctx.modelRegistry.getAvailable();
+  const total = available.length;
+  const CONCURRENCY = 8;
+  const results: ProbeResult[] = new Array(total);
+  let cursor = 0;
+  let completed = 0;
+
+  async function worker() {
+    while (cursor < total) {
+      const i = cursor++;
+      results[i] = await probeOne(ctx, available[i]);
+      completed++;
+      onProgress?.(completed, total, results[i]);
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(CONCURRENCY, total) }, () => worker());
+  await Promise.all(workers);
+
+  const outputPath = join(process.cwd(), ".pi", "bifrost-probe.json");
+  const dir = dirname(outputPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(outputPath, JSON.stringify(results, null, 2), "utf-8");
+  return { results, path: outputPath };
+}
+
+async function probeOne(
+  ctx: ExtensionContext,
+  model: Model<Api>,
+): Promise<ProbeResult> {
+  const base: ProbeResult = {
+    provider: model.provider,
+    model: model.id,
+    cost_input: model.cost?.input ?? 0,
+    cost_output: model.cost?.output ?? 0,
+    status: "skipped",
+    duration_ms: 0,
+  };
+
+  // Only probe OpenAI-compatible HTTP models.
+  const api = model.api as string | undefined;
+  if (
+    !api ||
+    (!api.startsWith("openai-") && api !== "mistral-conversations")
+  ) {
+    base.error = `unsupported api: ${api}`;
+    return base;
+  }
+
+  const start = performance.now();
+  try {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    const apiKey = auth.ok ? auth.apiKey : undefined;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      ...(auth.ok && auth.headers ? auth.headers : {}),
+    };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+
+    try {
+      let baseUrl = model.baseUrl.endsWith("/")
+        ? model.baseUrl
+        : `${model.baseUrl}/`;
+      // Guard against providers that already include the endpoint path.
+      if (baseUrl.endsWith("/chat/completions/") || baseUrl.endsWith("/v1/chat/completions/")) {
+        // URL is already the full chat/completions endpoint.
+      } else {
+        baseUrl = new URL("chat/completions", baseUrl).toString();
+      }
+      const url = baseUrl;
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          model: model.id,
+          messages: [{ role: "user", content: PROBE_PROMPT }],
+          max_tokens: PROBE_MAX_TOKENS,
+          temperature: 0,
+          stream: false,
+        }),
+        signal: controller.signal,
+      });
+
+      base.duration_ms = +(performance.now() - start).toFixed(1);
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        base.status = "error";
+        base.error = `HTTP ${response.status}: ${body.slice(0, 200)}`;
+        return base;
+      }
+
+      const data = (await response.json()) as {
+        choices?: Array<{ message?: { content?: string } }>;
+        usage?: { total_tokens?: number };
+      };
+      base.status = "ok";
+      base.tokens = data.usage?.total_tokens;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    base.duration_ms = +(performance.now() - start).toFixed(1);
+    base.status = err instanceof DOMException && err.name === "AbortError"
+      ? "timeout"
+      : "error";
+    base.error = String(err).slice(0, 200);
+  }
+
+  return base;
+}