@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,86 @@
+/**
+ * Images in a reply load on the reader's device the moment it renders, so a
+ * reply can post data to any server by writing it into an image URL: no tool
+ * call, no click. Links do the same wherever the host unfurls them into a
+ * preview, and on a click everywhere else. An image or link is a leak when its
+ * URL is not one the model was given this turn and its host is not one the
+ * host allowed.
+ *
+ * The reply is read the way a renderer reads it: markdown images and links
+ * (inline, and the reference definitions either may use), autolinks, HTML tags
+ * as the browser tokenizes them, and `<style>` blocks, with entities, escapes
+ * and CSS escapes decoded. Where a renderer could read it more than one way,
+ * every reading is checked.
+ *
+ * @module
+ */
+import type { TurnHistoryMessage } from '../kernel/turn-events.js';
+import type { ModelRequest } from '../kernel/types.js';
+/** The URLs a request already contains, split by who controls them: those from the system prompt, user, and host history, and those from tool results. */
+interface GivenUrls {
+    /** From the system prompt, the user, and host history. */
+    request: ReadonlySet<string>;
+    /** From tool results, which whoever wrote them controls. */
+    tools: ReadonlySet<string>;
+}
+interface GivenUrlSets extends GivenUrls {
+    request: Set<string>;
+    tools: Set<string>;
+    /** A request's input, or a message, that quotes the model's own words: a URL in it was not given. */
+    own: WeakSet<object>;
+}
+declare function givenUrlSets(): GivenUrlSets;
+interface UrlScope {
+    given?: GivenUrls;
+    /** Hostnames the check lets through whatever their URL. */
+    hosts?: readonly string[];
+    /**
+     * Whether a URL a tool returned counts as given. Default true. A tool result
+     * can offer the model a set of URLs to pick from, and the pick tells their
+     * server something; false closes that channel.
+     */
+    fromTools?: boolean;
+}
+/** Adds every absolute URL in `text`, as a reader of it could have copied it. */
+declare function addSeenUrls(seen: Set<string>, text: string): void;
+declare function addHistoryUrls(given: GivenUrlSets, messages: readonly TurnHistoryMessage[]): void;
+declare function addRequestUrls(given: GivenUrlSets, request: Pick<ModelRequest, 'system' | 'input' | 'history'>): void;
+type Span = {
+    start: number;
+    end: number;
+};
+declare function imageLeakSpans(text: string, scope: UrlScope): Span[];
+/** With `skipImages`, an image's own markup is left to the image check. */
+declare function linkLeakSpans(text: string, scope: UrlScope, skipImages: boolean): Span[];
+/**
+ * Patterns covering every image a renderer could read, for the streaming hold.
+ * Each match is at least as long as the image it holds for: an inline image
+ * runs to the end of its paragraph, a tag to the `>` the tokenizer ends it at,
+ * a `<style>` block to the tag that closes it.
+ */
+declare const IMAGE_PATTERNS: readonly RegExp[];
+/** Patterns covering every link a renderer could read, as `IMAGE_PATTERNS` do images. */
+declare const LINK_PATTERNS: readonly RegExp[];
+/** Where the first leak among the constructs starting in a settled stretch [from, to) of the reply starts. */
+type UrlFinder = (reply: string, from: number, to: number) => number | undefined;
+/** Whether a settled regex match at `at` leaks, read with the reply so far. */
+type UrlMatchTest = (match: string, reply: string, at: number) => boolean;
+/**
+ * How the stream reads one URL pattern: constructs that can nest are read by
+ * a finder over each settled stretch, each once; the rest by testing each
+ * match of the pattern.
+ */
+type UrlPatternReading = {
+    find: UrlFinder;
+} | {
+    test: UrlMatchTest;
+};
+/**
+ * The readings of `IMAGE_PATTERNS`, in its order. A definition leaks once any
+ * image could use it, and an image opener once a leaking definition has
+ * settled; the reply is read once overall for openers.
+ */
+declare function imageReadings(scope: UrlScope): UrlPatternReading[];
+declare function linkReadings(scope: UrlScope, skipImages: boolean): UrlPatternReading[];
+export type { GivenUrlSets, GivenUrls, Span, UrlFinder, UrlMatchTest, UrlPatternReading, UrlScope };
+export { addHistoryUrls, addRequestUrls, addSeenUrls, givenUrlSets, IMAGE_PATTERNS, imageLeakSpans, imageReadings, LINK_PATTERNS, linkLeakSpans, linkReadings, };