@consensus-tools/universal 0.9.0

package/src/resolve.ts

@@ -0,0 +1,30 @@
+import type { ToolExecutor, Wrappable } from "./types.js";
+
+/**
+ * Resolves a Wrappable into a plain ToolExecutor function.
+ *
+ * Resolution order: direct function > .execute > .invoke > .call
+ * First match wins.
+ */
+export function resolveWrappable(wrappable: Wrappable): ToolExecutor {
+  if (typeof wrappable === "function") {
+    return wrappable;
+  }
+
+  if (typeof wrappable === "object" && wrappable !== null) {
+    if ("execute" in wrappable && typeof wrappable.execute === "function") {
+      return wrappable.execute.bind(wrappable);
+    }
+    if ("invoke" in wrappable && typeof wrappable.invoke === "function") {
+      return wrappable.invoke.bind(wrappable);
+    }
+    if ("call" in wrappable && typeof wrappable.call === "function") {
+      return wrappable.call.bind(wrappable);
+    }
+  }
+
+  throw new TypeError(
+    "Expected a Wrappable: a function, or an object with .execute(), .invoke(), or .call() method. " +
+    `Received: ${typeof wrappable}`,
+  );
+}

package/src/risk-tiers.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { classifyTool } from "./risk-tiers.js";
+
+describe("classifyTool", () => {
+  it("classifies read-only tools as low risk", () => {
+    expect(classifyTool("get_weather")).toBe("low");
+    expect(classifyTool("list_files")).toBe("low");
+    expect(classifyTool("search_documents")).toBe("low");
+    expect(classifyTool("fetch_user")).toBe("low");
+    expect(classifyTool("read_config")).toBe("low");
+    expect(classifyTool("query_database")).toBe("low");
+    expect(classifyTool("check_status")).toBe("low");
+    expect(classifyTool("view_dashboard")).toBe("low");
+  });
+
+  it("classifies write/send/delete tools as high risk", () => {
+    expect(classifyTool("send_email")).toBe("high");
+    expect(classifyTool("delete_user")).toBe("high");
+    expect(classifyTool("write_file")).toBe("high");
+    expect(classifyTool("deploy_service")).toBe("high");
+    expect(classifyTool("merge_branch")).toBe("high");
+    expect(classifyTool("grant_permission")).toBe("high");
+    expect(classifyTool("execute_command")).toBe("high");
+    expect(classifyTool("transfer_funds")).toBe("high");
+  });
+
+  it("defaults unknown tools to high risk", () => {
+    expect(classifyTool("some_unknown_tool")).toBe("high");
+    expect(classifyTool("foobar")).toBe("high");
+  });
+
+  it("respects user overrides", () => {
+    expect(classifyTool("send_email", { send_email: "low" })).toBe("low");
+    expect(classifyTool("get_weather", { get_weather: "high" })).toBe("high");
+  });
+});

package/src/risk-tiers.ts

@@ -0,0 +1,49 @@
+import type { RiskTier, RiskTierMap } from "./types.js";
+
+// ── Default Risk Classification ──────────────────────────────────────
+// Tools are classified by name prefix/pattern. Write/send/delete/mutate
+// operations get full LLM deliberation. Read-only operations fast-path
+// through regex only.
+//
+// Users override via config.riskTiers: { "my_tool": "low" }
+
+const HIGH_RISK_PATTERNS = [
+  /^(send|email|mail)/i,
+  /^(delete|remove|drop|destroy)/i,
+  /^(write|update|patch|put|post|create|insert)/i,
+  /^(deploy|release|publish|push)/i,
+  /^(merge|commit|approve)/i,
+  /^(grant|revoke|escalate|permission)/i,
+  /^(execute|run|eval|exec)/i,
+  /^(transfer|pay|charge|refund)/i,
+];
+
+const LOW_RISK_PATTERNS = [
+  /^(get|fetch|read|list|search|query|find|lookup)/i,
+  /^(check|verify|validate|inspect|describe)/i,
+  /^(count|sum|aggregate|stats)/i,
+  /^(view|show|display|render|preview)/i,
+];
+
+/**
+ * Classify a tool name into a risk tier.
+ *
+ * Priority: user overrides > low-risk patterns > high-risk patterns > default high.
+ * Unknown tools default to high-risk (safe by default).
+ */
+export function classifyTool(toolName: string, overrides?: RiskTierMap): RiskTier {
+  if (overrides?.[toolName]) {
+    return overrides[toolName];
+  }
+
+  for (const pattern of LOW_RISK_PATTERNS) {
+    if (pattern.test(toolName)) return "low";
+  }
+
+  for (const pattern of HIGH_RISK_PATTERNS) {
+    if (pattern.test(toolName)) return "high";
+  }
+
+  // Unknown tools default to high-risk (safe by default)
+  return "high";
+}

package/src/types.ts

@@ -0,0 +1,127 @@
+import type { IStorage } from "@consensus-tools/storage";
+import type { DecisionResult } from "@consensus-tools/wrapper";
+import type { PersonaConfig } from "@consensus-tools/personas";
+
+// ── Wrappable ────────────────────────────────────────────────────────
+// Any tool executor that consensus can wrap.
+// Resolution order: execute > invoke > call (first match wins).
+
+export type ToolExecutor = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+
+export type Wrappable =
+  | ToolExecutor
+  | { execute: ToolExecutor }
+  | { invoke: ToolExecutor }
+  | { call: ToolExecutor };
+
+// ── Fail Policy ──────────────────────────────────────────────────────
+
+export type FailPolicy = "closed" | "open";
+
+// ── Execution Mode ───────────────────────────────────────────────────
+
+export type ExecutionMode = "enforce" | "shadow";
+
+// ── Model Adapter ────────────────────────────────────────────────────
+// Provider-agnostic LLM interface. Accepts structured messages,
+// returns raw text. Users wrap their SDK call:
+//
+//   model: (msgs) => openai.chat({ messages: msgs }).then(r => r.choices[0].message.content)
+//   model: (msgs) => anthropic.messages.create({ messages: msgs }).then(r => r.content[0].text)
+
+export interface ModelMessage {
+  role: "system" | "user";
+  content: string;
+}
+
+export type ModelAdapter = (messages: ModelMessage[]) => Promise<string>;
+
+// ── Risk Tiers ───────────────────────────────────────────────────────
+
+export type RiskTier = "low" | "high";
+
+export type RiskTierMap = Record<string, RiskTier>;
+
+// ── Feedback ─────────────────────────────────────────────────────────
+// Human feedback signal for reputation ground truth.
+
+export interface FeedbackSignal {
+  /** The decision ID this feedback relates to. */
+  decisionId: string;
+  /** "override_block" = human unblocked a blocked call. "flag_miss" = human flagged a missed risk. */
+  type: "override_block" | "flag_miss";
+}
+
+// ── Logger ───────────────────────────────────────────────────────────
+
+export interface LogEvent {
+  event: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+// ── LLM Decision Result ─────────────────────────────────────────────
+// Result from the LLM persona deliberation path.
+
+export interface LlmDecisionResult {
+  /** Unique decision ID for feedback reference. */
+  decisionId: string;
+  /** Final action: allow, block, or escalate. */
+  action: "allow" | "block" | "escalate";
+  /** Per-persona vote breakdown. */
+  votes: Array<{
+    personaId: string;
+    personaName: string;
+    vote: "YES" | "NO" | "REWRITE";
+    confidence: number;
+    rationale: string;
+    source: "llm" | "regex_fallback";
+  }>;
+  /** Policy used for resolution. */
+  policy: string;
+  /** Consensus trace from resolveConsensus. */
+  consensusTrace: Record<string, unknown>;
+  /** Aggregate score (0-1). */
+  aggregateScore: number;
+}
+
+// ── Config ───────────────────────────────────────────────────────────
+
+export interface UniversalConfig {
+  /** Consensus policy name. For regex mode: 'majority', 'supermajority', 'unanimous', 'threshold:X'.
+   *  For LLM mode: also supports all 9 core policies (WEIGHTED_REPUTATION, MAJORITY_VOTE, etc.). */
+  policy?: string;
+  /** Guard domain names to use as reviewers (regex mode). */
+  guards?: string[];
+  /** Behavior on error: 'closed' blocks, 'open' allows. Default: 'closed'. */
+  failPolicy?: FailPolicy;
+  /** Storage backend: 'memory' for in-memory, or an IStorage instance. Default: 'memory'. */
+  storage?: "memory" | IStorage;
+  /** Logging: true for console.debug, false to disable, or a custom function. Default: true. */
+  logger?: boolean | ((event: LogEvent) => void);
+  /** Called after every consensus decision (both regex and LLM modes). */
+  onDecision?: (decision: DecisionResult<unknown> | LlmDecisionResult) => void | Promise<void>;
+  /** Called when an error occurs during deliberation. */
+  onError?: (err: Error, action: unknown) => void;
+
+  // ── LLM Persona Mode (activated when `model` is provided) ─────────
+
+  /** LLM model adapter. When provided, enables LLM persona mode. */
+  model?: ModelAdapter;
+  /** Persona pack name. Default: 'default' (security, compliance, operations). */
+  pack?: string;
+  /** Custom personas (overrides pack). */
+  personas?: PersonaConfig[];
+  /** Execution mode: 'enforce' blocks on consensus rejection, 'shadow' logs but never blocks. Default: 'enforce'. */
+  mode?: ExecutionMode;
+  /** Tool risk tier overrides. Keys are tool names, values are 'low' or 'high'. */
+  riskTiers?: RiskTierMap;
+  /** Human feedback callback for reputation ground truth. */
+  onFeedback?: (signal: FeedbackSignal) => void;
+  /** Storage for persisting reputation across restarts. Default: in-memory (lost on restart). */
+  reputationStore?: IStorage;
+  /** Reputation threshold below which persona respawn triggers. Default: 0.15. */
+  respawnThreshold?: number;
+  /** Per-persona LLM call timeout in milliseconds. Default: 3000. */
+  personaTimeout?: number;
+}