@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/src/router/q-learning-router.ts

@@ -0,0 +1,304 @@
+/**
+ * router/q-learning-router.ts — Q-learning agent router.
+ *
+ * v6.4.0 — ported from ruflo `q-learning-router.ts` (8-action softmax
+ * agent-route over coder / tester / reviewer / …).
+ *
+ * Bizar has more than 8 named agents, so the action set is the 8 most
+ * commonly delegated targets from `Agent` tool calls (matches
+ * `.claude/agents/*.md` to first 8 names). Adding the full
+ * 12-agent space could be done in a follow-up but each new agent
+ * increases state-action coverage cost; 8 keeps the bandit honest.
+ *
+ *   - State: a 64-dim bag-of-words hash of the task string (FNV-1a
+ *     folded into 64 buckets). LRU-cached so repeated task patterns
+ *     are O(1).
+ *   - Action: one of `odin|frigg|vor|mimir|heimdall|thor|tyr|forseti`.
+ *   - Reward: `+1` on `recordOutcome(agent, true)`, `0` on false.
+ *   - Exploration: ε-greedy with ε = 0.1 (configurable).
+ *
+ * `selectAgent()` returns `{agent, confidence}`. `confidence` is the
+ * posterior mean of the picked action's Q-value clamped to [0,1].
+ *
+ * Tiny surface area by design — the
+ * `AgentRouteDecision` shape is what `model_route` /
+ * `agent_route` MCP tools expose.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import { detectCodemodIntent } from "./codemod-intent.js";
+
+export const AGENT_ACTIONS: readonly string[] = [
+  "odin",
+  "frigg",
+  "vor",
+  "mimir",
+  "heimdall",
+  "thor",
+  "tyr",
+  "forseti",
+] as const;
+
+export type AgentName = (typeof AGENT_ACTIONS)[number];
+
+export interface AgentRouteDecision {
+  agent: string;
+  confidence: number;
+}
+
+export interface QLearningRouterOpts {
+  stateDim?: number;
+  epsilon?: number;
+  lruSize?: number;
+  seed?: number;
+}
+
+const DEFAULT_STATE_DIM = 64;
+const DEFAULT_EPSILON = 0.1;
+const DEFAULT_LRU = 256;
+
+const STOPWORDS = new Set([
+  "the", "a", "an", "and", "or", "but", "in", "on", "at", "to",
+  "for", "of", "with", "by", "is", "are", "be", "was", "were", "this",
+  "that", "it", "as", "if", "from", "into", "so", "than",
+]);
+
+export class QLearningRouter {
+  private readonly stateDim: number;
+  private readonly epsilon: number;
+  private readonly lruSize: number;
+  // Q[agentIdx][stateBucket] → mean reward for that bucket.
+  // Initialised to 0.5 (neutral). Updated by EMA on recordOutcome.
+  private readonly q: Float32Array[] = [];
+  private readonly counts: Uint32Array[] = [];
+  private readonly lru: Map<string, AgentRouteDecision> = new Map();
+  private rngState: number;
+
+  constructor(opts?: QLearningRouterOpts) {
+    this.stateDim = opts?.stateDim ?? DEFAULT_STATE_DIM;
+    this.epsilon = opts?.epsilon ?? DEFAULT_EPSILON;
+    this.lruSize = opts?.lruSize ?? DEFAULT_LRU;
+    this.rngState = (opts?.seed ?? 0) | 0;
+    for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+      this.q.push(new Float32Array(this.stateDim).fill(0.5));
+      this.counts.push(new Uint32Array(this.stateDim));
+    }
+  }
+
+  /**
+   * Greedy ε-soft policy. Returns a cached decision when the same
+   * (task) hash has been seen recently (LRU bounded by `lruSize`).
+   * Codemod-eligible prompts short-circuit to `heimdall` (the
+   * routine-implementation agent) so they still get a "best" agent
+   * without paying the bandit lookup cost twice.
+   */
+  selectAgent(task: string): AgentRouteDecision {
+    if (!task || typeof task !== "string") {
+      return { agent: "odin", confidence: 0.5 };
+    }
+
+    // Tier-1 codemod-eligible prompt → deterministic safe pick.
+    const cm = detectCodemodIntent(task);
+    if (cm !== null) {
+      return { agent: "heimdall", confidence: 1.0 };
+    }
+
+    const bucket = this.bucketize(task);
+    const cacheKey = String(bucket);
+    const cached = this.lru.get(cacheKey);
+    if (cached) {
+      // Touch the LRU entry to mark recently used.
+      this.lru.delete(cacheKey);
+      this.lru.set(cacheKey, cached);
+      return cached;
+    }
+
+    let agentIdx: number;
+    let confidence = 0.5;
+    if (this.random() < this.epsilon) {
+      // Explore: uniformly at random.
+      agentIdx = Math.floor(this.random() * AGENT_ACTIONS.length) % AGENT_ACTIONS.length;
+      confidence = 0.25;
+    } else {
+      // Exploit: argmax Q for this bucket. Tie-break by lower count
+      // (prefer the less-tried action), then by the canonical order.
+      let bestQ = -Infinity;
+      let bestCount = Infinity;
+      const ties: number[] = [];
+      for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+        const qv = this.q[i][bucket];
+        if (qv > bestQ) {
+          bestQ = qv; bestCount = this.counts[i][bucket]; ties.length = 0; ties.push(i);
+        } else if (qv === bestQ) {
+          const c = this.counts[i][bucket];
+          if (c < bestCount) { bestCount = c; ties.length = 0; ties.push(i); }
+          else ties.push(i);
+        }
+      }
+      agentIdx = ties[Math.floor(this.random() * ties.length)] ?? 0;
+      confidence = clamp01(bestQ);
+    }
+
+    const decision: AgentRouteDecision = {
+      agent: AGENT_ACTIONS[agentIdx],
+      confidence,
+    };
+
+    // Promote to LRU. LRU has a hard cap; evict oldest on overflow.
+    if (this.lru.size >= this.lruSize) {
+      const oldest = this.lru.keys().next().value;
+      if (oldest !== undefined) this.lru.delete(oldest);
+    }
+    this.lru.set(cacheKey, decision);
+    return decision;
+  }
+
+  /**
+   * EMA update of Q[agentIdx][bucket]. Uses the standard
+   *   Q ← Q + α (reward − Q)
+   * where α = 1 / (1 + count) — decreasing step size over time.
+   */
+  recordOutcome(agent: string, success: boolean): void {
+    const idx = AGENT_ACTIONS.indexOf(agent as AgentName);
+    if (idx < 0) return;
+    // Reward shape: +1 success, 0 failure, normalised to [0,1] in Q.
+    const reward = success ? 1.0 : 0.0;
+    for (let b = 0; b < this.stateDim; b++) {
+      const c = this.counts[idx][b] + 1;
+      this.counts[idx][b] = c;
+      const alpha = 1 / (1 + c);
+      this.q[idx][b] = this.q[idx][b] + alpha * (reward - this.q[idx][b]);
+    }
+  }
+
+  /** Read-only access for tests / telemetry. */
+  snapshot(): Array<{ agent: string; qMean: number; n: number }> {
+    return AGENT_ACTIONS.map((agent, i) => {
+      let total = 0;
+      let n = 0;
+      for (let b = 0; b < this.stateDim; b++) {
+        total += this.q[i][b];
+        n += this.counts[i][b];
+      }
+      return {
+        agent,
+        qMean: n === 0 ? 0.5 : total / this.stateDim,
+        n,
+      };
+    });
+  }
+
+  // -----------------------------------------------------------------
+  // Persistence — same JSON-file policy as the model router.
+  // -----------------------------------------------------------------
+
+  /** Stable on-disk serialisation: Q-table per agent, counts, seed. */
+  fullSnapshot(): QLearningSnapshot {
+    const q: number[][] = [];
+    const counts: number[][] = [];
+    for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+      q.push(Array.from(this.q[i]));
+      counts.push(Array.from(this.counts[i]));
+    }
+    return {
+      version: 1,
+      stateDim: this.stateDim,
+      epsilon: this.epsilon,
+      q,
+      counts,
+      rngSeed: this.rngState,
+    };
+  }
+
+  static fromSnapshot(snap: Partial<QLearningSnapshot>): QLearningRouter {
+    const inst = new QLearningRouter({
+      stateDim: snap.stateDim,
+      epsilon: snap.epsilon,
+      seed: snap.rngSeed,
+    });
+    if (snap.q && snap.counts) {
+      const dim = inst.stateDim;
+      for (let i = 0; i < Math.min(snap.q.length, AGENT_ACTIONS.length); i++) {
+        const row = snap.q[i] ?? [];
+        const crows = snap.counts[i] ?? [];
+        for (let b = 0; b < Math.min(dim, row.length); b++) {
+          inst.q[i][b] = row[b];
+          inst.counts[i][b] = crows[b] ?? 0;
+        }
+      }
+    }
+    return inst;
+  }
+
+  saveTo(path: string): void {
+    const fp = isAbsolute(path) ? path : resolve(path);
+    mkdirSync(dirname(fp), { recursive: true });
+    writeFileSync(fp, JSON.stringify(this.fullSnapshot(), null, 2), "utf-8");
+  }
+
+  static loadFrom(path: string): QLearningRouter {
+    try {
+      if (!existsSync(path)) return new QLearningRouter();
+      const snap = JSON.parse(readFileSync(path, "utf-8")) as Partial<QLearningSnapshot>;
+      return QLearningRouter.fromSnapshot(snap);
+    } catch {
+      return new QLearningRouter();
+    }
+  }
+
+  // -----------------------------------------------------------------
+  // Helpers (FNV-1a bucketing + seeded RNG).
+  // -----------------------------------------------------------------
+
+  /** FNV-1a 32-bit hash, folded into [0, stateDim). Bag-of-words. */
+  private bucketize(text: string): number {
+    // Tokenise, drop stopwords.
+    const tokens = text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]+/g, " ")
+      .split(/\s+/)
+      .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+
+    // If everything was stopwords, the whole string is its own bucket.
+    const words = tokens.length > 0 ? tokens : [text.toLowerCase().trim()];
+
+    let acc = 2166136261 >>> 0; // FNV-1a init.
+    for (const w of words) {
+      let h = 2166136261 >>> 0;
+      for (let i = 0; i < w.length; i++) {
+        h ^= w.charCodeAt(i);
+        h = Math.imul(h, 16777619) >>> 0;
+      }
+      acc ^= h;
+      acc = Math.imul(acc + 0x9e3779b9, 16777619) >>> 0;
+    }
+    return acc % this.stateDim;
+  }
+
+  private random(): number {
+    if (this.rngState !== 0) {
+      this.rngState = (this.rngState * 1664525 + 1013904223) | 0;
+      const u = (this.rngState >>> 0) / 0xffffffff;
+      return u || 1e-12;
+    }
+    return Math.random() || 1e-12;
+  }
+}
+
+export interface QLearningSnapshot {
+  version: number;
+  stateDim: number;
+  epsilon: number;
+  q: number[][];
+  counts: number[][];
+  rngSeed: number;
+}
+
+function clamp01(n: number): number {
+  if (Number.isNaN(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}

package/packages/sdk/src/swarm-topology.ts

@@ -0,0 +1,279 @@
+/**
+ * swarm-topology.ts — in-process swarm coordination topology registry.
+ *
+ * F-032 — ported from ruflo `v3/mcp/tools/swarm-tools.ts` `swarm/init`
+ * (line 389). Tracks swarm definitions and the agents assigned to them.
+ * No event bus — purely a registry the MCP tools can read/write.
+ *
+ * The `default` swarm is created lazily on first `initSwarm` call so
+ * consumers always have at least one swarm to inspect.
+ *
+ * Persistence is opt-in: pass `{ persistPath }` to the constructor (or
+ * to the `swarmTopologyRegistry` singleton via its mutator) and the
+ * registry writes a JSON snapshot to disk after every mutation.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type SwarmTopology =
+  | "hierarchical"
+  | "mesh"
+  | "adaptive"
+  | "collective"
+  | "hierarchical-mesh";
+
+export const SWARM_TOPOLOGIES: readonly SwarmTopology[] = [
+  "hierarchical",
+  "mesh",
+  "adaptive",
+  "collective",
+  "hierarchical-mesh",
+] as const;
+
+export const DEFAULT_TOPOLOGY: SwarmTopology = "hierarchical-mesh";
+export const DEFAULT_MAX_AGENTS = 15;
+export const MIN_MAX_AGENTS = 1;
+export const MAX_MAX_AGENTS = 1000;
+export const DEFAULT_SWARM_ID = "default";
+
+export interface SwarmRecord {
+  swarmId: string;
+  topology: SwarmTopology;
+  maxAgents: number;
+  metadata?: Record<string, unknown>;
+  agentIds: string[];
+  createdAt: string;
+  decommissionedAt?: string;
+}
+
+export interface InitSwarmInput {
+  swarmId?: string;
+  topology?: SwarmTopology;
+  maxAgents?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface InitSwarmResult {
+  swarmId: string;
+  topology: SwarmTopology;
+  maxAgents: number;
+  createdAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SwarmTopologyRegistryOpts {
+  /**
+   * When set, the registry loads from this file on construction (if it
+   * exists) and writes a JSON snapshot after every mutation. The parent
+   * directory is created on demand. Path resolution is the caller's
+   * responsibility — the registry treats the value as final.
+   */
+  persistPath?: string;
+}
+
+interface PersistShape {
+  version: 1;
+  swarms: SwarmRecord[];
+}
+
+function clampMaxAgents(n: unknown): number {
+  const v = typeof n === "number" && Number.isFinite(n) ? Math.floor(n) : DEFAULT_MAX_AGENTS;
+  if (v < MIN_MAX_AGENTS) return MIN_MAX_AGENTS;
+  if (v > MAX_MAX_AGENTS) return MAX_MAX_AGENTS;
+  return v;
+}
+
+function normalizeTopology(t: unknown): SwarmTopology {
+  if (typeof t === "string" && (SWARM_TOPOLOGIES as readonly string[]).includes(t)) {
+    return t as SwarmTopology;
+  }
+  return DEFAULT_TOPOLOGY;
+}
+
+export class SwarmTopologyRegistry {
+  private readonly swarms: Map<string, SwarmRecord> = new Map();
+  private defaultSeeded = false;
+  private persistPath?: string;
+
+  constructor(opts: SwarmTopologyRegistryOpts = {}) {
+    this.persistPath = opts.persistPath;
+    if (this.persistPath) this.loadFromDisk();
+  }
+
+  /**
+   * Configure (or clear) the persistence path after construction.
+   */
+  setPersistPath(path: string | undefined): void {
+    this.persistPath = path;
+    if (path) this.loadFromDisk();
+  }
+
+  private nextSwarmId(): string {
+    let i = 1;
+    while (this.swarms.has(`swarm-${i}`)) i++;
+    return `swarm-${i}`;
+  }
+
+  private ensureDefault(): void {
+    if (this.defaultSeeded) return;
+    this.defaultSeeded = true;
+    if (!this.swarms.has(DEFAULT_SWARM_ID)) {
+      const createdAt = new Date().toISOString();
+      this.swarms.set(DEFAULT_SWARM_ID, {
+        swarmId: DEFAULT_SWARM_ID,
+        topology: DEFAULT_TOPOLOGY,
+        maxAgents: DEFAULT_MAX_AGENTS,
+        agentIds: [],
+        createdAt,
+      });
+    }
+  }
+
+  initSwarm(input: InitSwarmInput = {}): InitSwarmResult {
+    this.ensureDefault();
+
+    let swarmId = input.swarmId?.trim();
+    if (!swarmId) swarmId = this.nextSwarmId();
+    if (this.swarms.has(swarmId)) {
+      throw new Error(`initSwarm: swarm already exists: ${swarmId}`);
+    }
+
+    const topology = normalizeTopology(input.topology);
+    const maxAgents = clampMaxAgents(input.maxAgents);
+    const createdAt = new Date().toISOString();
+    const record: SwarmRecord = {
+      swarmId,
+      topology,
+      maxAgents,
+      metadata: input.metadata,
+      agentIds: [],
+      createdAt,
+    };
+    this.swarms.set(swarmId, record);
+    this.persist();
+    return { swarmId, topology, maxAgents, createdAt, metadata: input.metadata };
+  }
+
+  getSwarm(swarmId: string): SwarmRecord | undefined {
+    return this.swarms.get(swarmId);
+  }
+
+  listSwarms(): SwarmRecord[] {
+    return Array.from(this.swarms.values());
+  }
+
+  recordAgentInSwarm(swarmId: string, agentId: string): SwarmRecord {
+    const record = this.swarms.get(swarmId);
+    if (!record) {
+      throw new Error(`recordAgentInSwarm: swarm not found: ${swarmId}`);
+    }
+    if (record.decommissionedAt) {
+      throw new Error(`recordAgentInSwarm: swarm is decommissioned: ${swarmId}`);
+    }
+    if (record.agentIds.length >= record.maxAgents && !record.agentIds.includes(agentId)) {
+      throw new Error(
+        `recordAgentInSwarm: swarm ${swarmId} is at maxAgents (${record.maxAgents})`,
+      );
+    }
+    if (!record.agentIds.includes(agentId)) {
+      record.agentIds.push(agentId);
+    }
+    this.persist();
+    return record;
+  }
+
+  decommissionSwarm(swarmId: string): SwarmRecord {
+    if (swarmId === DEFAULT_SWARM_ID) {
+      throw new Error("decommissionSwarm: cannot decommission the default swarm");
+    }
+    const record = this.swarms.get(swarmId);
+    if (!record) {
+      throw new Error(`decommissionSwarm: swarm not found: ${swarmId}`);
+    }
+    if (record.decommissionedAt) return record;
+    record.decommissionedAt = new Date().toISOString();
+    this.persist();
+    return record;
+  }
+
+  /**
+   * Test/dev helper: drop everything.
+   */
+  reset(): void {
+    this.swarms.clear();
+    this.defaultSeeded = false;
+    if (this.persistPath && existsSync(this.persistPath)) {
+      try { writeFileSync(this.persistPath, JSON.stringify({ version: 1, swarms: [] }, null, 2), "utf-8"); }
+      catch { /* best-effort */ }
+    }
+  }
+
+  // ── Persistence ───────────────────────────────────────────────────────
+
+  private loadFromDisk(): void {
+    if (!this.persistPath || !existsSync(this.persistPath)) return;
+    try {
+      const raw = readFileSync(this.persistPath, "utf-8");
+      const data = JSON.parse(raw) as Partial<PersistShape>;
+      if (Array.isArray(data.swarms)) {
+        for (const s of data.swarms) {
+          if (!s || typeof s.swarmId !== "string") continue;
+          this.swarms.set(s.swarmId, s);
+          if (s.swarmId === DEFAULT_SWARM_ID) this.defaultSeeded = true;
+        }
+      }
+    } catch {
+      // Corrupt or partial file — start fresh.
+    }
+  }
+
+  private persist(): void {
+    if (!this.persistPath) return;
+    try {
+      mkdirSync(dirname(this.persistPath), { recursive: true });
+      const data: PersistShape = {
+        version: 1,
+        swarms: Array.from(this.swarms.values()),
+      };
+      writeFileSync(this.persistPath, JSON.stringify(data, null, 2), "utf-8");
+    } catch {
+      // Persistence is best-effort.
+    }
+  }
+}
+
+/**
+ * Process-wide singleton used by MCP tools. Persistence defaults to
+ * `.harness/topology.json` in the current working directory.
+ */
+const _sharedRegistry = new SwarmTopologyRegistry({
+  persistPath: ".harness/topology.json",
+});
+
+export function initSwarm(input: InitSwarmInput = {}): InitSwarmResult {
+  return _sharedRegistry.initSwarm(input);
+}
+
+export function getSwarm(swarmId: string): SwarmRecord | undefined {
+  return _sharedRegistry.getSwarm(swarmId);
+}
+
+export function listSwarms(): SwarmRecord[] {
+  return _sharedRegistry.listSwarms();
+}
+
+export function recordAgentInSwarm(swarmId: string, agentId: string): SwarmRecord {
+  return _sharedRegistry.recordAgentInSwarm(swarmId, agentId);
+}
+
+export function decommissionSwarm(swarmId: string): SwarmRecord {
+  return _sharedRegistry.decommissionSwarm(swarmId);
+}
+
+/**
+ * Process-wide singleton used by MCP tools. Tests should construct
+ * their own `new SwarmTopologyRegistry()` to get an isolated, non-
+ * persistent instance.
+ */
+export const swarmTopologyRegistry = _sharedRegistry;