@flowdot.ai/guardian-agent 0.1.0

package/dist/notify/console.js

@@ -0,0 +1,27 @@
+/**
+ * consoleNotifier — writes notification events to stderr (or a configured stream).
+ * SPEC §6.3.
+ */
+export function consoleNotifier(options = {}) {
+    const stream = options.stream ?? process.stderr;
+    const prefix = options.prefix ?? '[guardian]';
+    return {
+        notify: async (event) => {
+            stream.write(`${prefix} ${formatEvent(event)}\n`);
+        },
+    };
+}
+function formatEvent(event) {
+    const parts = [event.kind, `agent=${event.agentId || '-'}`, `source=${event.source}`];
+    if (event.userId !== undefined)
+        parts.push(`user=${event.userId}`);
+    parts.push(`at=${event.ts}`);
+    const summary = JSON.stringify(event.summary);
+    if (summary !== '{}')
+        parts.push(`summary=${summary}`);
+    if (event.canonicalClearUrl !== undefined) {
+        parts.push(`clear=${event.canonicalClearUrl}`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=console.js.map

package/dist/notify/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/notify/console.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC9C,OAAO;QACL,MAAM,EAAE,KAAK,EAAE,KAAwB,EAAiB,EAAE;YACxD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,KAAwB;IAC3C,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,KAAK,CAAC,OAAO,IAAI,GAAG,EAAE,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,OAAO,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/notify/index.d.ts

@@ -0,0 +1,8 @@
+export type { Notifier, NotificationEvent, NotificationKind } from './types.js';
+export { consoleNotifier } from './console.js';
+export type { ConsoleNotifierOptions } from './console.js';
+export { webhookNotifier } from './webhook.js';
+export type { WebhookNotifierOptions } from './webhook.js';
+export { multiNotifier } from './multi.js';
+export type { MultiNotifierOptions } from './multi.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/notify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/notify/index.js

@@ -0,0 +1,4 @@
+export { consoleNotifier } from './console.js';
+export { webhookNotifier } from './webhook.js';
+export { multiNotifier } from './multi.js';
+//# sourceMappingURL=index.js.map

package/dist/notify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/notify/multi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * multiNotifier — fan a notification out to several notifiers in parallel.
+ * SPEC §6.3.
+ *
+ * Failures in one notifier do NOT stop the others. Errors are collected and
+ * reported via the optional `onError` callback.
+ */
+import type { Notifier, NotificationEvent } from './types.js';
+export interface MultiNotifierOptions {
+    notifiers: readonly Notifier[];
+    onError?: (err: unknown, event: NotificationEvent, index: number) => void;
+}
+export declare function multiNotifier(options: MultiNotifierOptions): Notifier;
+//# sourceMappingURL=multi.d.ts.map

package/dist/notify/multi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi.d.ts","sourceRoot":"","sources":["../../src/notify/multi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3E;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,QAAQ,CAerE"}

package/dist/notify/multi.js

@@ -0,0 +1,22 @@
+/**
+ * multiNotifier — fan a notification out to several notifiers in parallel.
+ * SPEC §6.3.
+ *
+ * Failures in one notifier do NOT stop the others. Errors are collected and
+ * reported via the optional `onError` callback.
+ */
+export function multiNotifier(options) {
+    const { notifiers, onError } = options;
+    return {
+        notify: async (event) => {
+            const results = await Promise.allSettled(notifiers.map(async (n) => n.notify(event)));
+            for (let i = 0; i < results.length; i++) {
+                const r = results[i];
+                if (r?.status === 'rejected') {
+                    onError?.(r.reason, event, i);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=multi.js.map

package/dist/notify/multi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi.js","sourceRoot":"","sources":["../../src/notify/multi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACvC,OAAO;QACL,MAAM,EAAE,KAAK,EAAE,KAAwB,EAAiB,EAAE;YACxD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC5C,CAAC;YACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;gBACrB,IAAI,CAAC,EAAE,MAAM,KAAK,UAAU,EAAE,CAAC;oBAC7B,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/notify/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Notification types. SPEC §6.
+ */
+export type NotificationKind = 'estop_press' | 'estop_clear' | 'policy_breach' | 'gate_denied';
+export interface NotificationEvent {
+    kind: NotificationKind;
+    /** User identifier on hub-coordinated deployments; undefined in single-process. */
+    userId?: string;
+    agentId: string;
+    ts: string;
+    /** "cli" | "native" | "mobile" | "hub" | "local" | host-defined */
+    source: string;
+    /** Free-form structured summary (counts, IP, reason, …). */
+    summary: Record<string, unknown>;
+    /** Optional canonical clear URL for hub-coordinated deployments. */
+    canonicalClearUrl?: string;
+}
+export interface Notifier {
+    notify(event: NotificationEvent): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/notify/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/notify/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,aAAa,GACb,eAAe,GACf,aAAa,CAAC;AAElB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD"}

package/dist/notify/types.js

@@ -0,0 +1,5 @@
+/**
+ * Notification types. SPEC §6.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/notify/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/notify/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/notify/webhook.d.ts

@@ -0,0 +1,21 @@
+/**
+ * webhookNotifier — POSTs notification events as JSON to a URL.
+ * SPEC §6.3.
+ *
+ * Failures are reported via the optional `onError` callback; they do NOT
+ * throw, because notifier failures must never block the press/clear flow
+ * the notification accompanies.
+ */
+import type { Notifier, NotificationEvent } from './types.js';
+export interface WebhookNotifierOptions {
+    url: string;
+    headers?: Record<string, string>;
+    /** Override fetch (for testing). */
+    fetch?: typeof fetch;
+    /** Callback on non-2xx, network error, or timeout. */
+    onError?: (err: unknown, event: NotificationEvent) => void;
+    /** Request timeout in ms. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export declare function webhookNotifier(options: WebhookNotifierOptions): Notifier;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/notify/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/notify/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3D,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,QAAQ,CA4BzE"}

package/dist/notify/webhook.js

@@ -0,0 +1,37 @@
+/**
+ * webhookNotifier — POSTs notification events as JSON to a URL.
+ * SPEC §6.3.
+ *
+ * Failures are reported via the optional `onError` callback; they do NOT
+ * throw, because notifier failures must never block the press/clear flow
+ * the notification accompanies.
+ */
+const DEFAULT_TIMEOUT_MS = 5000;
+export function webhookNotifier(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    return {
+        notify: async (event) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            try {
+                const resp = await fetchImpl(options.url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        ...(options.headers ?? {}),
+                    },
+                    body: JSON.stringify(event),
+                    signal: controller.signal,
+                });
+                if (!resp.ok) {
+                    options.onError?.(new Error(`webhook_status_${resp.status}`), event);
+                }
+            }
+            catch (err) {
+                options.onError?.(err, event);
+            }
+            clearTimeout(timer);
+        },
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/dist/notify/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/notify/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACzC,OAAO;QACL,MAAM,EAAE,KAAK,EAAE,KAAwB,EAAiB,EAAE;YACxD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,OAAO,CAAC,SAAS,IAAI,kBAAkB,CACxC,CAAC;YACF,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE;oBACxC,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE;wBACP,cAAc,EAAE,kBAAkB;wBAClC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;qBAC3B;oBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;oBAC3B,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAC;gBACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;oBACb,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAChC,CAAC;YACD,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/policy/attribution.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Model-attribution path rendering + glob matching. SPEC §3 extension (v0.7+).
+ *
+ * A {@link ModelAttribution} renders to a 4-segment path:
+ *
+ *     surface / aggregator / provider / id
+ *
+ * Missing segments render as `'*'`. Examples:
+ *
+ *     { provider: 'Anthropic', id: 'claude-opus-4.5' }
+ *       →  "* /* /Anthropic/claude-opus-4.5"
+ *
+ *     { surface: 'FlowDot', aggregator: 'RedPill',
+ *       provider: 'Anthropic', id: 'claude-opus-4.5' }
+ *       →  "FlowDot/RedPill/Anthropic/claude-opus-4.5"
+ *
+ * Pattern matching is **flat-glob**: `*` matches any run of characters
+ * including `/`. This lets simple substring-style patterns like
+ * `*claude-opus*` match the rendered path regardless of which provider,
+ * aggregator, or surface issued the call. Authors who want to constrain a
+ * specific segment write the slashes explicitly:
+ *
+ *     "* /RedPill/* /*"           → anything routed through RedPill
+ *     "FlowDot/* /Anthropic/*"    → any Anthropic model from FlowDot, any aggregator
+ *     "* /* /Anthropic/claude-*-4.5*"  → any claude-*-4.5* model from Anthropic
+ *     "*claude-opus*"              → any claude-opus model anywhere
+ *
+ * Character classes (`[abc]`, `[!abc]`) and single-char wildcards (`?`) are
+ * also supported — same semantics as `policy/evaluator.ts:globMatch` but
+ * without the segment-bound restriction (since flat-glob has no segments).
+ */
+import type { ModelAttribution } from '../types.js';
+/**
+ * The placeholder used for missing segments. Chosen so a wildcard pattern
+ * like `* /* /Anthropic/*` still matches an attribution missing both surface
+ * and aggregator.
+ */
+export declare const ATTRIBUTION_MISSING_SEGMENT = "*";
+/**
+ * Render a {@link ModelAttribution} as a 4-segment path. Missing fields
+ * become `'*'`. The path never contains an empty segment.
+ */
+export declare function renderAttributionPath(attribution: ModelAttribution): string;
+/**
+ * Test whether a pattern matches the rendered attribution path.
+ *
+ * Pattern syntax (flat-glob):
+ *   `*`     — any run of characters, including `/`
+ *   `?`     — exactly one character (including `/`)
+ *   `[seq]` — character class
+ *   `[!seq]` — negated character class
+ *
+ * The pattern is anchored: it matches the full path, not a prefix.
+ */
+export declare function matchAttributionPath(pattern: string, attribution: ModelAttribution): boolean;
+/**
+ * Pattern matching against a raw rendered path string. Exposed for
+ * `PolicyEvaluator` and for testing.
+ */
+export declare function flatGlobMatch(pattern: string, value: string): boolean;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/policy/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/policy/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,CAI3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAE5F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/policy/attribution.js

@@ -0,0 +1,116 @@
+/**
+ * Model-attribution path rendering + glob matching. SPEC §3 extension (v0.7+).
+ *
+ * A {@link ModelAttribution} renders to a 4-segment path:
+ *
+ *     surface / aggregator / provider / id
+ *
+ * Missing segments render as `'*'`. Examples:
+ *
+ *     { provider: 'Anthropic', id: 'claude-opus-4.5' }
+ *       →  "* /* /Anthropic/claude-opus-4.5"
+ *
+ *     { surface: 'FlowDot', aggregator: 'RedPill',
+ *       provider: 'Anthropic', id: 'claude-opus-4.5' }
+ *       →  "FlowDot/RedPill/Anthropic/claude-opus-4.5"
+ *
+ * Pattern matching is **flat-glob**: `*` matches any run of characters
+ * including `/`. This lets simple substring-style patterns like
+ * `*claude-opus*` match the rendered path regardless of which provider,
+ * aggregator, or surface issued the call. Authors who want to constrain a
+ * specific segment write the slashes explicitly:
+ *
+ *     "* /RedPill/* /*"           → anything routed through RedPill
+ *     "FlowDot/* /Anthropic/*"    → any Anthropic model from FlowDot, any aggregator
+ *     "* /* /Anthropic/claude-*-4.5*"  → any claude-*-4.5* model from Anthropic
+ *     "*claude-opus*"              → any claude-opus model anywhere
+ *
+ * Character classes (`[abc]`, `[!abc]`) and single-char wildcards (`?`) are
+ * also supported — same semantics as `policy/evaluator.ts:globMatch` but
+ * without the segment-bound restriction (since flat-glob has no segments).
+ */
+/**
+ * The placeholder used for missing segments. Chosen so a wildcard pattern
+ * like `* /* /Anthropic/*` still matches an attribution missing both surface
+ * and aggregator.
+ */
+export const ATTRIBUTION_MISSING_SEGMENT = '*';
+/**
+ * Render a {@link ModelAttribution} as a 4-segment path. Missing fields
+ * become `'*'`. The path never contains an empty segment.
+ */
+export function renderAttributionPath(attribution) {
+    const surface = attribution.surface ?? ATTRIBUTION_MISSING_SEGMENT;
+    const aggregator = attribution.aggregator ?? ATTRIBUTION_MISSING_SEGMENT;
+    return `${surface}/${aggregator}/${attribution.provider}/${attribution.id}`;
+}
+/**
+ * Test whether a pattern matches the rendered attribution path.
+ *
+ * Pattern syntax (flat-glob):
+ *   `*`     — any run of characters, including `/`
+ *   `?`     — exactly one character (including `/`)
+ *   `[seq]` — character class
+ *   `[!seq]` — negated character class
+ *
+ * The pattern is anchored: it matches the full path, not a prefix.
+ */
+export function matchAttributionPath(pattern, attribution) {
+    return flatGlobMatch(pattern, renderAttributionPath(attribution));
+}
+/**
+ * Pattern matching against a raw rendered path string. Exposed for
+ * `PolicyEvaluator` and for testing.
+ */
+export function flatGlobMatch(pattern, value) {
+    return flatGlobToRegExp(pattern).test(value);
+}
+function flatGlobToRegExp(pattern) {
+    let out = '^';
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === '*') {
+            out += '.*';
+            i++;
+        }
+        else if (c === '?') {
+            out += '.';
+            i++;
+        }
+        else if (c === '[') {
+            let end = i + 1;
+            let negate = false;
+            if (pattern[end] === '!') {
+                negate = true;
+                end++;
+            }
+            let body = '';
+            while (end < pattern.length && pattern[end] !== ']') {
+                body += pattern[end];
+                end++;
+            }
+            if (end >= pattern.length) {
+                out += '\\[';
+                i++;
+            }
+            else {
+                out += '[' + (negate ? '^' : '') + escapeForCharClass(body) + ']';
+                i = end + 1;
+            }
+        }
+        else {
+            out += escapeRegex(c);
+            i++;
+        }
+    }
+    out += '$';
+    return new RegExp(out);
+}
+function escapeRegex(c) {
+    return /[\\^$.*+?()[\]{}|]/.test(c) ? '\\' + c : c;
+}
+function escapeForCharClass(body) {
+    return body.replace(/[\\\]]/g, (m) => '\\' + m);
+}
+//# sourceMappingURL=attribution.js.map

package/dist/policy/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/policy/attribution.ts"],"names":[],"mappings":"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"}

package/dist/policy/evaluator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * PolicyEvaluator — resolution order + wildcards. SPEC §3.3, §3.4.
+ *
+ * Resolution order:
+ *   1. banned (forever-deny) exact match
+ *   2. banned wildcard match
+ *   3. forever-allow exact match
+ *   4. forever-allow wildcard match
+ *   5. session-allow exact match
+ *   6. session-allow wildcard match
+ *   7. once-allow exact match (rare — `once` is normally not persisted but
+ *      can appear if a runtime queries with a transient rule loaded)
+ *   8. once-allow wildcard match
+ *   9. defaults.scope if not 'prompt'
+ *  10. 'prompt' (consult gate)
+ *
+ * Banned-beats-allow at every layer: a `scope: banned` rule cannot be
+ * overridden by an allow rule at any other scope.
+ */
+import type { ModelAttribution } from '../types.js';
+import type { Policy, PolicyEvaluation, PolicyScope } from './types.js';
+export declare class PolicyEvaluator {
+    private readonly policy;
+    constructor(policy: Policy);
+    /** Evaluate a tool name (optionally with model attribution for `when` rules). */
+    evaluate(toolName: string, model?: ModelAttribution): PolicyEvaluation;
+    /** Helper for tests / debugging. */
+    rankFor(scope: PolicyScope): number;
+    private firstMatch;
+}
+/**
+ * Minimal fnmatch-equivalent. Supports `*` (any sequence), `?` (one char),
+ * and `[seq]` / `[!seq]` character classes.
+ */
+export declare function globMatch(pattern: string, name: string): boolean;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/policy/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/policy/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AASpF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAI1B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,gBAAgB;IAkEtE,oCAAoC;IACpC,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;IAMnC,OAAO,CAAC,UAAU;CAsBnB;AAsCD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhE"}

package/dist/policy/evaluator.js

@@ -0,0 +1,211 @@
+/**
+ * PolicyEvaluator — resolution order + wildcards. SPEC §3.3, §3.4.
+ *
+ * Resolution order:
+ *   1. banned (forever-deny) exact match
+ *   2. banned wildcard match
+ *   3. forever-allow exact match
+ *   4. forever-allow wildcard match
+ *   5. session-allow exact match
+ *   6. session-allow wildcard match
+ *   7. once-allow exact match (rare — `once` is normally not persisted but
+ *      can appear if a runtime queries with a transient rule loaded)
+ *   8. once-allow wildcard match
+ *   9. defaults.scope if not 'prompt'
+ *  10. 'prompt' (consult gate)
+ *
+ * Banned-beats-allow at every layer: a `scope: banned` rule cannot be
+ * overridden by an allow rule at any other scope.
+ */
+import { matchAttributionPath } from './attribution.js';
+const RANK = {
+    banned: 0,
+    forever: 1,
+    session: 2,
+    once: 3,
+};
+export class PolicyEvaluator {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /** Evaluate a tool name (optionally with model attribution for `when` rules). */
+    evaluate(toolName, model) {
+        // Walk rules in resolution order. We sort once on construction to make
+        // multiple evaluations cheap, but for code simplicity we do it per-call.
+        const banned = this.firstMatch(toolName, (r) => r.scope === 'banned' && whenMatches(r, model));
+        if (banned !== null) {
+            return {
+                decision: 'deny',
+                matchedRule: banned.rule,
+                matchedAt: banned.matchedAt,
+                scope: 'banned',
+            };
+        }
+        // Walk allow scopes in order forever > session > once.
+        for (const scope of ['forever', 'session', 'once']) {
+            const m = this.firstMatch(toolName, (r) => r.scope === scope && effectiveDecision(r) === 'allow' && whenMatches(r, model));
+            if (m !== null) {
+                return {
+                    decision: 'allow',
+                    matchedRule: m.rule,
+                    matchedAt: m.matchedAt,
+                    scope,
+                };
+            }
+            // A deny at this scope also short-circuits (though uncommon outside `banned`).
+            const denyAt = this.firstMatch(toolName, (r) => r.scope === scope && effectiveDecision(r) === 'deny' && whenMatches(r, model));
+            if (denyAt !== null) {
+                return {
+                    decision: 'deny',
+                    matchedRule: denyAt.rule,
+                    matchedAt: denyAt.matchedAt,
+                    scope,
+                };
+            }
+        }
+        // Fall back to defaults.
+        const d = this.policy.defaults;
+        if (d.scope === 'prompt') {
+            return {
+                decision: 'prompt',
+                matchedRule: undefined,
+                matchedAt: 'default',
+                scope: 'prompt',
+            };
+        }
+        const decision = d.decision ?? (d.scope === 'banned' ? 'deny' : 'allow');
+        return {
+            decision,
+            matchedRule: undefined,
+            matchedAt: 'default',
+            scope: d.scope,
+        };
+    }
+    /** Helper for tests / debugging. */
+    rankFor(scope) {
+        return RANK[scope];
+    }
+    // ---- internal --------------------------------------------------------------
+    firstMatch(toolName, pred) {
+        // Exact match: rule.tool equals toolName (and `pred` holds). Category
+        // matches (`category:<name>` form) also flow through here — the prefix is
+        // just a naming convention. `matchedAt: 'category'` is reserved for a
+        // future wildcard-category form not yet specified.
+        for (const rule of this.policy.rules) {
+            if (rule.tool === toolName && pred(rule)) {
+                return { rule, matchedAt: 'exact' };
+            }
+        }
+        // Wildcard match (declaration order wins among multiple matches).
+        for (const rule of this.policy.rules) {
+            if (rule.tool === toolName)
+                continue; // already handled
+            if (containsGlobChars(rule.tool) && globMatch(rule.tool, toolName) && pred(rule)) {
+                return { rule, matchedAt: 'wildcard' };
+            }
+        }
+        return null;
+    }
+}
+function effectiveDecision(rule) {
+    /* c8 ignore start */
+    if (rule.scope === 'banned')
+        return 'deny';
+    /* c8 ignore stop */
+    return rule.decision ?? 'allow';
+}
+/**
+ * Returns true iff the rule's `when` clause is satisfied by the given model.
+ * Rules without `when` always match. Glob support: `*`, `?`, `[seq]`.
+ *
+ * If `when` requires a model attribute but no model is supplied, the rule
+ * fails to match (defensive — model-conditional rules SHOULD NOT fire
+ * unconditionally).
+ */
+function whenMatches(rule, model) {
+    if (!rule.when)
+        return true;
+    if (rule.when['model.provider'] !== undefined) {
+        if (!model)
+            return false;
+        if (!globMatch(rule.when['model.provider'], model.provider))
+            return false;
+    }
+    if (rule.when['model.id'] !== undefined) {
+        if (!model)
+            return false;
+        if (!globMatch(rule.when['model.id'], model.id))
+            return false;
+    }
+    if (rule.when.attribution_path !== undefined) {
+        if (!model)
+            return false;
+        if (!matchAttributionPath(rule.when.attribution_path, model))
+            return false;
+    }
+    return true;
+}
+function containsGlobChars(s) {
+    return s.includes('*') || s.includes('?') || s.includes('[');
+}
+/**
+ * Minimal fnmatch-equivalent. Supports `*` (any sequence), `?` (one char),
+ * and `[seq]` / `[!seq]` character classes.
+ */
+export function globMatch(pattern, name) {
+    const re = globToRegExp(pattern);
+    return re.test(name);
+}
+function globToRegExp(pattern) {
+    let out = '^';
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === '*') {
+            out += '.*';
+            i++;
+        }
+        else if (c === '?') {
+            out += '.';
+            i++;
+        }
+        else if (c === '[') {
+            // Character class
+            let end = i + 1;
+            let negate = false;
+            if (pattern[end] === '!') {
+                negate = true;
+                end++;
+            }
+            let body = '';
+            while (end < pattern.length && pattern[end] !== ']') {
+                body += pattern[end];
+                end++;
+            }
+            if (end >= pattern.length) {
+                // unmatched '[' — treat literally.
+                out += '\\[';
+                i++;
+            }
+            else {
+                out += '[' + (negate ? '^' : '') + escapeForCharClass(body) + ']';
+                i = end + 1;
+            }
+        }
+        else {
+            out += escapeRegex(c);
+            i++;
+        }
+    }
+    out += '$';
+    return new RegExp(out);
+}
+function escapeRegex(c) {
+    return /[\\^$.*+?()[\]{}|]/.test(c) ? '\\' + c : c;
+}
+function escapeForCharClass(body) {
+    // Inside a char class, escape `]` and `\` only.
+    return body.replace(/[\\\]]/g, (m) => '\\' + m);
+}
+//# sourceMappingURL=evaluator.js.map