@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/guardrails_evaluator/core.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Core guardrail policy evaluation orchestration.
+ *
+ * Mirrors Python's `agent_engine_runner_shared/guardrails_evaluator/core.py`: a registry of
+ * per-`policy_type` engines plus `evaluateGuardrailCheck`, which aggregates the
+ * strictest decision across the OE-selected policies for one runtime boundary.
+ */
+import { type GuardrailCheckEvidence, type GuardrailCheckRequest, type GuardrailCheckResponse, type GuardrailRuntimePolicy } from "../models.js";
+/** Engine-owned result for a policy evaluation. */
+export interface GuardrailPolicyEngineResult {
+    evidence: GuardrailCheckEvidence[];
+    transformedText?: string | null;
+}
+/** Contract implemented by native and future remote guardrail engines. */
+export interface GuardrailPolicyEngine {
+    readonly policyType: string;
+    /** Return engine-owned evidence and optional transformed text when triggered. */
+    evaluate(policy: GuardrailRuntimePolicy, text: string): GuardrailPolicyEngineResult | null;
+}
+export declare function registerGuardrailPolicyEngine(engine: GuardrailPolicyEngine): void;
+/** Evaluate guardrail policies for one runtime boundary. */
+export declare function evaluateGuardrailCheck(request: GuardrailCheckRequest): GuardrailCheckResponse;
+//# sourceMappingURL=core.d.ts.map

package/dist/guardrails_evaluator/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/guardrails_evaluator/core.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC5B,MAAM,cAAc,CAAC;AActB,mDAAmD;AACnD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CACN,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,MAAM,GACX,2BAA2B,GAAG,IAAI,CAAC;CACvC;AAID,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,qBAAqB,GAC5B,IAAI,CAEN;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,GAC7B,sBAAsB,CA4GxB"}

package/dist/guardrails_evaluator/core.js

@@ -0,0 +1,122 @@
+/**
+ * Core guardrail policy evaluation orchestration.
+ *
+ * Mirrors Python's `agent_engine_runner_shared/guardrails_evaluator/core.py`: a registry of
+ * per-`policy_type` engines plus `evaluateGuardrailCheck`, which aggregates the
+ * strictest decision across the OE-selected policies for one runtime boundary.
+ */
+import { getLogger } from "../logger.js";
+import { Metrics } from "../metrics.js";
+import { appliesToStage, checkDecision, GuardrailCheckDecision, } from "../models.js";
+const logger = getLogger("agent_engine_runner_shared.guardrails_evaluator.core");
+const DECISION_PRIORITY = {
+    [GuardrailCheckDecision.ALLOW]: 0,
+    [GuardrailCheckDecision.LOG_ONLY]: 1,
+    [GuardrailCheckDecision.MODIFY]: 2,
+    [GuardrailCheckDecision.REQUIRE_REVIEW]: 3,
+    [GuardrailCheckDecision.BLOCK]: 4,
+};
+const POLICY_ENGINES = new Map();
+export function registerGuardrailPolicyEngine(engine) {
+    POLICY_ENGINES.set(engine.policyType, engine);
+}
+/** Evaluate guardrail policies for one runtime boundary. */
+export function evaluateGuardrailCheck(request) {
+    const triggeredPolicyIds = [];
+    const evidence = [];
+    let transformedText = request.input.text;
+    let decision = GuardrailCheckDecision.ALLOW;
+    for (const policy of request.policies) {
+        if (!appliesToStage(policy, request.stage)) {
+            continue;
+        }
+        const engine = POLICY_ENGINES.get(policy.type);
+        if (engine === undefined) {
+            // An unsupported policy type cannot be enforced, so fail closed to BLOCK
+            // rather than silently allowing content through.
+            const reason = `Unsupported guardrail policy type: ${policy.type}`;
+            const policyIds = [...triggeredPolicyIds, policy.id];
+            return {
+                decision: GuardrailCheckDecision.BLOCK,
+                allowed: false,
+                transformed_text: null,
+                triggered_policy_ids: policyIds,
+                evidence: [
+                    ...evidence,
+                    {
+                        policy_id: policy.id,
+                        message: reason,
+                        metadata: { policy_type: policy.type },
+                    },
+                ],
+                reason,
+                metadata: { triggered_count: policyIds.length },
+            };
+        }
+        let policyDecision = checkDecision(policy);
+        const shouldTransform = policyDecision === GuardrailCheckDecision.MODIFY;
+        const result = engine.evaluate(policy, transformedText);
+        if (result === null) {
+            continue;
+        }
+        // A policy that actually triggered but whose `action` (and `on_fail`) does
+        // not resolve to a known verb would otherwise fall through to ALLOW and let
+        // the matching content pass. That is fail-open on a misconfiguration (e.g.
+        // an operator typo), and inconsistent with the fail-closed handling of an
+        // unknown policy type above. Fail closed to BLOCK and make the misconfig
+        // observable instead.
+        if (policyDecision === GuardrailCheckDecision.ALLOW) {
+            logger.warn(`Guardrail policy ${policy.id} triggered but its action ` +
+                `"${policy.action}" did not resolve to a known decision; ` +
+                `failing closed to BLOCK`);
+            Metrics.recordError("guardrails_unresolved_action", {
+                policy_id: policy.id,
+            });
+            policyDecision = GuardrailCheckDecision.BLOCK;
+        }
+        evidence.push(...result.evidence);
+        if (shouldTransform && result.transformedText != null) {
+            transformedText = result.transformedText;
+        }
+        triggeredPolicyIds.push(policy.id);
+        if (DECISION_PRIORITY[policyDecision] > DECISION_PRIORITY[decision]) {
+            decision = policyDecision;
+        }
+    }
+    if (decision === GuardrailCheckDecision.ALLOW) {
+        return {
+            decision: GuardrailCheckDecision.ALLOW,
+            allowed: true,
+            transformed_text: request.input.text,
+            triggered_policy_ids: [],
+            evidence: [],
+            reason: null,
+            metadata: {},
+        };
+    }
+    const policyCount = triggeredPolicyIds.length;
+    let reason;
+    if (decision === GuardrailCheckDecision.BLOCK) {
+        reason = `${policyCount} guardrail policy triggered a block decision`;
+    }
+    else if (decision === GuardrailCheckDecision.REQUIRE_REVIEW) {
+        reason = `${policyCount} guardrail policy requires review`;
+    }
+    else if (decision === GuardrailCheckDecision.MODIFY) {
+        reason = `${policyCount} guardrail policy modified the content`;
+    }
+    else {
+        reason = `${policyCount} guardrail policy triggered`;
+    }
+    const allowed = decision === GuardrailCheckDecision.LOG_ONLY ||
+        decision === GuardrailCheckDecision.MODIFY;
+    return {
+        decision,
+        allowed,
+        transformed_text: allowed ? transformedText : null,
+        triggered_policy_ids: triggeredPolicyIds,
+        evidence,
+        reason,
+        metadata: { triggered_count: policyCount },
+    };
+}

package/dist/guardrails_evaluator/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Guardrails evaluator public surface.
+ *
+ * Importing this module registers the native `output_validation` regex engine
+ * as a side effect (mirroring Python's `guardrails_evaluator/__init__.py`), so
+ * `evaluateGuardrailCheck` can resolve it without an explicit registration call.
+ */
+export { evaluateGuardrailCheck, registerGuardrailPolicyEngine, type GuardrailPolicyEngine, type GuardrailPolicyEngineResult, } from "./core.js";
+export { OutputValidationPolicyEngine, registerRegexGuardrailPolicyEngine, } from "./regex.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/guardrails_evaluator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guardrails_evaluator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,4BAA4B,EAC5B,kCAAkC,GACnC,MAAM,YAAY,CAAC"}

package/dist/guardrails_evaluator/index.js

@@ -0,0 +1,11 @@
+/**
+ * Guardrails evaluator public surface.
+ *
+ * Importing this module registers the native `output_validation` regex engine
+ * as a side effect (mirroring Python's `guardrails_evaluator/__init__.py`), so
+ * `evaluateGuardrailCheck` can resolve it without an explicit registration call.
+ */
+import { registerRegexGuardrailPolicyEngine } from "./regex.js";
+registerRegexGuardrailPolicyEngine();
+export { evaluateGuardrailCheck, registerGuardrailPolicyEngine, } from "./core.js";
+export { OutputValidationPolicyEngine, registerRegexGuardrailPolicyEngine, } from "./regex.js";

package/dist/guardrails_evaluator/regex.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Regex guardrail policy engine (`output_validation`).
+ *
+ * Mirrors Python's `agent_engine_runner_shared/guardrails_evaluator/regex.py`, with one
+ * deliberate divergence: Python uses the `regex` module's per-call `timeout=`
+ * to bound each pattern. Stock JS `RegExp` has no per-match timeout, so a single
+ * catastrophically-backtracking pattern cannot be interrupted mid-match. Per the
+ * approved scope we bound risk with a
+ * total wall-clock deadline checked *between* patterns plus hard pattern-count
+ * and input-length caps, and emit a `guardrails_regex_overrun` metric so the
+ * alarm signal exists if we later need RE2/worker isolation (option (b)).
+ */
+import { type GuardrailRuntimePolicy } from "../models.js";
+import { type GuardrailPolicyEngine, type GuardrailPolicyEngineResult } from "./core.js";
+export declare class OutputValidationPolicyEngine implements GuardrailPolicyEngine {
+    readonly policyType = "output_validation";
+    evaluate(policy: GuardrailRuntimePolicy, text: string): GuardrailPolicyEngineResult | null;
+}
+export declare function registerRegexGuardrailPolicyEngine(): void;
+//# sourceMappingURL=regex.d.ts.map

package/dist/guardrails_evaluator/regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/guardrails_evaluator/regex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EACjC,MAAM,WAAW,CAAC;AAuBnB,qBAAa,4BAA6B,YAAW,qBAAqB;IACxE,QAAQ,CAAC,UAAU,uBAAiC;IAEpD,QAAQ,CACN,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,MAAM,GACX,2BAA2B,GAAG,IAAI;CAkEtC;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD"}

package/dist/guardrails_evaluator/regex.js

@@ -0,0 +1,233 @@
+/**
+ * Regex guardrail policy engine (`output_validation`).
+ *
+ * Mirrors Python's `agent_engine_runner_shared/guardrails_evaluator/regex.py`, with one
+ * deliberate divergence: Python uses the `regex` module's per-call `timeout=`
+ * to bound each pattern. Stock JS `RegExp` has no per-match timeout, so a single
+ * catastrophically-backtracking pattern cannot be interrupted mid-match. Per the
+ * approved scope we bound risk with a
+ * total wall-clock deadline checked *between* patterns plus hard pattern-count
+ * and input-length caps, and emit a `guardrails_regex_overrun` metric so the
+ * alarm signal exists if we later need RE2/worker isolation (option (b)).
+ */
+import { getLogger } from "../logger.js";
+import { Metrics } from "../metrics.js";
+import { checkDecision, GuardrailCheckDecision, } from "../models.js";
+import { registerGuardrailPolicyEngine, } from "./core.js";
+const DEFAULT_REPLACEMENT_TEXT = "[BLOCKED]";
+const OUTPUT_VALIDATION_POLICY_TYPE = "output_validation";
+const MAX_REGEX_PATTERNS = 100;
+const MAX_REGEX_TEXT_LENGTH = 20_000;
+const TOTAL_REGEX_TIMEOUT_MS = 200;
+const logger = getLogger("agent_engine_runner_shared.guardrails_evaluator.regex");
+export class OutputValidationPolicyEngine {
+    policyType = OUTPUT_VALIDATION_POLICY_TYPE;
+    evaluate(policy, text) {
+        const { patterns, invalidPatterns } = compileRegexPatterns(policy);
+        const checkedPatterns = patterns.slice(0, MAX_REGEX_PATTERNS);
+        let skippedPatterns = patterns
+            .slice(MAX_REGEX_PATTERNS)
+            .map((p) => p.pattern);
+        const textTooLong = text.length > MAX_REGEX_TEXT_LENGTH;
+        if (skippedPatterns.length > 0) {
+            logger.warn(`Guardrail policy ${policy.id} has ${patterns.length} regex patterns, ` +
+                `exceeding max ${MAX_REGEX_PATTERNS}; skipping ${skippedPatterns.length} patterns`);
+        }
+        let matches;
+        let timedOutPatterns;
+        if (textTooLong) {
+            logger.warn(`Guardrail policy ${policy.id} regex input length ${text.length} ` +
+                `exceeds max ${MAX_REGEX_TEXT_LENGTH}; failing closed`);
+            matches = [];
+            timedOutPatterns = [];
+            skippedPatterns = patterns.map((p) => p.pattern);
+        }
+        else {
+            ({ matches, timedOutPatterns } = findRegexMatches(text, checkedPatterns, policy.id));
+        }
+        if (matches.length === 0 &&
+            timedOutPatterns.length === 0 &&
+            skippedPatterns.length === 0 &&
+            invalidPatterns.length === 0) {
+            return null;
+        }
+        const replacementText = replacementTextFor(policy);
+        // An invalid pattern means the policy cannot be enforced as written, so it
+        // fails closed alongside timed-out and skipped patterns rather than silently
+        // passing content through as a clean allow.
+        const failClosed = timedOutPatterns.length > 0 ||
+            skippedPatterns.length > 0 ||
+            invalidPatterns.length > 0;
+        return {
+            evidence: [
+                regexEvidence(policy, matches, timedOutPatterns, skippedPatterns, invalidPatterns, textTooLong),
+            ],
+            transformedText: failClosed
+                ? replacementText
+                : redactPatterns(text, matches, replacementText),
+        };
+    }
+}
+export function registerRegexGuardrailPolicyEngine() {
+    registerGuardrailPolicyEngine(new OutputValidationPolicyEngine());
+}
+function findRegexMatches(text, patterns, policyId) {
+    const matches = [];
+    const timedOutPatterns = [];
+    const deadline = performance.now() + TOTAL_REGEX_TIMEOUT_MS;
+    for (let index = 0; index < patterns.length; index += 1) {
+        if (performance.now() >= deadline) {
+            // Deadline exceeded: JS cannot interrupt a running match, so the best we
+            // can do is stop before the remaining patterns and fail closed on them.
+            timedOutPatterns.push(...patterns.slice(index).map((p) => p.pattern));
+            Metrics.recordError("guardrails_regex_overrun", { policy_id: policyId });
+            logger.warn(`Guardrail policy ${policyId} regex evaluation exceeded ` +
+                `${TOTAL_REGEX_TIMEOUT_MS}ms; failing closed on ` +
+                `${patterns.length - index} remaining patterns`);
+            break;
+        }
+        const pattern = patterns[index];
+        for (const match of text.matchAll(pattern.compiled)) {
+            // `match.index` is typed as optional; a `NaN`/undefined start would
+            // corrupt the sort and span-merge redaction below, so skip such matches
+            // rather than emit a match with a `NaN` offset.
+            const start = match.index;
+            if (start === undefined || Number.isNaN(start)) {
+                continue;
+            }
+            matches.push({
+                pattern: pattern.pattern,
+                start,
+                end: start + match[0].length,
+            });
+        }
+    }
+    matches.sort((a, b) => a.start - b.start || a.end - b.end);
+    return { matches, timedOutPatterns };
+}
+function regexEvidence(policy, matches, timedOutPatterns, skippedPatterns, invalidPatterns, textTooLong) {
+    const matchedPatterns = [...new Set(matches.map((m) => m.pattern))];
+    const triggeredPatterns = [
+        ...new Set([
+            ...matchedPatterns,
+            ...timedOutPatterns,
+            ...skippedPatterns,
+            ...invalidPatterns,
+        ]),
+    ];
+    const regexMatches = matches.map(regexMatchMetadata);
+    return {
+        policy_id: policy.id,
+        message: regexEvidenceMessage(policy, triggeredPatterns, invalidPatterns, textTooLong || timedOutPatterns.length > 0 || skippedPatterns.length > 0),
+        metadata: {
+            engine: OUTPUT_VALIDATION_POLICY_TYPE,
+            validator: "regex_match",
+            matched_patterns: matchedPatterns,
+            timed_out_patterns: timedOutPatterns,
+            skipped_patterns: skippedPatterns,
+            invalid_patterns: invalidPatterns,
+            text_too_long: textTooLong,
+            matches: regexMatches,
+            regex_matches: regexMatches,
+        },
+    };
+}
+function regexEvidenceMessage(policy, triggeredPatterns, invalidPatterns, safetyLimited) {
+    const patternSummary = triggeredPatterns.join(", ");
+    if (invalidPatterns.length > 0) {
+        return ("Regex guardrail failed closed; invalid patterns could not be " +
+            `evaluated: ${invalidPatterns.join(", ")}`);
+    }
+    if (safetyLimited) {
+        return `Regex evaluation exceeded safety limits: ${patternSummary}`;
+    }
+    const decision = checkDecision(policy);
+    if (triggeredPatterns.length > 0 &&
+        decision === GuardrailCheckDecision.BLOCK) {
+        return `Regex match blocked content: ${patternSummary}`;
+    }
+    if (triggeredPatterns.length > 0 &&
+        decision === GuardrailCheckDecision.MODIFY) {
+        return `Regex match modified content: ${patternSummary}`;
+    }
+    if (triggeredPatterns.length > 0 &&
+        decision === GuardrailCheckDecision.LOG_ONLY) {
+        return `Regex match logged: ${patternSummary}`;
+    }
+    if (triggeredPatterns.length > 0 &&
+        decision === GuardrailCheckDecision.REQUIRE_REVIEW) {
+        return `Regex match requires review: ${patternSummary}`;
+    }
+    return `Regex match triggered: ${patternSummary}`;
+}
+function regexMatchMetadata(match) {
+    return {
+        pattern: match.pattern,
+        start: match.start,
+        end: match.end,
+        length: match.end - match.start,
+    };
+}
+function redactPatterns(text, matches, replacementText) {
+    let redacted = text;
+    const spans = mergedSpans(matches);
+    for (let i = spans.length - 1; i >= 0; i -= 1) {
+        const [start, end] = spans[i];
+        redacted = `${redacted.slice(0, start)}${replacementText}${redacted.slice(end)}`;
+    }
+    return redacted;
+}
+function mergedSpans(matches) {
+    const spans = [];
+    const sorted = [...matches].sort((a, b) => a.start - b.start || a.end - b.end);
+    for (const match of sorted) {
+        if (match.start === match.end) {
+            continue;
+        }
+        const last = spans[spans.length - 1];
+        if (last === undefined || match.start > last[1]) {
+            spans.push([match.start, match.end]);
+            continue;
+        }
+        last[1] = Math.max(last[1], match.end);
+    }
+    return spans;
+}
+/**
+ * Compile configured patterns, returning valid patterns and the raw strings of
+ * any that failed to compile. Un-compilable patterns are surfaced (not dropped)
+ * so the caller can fail closed — a pattern that cannot compile means the
+ * operator's policy is not being enforced as written. The warning omits the
+ * pattern text to avoid leaking policy content into logs; the pattern is still
+ * returned so it can appear in operator-facing evidence.
+ */
+function compileRegexPatterns(policy) {
+    const raw = policy.config.regex_patterns;
+    if (!Array.isArray(raw)) {
+        return { patterns: [], invalidPatterns: [] };
+    }
+    const patterns = [];
+    const invalidPatterns = [];
+    for (const value of raw) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const pattern = value.trim();
+        if (pattern === "") {
+            continue;
+        }
+        try {
+            // `g` for finditer-style global scan, `i` to mirror Python's IGNORECASE.
+            patterns.push({ pattern, compiled: new RegExp(pattern, "gi") });
+        }
+        catch {
+            logger.warn(`Invalid guardrail regex pattern for policy ${policy.id}; failing closed`);
+            invalidPatterns.push(pattern);
+        }
+    }
+    return { patterns, invalidPatterns };
+}
+function replacementTextFor(policy) {
+    const value = policy.config.replacement_text;
+    return typeof value === "string" ? value : DEFAULT_REPLACEMENT_TEXT;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Framework hook registry for runner-shared.
+ *
+ * Most hooks are registered once at process startup by the framework SDK
+ * before the server starts. The workflow adapter is the exception: it is
+ * register-or-clear on every graph materialization so eligibility cannot
+ * leak from a durable graph into a later native one. Consumers in
+ * runner-shared call `get*()` instead of importing framework-specific
+ * modules directly.
+ *
+ * Type aliases use sdk-core interfaces where possible. The suspend handler
+ * remains loosely typed because its signature is framework-specific
+ * (e.g. langgraph's `interrupt` returns whatever the resume caller provides).
+ */
+import type { BaseLLM } from "@mongodb-js/agent-engine-sdk";
+import type { AERQueryPlugin } from "./server/query.js";
+export type SuspendHandler = (payload: Record<string, unknown>) => Record<string, unknown>;
+export type LLMAdapterFactory = (rawLlm: unknown, options?: {
+    tools?: unknown[];
+    tool_choice?: unknown;
+}) => BaseLLM;
+export type Instrumentor = () => void;
+export interface WorkflowAdapter {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Mark the dynamic extent of the user's @app.entrypoint call.
+ *
+ * **Framework-internal — user agent code must never call this.** Users only
+ * declare an entrypoint (`app.entrypoint(fn)`); the framework SDK wraps its
+ * own evaluation of that function (during AER graph construction and
+ * during Tool preparation, retried after failure) in this helper so
+ * that `registerLlm()` can reject `app.llm()` calls made outside the
+ * entrypoint. Tests that call `app.llm()`/`registerLlm()` directly (bypassing
+ * `app.entrypoint` + `getAgent()`) use it to simulate that framework
+ * evaluation.
+ */
+export declare function entrypointScope<T>(fn: () => T): T;
+export declare function registerSuspendHandler(handler: SuspendHandler): void;
+export declare function getSuspendHandler(): SuspendHandler | null;
+export declare function registerLLMAdapterFactory(factory: LLMAdapterFactory): void;
+export declare function getLLMAdapterFactory(): LLMAdapterFactory;
+export declare function registerInstrumentor(fn: Instrumentor): void;
+export declare function getInstrumentor(): Instrumentor | null;
+/**
+ * Register the framework adapter's `AERQueryPlugin`.
+ *
+ * Mirrors Python's `TenantRuntime.register_query_plugin`. The AER's
+ * `/query/sessions` routes return 501 until a plugin is registered.
+ */
+export declare function registerQueryPlugin(plugin: AERQueryPlugin): void;
+/** Return the registered `AERQueryPlugin`, or `null` if none has been registered. */
+export declare function getQueryPlugin(): AERQueryPlugin | null;
+/**
+ * Declare that the materialized graph supports OE durable workflow routing.
+ *
+ * Call this or {@link clearWorkflowAdapter} on every `getAgent()` materialization
+ * so a later ineligible graph cannot reuse the previous request's identity.
+ */
+export declare function registerWorkflowAdapter(name: string, version: string): void;
+/** Drop durable eligibility for the latest materialized graph. */
+export declare function clearWorkflowAdapter(): void;
+export declare function getWorkflowAdapter(): WorkflowAdapter | null;
+/**
+ * Register an LLM by id. Throws on duplicate id.
+ *
+ * Framework SDKs call this from `app.llm()` for every LLM the agent uses.
+ * The unnamed-LLM convenience case is represented by registering under the
+ * sentinel id `"__default__"`; a second unnamed call therefore raises the
+ * same duplicate-id error as a second named call with the same id.
+ */
+export declare function registerLlm(llmId: string, llm: unknown): void;
+export declare function getNamedLlm(llmId: string): unknown;
+export declare function hasNamedLlms(): boolean;
+export declare function resetLlmRegistry(): void;
+/** Return a shallow copy of the current registry. */
+export declare function snapshotLlmRegistry(): Map<string, unknown>;
+export declare function resetHooks(): void;
+/**
+ * Run the user's agent entrypoint to populate the named-LLM registry.
+ *
+ * Resets the registry before invoking `graphBuilder.getAgent()` so
+ * import-time registrations don't collide if the entrypoint re-registers
+ * them. If the entrypoint registers nothing, restores the pre-reset snapshot
+ * so import-time-only agents still work.
+ *
+ * Returns false after failed construction, including when a snapshot is restored.
+ * Successful construction with no named LLMs is still complete.
+ *
+ * `onEntrypointError`, when supplied, receives the thrown value on that same
+ * path so the caller can attribute a later registry lookup miss to its real
+ * cause rather than to a missing `app.llm()` call.
+ *
+ * Shared by ToolServer.onStartup and ToolFunctionRunner._prepare — mirrors
+ * Python's ToolExecution.prepare() which both inherit.
+ *
+ * @internal — exported for server/ consumers; not part of the public API.
+ */
+export declare function populateLlmRegistryFromEntrypoint(graphBuilder: {
+    getAgent?: () => unknown;
+} | null, logger: {
+    warn(msg: string): void;
+    info(msg: string): void;
+}, warnings: {
+    entrypointFailed: string;
+    noLlmRegistered: string;
+}, onEntrypointError?: (error: unknown) => void): boolean;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7B,MAAM,MAAM,iBAAiB,GAAG,CAC9B,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,KACnD,OAAO,CAAC;AAEb,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC;AACtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQjD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAEpE;AAED,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAEzD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAE1E;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,CAOxD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAE3D;AAED,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAEhE;AAED,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,cAAc,GAAG,IAAI,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK3E;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAe7D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQlD;AAED,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,qDAAqD;AACrD,wBAAgB,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1D;AAED,wBAAgB,UAAU,IAAI,IAAI,CASjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAA;CAAE,GAAG,IAAI,EACjD,MAAM,EAAE;IAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC5D,QAAQ,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,EAC/D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC3C,OAAO,CA+CT"}