@codebam/jev-guardrails 0.1.0

package/dist/openrouter.js

@@ -0,0 +1,205 @@
+/** Default endpoint. */
+export const OPENROUTER_DECISIONS_ENDPOINT = 'https://openrouter.ai/api/alpha/decisions';
+/** Default OpenRouter model alias for the latest Jev. */
+export const OPENROUTER_DEFAULT_MODEL = '~typesafe/jev-latest';
+/** Friendly model names mapped to OpenRouter slugs. */
+const OPENROUTER_MODEL_ALIASES = {
+    'jev-latest': OPENROUTER_DEFAULT_MODEL,
+    'typesafe/jev-latest': OPENROUTER_DEFAULT_MODEL,
+    '~typesafe/jev-latest': OPENROUTER_DEFAULT_MODEL,
+    'jev-1.13': 'typesafe/jev-1.13',
+    'typesafe/jev-1.13': 'typesafe/jev-1.13',
+};
+/** Error raised for a non-2xx OpenRouter response after retries. */
+export class OpenRouterError extends Error {
+    status;
+    body;
+    constructor(status, message, body = '') {
+        super(message);
+        this.name = 'OpenRouterError';
+        this.status = status;
+        this.body = body;
+    }
+}
+const DEFAULT_RETRY = {
+    maxRetries: 2,
+    backoffInitialMs: 500,
+    backoffMaxMs: 5000,
+    backoffJitter: 0.25,
+    httpStatuses: new Set([408, 409, 425, 429, 500, 502, 503, 504, 529]),
+    respectRetryAfter: true,
+    maxRetryAfterMs: 60000,
+    apiConnectionError: true,
+    apiTimeoutError: true,
+};
+/** Resolve a friendly Jev name to an OpenRouter model slug. */
+export function normalizeOpenRouterModel(model) {
+    const trimmed = model?.trim() ?? '';
+    if (trimmed.length === 0)
+        return OPENROUTER_DEFAULT_MODEL;
+    const alias = OPENROUTER_MODEL_ALIASES[trimmed.toLowerCase()];
+    if (alias !== undefined)
+        return alias;
+    if (trimmed.includes('/'))
+        return trimmed;
+    return `typesafe/${trimmed}`;
+}
+/** Resolve a caller base URL to the exact Decisions endpoint. */
+export function resolveOpenRouterEndpoint(baseURL) {
+    const trimmed = baseURL?.trim().replace(/\/+$/, '') ?? '';
+    if (trimmed.length === 0)
+        return OPENROUTER_DECISIONS_ENDPOINT;
+    if (trimmed.endsWith('/decisions'))
+        return trimmed;
+    if (trimmed.endsWith('/api/alpha'))
+        return `${trimmed}/decisions`;
+    if (!/\/api\//.test(trimmed))
+        return `${trimmed}/api/alpha/decisions`;
+    return trimmed;
+}
+/** OpenRouter Decisions transport implementing the library's `JevTransport`. */
+export class OpenRouterDecisionsTransport {
+    endpoint;
+    model;
+    apiKey;
+    fetchImpl;
+    retry;
+    sessionId;
+    headers;
+    constructor(options) {
+        if (options.apiKey.trim().length === 0) {
+            throw new OpenRouterError(401, 'OpenRouter API key is missing');
+        }
+        this.endpoint = resolveOpenRouterEndpoint(options.baseURL);
+        this.model = options.model?.trim() ?? OPENROUTER_DEFAULT_MODEL;
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.retry = { ...DEFAULT_RETRY, ...options.retry, httpStatuses: options.retry?.httpStatuses ?? DEFAULT_RETRY.httpStatuses };
+        this.sessionId = options.sessionId;
+        this.headers = {
+            ...(options.referer !== undefined ? { 'HTTP-Referer': options.referer } : {}),
+            ...(options.title !== undefined ? { 'X-Title': options.title } : {}),
+            ...(options.headers ?? {}),
+        };
+    }
+    /** Submit one Decisions request and return the normalized response. */
+    async systemOne(request, options = {}) {
+        const model = normalizeOpenRouterModel(request.model ?? this.model);
+        const body = {
+            model,
+            state: request.state,
+            questions: request.questions,
+        };
+        if (this.sessionId !== undefined)
+            body.session_id = this.sessionId;
+        let attempt = 0;
+        for (;;) {
+            const response = await this.fetchOnce(body, options);
+            if (response.ok) {
+                return (await response.json());
+            }
+            const text = await response.text().catch(() => '');
+            if (attempt < this.retry.maxRetries && this.retry.httpStatuses.has(response.status)) {
+                await sleep(this.retryDelay(attempt, response.headers));
+                attempt += 1;
+                continue;
+            }
+            throw new OpenRouterError(response.status, describeError(response.status, text), text);
+        }
+    }
+    async fetchOnce(body, options) {
+        try {
+            return await this.fetchImpl(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.apiKey}`,
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                    ...this.headers,
+                    ...(options.headers ?? {}),
+                },
+                body: JSON.stringify(body),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted || (error instanceof Error && error.name === 'AbortError'))
+                throw error;
+            const retry = this.retry;
+            if (retry.apiConnectionError) {
+                // One bounded connection-retry loop; the abort check above keeps
+                // cancellation immediate.
+                let attempt = 0;
+                while (attempt < retry.maxRetries) {
+                    await sleep(this.retryDelay(attempt));
+                    attempt += 1;
+                    try {
+                        return await this.fetchImpl(this.endpoint, {
+                            method: 'POST',
+                            headers: {
+                                authorization: `Bearer ${this.apiKey}`,
+                                'content-type': 'application/json',
+                                accept: 'application/json',
+                                ...this.headers,
+                                ...(options.headers ?? {}),
+                            },
+                            body: JSON.stringify(body),
+                            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                        });
+                    }
+                    catch (retryError) {
+                        if (options.signal?.aborted || (retryError instanceof Error && retryError.name === 'AbortError'))
+                            throw retryError;
+                    }
+                }
+            }
+            throw error;
+        }
+    }
+    retryDelay(attempt, headers) {
+        if (headers !== undefined && this.retry.respectRetryAfter) {
+            const retryAfterMs = parseRetryAfter(headers.get('retry-after'), headers.get('retry-after-ms'));
+            if (retryAfterMs !== undefined)
+                return Math.min(retryAfterMs, this.retry.maxRetryAfterMs);
+        }
+        const base = Math.min(this.retry.backoffInitialMs * 2 ** attempt, this.retry.backoffMaxMs);
+        const jitter = base * this.retry.backoffJitter * Math.random();
+        return Math.max(0, Math.round(base - jitter));
+    }
+}
+/** Build an OpenRouter Decisions transport. */
+export function createOpenRouterTransport(options) {
+    return new OpenRouterDecisionsTransport(options);
+}
+function parseRetryAfter(secondsHeader, msHeader) {
+    if (msHeader !== null) {
+        const ms = Number(msHeader);
+        if (Number.isFinite(ms) && ms >= 0)
+            return ms;
+    }
+    if (secondsHeader !== null) {
+        const seconds = Number(secondsHeader);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return seconds * 1000;
+        const date = Date.parse(secondsHeader);
+        if (!Number.isNaN(date))
+            return Math.max(0, date - Date.now());
+    }
+    return undefined;
+}
+function describeError(status, text) {
+    try {
+        const parsed = JSON.parse(text);
+        const message = parsed.error?.message ?? parsed.message;
+        if (typeof message === 'string')
+            return `OpenRouter Decisions request failed (${status}): ${message}`;
+    }
+    catch {
+        // Not JSON; fall through to the raw text.
+    }
+    return `OpenRouter Decisions request failed (${status})${text.length > 0 ? `: ${text.slice(0, 300)}` : ''}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/openrouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../src/openrouter.ts"],"names":[],"mappings":"AAaA,wBAAwB;AACxB,MAAM,CAAC,MAAM,6BAA6B,GAAG,2CAA2C,CAAA;AAExF,yDAAyD;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAA;AAE9D,uDAAuD;AACvD,MAAM,wBAAwB,GAA2B;IACvD,YAAY,EAAE,wBAAwB;IACtC,qBAAqB,EAAE,wBAAwB;IAC/C,sBAAsB,EAAE,wBAAwB;IAChD,UAAU,EAAE,mBAAmB;IAC/B,mBAAmB,EAAE,mBAAmB;CACzC,CAAA;AAED,oEAAoE;AACpE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAQ;IACd,IAAI,CAAQ;IAErB,YAAY,MAAc,EAAE,OAAe,EAAE,IAAI,GAAG,EAAE;QACpD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAwBD,MAAM,aAAa,GAAgB;IACjC,UAAU,EAAE,CAAC;IACb,gBAAgB,EAAE,GAAG;IACrB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,iBAAiB,EAAE,IAAI;IACvB,eAAe,EAAE,KAAK;IACtB,kBAAkB,EAAE,IAAI;IACxB,eAAe,EAAE,IAAI;CACtB,CAAA;AAED,+DAA+D;AAC/D,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,wBAAwB,CAAA;IACzD,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IAC7D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACrC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAA;IACzC,OAAO,YAAY,OAAO,EAAE,CAAA;AAC9B,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,MAAM,OAAO,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,CAAA;IACzD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,6BAA6B,CAAA;IAC9D,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,OAAO,CAAA;IAClD,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,GAAG,OAAO,YAAY,CAAA;IACjE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,OAAO,sBAAsB,CAAA;IACrE,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,gFAAgF;AAChF,MAAM,OAAO,4BAA4B;IACtB,QAAQ,CAAQ;IAChB,KAAK,CAAQ;IACb,MAAM,CAAQ;IACd,SAAS,CAAO;IAChB,KAAK,CAAa;IAClB,SAAS,CAAoB;IAC7B,OAAO,CAAwB;IAEhD,YAAY,OAAmC;QAC7C,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,+BAA+B,CAAC,CAAA;QACjE,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC1D,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,wBAAwB,CAAA;QAC9D,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACnE,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,KAAK,EAAE,YAAY,IAAI,aAAa,CAAC,YAAY,EAAE,CAAA;QAC5H,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;QAClC,IAAI,CAAC,OAAO,GAAG;YACb,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7E,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;SAC3B,CAAA;IACH,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,SAAS,CACb,OAA4B,EAC5B,UAA0B,EAAE;QAE5B,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;QACnE,MAAM,IAAI,GAA4B;YACpC,KAAK;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAA;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,CAAA;QAElE,IAAI,OAAO,GAAG,CAAC,CAAA;QACf,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YACpD,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAuB,CAAA;YACtD,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;YAClD,IAAI,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACpF,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;gBACvD,OAAO,IAAI,CAAC,CAAA;gBACZ,SAAQ;YACV,CAAC;YACD,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;QACxF,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAA6B,EAAE,OAAuB;QAC5E,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACzC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;oBACtC,cAAc,EAAE,kBAAkB;oBAClC,MAAM,EAAE,kBAAkB;oBAC1B,GAAG,IAAI,CAAC,OAAO;oBACf,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;iBAC3B;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpE,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;gBAAE,MAAM,KAAK,CAAA;YACnG,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;YACxB,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC;gBAC7B,iEAAiE;gBACjE,0BAA0B;gBAC1B,IAAI,OAAO,GAAG,CAAC,CAAA;gBACf,OAAO,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;oBAClC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;oBACrC,OAAO,IAAI,CAAC,CAAA;oBACZ,IAAI,CAAC;wBACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE;4BACzC,MAAM,EAAE,MAAM;4BACd,OAAO,EAAE;gCACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gCACtC,cAAc,EAAE,kBAAkB;gCAClC,MAAM,EAAE,kBAAkB;gCAC1B,GAAG,IAAI,CAAC,OAAO;gCACf,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;6BAC3B;4BACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;4BAC1B,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;yBACpE,CAAC,CAAA;oBACJ,CAAC;oBAAC,OAAO,UAAU,EAAE,CAAC;wBACpB,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,UAAU,YAAY,KAAK,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY,CAAC;4BAAE,MAAM,UAAU,CAAA;oBACpH,CAAC;gBACH,CAAC;YACH,CAAC;YACD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,OAAe,EAAE,OAAiB;QACnD,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC1D,MAAM,YAAY,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAA;YAC/F,IAAI,YAAY,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAA;QAC3F,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,CAAC,IAAI,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;QAC1F,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;QAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAA;IAC/C,CAAC;CACF;AAED,+CAA+C;AAC/C,MAAM,UAAU,yBAAyB,CAAC,OAAmC;IAC3E,OAAO,IAAI,4BAA4B,CAAC,OAAO,CAAC,CAAA;AAClD,CAAC;AAED,SAAS,eAAe,CAAC,aAA4B,EAAE,QAAuB;IAC5E,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC3B,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,EAAE,CAAA;IAC/C,CAAC;IACD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,CAAA;QACrC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC;YAAE,OAAO,OAAO,GAAG,IAAI,CAAA;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAChE,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAS,aAAa,CAAC,MAAc,EAAE,IAAY;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyD,CAAA;QACvF,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAA;QACvD,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,wCAAwC,MAAM,MAAM,OAAO,EAAE,CAAA;IACvG,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;IACD,OAAO,wCAAwC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC7G,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC"}

package/dist/policies.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Probabilities to product actions.
+ *
+ * TypeSafe answers the questions; this module owns the decision. The same
+ * answers under a different policy are a different product, so every policy
+ * field is explicit and overridable.
+ *
+ * @module @codebam/jev-guardrails/policies
+ */
+import type { Battery, GuardAction, GuardPolicyInput, GuardSide, ResolvedGuardPolicy } from './types.js';
+/** Highest precedence first. `support` routes to a crisis path, not a refusal. */
+export declare const DEFAULT_PRECEDENCE: readonly GuardAction[];
+/** Default action map for the text-input battery. */
+export declare const INPUT_ACTIONS: Record<string, GuardAction | null>;
+/** Default action map for the model-output battery. */
+export declare const OUTPUT_ACTIONS: Record<string, GuardAction | null>;
+/** Default action map for untrusted text that entered the model context. */
+export declare const OBSERVATION_ACTIONS: Record<string, GuardAction | null>;
+/** Default action map for a proposed agent action. */
+export declare const ACTION_ACTIONS: Record<string, GuardAction | null>;
+/** Default action map per side. */
+export declare const DEFAULT_ACTIONS: Record<GuardSide, Record<string, GuardAction | null>>;
+/** Merge a caller policy over a battery's defaults. */
+export declare function resolvePolicy(side: GuardSide, overrides: GuardPolicyInput | undefined, battery: Battery): ResolvedGuardPolicy;
+/** One triggered reason and its candidate action. */
+export interface TriggeredHazard {
+    name: string;
+    probability: number;
+    action: GuardAction;
+    reason: string;
+}
+/** The complete route recommendation from one set of hazard probabilities. */
+export interface RouteResult {
+    action: GuardAction;
+    reasons: string[];
+    triggered: TriggeredHazard[];
+    /** True when a severity score upgraded at least one review to a block. */
+    severityEscalated: boolean;
+}
+/** The pure routing function: hazards + severity + policy -> one action. */
+export declare function routePolicy(input: {
+    hazards: Record<string, number>;
+    severity?: number;
+    policy: ResolvedGuardPolicy;
+}): RouteResult;
+/** A concise, model-readable summary of the top hazards in a decision. */
+export declare function summarizeHazards(hazards: Record<string, number>, labels?: Record<string, string>): string;
+//# sourceMappingURL=policies.d.ts.map

package/dist/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,mBAAmB,EACpB,MAAM,YAAY,CAAA;AAGnB,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAA4C,CAAA;AAEjG,qDAAqD;AACrD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAK5D,CAAA;AAED,uDAAuD;AACvD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAK7D,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAOlE,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAQ7D,CAAA;AAED,mCAAmC;AACnC,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC,CAKjF,CAAA;AAED,uDAAuD;AACvD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,OAAO,EAAE,OAAO,GACf,mBAAmB,CA8BrB;AAgBD,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,SAAS,EAAE,eAAe,EAAE,CAAA;IAC5B,0EAA0E;IAC1E,iBAAiB,EAAE,OAAO,CAAA;CAC3B;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,mBAAmB,CAAA;CAC5B,GAAG,WAAW,CAiEd;AAOD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CASR"}

package/dist/policies.js

@@ -0,0 +1,167 @@
+import { formatP } from './util.js';
+/** Highest precedence first. `support` routes to a crisis path, not a refusal. */
+export const DEFAULT_PRECEDENCE = ['support', 'block', 'review', 'allow'];
+/** Default action map for the text-input battery. */
+export const INPUT_ACTIONS = {
+    jailbreak: 'block',
+    harmful_request: 'block',
+    medical_advice: 'review',
+    self_harm: 'support',
+};
+/** Default action map for the model-output battery. */
+export const OUTPUT_ACTIONS = {
+    broke_policy: 'block',
+    harmful_request: 'block',
+    medical_advice: 'review',
+    self_harm: 'support',
+};
+/** Default action map for untrusted text that entered the model context. */
+export const OBSERVATION_ACTIONS = {
+    injection: 'block',
+    destructive: 'block',
+    exfiltration: 'block',
+    secrets: 'review',
+    hidden: 'review',
+    urgency: 'review',
+};
+/** Default action map for a proposed agent action. */
+export const ACTION_ACTIONS = {
+    destructive: 'block',
+    exfiltration: 'block',
+    remote_code: 'block',
+    weakens_security: 'block',
+    credential_access: 'review',
+    outside_scope: 'review',
+    consequential: 'review',
+};
+/** Default action map per side. */
+export const DEFAULT_ACTIONS = {
+    input: INPUT_ACTIONS,
+    output: OUTPUT_ACTIONS,
+    observation: OBSERVATION_ACTIONS,
+    action: ACTION_ACTIONS,
+};
+/** Merge a caller policy over a battery's defaults. */
+export function resolvePolicy(side, overrides, battery) {
+    const baseActions = battery.defaultActions ?? DEFAULT_ACTIONS[side];
+    const actions = { ...baseActions };
+    if (overrides?.actions) {
+        for (const [name, action] of Object.entries(overrides.actions))
+            actions[name] = action;
+    }
+    const precedence = overrides?.precedence ?? DEFAULT_PRECEDENCE;
+    if (precedence.length === 0)
+        throw new Error('jev-guardrails: policy precedence must not be empty');
+    const reviewThreshold = requireProbability(overrides?.reviewThreshold ?? 0.35, 'reviewThreshold');
+    const actionThreshold = requireProbability(overrides?.actionThreshold ?? 0.7, 'actionThreshold');
+    if (reviewThreshold > actionThreshold) {
+        throw new Error('jev-guardrails: reviewThreshold must be less than or equal to actionThreshold');
+    }
+    const severityReview = requireNonNegative(overrides?.severityReview ?? 1.25, 'severityReview');
+    const severityBlock = requireNonNegative(overrides?.severityBlock ?? 2.0, 'severityBlock');
+    if (severityReview > severityBlock) {
+        throw new Error('jev-guardrails: severityReview must be less than or equal to severityBlock');
+    }
+    return {
+        reviewThreshold,
+        actionThreshold,
+        severityReview,
+        severityBlock,
+        actions,
+        fallback: overrides?.fallback ?? 'review',
+        precedence,
+        failMode: overrides?.failMode ?? 'open',
+    };
+}
+function requireProbability(value, name) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`jev-guardrails: ${name} must be a probability between 0 and 1`);
+    }
+    return value;
+}
+function requireNonNegative(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`jev-guardrails: ${name} must be a non-negative number`);
+    }
+    return value;
+}
+/** The pure routing function: hazards + severity + policy -> one action. */
+export function routePolicy(input) {
+    const { hazards, severity, policy } = input;
+    const candidates = [];
+    for (const [name, rawProbability] of Object.entries(hazards)) {
+        const probability = Number.isFinite(rawProbability) ? rawProbability : 0;
+        const configured = policy.actions[name];
+        if (configured === null)
+            continue;
+        if (probability >= policy.actionThreshold) {
+            const action = configured ?? policy.fallback;
+            candidates.push({
+                name,
+                probability,
+                action,
+                reason: `${name} ${formatP(probability)} at or above action threshold -> ${action}`,
+            });
+        }
+        else if (probability >= policy.reviewThreshold) {
+            candidates.push({
+                name,
+                probability,
+                action: 'review',
+                reason: `${name} ${formatP(probability)} at or above review threshold -> review`,
+            });
+        }
+    }
+    let severityEscalated = false;
+    if (severity !== undefined && Number.isFinite(severity)) {
+        if (severity >= policy.severityBlock) {
+            for (const candidate of candidates) {
+                if (candidate.action === 'review') {
+                    candidate.action = 'block';
+                    candidate.reason = `${candidate.reason}; severity ${severity.toFixed(2)} escalated review to block`;
+                    severityEscalated = true;
+                }
+            }
+            const alreadyBlocking = candidates.some((candidate) => candidate.action === 'block');
+            if (!alreadyBlocking) {
+                candidates.push({
+                    name: 'severity',
+                    probability: 1,
+                    action: 'block',
+                    reason: `severity ${severity.toFixed(2)} at or above block threshold -> block`,
+                });
+            }
+        }
+        else if (severity >= policy.severityReview) {
+            candidates.push({
+                name: 'severity',
+                probability: 1,
+                action: 'review',
+                reason: `severity ${severity.toFixed(2)} at or above review threshold -> review`,
+            });
+        }
+    }
+    const action = policy.precedence.find((candidateAction) => candidates.some((candidate) => candidate.action === candidateAction)) ?? 'allow';
+    const reasons = candidates
+        .filter((candidate) => candidate.action === action || action === 'allow')
+        .map((candidate) => candidate.reason)
+        .sort((a, b) => actionRank(b, policy) - actionRank(a, policy));
+    return { action, reasons, triggered: candidates, severityEscalated };
+}
+function actionRank(reason, policy) {
+    const index = policy.precedence.findIndex((action) => reason.includes(`-> ${action}`));
+    return index === -1 ? 0 : policy.precedence.length - index;
+}
+/** A concise, model-readable summary of the top hazards in a decision. */
+export function summarizeHazards(hazards, labels = {}) {
+    const entries = Object.entries(hazards)
+        .filter(([, probability]) => Number.isFinite(probability))
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 2);
+    if (entries.length === 0)
+        return 'no hazard above threshold';
+    return entries
+        .map(([name, probability]) => `${labels[name] ?? name} ${formatP(probability)}`)
+        .join('; ');
+}
+//# sourceMappingURL=policies.js.map

package/dist/policies.js.map

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

package/dist/redact.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Secret redaction for state sent to Jev.
+ *
+ * Guardrail checks are most useful on realistic input, but prompts and tool
+ * arguments often carry credentials. The built-in rules preserve the *shape*
+ * that makes a credential dangerous (so the `secrets` and `exfiltration`
+ * questions still fire) while replacing the value itself.
+ *
+ * @module @codebam/jev-guardrails/redact
+ */
+import type { RedactionPattern, RedactorOptions } from './types.js';
+/** Built-in best-effort secret patterns. These are signals, not a scanner. */
+export declare const DEFAULT_SECRET_PATTERNS: RedactionPattern[];
+/** Redact known secret shapes from one string. */
+export declare function redactString(text: string, options?: RedactorOptions): string;
+/** Recursively redact every string in a JSON-like value, preserving its shape. */
+export declare function redactState<T>(state: T, options?: RedactorOptions): T;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGnE,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,EAwErD,CAAA;AASD,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAiBhF;AAKD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,eAAoB,GAAG,CAAC,CAEzE"}

package/dist/redact.js

@@ -0,0 +1,124 @@
+import { isRecord } from './util.js';
+/** Built-in best-effort secret patterns. These are signals, not a scanner. */
+export const DEFAULT_SECRET_PATTERNS = [
+    {
+        name: 'private-key',
+        pattern: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+        replacement: '[REDACTED:private-key]',
+    },
+    {
+        name: 'aws-access-key',
+        pattern: /\b(?:AKIA|ASIA|AROA|AIPA|ANPA|ANVA|APKA)[0-9A-Z]{16}\b/g,
+        replacement: '[REDACTED:aws-access-key]',
+    },
+    {
+        name: 'github-token',
+        pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+        replacement: '[REDACTED:github-token]',
+    },
+    {
+        name: 'github-pat',
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+        replacement: '[REDACTED:github-pat]',
+    },
+    {
+        name: 'slack-token',
+        pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+        replacement: '[REDACTED:slack-token]',
+    },
+    {
+        name: 'openai-key',
+        pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
+        replacement: '[REDACTED:api-key]',
+    },
+    {
+        name: 'anthropic-key',
+        pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+        replacement: '[REDACTED:api-key]',
+    },
+    {
+        name: 'google-api-key',
+        pattern: /\bAIza[0-9A-Za-z_-]{20,}\b/g,
+        replacement: '[REDACTED:api-key]',
+    },
+    {
+        name: 'stripe-key',
+        pattern: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+        replacement: '[REDACTED:stripe-key]',
+    },
+    {
+        name: 'jwt',
+        pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+        replacement: '[REDACTED:jwt]',
+    },
+    {
+        name: 'bearer-token',
+        pattern: /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{16,})\b/gi,
+        replacement: (_match, _scheme) => `Bearer [REDACTED:bearer-token]`,
+    },
+    {
+        name: 'basic-auth',
+        pattern: /\b(Basic\s+)([A-Za-z0-9+/=]{12,})\b/gi,
+        replacement: (_match, _scheme) => `Basic [REDACTED:basic-auth]`,
+    },
+    {
+        name: 'url-password',
+        pattern: /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:)([^\s/@]+)(@)/gi,
+        replacement: (_match, prefix, _password, suffix) => `${prefix}[REDACTED:url-password]${suffix}`,
+    },
+    {
+        name: 'assigned-secret',
+        pattern: /([A-Za-z0-9_.-]*(?:api[_-]?key|apikey|client[_-]?secret|secret|token|password|passwd|pwd|private[_-]?key))(\s*[:=]\s*)(["']?)([^\s"',;]{8,})(\3)/gi,
+        replacement: (_match, key, separator, quote, _value) => `${key}${separator}${quote}[REDACTED:assigned-secret]${quote}`,
+    },
+];
+function replacementFor(pattern) {
+    if (typeof pattern.replacement === 'function') {
+        return pattern.replacement;
+    }
+    return pattern.replacement ?? `[REDACTED:${pattern.name}]`;
+}
+/** Redact known secret shapes from one string. */
+export function redactString(text, options = {}) {
+    const patterns = [
+        ...(options.secrets === false ? [] : DEFAULT_SECRET_PATTERNS),
+        ...(options.extraPatterns ?? []),
+    ];
+    let output = text;
+    for (const rule of patterns) {
+        try {
+            const replacement = replacementFor(rule);
+            output = typeof replacement === 'string'
+                ? output.replace(rule.pattern, replacement)
+                : output.replace(rule.pattern, replacement);
+        }
+        catch {
+            // A misbehaving custom pattern must never break a safety check.
+        }
+    }
+    return output;
+}
+/** Object keys whose values are secrets even without a recognizable value shape. */
+const SENSITIVE_KEYS = /(?:^|[_-])(?:password|passwd|pwd|secret|token|api_?key|apikey|authorization|auth|cookie|private_?key|client_?secret|access_?key|session_?id)(?:$|[_-])/i;
+/** Recursively redact every string in a JSON-like value, preserving its shape. */
+export function redactState(state, options = {}) {
+    return redactValue(state, options);
+}
+function redactValue(value, options, key = '') {
+    if (typeof value === 'string') {
+        if (SENSITIVE_KEYS.test(key) && value.trim().length > 0 && !value.includes('[REDACTED:')) {
+            return '[REDACTED:assigned-secret]';
+        }
+        return redactString(value, options);
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => redactValue(entry, options, key));
+    if (isRecord(value)) {
+        const out = {};
+        for (const [entryKey, entry] of Object.entries(value))
+            out[entryKey] = redactValue(entry, options, entryKey);
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEpC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAuB;IACzD;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,mFAAmF;QAC5F,WAAW,EAAE,wBAAwB;KACtC;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,yDAAyD;QAClE,WAAW,EAAE,2BAA2B;KACzC;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,iCAAiC;QAC1C,WAAW,EAAE,yBAAyB;KACvC;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,mCAAmC;QAC5C,WAAW,EAAE,uBAAuB;KACrC;IACD;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,mCAAmC;QAC5C,WAAW,EAAE,wBAAwB;KACtC;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,sCAAsC;QAC/C,WAAW,EAAE,oBAAoB;KAClC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,gCAAgC;QACzC,WAAW,EAAE,oBAAoB;KAClC;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,6BAA6B;QACtC,WAAW,EAAE,oBAAoB;KAClC;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,+CAA+C;QACxD,WAAW,EAAE,uBAAuB;KACrC;IACD;QACE,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,iEAAiE;QAC1E,WAAW,EAAE,gBAAgB;KAC9B;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,4CAA4C;QACrD,WAAW,EAAE,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE,CAAC,gCAAgC;KAC3E;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,uCAAuC;QAChD,WAAW,EAAE,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE,CAAC,6BAA6B;KACxE;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,qDAAqD;QAC9D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAc,EAAE,SAAiB,EAAE,MAAc,EAAE,EAAE,CAAC,GAAG,MAAM,0BAA0B,MAAM,EAAE;KACxH;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,oJAAoJ;QAC7J,WAAW,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,SAAiB,EAAE,KAAa,EAAE,MAAc,EAAE,EAAE,CACrF,GAAG,GAAG,GAAG,SAAS,GAAG,KAAK,6BAA6B,KAAK,EAAE;KACjE;CACF,CAAA;AAED,SAAS,cAAc,CAAC,OAAyB;IAC/C,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QAC9C,OAAO,OAAO,CAAC,WAA+D,CAAA;IAChF,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,IAAI,aAAa,OAAO,CAAC,IAAI,GAAG,CAAA;AAC5D,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAA2B,EAAE;IACtE,MAAM,QAAQ,GAAG;QACf,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,uBAAuB,CAAC;QAC7D,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;KACjC,CAAA;IACD,IAAI,MAAM,GAAG,IAAI,CAAA;IACjB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;YACxC,MAAM,GAAG,OAAO,WAAW,KAAK,QAAQ;gBACtC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;gBAC3C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,oFAAoF;AACpF,MAAM,cAAc,GAAG,yJAAyJ,CAAA;AAEhL,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAI,KAAQ,EAAE,UAA2B,EAAE;IACpE,OAAO,WAAW,CAAC,KAAK,EAAE,OAAO,CAAM,CAAA;AACzC,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,OAAwB,EAAE,GAAG,GAAG,EAAE;IACrE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACzF,OAAO,4BAA4B,CAAA;QACrC,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAA;IACvF,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,GAAG,GAA4B,EAAE,CAAA;QACvC,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;QAC5G,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Human-readable and model-readable explanations for verdicts.
+ *
+ * Guardrail messages are themselves instructions to a model, so they are
+ * written to be short, specific, and non-negotiable: state the finding, name
+ * the consequence, and close the obvious workaround.
+ *
+ * @module @codebam/jev-guardrails/render
+ */
+import type { GuardVerdict } from './types.js';
+/** Fallback labels for every built-in hazard. */
+export declare const DEFAULT_HAZARD_LABELS: Record<string, string>;
+/** A verdict with or without its final `reason` field. */
+type VerdictView = Omit<GuardVerdict, 'reason'> & {
+    reason?: string;
+};
+/** One-line audit summary for logs and callbacks. */
+export declare function describeVerdict(verdict: VerdictView, labels?: Record<string, string>): string;
+/** Reason shown to the model when a tool call or prompt is denied. */
+export declare function modelFacingReason(verdict: VerdictView, labels?: Record<string, string>): string;
+/** Plugin-visible context attached to a conversation when input is flagged but allowed. */
+export declare function guardrailNotice(verdict: VerdictView, labels?: Record<string, string>): string;
+/** Steering message used when a model response is blocked or flagged. */
+export declare function correctionNotice(verdict: VerdictView, labels?: Record<string, string>): string;
+export {};
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAA;AAGzD,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBxD,CAAA;AAED,0DAA0D;AAC1D,KAAK,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AA0BrE,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAe7F;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAe/F;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI7F;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI9F"}