@polderlabs/bizar 6.2.5 → 7.0.0

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

@@ -0,0 +1,147 @@
+/**
+ * consensus/index.ts — Public orchestrator for the consensus layer.
+ *
+ * F-039 — wraps `ByzantineConsensus` behind a stable factory API and
+ * re-exports every type/utility callers need. This is the surface the
+ * MCP tool (`consensus_propose`) and any future dashboard wiring
+ * consume.
+ *
+ * The orchestrator is intentionally minimal — it's a thin facade over
+ * `ByzantineConsensus` plus the type re-exports. Anything fancier
+ * (proposer scheduling, fault dashboards, etc.) belongs in `queen.ts`
+ * or a future `dashboard.ts`.
+ */
+
+import { ByzantineConsensus, type ByzantineConsensusOpts } from "./byzantine.js";
+import {
+  DEFAULT_MAX_FAULTS,
+  DEFAULT_QUORUM,
+  type CommitResult,
+  type ConsensusStatus,
+  type Decision,
+  type ProposeResult,
+  type ProposalSnapshot,
+  type Vote,
+  type VoteResult,
+  type ViewChangeResult,
+} from "./types.js";
+
+export interface CreateConsensusOpts extends Omit<ByzantineConsensusOpts, "localAgentId" | "peers"> {
+  localAgentId: string;
+  peers: string[];
+}
+
+export interface ConsensusHandle {
+  /** Identity of the local agent (vote short-circuits on its own calls). */
+  readonly localAgentId: string;
+  /** Read-only snapshot of every proposal the instance has tracked. */
+  status(): ConsensusStatus;
+  /** Snapshot of a single proposal, or `undefined` if unknown. */
+  getProposal(proposalId: string): ProposalSnapshot | undefined;
+  /** Initiate pre-prepare for a new proposal. Re-submitting the same
+   *  payload under the same view returns the cached proposalId. */
+  propose(payload: unknown): ProposeResult;
+  /** Cast a vote for a peer during the `prepare` phase. */
+  castVote(proposalId: string, agentId: string, decision: Decision, signature?: string): VoteResult;
+  /** Transport-friendly entry point — `onPrepare(proposalId, vote)`. */
+  onPrepare(proposalId: string, vote: Vote): VoteResult;
+  /** Force-commit a proposal (admin override; rare). */
+  commit(proposalId: string): CommitResult;
+  /** Trigger a view-change; returns the new proposer + view number. */
+  viewChange(reason: string, proposalId?: string): ViewChangeResult;
+  /** Head of the round-robin proposer schedule. */
+  getCurrentProposer(): string;
+  /** Current view number (incremented on every view-change). */
+  getViewNumber(): number;
+  /** Quorum threshold in effect. */
+  getQuorum(): number;
+  /** Peer roster (read-only copy). */
+  getPeers(): string[];
+}
+
+/**
+ * Build a `ConsensusHandle` for a given local agent + peer roster.
+ * The returned object is the public surface used by the MCP tool and
+ * any dashboard wiring.
+ */
+export function createConsensus(opts: CreateConsensusOpts): ConsensusHandle {
+  const instance = new ByzantineConsensus(opts);
+  return {
+    localAgentId: opts.localAgentId,
+    status: () => instance.status(),
+    getProposal: (id) => instance.getProposal(id),
+    propose: (payload) => instance.propose(payload),
+    castVote: (proposalId, agentId, decision, signature) =>
+      instance.castVote(proposalId, agentId, decision, signature),
+    onPrepare: (proposalId, vote) => instance.onPrepare(proposalId, vote),
+    commit: (proposalId) => instance.commit(proposalId),
+    viewChange: (reason, proposalId) => instance.viewChange(reason, proposalId),
+    getCurrentProposer: () => instance.getCurrentProposer(),
+    getViewNumber: () => instance.getViewNumber(),
+    getQuorum: () => instance.getQuorum(),
+    getPeers: () => instance.getPeers(),
+  };
+}
+
+// ─── Re-exports ────────────────────────────────────────────────────────
+
+export { ByzantineConsensus, type ByzantineConsensusOpts } from "./byzantine.js";
+export { QueenCoordinator, type QueenCoordinatorOpts } from "./queen.js";
+export {
+  DEFAULT_MAX_FAULTS,
+  DEFAULT_PEER_COUNT,
+  DEFAULT_QUORUM,
+  PHASE_ORDER,
+} from "./types.js";
+export type {
+  CommitResult,
+  ConsensusOpts,
+  ConsensusStatus,
+  Decision,
+  Phase,
+  ProposeResult,
+  Proposal,
+  ProposalSnapshot,
+  ProposalStatus,
+  Vote,
+  VoteResult,
+  ViewChangeResult,
+} from "./types.js";
+
+// ─── Process-wide singleton ───────────────────────────────────────────
+
+/**
+ * The shared consensus singleton used by the MCP tool. Initialized
+ * with the Bizar default 5-peer roster (odin / frigg / vor / mimir /
+ * heimdall — the same five Norse agents F-033 routes between) and a
+ * deterministic seed so MCP-driven consensus is reproducible across
+ * restarts. Tests should call `createConsensus()` with their own
+ * `localAgentId` + `peers` to get an isolated instance.
+ *
+ * The roster here is intentional — it maps to the existing 5-agent
+ * surface F-033 already exposes, so a single MCP call can drive the
+ * same set of agents the orchestrator routes to.
+ */
+const DEFAULT_PEERS: readonly string[] = ["odin", "frigg", "vor", "mimir", "heimdall"];
+const DEFAULT_LOCAL_AGENT = "odin";
+const DEFAULT_PROPOSER_SEED = "bizar-f039-default";
+
+let _shared: ConsensusHandle | null = null;
+
+export function getSharedConsensus(): ConsensusHandle {
+  if (_shared) return _shared;
+  _shared = createConsensus({
+    localAgentId: DEFAULT_LOCAL_AGENT,
+    peers: [...DEFAULT_PEERS],
+    quorum: DEFAULT_QUORUM,
+    maxFaults: DEFAULT_MAX_FAULTS,
+    proposerSeed: DEFAULT_PROPOSER_SEED,
+    historyLimit: 50,
+  });
+  return _shared;
+}
+
+/** Reset the singleton — test/dev only. */
+export function resetSharedConsensus(): void {
+  _shared = null;
+}

package/packages/sdk/src/consensus/queen.ts

@@ -0,0 +1,173 @@
+/**
+ * consensus/queen.ts — Proposer election (QueenCoordinator).
+ *
+ * F-039 — thin port of ruflo's capability-scored QueenCoordinator
+ * (v3/@claude-flow/swarm/src/coordination/queen-coordinator.ts) for
+ * the consensus layer's proposer selection. Bizar needs a deterministic,
+ * fault-aware round-robin; we don't port the full ReasoningBank pattern
+ * matching because Bizar's review steps don't have agent capability
+ * vectors — they have peer rosters + a fault log.
+ *
+ * Algorithm: round-robin weighted by recent fault count. A peer with
+ * N faults is skipped N times before becoming proposer again. With
+ * `proposerSeed`, the initial head is computed deterministically so
+ * tests can pin it.
+ */
+
+export interface QueenCoordinatorOpts {
+  /** Full peer roster, in the order round-robin walks them. Required. */
+  peers: string[];
+  /** Maximum Byzantine faults the cluster can tolerate (used as the
+   *  skip-multiplier floor). Defaults to 1. */
+  maxFaults?: number;
+  /** Optional seed — when set, the initial head is `peers[seedHash % peers.length]`. */
+  seed?: string;
+}
+
+/**
+ * Tracks per-peer fault counts and walks the peer list in
+ * round-robin order, skipping any peer whose `faultCount` is greater
+ * than the candidate's expected count at that position.
+ *
+ * Concretely: if peer X has faultCount 2, the next 2 round-robin
+ * positions that would land on X skip it instead and the proposer
+ * becomes the peer at the next non-skipped position. After 2
+ * `advance()` calls (or `selectProposer` calls that consumed a skip),
+ * X is eligible again.
+ *
+ * The fault penalty decays as the round-robin walks — this keeps
+ * the cluster moving even when one peer has accumulated many faults.
+ */
+export class QueenCoordinator {
+  private readonly peers: readonly string[];
+  /** Maximum Byzantine faults the cluster is sized for (used as the
+   *  skip-multiplier floor — `recordFault` adds a skip of size
+   *  `maxFaults` so the worst peer is skipped `maxFaults` rounds). */
+  private readonly maxFaults: number;
+  /** Per-peer cumulative fault count. */
+  private readonly faults: Map<string, number> = new Map();
+  /** Per-peer remaining-skip count (decremented on every advance). */
+  private readonly skips: Map<string, number> = new Map();
+  /** Current head of the round-robin walk. */
+  private cursor = 0;
+
+  constructor(opts: QueenCoordinatorOpts) {
+    if (!opts || !Array.isArray(opts.peers) || opts.peers.length === 0) {
+      throw new Error("QueenCoordinator: `peers` is required and must be non-empty");
+    }
+    const seen = new Set<string>();
+    for (const p of opts.peers) {
+      if (typeof p !== "string" || p.length === 0) {
+        throw new Error("QueenCoordinator: every peer id must be a non-empty string");
+      }
+      if (seen.has(p)) {
+        throw new Error(`QueenCoordinator: duplicate peer id "${p}"`);
+      }
+      seen.add(p);
+      this.faults.set(p, 0);
+      this.skips.set(p, 0);
+    }
+    this.peers = [...opts.peers];
+    this.maxFaults = Math.max(0, opts.maxFaults ?? 1);
+    if (opts.seed) {
+      this.cursor = this.seedCursor(opts.seed);
+    }
+  }
+
+  /** Current proposer (head of the round-robin walk). */
+  currentProposer(): string {
+    return this.peers[this.cursor % this.peers.length] as string;
+  }
+
+  /** Record a fault against a peer (the proposer just voted `no`, or
+   *  missed its pre-prepare window). Increments both the cumulative
+   *  fault log and the per-peer skip counter — the peer is then
+   *  skipped for `maxFaults` round-robin steps before becoming
+   *  proposer-eligible again. With `maxFaults = 1` (the F-039
+   *  default), one fault skips the peer for one round. */
+  recordFault(peerId: string): void {
+    if (!this.faults.has(peerId)) {
+      throw new Error(`recordFault: unknown peer "${peerId}"`);
+    }
+    this.faults.set(peerId, (this.faults.get(peerId) ?? 0) + 1);
+    this.skips.set(peerId, (this.skips.get(peerId) ?? 0) + this.maxFaults);
+  }
+
+  /**
+   * Walk one step forward. Skips any peer whose remaining-skip count
+   * is > 0 (decrementing the counter as it skips). Returns the new
+   * proposer.
+   */
+  advance(): string {
+    const n = this.peers.length;
+    let steps = 0;
+    while (steps < n) {
+      this.cursor = (this.cursor + 1) % n;
+      const candidate = this.peers[this.cursor] as string;
+      const skip = this.skips.get(candidate) ?? 0;
+      if (skip > 0) {
+        this.skips.set(candidate, skip - 1);
+        steps++;
+        continue;
+      }
+      return candidate;
+    }
+    // Everyone had skip > 0 — we walked the full circle and decremented
+    // everyone. Just return where we landed.
+    return this.peers[this.cursor] as string;
+  }
+
+  /**
+   * Equivalent to `selectProposer(peers, recentFaults)` from the F-039
+   * spec — but stateful, because we own the fault log. Returns the
+   * current proposer without advancing.
+   */
+  selectProposer(): string {
+    // If the current proposer has a non-zero skip, walk forward to find
+    // the next eligible peer.
+    const n = this.peers.length;
+    let probe = this.cursor;
+    for (let i = 0; i < n; i++) {
+      const candidate = this.peers[probe] as string;
+      const skip = this.skips.get(candidate) ?? 0;
+      if (skip === 0) return candidate;
+      probe = (probe + 1) % n;
+    }
+    // All peers have skip > 0 — same fallback as advance().
+    return this.peers[this.cursor] as string;
+  }
+
+  /** Cumulative fault counts (read-only snapshot). */
+  faultCounts(): Record<string, number> {
+    return Object.fromEntries(this.faults);
+  }
+
+  /** Number of peers currently under a skip penalty. */
+  pendingSkipCount(): number {
+    let n = 0;
+    for (const v of this.skips.values()) if (v > 0) n++;
+    return n;
+  }
+
+  /** Test/dev helper: drop the cursor and fault counts. */
+  reset(): void {
+    this.cursor = 0;
+    for (const k of this.faults.keys()) this.faults.set(k, 0);
+    for (const k of this.skips.keys()) this.skips.set(k, 0);
+  }
+
+  // ─── Helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Stable hash of an optional seed string → integer cursor in
+   * `[0, peers.length)`. Lets a test caller pin the initial proposer
+   * for replay safety (F-039 determinism rule).
+   */
+  private seedCursor(seed: string): number {
+    let h = 5381;
+    for (let i = 0; i < seed.length; i++) {
+      h = ((h << 5) + h + seed.charCodeAt(i)) >>> 0;
+    }
+    return h % this.peers.length;
+  }
+}

package/packages/sdk/src/consensus/types.ts

@@ -0,0 +1,199 @@
+/**
+ * consensus/types.ts — Shared type definitions for the in-process
+ * Byzantine consensus layer.
+ *
+ * F-039 — thin port of ruflo's `v3/@claude-flow/swarm/src/consensus/byzantine.ts`
+ * for Bizar's review/decision steps. We carry the full PBFT phase
+ * vocabulary (pre-prepare / prepare / commit / reply) and a 3-of-5
+ * simple-majority quorum — enough surface for Bizar to gate
+ * multi-agent review decisions without the operational cost of full
+ * PBFT (no transport, no crypto signatures, no checkpoint protocol).
+ *
+ * Determinism rule: quorum math is purely set-based. The only place
+ * randomness (or ordering) enters is the optional round-robin
+ * proposer election in `queen.ts`, and even there the caller can
+ * pass an explicit seed for replay safety.
+ */
+
+// ─── Phase vocabulary ──────────────────────────────────────────────────
+
+/**
+ * PBFT-style phase identifiers. Each proposal walks
+ * `pre-prepare → prepare → commit → reply` in order.
+ */
+export type Phase =
+  | "pre-prepare"
+  | "prepare"
+  | "commit"
+  | "reply";
+
+export const PHASE_ORDER: readonly Phase[] = [
+  "pre-prepare",
+  "prepare",
+  "commit",
+  "reply",
+] as const;
+
+/** Decision a peer casts during the `prepare` phase. */
+export type Decision = "yes" | "no" | "abstain";
+
+// ─── Messages ──────────────────────────────────────────────────────────
+
+/**
+ * A vote cast by a peer during the `prepare` phase. The signature
+ * field is a free-form string — we don't enforce cryptographic
+ * signatures in the thin port (no transport), but callers that
+ * wire in a transport can stuff an HMAC in here without changing
+ * the shape.
+ */
+export interface Vote {
+  agentId: string;
+  phase: Extract<Phase, "prepare">;
+  decision: Decision;
+  signature?: string;
+  /** Wall-clock timestamp at which the peer emitted the vote. */
+  timestamp: string;
+}
+
+/**
+ * A proposal is the unit of agreement. `proposer` is the agent that
+ * initiated pre-prepare; `quorum` is the number of matching `yes`
+ * votes required for commit (3-of-5 simple majority by default).
+ */
+export interface Proposal {
+  id: string;
+  payload: unknown;
+  proposer: string;
+  quorum: number;
+  /** Total peer count this proposal was negotiated against (incl. proposer). */
+  peerCount: number;
+  /** Current phase, drives which transitions are legal. */
+  phase: Phase;
+  /** Set of agentIds that have voted `yes` in `prepare`. */
+  approvals: Set<string>;
+  /** Set of agentIds that have voted `no` in `prepare`. */
+  rejections: Set<string>;
+  /** Set of agentIds that have voted `abstain`. */
+  abstentions: Set<string>;
+  /** Free-form reason for `view-change` (set if status === 'view-change'). */
+  viewChangeReason?: string;
+  /** Set when the proposal is committed. */
+  committedAt?: string;
+  /** Set when the proposal is finalized (reply phase). */
+  finalizedAt?: string;
+  /** Wall-clock timestamp at which the proposer started pre-prepare. */
+  createdAt: string;
+}
+
+export type ProposalStatus =
+  | "pending"
+  | "pre-prepare"
+  | "prepare"
+  | "commit"
+  | "reply"
+  | "view-change"
+  | "committed"
+  | "rejected"
+  | "expired";
+
+/** A snapshot of a proposal for the public `status()` query. */
+export interface ProposalSnapshot {
+  id: string;
+  status: ProposalStatus;
+  phase: Phase;
+  proposer: string;
+  quorum: number;
+  peerCount: number;
+  approvals: number;
+  rejections: number;
+  abstentions: number;
+  createdAt: string;
+  committedAt?: string;
+  finalizedAt?: string;
+  viewChangeReason?: string;
+  payload: unknown;
+}
+
+// ─── Quorum ────────────────────────────────────────────────────────────
+
+/** 3-of-5 simple majority quorum, per the F-039 spec. */
+export const DEFAULT_QUORUM = 3;
+export const DEFAULT_PEER_COUNT = 5;
+
+/** The default fault tolerance — at most 1 Byzantine peer per cluster. */
+export const DEFAULT_MAX_FAULTS = 1;
+
+// ─── Consensus status (returned by `status()`) ─────────────────────────
+
+export interface ConsensusStatus {
+  /** All proposals the instance has processed, in arrival order. */
+  proposals: ProposalSnapshot[];
+  /** Current proposer (head of the round-robin schedule, weighted by faults). */
+  currentProposer: string;
+  /** View number — increments on every view-change. */
+  viewNumber: number;
+  /** Total proposals ever committed (status === 'committed'). */
+  committed: number;
+  /** Total proposals ever rejected (status === 'rejected'). */
+  rejected: number;
+  /** Total proposals ever expired (status === 'expired'). */
+  expired: number;
+  /** Total view-changes triggered by a faulty proposer. */
+  viewChanges: number;
+}
+
+// ─── Constructor / orchestrator options ─────────────────────────────────
+
+export interface ConsensusOpts {
+  /** Local agent id — votes cast by `localAgentId` are short-circuited
+   *  to `prepare`. Required. */
+  localAgentId: string;
+  /** Full peer roster (including `localAgentId`). Order matters for
+   *  round-robin proposer election. Required. */
+  peers: string[];
+  /** Quorum threshold for `prepare → commit`. Defaults to 3. */
+  quorum?: number;
+  /** Maximum Byzantine faults the cluster is sized for. Defaults to 1. */
+  maxFaults?: number;
+  /** Wall-clock timeout (ms) after which a pending proposal expires. */
+  /** Optional seed for round-robin proposer election — makes proposer
+   *  selection deterministic for tests. If absent, round-robin walks
+   *  the peer list in the order given. */
+  proposerSeed?: string;
+  /** A clock function for deterministic timestamps in tests. */
+  now?: () => Date;
+}
+
+// ─── Public result shapes ──────────────────────────────────────────────
+
+export interface ProposeResult {
+  proposalId: string;
+  status: ProposalStatus;
+  phase: Phase;
+}
+
+export interface VoteResult {
+  proposalId: string;
+  status: ProposalStatus;
+  phase: Phase;
+  approvals: number;
+  rejections: number;
+  abstentions: number;
+  committed: boolean;
+}
+
+export interface CommitResult {
+  proposalId: string;
+  status: ProposalStatus;
+  committedAt: string;
+  finalizedAt: string;
+  approvals: number;
+}
+
+export interface ViewChangeResult {
+  previousProposer: string;
+  newProposer: string;
+  viewNumber: number;
+  reason: string;
+  proposalId: string;
+}

package/{plugins/bizar → packages/sdk}/src/dangerous-patterns.ts

@@ -5,20 +5,10 @@
  * + OpenFang `crates/openfang-skills/src/verify.rs` + OpenClaw
  * `src/security/external-content.ts:28-43`.
  *
- * Detects dangerous commands and blocks/requires approval before
- * tool execution. Every tool that takes a "command" or "path"
- * argument runs through `checkDangerous()` before being dispatched.
- *
- * Categories:
- *   - Filesystem destruction (rm -rf, mkfs, dd, fork bombs)
- *   - Privilege escalation (sudo, su, chmod 777, chown)
- *   - Network exfiltration (curl to metadata, wget, nc backdoors)
- *   - Process control (kill -9 1, pkill, shutdown)
- *   - Crypto mining (xmrig, minerd)
- *   - Path traversal in file paths (../../etc/passwd, ~/.ssh/)
- *
- * v6.0.0 — initial patterns. Tuned to catch the common exploits
- * without false positives on legitimate dev work.
+ * Detects dangerous commands and blocks/requires approval before tool
+ * execution. Every tool that takes a "command" or "path" argument runs
+ * through `checkDangerous()` before being dispatched. Framework-agnostic
+ * — used by both the SDK MCP server and any Claude Code hook scripts.
  */
 
 export type ApprovalDecision = "allow" | "require-approval" | "deny";
@@ -30,8 +20,6 @@ export interface ApprovalCheck {
   pattern?: string;
 }
 
-// 30+ patterns from Hermes + OpenFang + OpenClaw. Catches the common
-// dangerous operations in coding-agent contexts.
 const DANGEROUS_PATTERNS: Array<{ name: string; pattern: RegExp; decision: ApprovalDecision; reason: string }> = [
   // Filesystem destruction
   { name: "rm-rf-root", pattern: /\brm\s+(-\w*r\w*f\w*\s+)*\/\s*$/i, decision: "deny", reason: "Recursive delete of root filesystem" },
@@ -62,10 +50,10 @@ const DANGEROUS_PATTERNS: Array<{ name: string; pattern: RegExp; decision: Appro
   { name: "shutdown", pattern: /\b(shutdown|halt|poweroff|reboot)\b/i, decision: "deny", reason: "System shutdown" },
   { name: "init-0", pattern: /\binit\s+0\b/i, decision: "deny", reason: "init 0 (shutdown)" },
 
-  // Crypto mining (common malware)
+  // Crypto mining
   { name: "xmrig", pattern: /\b(xmrig|minerd|cpuminer|cgminer)\b/i, decision: "deny", reason: "Crypto miner" },
 
-  // Package management (often exploited)
+  // Package management
   { name: "pip-install-shell", pattern: /\bpip\s+install\s+.*\|\s*(ba)?sh\b/i, decision: "deny", reason: "pip install piped to shell" },
   { name: "npm-install-shell", pattern: /\bnpm\s+install\s+.*\|\s*(ba)?sh\b/i, decision: "deny", reason: "npm install piped to shell" },
 
@@ -90,15 +78,7 @@ const DANGEROUS_PATTERNS: Array<{ name: string; pattern: RegExp; decision: Appro
   { name: "system-prompt-leak", pattern: /reveal\s+(your\s+)?system\s+prompt/i, decision: "deny", reason: "Prompt extraction attempt" },
 ];
 
-/**
- * Check a tool call's arguments for dangerous patterns.
- * Returns a decision (allow / require-approval / deny) and a reason.
- *
- * The check is applied to the union of all string-typed arguments,
- * so the caller doesn't need to know which arg is the "command".
- */
 export function checkDangerous(args: Record<string, unknown>): ApprovalCheck {
-  // Collect all string values from the args object
   const text = collectStrings(args);
   if (!text) return { decision: "allow" };
 
@@ -128,12 +108,10 @@ function collectStrings(value: unknown, parts: string[] = []): string {
   return parts.join("\n");
 }
 
-/** Get all pattern names (for audit / reporting). */
 export function listDangerousPatterns(): string[] {
   return DANGEROUS_PATTERNS.map((p) => p.name);
 }
 
-/** Count of patterns in each category. */
 export function getDangerousPatternStats(): {
   total: number;
   deny: number;