@polderlabs/bizar 6.3.0 → 7.0.0

package/packages/sdk/src/router/index.ts

@@ -0,0 +1,247 @@
+/**
+ * router/index.ts — orchestrator for Bizar's self-learning router.
+ *
+ * v6.4.0 — F-033. Composes the three sub-routers
+ * (`codemod-intent`, `model-router`, `q-learning-router`) into a
+ * single precedence chain:
+ *
+ *     explicit-route (caller-provided) >
+ *       codemod-intent ($0 Tier-1 short-circuit) >
+ *         q-learning-router (8-action agent pick) >
+ *           model-router (Thompson bandit for tier) >
+ *             default ("odin", "mid", confidence 0.5)
+ *
+ * The orchestrator is what the `hooks_route` MCP tool (and any
+ * in-process caller such as the Odin agent) calls to make a routing
+ * decision. It surfaces two human-readable tags on `stdout`-equivalent
+ * surfaces:
+ *
+ *   - `[CODEMOD_AVAILABLE] <intent>` — printed BEFORE the model call
+ *     would happen, telling the model that a deterministic $0 codemod
+ *     could short-circuit the work. Honoured by the Odin prompt.
+ *   - `[TASK_MODEL_RECOMMENDATION] <tier> (conf=<n>)` — appended to
+ *     prompt-side telemetry so downstream model selection knows the
+ *     bandit-learner thinks this task should be routed to `flash` /
+ *     `mid` / `expensive`.
+ *
+ * Persistence: when constructed via `getRouter({ persist: true })`,
+ * the orchestrator holds a single shared `ModelRouter` +
+ * `QLearningRouter` whose state lives at `.harness/router-state.json`
+ * and `.harness/q-router-state.json` respectively. Callers can also
+ * pass `modelRouter` / `qRouter` for in-memory-only operation
+ * (preferred in tests).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import {
+  detectCodemodIntent,
+  type CodemodIntent,
+  CODEMOD_CONFIDENCE_THRESHOLD,
+} from "./codemod-intent.js";
+import {
+  ModelRouter,
+  type ModelTier,
+  type RouteDecision,
+} from "./model-router.js";
+import {
+  QLearningRouter,
+  AGENT_ACTIONS,
+  type AgentRouteDecision,
+} from "./q-learning-router.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RouteInput {
+  task: string;
+  /** Caller-provided explicit override for the agent (highest precedence). */
+  explicitAgent?: string;
+  /** Optional embedding — currently ignored (reserved for future ANN
+   *  lookup that could refine the state bucket). */
+  embedding?: number[];
+}
+
+export interface RouteDecisionOutput {
+  agent: string;
+  modelTier: ModelTier;
+  agentConfidence: number;
+  modelConfidence: number;
+  /** Null unless the prompt matched a Tier-1 codemod intent. */
+  codemodIntent: CodemodIntent | null;
+  /** `[CODEMOD_AVAILABLE] var-to-const` style surface for prompt pre-injection. */
+  surfacedTags: string[];
+}
+
+export interface RouterBundle {
+  modelRouter: ModelRouter;
+  qRouter: QLearningRouter;
+  decideAgent(input: RouteInput): RouteDecisionOutput;
+  /** Persist both routers to `path`'s sibling state files. */
+  saveTo(path: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export interface GetRouterOpts {
+  /** When provided, the orchestrator attempts to load priors + Q-table
+   *  from `<basePath>.{model,q}` if those files exist; missing files
+   *  fall back to defaults. */
+  basePath?: string;
+  /** In-memory overrides — useful for tests. */
+  modelRouter?: ModelRouter;
+  qRouter?: QLearningRouter;
+}
+
+/** Default state-file paths (kept beside the orchestrator's caller). */
+export const DEFAULT_MODEL_STATE_PATH = ".harness/router-state.json";
+export const DEFAULT_Q_STATE_PATH = ".harness/q-router-state.json";
+
+/**
+ * Build (or rehydrate) a router bundle.
+ *
+ * Default state files are stored under `.harness/` in the current
+ * working directory. Tests typically pass `modelRouter` / `qRouter`
+ * to keep things in-process.
+ */
+export function getRouter(opts: GetRouterOpts = {}): RouterBundle {
+  const basePath = opts.basePath ?? join(process.cwd(), ".harness", "router-state");
+  const modelPath = `${basePath}.model`;
+  const qPath = `${basePath}.q`;
+
+  const modelRouter =
+    opts.modelRouter ??
+    (existsSync(modelPath) ? ModelRouter.loadFrom(modelPath) : new ModelRouter());
+  const qRouter =
+    opts.qRouter ??
+    (existsSync(qPath) ? QLearningRouter.loadFrom(qPath) : new QLearningRouter());
+
+  return {
+    modelRouter,
+    qRouter,
+    decideAgent(input: RouteInput): RouteDecisionOutput {
+      return decideAgentWith(modelRouter, qRouter, input);
+    },
+    saveTo(path: string): void {
+      const fp = isAbsolute(path) ? path : resolve(path);
+      mkdirSync(dirname(fp), { recursive: true });
+      modelRouter.saveTo(modelPath);
+      qRouter.saveTo(qPath);
+      // And a tiny pointer file for callers that only know the bundle name.
+      writeFileSync(
+        fp,
+        JSON.stringify({ modelPath, qPath, version: 1 }, null, 2),
+        "utf-8",
+      );
+    },
+  };
+}
+
+/**
+ * Pure, testable entry point — the actual precedence chain.
+ *
+ * Order:
+ *  1. caller-supplied `explicitAgent` wins outright.
+ *  2. Tier-1 codemod intent → agent="heimdall" (routine implementation),
+ *     tier="flash" ($0), confidence 1.0, surface `[CODEMOD_AVAILABLE]`.
+ *  3. Q-learning agent pick (clamped to known agent names).
+ *  4. Thompson-bandit model-tier pick.
+ *  5. Defaults: agent="odin", tier="mid".
+ */
+export function decideAgentWith(
+  modelRouter: ModelRouter,
+  qRouter: QLearningRouter,
+  input: RouteInput,
+): RouteDecisionOutput {
+  const task = String(input?.task ?? "");
+  const surfacedTags: string[] = [];
+
+  // 1. Explicit override — highest precedence.
+  if (input.explicitAgent && AGENT_ACTIONS.includes(input.explicitAgent)) {
+    // Still pick a model tier (bandit) so we can surface
+    // [TASK_MODEL_RECOMMENDATION] downstream.
+    const tier: RouteDecision = modelRouter.route(task);
+    surfacedTags.push(tierTag(tier));
+    return {
+      agent: input.explicitAgent,
+      modelTier: tier.tier,
+      agentConfidence: 1.0,
+      modelConfidence: tier.confidence,
+      codemodIntent: null,
+      surfacedTags,
+    };
+  }
+
+  // 2. Codemod short-circuit (only when there's a task string).
+  const cm = task ? detectCodemodIntent(task) : null;
+  if (cm !== null) {
+    surfacedTags.push(codemodTag(cm.intent, cm.confidence));
+    // Tier-1 codemod: $0, model tier = "flash" but the call is
+    // supposed to be skipped (deterministic). We still set
+    // modelTier/Confidence so downstream telemetry has consistent
+    // shape.
+    surfacedTags.push(tierTag({ tier: "flash", confidence: 1.0 }));
+    return {
+      agent: "heimdall",
+      modelTier: "flash",
+      agentConfidence: 1.0,
+      modelConfidence: 1.0,
+      codemodIntent: cm.intent,
+      surfacedTags,
+    };
+  }
+
+  // 3. Q-learning agent pick.
+  const agentDecision: AgentRouteDecision = qRouter.selectAgent(task);
+  // 4. Thompson bandit for model tier.
+  const tierDecision: RouteDecision = modelRouter.route(task);
+  surfacedTags.push(tierTag(tierDecision));
+
+  return {
+    agent: agentDecision.agent,
+    modelTier: tierDecision.tier,
+    agentConfidence: agentDecision.confidence,
+    modelConfidence: tierDecision.confidence,
+    codemodIntent: null,
+    surfacedTags,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tag formatters — the strings the spec asks us to surface to the prompt.
+// ---------------------------------------------------------------------------
+
+export function codemodTag(intent: CodemodIntent, confidence: number): string {
+  return `[CODEMOD_AVAILABLE] ${intent} (conf=${confidence.toFixed(2)} >= ${CODEMOD_CONFIDENCE_THRESHOLD.toFixed(2)})`;
+}
+
+export function tierTag(decision: RouteDecision): string {
+  return `[TASK_MODEL_RECOMMENDATION] ${decision.tier} (conf=${decision.confidence.toFixed(2)})`;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience re-exports so callers can `import { ... } from "..."/router"
+// ---------------------------------------------------------------------------
+
+export {
+  detectCodemodIntent,
+  CODEMOD_CONFIDENCE_THRESHOLD,
+} from "./codemod-intent.js";
+export type { CodemodIntent, CodemodIntentHit } from "./codemod-intent.js";
+
+export {
+  ModelRouter,
+  type ModelTier,
+  type RouteDecision,
+} from "./model-router.js";
+
+export {
+  QLearningRouter,
+  AGENT_ACTIONS,
+  type AgentName,
+  type AgentRouteDecision,
+} from "./q-learning-router.js";

package/packages/sdk/src/router/memory-distillation-shim.mjs

@@ -0,0 +1,18 @@
+/**
+ * router/memory-distillation-shim.mjs — runtime-only ESM re-export of
+ * `memory-distillation.ts` so the `memory_distill` MCP tool can
+ * dynamically `import()` the pipeline without taking a static
+ * dependency on the heavier consolidation logic.
+ *
+ * v6.4.0 — F-033 (Self-Learning, ADR-174). Lives next to its sibling
+ * `memory-distillation.ts`; the parent keeps the strict TS surface,
+ * this shim keeps the runtime import ESM-clean for the MCP tool.
+ */
+
+export {
+  runDistillation,
+  retrieve,
+  judge,
+  distill,
+  PROVENANCE_TIERS,
+} from "./memory-distillation.js";

package/packages/sdk/src/router/memory-distillation.ts

@@ -0,0 +1,249 @@
+/**
+ * router/memory-distillation.ts — RETRIEVE → JUDGE → DISTILL →
+ * CONSOLIDATE (ADR-174) as a pure TypeScript module.
+ *
+ * v6.4.0 — ported from ruflo `@claude-flow/neural/src/reasoning-bank.ts`
+ * (the 4-step pipeline) + ADR-174 (provenance-tiered promote gate).
+ *
+ * This is the $0 default path — deterministic, no LLM, no I/O.
+ * Living inside the SDK (rather than the dashboard .mjs files) so
+ * the `memory_distill` MCP tool can call it via a static TypeScript
+ * import without crossing the ESM/CJS boundary at runtime.
+ *
+ * The dashboard's `bizar-dash/src/server/memory-{distillation,
+ * consolidator}.mjs` re-export the same semantics and add the
+ * vault I/O (read notes, write promoted patterns back). Both paths
+ * agree on the `Pattern` shape so the schema is one-of.
+ */
+
+export const PROVENANCE_TIERS = [
+  "oracle:test-exec",
+  "proxy:structural",
+  "judge:fable",
+] as const;
+
+export type ProvenanceTier = (typeof PROVENANCE_TIERS)[number];
+
+export interface MemoryEntryLike {
+  memory_id?: string;
+  id?: string;
+  path?: string;
+  relPath?: string;
+  frontmatter?: Record<string, unknown>;
+  body?: string;
+  kind?: string;
+  type?: string;
+  created?: string;
+  createdAt?: string;
+  tags?: unknown;
+}
+
+export interface Retrieval {
+  complexity: "simple" | "moderate" | "complex";
+  testExec: boolean;
+  hasCodeBlock: boolean;
+  length: number;
+}
+
+export interface Pattern {
+  id: string;
+  kind: "pattern";
+  summary: string;
+  uses: string[];
+  evidence: string[];
+  provenance_tier: ProvenanceTier;
+  promoted: boolean;
+  score: number;
+}
+
+export interface DistillationResult {
+  patterns: Pattern[];
+  promoted: Pattern[];
+  byTier: Record<ProvenanceTier, number>;
+}
+
+const COMPLEXITY_SIMPLE_MAX = 600;
+const COMPLEXITY_MODERATE_MAX = 2400;
+
+function firstLine(s: string): string {
+  if (!s) return "";
+  const i = s.indexOf("\n");
+  return (i < 0 ? s : s.slice(0, i)).trim();
+}
+
+function snippet(body: string): string {
+  const cleaned = body.replace(/\s+/g, " ").trim();
+  return cleaned.length <= 200 ? cleaned : cleaned.slice(0, 200) + "…";
+}
+
+function shorten(s: string): string {
+  let h = 5381 >>> 0;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(36).slice(0, 10);
+}
+
+function wordSet(s: string): Set<string> {
+  const out = new Set<string>();
+  const norm = (s || "").toLowerCase().replace(/[^a-z0-9\s]+/g, " ");
+  for (const w of norm.split(/\s+/)) {
+    if (w.length > 2) out.add(w);
+  }
+  return out;
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter += 1;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+function dedupe<T>(arr: T[]): T[] {
+  const seen = new Set<T>();
+  const out: T[] = [];
+  for (const x of arr) if (!seen.has(x)) { seen.add(x); out.push(x); }
+  return out;
+}
+
+export function retrieve(entry: MemoryEntryLike): Retrieval {
+  const body = String(entry?.body ?? "");
+  const fm = entry?.frontmatter ?? {};
+  const hasCodeBlock = /```/.test(body);
+  const tagsArr = Array.isArray(fm.tags) ? fm.tags : [];
+  const testExec =
+    Boolean(fm.test_exec) ||
+    Boolean(fm.testExec) ||
+    tagsArr.some((t) => String(t).includes("test-exec")) ||
+    String(fm.kind ?? "") === "feedback";
+  const len = body.length;
+  let complexity: Retrieval["complexity"];
+  if (hasCodeBlock || len > COMPLEXITY_MODERATE_MAX) complexity = "complex";
+  else if (len > COMPLEXITY_SIMPLE_MAX) complexity = "moderate";
+  else complexity = "simple";
+  return { complexity, testExec, hasCodeBlock, length: len };
+}
+
+export function judge(_entry: MemoryEntryLike, retrieval: Retrieval): ProvenanceTier {
+  if (retrieval.testExec) return "oracle:test-exec";
+  return "proxy:structural";
+}
+
+export function distill(entry: MemoryEntryLike): Omit<Pattern, "provenance_tier" | "promoted" | "score"> | null {
+  const fm = entry?.frontmatter ?? {};
+  const body = String(entry?.body ?? "").trim();
+  const id = String(entry?.memory_id ?? entry?.id ?? entry?.path ?? entry?.relPath ?? "");
+  const kindRaw = String(fm.kind ?? entry?.kind ?? entry?.type ?? "").toLowerCase();
+
+  if (kindRaw === "coding_convention" || kindRaw === "bug_pattern") {
+    return {
+      id: `pat_${shorten(id || body.slice(0, 24))}`,
+      kind: "pattern",
+      summary: firstLine(body) || "(empty)",
+      uses: id ? [id] : [],
+      evidence: [snippet(body)],
+    };
+  }
+
+  const head = firstLine(body).toLowerCase();
+  if (
+    kindRaw === "task_summary" ||
+    kindRaw === "session_summary" ||
+    /\bpattern\s*:/.test(head) ||
+    /^\s*(use|avoid|do|don't)\s*:/.test(head)
+  ) {
+    return {
+      id: `pat_${shorten(id || head.replace(/\W+/g, " ").slice(0, 24))}`,
+      kind: "pattern",
+      summary: firstLine(body) || "(empty)",
+      uses: id ? [id] : [],
+      evidence: [snippet(body)],
+    };
+  }
+  return null;
+}
+
+/**
+ * Distillation candidates carry their tier separately; we shift it on
+ * to `provenance_tier` here and set the `promoted` flag.
+ */
+interface Candidate {
+  id: string;
+  kind: "pattern";
+  summary: string;
+  uses: string[];
+  evidence: string[];
+  _tier: ProvenanceTier;
+}
+
+export function runDistillation(entries: MemoryEntryLike[]): DistillationResult {
+  const empty = {
+    patterns: [] as Pattern[],
+    promoted: [] as Pattern[],
+    byTier: { "oracle:test-exec": 0, "proxy:structural": 0, "judge:fable": 0 } as Record<ProvenanceTier, number>,
+  };
+  if (!Array.isArray(entries) || entries.length === 0) return empty;
+
+  const candidates: Candidate[] = [];
+  for (const entry of entries) {
+    const retrieval = retrieve(entry);
+    const tier = judge(entry, retrieval);
+    const pattern = distill(entry);
+    if (!pattern) continue;
+    candidates.push({ ...pattern, _tier: tier });
+  }
+
+  // Cluster by Jaccard similarity ≥ 0.5 over (summary + evidence).
+  const groups: { rep: Candidate; members: Candidate[] }[] = [];
+  for (const c of candidates) {
+    const ws = wordSet(c.summary + " " + c.evidence.join(" "));
+    let placed = false;
+    for (const g of groups) {
+      const gs = wordSet(g.rep.summary + " " + g.rep.evidence.join(" "));
+      if (jaccard(ws, gs) >= 0.5) {
+        g.members.push(c);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) groups.push({ rep: c, members: [c] });
+  }
+
+  const byTier: Record<ProvenanceTier, number> = {
+    "oracle:test-exec": 0,
+    "proxy:structural": 0,
+    "judge:fable": 0,
+  };
+  const patterns: Pattern[] = [];
+  for (const g of groups) {
+    const usesSet = new Set<string>();
+    const evidence: string[] = [];
+    for (const m of g.members) {
+      for (const u of m.uses ?? []) usesSet.add(u);
+      for (const e of m.evidence ?? []) evidence.push(e);
+    }
+    const tiers = g.members.map((m) => m._tier);
+    let tier: ProvenanceTier = "proxy:structural";
+    if (tiers.includes("oracle:test-exec")) tier = "oracle:test-exec";
+    else if (tiers.includes("judge:fable")) tier = "judge:fable";
+
+    const promoted = usesSet.size >= 1 && (tier === "oracle:test-exec" || tier === "judge:fable");
+    const pattern: Pattern = {
+      id: g.rep.id,
+      kind: "pattern",
+      summary: g.rep.summary,
+      uses: Array.from(usesSet),
+      evidence: dedupe(evidence).slice(0, 5),
+      provenance_tier: tier,
+      promoted,
+      score: 0.5 + usesSet.size * 0.1,
+    };
+    patterns.push(pattern);
+    byTier[tier] += 1;
+  }
+
+  const promoted = patterns.filter((p) => p.promoted);
+  return { patterns, promoted, byTier };
+}