@consensus-tools/universal 0.9.0

package/src/__tests__/defaults.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import {
+  DEFAULTS,
+  DEFAULT_GUARD,
+  DEFAULT_POLICY,
+  DEFAULT_PERSONA_COUNT,
+  DEFAULT_PERSONA_TRIO,
+  policyToStrategy,
+} from "../defaults.js";
+import { ConfigError } from "../errors.js";
+
+describe("DEFAULTS", () => {
+  it("provides full defaults matching expected values", () => {
+    expect(DEFAULTS.policy).toBe("majority");
+    expect(DEFAULTS.guards).toEqual(["agent_action"]);
+    expect(DEFAULTS.failPolicy).toBe("closed");
+    expect(DEFAULTS.storage).toBe("memory");
+    expect(DEFAULTS.logger).toBe(true);
+  });
+
+  it("exports expected guard and policy constants", () => {
+    expect(DEFAULT_GUARD).toBe("agent_action");
+    expect(DEFAULT_POLICY).toBe("majority");
+    expect(DEFAULT_PERSONA_COUNT).toBe(3);
+    expect(DEFAULT_PERSONA_TRIO).toEqual(["security", "compliance", "user-impact"]);
+  });
+
+  it("merges partial config with defaults", () => {
+    const partial = { policy: "unanimous", failPolicy: "open" as const };
+    const merged = { ...DEFAULTS, ...partial };
+    expect(merged.policy).toBe("unanimous");
+    expect(merged.failPolicy).toBe("open");
+    // Untouched defaults remain
+    expect(merged.guards).toEqual(["agent_action"]);
+    expect(merged.storage).toBe("memory");
+    expect(merged.logger).toBe(true);
+  });
+});
+
+describe("policyToStrategy", () => {
+  it("maps 'majority' to { strategy: 'majority' }", () => {
+    expect(policyToStrategy("majority")).toEqual({ strategy: "majority" });
+  });
+
+  it("maps 'supermajority' to { strategy: 'threshold', threshold: 0.67 }", () => {
+    expect(policyToStrategy("supermajority")).toEqual({ strategy: "threshold", threshold: 0.67 });
+  });
+
+  it("maps 'unanimous' to { strategy: 'unanimous' }", () => {
+    expect(policyToStrategy("unanimous")).toEqual({ strategy: "unanimous" });
+  });
+
+  it("maps 'threshold:0.8' to { strategy: 'threshold', threshold: 0.8 }", () => {
+    expect(policyToStrategy("threshold:0.8")).toEqual({ strategy: "threshold", threshold: 0.8 });
+  });
+
+  it("throws ConfigError for unknown policy name", () => {
+    expect(() => policyToStrategy("bogus")).toThrow(ConfigError);
+    expect(() => policyToStrategy("bogus")).toThrow('Unknown policy "bogus"');
+  });
+
+  it("throws ConfigError for invalid threshold value", () => {
+    expect(() => policyToStrategy("threshold:abc")).toThrow(ConfigError);
+    expect(() => policyToStrategy("threshold:abc")).toThrow("Invalid threshold value");
+  });
+
+  it("throws ConfigError for threshold out of range", () => {
+    expect(() => policyToStrategy("threshold:1.5")).toThrow(ConfigError);
+    expect(() => policyToStrategy("threshold:-0.1")).toThrow(ConfigError);
+  });
+});

package/src/__tests__/fail-policy.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { DecisionResult } from "@consensus-tools/wrapper";
+import { ConsensusBlockedError } from "../errors.js";
+
+// Mock the wrapper's consensus function and guards' createGuardTemplate
+const mockWrapped = vi.fn<(...args: unknown[]) => Promise<DecisionResult<unknown>>>();
+
+vi.mock("@consensus-tools/wrapper", () => ({
+  consensus: vi.fn(() => mockWrapped),
+}));
+
+vi.mock("@consensus-tools/guards", () => ({
+  createGuardTemplate: vi.fn((_name: string, _config: unknown) => ({
+    asReviewer: () => vi.fn(),
+  })),
+  GUARD_CONFIGS: {
+    security: { description: "Security reviewer", rules: () => [] },
+    compliance: { description: "Compliance reviewer", rules: () => [] },
+    "user-impact": { description: "User-impact reviewer", rules: () => [] },
+  },
+  DEFAULT_PERSONA_TRIO: ["security", "compliance", "user-impact"],
+}));
+
+const { consensus } = await import("../index.js");
+
+describe("failPolicy behavior", () => {
+  let originalNodeEnv: string | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    originalNodeEnv = process.env["NODE_ENV"];
+  });
+
+  afterEach(() => {
+    if (originalNodeEnv === undefined) {
+      delete process.env["NODE_ENV"];
+    } else {
+      process.env["NODE_ENV"] = originalNodeEnv;
+    }
+  });
+
+  it("failPolicy: 'closed' + error -> ConsensusBlockedError thrown", async () => {
+    const fn = vi.fn(async () => "result");
+
+    mockWrapped.mockRejectedValueOnce(new Error("deliberation crashed"));
+
+    const wrapped = consensus.wrap(fn, { failPolicy: "closed" });
+    await expect(wrapped("myTool", {})).rejects.toThrow(ConsensusBlockedError);
+
+    // Second call: verify message
+    mockWrapped.mockRejectedValueOnce(new Error("deliberation crashed again"));
+    const wrapped2 = consensus.wrap(fn, { failPolicy: "closed" });
+    await expect(wrapped2("myTool", {})).rejects.toThrow("Consensus deliberation failed");
+  });
+
+  it("failPolicy: 'open' + error -> fn result returned", async () => {
+    const fn = vi.fn(async (_name: string, _args: Record<string, unknown>) => "fallback-result");
+
+    // First call: mockWrapped rejects (deliberation error)
+    mockWrapped.mockRejectedValueOnce(new Error("deliberation crashed"));
+
+    const wrapped = consensus.wrap(fn, { failPolicy: "open" });
+    const result = await wrapped("myTool", { key: "val" });
+
+    // failPolicy 'open' should call fn directly and return its result
+    expect(result).toBe("fallback-result");
+    expect(fn).toHaveBeenCalledWith("myTool", { key: "val" });
+  });
+
+  it("NODE_ENV=production + failPolicy:'open' -> console.warn emitted", () => {
+    process.env["NODE_ENV"] = "production";
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const fn = vi.fn(async () => "result");
+    consensus.wrap(fn, { failPolicy: "open" });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("failPolicy 'open' in production"),
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("NODE_ENV=production + storage:'memory' -> console.warn emitted", () => {
+    process.env["NODE_ENV"] = "production";
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const fn = vi.fn(async () => "result");
+    // storage defaults to 'memory', so no explicit override needed
+    consensus.wrap(fn, { storage: "memory" });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("storage 'memory' in production"),
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("NODE_ENV=development -> no warnings emitted", () => {
+    process.env["NODE_ENV"] = "development";
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const fn = vi.fn(async () => "result");
+    consensus.wrap(fn, { failPolicy: "open", storage: "memory" });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});

package/src/__tests__/frameworks.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from "vitest";
+import { MissingDependencyError } from "../errors.js";
+
+// Mock the wrapper and guards (needed for module load)
+vi.mock("@consensus-tools/wrapper", () => ({
+  consensus: vi.fn(() => vi.fn()),
+}));
+
+vi.mock("@consensus-tools/guards", () => ({
+  createGuardTemplate: vi.fn((_name: string, _config: unknown) => ({
+    asReviewer: () => vi.fn(),
+  })),
+}));
+
+// Mock the optional adapter packages to simulate them not being installed
+vi.mock("@consensus-tools/langchain", () => {
+  throw new Error("Cannot find module '@consensus-tools/langchain'");
+});
+
+vi.mock("@consensus-tools/ai-sdk", () => {
+  throw new Error("Cannot find module '@consensus-tools/ai-sdk'");
+});
+
+vi.mock("@consensus-tools/mcp", () => {
+  throw new Error("Cannot find module '@consensus-tools/mcp'");
+});
+
+const { consensus } = await import("../index.js");
+
+describe("framework shortcuts", () => {
+  it("consensus.langchain() throws MissingDependencyError when adapter not installed", async () => {
+    await expect(consensus.langchain({} as any)).rejects.toThrow(MissingDependencyError);
+    await expect(consensus.langchain({} as any)).rejects.toThrow("@consensus-tools/langchain");
+  });
+
+  it("consensus.aiSdk() throws MissingDependencyError when adapter not installed", async () => {
+    await expect(consensus.aiSdk(() => {})).rejects.toThrow(MissingDependencyError);
+    await expect(consensus.aiSdk(() => {})).rejects.toThrow("@consensus-tools/ai-sdk");
+  });
+
+  it("consensus.mcp() throws MissingDependencyError when adapter not installed", async () => {
+    await expect(consensus.mcp()).rejects.toThrow(MissingDependencyError);
+    await expect(consensus.mcp()).rejects.toThrow("@consensus-tools/mcp");
+  });
+});
+
+describe("consensus.langchain() with adapter installed", () => {
+  it("returns a handler instance when adapter is available", async () => {
+    // Create a mock handler class
+    class MockGuardHandler {
+      name = "consensus-guard";
+      config: Record<string, unknown>;
+      constructor(config: Record<string, unknown>) {
+        this.config = config;
+      }
+    }
+
+    // Temporarily override the langchain mock to return a working module
+    const mockMod = {
+      ConsensusGuardCallbackHandler: MockGuardHandler,
+    };
+
+    // We need to test with a fresh import; use vi.doMock to override for a scoped import
+    vi.doMock("@consensus-tools/langchain", () => mockMod);
+
+    // Re-import to pick up the new mock
+    const { consensus: freshConsensus } = await import("../index.js");
+
+    const handler = await freshConsensus.langchain(null, { policy: "supermajority", guards: ["security"] });
+
+    expect(handler).toBeInstanceOf(MockGuardHandler);
+    expect((handler as MockGuardHandler).config).toEqual({
+      policy: "supermajority",
+      guards: ["security"],
+      onDecision: undefined,
+    });
+
+    // Restore the original mock (not installed)
+    vi.doMock("@consensus-tools/langchain", () => {
+      throw new Error("Cannot find module '@consensus-tools/langchain'");
+    });
+  });
+
+  it("uses default policy 'majority' when no config provided", async () => {
+    class MockGuardHandler {
+      name = "consensus-guard";
+      config: Record<string, unknown>;
+      constructor(config: Record<string, unknown>) {
+        this.config = config;
+      }
+    }
+
+    vi.doMock("@consensus-tools/langchain", () => ({
+      ConsensusGuardCallbackHandler: MockGuardHandler,
+    }));
+
+    const { consensus: freshConsensus } = await import("../index.js");
+    const handler = await freshConsensus.langchain(null);
+
+    expect((handler as MockGuardHandler).config.policy).toBe("majority");
+
+    vi.doMock("@consensus-tools/langchain", () => {
+      throw new Error("Cannot find module '@consensus-tools/langchain'");
+    });
+  });
+});

package/src/__tests__/logger.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from "vitest";
+import { createLogger } from "../logger.js";
+import type { LogEvent } from "../types.js";
+
+describe("createLogger", () => {
+  it("emits deliberation.start event via beforeSubmit hook", () => {
+    const logFn = vi.fn<(event: LogEvent) => void>();
+    const hooks = createLogger({ logger: logFn });
+
+    hooks.beforeSubmit!(["arg1", "arg2"]);
+
+    expect(logFn).toHaveBeenCalledOnce();
+    const event = logFn.mock.calls[0]![0];
+    expect(event.event).toBe("deliberation.start");
+    expect(event.data).toEqual({ args: ["arg1", "arg2"] });
+    expect(typeof event.timestamp).toBe("number");
+  });
+
+  it("emits deliberation.result event via afterResolve hook", () => {
+    const logFn = vi.fn<(event: LogEvent) => void>();
+    const hooks = createLogger({ logger: logFn });
+
+    const mockResult = {
+      action: "allow" as const,
+      output: "ok",
+      scores: [{ score: 0.9, rationale: "safe" }],
+      aggregateScore: 0.9,
+      attempt: 1,
+    };
+
+    hooks.afterResolve!(mockResult);
+
+    expect(logFn).toHaveBeenCalledOnce();
+    const event = logFn.mock.calls[0]![0];
+    expect(event.event).toBe("deliberation.result");
+    expect(event.data).toEqual({
+      action: "allow",
+      aggregateScore: 0.9,
+      attempt: 1,
+      scoresCount: 1,
+    });
+  });
+
+  it("emits deliberation.error-level event via onBlock hook", () => {
+    const logFn = vi.fn<(event: LogEvent) => void>();
+    const hooks = createLogger({ logger: logFn });
+
+    const mockResult = {
+      action: "block" as const,
+      output: null,
+      scores: [{ score: 0, rationale: "blocked" }],
+      aggregateScore: 0,
+      attempt: 1,
+    };
+
+    hooks.onBlock!(mockResult);
+
+    expect(logFn).toHaveBeenCalledOnce();
+    const event = logFn.mock.calls[0]![0];
+    expect(event.event).toBe("deliberation.result");
+    expect(event.data.action).toBe("block");
+  });
+
+  it("returns empty hooks when logger is false (suppresses all events)", () => {
+    const hooks = createLogger({ logger: false });
+
+    expect(hooks.beforeSubmit).toBeUndefined();
+    expect(hooks.afterResolve).toBeUndefined();
+    expect(hooks.onBlock).toBeUndefined();
+    expect(hooks.onEscalate).toBeUndefined();
+  });
+
+  it("uses custom logger function to receive events", () => {
+    const events: LogEvent[] = [];
+    const customLogger = (event: LogEvent) => {
+      events.push(event);
+    };
+    const hooks = createLogger({ logger: customLogger });
+
+    hooks.beforeSubmit!(["hello"]);
+    hooks.afterResolve!({
+      action: "allow",
+      output: "world",
+      scores: [],
+      aggregateScore: 1.0,
+      attempt: 1,
+    });
+
+    expect(events).toHaveLength(2);
+    expect(events[0]!.event).toBe("deliberation.start");
+    expect(events[1]!.event).toBe("deliberation.result");
+  });
+});

package/src/__tests__/resolve.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest";
+import { resolveWrappable } from "../resolve.js";
+
+describe("resolveWrappable", () => {
+  it("returns the function directly when input is a function", () => {
+    const fn = async (name: string, args: Record<string, unknown>) => ({ name, args });
+    const result = resolveWrappable(fn);
+    expect(result).toBe(fn);
+  });
+
+  it("returns .execute when input has .execute", async () => {
+    const obj = {
+      state: "bound",
+      execute: async function (name: string, args: Record<string, unknown>) {
+        return { name, args, state: this.state };
+      },
+    };
+    const resolved = resolveWrappable(obj as any);
+    const output = await resolved("test", { a: 1 });
+    expect(output).toEqual({ name: "test", args: { a: 1 }, state: "bound" });
+  });
+
+  it("returns .invoke when input has .invoke", async () => {
+    const obj = {
+      state: "invoked",
+      invoke: async function (name: string, args: Record<string, unknown>) {
+        return { name, args, state: this.state };
+      },
+    };
+    const resolved = resolveWrappable(obj as any);
+    const output = await resolved("test", { b: 2 });
+    expect(output).toEqual({ name: "test", args: { b: 2 }, state: "invoked" });
+  });
+
+  it("returns .call when input has .call", async () => {
+    const obj = {
+      state: "called",
+      call: async function (name: string, args: Record<string, unknown>) {
+        return { name, args, state: this.state };
+      },
+    };
+    const resolved = resolveWrappable(obj as any);
+    const output = await resolved("test", { c: 3 });
+    expect(output).toEqual({ name: "test", args: { c: 3 }, state: "called" });
+  });
+
+  it("prefers .execute over .invoke when both exist (resolution order)", async () => {
+    const obj = {
+      execute: async (_name: string, _args: Record<string, unknown>) => "execute-wins",
+      invoke: async (_name: string, _args: Record<string, unknown>) => "invoke-loses",
+    };
+    const resolved = resolveWrappable(obj as any);
+    const output = await resolved("test", {});
+    expect(output).toBe("execute-wins");
+  });
+
+  it("throws TypeError for null", () => {
+    expect(() => resolveWrappable(null as any)).toThrow(TypeError);
+    expect(() => resolveWrappable(null as any)).toThrow("Expected a Wrappable");
+  });
+
+  it("throws TypeError for undefined", () => {
+    expect(() => resolveWrappable(undefined as any)).toThrow(TypeError);
+    expect(() => resolveWrappable(undefined as any)).toThrow("Expected a Wrappable");
+  });
+
+  it("throws TypeError for object with no matching methods", () => {
+    const obj = { foo: () => "bar" };
+    expect(() => resolveWrappable(obj as any)).toThrow(TypeError);
+    expect(() => resolveWrappable(obj as any)).toThrow("Expected a Wrappable");
+  });
+
+  it("throws TypeError for string primitive", () => {
+    expect(() => resolveWrappable("hello" as any)).toThrow(TypeError);
+  });
+
+  it("throws TypeError for number primitive", () => {
+    expect(() => resolveWrappable(42 as any)).toThrow(TypeError);
+  });
+});

package/src/__tests__/wrap.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { DecisionResult } from "@consensus-tools/wrapper";
+import { ConsensusBlockedError } from "../errors.js";
+
+// Mock the wrapper's consensus function and guards' createGuardTemplate
+const mockWrapped = vi.fn<(...args: unknown[]) => Promise<DecisionResult<unknown>>>();
+
+vi.mock("@consensus-tools/wrapper", () => ({
+  consensus: vi.fn(() => mockWrapped),
+}));
+
+vi.mock("@consensus-tools/guards", () => ({
+  createGuardTemplate: vi.fn((_name: string, _config: unknown) => ({
+    asReviewer: () => vi.fn(),
+  })),
+  GUARD_CONFIGS: {
+    security: { description: "Security reviewer", rules: () => [] },
+    compliance: { description: "Compliance reviewer", rules: () => [] },
+    "user-impact": { description: "User-impact reviewer", rules: () => [] },
+  },
+  DEFAULT_PERSONA_TRIO: ["security", "compliance", "user-impact"],
+}));
+
+// Import after mocks are set up
+const { consensus } = await import("../index.js");
+
+describe("consensus.wrap()", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("happy path: wrap function, reviewers run, decision returned", async () => {
+    const fn = vi.fn(async (_name: string, _args: Record<string, unknown>) => "tool-result");
+
+    mockWrapped.mockResolvedValueOnce({
+      action: "allow",
+      output: "tool-result",
+      scores: [{ score: 0.9, rationale: "approved" }],
+      aggregateScore: 0.9,
+      attempt: 1,
+    });
+
+    const wrapped = consensus.wrap(fn);
+    const result = await wrapped("myTool", { input: "data" });
+
+    expect(result).toBe("tool-result");
+    expect(mockWrapped).toHaveBeenCalledWith("myTool", { input: "data" });
+  });
+
+  it("wrapped fn returns undefined -> reviewers evaluate undefined", async () => {
+    const fn = vi.fn(async () => undefined);
+
+    mockWrapped.mockResolvedValueOnce({
+      action: "allow",
+      output: undefined,
+      scores: [{ score: 0.8 }],
+      aggregateScore: 0.8,
+      attempt: 1,
+    });
+
+    const wrapped = consensus.wrap(fn);
+    const result = await wrapped("myTool", {});
+
+    expect(result).toBeUndefined();
+  });
+
+  it("wrapped fn throws synchronously -> failPolicy 'closed' throws ConsensusBlockedError", async () => {
+    const fn = vi.fn(() => {
+      throw new Error("sync explosion");
+    });
+
+    mockWrapped.mockRejectedValueOnce(new Error("sync explosion"));
+
+    const wrapped = consensus.wrap(fn, { failPolicy: "closed" });
+    await expect(wrapped("myTool", {})).rejects.toThrow(ConsensusBlockedError);
+  });
+
+  it("all reviewers return score=0 -> unanimous block with failPolicy closed", async () => {
+    const fn = vi.fn(async () => "result");
+
+    mockWrapped.mockResolvedValueOnce({
+      action: "block",
+      output: null,
+      scores: [
+        { score: 0, rationale: "blocked-1" },
+        { score: 0, rationale: "blocked-2" },
+        { score: 0, rationale: "blocked-3" },
+      ],
+      aggregateScore: 0,
+      attempt: 1,
+    });
+
+    const wrapped = consensus.wrap(fn, { failPolicy: "closed" });
+    await expect(wrapped("dangerousTool", {})).rejects.toThrow(ConsensusBlockedError);
+
+    // Second call to verify message content
+    mockWrapped.mockResolvedValueOnce({
+      action: "block",
+      output: null,
+      scores: [
+        { score: 0, rationale: "blocked-1" },
+        { score: 0, rationale: "blocked-2" },
+        { score: 0, rationale: "blocked-3" },
+      ],
+      aggregateScore: 0,
+      attempt: 1,
+    });
+    await expect(wrapped("dangerousTool", {})).rejects.toThrow(/Consensus block/);
+  });
+});