@airprompter/agent-core 0.1.0

package/dist/esm/bundle/hpke.js

@@ -0,0 +1,107 @@
+/**
+ * HPKE base mode (RFC 9180) with DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and
+ * AES-GCM, on node:crypto alone. The offline bundle (`.apbundle`) is sealed
+ * to the target's X25519 distribution key with AES-256-GCM; AES-128-GCM is
+ * here only so the implementation can be checked against RFC 9180's A.1
+ * test vector, which uses that AEAD with the same KEM and KDF.
+ */
+import { createCipheriv, createDecipheriv, createHmac, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync } from "node:crypto";
+const KEM_X25519 = 0x0020;
+const KDF_HKDF_SHA256 = 0x0001;
+export const AEAD_AES_128_GCM = 0x0001;
+export const AEAD_AES_256_GCM = 0x0002;
+const NSECRET = 32;
+const NN = 12;
+const utf8 = (text) => Buffer.from(text, "utf8");
+const i2osp2 = (value) => Buffer.from([(value >> 8) & 0xff, value & 0xff]);
+const kemSuiteId = Buffer.concat([utf8("KEM"), i2osp2(KEM_X25519)]);
+const hpkeSuiteId = (aead) => Buffer.concat([utf8("HPKE"), i2osp2(KEM_X25519), i2osp2(KDF_HKDF_SHA256), i2osp2(aead)]);
+function hkdfExtract(salt, ikm) {
+    return createHmac("sha256", salt.length ? salt : Buffer.alloc(32)).update(ikm).digest();
+}
+function hkdfExpand(prk, info, length) {
+    const blocks = [];
+    let previous = Buffer.alloc(0);
+    for (let counter = 1; Buffer.concat(blocks).length < length; counter += 1) {
+        previous = createHmac("sha256", prk).update(Buffer.concat([previous, info, Buffer.from([counter])])).digest();
+        blocks.push(previous);
+    }
+    return Buffer.concat(blocks).subarray(0, length);
+}
+function labeledExtract(suiteId, salt, label, ikm) {
+    return hkdfExtract(salt, Buffer.concat([utf8("HPKE-v1"), suiteId, utf8(label), ikm]));
+}
+function labeledExpand(suiteId, prk, label, info, length) {
+    return hkdfExpand(prk, Buffer.concat([i2osp2(length), utf8("HPKE-v1"), suiteId, utf8(label), info]), length);
+}
+function rawPublic(key) {
+    return Buffer.from(key.export({ format: "jwk" }).x, "base64url");
+}
+export function x25519PublicKeyFromRaw(raw) {
+    return createPublicKey({ key: { kty: "OKP", crv: "X25519", x: Buffer.from(raw).toString("base64url") }, format: "jwk" });
+}
+export function x25519PrivateKeyFromRaw(raw, publicRaw) {
+    return createPrivateKey({ key: { kty: "OKP", crv: "X25519", x: Buffer.from(publicRaw).toString("base64url"), d: Buffer.from(raw).toString("base64url") }, format: "jwk" });
+}
+export function generateX25519KeyPair() {
+    const pair = generateKeyPairSync("x25519");
+    return { privateKey: pair.privateKey, publicKey: pair.publicKey, publicRaw: rawPublic(pair.publicKey) };
+}
+function extractAndExpand(dh, kemContext) {
+    const eaePrk = labeledExtract(kemSuiteId, Buffer.alloc(0), "eae_prk", dh);
+    return labeledExpand(kemSuiteId, eaePrk, "shared_secret", kemContext, NSECRET);
+}
+export function encap(recipientPublicRaw, ephemeral) {
+    const e = ephemeral ?? generateX25519KeyPair();
+    const dh = diffieHellman({ privateKey: e.privateKey, publicKey: x25519PublicKeyFromRaw(recipientPublicRaw) });
+    const enc = e.publicRaw;
+    return { sharedSecret: extractAndExpand(dh, Buffer.concat([enc, Buffer.from(recipientPublicRaw)])), enc };
+}
+export function decap(enc, recipientPrivateKey, recipientPublicRaw) {
+    const dh = diffieHellman({ privateKey: recipientPrivateKey, publicKey: x25519PublicKeyFromRaw(enc) });
+    return extractAndExpand(dh, Buffer.concat([Buffer.from(enc), Buffer.from(recipientPublicRaw)]));
+}
+export function keySchedule(sharedSecret, info, aead) {
+    const suite = hpkeSuiteId(aead);
+    const pskIdHash = labeledExtract(suite, Buffer.alloc(0), "psk_id_hash", Buffer.alloc(0));
+    const infoHash = labeledExtract(suite, Buffer.alloc(0), "info_hash", info);
+    const context = Buffer.concat([Buffer.from([0x00]), pskIdHash, infoHash]);
+    const secret = labeledExtract(suite, sharedSecret, "secret", Buffer.alloc(0));
+    const nk = aead === AEAD_AES_256_GCM ? 32 : 16;
+    return { key: labeledExpand(suite, secret, "key", context, nk), baseNonce: labeledExpand(suite, secret, "base_nonce", context, NN), aead };
+}
+function nonceFor(context, seq) {
+    const nonce = Buffer.from(context.baseNonce);
+    // XOR the sequence number into the low-order bytes (big-endian).
+    let remaining = seq;
+    for (let index = nonce.length - 1; index >= 0 && remaining > 0; index -= 1) {
+        nonce[index] = nonce[index] ^ (remaining & 0xff);
+        remaining = Math.floor(remaining / 256);
+    }
+    return nonce;
+}
+/** ct ‖ tag(16), as HPKE's AEAD.Seal returns it. */
+export function seal(context, aad, plaintext, seq = 0) {
+    const algorithm = context.aead === AEAD_AES_256_GCM ? "aes-256-gcm" : "aes-128-gcm";
+    const cipher = createCipheriv(algorithm, context.key, nonceFor(context, seq));
+    cipher.setAAD(aad);
+    return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+export function open(context, aad, ciphertext, seq = 0) {
+    const algorithm = context.aead === AEAD_AES_256_GCM ? "aes-256-gcm" : "aes-128-gcm";
+    const buffer = Buffer.from(ciphertext);
+    const decipher = createDecipheriv(algorithm, context.key, nonceFor(context, seq));
+    decipher.setAAD(aad);
+    decipher.setAuthTag(buffer.subarray(buffer.length - 16));
+    return Buffer.concat([decipher.update(buffer.subarray(0, buffer.length - 16)), decipher.final()]);
+}
+/** Single-shot base-mode seal: returns `enc` and the ciphertext. */
+export function sealTo(recipientPublicRaw, info, aad, plaintext, aead = AEAD_AES_256_GCM) {
+    const { sharedSecret, enc } = encap(recipientPublicRaw);
+    return { enc, ciphertext: seal(keySchedule(sharedSecret, Buffer.from(info), aead), aad, plaintext) };
+}
+export function openFrom(input) {
+    const sharedSecret = decap(input.enc, input.recipientPrivateKey, input.recipientPublicRaw);
+    return open(keySchedule(sharedSecret, Buffer.from(input.info), input.aead ?? AEAD_AES_256_GCM), input.aad, input.ciphertext);
+}
+//# sourceMappingURL=hpke.js.map

package/dist/esm/bundle/hpke.js.map

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

package/dist/esm/checks/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Declared output checks (T29 / 5-E, checks.md): deterministic, on the host,
+ * on the output the SDK already sees; the result is two counters on the
+ * window (`checks.passed` / `checks.failed`) and never leaves the process.
+ * A port of `conformance/checks.mjs`; `vectors/checks.json` pins the two.
+ *
+ * Kinds: `json_schema` (a documented JSON Schema subset), `enum` (the string
+ * at a dotted path is one of the allowed values), `length` (an output-token
+ * band — the provider's count when reported, else ceil(UTF-8 bytes / 4)),
+ * `must_match` / `must_not_match` (a pattern that must / must not occur).
+ *
+ * Regex safety rule: RE2-class syntax only — no backreferences, no
+ * lookaround, no atomic or possessive groups, no quantified group whose body
+ * is itself quantified — patterns of at most 256 characters, and an output
+ * over 64 KiB fails a pattern check closed rather than being scanned in
+ * part. A refused pattern is refused at declaration and fails closed here.
+ */
+import type { OutputCheck } from "../protocol/types.js";
+export declare const CHECK_BOUNDS: Readonly<{
+    maxChecks: 8;
+    nameMaxLength: 64;
+    patternMaxLength: 256;
+    subjectMaxBytes: 65536;
+    schemaMaxBytes: 16384;
+    enumMaxValues: 64;
+    enumValueMaxLength: 128;
+    pathMaxLength: 128;
+    maxTokens: 1000000;
+}>;
+/** A declared check as the console stores it: the pin projection plus `enabled`. */
+export type DeclaredCheck = OutputCheck & {
+    enabled?: boolean;
+};
+export type CheckResult = {
+    name: string;
+    kind: OutputCheck["kind"];
+    verdict: "pass" | "fail";
+    reason?: string;
+};
+export type CheckOutcome = {
+    passed: number;
+    failed: number;
+    results: CheckResult[];
+};
+export declare function utf8Bytes(text: string): number;
+/** ceil(bytes / 4): the estimate when the provider reported no output tokens. */
+export declare function estimateTokens(text: string): number;
+/** Why a pattern is refused, or null when it is RE2-class and inside the cap. */
+export declare function patternRefusal(pattern: unknown): string | null;
+/** Why a declared check is refused, or null when it is well-formed. */
+export declare function checkRefusal(check: unknown): string | null;
+/** Every refusal of a declared list; empty when all pass. */
+export declare function checksRefusals(checks: unknown): Array<{
+    name: string | null;
+    reason: string;
+}>;
+/** The JSON Schema subset checks.md names; unknown keywords are ignored. */
+export declare function validateJsonSchema(schema: unknown, value: unknown): boolean;
+/** A dotted path into parsed JSON; "" is the whole value. */
+export declare function valueAtPath(value: unknown, path: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+/** One check on one output; never throws. `outputTokens` null = estimate. */
+export declare function evaluateCheck(check: OutputCheck, input: {
+    text: string;
+    outputTokens: number | null;
+}): CheckResult;
+/** Every enabled check on one output: the window's counters and the per-check results. */
+export declare function evaluateChecks(checks: readonly DeclaredCheck[] | undefined, input: {
+    text: string;
+    outputTokens: number | null;
+}): CheckOutcome;
+/** The pin / manifest projection: enabled checks only, sorted by name, the kind's own members only. */
+export declare function projectChecks(checks: readonly DeclaredCheck[] | undefined): OutputCheck[];
+/**
+ * The output text of whatever the provider answered, for the checks: a
+ * plain string; OpenAI `choices[0].message.content` (a string or content
+ * parts); Anthropic `content[].text`; Bedrock Converse
+ * `output.message.content[].text`. Null when nothing recognisable — then the
+ * checks are not run (never a failure invented from an unknown shape).
+ */
+export declare function outputTextOf(result: unknown): string | null;

package/dist/esm/checks/index.js

@@ -0,0 +1,436 @@
+/**
+ * Declared output checks (T29 / 5-E, checks.md): deterministic, on the host,
+ * on the output the SDK already sees; the result is two counters on the
+ * window (`checks.passed` / `checks.failed`) and never leaves the process.
+ * A port of `conformance/checks.mjs`; `vectors/checks.json` pins the two.
+ *
+ * Kinds: `json_schema` (a documented JSON Schema subset), `enum` (the string
+ * at a dotted path is one of the allowed values), `length` (an output-token
+ * band — the provider's count when reported, else ceil(UTF-8 bytes / 4)),
+ * `must_match` / `must_not_match` (a pattern that must / must not occur).
+ *
+ * Regex safety rule: RE2-class syntax only — no backreferences, no
+ * lookaround, no atomic or possessive groups, no quantified group whose body
+ * is itself quantified — patterns of at most 256 characters, and an output
+ * over 64 KiB fails a pattern check closed rather than being scanned in
+ * part. A refused pattern is refused at declaration and fails closed here.
+ */
+export const CHECK_BOUNDS = Object.freeze({
+    maxChecks: 8,
+    nameMaxLength: 64,
+    patternMaxLength: 256,
+    subjectMaxBytes: 65536,
+    schemaMaxBytes: 16384,
+    enumMaxValues: 64,
+    enumValueMaxLength: 128,
+    pathMaxLength: 128,
+    maxTokens: 1_000_000,
+});
+const NAME = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const encoder = new TextEncoder();
+export function utf8Bytes(text) {
+    return encoder.encode(text).length;
+}
+/** ceil(bytes / 4): the estimate when the provider reported no output tokens. */
+export function estimateTokens(text) {
+    return Math.ceil(utf8Bytes(text) / 4);
+}
+/** Why a pattern is refused, or null when it is RE2-class and inside the cap. */
+export function patternRefusal(pattern) {
+    if (typeof pattern !== "string" || pattern.length === 0)
+        return "empty";
+    if (pattern.length > CHECK_BOUNDS.patternMaxLength)
+        return "too_long";
+    if (/\\[1-9]/.test(pattern) || /\\k</.test(pattern))
+        return "backreference";
+    if (/\(\?<?[=!]/.test(pattern))
+        return "lookaround";
+    if (/\(\?>/.test(pattern) || /[*+?}]\+/.test(pattern))
+        return "possessive_or_atomic";
+    let depth = 0;
+    const bodies = [];
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "\\") {
+            i += 1;
+            continue;
+        }
+        if (ch === "[") {
+            let j = i + 1;
+            if (pattern[j] === "^")
+                j += 1;
+            if (pattern[j] === "]")
+                j += 1;
+            while (j < pattern.length && pattern[j] !== "]") {
+                if (pattern[j] === "\\")
+                    j += 1;
+                j += 1;
+            }
+            i = j;
+            continue;
+        }
+        if (ch === "(") {
+            depth += 1;
+            bodies.push({ quantified: false });
+            continue;
+        }
+        if (ch === ")") {
+            const body = bodies.pop();
+            depth -= 1;
+            const groupQuantified = /^(?:[*+?]|\{\d+(?:,\d*)?\})/.test(pattern.slice(i + 1));
+            if (groupQuantified && body?.quantified)
+                return "nested_quantifier";
+            if (groupQuantified && bodies.length > 0)
+                bodies[bodies.length - 1].quantified = true;
+            continue;
+        }
+        if (ch === "{") {
+            const counted = /^\{\d+(?:,\d*)?\}/.exec(pattern.slice(i));
+            if (!counted)
+                return "invalid";
+            if (bodies.length > 0)
+                bodies[bodies.length - 1].quantified = true;
+            i += counted[0].length - 1;
+            continue;
+        }
+        if (ch === "}")
+            return "invalid";
+        if ((ch === "*" || ch === "+") && bodies.length > 0)
+            bodies[bodies.length - 1].quantified = true;
+    }
+    if (depth !== 0)
+        return "unbalanced";
+    try {
+        new RegExp(pattern, "u");
+    }
+    catch {
+        return "invalid";
+    }
+    return null;
+}
+function schemaPatternRefusal(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return null;
+    if (Array.isArray(schema)) {
+        for (const entry of schema) {
+            const bad = schemaPatternRefusal(entry);
+            if (bad)
+                return bad;
+        }
+        return null;
+    }
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "pattern" && typeof value === "string") {
+            const bad = patternRefusal(value);
+            if (bad)
+                return bad;
+            continue;
+        }
+        const bad = schemaPatternRefusal(value);
+        if (bad)
+            return bad;
+    }
+    return null;
+}
+/** Why a declared check is refused, or null when it is well-formed. */
+export function checkRefusal(check) {
+    if (typeof check !== "object" || check === null)
+        return "not_an_object";
+    const c = check;
+    if (typeof c.name !== "string" || !NAME.test(c.name) || c.name.length > CHECK_BOUNDS.nameMaxLength)
+        return "bad_name";
+    switch (c.kind) {
+        case "json_schema": {
+            if (typeof c.schema !== "object" || c.schema === null || Array.isArray(c.schema))
+                return "schema_not_an_object";
+            if (utf8Bytes(JSON.stringify(c.schema)) > CHECK_BOUNDS.schemaMaxBytes)
+                return "schema_too_large";
+            const bad = schemaPatternRefusal(c.schema);
+            return bad ? `schema_pattern_${bad}` : null;
+        }
+        case "enum": {
+            if (typeof c.path !== "string" || c.path.length > CHECK_BOUNDS.pathMaxLength)
+                return "bad_path";
+            const values = c.values;
+            if (!Array.isArray(values) || values.length === 0 || values.length > CHECK_BOUNDS.enumMaxValues)
+                return "bad_values";
+            if (!values.every((v) => typeof v === "string" && v.length > 0 && v.length <= CHECK_BOUNDS.enumValueMaxLength))
+                return "bad_values";
+            if (new Set(values).size !== values.length)
+                return "duplicate_values";
+            return null;
+        }
+        case "length": {
+            const okInt = (v) => Number.isInteger(v) && v >= 0 && v <= CHECK_BOUNDS.maxTokens;
+            if (c.minTokens === undefined && c.maxTokens === undefined)
+                return "no_bound";
+            if (c.minTokens !== undefined && !okInt(c.minTokens))
+                return "bad_bound";
+            if (c.maxTokens !== undefined && !okInt(c.maxTokens))
+                return "bad_bound";
+            if (c.minTokens !== undefined && c.maxTokens !== undefined && c.minTokens > c.maxTokens)
+                return "inverted_bounds";
+            return null;
+        }
+        case "must_match":
+        case "must_not_match": {
+            const refusal = patternRefusal(c.pattern);
+            if (refusal)
+                return `pattern_${refusal}`;
+            if (c.flags !== undefined && c.flags !== "i")
+                return "bad_flags";
+            return null;
+        }
+        default:
+            return "unknown_kind";
+    }
+}
+/** Every refusal of a declared list; empty when all pass. */
+export function checksRefusals(checks) {
+    const refusals = [];
+    if (!Array.isArray(checks))
+        return [{ name: null, reason: "not_a_list" }];
+    if (checks.length > CHECK_BOUNDS.maxChecks)
+        refusals.push({ name: null, reason: "too_many" });
+    const names = new Set();
+    for (const check of checks) {
+        const reason = checkRefusal(check);
+        const name = typeof check?.name === "string" ? (check.name) : null;
+        if (reason)
+            refusals.push({ name, reason });
+        if (name !== null) {
+            if (names.has(name))
+                refusals.push({ name, reason: "duplicate_name" });
+            names.add(name);
+        }
+    }
+    return refusals;
+}
+function parseJson(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        const starts = ["{", "["].map((c) => text.indexOf(c)).filter((i) => i >= 0);
+        const start = starts.length ? Math.min(...starts) : -1;
+        const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
+        if (start < 0 || end <= start)
+            return { ok: false };
+        try {
+            return { ok: true, value: JSON.parse(text.slice(start, end + 1)) };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+}
+/** The JSON Schema subset checks.md names; unknown keywords are ignored. */
+export function validateJsonSchema(schema, value) {
+    if (typeof schema !== "object" || schema === null)
+        return true;
+    const s = schema;
+    if (s.type !== undefined) {
+        const types = Array.isArray(s.type) ? s.type : [s.type];
+        const actual = typeOf(value);
+        if (!types.some((t) => t === actual || (t === "number" && actual === "integer")))
+            return false;
+    }
+    if (Array.isArray(s.enum) && !s.enum.some((v) => JSON.stringify(v) === JSON.stringify(value)))
+        return false;
+    if (s.const !== undefined && JSON.stringify(s.const) !== JSON.stringify(value))
+        return false;
+    if (Array.isArray(s.anyOf) && !s.anyOf.some((sub) => validateJsonSchema(sub, value)))
+        return false;
+    if (typeof value === "string") {
+        const length = [...value].length;
+        if (typeof s.minLength === "number" && length < s.minLength)
+            return false;
+        if (typeof s.maxLength === "number" && length > s.maxLength)
+            return false;
+        if (typeof s.pattern === "string") {
+            if (patternRefusal(s.pattern) || utf8Bytes(value) > CHECK_BOUNDS.subjectMaxBytes)
+                return false;
+            if (!new RegExp(s.pattern, "u").test(value))
+                return false;
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof s.minimum === "number" && value < s.minimum)
+            return false;
+        if (typeof s.maximum === "number" && value > s.maximum)
+            return false;
+    }
+    if (Array.isArray(value)) {
+        if (typeof s.minItems === "number" && value.length < s.minItems)
+            return false;
+        if (typeof s.maxItems === "number" && value.length > s.maxItems)
+            return false;
+        if (s.items !== undefined && !value.every((item) => validateJsonSchema(s.items, item)))
+            return false;
+    }
+    if (typeOf(value) === "object") {
+        const record = value;
+        const properties = typeof s.properties === "object" && s.properties !== null ? s.properties : {};
+        for (const key of Array.isArray(s.required) ? s.required : [])
+            if (!(key in record))
+                return false;
+        for (const [key, sub] of Object.entries(properties))
+            if (key in record && !validateJsonSchema(sub, record[key]))
+                return false;
+        if (s.additionalProperties === false)
+            for (const key of Object.keys(record))
+                if (!(key in properties))
+                    return false;
+    }
+    return true;
+}
+/** A dotted path into parsed JSON; "" is the whole value. */
+export function valueAtPath(value, path) {
+    if (path === "")
+        return { found: true, value };
+    let current = value;
+    for (const part of path.split(".")) {
+        if (Array.isArray(current) && /^\d+$/.test(part))
+            current = current[Number(part)];
+        else if (typeof current === "object" && current !== null && part in current)
+            current = current[part];
+        else
+            return { found: false };
+        if (current === undefined)
+            return { found: false };
+    }
+    return { found: true, value: current };
+}
+/** One check on one output; never throws. `outputTokens` null = estimate. */
+export function evaluateCheck(check, input) {
+    const text = typeof input.text === "string" ? input.text : "";
+    const fail = (reason) => ({ name: check.name, kind: check.kind, verdict: "fail", reason });
+    const pass = () => ({ name: check.name, kind: check.kind, verdict: "pass" });
+    switch (check.kind) {
+        case "json_schema": {
+            const parsed = parseJson(text);
+            if (!parsed.ok)
+                return fail("not_json");
+            return validateJsonSchema(check.schema, parsed.value) ? pass() : fail("schema_mismatch");
+        }
+        case "enum": {
+            let candidate;
+            if (check.path === "") {
+                const trimmed = text.trim();
+                const parsed = parseJson(trimmed);
+                candidate = parsed.ok && typeof parsed.value === "string" ? parsed.value : trimmed;
+            }
+            else {
+                const parsed = parseJson(text);
+                if (!parsed.ok)
+                    return fail("not_json");
+                const at = valueAtPath(parsed.value, check.path);
+                if (!at.found)
+                    return fail("path_missing");
+                candidate = at.value;
+            }
+            if (typeof candidate !== "string")
+                return fail("not_a_string");
+            return check.values.includes(candidate) ? pass() : fail("not_in_enum");
+        }
+        case "length": {
+            const tokens = Number.isInteger(input.outputTokens) && input.outputTokens >= 0 ? input.outputTokens : estimateTokens(text);
+            if (check.minTokens !== undefined && tokens < check.minTokens)
+                return fail("too_short");
+            if (check.maxTokens !== undefined && tokens > check.maxTokens)
+                return fail("too_long");
+            return pass();
+        }
+        case "must_match":
+        case "must_not_match": {
+            if (patternRefusal(check.pattern))
+                return fail("pattern_refused");
+            if (utf8Bytes(text) > CHECK_BOUNDS.subjectMaxBytes)
+                return fail("subject_too_long");
+            const matched = new RegExp(check.pattern, check.flags === "i" ? "iu" : "u").test(text);
+            if (check.kind === "must_match")
+                return matched ? pass() : fail("no_match");
+            return matched ? fail("matched") : pass();
+        }
+        default:
+            return fail("unknown_kind");
+    }
+}
+/** Every enabled check on one output: the window's counters and the per-check results. */
+export function evaluateChecks(checks, input) {
+    const results = [];
+    for (const check of checks ?? []) {
+        if (check && check.enabled === false)
+            continue;
+        results.push(evaluateCheck(check, input));
+    }
+    return { passed: results.filter((r) => r.verdict === "pass").length, failed: results.filter((r) => r.verdict === "fail").length, results };
+}
+/** The pin / manifest projection: enabled checks only, sorted by name, the kind's own members only. */
+export function projectChecks(checks) {
+    return (checks ?? [])
+        .filter((check) => check && check.enabled !== false)
+        .map((check) => {
+        switch (check.kind) {
+            case "json_schema":
+                return { kind: "json_schema", name: check.name, schema: check.schema };
+            case "enum":
+                return { kind: "enum", name: check.name, path: check.path, values: [...check.values] };
+            case "length":
+                return { kind: "length", name: check.name, ...(check.minTokens !== undefined ? { minTokens: check.minTokens } : {}), ...(check.maxTokens !== undefined ? { maxTokens: check.maxTokens } : {}) };
+            default:
+                return { kind: check.kind, name: check.name, pattern: check.pattern, ...(check.flags ? { flags: check.flags } : {}) };
+        }
+    })
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * The output text of whatever the provider answered, for the checks: a
+ * plain string; OpenAI `choices[0].message.content` (a string or content
+ * parts); Anthropic `content[].text`; Bedrock Converse
+ * `output.message.content[].text`. Null when nothing recognisable — then the
+ * checks are not run (never a failure invented from an unknown shape).
+ */
+export function outputTextOf(result) {
+    if (typeof result === "string")
+        return result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const root = result;
+    const partsText = (parts) => {
+        if (typeof parts === "string")
+            return parts;
+        if (!Array.isArray(parts))
+            return null;
+        const texts = parts.map((part) => (typeof part === "object" && part !== null && typeof part.text === "string" ? part.text : null)).filter((t) => t !== null);
+        return texts.length ? texts.join("") : null;
+    };
+    const choice = Array.isArray(root.choices) ? root.choices[0] : undefined;
+    const message = choice && typeof choice.message === "object" && choice.message !== null ? choice.message : null;
+    if (message)
+        return partsText(message.content);
+    if (root.content !== undefined)
+        return partsText(root.content);
+    const output = typeof root.output === "object" && root.output !== null ? root.output : null;
+    const outMessage = output && typeof output.message === "object" && output.message !== null ? output.message : null;
+    if (outMessage)
+        return partsText(outMessage.content);
+    if (typeof root.output_text === "string")
+        return root.output_text;
+    // Responses API: output items (messages) whose content parts carry `text`.
+    if (Array.isArray(root.output)) {
+        const texts = root.output.map((item) => partsText(item?.content)).filter((t) => t !== null);
+        return texts.length ? texts.join("") : null;
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map