ovrule-lab 0.2.2 → 0.3.0

package/README.md

@@ -27,16 +27,15 @@ console.log(receipt.summary);
 import { guard } from "ovrule-lab";
 
 const result = await guard({
-  scenario: "Finance agent wants to wire $18,000 to a new vendor after bank details changed.",
-  policyPack: "finance",
+  scenario: "An AI coding agent wants to run DROP TABLE users on the production database.",
 });
 
 if (!result.allowed) {
-  console.error(result.decision, result.suggestedFixes);
-  throw new Error("Tool call blocked by Ovrule.");
+  console.error(result.decision, result.reason); // "REFUSED" — irreversible, production-wide
+  throw new Error("Action blocked by Ovrule.");
 }
 
-await issueWireTransfer();
+await runCommand();
 ```
 
 ## 3. LangChain middleware integration
@@ -55,8 +54,8 @@ export async function beforeToolInvoke(input: string) {
   if (!guard.allowed) {
     return {
       blocked: true,
-      receipt: guard.receipt,
-      fixes: guard.suggestedFixes,
+      decision: guard.decision,
+      reason: guard.reason,
     };
   }
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type Decision = "ADMISSIBLE" | "AMBIGUOUS" | "REFUSED";
 export type Verdict = "PASS" | "WARN" | "FAIL";
-export type PolicyPackId = "general" | "customer_support" | "healthcare" | "finance";
+export type PolicyPackId = "general" | "customer_support" | "healthcare" | "finance" | "payments" | "code";
 export type RuleName = "SAFETY" | "AUTHORIZATION" | "CAUSAL VALIDITY" | "REVERSIBILITY" | "IMPACT SCOPE" | "CONSENT";
 export type RuleTraceItem = {
     rule: RuleName;
@@ -77,8 +77,10 @@ export type ProposedAction = {
 export type GuardResult = {
     allowed: boolean;
     decision: Decision;
-    suggestedFixes: FixSuggestion[];
-    receipt: CaseFileReceipt;
+    reason: string;
+    ruleTrace: RuleTraceItem[];
+    receiptId: string;
+    signature?: string;
 };
 export type OvruleClientOptions = {
     baseUrl?: string;
@@ -103,4 +105,18 @@ export declare function guard(action: string | ProposedAction, options?: Request
 export declare function verify(receipt: CaseFileReceipt, signature: string, options?: {
     signal?: AbortSignal;
 } & OvruleClientOptions): Promise<boolean>;
+/** Thrown by a guarded tool when Ovrule refuses the action. `.result` holds the decision. */
+export declare class GuardBlockedError extends Error {
+    readonly result: GuardResult;
+    constructor(result: GuardResult);
+}
+/**
+ * Wrap any agent tool so it is audited by Ovrule BEFORE it runs. Works with any
+ * framework (LangChain, OpenAI Agents, MCP) because tools are just functions.
+ * A refused action throws GuardBlockedError and the tool never executes.
+ *
+ *   const safeExec = guardTool(runCommand, (cmd) => `An AI agent wants to run: ${cmd}`, { policyPack: "code" });
+ *   await safeExec("DROP TABLE users;"); // throws — never runs
+ */
+export declare function guardTool<A extends unknown[], R>(tool: (...args: A) => Promise<R>, describe: (...args: A) => string, options?: RequestOptions & OvruleClientOptions): (...args: A) => Promise<R>;
 export {};

package/dist/index.js

@@ -129,14 +129,26 @@ export class OvruleClient {
         return finalReceipt;
     }
     async guard(action, options = {}) {
-        const receipt = await this.classify(action, options);
-        const allowed = receipt.decision === "ADMISSIBLE";
-        const suggestedFixes = receipt.suggestedFixes ?? [];
+        const payload = normalizeAction(action, options);
+        const response = await this.fetchImpl(`${this.baseUrl}/api/guard`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ action: payload.scenario, policyPack: payload.policyPack }),
+            signal: options.signal,
+        });
+        // A blocked (REFUSED) action returns HTTP 403 with a full decision body, so we
+        // read the body regardless of status and only fail on a missing decision.
+        const data = (await response.json().catch(() => null));
+        if (!data || data.decision === undefined) {
+            throw new Error((data && data.error) || `Ovrule guard failed with status ${response.status}.`);
+        }
         return {
-            allowed,
-            decision: receipt.decision,
-            suggestedFixes,
-            receipt,
+            allowed: Boolean(data.allowed),
+            decision: data.decision,
+            reason: data.reason ?? "",
+            ruleTrace: data.ruleTrace ?? [],
+            receiptId: data.receiptId ?? "",
+            signature: data.signature,
         };
     }
     async verify(receipt, signature, options = {}) {
@@ -171,3 +183,29 @@ export async function verify(receipt, signature, options) {
     }
     return defaultClient.verify(receipt, signature, options);
 }
+/** Thrown by a guarded tool when Ovrule refuses the action. `.result` holds the decision. */
+export class GuardBlockedError extends Error {
+    result;
+    constructor(result) {
+        super(`Ovrule blocked action (${result.decision}): ${result.reason}`);
+        this.result = result;
+        this.name = "GuardBlockedError";
+    }
+}
+/**
+ * Wrap any agent tool so it is audited by Ovrule BEFORE it runs. Works with any
+ * framework (LangChain, OpenAI Agents, MCP) because tools are just functions.
+ * A refused action throws GuardBlockedError and the tool never executes.
+ *
+ *   const safeExec = guardTool(runCommand, (cmd) => `An AI agent wants to run: ${cmd}`, { policyPack: "code" });
+ *   await safeExec("DROP TABLE users;"); // throws — never runs
+ */
+export function guardTool(tool, describe, options) {
+    return async (...args) => {
+        const result = await guard(describe(...args), options);
+        if (!result.allowed) {
+            throw new GuardBlockedError(result);
+        }
+        return tool(...args);
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ovrule-lab",
-  "version": "0.2.2",
-  "description": "TypeScript SDK for Ovrule case-file classification, guardrails, and receipt verification.",
+  "version": "0.3.0",
+  "description": "TypeScript SDK for Ovrule — accountability guardrails for AI agents: classify an action, guard a tool call (incl. the accounts-payable / payment-fraud pack), and verify signed receipts.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -19,7 +19,7 @@
     "bin/welcome.js"
   ],
   "bin": {
-    "ovrule-lab": "bin/ovrule-lab"
+    "ovrule-lab": "./bin/ovrule-lab"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -38,6 +38,5 @@
   "sideEffects": false,
   "devDependencies": {
     "typescript": "^5.8.3"
-  },
-  "author": ""
+  }
 }