@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/security-monitor.js

@@ -0,0 +1,307 @@
+/**
+ * Autonomous security monitor — an opt-in LLM judge that vets a single pending
+ * write/execute/external tool call before it runs, from inside the existing
+ * permission gate ({@link file://./tools/tool-permissions.ts}).
+ *
+ * The monitor reuses the gate's read/write/execute/external classification:
+ * read-class tools are never consulted (enforced by the gate). For every other
+ * class the monitor is handed { action name, category, args, recent transcript }
+ * and returns a strict verdict: { block, reason, severity, tier }. The judge
+ * enforces a two-tier model — HARD blocks (never cleared by user intent) and
+ * SOFT blocks (clearable by precise, explicit user intent in the transcript).
+ * The clearing logic lives entirely in the judge prompt; this class trusts the
+ * returned `block` flag.
+ *
+ * Fail-CLOSED for what the monitor exists to vet: when the judge errors or
+ * returns unparseable output, a `write`, `execute` or `external` action gets
+ * a SOFT block naming the failure, so a judge outage withholds the action
+ * rather than waving it through. A `read` action is allowed on the same
+ * failure — the gate never consults the monitor for one, so reaching here
+ * with `read` is a caller's choice, and a read has nothing to withhold.
+ *
+ * This module performs a single non-streaming provider call per review via
+ * `provider.generateMessageTraced`. It is fully opt-in and constructed only
+ * when an agent enables it — when no monitor is wired into the gate, the gate
+ * behaves byte-for-byte as before.
+ */
+import { createLogger } from "@nodetool-ai/config";
+import { extractJSON } from "./utils/json-parser.js";
+import { SECURITY_MONITOR_SYSTEM_PROMPT, buildSecurityMonitorUserPrompt } from "./prompts/security-monitor-prompt.js";
+import { isBoolean, isObjectLike, isRecord, isString } from "./utils/type-guards.js";
+const log = createLogger("nodetool.agents.security-monitor");
+const DEFAULT_MAX_TRANSCRIPT_CHARS = 8_000;
+const DEFAULT_MAX_ARG_CHARS = 4_000;
+const JUDGE_MAX_TOKENS = 300;
+const TRUNCATION_MARKER = "…[truncated]";
+const SEVERITIES = new Set([
+    "low",
+    "medium",
+    "high",
+    "critical"
+]);
+const TIERS = new Set([
+    "hard",
+    "soft",
+    "none"
+]);
+/** The allow verdict a read-class action gets when the judge cannot answer. */
+const ALLOW_VERDICT = {
+    block: false,
+    reason: "",
+    severity: "low",
+    tier: "none"
+};
+/**
+ * The verdict when the judge produced no usable answer. Actionable classes
+ * fail closed; `read` fails open. SOFT, because the judge said nothing about
+ * a boundary — the block records that it was not judged, and a retry after
+ * the judge recovers is the right next step.
+ */
+function unjudgedVerdict(category, failure) {
+    if (category === "read")
+        return { ...ALLOW_VERDICT };
+    return {
+        block: true,
+        reason: `the security monitor could not judge this action (${failure})`,
+        severity: "high",
+        tier: "soft"
+    };
+}
+/** Truncate a string to `max` chars, appending a visible marker when cut. */
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, max) + TRUNCATION_MARKER;
+}
+/** Extract a plain string from a message's content (string | parts | other). */
+function extractText(content) {
+    if (content === null || content === undefined)
+        return "";
+    if (isString(content))
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const part of content) {
+            if (isObjectLike(part) &&
+                "text" in part &&
+                isString(part.text)) {
+                parts.push(part.text);
+            }
+        }
+        return parts.join("");
+    }
+    return "";
+}
+/** Coerce an unknown into a {@link SecuritySeverity}, defaulting to "low". */
+function coerceSeverity(value) {
+    if (isString(value) && SEVERITIES.has(value)) {
+        return value;
+    }
+    return "low";
+}
+/** Coerce an unknown into a {@link SecurityTier}, defaulting to "none". */
+function coerceTier(value) {
+    if (isString(value) && TIERS.has(value)) {
+        return value;
+    }
+    return "none";
+}
+/** Interpret a loose boolean-ish value ("yes"/"true"/true) as a block flag. */
+function coerceBlock(value) {
+    if (isBoolean(value))
+        return value;
+    if (isString(value)) {
+        const lowered = value.trim().toLowerCase();
+        return lowered === "true" || lowered === "yes" || lowered === "1";
+    }
+    return false;
+}
+function tagBody(text, tag) {
+    const match = text.match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, "i"));
+    return match ? match[1].trim() : null;
+}
+/**
+ * Parse a verdict from the judge's raw message text. Strategy order:
+ *   1. The strict JSON object (direct or via {@link extractJSON} fence/brace
+ *      recovery).
+ *   2. The alternate `<block>…</block><reason>…</reason>` tag form.
+ * Returns null when neither yields a usable verdict, letting the caller apply
+ * the fail-open default.
+ */
+/**
+ * Scan `text` for the first balanced `{…}` object that actually parses AND
+ * contains a `block` or `tier` key. `extractJSON` returns the FIRST balanced
+ * object, which — for a verbose judge that prepends prose containing another
+ * object (e.g. echoing the tool args it was shown) — is not the verdict. Using
+ * that wrong object made a real BLOCK decision fall through to the fail-open
+ * ALLOW default.
+ */
+function findVerdictObject(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "{")
+            continue;
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let j = i; j < text.length; j++) {
+            const ch = text[j];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (ch === "\\")
+                    escaped = true;
+                else if (ch === '"')
+                    inString = false;
+                continue;
+            }
+            if (ch === '"')
+                inString = true;
+            else if (ch === "{")
+                depth++;
+            else if (ch === "}") {
+                depth--;
+                if (depth === 0) {
+                    const candidate = text.slice(i, j + 1);
+                    try {
+                        const obj = JSON.parse(candidate);
+                        if (isRecord(obj) &&
+                            ("block" in obj || "tier" in obj)) {
+                            return obj;
+                        }
+                    }
+                    catch {
+                        // not valid JSON — keep scanning from the next "{"
+                    }
+                    break; // move outer loop past this object
+                }
+            }
+        }
+    }
+    return null;
+}
+export function parseVerdict(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    // Strategy 1: the verdict JSON object (the first balanced object that carries
+    // block/tier), falling back to extractJSON's fence/brace recovery.
+    const scanned = findVerdictObject(trimmed);
+    const parsed = scanned ?? extractJSON(trimmed);
+    if (isRecord(parsed)) {
+        const obj = parsed;
+        if ("block" in obj || "tier" in obj) {
+            const tier = coerceTier(obj["tier"]);
+            // Fail safe: block when `block` is truthy OR the tier is non-"none". A
+            // non-boolean `block` (e.g. {block:1,tier:"hard"}) coerces to false, which
+            // combined with a hard/soft tier would otherwise fail open — the tier
+            // rescues it. A `{tier:"hard"}` with no block field blocks the same way.
+            const block = coerceBlock(obj["block"]) || tier !== "none";
+            return {
+                block,
+                tier,
+                severity: coerceSeverity(obj["severity"]),
+                reason: isString(obj["reason"]) ? obj["reason"] : ""
+            };
+        }
+    }
+    // Strategy 2: tag form, e.g. <block>yes</block><reason>…</reason>.
+    const blockTag = tagBody(trimmed, "block");
+    const tierTag = tagBody(trimmed, "tier");
+    if (blockTag !== null || tierTag !== null) {
+        const tier = coerceTier(tierTag);
+        return {
+            block: blockTag !== null ? coerceBlock(blockTag) : tier !== "none",
+            tier,
+            severity: coerceSeverity(tagBody(trimmed, "severity")),
+            reason: tagBody(trimmed, "reason") ?? ""
+        };
+    }
+    return null;
+}
+/**
+ * The LLM judge. One {@link review} call per actionable tool invocation.
+ */
+export class SecurityMonitor {
+    provider;
+    model;
+    maxTranscriptChars;
+    maxArgChars;
+    threadId;
+    constructor(opts) {
+        this.provider = opts.provider;
+        this.model = opts.model;
+        this.maxTranscriptChars =
+            opts.maxTranscriptChars ?? DEFAULT_MAX_TRANSCRIPT_CHARS;
+        this.maxArgChars = opts.maxArgChars ?? DEFAULT_MAX_ARG_CHARS;
+        this.threadId = opts.threadId;
+    }
+    /**
+     * Judge a single pending action. Returns a {@link SecurityVerdict}. On any
+     * provider error or unparseable output, returns {@link unjudgedVerdict}: a
+     * block for an actionable category, allow for `read` (see module header).
+     */
+    async review(action) {
+        let argsJson;
+        try {
+            argsJson = JSON.stringify(action.args ?? {}, null, 2);
+        }
+        catch {
+            argsJson = String(action.args);
+        }
+        const userMsg = buildSecurityMonitorUserPrompt({
+            name: action.name,
+            category: action.category,
+            argsJson: truncate(argsJson, this.maxArgChars),
+            transcript: truncate(action.transcript ?? "", this.maxTranscriptChars)
+        });
+        const messages = [
+            { role: "system", content: SECURITY_MONITOR_SYSTEM_PROMPT },
+            { role: "user", content: userMsg }
+        ];
+        let reply;
+        try {
+            reply = await this.provider.generateMessageTraced({
+                messages,
+                model: this.model,
+                maxTokens: JUDGE_MAX_TOKENS,
+                temperature: 0,
+                threadId: this.threadId
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            log.warn("Security monitor judge call failed", {
+                tool: action.name,
+                category: action.category,
+                error
+            });
+            return unjudgedVerdict(action.category, `judge call failed: ${error}`);
+        }
+        const verdict = parseVerdict(extractText(reply.content));
+        if (!verdict) {
+            log.warn("Security monitor verdict unparseable", {
+                tool: action.name,
+                category: action.category
+            });
+            return unjudgedVerdict(action.category, "verdict unparseable");
+        }
+        if (verdict.block) {
+            log.info("Security monitor blocked a pending action", {
+                tool: action.name,
+                category: action.category,
+                tier: verdict.tier,
+                severity: verdict.severity
+            });
+        }
+        return verdict;
+    }
+}
+/**
+ * Bridge a {@link SecurityMonitor} into the permission gate. Returns a plain
+ * consult callback (the gate stays free of any provider/LLM dependency) that
+ * forwards a pending action to {@link SecurityMonitor.review}.
+ */
+export function createSecurityMonitorConsult(monitor) {
+    return (action) => monitor.review(action);
+}
+//# sourceMappingURL=security-monitor.js.map

package/dist/security-monitor.js.map

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

package/dist/serpapi/catalog.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The SerpAPI engine catalog — where "discover the endpoints" actually happens.
+ *
+ * SerpAPI is one endpoint (`/search.json`) whose `engine` parameter selects
+ * which of ~120 contracts applies, and each contract has its own parameters.
+ * Hand-wrapping them produces the same backlog the Apify actor wrappers did, so
+ * nothing here is hand-written: the catalog is read from SerpAPI's own
+ * playground, which ships every engine and every parameter — name, label,
+ * description, required flag, type, and allowed options — as one JSON blob in a
+ * `data-react-props` attribute.
+ *
+ * That is a page, not a documented API, so the parse is defensive and the
+ * failure is named: a page whose shape changed comes back as
+ * `catalog_unavailable`, which the capability module reports as "discovery is
+ * down, here is why" rather than as an empty engine list that reads like
+ * SerpAPI ships nothing.
+ *
+ * The catalog is cached process-wide with a TTL. One fetch is ~3 MB, and the
+ * contract of an engine changes on SerpAPI's release schedule, not per call.
+ */
+/** One parameter of one engine, as the playground describes it. */
+export interface SerpApiParameter {
+    readonly name: string;
+    /** SerpAPI's own display name, e.g. "Search Query". */
+    readonly label: string;
+    /** The description with its documentation markup flattened to text. */
+    readonly description: string;
+    readonly required: boolean;
+    /** SerpAPI's widget type — "select", "number", "location", … — when given. */
+    readonly type?: string;
+    /** Allowed values, for the parameters that enumerate them. */
+    readonly options?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** The group the playground files it under, e.g. "localization". */
+    readonly group: string;
+    /** Present but not offered in the playground UI. */
+    readonly hidden: boolean;
+}
+/** One engine's whole contract. */
+export interface SerpApiEngine {
+    readonly engine: string;
+    /** Derived from the id ("google_scholar" → "Google Scholar"). */
+    readonly label: string;
+    /** The page this contract was read from, and where a human can read it. */
+    readonly playgroundUrl: string;
+    readonly parameters: readonly SerpApiParameter[];
+}
+/** Every engine, plus the shared option lists the localization fields take. */
+export interface SerpApiCatalog {
+    readonly engines: ReadonlyMap<string, SerpApiEngine>;
+    /** `hl` values: language code → language name. */
+    readonly languages: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** `gl` values: country code → country name. */
+    readonly countries: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** `google_domain` values. */
+    readonly googleDomains: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly fetchedAt: number;
+}
+/** How long a fetched catalog is reused. */
+export declare const CATALOG_TTL_MS: number;
+export interface CatalogOptions {
+    readonly fetchImpl?: typeof fetch;
+    readonly signal?: AbortSignal;
+    /** Ignore the cached copy and re-read the page. */
+    readonly force?: boolean;
+    /** Injected for tests; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** Drop the cached catalog. For tests, and for a forced refresh. */
+export declare function clearSerpApiCatalogCache(): void;
+/** The catalog, from cache when it is fresh and from serpapi.com otherwise. */
+export declare function loadSerpApiCatalog(options?: CatalogOptions): Promise<SerpApiCatalog>;
+/**
+ * Parse the playground page into a catalog.
+ *
+ * Exported so the parse can be tested against a checked-in page fixture
+ * without a network call — the check that matters is that a page shape change
+ * is caught, and only a fixture can fail on that.
+ */
+export declare function parseSerpApiCatalog(html: string, fetchedAt: number): SerpApiCatalog;
+/**
+ * Flatten one parameter's documentation HTML to the text a model reads.
+ *
+ * Entities are decoded first and tags are stripped until the string stops
+ * changing, rather than in one pass. A single pass is incomplete sanitization:
+ * `<<b>script>` survives it as `<script`, and decoding afterwards would turn
+ * `&lt;script&gt;` back into markup this function claims to have removed.
+ */
+export declare function htmlToText(html: string): string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/serpapi/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/serpapi/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAoBH,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjF,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAClD;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrD,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClF,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClF,8BAA8B;IAC9B,QAAQ,CAAC,aAAa,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,4CAA4C;AAC5C,eAAO,MAAM,cAAc,QAAqB,CAAC;AAcjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAmCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,cAAc,CA6BhB;AA6DD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU/C"}

package/dist/serpapi/catalog.js

@@ -0,0 +1,246 @@
+/**
+ * The SerpAPI engine catalog — where "discover the endpoints" actually happens.
+ *
+ * SerpAPI is one endpoint (`/search.json`) whose `engine` parameter selects
+ * which of ~120 contracts applies, and each contract has its own parameters.
+ * Hand-wrapping them produces the same backlog the Apify actor wrappers did, so
+ * nothing here is hand-written: the catalog is read from SerpAPI's own
+ * playground, which ships every engine and every parameter — name, label,
+ * description, required flag, type, and allowed options — as one JSON blob in a
+ * `data-react-props` attribute.
+ *
+ * That is a page, not a documented API, so the parse is defensive and the
+ * failure is named: a page whose shape changed comes back as
+ * `catalog_unavailable`, which the capability module reports as "discovery is
+ * down, here is why" rather than as an empty engine list that reads like
+ * SerpAPI ships nothing.
+ *
+ * The catalog is cached process-wide with a TTL. One fetch is ~3 MB, and the
+ * contract of an engine changes on SerpAPI's release schedule, not per call.
+ */
+import { SerpApiError, asSerpApiError } from "./errors.js";
+import { isRecord, isString } from "../utils/type-guards.js";
+import { HOST_OWNED_PARAMS, SERPAPI_BASE } from "./client.js";
+/**
+ * Parameters the playground lists that are not part of an engine's contract as
+ * a caller sees it.
+ *
+ * `api_key` and `output` belong to the host, and `engine` is the selector that
+ * chose this contract in the first place. All three are marked *required* in
+ * SerpAPI's own table, so leaving them in would make every checked call demand
+ * the one field the caller must never set.
+ */
+const CALLER_CANNOT_SET = new Set([
+    ...HOST_OWNED_PARAMS,
+    "engine"
+]);
+/** How long a fetched catalog is reused. */
+export const CATALOG_TTL_MS = 6 * 60 * 60 * 1000;
+const PLAYGROUND_URL = `${SERPAPI_BASE}/playground`;
+const FETCH_TIMEOUT_MS = 60_000;
+let cached;
+/** In-flight fetch, so a burst of calls costs one 3 MB download, not five. */
+let inFlight;
+/** Drop the cached catalog. For tests, and for a forced refresh. */
+export function clearSerpApiCatalogCache() {
+    cached = undefined;
+    inFlight = undefined;
+}
+/** The catalog, from cache when it is fresh and from serpapi.com otherwise. */
+export async function loadSerpApiCatalog(options = {}) {
+    const now = options.now ?? Date.now;
+    if (options.force !== true && cached !== undefined && cached.expiresAt > now()) {
+        return cached.catalog;
+    }
+    if (options.force !== true && inFlight !== undefined)
+        return inFlight;
+    const pending = fetchCatalog(options)
+        .then((catalog) => {
+        cached = { catalog, expiresAt: now() + CATALOG_TTL_MS };
+        return catalog;
+    })
+        .finally(() => {
+        inFlight = undefined;
+    });
+    inFlight = pending;
+    return pending;
+}
+async function fetchCatalog(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeout = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    const signal = options.signal === undefined
+        ? timeout
+        : AbortSignal.any([options.signal, timeout]);
+    let html;
+    try {
+        const response = await fetchImpl(PLAYGROUND_URL, { signal });
+        if (!response.ok) {
+            throw new SerpApiError("catalog_unavailable", `Could not read the SerpAPI engine catalog: ${PLAYGROUND_URL} answered ${response.status}.`, { status: response.status });
+        }
+        html = await response.text();
+    }
+    catch (error) {
+        if (error instanceof SerpApiError)
+            throw error;
+        const failure = asSerpApiError(error);
+        if (failure.kind === "cancelled")
+            throw failure;
+        throw new SerpApiError("catalog_unavailable", `Could not read the SerpAPI engine catalog: ${failure.message}`, { cause: error });
+    }
+    return parseSerpApiCatalog(html, (options.now ?? Date.now)());
+}
+/**
+ * Parse the playground page into a catalog.
+ *
+ * Exported so the parse can be tested against a checked-in page fixture
+ * without a network call — the check that matters is that a page shape change
+ * is caught, and only a fixture can fail on that.
+ */
+export function parseSerpApiCatalog(html, fetchedAt) {
+    const props = readReactProps(html);
+    const rawEngines = props.parameters;
+    if (!isRecord(rawEngines) || Object.keys(rawEngines).length === 0) {
+        throw new SerpApiError("catalog_unavailable", "The SerpAPI playground page carried no engine parameter table. Its " +
+            "markup has changed; the catalog parser needs updating.");
+    }
+    const engines = new Map();
+    for (const [engine, groups] of Object.entries(rawEngines)) {
+        if (!isRecord(groups))
+            continue;
+        engines.set(engine, {
+            engine,
+            label: engineLabel(engine),
+            playgroundUrl: `${PLAYGROUND_URL}?engine=${encodeURIComponent(engine)}`,
+            parameters: readParameters(groups)
+        });
+    }
+    return {
+        engines,
+        languages: readOptionPairs(props.hl_options),
+        countries: readOptionPairs(props.gl_options),
+        googleDomains: readOptionPairs(props.google_domain_options),
+        fetchedAt
+    };
+}
+/**
+ * The page mounts its React root with the whole catalog in one HTML-escaped
+ * attribute. The value cannot itself contain a raw `"` — it is escaped to
+ * `"` — so the attribute ends at the first quote, and a lazy match is
+ * exact rather than approximate.
+ */
+function readReactProps(html) {
+    const match = /data-react-props="([^"]*)"/.exec(html);
+    if (match === null) {
+        throw new SerpApiError("catalog_unavailable", "The SerpAPI playground page no longer carries a data-react-props " +
+            "attribute. Its markup has changed; the catalog parser needs updating.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(unescapeHtml(match[1]));
+    }
+    catch (error) {
+        throw new SerpApiError("catalog_unavailable", "The SerpAPI playground page carried a data-react-props attribute that " +
+            "is not JSON. Its markup has changed; the catalog parser needs updating.", { cause: error });
+    }
+    if (!isRecord(parsed)) {
+        throw new SerpApiError("catalog_unavailable", "The SerpAPI playground props are not an object.");
+    }
+    return parsed;
+}
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " "
+};
+/** Undo the attribute escaping. Numeric forms appear inside descriptions. */
+function unescapeHtml(text) {
+    return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, entity) => {
+        if (entity.startsWith("#x") || entity.startsWith("#X")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+        }
+        if (entity.startsWith("#")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+        }
+        return Object.hasOwn(ENTITIES, entity.toLowerCase())
+            ? ENTITIES[entity.toLowerCase()]
+            : whole;
+    });
+}
+/**
+ * Flatten one parameter's documentation HTML to the text a model reads.
+ *
+ * Entities are decoded first and tags are stripped until the string stops
+ * changing, rather than in one pass. A single pass is incomplete sanitization:
+ * `<<b>script>` survives it as `<script`, and decoding afterwards would turn
+ * `&lt;script&gt;` back into markup this function claims to have removed.
+ */
+export function htmlToText(html) {
+    let text = unescapeHtml(html)
+        .replace(/<br\s*\/?>/gi, " ")
+        .replace(/<\/(p|div|li)>/gi, " ");
+    let previous = "";
+    while (text !== previous) {
+        previous = text;
+        text = text.replace(/<[^>]*>/g, "");
+    }
+    return text.replace(/\s+/g, " ").trim();
+}
+function readParameters(groups) {
+    const parameters = [];
+    for (const [group, groupValue] of Object.entries(groups)) {
+        if (!isRecord(groupValue))
+            continue;
+        const groupHidden = groupValue.hidden === true;
+        const table = groupValue.parameters;
+        if (!isRecord(table))
+            continue;
+        for (const [name, value] of Object.entries(table)) {
+            if (!isRecord(value) || CALLER_CANNOT_SET.has(name))
+                continue;
+            const options = readOptionPairs(value.options);
+            const parameter = {
+                name,
+                label: isString(value.name) ? value.name : name,
+                description: isString(value.html) ? htmlToText(value.html) : "",
+                required: value.required === true,
+                group,
+                hidden: groupHidden || value.hidden_from_playground === true
+            };
+            if (isString(value.type))
+                parameter.type = value.type;
+            if (options.length > 0)
+                parameter.options = options;
+            parameters.push(parameter);
+        }
+    }
+    return parameters;
+}
+/** Read SerpAPI's `[[value, label], …]` option lists. */
+function readOptionPairs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const pairs = [];
+    for (const entry of value) {
+        if (!Array.isArray(entry) || entry.length === 0)
+            continue;
+        const [raw, label] = entry;
+        if (typeof raw !== "string" && typeof raw !== "number")
+            continue;
+        pairs.push({
+            value: String(raw),
+            label: isString(label) ? label : String(raw)
+        });
+    }
+    return pairs;
+}
+/** "google_scholar_author" → "Google Scholar Author". */
+function engineLabel(engine) {
+    return engine
+        .split("_")
+        .map((word) => (word.length === 0 ? word : word[0].toUpperCase() + word.slice(1)))
+        .join(" ");
+}
+//# sourceMappingURL=catalog.js.map