@polderlabs/bizar 6.3.0 → 7.0.0

package/packages/sdk/src/mcp/server.ts

@@ -23,7 +23,7 @@
  *         allowedTools: ["mcp__bizar__*"],
  *       },
  *     })) {
- *       console.log(msg);
+ *       handleAgentMessage(msg);
  *     }
  *
  * The MCP server can also be registered in `~/.claude/settings.json`
@@ -47,6 +47,22 @@ import {
   resolveVaultRoot,
 } from "../memory/index.js";
 import { checkDangerous } from "../dangerous-patterns.js";
+import { ModelRouter } from "../router/model-router.js";
+import { QLearningRouter } from "../router/q-learning-router.js";
+import { runDistillation } from "../router/memory-distillation.js";
+import { decideAgentWith } from "../router/index.js";
+import { bizarAgentRegistry } from "../agent-registry.js";
+import {
+  initSwarm as initSwarmOnRegistry,
+  DEFAULT_TOPOLOGY,
+  DEFAULT_MAX_AGENTS,
+  type SwarmTopology,
+} from "../swarm-topology.js";
+import { getSharedConsensus } from "../consensus/index.js";
+import {
+  createFederation,
+  type FederationHandle,
+} from "../federation/index.js";
 
 // We don't import from @anthropic-ai/claude-agent-sdk as a hard dep —
 // the package is optional. Callers pass the result of `tool()` and
@@ -372,6 +388,117 @@ const graphPathTool = defineTool<{ from: string; to: string }>(
   { readOnlyHint: true },
 );
 
+// ---------------------------------------------------------------------------
+// Swarm / agent lifecycle tools (F-032)
+// ---------------------------------------------------------------------------
+
+const agentSpawnTool = defineTool<{
+  type: string;
+  name?: string;
+  priority?: "low" | "normal" | "high" | "critical";
+  metadata?: string;
+}>(
+  "agent_spawn",
+  "Spawn a new agent in the in-process BizarAgentRegistry. Returns the new agentId. Heartbeat is a stub — this registry is a coordination surface, not an agent runtime.",
+  { type: "string", name: "string", priority: "string", metadata: "string" },
+  async ({ type, name, priority, metadata }) => {
+    try {
+      let parsedMetadata: Record<string, unknown> | undefined;
+      if (metadata && typeof metadata === "string" && metadata.trim().length > 0) {
+        try { parsedMetadata = JSON.parse(metadata) as Record<string, unknown>; }
+        catch { return err("agent_spawn: `metadata` must be a JSON string"); }
+      }
+      const result = bizarAgentRegistry.registerAgent({
+        type,
+        name,
+        priority,
+        metadata: parsedMetadata,
+      });
+      return ok(JSON.stringify(result, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+);
+
+const agentListTool = defineTool<{
+  status?: string;
+  type?: string;
+  limit?: number;
+  offset?: number;
+}>(
+  "agent_list",
+  "List agents tracked by the in-process BizarAgentRegistry. Filter by status (active|terminated|all) and/or type. Supports limit/offset pagination.",
+  { status: "string", type: "string", limit: "number", offset: "number" },
+  async ({ status, type, limit, offset }) => {
+    try {
+      const allowedStatuses = ["active", "terminated", "all"] as const;
+      type StatusFilter = typeof allowedStatuses[number];
+      const s: StatusFilter = (allowedStatuses as readonly string[]).includes(status ?? "")
+        ? (status as StatusFilter)
+        : "all";
+      const result = bizarAgentRegistry.listAgents({
+        status: s,
+        type,
+        limit: typeof limit === "number" ? limit : undefined,
+        offset: typeof offset === "number" ? offset : undefined,
+      });
+      return ok(JSON.stringify(result, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+  { readOnlyHint: true },
+);
+
+const agentTerminateTool = defineTool<{
+  agentId: string;
+  graceful?: boolean;
+  reason?: string;
+}>(
+  "agent_terminate",
+  "Terminate a registered agent. Returns the agentId, status, and terminatedAt timestamp. No-op if the agent is already terminated.",
+  { agentId: "string", graceful: "boolean", reason: "string" },
+  async ({ agentId, graceful, reason }) => {
+    try {
+      const result = bizarAgentRegistry.terminateAgent({
+        agentId,
+        reason,
+        graceful: graceful ?? true,
+      });
+      return ok(JSON.stringify(result, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+);
+
+const swarmInitTool = defineTool<{
+  topology?: string;
+  maxAgents?: number;
+  metadata?: string;
+}>(
+  "swarm_init",
+  "Initialize a new swarm in the SwarmTopologyRegistry. topology ∈ hierarchical|mesh|adaptive|collective|hierarchical-mesh (default 'hierarchical-mesh'); maxAgents clamped to [1,1000] (default 15). The 'default' swarm is created lazily on first call.",
+  { topology: "string", maxAgents: "number", metadata: "string" },
+  async ({ topology, maxAgents, metadata }) => {
+    try {
+      let parsedMetadata: Record<string, unknown> | undefined;
+      if (metadata && typeof metadata === "string" && metadata.trim().length > 0) {
+        try { parsedMetadata = JSON.parse(metadata) as Record<string, unknown>; }
+        catch { return err("swarm_init: `metadata` must be a JSON string"); }
+      }
+      const allowedTopologies: readonly SwarmTopology[] = [
+        "hierarchical", "mesh", "adaptive", "collective", "hierarchical-mesh",
+      ];
+      const topo: SwarmTopology = (allowedTopologies as readonly string[]).includes(topology ?? "")
+        ? (topology as SwarmTopology)
+        : DEFAULT_TOPOLOGY;
+      const max = typeof maxAgents === "number" ? maxAgents : DEFAULT_MAX_AGENTS;
+      const result = initSwarmOnRegistry({
+        topology: topo,
+        maxAgents: max,
+        metadata: parsedMetadata,
+      });
+      return ok(JSON.stringify(result, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+);
+
 // ---------------------------------------------------------------------------
 // Safety tool — exposed so any model can self-audit a Bash command
 // before running it.
@@ -390,6 +517,219 @@ const dangerCheckTool = defineTool<{ command: string }>(
   { readOnlyHint: true },
 );
 
+// ---------------------------------------------------------------------------
+// Self-learning tools (F-033 / ADR-174) — Thompson-sampling model
+// router + Q-learning agent router + memory distillation trigger.
+// ---------------------------------------------------------------------------
+
+/** Singleton model router — the priors accumulate across tool calls
+ *  within one MCP server instance, so the bandit can learn from
+ *  outcomes in real time. Tests construct their own router via the
+ *  exported `BIZAR_TOOLS` indirection. */
+const modelRouter = new ModelRouter();
+
+/** Singleton Q-learning router — same reasoning as above. */
+const agentRouter = new QLearningRouter();
+
+const modelRouteTool = defineTool<{ prompt: string }>(
+  "model_route",
+  "Adaptive model-tier routing. Returns the recommended tier ('flash'|'mid'|'expensive') for a prompt using a Thompson-sampling bandit over Beta(α,β) priors. Codemod-eligible prompts (var-to-const, remove-console, add-logging) short-circuit to 'flash' with codemodIntent set.",
+  { prompt: "string" },
+  async ({ prompt }) => {
+    try {
+      const decision = modelRouter.route(prompt);
+      return ok(JSON.stringify(decision, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+  { readOnlyHint: true },
+);
+
+const agentRouteTool = defineTool<{ task: string }>(
+  "agent_route",
+  "Adaptive agent routing. Returns the recommended Bizar agent (odin|frigg|vor|mimir|heimdall|thor|tyr|forseti) for a task using Q-learning over a 64-dim bag-of-words feature hash. Codemod-eligible tasks route to heimdall (the routine-implementation agent).",
+  { task: "string" },
+  async ({ task }) => {
+    try {
+      const decision = agentRouter.selectAgent(task);
+      return ok(JSON.stringify(decision, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+  { readOnlyHint: true },
+);
+
+const memoryDistillTool = defineTool<{ since?: string }>(
+  "memory_distill",
+  "Run the ReasoningBank distillation pipeline (ADR-174: RETRIEVE → JUDGE → DISTILL → CONSOLIDATE) over the in-process memory vault. Optionally filter entries by createdAt >= since. Returns {distilled, promoted, byTier} — promoted patterns are only emitted for oracle:test-exec or judge:fable tiers.",
+  { since: "string" },
+  async ({ since }) => {
+    try {
+      // The dashboard owns the consolidator module; the SDK tool
+      // shim reads directly from the vault and runs the same
+      // RETRIEVE → JUDGE → DISTILL → CONSOLIDATE pipeline inline,
+      // so the tool works without the dashboard process.
+      const root = resolveVaultRoot();
+      const all = listNotes(root, "", 10000);
+      const cutoff = since ? new Date(since) : null;
+      const entries = all
+        .filter((n) => !cutoff || !Number.isNaN(cutoff.getTime()) && new Date(
+          String(n.frontmatter?.createdAt ?? n.frontmatter?.created ?? 0),
+        ) >= cutoff)
+        .map((n) => ({
+          memory_id: n.relPath,
+          relPath: n.relPath,
+          frontmatter: n.frontmatter ?? {},
+          body: n.body ?? "",
+          kind: typeof (n.frontmatter?.kind ?? n.frontmatter?.type) === "string"
+            ? (n.frontmatter?.kind ?? n.frontmatter?.type) as string
+            : undefined,
+          created: typeof (n.frontmatter?.createdAt ?? n.frontmatter?.created) === "string"
+            ? (n.frontmatter?.createdAt ?? n.frontmatter?.created) as string
+            : undefined,
+        }));
+
+      // Static import — the SDK owns `memory-distillation.ts` so the
+      // tool can run the RETRIEVE → JUDGE → DISTILL → CONSOLIDATE
+      // pipeline without depending on the dashboard process.
+      const result = runDistillation(entries);
+      return ok(JSON.stringify({
+        distilled: result.patterns.length,
+        promoted: result.promoted.map((p: { id: string }) => p.id),
+        byTier: result.byTier,
+      }, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Self-learning orchestrator tool (F-033)
+//
+// Replaces the prompt-time heuristics in the Odin agent with a single
+// tool call. Combines the codemod tier-1 short-circuit, the
+// Q-learning agent pick, and the Thompson-bandit model-tier pick
+// behind one MCP `hooks_route` tool (matches ruflo
+// `v3/mcp/tools/hooks-tools.ts:1207`).
+// ---------------------------------------------------------------------------
+
+const hooksRouteTool = defineTool<{ task: string; explicitAgent?: string }>(
+  "hooks_route",
+  "Self-Learning router (F-033): decide which agent + model tier should handle a task. Returns {agent, modelTier, agentConfidence, modelConfidence, codemodIntent, surfacedTags}. surfacedTags contains the human-readable markers (e.g. [CODEMOD_AVAILABLE] / [TASK_MODEL_RECOMMENDATION]) that should be prepended to the prompt for downstream observability.",
+  { task: "string", explicitAgent: "string" },
+  async ({ task, explicitAgent }) => {
+    try {
+      const decision = decideAgentWith(modelRouter, agentRouter, {
+        task: String(task ?? ""),
+        explicitAgent: explicitAgent ? String(explicitAgent) : undefined,
+      });
+      return ok(JSON.stringify(decision, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+  { readOnlyHint: true },
+);
+
+// ---------------------------------------------------------------------------
+// Consensus tool (F-039) — thin PBFT-style 3-of-5 majority for
+// review/decision steps. Wraps the shared `getSharedConsensus()`
+// orchestrator; the MCP surface is intentionally minimal (one tool)
+// because the consensus layer is a coordination primitive — model
+// callers propose payloads, the cluster of 5 agents (odin / frigg /
+// vor / mimir / heimdall) reaches quorum, and the tool returns the
+// proposalId + status. Vote tally and view-change are internal — the
+// MCP caller drives the lifecycle through the orchestrator's
+// `castVote` / `viewChange` if it wants finer control.
+//
+// The payload is a JSON string so callers don't need a zod schema for
+// every consensus call; the orchestrator's replay-protection hash
+// keys on the canonicalized JSON anyway, so semantically equivalent
+// payloads collapse to the same proposalId.
+// ---------------------------------------------------------------------------
+
+const consensusProposeTool = defineTool<{
+  payload: string;
+  quorum?: number;
+  vote?: string;
+  agentId?: string;
+}>(
+  "consensus_propose",
+  "PBFT-style 3-of-5 majority consensus for Bizar review/decision steps. payload is a JSON-encoded string (canonicalized via JSON.stringify). vote ∈ yes|no|abstain (defaults to 'yes' from the local agent). agentId is the peer whose vote this call represents (defaults to the local agent = 'odin'). Returns { proposalId, status, phase, approvals, rejections }. Re-submitting the same payload in the same view returns the cached proposalId (replay protection).",
+  { payload: "string", quorum: "number", vote: "string", agentId: "string" },
+  async ({ payload, quorum, vote, agentId }) => {
+    try {
+      if (typeof payload !== "string" || payload.trim().length === 0) {
+        return err("consensus_propose: `payload` must be a non-empty JSON string");
+      }
+      let parsedPayload: unknown;
+      try {
+        parsedPayload = JSON.parse(payload);
+      } catch (e) {
+        return err(`consensus_propose: \`payload\` is not valid JSON: ${String(e)}`);
+      }
+      const consensus = getSharedConsensus();
+      const proposeResult = consensus.propose(parsedPayload);
+      const v: "yes" | "no" | "abstain" =
+        vote === "no" || vote === "abstain" ? vote : "yes";
+      const voter = agentId && agentId.trim().length > 0 ? agentId.trim() : consensus.localAgentId;
+      const voteResult = consensus.castVote(
+        proposeResult.proposalId,
+        voter,
+        v,
+      );
+      return ok(JSON.stringify({
+        proposalId: voteResult.proposalId,
+        status: voteResult.status,
+        phase: voteResult.phase,
+        approvals: voteResult.approvals,
+        rejections: voteResult.rejections,
+        abstentions: voteResult.abstentions,
+        committed: voteResult.committed,
+        quorum: quorum ?? consensus.getQuorum(),
+        currentProposer: consensus.getCurrentProposer(),
+        viewNumber: consensus.getViewNumber(),
+      }, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Federation tool (F-038) — Cross-installation agent federation
+// skeleton. Reads status from the shared `createFederation()` handle
+// (one per MCP server instance). The handle is configured against
+// `.harness/federation-audit.log` + `.harness/federation-budget.json`
+// under the project root. Per-call signing/receiving is not exposed
+// as a tool here — it's a library API used by the dashboard / future
+// transport layer; the MCP surface is intentionally a status probe
+// so callers can check peer trust + audit size + budget headroom
+// without needing to import the SDK.
+// ---------------------------------------------------------------------------
+
+function resolveFederationHandle(): FederationHandle {
+  const root = findRepoRoot();
+  const nodeId = `${root.replace(/[^a-zA-Z0-9_-]+/g, "_")}-mcp`;
+  // Shared secret per repo — the F-038 skeleton is in-process, so a
+  // hard-coded secret is fine for the status probe. Real deployments
+  // would source this from the env (BIZAR_FEDERATION_SECRET).
+  const secret = process.env.BIZAR_FEDERATION_SECRET ?? `bizar-federation-${root}`;
+  return createFederation({
+    nodeId,
+    secret,
+    auditPath: join(root, ".harness", "federation-audit.log"),
+    budgetPath: join(root, ".harness", "federation-budget.json"),
+  });
+}
+
+const federationStatusTool = defineTool<Record<string, never>>(
+  "federation_status",
+  "Federation skeleton status probe (F-038). Returns { nodeId, peers, nonceCacheSize, auditSizeBytes, auditPath, budget: { path, perPeer, outstandingReservations } }. Reads from the local createFederation() handle configured against .harness/federation-audit.log + .harness/federation-budget.json. Read-only.",
+  {},
+  async () => {
+    try {
+      const handle = resolveFederationHandle();
+      const snap = handle.status();
+      return ok(JSON.stringify(snap, null, 2));
+    } catch (e) { return err(String(e)); }
+  },
+  { readOnlyHint: true },
+);
+
 // ---------------------------------------------------------------------------
 // Factory — wire all tools into an MCP server
 // ---------------------------------------------------------------------------
@@ -408,6 +748,16 @@ export const BIZAR_TOOLS: SdkMcpToolDef[] = [
   graphQueryTool,
   graphPathTool,
   dangerCheckTool,
+  agentSpawnTool,
+  agentListTool,
+  agentTerminateTool,
+  swarmInitTool,
+  modelRouteTool,
+  agentRouteTool,
+  memoryDistillTool,
+  hooksRouteTool,
+  consensusProposeTool,
+  federationStatusTool,
 ];
 
 /**

package/packages/sdk/src/router/codemod-intent.ts

@@ -0,0 +1,125 @@
+/**
+ * router/codemod-intent.ts — Tier-1 codemod intent detection.
+ *
+ * v6.4.0 — ported from ruflo `enhanced-model-router.ts` (ADR-026, ADR-143).
+ *
+ * Three deterministic intents are eligible for $0 Tier-1 codemod
+ * execution — they can be applied structurally, no LLM in the loop:
+ *
+ *   - `var-to-const`   — convert `var` declarations to `const` / `let`.
+ *   - `remove-console` — strip `console.*` calls.
+ *   - `add-logging`    — add `console.*` / logger statements.
+ *
+ * Other intents (`add-types`, `add-error-handling`, `async-await`, …)
+ * REQUIRE judgement and route to a model tier (Tier-2/3); they are
+ * explicitly OUT OF SCOPE for this detector. See ADR-143.
+ *
+ * Pure function — no I/O. Confidence is the match strength
+ * (number of distinct regex patterns that hit, normalised by pattern
+ * count; capped at 1.0). Returning `null` means the prompt is NOT
+ * codemod-eligible and the caller should consult the bandit / neural
+ * router.
+ */
+
+export type CodemodIntent = "var-to-const" | "remove-console" | "add-logging";
+
+export interface CodemodIntentHit {
+  intent: CodemodIntent;
+  confidence: number;
+}
+
+const PATTERNS: Record<CodemodIntent, RegExp[]> = {
+  "var-to-const": [
+    /convert\s+var\s+to\s+const/i,
+    /convert\s+var\s+declarations?\s+to\s+const/i,
+    /change\s+var\s+to\s+const/i,
+    /change\s+var\s+declarations?\s+to\s+const/i,
+    /replace\s+var\s+with\s+const/i,
+    /var\s*(?:→|->|to)\s*const/i,
+    /use\s+const\s+instead\s+of\s+var/i,
+    /\bvar\s+to\s+const\b/i,
+  ],
+  "remove-console": [
+    /remove\s+(?:all\s+)?console\.log/i,
+    /remove\s+(?:all\s+)?console\s+statements?/i,
+    /delete\s+(?:all\s+)?console\s+statements?/i,
+    /strip\s+console/i,
+    /clean\s+up\s+console/i,
+    /clean\s+up\s+debug\s+logs?/i,
+    /remove\s+(?:all\s+)?debug\s+logs?/i,
+    /delete\s+(?:all\s+)?console\.log/i,
+    /strip\s+(?:all\s+)?console/i,
+  ],
+  "add-logging": [
+    /\badd\s+logging\b/i,
+    /\badd\s+console\.log\b/i,
+    /\badd\s+debug\s+logs?\b/i,
+    /\blog\s+this\s+function\b/i,
+    /\badd\s+trace\s+logging\b/i,
+    /\binstrument\s+with\s+logs?\b/i,
+  ],
+};
+
+/**
+ * Default confidence threshold for `detectCodemodIntent`. The function
+ * returns `null` for pattern-set hits with confidence below this.
+ *
+ * Kept intentionally low (0.1) so a single canonical phrase on a
+ * 7-pattern intent — natural prompts like "convert var to const" —
+ * still short-circuits the bandit. Callers that want stricter
+ * filtering (the F-033 orchestrator `decideAgentWith`, see ADR-174)
+ * can pass `threshold` explicitly.
+ *
+ * Strong threshold the spec mentions ("Return null if confidence < 0.6")
+ * is exported as `STRICT_CODEMOD_CONFIDENCE_THRESHOLD` below.
+ */
+export const DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD = 0.1;
+export const STRICT_CODEMOD_CONFIDENCE_THRESHOLD = 0.6;
+/** Alias used in the spec — kept for backwards compat. */
+export const CODEMOD_CONFIDENCE_THRESHOLD = DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD;
+
+export interface CodemodDetectionOptions {
+  /** Override the threshold. Default:
+   *  `DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD` (=0.1). */
+  threshold?: number;
+}
+
+/**
+ * Probe whether a prompt matches one of the deterministic codemod
+ * intents. Order matters only for tie-breaking: we return the FIRST
+ * intent whose overall score is highest in case of a multi-intent
+ * tie.
+ *
+ * Confidence is `hits / patterns.length`. A single regex hit on a
+ * intent with 7 patterns yields confidence 1/7 ≈ 0.14 — enough to
+ * flag the intent but well below 1.0 so the caller can decide
+ * whether to escalate. Two hits on a smaller intent (say 4
+ * patterns) yields 0.5 — past the 0.4 bandit-confirmation
+ * threshold.
+ *
+ * Result filtered by `opts.threshold` (default 0.1). When the
+ * strongest pattern-set hit is below the threshold the function
+ * returns `null` so the caller falls through to Q-learning / bandit.
+ */
+export function detectCodemodIntent(
+  prompt: string,
+  opts: CodemodDetectionOptions = {},
+): CodemodIntentHit | null {
+  if (!prompt || typeof prompt !== "string") return null;
+
+  let best: { intent: CodemodIntent; confidence: number } | null = null;
+  for (const intent of Object.keys(PATTERNS) as CodemodIntent[]) {
+    const patterns = PATTERNS[intent];
+    let hits = 0;
+    for (const p of patterns) if (p.test(prompt)) hits += 1;
+    if (hits === 0) continue;
+    const confidence = hits / patterns.length;
+    if (best === null || confidence > best.confidence) {
+      best = { intent, confidence };
+    }
+  }
+  if (best === null) return null;
+  const threshold = opts.threshold ?? DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD;
+  if (best.confidence < threshold) return null;
+  return best;
+}