@sema-agent/core/dist/brain/request-route.d.ts

Stateless, task-oriented AI agent core

/**
 * The route a provider request took, as the brain that built it states it: where the credential it carried came
 * from, how that credential rode, and which knob named the request's root. One projection of the two resolutions a
 * request build already runs ({@link import("./route-adjudicator.js").resolveRouteCredential} and
 * {@link import("./route-adjudicator.js").resolveRequestRootOf}) — never a key value, never a URL.
 *
 * Who reads it: the engine's terminal-shell mint lifts the committed request's route onto
 * `AssistantMessage.apiErrorRoute` (only beside `isApiErrorMessage`), and a run whose terminal is a provider refusal
 * carries it on `terminal.detail.route`. {@link ROUTE_CREDENTIAL_PAIRING} is the same vocabulary as a table: one row
 * per declaration shape a request can carry, naming the knob(s) the credential is read from and the root knob it is
 * paired with — the machine-readable half of the pairing law whose verdicts the conformance corpus pins.
 */
import type { RouteCredential } from "../internal/llm.js";
/** Where the credential a request would carry came from.
 *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
 *    (`getApiKeyAndHeaders`), or a credential header declared on `Model.headers`. Bound to the
 *    origin of the first request sent carrying it; refused only on its way to another origin.
 *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
 *    in `config.headers`). Paired only with the deployment's own root (`config.baseUrl`, else the lane's default).
 *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
 *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
 *    credential route is a configuration hole, not a keyless deployment). */
export declare const ROUTE_CREDENTIAL_SOURCES: readonly ["per-model", "deployment-config", "absent"];
export type RouteCredentialSource = (typeof ROUTE_CREDENTIAL_SOURCES)[number];
/** How a credential rode: the brain's apiKey knob (written as the lane's own auth header), or an auth-bearing header
 *  from one of the header bags. */
export declare const ROUTE_CARRIERS: readonly ["apiKey", "header"];
export type RouteCarrier = (typeof ROUTE_CARRIERS)[number];
/** The header bag an auth-bearing header came from: the per-call options (the per-model auth hook's headers), the
 *  model entry (`Model.headers`), or the brain's construction config (`config.headers`). */
export declare const ROUTE_CARRIER_BAGS: readonly ["options", "model", "config"];
export type RouteCarrierBag = (typeof ROUTE_CARRIER_BAGS)[number];
/** Which knob named the request's root: the model entry (`Model.baseUrl`), the brain's construction config
 *  (`config.baseUrl`), or the lane's own default endpoint (neither was declared). */
export declare const REQUEST_ROOT_ORIGINS: readonly ["model", "deployment", "lane-default"];
export type RequestRootOrigin = (typeof REQUEST_ROOT_ORIGINS)[number];
/**
 * The route a request took ({@link requestRouteOf}). Never a key value and never a URL — the words name knobs, so the
 * value may travel wherever the failure it describes travels.
 *  - `credentialSource` — {@link RouteCredentialSource}.
 *  - `carrier` — how the credential rode ({@link RouteCarrier}); absent exactly when `credentialSource` is `"absent"`.
 *  - `carrierBag` — the header bag whose auth header rode ({@link RouteCarrierBag}); present exactly when one did:
 *    with carrier `"header"`, and beside carrier `"apiKey"` when one source sets both — the per-model hook's answer
 *    (`apiKey` and an auth header in its `headers`) or the deployment (`config.apiKey` and an auth header in
 *    `config.headers`); both ride.
 *  - `root` — which knob named the request's root ({@link RequestRootOrigin}).
 * The legal shapes are exactly the rows of {@link ROUTE_CREDENTIAL_PAIRING}.
 */
export interface RequestRoute {
    credentialSource: RouteCredentialSource;
    carrier?: RouteCarrier;
    carrierBag?: RouteCarrierBag;
    root: RequestRootOrigin;
}
/** The route of a request carrying `credential`, rooted at the knob `root` names — the one mint of a
 *  {@link RequestRoute}. Reads the credential's SHAPE only; its key value never leaves this function. */
export declare function requestRouteOf(credential: RouteCredential, root: RequestRootOrigin): RequestRoute;
/** One row of {@link ROUTE_CREDENTIAL_PAIRING}. */
export interface RouteCredentialPairingRow {
    readonly credentialSource: RouteCredentialSource;
    readonly carrier?: RouteCarrier;
    readonly carrierBag?: RouteCarrierBag;
    /** The knob(s) the credential is read from, in this engine's own spelling (`getApiKeyAndHeaders` is the per-model
     *  auth hook, whose answer reaches the brain as the per-call options). Empty for `"absent"`. */
    readonly credentialKnobs: readonly string[];
    /** The root knob the credential is paired with: `"Model.baseUrl"` for a per-model credential (paired with the
     *  ORIGIN that knob named the first time the credential was judged), `"config.baseUrl"` for the deployment credential (paired only
     *  when the request targets that root — or, undeclared, the lane's own default endpoint). Absent for
     *  `"absent"`. */
    readonly pairsWith?: "Model.baseUrl" | "config.baseUrl";
}
/**
 * The pairing law as a table — one row per route shape a request can carry, in resolution precedence (an earlier
 * row's source wins when several are configured; one rank per source — the first three rows are the per-model hook's
 * answer, the three deployment rows the deployment config, each source's credential judged as one). A consumer naming "which key was that" reads the row a {@link RequestRoute} lands on (same
 * `credentialSource` / `carrier` / `carrierBag`), never a sentence. The verdicts the law gives these shapes are the
 * conformance corpus's (`ROUTE_ADJUDICATION_CONFORMANCE_CORPUS`).
 */
export declare const ROUTE_CREDENTIAL_PAIRING: readonly RouteCredentialPairingRow[];
/** The pairing row a route lands on, `undefined` for a shape no request carries. */
export declare function routePairingRowOf(route: Pick<RequestRoute, "credentialSource" | "carrier" | "carrierBag">): RouteCredentialPairingRow | undefined;
/** A route as a value this engine did not build carries it (a host Brain's message, an adapter's request): each member
 *  read once, and the whole value admitted only as a shape some request carries — a {@link ROUTE_CREDENTIAL_PAIRING}
 *  row plus a closed-set root. Anything else is no route (absent), never a partial one. */
export declare function admittedRequestRoute(value: unknown): RequestRoute | undefined;