proactive-gate 0.1.2 → 0.2.1

package/dist/src/adapters/ai-sdk.js

@@ -0,0 +1,17 @@
+export function gateToolApproval(options) {
+    const commit = options.commit ?? true;
+    return async (call) => {
+        const input = options.toInput(call);
+        const decision = await options.gate.evaluate(input);
+        if (!decision.allowed)
+            return { approved: false, reason: describe(decision) };
+        if (commit && !(await options.gate.commit(decision, input)))
+            return { approved: false, reason: "a budget was exhausted at commit" };
+        return { approved: true, ...(decision.deliverAt ? { reason: `deliver at ${decision.deliverAt.toISOString()}` } : {}) };
+    };
+}
+export function describe(decision) {
+    if (decision.deferredBy)
+        return `deferred by ${decision.deferredBy} until ${decision.retryAt?.toISOString()}: ${decision.reason}`;
+    return `rejected by ${decision.rejectedBy}: ${decision.reason}`;
+}

package/dist/src/adapters/langchain.d.ts

@@ -0,0 +1,32 @@
+/**
+ * LangChain middleware that wraps tool calls. For the tools listed in `tools`
+ * the gate decides first; a rejection returns a tool message carrying the
+ * reason instead of running the tool.
+ *
+ *   createAgent({ tools: [sendMessage], middleware: [gateMiddleware({ gate, tools: ["send_message"], toInput: (req) => req.toolCall.args.gate })] })
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface ToolCallRequest {
+    toolCall: {
+        name: string;
+        id?: string;
+        args: Record<string, unknown>;
+    };
+}
+export interface ToolMessageLike {
+    type: "tool";
+    content: string;
+    tool_call_id: string;
+    status: "success" | "error";
+}
+export interface ToolCallMiddleware<R extends ToolCallRequest = ToolCallRequest, T = unknown> {
+    name: string;
+    wrapToolCall(request: R, handler: (request: R) => Promise<T>): Promise<T | ToolMessageLike>;
+}
+export declare function gateMiddleware<R extends ToolCallRequest = ToolCallRequest, T = unknown>(options: {
+    gate: Gate;
+    tools: string[];
+    toInput: (request: R) => EvaluateInput;
+    commit?: boolean;
+}): ToolCallMiddleware<R, T>;

package/dist/src/adapters/langchain.js

@@ -0,0 +1,20 @@
+import { describe } from "./ai-sdk.js";
+export function gateMiddleware(options) {
+    const commit = options.commit ?? true;
+    const watched = new Set(options.tools);
+    return {
+        name: "proactive-gate",
+        async wrapToolCall(request, handler) {
+            if (!watched.has(request.toolCall.name))
+                return handler(request);
+            const input = options.toInput(request);
+            const decision = await options.gate.evaluate(input);
+            const refuse = (reason) => ({ type: "tool", content: `proactive-gate: ${reason}`, tool_call_id: request.toolCall.id ?? "", status: "error" });
+            if (!decision.allowed)
+                return refuse(describe(decision));
+            if (commit && !(await options.gate.commit(decision, input)))
+                return refuse("a budget was exhausted at commit");
+            return handler(request);
+        },
+    };
+}

package/dist/src/adapters/mastra.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Mastra output processor. Put it in the agent's `outputProcessors`; when
+ * the gate rejects, the processor calls abort(reason) and the agent's result
+ * is stopped before it reaches the user.
+ *
+ *   outputProcessors: [gateProcessor({ gate, toInput: ({ messages }) => ({ user, candidate: { id, type: "reply" } }) })]
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface ProcessorArgs<M = unknown> {
+    messages: M[];
+    abort: (reason?: string) => never;
+}
+export interface OutputProcessor<M = unknown> {
+    id: string;
+    processOutputResult(args: ProcessorArgs<M>): Promise<M[]>;
+}
+export declare function gateProcessor<M = unknown>(options: {
+    gate: Gate;
+    toInput: (args: {
+        messages: M[];
+    }) => EvaluateInput;
+    id?: string;
+    commit?: boolean;
+}): OutputProcessor<M>;

package/dist/src/adapters/mastra.js

@@ -0,0 +1,16 @@
+import { describe } from "./ai-sdk.js";
+export function gateProcessor(options) {
+    const commit = options.commit ?? true;
+    return {
+        id: options.id ?? "proactive-gate",
+        async processOutputResult({ messages, abort }) {
+            const input = options.toInput({ messages });
+            const decision = await options.gate.evaluate(input);
+            if (!decision.allowed)
+                return abort(`proactive-gate: ${describe(decision)}`);
+            if (commit && !(await options.gate.commit(decision, input)))
+                return abort("proactive-gate: a budget was exhausted at commit");
+            return messages;
+        },
+    };
+}

package/dist/src/adapters/openai-agents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * An OpenAI Agents SDK tool input guardrail. Attach it to the send tool with
+ * `defineToolInputGuardrail`-compatible shape; a rejection trips the wire with
+ * the reason in outputInfo.
+ *
+ *   tool({ name: "send_message", inputGuardrails: [gateToolInputGuardrail({ gate, toInput: ({ input }) => input.gate })] })
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface GuardrailArgs<I = unknown> {
+    input: I;
+    context?: unknown;
+}
+export interface GuardrailResult {
+    tripwireTriggered: boolean;
+    outputInfo: {
+        reason?: string;
+        surfaces?: string[];
+        deliverAt?: string;
+    };
+}
+export interface ToolInputGuardrail<I = unknown> {
+    name: string;
+    execute(args: GuardrailArgs<I>): Promise<GuardrailResult>;
+}
+export declare function gateToolInputGuardrail<I = unknown>(options: {
+    gate: Gate;
+    toInput: (args: GuardrailArgs<I>) => EvaluateInput;
+    name?: string;
+    commit?: boolean;
+}): ToolInputGuardrail<I>;

package/dist/src/adapters/openai-agents.js

@@ -0,0 +1,16 @@
+import { describe } from "./ai-sdk.js";
+export function gateToolInputGuardrail(options) {
+    const commit = options.commit ?? true;
+    return {
+        name: options.name ?? "proactive-gate",
+        async execute(args) {
+            const input = options.toInput(args);
+            const decision = await options.gate.evaluate(input);
+            if (!decision.allowed)
+                return { tripwireTriggered: true, outputInfo: { reason: describe(decision) } };
+            if (commit && !(await options.gate.commit(decision, input)))
+                return { tripwireTriggered: true, outputInfo: { reason: "a budget was exhausted at commit" } };
+            return { tripwireTriggered: false, outputInfo: { surfaces: decision.surfaces, ...(decision.deliverAt ? { deliverAt: decision.deliverAt.toISOString() } : {}) } };
+        },
+    };
+}

package/dist/src/checks.d.ts

@@ -17,8 +17,10 @@ export declare function enabled(): Check;
 export declare function mode(options: {
     allow: string[];
 }): Check;
-/** A global pause until an instant. */
-export declare function snooze(): Check;
+/** A global pause until an instant. With `defer: true` the decision carries the instant as `retryAt` instead of rejecting. */
+export declare function snooze(options?: {
+    defer?: boolean;
+}): Check;
 /** Per-type mute. */
 export declare function mute(): Check;
 /**
@@ -34,6 +36,9 @@ export declare function quietHours(options?: {
  * For the first `days` after sign-up the user hears from the system only at
  * or above `minPriority`. A proactive assistant is least calibrated exactly
  * when the user is least forgiving.
+ *
+ * Seven days is a judgement, not a finding. No study sets this number, and
+ * none of the literature the package cites speaks to it.
  */
 export declare function trustRamp(options?: {
     days?: number;
@@ -43,6 +48,10 @@ export declare function trustRamp(options?: {
  * When the user has dismissed `dismissals` candidates of a type within
  * `withinDays`, that type stays silent for `silenceDays`. Fed by
  * gate.record(userId, candidate, "dismissed").
+ *
+ * Three in thirty buying seven days is a judgement, not a finding. The shape
+ * is defensible, since a dismissal is the clearest signal a user gives; the
+ * three numbers are ours and no study sets them.
  */
 export declare function dismissalCooldown(options?: {
     dismissals?: number;
@@ -59,23 +68,120 @@ export declare function adaptiveTiming(options?: {
     nextGoodMoment?: (ctx: CheckContext) => Promise<Date | null> | Date | null;
     surfacesFor?: (ctx: CheckContext) => Surface[] | null;
 }): Check;
-/**
- * At most `limit` deliveries per user per local day. The check reads the
- * counter; gate.commit() increments it atomically and can still refuse when
- * two instances race, which is the only race-safe place to enforce a cap.
- */
 export interface BudgetCheck extends Check {
     limit: number;
+    consume(ctx: CheckContext): Promise<boolean>;
 }
-export declare function dailyBudget(options?: {
+export interface BudgetOptions {
     limit?: number;
     bypassPriority?: Priority;
-}): BudgetCheck;
+    /** Fraction of the limit at which a pass carries a nearLimit note. Default 0.8. */
+    nearLimit?: number;
+}
 export declare const budgetKey: (userId: string, now: Date, timezone?: string) => string;
 export declare const weeklyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
-export declare function weeklyBudget(options?: {
-    limit?: number;
-    bypassPriority?: Priority;
+export declare const monthlyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
+/**
+ * At most `limit` deliveries per user per local day.
+ *
+ * Five is a judgement, not a finding. The direction has support: Pielot and
+ * Rello, "Productive, Anxious, Lonely: 24 Hours Without Push Notifications",
+ * MobileHCI 2017 (https://arxiv.org/abs/1612.02314), cite an in-situ log study
+ * (Pielot, Church and de Oliveira, MobileHCI 2014) in which participants
+ * received a median of 63.5 notifications a day, so a handful is far below the
+ * ambient load. Nothing in that work says five.
+ */
+export declare function dailyBudget(options?: BudgetOptions): BudgetCheck;
+/**
+ * At most `limit` deliveries per user per local ISO week.
+ *
+ * The week is the ISO week, so the counter resets on Monday morning in the
+ * user's zone. For a Sunday-to-Thursday working week that reset lands
+ * mid-week. Documented rather than fixed; changing it would move every
+ * existing key.
+ */
+export declare function weeklyBudget(options?: BudgetOptions): BudgetCheck;
+/** At most `limit` deliveries per user per local calendar month. */
+export declare function monthlyBudget(options?: BudgetOptions): BudgetCheck;
+/**
+ * Expected-utility alerting: act only when the caller's estimate of acceptance
+ * clears tau = cFA / (cFA + pNeed * cFN). That threshold is the classical Bayes
+ * decision boundary between the cost of alerting when the user did not want it,
+ * (1 - p) * cFA, and the cost of staying silent when they did, p * cFN.
+ * The alerting application is Horvitz, Jacobs and Hovel, "Attention-Sensitive
+ * Alerting", UAI 1999 (https://arxiv.org/abs/1301.6707); the system in that
+ * paper is named Priorities.
+ * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
+ */
+export declare function utilityFloor(options: {
+    costFalseAlarm: number;
+    costMissedHelp: number;
+}): Check;
+/**
+ * Bounded deferral: when the user is busy, wait t* = min(bound,
+ * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
+ * staleness loss against the cost of interrupting a busy person, with the
+ * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ *
+ * The derivation is Achlioptas and Horvitz, "Principles of Bounded Deferral
+ * for Balancing Information Awareness with Interruption", Microsoft Research
+ * (http://erichorvitz.com/Bounded_Deferral.pdf): the expected cost is
+ * stationary where f'(t0) = lambda * c with f''(t0) > 0, so a quadratic
+ * staleness f(t) = s * t^2 gives t* = lambda * c / (2 * s).
+ *
+ * `lambda` defaults to 1/43 from the same paper's field study: 113 Microsoft
+ * employees (42 program managers, 25 developers, 19 testers, 10 administrators,
+ * 9 managers, 4 in sales and marketing, 4 research scientists), three
+ * sequential business days between 10am and 4pm, 4,803 busy situations, mean
+ * busy-session duration 43.12 s with a standard deviation of 51.79 s. That
+ * spread matters: the same paper's two-subject Interruption Workbench analysis
+ * puts the mean time to a lower-cost state after an alert at 11 s for one
+ * person and 101 s for the other. Measure your own users before trusting it.
+ *
+ * `staleness` and `boundSeconds` are scale choices, not findings. Only the
+ * ratio interruptCost / staleness affects t*, so the pair below is one way to
+ * express "a few minutes"; nothing in the literature fixes either number.
+ */
+export declare function boundedDeferral(options?: {
+    lambda?: number;
+    interruptCost?: number;
+    staleness?: number;
+    boundSeconds?: number;
+    isBusy?: (ctx: CheckContext) => boolean;
+}): Check;
+/** Deliveries only inside [start, end) local time in a fixed zone or the user's. */
+export declare function allowedWindow(options: {
+    start: string;
+    end: string;
+    timezone: string;
+    priorityFloor?: Priority;
+    id?: string;
+}): Check;
+/** Requires `user.consents[name]`, always or only inside a local-time window. */
+export declare function requiresConsent(options: {
+    name: string;
+    when?: {
+        start: string;
+        end: string;
+        timezone: string;
+    };
+    id?: string;
+}): Check;
+/** Fixed-window rate limit keyed by user or by candidate.channel; consumed at commit. */
+export declare function rateLimit(options: {
+    limit: number;
+    perSeconds: number;
+    keyBy?: "user" | "channel";
+    id?: string;
+}): BudgetCheck;
+/** The user wrote to the assistant within the last `withinHours`. */
+export declare function recentInteraction(options: {
+    withinHours: number;
+}): Check;
+/** At most `limit` deliveries in the `withinHours` window that opened with the user's last inbound message. */
+export declare function windowBudget(options: {
+    limit: number;
+    withinHours: number;
 }): BudgetCheck;
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export declare function defaultChecks(options?: {

package/dist/src/checks.js

@@ -2,6 +2,7 @@ import { PRIORITY_RANK } from "./types.js";
 const pass = { kind: "pass" };
 const reject = (reason) => ({ kind: "reject", reason });
 const skip = (reason) => ({ kind: "skip", reason });
+const defer = (reason, retryAt) => ({ kind: "defer", reason, retryAt });
 const atLeast = (priority, floor) => PRIORITY_RANK[priority] >= PRIORITY_RANK[floor];
 const toDate = (value) => {
     if (value === null || value === undefined)
@@ -37,6 +38,7 @@ export function inWindow(minutes, start, end) {
         return false;
     return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
 }
+const localDay = (now, timezone) => (timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10));
 /* ------------------------------------------------------------------------ */
 /* The checks, in the order LILA runs them. Compose your own order freely.  */
 /* ------------------------------------------------------------------------ */
@@ -72,13 +74,16 @@ export function mode(options) {
             : pass,
     };
 }
-/** A global pause until an instant. */
-export function snooze() {
+/** A global pause until an instant. With `defer: true` the decision carries the instant as `retryAt` instead of rejecting. */
+export function snooze(options = {}) {
     return {
         id: "snooze",
         run: ({ user, now }) => {
             const until = toDate(user.snoozedUntil);
-            return until && until > now ? reject(`snoozed until ${until.toISOString()}`) : pass;
+            if (!until || until <= now)
+                return pass;
+            const reason = `snoozed until ${until.toISOString()}`;
+            return options.defer ? defer(reason, until) : reject(reason);
         },
     };
 }
@@ -127,6 +132,9 @@ export function quietHours(options = {}) {
  * For the first `days` after sign-up the user hears from the system only at
  * or above `minPriority`. A proactive assistant is least calibrated exactly
  * when the user is least forgiving.
+ *
+ * Seven days is a judgement, not a finding. No study sets this number, and
+ * none of the literature the package cites speaks to it.
  */
 export function trustRamp(options = {}) {
     const days = options.days ?? 7;
@@ -148,6 +156,10 @@ export function trustRamp(options = {}) {
  * When the user has dismissed `dismissals` candidates of a type within
  * `withinDays`, that type stays silent for `silenceDays`. Fed by
  * gate.record(userId, candidate, "dismissed").
+ *
+ * Three in thirty buying seven days is a judgement, not a finding. The shape
+ * is defensible, since a dismissal is the clearest signal a user gives; the
+ * three numbers are ours and no study sets them.
  */
 export function dismissalCooldown(options = {}) {
     const n = options.dismissals ?? 3;
@@ -196,21 +208,30 @@ export function adaptiveTiming(options = {}) {
         },
     };
 }
-export function dailyBudget(options = {}) {
-    const limit = options.limit ?? 5;
+function budget(spec, options) {
+    const limit = options.limit ?? spec.defaultLimit;
+    const nearAt = Math.max(1, Math.ceil(limit * (options.nearLimit ?? 0.8)));
+    const bypass = (priority) => options.bypassPriority !== undefined && atLeast(priority, options.bypassPriority);
     return {
-        id: "dailyBudget",
+        id: spec.id,
         limit,
-        async run({ user, now, store, priority }) {
-            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+        async run(ctx) {
+            if (bypass(ctx.priority))
                 return pass;
-            const key = budgetKey(user.id, now, user.timezone);
-            const used = Number((await store.get(key)) ?? 0);
-            return used < limit ? pass : reject(`daily budget of ${limit} used (${used})`);
+            const used = Number((await ctx.store.get(spec.keyFor(ctx))) ?? 0);
+            if (used >= limit)
+                return reject(`${spec.label} of ${limit} used (${used})`);
+            return used >= nearAt ? { kind: "pass", reason: `${used} of ${limit} used`, nearLimit: { used, limit } } : pass;
+        },
+        async consume(ctx) {
+            if (bypass(ctx.priority))
+                return true;
+            const used = await ctx.store.incr(spec.keyFor(ctx), spec.ttlSeconds);
+            return used <= limit;
         },
     };
 }
-export const budgetKey = (userId, now, timezone) => `budget:${userId}:${timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10)}`;
+export const budgetKey = (userId, now, timezone) => `budget:${userId}:${localDay(now, timezone)}`;
 const isoWeekKey = (day) => {
     const date = new Date(`${day}T00:00:00Z`);
     const weekday = date.getUTCDay() || 7;
@@ -219,24 +240,175 @@ const isoWeekKey = (day) => {
     const week = Math.ceil((((date.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
     return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
 };
-export const weeklyBudgetKey = (userId, now, timezone) => {
-    const day = timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10);
-    return `weeklyBudget:${userId}:${isoWeekKey(day)}`;
-};
+export const weeklyBudgetKey = (userId, now, timezone) => `weeklyBudget:${userId}:${isoWeekKey(localDay(now, timezone))}`;
+export const monthlyBudgetKey = (userId, now, timezone) => `monthlyBudget:${userId}:${localDay(now, timezone).slice(0, 7)}`;
+/**
+ * At most `limit` deliveries per user per local day.
+ *
+ * Five is a judgement, not a finding. The direction has support: Pielot and
+ * Rello, "Productive, Anxious, Lonely: 24 Hours Without Push Notifications",
+ * MobileHCI 2017 (https://arxiv.org/abs/1612.02314), cite an in-situ log study
+ * (Pielot, Church and de Oliveira, MobileHCI 2014) in which participants
+ * received a median of 63.5 notifications a day, so a handful is far below the
+ * ambient load. Nothing in that work says five.
+ */
+export function dailyBudget(options = {}) {
+    return budget({ id: "dailyBudget", label: "daily budget", defaultLimit: 5, keyFor: ({ user, now }) => budgetKey(user.id, now, user.timezone), ttlSeconds: 2 * DAY_SECONDS }, options);
+}
+/**
+ * At most `limit` deliveries per user per local ISO week.
+ *
+ * The week is the ISO week, so the counter resets on Monday morning in the
+ * user's zone. For a Sunday-to-Thursday working week that reset lands
+ * mid-week. Documented rather than fixed; changing it would move every
+ * existing key.
+ */
 export function weeklyBudget(options = {}) {
-    const limit = options.limit ?? 20;
+    return budget({ id: "weeklyBudget", label: "weekly budget", defaultLimit: 20, keyFor: ({ user, now }) => weeklyBudgetKey(user.id, now, user.timezone), ttlSeconds: 8 * DAY_SECONDS }, options);
+}
+/** At most `limit` deliveries per user per local calendar month. */
+export function monthlyBudget(options = {}) {
+    return budget({ id: "monthlyBudget", label: "monthly budget", defaultLimit: 60, keyFor: ({ user, now }) => monthlyBudgetKey(user.id, now, user.timezone), ttlSeconds: 32 * DAY_SECONDS }, options);
+}
+/* ------------------------------------------------------------------------ */
+/* Optional, caller-fed checks. Off by default; the package ships no model.  */
+/* ------------------------------------------------------------------------ */
+/**
+ * Expected-utility alerting: act only when the caller's estimate of acceptance
+ * clears tau = cFA / (cFA + pNeed * cFN). That threshold is the classical Bayes
+ * decision boundary between the cost of alerting when the user did not want it,
+ * (1 - p) * cFA, and the cost of staying silent when they did, p * cFN.
+ * The alerting application is Horvitz, Jacobs and Hovel, "Attention-Sensitive
+ * Alerting", UAI 1999 (https://arxiv.org/abs/1301.6707); the system in that
+ * paper is named Priorities.
+ * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
+ */
+export function utilityFloor(options) {
+    const { costFalseAlarm: cFA, costMissedHelp: cFN } = options;
     return {
-        id: "weeklyBudget",
-        limit,
-        async run({ user, now, store, priority }) {
-            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+        id: "utilityFloor",
+        run: ({ candidate }) => {
+            if (typeof candidate.pAccept !== "number")
+                return skip("no pAccept on the candidate; utility floor cannot be evaluated");
+            const pNeed = typeof candidate.pNeed === "number" ? candidate.pNeed : 1;
+            const tau = cFA / (cFA + pNeed * cFN);
+            return candidate.pAccept >= tau ? pass : reject(`pAccept ${round3(candidate.pAccept)} < tau ${round3(tau)}`);
+        },
+    };
+}
+const round3 = (n) => Math.round(n * 1000) / 1000;
+/**
+ * Bounded deferral: when the user is busy, wait t* = min(bound,
+ * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
+ * staleness loss against the cost of interrupting a busy person, with the
+ * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ *
+ * The derivation is Achlioptas and Horvitz, "Principles of Bounded Deferral
+ * for Balancing Information Awareness with Interruption", Microsoft Research
+ * (http://erichorvitz.com/Bounded_Deferral.pdf): the expected cost is
+ * stationary where f'(t0) = lambda * c with f''(t0) > 0, so a quadratic
+ * staleness f(t) = s * t^2 gives t* = lambda * c / (2 * s).
+ *
+ * `lambda` defaults to 1/43 from the same paper's field study: 113 Microsoft
+ * employees (42 program managers, 25 developers, 19 testers, 10 administrators,
+ * 9 managers, 4 in sales and marketing, 4 research scientists), three
+ * sequential business days between 10am and 4pm, 4,803 busy situations, mean
+ * busy-session duration 43.12 s with a standard deviation of 51.79 s. That
+ * spread matters: the same paper's two-subject Interruption Workbench analysis
+ * puts the mean time to a lower-cost state after an alert at 11 s for one
+ * person and 101 s for the other. Measure your own users before trusting it.
+ *
+ * `staleness` and `boundSeconds` are scale choices, not findings. Only the
+ * ratio interruptCost / staleness affects t*, so the pair below is one way to
+ * express "a few minutes"; nothing in the literature fixes either number.
+ */
+export function boundedDeferral(options = {}) {
+    const lambda = options.lambda ?? 1 / 43;
+    const cost = options.interruptCost ?? 1;
+    const staleness = options.staleness ?? 0.0001;
+    const bound = options.boundSeconds ?? 240;
+    const tStar = Math.min(bound, (lambda * cost) / (2 * staleness));
+    return {
+        id: "boundedDeferral",
+        nonRejecting: true,
+        run: (ctx) => {
+            const busy = options.isBusy ? options.isBusy(ctx) : ctx.candidate.busy === true;
+            if (!busy)
                 return pass;
-            const key = weeklyBudgetKey(user.id, now, user.timezone);
-            const used = Number((await store.get(key)) ?? 0);
-            return used < limit ? pass : reject(`weekly budget of ${limit} used (${used})`);
+            const at = new Date(ctx.now.getTime() + Math.round(tStar * 1000));
+            return { kind: "adjust", reason: `user busy; deliver at ${at.toISOString()} (t* ${Math.round(tStar)} s)`, deliverAt: at };
+        },
+    };
+}
+/* ------------------------------------------------------------------------ */
+/* Primitives the presets compose.                                           */
+/* ------------------------------------------------------------------------ */
+const zoneOf = (ctx, timezone) => (timezone === "user" ? ctx.user.timezone : timezone);
+/** Deliveries only inside [start, end) local time in a fixed zone or the user's. */
+export function allowedWindow(options) {
+    const start = parseHHMM(options.start);
+    const end = parseHHMM(options.end);
+    return {
+        id: options.id ?? "allowedWindow",
+        run: (ctx) => {
+            const zone = zoneOf(ctx, options.timezone);
+            if (!zone)
+                return skip("no timezone on the user; window cannot be evaluated");
+            if (options.priorityFloor && atLeast(ctx.priority, options.priorityFloor))
+                return pass;
+            const { minutes } = localClock(ctx.now, zone);
+            return inWindow(minutes, start, end) ? pass : reject(`outside the allowed window ${options.start} to ${options.end} ${zone}`);
+        },
+    };
+}
+/** Requires `user.consents[name]`, always or only inside a local-time window. */
+export function requiresConsent(options) {
+    const when = options.when ? { start: parseHHMM(options.when.start), end: parseHHMM(options.when.end), timezone: options.when.timezone } : null;
+    return {
+        id: options.id ?? `consent:${options.name}`,
+        run: (ctx) => {
+            if (when) {
+                const zone = zoneOf(ctx, when.timezone);
+                if (!zone)
+                    return skip("no timezone on the user; consent window cannot be evaluated");
+                if (!inWindow(localClock(ctx.now, zone).minutes, when.start, when.end))
+                    return pass;
+            }
+            return ctx.user.consents?.[options.name] ? pass : reject(`consent "${options.name}" is missing${when ? ` (required ${options.when.start} to ${options.when.end})` : ""}`);
         },
     };
 }
+/** Fixed-window rate limit keyed by user or by candidate.channel; consumed at commit. */
+export function rateLimit(options) {
+    const keyBy = options.keyBy ?? "user";
+    const keyFor = (ctx) => {
+        const scope = keyBy === "channel" ? ctx.candidate.channel ?? ctx.user.id : ctx.user.id;
+        return `rate:${keyBy}:${scope}:${options.perSeconds}:${Math.floor(ctx.now.getTime() / 1000 / options.perSeconds)}`;
+    };
+    const id = options.id ?? `rate:${options.limit}/${options.perSeconds}s`;
+    return budget({ id, label: `rate limit ${options.limit} per ${options.perSeconds} s`, defaultLimit: options.limit, keyFor, ttlSeconds: options.perSeconds * 2 }, { limit: options.limit, nearLimit: 1 });
+}
+/** The user wrote to the assistant within the last `withinHours`. */
+export function recentInteraction(options) {
+    return {
+        id: "recentInteraction",
+        run: ({ user, now }) => {
+            const last = toDate(user.lastInboundAt);
+            if (!last)
+                return reject("no inbound message from the user on record");
+            const age = (now.getTime() - last.getTime()) / 3600000;
+            return age <= options.withinHours ? pass : reject(`last inbound message ${Math.floor(age)} h ago, window is ${options.withinHours} h`);
+        },
+    };
+}
+/** At most `limit` deliveries in the `withinHours` window that opened with the user's last inbound message. */
+export function windowBudget(options) {
+    const keyFor = ({ user }) => {
+        const last = toDate(user.lastInboundAt);
+        return `windowBudget:${user.id}:${last ? Math.floor(last.getTime() / 1000) : "none"}`;
+    };
+    return budget({ id: "windowBudget", label: `window budget`, defaultLimit: options.limit, keyFor, ttlSeconds: options.withinHours * 3600 }, { limit: options.limit, nearLimit: 1 });
+}
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export function defaultChecks(options = {}) {
     return [

package/dist/src/cli.d.ts

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 import type { Gate } from "./gate.js";
-import type { Decision } from "./types.js";
+import type { Decision, EvaluateInput } from "./types.js";
 export declare function loadPolicy(path?: string): Promise<Gate>;
 export declare function replay(lines: string[], gate: Gate, commit: boolean): Promise<Decision[]>;
 export declare function summarize(decisions: Decision[]): string;
+interface PreToolUseEvent {
+    tool_name?: string;
+    tool_input?: {
+        gate?: {
+            user: EvaluateInput["user"];
+            candidate: EvaluateInput["candidate"];
+            now?: string;
+        };
+    };
+}
+/** Turns a PreToolUse event into the hook output Claude Code expects, or null when the tool does not match. */
+export declare function hookDecision(event: PreToolUseEvent, gate: Gate, tool: string): Promise<string | null>;
+export {};