proactive-gate 0.1.2 → 0.2.1

package/dist/src/init.js

@@ -0,0 +1,115 @@
+/**
+ * `proactive-gate init` writes a policy you can read and edit, and prints the
+ * few lines that wire it into the framework you named. The goal is that the
+ * distance between "npm i" and a gate that actually runs is one command.
+ */
+import { presets } from "./presets.js";
+export const FRAMEWORKS = ["ai-sdk", "mastra", "langchain", "openai-agents", "none"];
+/** The order LILA runs, as a policy document. A preset is appended when one is named. */
+export function buildPolicy(preset) {
+    const checks = [
+        { id: "consent" },
+        { id: "enabled" },
+        { id: "mode", allow: ["normal"] },
+        { id: "snooze", defer: true },
+        { id: "mute" },
+        { id: "intensity" },
+        { id: "quietHours", priorityFloor: "critical" },
+        { id: "trustRamp", days: 7, minPriority: "high" },
+        { id: "dismissalCooldown", dismissals: 3, withinDays: 30, silenceDays: 7 },
+        { id: "dailyBudget", limit: 5, bypassPriority: "critical" },
+    ];
+    if (preset)
+        checks.splice(checks.length - 1, 0, { preset });
+    return { specVersion: "1.0.0", onStoreError: "open", checks };
+}
+const SNIPPETS = {
+    "ai-sdk": (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateToolApproval } from "proactive-gate/ai-sdk";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+const approve = gateToolApproval({ gate, toInput: (call) => call.input.gate });
+
+// Give the send tool needsApproval: true, then answer each request:
+const { approved, reason } = await approve(call);
+// addToolApprovalResponse({ id: call.approvalId, approved, reason })`,
+    mastra: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateProcessor } from "proactive-gate/mastra";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// In the agent definition:
+//   outputProcessors: [gateProcessor({ gate, toInput: ({ messages }) => ({ user, candidate }) })]
+// A rejection calls abort(reason) before the result reaches the user.`,
+    langchain: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateMiddleware } from "proactive-gate/langchain";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// createAgent({
+//   tools: [sendMessage],
+//   middleware: [gateMiddleware({ gate, tools: ["send_message"], toInput: (call) => call.args.gate })],
+// })
+// A rejection returns a tool message carrying the reason instead of running the tool.`,
+    "openai-agents": (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateToolInputGuardrail } from "proactive-gate/openai-agents";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// tool({
+//   name: "send_message",
+//   inputGuardrails: [gateToolInputGuardrail({ gate, toInput: (input) => input.gate })],
+// })
+// A rejection trips the wire with the reason in outputInfo.`,
+    none: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+const decision = await gate.evaluate({ user, candidate });
+if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
+  await send(candidate);
+} else {
+  log.info({ reason: decision.reason, rejectedBy: decision.rejectedBy }, "not sent");
+}`,
+};
+export function snippetFor(framework, file) {
+    return SNIPPETS[framework](file);
+}
+export function presetLines() {
+    return Object.entries(presets)
+        .map(([name, preset]) => `  ${name.padEnd(28)}${preset.sources[0] ?? ""}`)
+        .join("\n");
+}
+export function listText() {
+    return `presets (append one to the policy, or leave it out):\n${presetLines()}\n\nframeworks: ${FRAMEWORKS.join(", ")}`;
+}
+/** Everything init writes and prints, as data, so the test does not need a filesystem. */
+export function plan(options) {
+    if (options.preset && !presets[options.preset]) {
+        throw new Error(`unknown preset "${options.preset}"; known presets: ${Object.keys(presets).join(", ")}`);
+    }
+    const framework = options.framework ?? "none";
+    if (!FRAMEWORKS.includes(framework)) {
+        throw new Error(`unknown framework "${framework}"; known frameworks: ${FRAMEWORKS.join(", ")}`);
+    }
+    const preset = options.preset ? presets[options.preset] : undefined;
+    const lines = [
+        `wrote ${options.out}`,
+        "",
+        preset
+            ? `preset ${options.preset}: ${preset.note}\nsources:\n${preset.sources.map((s) => `  ${s}`).join("\n")}\n`
+            : "no preset: the ten checks above are the default order. `proactive-gate init --list` shows the platform and legal presets.\n",
+        `wire it in (${framework}):`,
+        "",
+        snippetFor(framework, options.out),
+        "",
+        `then replay a day against it before you ship:`,
+        `  npx proactive-gate replay day.jsonl --policy ${options.out} --commit`,
+    ];
+    return { policy: `${JSON.stringify(buildPolicy(options.preset), null, 2)}\n`, message: lines.join("\n") };
+}

package/dist/src/policy.d.ts

@@ -0,0 +1,8 @@
+import type { Check, GateOptions, Policy } from "./types.js";
+type Options = Record<string, unknown>;
+type Factory = (options: Options) => Check;
+/** Every check a JSON policy may name, with the options it reads. */
+export declare const KNOWN_CHECKS: Record<string, Factory>;
+/** Compile a JSON policy into gate options. Throws on unknown ids, unknown presets, or an unsupported specVersion. */
+export declare function compilePolicy(policy: Policy): GateOptions;
+export {};

package/dist/src/policy.js

@@ -0,0 +1,74 @@
+import * as checks from "./checks.js";
+import { presets } from "./presets.js";
+const num = (o, key) => (typeof o[key] === "number" ? o[key] : undefined);
+const str = (o, key) => (typeof o[key] === "string" ? o[key] : undefined);
+const bool = (o, key) => (typeof o[key] === "boolean" ? o[key] : undefined);
+const prio = (o, key) => str(o, key);
+const strs = (o, key) => (Array.isArray(o[key]) ? o[key] : undefined);
+const opt = (value, key) => (value === undefined ? {} : { [key]: value });
+const budgetOptions = (o) => ({ ...opt(num(o, "limit"), "limit"), ...opt(prio(o, "bypassPriority"), "bypassPriority"), ...opt(num(o, "nearLimit"), "nearLimit") });
+/** Every check a JSON policy may name, with the options it reads. */
+export const KNOWN_CHECKS = {
+    killSwitch: (o) => checks.killSwitch(() => bool(o, "on") === true),
+    consent: () => checks.consent(),
+    enabled: () => checks.enabled(),
+    mode: (o) => checks.mode({ allow: strs(o, "allow") ?? ["normal"] }),
+    snooze: (o) => checks.snooze({ ...opt(bool(o, "defer"), "defer") }),
+    mute: () => checks.mute(),
+    intensity: (o) => (o.floors ? checks.intensity(o.floors) : checks.intensity()),
+    quietHours: (o) => checks.quietHours({ ...opt(prio(o, "priorityFloor"), "priorityFloor") }),
+    trustRamp: (o) => checks.trustRamp({ ...opt(num(o, "days"), "days"), ...opt(prio(o, "minPriority"), "minPriority") }),
+    dismissalCooldown: (o) => checks.dismissalCooldown({ ...opt(num(o, "dismissals"), "dismissals"), ...opt(num(o, "withinDays"), "withinDays"), ...opt(num(o, "silenceDays"), "silenceDays") }),
+    adaptiveTiming: () => checks.adaptiveTiming(),
+    dailyBudget: (o) => checks.dailyBudget(budgetOptions(o)),
+    weeklyBudget: (o) => checks.weeklyBudget(budgetOptions(o)),
+    monthlyBudget: (o) => checks.monthlyBudget(budgetOptions(o)),
+    utilityFloor: (o) => checks.utilityFloor({ costFalseAlarm: num(o, "costFalseAlarm") ?? 1, costMissedHelp: num(o, "costMissedHelp") ?? 1 }),
+    boundedDeferral: (o) => checks.boundedDeferral({ ...opt(num(o, "lambda"), "lambda"), ...opt(num(o, "interruptCost"), "interruptCost"), ...opt(num(o, "staleness"), "staleness"), ...opt(num(o, "boundSeconds"), "boundSeconds") }),
+    allowedWindow: (o) => checks.allowedWindow({ start: str(o, "start") ?? "08:00", end: str(o, "end") ?? "21:00", timezone: str(o, "timezone") ?? "user", ...opt(prio(o, "priorityFloor"), "priorityFloor"), ...opt(str(o, "id"), "id") }),
+    requiresConsent: (o) => checks.requiresConsent({ name: str(o, "name") ?? "consent", ...(o.when ? { when: o.when } : {}), ...opt(str(o, "id"), "id") }),
+    rateLimit: (o) => checks.rateLimit({ limit: num(o, "limit") ?? 1, perSeconds: num(o, "perSeconds") ?? 1, ...opt(str(o, "keyBy"), "keyBy"), ...opt(str(o, "id"), "id") }),
+    recentInteraction: (o) => checks.recentInteraction({ withinHours: num(o, "withinHours") ?? 48 }),
+    windowBudget: (o) => checks.windowBudget({ limit: num(o, "limit") ?? 1, withinHours: num(o, "withinHours") ?? 48 }),
+};
+const SUPPORTED_MAJOR = 1;
+/** Compile a JSON policy into gate options. Throws on unknown ids, unknown presets, or an unsupported specVersion. */
+export function compilePolicy(policy) {
+    const major = Number(String(policy.specVersion).split(".")[0]);
+    if (!Number.isInteger(major) || major !== SUPPORTED_MAJOR) {
+        throw new Error(`policy specVersion ${policy.specVersion} is not supported; this package implements spec ${SUPPORTED_MAJOR}.x`);
+    }
+    if (!Array.isArray(policy.checks) || !policy.checks.length)
+        throw new Error("policy.checks must be a non-empty array");
+    const compiled = [];
+    for (const entry of policy.checks) {
+        const { shadow, ...rest } = entry;
+        let built;
+        if (typeof rest.preset === "string") {
+            const preset = presets[rest.preset];
+            if (!preset)
+                throw new Error(`unknown preset "${rest.preset}"; known presets: ${Object.keys(presets).join(", ")}`);
+            const { preset: _name, ...options } = rest;
+            built = preset(options);
+        }
+        else if (typeof rest.id === "string") {
+            const factory = KNOWN_CHECKS[rest.id];
+            if (!factory)
+                throw new Error(`unknown check "${rest.id}"; known checks: ${Object.keys(KNOWN_CHECKS).join(", ")}`);
+            const { id: _id, ...options } = rest;
+            built = [factory(options)];
+        }
+        else {
+            throw new Error("each policy entry needs an id or a preset");
+        }
+        if (shadow)
+            for (const c of built)
+                c.shadow = true;
+        compiled.push(...built);
+    }
+    return {
+        checks: compiled,
+        ...(policy.onStoreError ? { onStoreError: policy.onStoreError } : {}),
+        ...(policy.keyPrefix !== undefined ? { keyPrefix: policy.keyPrefix } : {}),
+    };
+}

package/dist/src/presets.d.ts

@@ -0,0 +1,9 @@
+import type { Check } from "./types.js";
+export interface Preset {
+    (options?: Record<string, unknown>): Check[];
+    /** Primary sources the numbers come from. */
+    sources: string[];
+    /** What the preset encodes and what it leaves out. */
+    note: string;
+}
+export declare const presets: Record<string, Preset>;

package/dist/src/presets.js

@@ -0,0 +1,45 @@
+/**
+ * Presets: the platform quotas and legal limits people ship against, as ordered
+ * check lists. Reviewable defaults, not legal advice. Every number sits next to
+ * its source; several official sources disagree with each other (the Kakao
+ * evening boundary is quoted as 20:00, 20:50 and 20:55), so read the note and
+ * decide for your own deployment.
+ */
+import * as c from "./checks.js";
+const define = (build, sources, note) => {
+    const preset = ((options = {}) => build(options));
+    preset.sources = sources;
+    preset.note = note;
+    return preset;
+};
+const LINE_PLANS = { communication: 200, light: 5000, standard: 30000 };
+export const presets = {
+    lineMessagingApi: define((o) => {
+        const plan = typeof o.plan === "string" ? o.plan : "communication";
+        const limit = LINE_PLANS[plan];
+        if (limit === undefined)
+            throw new Error(`lineMessagingApi: unknown plan "${plan}", known: ${Object.keys(LINE_PLANS).join(", ")}`);
+        return [c.consent(), c.monthlyBudget({ limit, nearLimit: 0.9 })];
+    }, ["https://developers.line.biz/en/docs/messaging-api/pricing/", "https://developers.line.biz/en/reference/messaging-api/"], "Monthly push messages per plan for Japan: communication 200, light 5,000, standard 30,000; replies are free and not counted. Multicast and broadcast request rates are not encoded."),
+    wechatSubscriptionMessage: define(() => [c.requiresConsent({ name: "subscription" }), c.windowBudget({ limit: 1, withinHours: 24 * 365 })], ["https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/subscribe-message-overview.html"], "One-time subscription: exactly one message per opt-in; set user.lastInboundAt to the opt-in instant. Long-term subscriptions for government, medical, transport, finance and education categories are not encoded."),
+    wechatCustomerService: define(() => [c.recentInteraction({ withinHours: 48 }), c.windowBudget({ limit: 5, withinHours: 48 })], ["https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/customer-message/send.html"], "Mini program customer-service messages: within 48 hours of the user's last message, at most 5 in that window."),
+    wechatTemplateMessage: define(() => [c.requiresConsent({ name: "templateTrigger" }), c.rateLimit({ limit: 3, perSeconds: 24 * 3600, keyBy: "user", id: "rate:template" })], ["https://developers.weixin.qq.com/doc/service/guide/product/template_message/Template_Message_Operation_Specifications.html"], "Template messages only after a user action (consents.templateTrigger) and no more than three repeated templates a day; marketing templates are not allowed at all."),
+    wecomAppMessage: define(() => [c.rateLimit({ limit: 30, perSeconds: 60, id: "rate:30/min" }), c.rateLimit({ limit: 1000, perSeconds: 3600, id: "rate:1000/h" })], ["https://developer.work.weixin.qq.com/document/path/96212"], "WeCom application messages per app per member: 30 a minute and 1,000 an hour; the platform drops the excess silently, this preset refuses it with a reason."),
+    kakaoAlimtalk: define(() => [c.consent()], ["https://kakaobusiness.gitbook.io/main/ad/infotalk"], "AlimTalk is informational and carries no time-of-day limit; consent is the only gate."),
+    kakaoBrandMessage: define(() => [c.requiresConsent({ name: "ad" }), c.allowedWindow({ start: "08:00", end: "20:50", timezone: "Asia/Seoul", id: "window:kakao" })], ["https://kakaobusiness.gitbook.io/main/ad/moment/messagead/channelmessage/new/send"], "Brand messages need advertising consent and go out 08:00 to 20:50 Korea time regardless of the recipient's location. Official sources also quote 20:00 and 20:55; 20:50 is the stricter documented value."),
+    krNetworkAct50: define(() => [c.requiresConsent({ name: "ad" }), c.requiresConsent({ name: "night", when: { start: "21:00", end: "08:00", timezone: "user" } })], ["https://www.law.go.kr", "https://developers.fingerpush.com/biz-message/console/ads-guide"], "Network Act article 50: prior consent for advertising, and a separate consent for 21:00 to 08:00 (email is exempt). The two-year re-confirmation is not encoded."),
+    jpAntiSpamLaw: define(() => [c.requiresConsent({ name: "optIn" })], ["https://www.soumu.go.jp/main_sosiki/cybersecurity/kokumin/basic/legal/08/"], "Opt-in since 2008 with sender identity and an opt-out route. There is no time-of-day rule in the law; a Japanese quiet-hours window would be etiquette, so none is encoded."),
+    cnMinorMode: define(() => {
+        const window = c.allowedWindow({ start: "06:00", end: "22:00", timezone: "Asia/Shanghai", id: "window:minor" });
+        const budget = c.dailyBudget({ limit: 1 });
+        const adult = () => ({ kind: "pass", reason: "not a minor" });
+        return [
+            { id: window.id, run: (ctx) => (ctx.user.minor ? window.run(ctx) : adult(ctx)) },
+            { id: budget.id, limit: budget.limit, run: (ctx) => (ctx.user.minor ? budget.run(ctx) : adult(ctx)), consume: (ctx) => (ctx.user.minor ? budget.consume(ctx) : Promise.resolve(true)) },
+        ];
+    }, ["https://www.cac.gov.cn/2024-11/15/c_1733364304749288.htm", "https://www.cac.gov.cn/2022-01/04/c_1642894606364259.htm"], "Minor mode: no service 22:00 to 06:00 China time and a daily budget of one when user.minor is true; adults pass both checks. Per-age daily durations are not encoded."),
+    usTcpa: define(() => [c.allowedWindow({ start: "08:00", end: "21:00", timezone: "user", id: "window:tcpa" })], ["https://www.law.cornell.edu/cfr/text/47/64.1200"], "47 CFR 64.1200: no solicitation before 8 a.m. or after 9 p.m. at the called party's local time."),
+    euEprivacy: define(() => [{ ...c.requiresConsent({ name: "marketing" }), run: (ctx) => (ctx.user.existingCustomer ? { kind: "pass", reason: "existing customer, soft opt-in" } : c.requiresConsent({ name: "marketing" }).run(ctx)) }], ["https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32002L0058"], "Directive 2002/58/EC article 13: prior consent for direct marketing, with the soft opt-in for existing customers (user.existingCustomer)."),
+    telegramBot: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" }), c.rateLimit({ limit: 20, perSeconds: 60, keyBy: "channel", id: "rate:20/min" })], ["https://core.telegram.org/bots/faq"], "One message a second per chat and twenty a minute per group, keyed by candidate.channel. The broadcast rate of roughly thirty a second is not encoded."),
+    slackApp: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" })], ["https://docs.slack.dev/apis/web-api/rate-limits/"], "chat.postMessage: one message a second per channel, keyed by candidate.channel."),
+};

package/dist/src/stores.js

@@ -1,5 +1,3 @@
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
 /** In-process store. Correct for one instance, wrong the moment you scale out. */
 export class MemoryStore {
     clock;
@@ -71,13 +69,12 @@ export class SqliteStore {
     database;
     clock;
     constructor(path, clock = () => Date.now()) {
-        let DatabaseSync;
-        try {
-            ({ DatabaseSync } = require("node:sqlite"));
-        }
-        catch {
+        // Resolved lazily so the module also loads where node:sqlite does not exist (older Node, a browser bundle).
+        const loader = globalThis.process?.getBuiltinModule;
+        const mod = loader ? loader("node:sqlite") : undefined;
+        const DatabaseSync = mod?.DatabaseSync;
+        if (!DatabaseSync)
             throw new Error("SqliteStore requires Node.js 22.5 or newer.");
-        }
         this.database = new DatabaseSync(path);
         this.clock = clock;
         this.database.exec("CREATE TABLE IF NOT EXISTS proactive_gate_store (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL, expires_at INTEGER)");

package/dist/src/types.d.ts

@@ -29,6 +29,14 @@ export interface UserState {
     createdAt?: Date | string;
     /** Surfaces the user allows, in preference order. Defaults to the candidate's surfaces. */
     surfaces?: Surface[];
+    /** Named consents a preset can require, e.g. { ad: true, night: false }. */
+    consents?: Record<string, boolean>;
+    /** Last message the user sent to the assistant; drives inbound-window presets. */
+    lastInboundAt?: Date | string | null;
+    /** True when the user is a minor under the applicable rules. */
+    minor?: boolean;
+    /** True when a soft opt-in for existing customers applies. */
+    existingCustomer?: boolean;
 }
 /** The thing the agent wants to say. */
 export interface Candidate {
@@ -38,6 +46,14 @@ export interface Candidate {
     priority?: Priority;
     /** Surfaces this candidate can be delivered on, in preference order. */
     surfaces?: Surface[];
+    /** Channel or chat the message goes to; rate limits keyed by channel read it. */
+    channel?: string;
+    /** The caller's own signal that the user is busy right now; boundedDeferral reads it. */
+    busy?: boolean;
+    /** Caller-estimated probability the user accepts this message; utilityFloor reads it. */
+    pAccept?: number;
+    /** Caller-estimated probability the user needs it; utilityFloor reads it, default 1. */
+    pNeed?: number;
     /** Free-form payload; the gate never reads it. */
     payload?: unknown;
 }
@@ -50,6 +66,11 @@ export interface EvaluateInput {
 /** What a single check may say. */
 export type CheckOutcome = {
     kind: "pass";
+    reason?: string;
+    nearLimit?: {
+        used: number;
+        limit: number;
+    };
 } | {
     kind: "reject";
     reason: string;
@@ -61,6 +82,10 @@ export type CheckOutcome = {
 } | {
     kind: "skip";
     reason: string;
+} | {
+    kind: "defer";
+    reason: string;
+    retryAt: Date;
 };
 export interface CheckContext {
     user: UserState;
@@ -75,26 +100,50 @@ export interface Check {
     id: string;
     /** True when the check can never reject; it only adjusts timing or surfaces. */
     nonRejecting?: boolean;
+    /** True to record what the check would have done without letting it stop evaluation. */
+    shadow?: boolean;
     run(ctx: CheckContext): Promise<CheckOutcome> | CheckOutcome;
+    /**
+     * Budget-like checks consume one unit at commit time. Return false when the
+     * unit was not available (a concurrent delivery took it). The gate calls
+     * consume() in check order, once per decision.
+     */
+    consume?(ctx: CheckContext): Promise<boolean>;
 }
 export interface TraceEntry {
     id: string;
     outcome: CheckOutcome["kind"];
     reason?: string;
     ms: number;
+    /** Present when the check ran in shadow mode and would have stopped evaluation. */
+    shadow?: boolean;
 }
 export interface Decision {
+    /** Unique per evaluation: userId, candidateId, the instant and a sequence number. commit() is idempotent on it. */
+    id: string;
     allowed: boolean;
     userId: string;
     candidateId: string;
-    /** Surfaces to route to when allowed. Empty when rejected. */
+    /** Surfaces to route to when allowed. Empty when rejected or deferred. */
     surfaces: Surface[];
     /** Set when a non-rejecting check asked for a later delivery. */
     deliverAt?: Date;
     /** The check that rejected, when rejected. */
     rejectedBy?: string;
-    /** Human-readable reason, when rejected. */
+    /** The check that deferred, when deferred. */
+    deferredBy?: string;
+    /** When to evaluate again, when deferred. */
+    retryAt?: Date;
+    /** Human-readable reason, when rejected or deferred. */
     reason?: string;
+    /** Checks in shadow mode that would have rejected or deferred. */
+    shadowed: string[];
+    /** Budget checks that passed close to their limit. */
+    nearLimit: Array<{
+        check: string;
+        used: number;
+        limit: number;
+    }>;
     /** Every check that ran, in order, with what it said. */
     trace: TraceEntry[];
     evaluatedAt: Date;
@@ -113,6 +162,13 @@ export interface Store {
     incr(key: string, ttlSeconds?: number): Promise<number>;
     del(key: string): Promise<void>;
 }
+/** Observation points. Hooks never change a decision; a throwing hook is reported to `error` and ignored. */
+export interface GateHooks {
+    before?(ctx: CheckContext, check: Check): void | Promise<void>;
+    after?(ctx: CheckContext, check: Check, outcome: CheckOutcome, ms: number): void | Promise<void>;
+    error?(ctx: CheckContext, check: Check, error: unknown): void | Promise<void>;
+    finally?(decision: Decision): void | Promise<void>;
+}
 export interface GateOptions {
     checks: Check[];
     store?: Store;
@@ -126,4 +182,20 @@ export interface GateOptions {
     onDecision?: (decision: Decision) => void;
     /** Key prefix for everything the gate writes to the store. */
     keyPrefix?: string;
+    /** Observation hooks, e.g. one OpenTelemetry span per check. */
+    hooks?: GateHooks;
 }
+/** A policy document: the same checks as data. See spec/schema/policy.schema.json. */
+export interface Policy {
+    specVersion: string;
+    onStoreError?: "open" | "closed";
+    keyPrefix?: string;
+    checks: PolicyEntry[];
+}
+export type PolicyEntry = ({
+    id: string;
+    shadow?: boolean;
+} & Record<string, unknown>) | ({
+    preset: string;
+    shadow?: boolean;
+} & Record<string, unknown>);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "proactive-gate",
-  "version": "0.1.2",
-  "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks: kill switch, consent, quiet hours, trust ramp, dismissal cooldown, daily budget.",
+  "version": "0.2.1",
+  "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks as code or JSON, a conformance spec, presets for platform and legal limits, adapters for AI SDK, Mastra, LangChain and OpenAI Agents, and a Python sibling.",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -9,23 +9,51 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
-    }
+    },
+    "./presets": {
+      "types": "./dist/src/presets.d.ts",
+      "import": "./dist/src/presets.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/src/adapters/ai-sdk.d.ts",
+      "import": "./dist/src/adapters/ai-sdk.js"
+    },
+    "./mastra": {
+      "types": "./dist/src/adapters/mastra.d.ts",
+      "import": "./dist/src/adapters/mastra.js"
+    },
+    "./langchain": {
+      "types": "./dist/src/adapters/langchain.d.ts",
+      "import": "./dist/src/adapters/langchain.js"
+    },
+    "./openai-agents": {
+      "types": "./dist/src/adapters/openai-agents.d.ts",
+      "import": "./dist/src/adapters/openai-agents.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "proactive-gate": "dist/src/cli.js"
   },
   "files": [
-    "dist",
+    "dist/src",
     "README.md",
     "LICENSE"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/test/gate.test.js",
+    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js test/release.test.mjs test/examples.test.mjs test/naive.test.mjs",
     "lint": "tsc -p tsconfig.json --noEmit",
+    "spec-lint": "node test/spec-lint.mjs",
+    "conformance": "npm run build && node dist/src/cli.js replay --fixtures spec/fixtures",
     "prepublishOnly": "npm test",
-    "examples": "npm run build && node dist/src/cli.js replay examples/day.jsonl --policy examples/policy.js --commit",
-    "bench": "npm run build && node bench/evaluate.mjs"
+    "examples": "npm run build && node dist/src/cli.js replay examples/day.jsonl --policy examples/policy.js --commit && node dist/src/cli.js replay examples/day.jsonl --policy examples/policy.json --commit && node examples/mastra/run.mjs && node examples/ai-sdk/run.mjs",
+    "bench": "npm run build && node bench/evaluate.mjs",
+    "release": "node scripts/release.mjs",
+    "release-gate": "npm run build && node scripts/release-gate.mjs",
+    "trace-svg": "npm run build && node scripts/trace-svg.mjs",
+    "bench:compare": "npm run build && node bench/compare.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -39,7 +67,20 @@
     "quiet-hours",
     "consent",
     "budget",
-    "llm"
+    "llm",
+    "policy",
+    "presets",
+    "langchain",
+    "mastra",
+    "ai-sdk",
+    "openai-agents",
+    "claude-code",
+    "guardrails",
+    "agent-guardrails",
+    "notification-budget",
+    "proactive-ai",
+    "python",
+    "conformance"
   ],
   "author": "Efe Genc",
   "license": "MIT",
@@ -47,7 +88,14 @@
     "type": "git",
     "url": "git+https://github.com/Bubblegunn/proactive-gate.git"
   },
-  "homepage": "https://github.com/Bubblegunn/proactive-gate#readme",
+  "homepage": "https://bubblegunn.github.io/proactive-gate/",
+  "bugs": {
+    "url": "https://github.com/Bubblegunn/proactive-gate/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@types/node": "^26.4.1",

package/dist/test/gate.test.d.ts

@@ -1 +0,0 @@
-export {};