ovrule-lab 0.2.1 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ TypeScript client for Ovrule case-file classification, guardrails, and receipt v
 npm install ovrule-lab
 ```
 
-On the first successful `classify()` or `guard()` call in a process, the SDK prints a one-line ready message plus a permalink to the created case. Later successful audits print only the case permalink. Set `OVRULE_QUIET=1` to suppress those logs.
+On the first successful `classify()` or `guard()` call in a process, the SDK prints the full Ovrule ASCII banner plus a permalink to the created case. Later successful audits print only the case permalink. Set `OVRULE_QUIET=1` to suppress all SDK logs. You can also run `npx ovrule-lab` at any time to print the banner manually.
 
 ## 1. Simple classify
 
@@ -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/bin/ovrule-lab

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./welcome.js";

package/bin/welcome.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { logBanner } from "../dist/banner.js";
+
+logBanner();

package/dist/banner.d.ts

@@ -0,0 +1,5 @@
+export declare const SDK_VERSION = "0.2.2";
+export declare function isQuietModeEnabled(): boolean;
+export declare function renderBanner(): string;
+export declare function logBanner(): void;
+export declare function getDefaultBaseUrl(): string;

package/dist/banner.js

@@ -0,0 +1,47 @@
+const DEFAULT_OVRULE_BASE_URL = "https://decision-receipt-lab.vercel.app";
+export const SDK_VERSION = "0.2.2";
+export function isQuietModeEnabled() {
+    return (typeof process !== "undefined" &&
+        typeof process.env === "object" &&
+        typeof process.env.OVRULE_QUIET !== "undefined" &&
+        process.env.OVRULE_QUIET !== "");
+}
+export function renderBanner() {
+    const reset = "\x1b[0m";
+    const dim = "\x1b[2m";
+    const bold = "\x1b[1m";
+    const cyan = "\x1b[36m";
+    const magenta = "\x1b[35m";
+    const yellow = "\x1b[33m";
+    return [
+        "",
+        `${bold}${cyan}   ╔═══════════════════════════════════════════════╗${reset}`,
+        `${bold}${cyan}   ║${reset}   ${bold}O${reset}${magenta}━━${reset}${bold}V${reset}   ${bold}Ovrule${reset} · SDK v${SDK_VERSION}                  ${bold}${cyan}║${reset}`,
+        `${bold}${cyan}   ║${reset}         ${dim}Auditable receipts for AI agents${reset}      ${bold}${cyan}║${reset}`,
+        `${bold}${cyan}   ╚═══════════════════════════════════════════════╝${reset}`,
+        "",
+        `   ${bold}Quickstart${reset}`,
+        `   ${dim}import { classify } from "ovrule-lab";${reset}`,
+        `   ${dim}const receipt = await classify("your agent action", {${reset}`,
+        `   ${dim}  baseUrl: "${DEFAULT_OVRULE_BASE_URL}"${reset}`,
+        `   ${dim}});${reset}`,
+        "",
+        `   ${bold}Methods${reset}`,
+        `   ${dim}classify(action, opts)${reset}   — full case file audit`,
+        `   ${dim}guard(action, opts)${reset}      — returns { allowed, decision, ... }`,
+        `   ${dim}verify(receipt, sig, opts)${reset} — verify a signed receipt`,
+        "",
+        `   ${bold}Docs${reset}     ${yellow}${DEFAULT_OVRULE_BASE_URL}/docs${reset}`,
+        `   ${bold}GitHub${reset}   ${yellow}https://github.com/elakumuk/decision-receipt-lab${reset}`,
+        "",
+    ].join("\n");
+}
+export function logBanner() {
+    if (isQuietModeEnabled()) {
+        return;
+    }
+    console.info(renderBanner());
+}
+export function getDefaultBaseUrl() {
+    return DEFAULT_OVRULE_BASE_URL;
+}

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

@@ -1,12 +1,5 @@
-const DEFAULT_OVRULE_BASE_URL = "https://decision-receipt-lab.vercel.app";
-const SDK_VERSION = "0.2.1";
+import { getDefaultBaseUrl, isQuietModeEnabled, logBanner } from "./banner.js";
 let hasShownReadyMessage = false;
-function isQuietModeEnabled() {
-    return (typeof process !== "undefined" &&
-        typeof process.env === "object" &&
-        typeof process.env.OVRULE_QUIET !== "undefined" &&
-        process.env.OVRULE_QUIET !== "");
-}
 function getConsoleBaseUrl(baseUrl) {
     if (baseUrl) {
         return baseUrl;
@@ -14,7 +7,7 @@ function getConsoleBaseUrl(baseUrl) {
     if (typeof window !== "undefined" && window.location?.origin) {
         return window.location.origin;
     }
-    return DEFAULT_OVRULE_BASE_URL;
+    return getDefaultBaseUrl();
 }
 function logSuccessfulAudit(receipt, baseUrl) {
     if (isQuietModeEnabled()) {
@@ -22,7 +15,7 @@ function logSuccessfulAudit(receipt, baseUrl) {
     }
     const caseUrl = `${getConsoleBaseUrl(baseUrl)}/case/${receipt.receiptId}`;
     if (!hasShownReadyMessage) {
-        console.info(`[ovrule-lab v${SDK_VERSION}] ready · docs: ${DEFAULT_OVRULE_BASE_URL}/docs`);
+        logBanner();
         hasShownReadyMessage = true;
     }
     console.info(`[ovrule-lab] ✓ audited via ${caseUrl}`);
@@ -77,7 +70,7 @@ export class OvruleClient {
     baseUrl;
     fetchImpl;
     constructor(options = {}) {
-        this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? DEFAULT_OVRULE_BASE_URL;
+        this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? getDefaultBaseUrl();
         this.fetchImpl = options.fetch ?? globalThis.fetch;
         if (!this.fetchImpl) {
             throw new Error("No fetch implementation available. Pass one in OvruleClient options.");
@@ -136,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 = {}) {
@@ -178,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.1",
-  "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",
@@ -14,8 +14,13 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "bin/ovrule-lab",
+    "bin/welcome.js"
   ],
+  "bin": {
+    "ovrule-lab": "./bin/ovrule-lab"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",