@sema-agent/server 7.130.0 → 7.132.0

package/dist/hooks/hook-llm.js

@@ -1,10 +1,11 @@
-import { adjudicateModelRoute, joinRequestUrl, resolveRouteCredential, routeKeyOf, routeRefusalText } from "@sema-agent/core";
-import { matchCatalogModel, refusedCatalogEntry } from "../model-select.js";
+import { admitRouteRequest, BrainError, joinRequestUrl, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
+import { matchCatalogModel, refusedCatalogEntry, servedModelTableLeg } from "../model-select.js";
 import { modelUnavailableMessage } from "../model-entry-refusal.js";
 import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
-import { dispatchBrainLane } from "../model-provider.js";
+import { anthropicRouteRoot, brainLaneFor, routeTableOf } from "../model-provider.js";
 import { egressRedirectRefusal } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
+const unresolvedPick = (error) => ({ ok: false, error, code: "model_unresolved" });
 export function buildHookFailureText(raw) {
     if (raw === "")
         return raw;
@@ -15,68 +16,86 @@ export function buildHookFailureText(raw) {
         return `[hook failure text withheld: redactor threw ${err instanceof Error ? err.name : typeof err}]`;
     }
 }
+const ROUTE_REFUSAL_CODES = {
+    "route.credential_mismatch": true,
+    "route.credential_missing": true,
+    "route.credential_origin_mismatch": true,
+    "route.credential_answer_conflict": true,
+};
+const ROUTE_REFUSAL_LEAD = "[invalid_request] ";
+function gateRefusal(pick, e, declaredRoot) {
+    const raw = e instanceof Error ? e.message : String(e);
+    const text = e instanceof BrainError && raw.startsWith(ROUTE_REFUSAL_LEAD) ? raw.slice(ROUTE_REFUSAL_LEAD.length) : raw;
+    const code = Object.keys(ROUTE_REFUSAL_CODES).find((c) => text.startsWith(`${c}:`)) ?? "unclassified";
+    return {
+        ok: false,
+        code: "route_refused",
+        error: `hook model "${pick.catalogRef}" cannot be routed (${code}) — ` + buildDisplaySafeRefusal(text, [pick.baseUrl, declaredRoot ?? ""]),
+    };
+}
 export function createHookLlm(deps) {
     const { config, metrics } = deps;
-    const anthropicRouteBaseUrl = () => config.anthropic?.baseUrl || "https://api.anthropic.com";
-    const shapeFrom = (catalogRef, m, providerModelId) => {
-        const lane = dispatchBrainLane(m?.provider, config.anthropic !== undefined);
+    const anthropicRouteBaseUrl = () => anthropicRouteRoot(config.anthropic ?? {});
+    const shapeFrom = (m, providerModelId = m.id) => {
+        const catalogRef = m.name;
+        const lane = brainLaneFor(m.provider, routeTableOf(config));
         switch (lane) {
             case "anthropic":
-                return { ok: true, catalogRef, providerModelId, baseUrl: m?.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages" };
+                return { ok: true, catalogRef, providerModelId, baseUrl: m.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages" };
             case "gateway": {
-                const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m?.baseUrl, config.gatewayBaseUrl);
-                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : { ok: false, error: endpoint.refusal };
+                const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m, config.gatewayBaseUrl, servedModelTableLeg(config));
+                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : unresolvedPick(endpoint.refusal);
             }
         }
     };
     const hookModelFor = (requested) => {
-        const shape = (ref) => shapeFrom(ref, config.models[ref], config.models[ref]?.id ?? ref);
+        const ownEntry = (ref) => (Object.hasOwn(config.models, ref) ? config.models[ref] : undefined);
         const unavailable = (field, ref) => {
-            if (config.models[ref] !== undefined)
+            if (ownEntry(ref) !== undefined)
                 return undefined;
             const hit = refusedCatalogEntry(ref, config.modelRefusals);
-            return hit === undefined ? undefined : { ok: false, error: modelUnavailableMessage(field, ref, hit.name, hit.refusal) };
+            return hit === undefined ? undefined : unresolvedPick(modelUnavailableMessage(field, ref, hit.name, hit.refusal));
         };
         if (requested === undefined) {
             const sum = config.roles.summarize;
             const roleModel = typeof sum === "string" ? sum : sum && typeof sum === "object" && "model" in sum && typeof sum.model === "string" ? sum.model : undefined;
-            if (roleModel !== undefined)
-                return unavailable("summarize role model", roleModel) ?? (config.models[roleModel] ? shape(roleModel) : shapeFrom(config.model.id, config.model, roleModel));
-            return shapeFrom(config.model.id, config.model, config.model.id);
+            if (roleModel !== undefined) {
+                const entry = ownEntry(roleModel);
+                return unavailable("summarize role model", roleModel) ?? (entry ? shapeFrom(entry) : shapeFrom(config.model, roleModel));
+            }
+            return shapeFrom(config.model);
         }
-        if (config.models[requested])
-            return shape(requested);
+        const matchedKey = matchCatalogModel(requested, config.models, config.modelRefusals);
+        if (matchedKey !== undefined)
+            return shapeFrom(config.models[matchedKey]);
         if (Object.hasOwn(config.modelRefusals ?? {}, requested))
             return unavailable("hook model", requested);
-        const byId = matchCatalogModel(requested, config.models, config.modelRefusals);
-        if (byId !== undefined)
-            return shape(byId);
         if (requested === config.model.id)
-            return shapeFrom(requested, config.model, requested);
-        return unavailable("hook model", requested) ?? { ok: false, error: `hook model "${requested}" is not in this deployment's catalog` };
+            return shapeFrom(config.model);
+        return unavailable("hook model", requested) ?? unresolvedPick(`hook model "${requested}" is not in this deployment's catalog`);
     };
     const judgeRoute = (pick, perModelKey, deploymentKey, declaredRoot) => {
         const credential = resolveRouteCredential({
             ...(perModelKey !== undefined ? { optionsApiKey: perModelKey } : {}),
             ...(deploymentKey !== undefined ? { configApiKey: deploymentKey } : {}),
         });
-        const verdict = adjudicateModelRoute({ id: pick.catalogRef, baseUrl: pick.baseUrl }, credential, { ...(declaredRoot !== undefined ? { baseUrl: declaredRoot } : {}) });
-        if (!verdict.ok) {
-            return {
-                ok: false,
-                error: `hook model "${pick.catalogRef}" cannot be routed (${verdict.code}) — ` +
-                    buildDisplaySafeRefusal(routeRefusalText(verdict), [pick.baseUrl, declaredRoot ?? ""]),
-            };
+        let admission;
+        try {
+            admission = admitRouteRequest({ id: pick.catalogRef, baseUrl: pick.baseUrl }, credential, { ...(declaredRoot !== undefined ? { baseUrl: declaredRoot } : {}) });
         }
-        if (verdict.posture === "keyless" && routeKeyOf(pick.baseUrl) !== routeKeyOf(declaredRoot)) {
+        catch (e) {
+            return gateRefusal(pick, e, declaredRoot);
+        }
+        if (credential.source === "absent" && routeKeyOf(pick.baseUrl) !== routeKeyOf(declaredRoot)) {
             return {
                 ok: false,
+                code: "route_refused",
                 error: `hook model "${pick.catalogRef}" points at ${pick.baseUrl}, which this deployment did not declare as its own endpoint, ` +
                     `and no per-model credential resolved — refusing to send the prompt there (it embeds user content; an unauthenticated ` +
                     `request still hands that content to whoever operates that URL)`,
             };
         }
-        return { ok: true, credential };
+        return { ok: true, credential, admission };
     };
     const fetchImpl = deps.fetchImpl ?? fetch;
     const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
@@ -85,6 +104,7 @@ export function createHookLlm(deps) {
             return pick;
         const ac = new AbortController();
         const t = setTimeout(() => ac.abort(), timeoutMs);
+        let phase = "assemble";
         try {
             const keyResolver = deps.getKeyResolver();
             let perModelKey;
@@ -93,17 +113,21 @@ export function createHookLlm(deps) {
                     perModelKey = (await keyResolver({ name: pick.catalogRef }))?.apiKey;
                 }
                 catch (e) {
-                    return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})` };
+                    return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})`, code: "credential_custody_failed" };
                 }
             }
             let url;
             let headers;
             let body;
+            let admitted;
+            let declaredRoot;
             if (pick.api === "anthropic-messages") {
                 const routeBase = anthropicRouteBaseUrl();
+                declaredRoot = routeBase;
                 const routed = judgeRoute(pick, perModelKey, config.anthropic?.authToken ?? config.anthropic?.apiKey, routeBase);
                 if (!routed.ok)
                     return routed;
+                admitted = routed.admission;
                 url = joinRequestUrl(pick.baseUrl, "/v1/messages");
                 headers = {
                     "content-type": "application/json",
@@ -121,29 +145,47 @@ export function createHookLlm(deps) {
                 body = JSON.stringify({ model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] });
             }
             else {
+                declaredRoot = config.gatewayBaseUrl;
                 const routed = judgeRoute(pick, perModelKey, config.gatewayApiKey, config.gatewayBaseUrl);
                 if (!routed.ok)
                     return routed;
+                admitted = routed.admission;
                 const hookKey = routed.credential.apiKey;
                 url = joinRequestUrl(pick.baseUrl, "/chat/completions");
                 headers = { "content-type": "application/json", ...(hookKey ? { authorization: `Bearer ${hookKey}` } : {}) };
                 body = JSON.stringify({ model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false });
             }
+            try {
+                admitted();
+            }
+            catch (e) {
+                return gateRefusal(pick, e, declaredRoot);
+            }
+            phase = "transport";
             const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal, redirect: "manual" });
             const redirected = egressRedirectRefusal(r, "declare the final endpoint as this route's base URL");
             if (redirected !== undefined)
                 return { ok: false, error: `hook llm ${redirected}`, code: "redirect_refused" };
             if (!r.ok)
-                return { ok: false, error: `hook llm HTTP ${r.status}` };
+                return { ok: false, error: `hook llm HTTP ${r.status}`, code: "bad_response" };
+            let answered;
+            try {
+                answered = await r.json();
+            }
+            catch (e) {
+                if (ac.signal.aborted || e?.name !== "SyntaxError")
+                    throw e;
+                return { ok: false, error: "hook llm answered with a body that is not JSON", code: "bad_response" };
+            }
             let text;
             if (pick.api === "anthropic-messages") {
-                const j = (await r.json());
-                const parts = (Array.isArray(j.content) ? j.content : []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text);
+                const j = answered;
+                const parts = (Array.isArray(j?.content) ? j.content : []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text);
                 text = parts.length > 0 ? parts.join("") : undefined;
             }
             else {
-                const j = (await r.json());
-                text = j.choices?.[0]?.message?.content ?? undefined;
+                const j = answered;
+                text = j?.choices?.[0]?.message?.content ?? undefined;
             }
             metrics.inc("hook_llm_calls_total", { type: "prompt" });
             return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content", code: "no_content" };
@@ -153,6 +195,7 @@ export function createHookLlm(deps) {
             return {
                 ok: false,
                 error: ac.signal.aborted ? "hook llm timeout" : `hook llm request to ${pick.baseUrl} failed: ${String(e)}${cause ? ` (${String(cause)})` : ""}`,
+                code: ac.signal.aborted || phase === "transport" ? "unreachable" : "route_refused",
             };
         }
         finally {