@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/guardrails/egress-urls.js

@@ -16,7 +16,7 @@
  */
 import { textForScan } from './serialize.js';
 function givenUrlSets() {
-    return { request: new Set(), tools: new Set() };
+    return { request: new Set(), tools: new Set(), own: new WeakSet() };
 }
 const RELATIVE_BASE = 'https://relative.invalid/';
 const RELATIVE_HOST = 'relative.invalid';
@@ -154,16 +154,16 @@ function addSeenUrls(seen, text) {
 }
 function addHistoryUrls(given, messages) {
     for (const message of messages) {
-        if (message.role === 'assistant')
+        if (message.role === 'assistant' || given.own.has(message))
             continue;
         addSeenUrls(message.role === 'tool' ? given.tools : given.request, textForScan(message).text);
     }
 }
 function addRequestUrls(given, request) {
     addSeenUrls(given.request, request.system);
-    addSeenUrls(given.request, textForScan(request.input).text);
+    if (!given.own.has(request.input))
+        addSeenUrls(given.request, textForScan(request.input).text);
     addHistoryUrls(given, request.history ?? []);
-    addHistoryUrls(given, request.continuation ?? []);
 }
 function isGiven(canonical, scope) {
     const { given } = scope;
@@ -211,7 +211,6 @@ function bareUrlLeaks(found, scope) {
         return false;
     return !(hosts.size === 1 && readings.some((url) => isGiven(url, scope)));
 }
-// ── Budget ───────────────────────────────────────────────────────────
 /**
  * Constructs overlap: a destination can hold further links, a tag further
  * tags, a `<style>` block further blocks, and each is decoded on its own. One
@@ -243,7 +242,6 @@ function indicesIn(from, to, at) {
             out.push(i);
     return out;
 }
-// ── Markdown ─────────────────────────────────────────────────────────
 /** A newline opening a blank line, or trailing space to the end: no bracket or code span reaches past one. */
 const PARAGRAPH_BREAK = /\n[ \t]*(?=\n|$)/g;
 const PARAGRAPH_BREAK_AT = /\n[ \t]*(?=\n|$)/y;
@@ -497,7 +495,6 @@ function bareLinkLeaks(text, scope, meter) {
     })
         .map((match) => ({ start: match.index, end: match.index + match[0].length }));
 }
-// ── HTML ─────────────────────────────────────────────────────────────
 const LT = 0x3c;
 const GT = 0x3e;
 const SLASH = 0x2f;
@@ -703,12 +700,9 @@ function tagLeaks(text, reader, scope, meter, from = 0, to = text.length) {
     }
     return spans;
 }
-// ── CSS ──────────────────────────────────────────────────────────────
 const CSS_NAME = /(?:[A-Za-z0-9_\-\u0080-￿]|\\(?:[0-9a-fA-F]{1,6}(?:\r\n|[ \t\n\r\f])?|[^\n\r\f0-9a-fA-F]))+/y;
-const CSS_STRING = {
-    '"': /(?:[^\x22\\\n\r\f]|\\(?:\r\n|[\s\S]))*/y,
-    "'": /(?:[^\x27\\\n\r\f]|\\(?:\r\n|[\s\S]))*/y,
-};
+const CSS_DOUBLE_QUOTED = /(?:[^\x22\\\n\r\f]|\\(?:\r\n|[\s\S]))*/y;
+const CSS_SINGLE_QUOTED = /(?:[^\x27\\\n\r\f]|\\(?:\r\n|[\s\S]))*/y;
 const CSS_URL_BODY = /(?:[^)\\]|\\[\s\S])*/y;
 /**
  * Every URL CSS could load, read as the CSS tokenizer reads it: each
@@ -726,7 +720,7 @@ function cssUrls(css) {
             i = close < 0 ? css.length : close + 2;
         }
         else if (char === '"' || char === "'") {
-            const string = CSS_STRING[char];
+            const string = char === '"' ? CSS_DOUBLE_QUOTED : CSS_SINGLE_QUOTED;
             string.lastIndex = i + 1;
             urls.push(unescapeCss(string.exec(css)[0]));
             i = string.lastIndex + 1;
@@ -781,7 +775,6 @@ function styleLeaks(text, scope, meter, from = 0, to = text.length) {
     }
     return spans;
 }
-// ── Checks ───────────────────────────────────────────────────────────
 /** `read`'s spans, sorted; all of `text` when reading it would decode past its cap. */
 function readFailingClosed(text, read) {
     try {
@@ -811,10 +804,9 @@ function linkLeakSpans(text, scope, skipImages) {
         ...tagLeaks(text, FOLLOWED, scope, meter),
     ]);
 }
-// ── Streaming ────────────────────────────────────────────────────────
 /**
  * A start tag as the tokenizer reads it, up to the `>` that ends it. Each
- * name, value and run of space is read one way only (the lookaheads end each
+ * name, value, and run of space is read one way only (the lookaheads end each
  * where the tokenizer does), so a tag that never ends fails in linear time.
  */
 const HTML_START_TAG = /<[A-Za-z][^\t\n\f\r />]*(?=[\t\n\f\r />])(?:[\t\n\f\r /]|[^\t\n\f\r />][^\t\n\f\r />=]*(?=[\t\n\f\r />=])[\t\n\f\r ]*(?![\t\n\f\r ])(?:=[\t\n\f\r ]*(?![\t\n\f\r ])(?:\x22[^\x22]*\x22|\x27[^\x27]*\x27|[^\t\n\f\r >\x22\x27][^\t\n\f\r >]*(?=[\t\n\f\r >])|(?=>))|(?!=)))*>/g;
@@ -866,7 +858,7 @@ function metered(reads) {
             test(match, reply, at) {
                 meter.cap = capFor(reply.length);
                 try {
-                    return read.match(match, reply, at, meter);
+                    return read.leaks(match, reply, at, meter);
                 }
                 catch (error) {
                     if (error instanceof Overspent)
@@ -894,13 +886,13 @@ function imageReadings(scope) {
     return metered([
         (reply, from, to, meter) => inlineLeaks(reply, imageOpeners(reply, from, to), scope, meter),
         {
-            match(match, reply, _at, meter) {
+            leaks(match, reply, _at, meter) {
                 const leaks = definitionLeaks(match, scope, meter).length > 0;
                 leakingDefinition ||= leaks;
                 return leaks && openerIn(reply);
             },
         },
-        { match: () => leakingDefinition },
+        { leaks: () => leakingDefinition },
         (reply, from, to, meter) => tagLeaks(reply, LOADED, scope, meter, from, to),
         (reply, from, to, meter) => styleLeaks(reply, scope, meter, from, to),
     ]);
@@ -908,9 +900,9 @@ function imageReadings(scope) {
 function linkReadings(scope, skipImages) {
     return metered([
         (reply, from, to, meter) => inlineLeaks(reply, linkOpeners(reply, from, to, skipImages), scope, meter),
-        { match: (match, _reply, _at, meter) => definitionLeaks(match, scope, meter).length > 0 },
-        { match: (match, _reply, _at, meter) => autolinkLeaks(match, scope, meter).length > 0 },
-        { match: (match, _reply, _at, meter) => bareLinkLeaks(match, scope, meter).length > 0 },
+        { leaks: (match, _reply, _at, meter) => definitionLeaks(match, scope, meter).length > 0 },
+        { leaks: (match, _reply, _at, meter) => autolinkLeaks(match, scope, meter).length > 0 },
+        { leaks: (match, _reply, _at, meter) => bareLinkLeaks(match, scope, meter).length > 0 },
         (reply, from, to, meter) => tagLeaks(reply, FOLLOWED, scope, meter, from, to),
     ]);
 }

package/esm/src/guardrails/egress.d.ts

@@ -1,7 +1,6 @@
-import type { ProviderEvent } from '../kernel/types.js';
-import { type GivenUrls } from './egress-urls.js';
-import { type SensitiveGroups, type SensitiveSelection } from './sensitive.js';
-import type { EgressEnforcer, GuardrailContext, GuardrailHit, OutboundPayload, Verdict } from './types.js';
+import type { ModelEvent } from '../kernel/types.js';
+import type { ResolvedDetect } from './detectors.js';
+import type { GuardrailContext, GuardrailHit } from './types.js';
 /** Why a reply was withheld, for the builder (`errorInternal`); the user reads `error.safety`. */
 declare const WITHHELD_REASON: {
     readonly canary: "canary leaked";
@@ -9,98 +8,39 @@ declare const WITHHELD_REASON: {
     readonly providerToolLeak: "a provider-side tool already sent the canary or system prompt";
     readonly egress: "Turn withheld: egress disclosure violation";
 };
-/** Never carries the live token, only a placeholder. */
-declare const CANARY_HIT: GuardrailHit;
-declare const PROMPT_ECHO_HIT: GuardrailHit;
 /** The prompt-echo hit, when `text` repeats the guarded system prompt's own words. */
 declare function promptEchoHits(text: string, privateSystem?: readonly string[], canary?: string): GuardrailHit[];
+/** What a prompt-leak check reads of the turn. */
+type LeakScope = Pick<GuardrailContext, 'canary' | 'canaryGiven' | 'privateSystem'>;
 /**
  * The system-prompt leak hits in any content-bearing field of an event
  * (`guardedEventTexts`). In the report of a provider-side tool they are one
  * `egress.provider-tool-leak`: the call already ran.
  */
-declare function eventPromptLeakHits(event: ProviderEvent, canary?: string, privateSystem?: readonly string[]): GuardrailHit[];
-/** Whether a hit is a system-prompt leak: a hard stop under any host policy. */
-declare function isPromptLeakHit(hit: GuardrailHit): boolean;
-/** Why a system-prompt leak withheld the reply, for the builder. */
-declare function promptLeakReason(hits: GuardrailHit[]): string;
-/** Where a URL check lets a URL through beyond the ones the model was given. */
-interface UrlCheck {
-    /** Hostnames the check lets through whatever their URL, such as the host's own CDN. */
-    hosts?: readonly string[];
-    /**
-     * Whether a URL a tool returned counts as given. Default true. A tool result
-     * can offer the model URLs to pick from, and the pick tells their server
-     * something; false closes that channel, and keeps only what the system
-     * prompt, the user and host history gave.
-     */
-    fromTools?: boolean;
+declare function eventPromptLeakHits(event: ModelEvent, scope: LeakScope): GuardrailHit[];
+/** A leak of ours in an event that is not the reply's text: its hits, and whether it stops the turn. */
+interface EventLeak {
+    stop: boolean;
+    hits: GuardrailHit[];
 }
 /**
- * Which bundled egress checks run; a check left out keeps its default. The
- * system-prompt leak checks are not among them: `guardrails.canary` and
- * `guardrails.promptEcho` switch those, and they run under any policy.
+ * What the detectors of what is ours find in an event's host content
+ * (`guardedEventTexts`) under their actions at `boundary`, as the event goes
+ * to the host with the reply. `flag` reports it; `redact` and `block` stop the
+ * turn, as an event has no text to replace. The report of a provider-side tool
+ * is read whatever the actions are and always stops: the call already ran.
  */
-interface EgressChecks {
-    /**
-     * Sensitive data in the reply, by group. Default every group but `network`:
-     * an address in a reply is not a secret, and replies explaining networks
-     * cite them.
-     */
-    sensitive?: SensitiveSelection;
-    /** The fence the kernel puts around user data, and the canary's note. Default on. */
-    boundary?: boolean;
-    /** Injection phrasing in the reply, as written or disguised. Default on. */
-    injection?: boolean;
-    /** Images that load a URL the model was not given. Default on. */
-    images?: boolean | UrlCheck;
-    /**
-     * Links to a URL the model was not given. Default off: a link loads on a
-     * click, or where the host unfurls links into previews, and replies cite
-     * pages from what the model knows. A host that unfurls turns it on.
-     */
-    links?: boolean | UrlCheck;
-}
-/** `EgressChecks` with defaults applied; a URL check is undefined when off. */
-interface ResolvedEgressChecks {
-    sensitive: SensitiveGroups;
-    boundary: boolean;
-    injection: boolean;
-    images?: UrlCheck;
-    links?: UrlCheck;
-}
-declare function resolveEgressChecks(checks?: EgressChecks): ResolvedEgressChecks;
-/** Every check off: the system-prompt leak checks alone. */
-declare const NO_CHECKS: ResolvedEgressChecks;
-declare const DEFAULT_CHECKS: ResolvedEgressChecks;
-/** What the bundled policy reads besides the reply. */
-interface EgressScope {
-    canary?: string;
-    privateSystem?: readonly string[];
-    /** The URLs the model was given this turn. */
-    given?: GivenUrls;
-}
-/** The bundled policy's hits in `text`, from the checks `checks` runs. */
-declare function collectEgressHits(text: string, scope?: EgressScope, checks?: ResolvedEgressChecks): GuardrailHit[];
+declare function eventLeak(event: ModelEvent, scope: LeakScope, detect: ResolvedDetect, boundary: 'reply' | 'live_reply'): EventLeak | undefined;
+/** Whether a hit is a system-prompt leak. */
+declare function isPromptLeakHit(hit: GuardrailHit): boolean;
+/** Why a system-prompt leak withheld the reply, for the builder. */
+declare function promptLeakReason(hits: GuardrailHit[]): string;
+/** The distinct rule names among the hits. */
 declare function hitRules(hits: GuardrailHit[]): string[];
-/** An enforce that blocks on `collect`'s hits in the reply and in any structured output. */
-declare function hitsEnforcer(collect: (text: string, context: GuardrailContext) => GuardrailHit[]): (payload: OutboundPayload, context: GuardrailContext) => Verdict;
-/** What the bundled policy reads from a gate's context. */
-declare function egressScope(context: GuardrailContext): EgressScope;
-/** Default egress enforce: every bundled check at its default (`EgressChecks`). */
-declare const standardEgressEnforce: (payload: OutboundPayload, context: GuardrailContext) => Verdict;
-declare function registerEgressChecks(enforce: EgressEnforcer, checks: ResolvedEgressChecks): void;
-/** The bundled checks `enforce` runs; undefined for a host enforce, whose checks are its own. */
-declare function egressChecksOf(enforce: EgressEnforcer | undefined): ResolvedEgressChecks | undefined;
-/** A misspelt check or group would leave the check it meant at its default, silently. */
-declare function egressChecksProblem(path: string, checks: unknown): string | undefined;
 /**
- * A policy that throws has reached no decision, so it cannot vouch for the output:
- * the failure becomes a `block`, not a pass. The turn then follows the profile's
- * ordinary `onBlock` handling instead of surfacing a raw host stack trace. The
- * thrown message may carry host internals, so it goes to the builder only
- * (`errorInternal`); the model reads the lexicon's `egress.policy_failed`.
+ * The words of the canary note a turn binds, when the profile's labels
+ * rewords it so that `SYSTEM_BOUNDARY` no longer reads them.
  */
-declare function runEnforcer(enforce: EgressEnforcer, payload: OutboundPayload, context: GuardrailContext): Promise<Verdict>;
-export type { EgressChecks, EgressScope, ResolvedEgressChecks, UrlCheck };
-export { CANARY_HIT, collectEgressHits, DEFAULT_CHECKS, egressChecksOf, egressChecksProblem, egressScope, eventPromptLeakHits, hitRules, hitsEnforcer, isPromptLeakHit, NO_CHECKS, PROMPT_ECHO_HIT, promptEchoHits, promptLeakReason, registerEgressChecks, resolveEgressChecks, runEnforcer, standardEgressEnforce, WITHHELD_REASON, };
+declare function boundaryNote({ canary, labels, }: Pick<GuardrailContext, 'canary' | 'labels'>): string | undefined;
+export type { EventLeak, LeakScope };
+export { boundaryNote, eventLeak, eventPromptLeakHits, hitRules, isPromptLeakHit, promptEchoHits, promptLeakReason, WITHHELD_REASON, };