macro-agent 0.1.12 → 0.2.0

package/src/dispatch/__tests__/permission-evaluator.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Unit tests for `evaluatePermission` — the per-tool-call decision
+ * function used by the PreToolUse hook to enforce dispatch-supplied
+ * loadout permissions.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  evaluatePermission,
+  matchRule,
+} from "../permission-evaluator.js";
+import type { OverlayPermissions } from "../permission-overlay.js";
+
+// ────────────────────────────────────────────────────────────────────
+// matchRule — single-rule pattern matching
+// ────────────────────────────────────────────────────────────────────
+
+describe("matchRule", () => {
+  it("matches a bare rule (no parens) against any tool input", () => {
+    expect(matchRule("Bash", "Bash", { command: "anything" }).matched).toBe(true);
+    expect(matchRule("Bash", "Bash", { command: "" }).matched).toBe(true);
+    expect(matchRule("Read", "Bash", { command: "x" }).matched).toBe(false);
+  });
+
+  it("matches a rule with empty parens (Bash()) — same as bare", () => {
+    expect(matchRule("Bash()", "Bash", { command: "echo hi" }).matched).toBe(true);
+  });
+
+  it("matches a literal pattern against the primary input field", () => {
+    expect(
+      matchRule("Bash(rm -rf /tmp/foo)", "Bash", { command: "rm -rf /tmp/foo" }).matched,
+    ).toBe(true);
+    expect(
+      matchRule("Bash(rm -rf /tmp/foo)", "Bash", { command: "rm -rf /tmp/bar" }).matched,
+    ).toBe(false);
+  });
+
+  it("treats `*` as glob (any sequence)", () => {
+    expect(
+      matchRule("Bash(echo perm-deny-test:*)", "Bash", {
+        command: "echo perm-deny-test:hello-world",
+      }).matched,
+    ).toBe(true);
+    expect(
+      matchRule("Bash(echo perm-deny-test:*)", "Bash", {
+        command: "echo perm-allow-test:other",
+      }).matched,
+    ).toBe(false);
+  });
+
+  it("treats multiple `*` as multiple globs", () => {
+    expect(
+      matchRule("Bash(*node *.js)", "Bash", { command: "/usr/bin/node script.js" }).matched,
+    ).toBe(true);
+    expect(
+      matchRule("Bash(*node *.js)", "Bash", { command: "/usr/bin/python script.py" }).matched,
+    ).toBe(false);
+  });
+
+  it("escapes regex specials in the pattern", () => {
+    // `.` is a regex special; should match literally, not as "any char".
+    expect(
+      matchRule("Write(.env)", "Write", { file_path: ".env" }).matched,
+    ).toBe(true);
+    // Without escaping, `.` would match `aenv` too — but this MUST not match:
+    expect(
+      matchRule("Write(.env)", "Write", { file_path: "aenv" }).matched,
+    ).toBe(false);
+  });
+
+  it("matches `**` like single `*` (no path-segment distinction)", () => {
+    expect(
+      matchRule("Read(**)", "Read", { file_path: "/etc/passwd" }).matched,
+    ).toBe(true);
+  });
+
+  it("returns no match when the tool name doesn't match the rule's tool", () => {
+    expect(matchRule("Bash(*)", "Read", { file_path: "/x" }).matched).toBe(false);
+  });
+
+  it("uses the right primary field per tool", () => {
+    expect(matchRule("Read(/etc/*)", "Read", { file_path: "/etc/passwd" }).field).toBe("file_path");
+    expect(matchRule("Bash(*)", "Bash", { command: "x" }).field).toBe("command");
+    expect(matchRule("Grep(TODO)", "Grep", { pattern: "TODO" }).field).toBe("pattern");
+  });
+
+  it("returns no match for tools without a defined primary field when a pattern is given", () => {
+    // FakeTool has no PRIMARY_INPUT_FIELD entry; pattern-bearing rules
+    // can't match. Bare `FakeTool` rules WOULD still match (covered by
+    // the first test).
+    expect(matchRule("FakeTool(*)", "FakeTool", { x: "y" }).matched).toBe(false);
+  });
+
+  it("returns no match when the input doesn't have the expected field", () => {
+    expect(matchRule("Bash(*)", "Bash", {}).matched).toBe(false);
+    expect(matchRule("Bash(*)", "Bash", { command: 42 }).matched).toBe(false);
+  });
+
+  it("returns no match for malformed rules", () => {
+    expect(matchRule("", "Bash", { command: "x" }).matched).toBe(false);
+    expect(matchRule("(", "Bash", { command: "x" }).matched).toBe(false);
+    expect(matchRule("Bash(unclosed", "Bash", { command: "x" }).matched).toBe(false);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// evaluatePermission — overlay-level decision precedence
+// ────────────────────────────────────────────────────────────────────
+
+describe("evaluatePermission", () => {
+  it("returns 'pass-through' when overlay has no rules", () => {
+    expect(
+      evaluatePermission("Bash", { command: "echo" }, {}).decision,
+    ).toBe("pass-through");
+  });
+
+  it("returns 'pass-through' when no rule matches the call", () => {
+    const overlay: OverlayPermissions = {
+      deny: ["Bash(rm -rf:*)"],
+      allow: ["Read(**)"],
+    };
+    expect(
+      evaluatePermission("Write", { file_path: "/tmp/x" }, overlay).decision,
+    ).toBe("pass-through");
+  });
+
+  it("returns 'deny' when a deny rule matches", () => {
+    const overlay: OverlayPermissions = {
+      deny: ["Bash(echo perm-deny-test:*)"],
+    };
+    const result = evaluatePermission(
+      "Bash",
+      { command: "echo perm-deny-test:hello" },
+      overlay,
+    );
+    expect(result.decision).toBe("deny");
+    expect(result.matchedRule).toBe("Bash(echo perm-deny-test:*)");
+    expect(result.matchedField).toBe("command");
+  });
+
+  it("returns 'allow' when an allow rule matches and no deny matches", () => {
+    const overlay: OverlayPermissions = {
+      allow: ["Read(/safe/**)"],
+      deny: ["Bash(*)"],
+    };
+    const result = evaluatePermission(
+      "Read",
+      { file_path: "/safe/foo.txt" },
+      overlay,
+    );
+    expect(result.decision).toBe("allow");
+    expect(result.matchedRule).toBe("Read(/safe/**)");
+  });
+
+  it("deny takes precedence over allow when both match", () => {
+    const overlay: OverlayPermissions = {
+      // Pattern uses `*` glob to cover the suffix; the colon convention
+      // (`Bash(rm -rf:*)`) is also legal but the test exercises the
+      // simpler suffix-glob form against a real space-separated command.
+      deny: ["Bash(rm -rf*)"],
+      allow: ["Bash(*)"],
+    };
+    expect(
+      evaluatePermission("Bash", { command: "rm -rf /tmp" }, overlay).decision,
+    ).toBe("deny");
+  });
+
+  it("first matching deny rule wins (matchedRule reports it)", () => {
+    const overlay: OverlayPermissions = {
+      deny: ["Bash(echo *)", "Bash(*)"],
+    };
+    const result = evaluatePermission(
+      "Bash",
+      { command: "echo hi" },
+      overlay,
+    );
+    expect(result.decision).toBe("deny");
+    expect(result.matchedRule).toBe("Bash(echo *)");
+  });
+
+  it("matches against the live test's exact rule shape (regression target)", () => {
+    // This is the exact rule the live-mail-reuse-dispatch.test.ts ships
+    // on the wire; the evaluator MUST match it for the live test's
+    // PERM_DENIED assertion to pass.
+    const overlay: OverlayPermissions = {
+      deny: ["Bash(echo perm-deny-test:*)"],
+    };
+    expect(
+      evaluatePermission(
+        "Bash",
+        { command: "echo perm-deny-test:hello-world" },
+        overlay,
+      ).decision,
+    ).toBe("deny");
+  });
+});

package/src/dispatch/__tests__/permission-overlay.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for the per-process permission-overlay registry.
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  setPermissionOverlay,
+  clearPermissionOverlay,
+  getPermissionOverlay,
+  clearAllPermissionOverlays,
+  _resetForTest,
+  _sizeForTest,
+} from "../permission-overlay.js";
+
+describe("permission-overlay registry", () => {
+  beforeEach(() => {
+    _resetForTest();
+  });
+
+  it("returns undefined when no overlay is set", () => {
+    expect(getPermissionOverlay("agent-A")).toBeUndefined();
+  });
+
+  it("set / get round-trip", () => {
+    setPermissionOverlay("agent-A", { deny: ["Bash(rm:*)"] });
+    expect(getPermissionOverlay("agent-A")).toEqual({ deny: ["Bash(rm:*)"] });
+  });
+
+  it("clear removes only the targeted agent's overlay", () => {
+    setPermissionOverlay("agent-A", { deny: ["Bash(*)"] });
+    setPermissionOverlay("agent-B", { deny: ["Read(*)"] });
+    clearPermissionOverlay("agent-A");
+    expect(getPermissionOverlay("agent-A")).toBeUndefined();
+    expect(getPermissionOverlay("agent-B")).toEqual({ deny: ["Read(*)"] });
+  });
+
+  it("clear is idempotent (no error when no overlay)", () => {
+    expect(() => clearPermissionOverlay("ghost")).not.toThrow();
+  });
+
+  it("set overwrites prior overlay for the same agent", () => {
+    setPermissionOverlay("agent-A", { deny: ["Bash(*)"] });
+    setPermissionOverlay("agent-A", { allow: ["Read(*)"] });
+    expect(getPermissionOverlay("agent-A")).toEqual({ allow: ["Read(*)"] });
+  });
+
+  it("clearAllPermissionOverlays drops everything", () => {
+    setPermissionOverlay("a", { deny: ["x"] });
+    setPermissionOverlay("b", { deny: ["y"] });
+    setPermissionOverlay("c", { deny: ["z"] });
+    expect(_sizeForTest()).toBe(3);
+    clearAllPermissionOverlays();
+    expect(_sizeForTest()).toBe(0);
+    expect(getPermissionOverlay("a")).toBeUndefined();
+  });
+});

package/src/dispatch/__tests__/permissions-handler.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for the `x-dispatch/permissions.{set,clear}` MAP request
+ * handlers. These verify the wire-shape contract — the OpenHive ACP+reuse
+ * dispatch path calls these to inject loadout deny rules into a long-lived
+ * agent's permission overlay before driving the prompt, and to clear them
+ * after the dispatch completes.
+ *
+ * The actual enforcement is exercised end-to-end in the live test
+ * (live-acp-reuse-dispatch.test.ts); here we just pin the handler's
+ * input/output contract and the side effects on the overlay registry.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  handlePermissionsSet,
+  handlePermissionsClear,
+  X_DISPATCH_PERMISSIONS_METHODS,
+} from "../permissions-handler.js";
+import {
+  getPermissionOverlay,
+  clearPermissionOverlay,
+} from "../permission-overlay.js";
+
+describe("x-dispatch/permissions handlers", () => {
+  const TEST_AGENT_ID = "agent_test_perm_handler_xyz";
+
+  beforeEach(() => {
+    clearPermissionOverlay(TEST_AGENT_ID);
+  });
+
+  afterEach(() => {
+    clearPermissionOverlay(TEST_AGENT_ID);
+  });
+
+  describe("set", () => {
+    it("accepts deny + allow, writes overlay, returns ok=true", () => {
+      const result = handlePermissionsSet(
+        {
+          agent_id: TEST_AGENT_ID,
+          deny: ["Read(/etc/secrets)"],
+          allow: ["Read(/tmp/*)"],
+        },
+        () => {},
+      );
+      expect(result).toEqual({ ok: true });
+      const overlay = getPermissionOverlay(TEST_AGENT_ID);
+      expect(overlay).toEqual({
+        deny: ["Read(/etc/secrets)"],
+        allow: ["Read(/tmp/*)"],
+      });
+    });
+
+    it("accepts deny only", () => {
+      const result = handlePermissionsSet(
+        { agent_id: TEST_AGENT_ID, deny: ["Bash(rm -rf:*)"] },
+        () => {},
+      );
+      expect(result).toEqual({ ok: true });
+      expect(getPermissionOverlay(TEST_AGENT_ID)).toEqual({
+        deny: ["Bash(rm -rf:*)"],
+      });
+    });
+
+    it("accepts allow only", () => {
+      const result = handlePermissionsSet(
+        { agent_id: TEST_AGENT_ID, allow: ["Read(*)"] },
+        () => {},
+      );
+      expect(result).toEqual({ ok: true });
+      expect(getPermissionOverlay(TEST_AGENT_ID)).toEqual({
+        allow: ["Read(*)"],
+      });
+    });
+
+    it("re-setting overwrites the prior overlay (idempotent)", () => {
+      handlePermissionsSet(
+        { agent_id: TEST_AGENT_ID, deny: ["Read(/old)"] },
+        () => {},
+      );
+      handlePermissionsSet(
+        { agent_id: TEST_AGENT_ID, deny: ["Read(/new)"] },
+        () => {},
+      );
+      expect(getPermissionOverlay(TEST_AGENT_ID)).toEqual({
+        deny: ["Read(/new)"],
+      });
+    });
+
+    it("rejects missing agent_id", () => {
+      // @ts-expect-error - testing runtime validation
+      const result = handlePermissionsSet({ deny: [] }, () => {});
+      expect(result.ok).toBe(false);
+      expect((result as { error: string }).error).toMatch(/agent_id/);
+    });
+
+    it("rejects non-string agent_id", () => {
+      const result = handlePermissionsSet(
+        // @ts-expect-error - testing runtime validation
+        { agent_id: 42, deny: [] },
+        () => {},
+      );
+      expect(result.ok).toBe(false);
+    });
+
+    it("rejects non-array deny", () => {
+      const result = handlePermissionsSet(
+        // @ts-expect-error - testing runtime validation
+        { agent_id: TEST_AGENT_ID, deny: "Read(*)" },
+        () => {},
+      );
+      expect(result.ok).toBe(false);
+      expect((result as { error: string }).error).toMatch(/deny/);
+    });
+
+    it("rejects non-array allow", () => {
+      const result = handlePermissionsSet(
+        // @ts-expect-error - testing runtime validation
+        { agent_id: TEST_AGENT_ID, allow: { 0: "x" } },
+        () => {},
+      );
+      expect(result.ok).toBe(false);
+      expect((result as { error: string }).error).toMatch(/allow/);
+    });
+  });
+
+  describe("clear", () => {
+    it("removes a previously-set overlay", () => {
+      handlePermissionsSet(
+        { agent_id: TEST_AGENT_ID, deny: ["Read(/secret)"] },
+        () => {},
+      );
+      expect(getPermissionOverlay(TEST_AGENT_ID)).toBeTruthy();
+
+      const result = handlePermissionsClear(
+        { agent_id: TEST_AGENT_ID },
+        () => {},
+      );
+      expect(result).toEqual({ ok: true });
+      expect(getPermissionOverlay(TEST_AGENT_ID)).toBeUndefined();
+    });
+
+    it("idempotent — clearing a non-existent overlay returns ok=true", () => {
+      const result = handlePermissionsClear(
+        { agent_id: TEST_AGENT_ID },
+        () => {},
+      );
+      expect(result).toEqual({ ok: true });
+    });
+
+    it("rejects missing agent_id", () => {
+      // @ts-expect-error - testing runtime validation
+      const result = handlePermissionsClear({}, () => {});
+      expect(result.ok).toBe(false);
+      expect((result as { error: string }).error).toMatch(/agent_id/);
+    });
+  });
+
+  describe("method names — pinning the wire contract", () => {
+    it("matches the namespaced x-dispatch/permissions.* convention", () => {
+      expect(X_DISPATCH_PERMISSIONS_METHODS).toEqual({
+        SET_REQUEST: "x-dispatch/permissions.set.request",
+        SET_RESPONSE: "x-dispatch/permissions.set.response",
+        CLEAR_REQUEST: "x-dispatch/permissions.clear.request",
+        CLEAR_RESPONSE: "x-dispatch/permissions.clear.response",
+      });
+    });
+  });
+});