@sema-agent/server 7.131.0 → 7.133.0

package/dist/task-mcp.js

@@ -1,22 +1,16 @@
 import { mcpInjectionDroppedNotice, readMcpToolAxes, resolveComplianceDenies } from "@sema-agent/core";
-import { describeBadWireName, isUsableWireName } from "./wire-name-bound.js";
+import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, describeNotStringArray, describeValueShape, isContentOriginWord, isStringArray, isUsableWireName, readRequestMcpTransport, stripControlAndBidi, } from "@sema-agent/settings-schema";
 import { HttpError, createCodedHttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
-import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "./mcp-content-origin.js";
 import { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
-import { declaresMcpAssertionHeader, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, readMcpIdentityHeaders, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
-import { echoKeyName } from "./request-key-closure.js";
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, specWithholdsMcpAssertionHeader, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
+import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { readMcpToolFaces } from "./mcp-tool-faces.js";
 export const MAX_REQUEST_MCP_SERVERS = 32;
 export const MAX_REQUEST_MCP_DROP_NAMES = MAX_REQUEST_MCP_SERVERS;
-export const MCP_SERVER_ENTRY_KEYS = ["allowTools", "contentOrigin", "elicitation", "name", "source", "toolAxes", "toolFaces", "transport"];
+export const MCP_SERVER_ENTRY_KEYS = ["allowTools", "contentOrigin", "elicitation", "name", "source", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
 export const STDIO_MCP_TRANSPORT_KEYS = ["args", "command", "env", "kind"];
 export const HTTP_MCP_TRANSPORT_KEYS = ["assertionHeader", "headers", "kind", "principalHeader", "url"];
-export const MCP_ENTRY_EMPTY_RECORD_KEYS = ["toolAxes", "toolFaces"];
-export const MCP_ENTRY_EMPTY_ARRAY_KEYS = ["allowTools"];
-export const MCP_TRANSPORT_EMPTY_RECORD_KEYS = ["env", "headers"];
-export const MCP_TRANSPORT_EMPTY_ARRAY_KEYS = ["args"];
 export function mcpInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("mcp") === true)
         return false;
@@ -24,83 +18,12 @@ export function mcpInjectionHonored(config) {
         return false;
     return config.requirePrincipal !== true;
 }
-function isStringRecord(v) {
-    return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
-}
 function isRecord(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
 }
-function isStringArray(v) {
-    return Array.isArray(v) && v.every((a) => typeof a === "string");
-}
 function isElicitationFlag(v) {
     return typeof v === "boolean";
 }
-function describeShape(v) {
-    if (v === undefined)
-        return "nothing (the key is absent)";
-    if (v === null)
-        return "null";
-    if (Array.isArray(v))
-        return "an array";
-    if (typeof v === "string")
-        return v.length === 0 ? "an empty string" : `a string of ${v.length} characters`;
-    if (typeof v === "object")
-        return "an object";
-    return `a ${typeof v}`;
-}
-function describeNotStringArray(v) {
-    return Array.isArray(v) ? "an array with a non-string element" : describeShape(v);
-}
-function describeNotStringRecord(v) {
-    return isRecord(v) ? "an object with a non-string value" : describeShape(v);
-}
-const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
-function readRequestTransport(t) {
-    if (!t || typeof t !== "object")
-        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeShape(t)}`);
-    const tr = t;
-    const lost = [];
-    if (tr.kind === "stdio") {
-        if (typeof tr.command !== "string" || tr.command.length === 0)
-            return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeShape(tr.command)}`);
-        if (tr.args !== undefined && !isStringArray(tr.args))
-            lost.push({ path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(tr.args)}` });
-        if (tr.env !== undefined && !isStringRecord(tr.env))
-            lost.push({ path: "transport.env", reason: `must be an object of string values — got ${describeNotStringRecord(tr.env)}` });
-        return {
-            ok: true,
-            transport: {
-                kind: "stdio",
-                command: tr.command,
-                ...(isStringArray(tr.args) ? { args: tr.args } : {}),
-                ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
-            },
-            lost,
-        };
-    }
-    if (tr.kind === "http") {
-        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
-            return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
-        const ids = readMcpIdentityHeaders(tr);
-        if (tr.headers !== undefined && !isStringRecord(tr.headers))
-            lost.push({ path: "transport.headers", reason: `must be an object of string values — got ${describeNotStringRecord(tr.headers)}` });
-        if (tr.principalHeader !== undefined && ids.principalHeader === undefined) {
-            lost.push({ path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeShape(tr.principalHeader)}` });
-        }
-        return {
-            ok: true,
-            transport: {
-                kind: "http",
-                url: tr.url,
-                ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
-                ...ids,
-            },
-            lost,
-        };
-    }
-    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeShape(tr.kind)}`);
-}
 const bad = (field) => ({ ok: false, field });
 const MALFORMED_NAME = "<malformed>";
 function declaredName(e) {
@@ -114,7 +37,7 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     const o = e;
     if (!isUsableWireName(o.name))
         return bad("name");
-    const read = readRequestTransport(o.transport);
+    const read = readRequestMcpTransport(o.transport);
     if (!read.ok)
         return bad(read.issue.path);
     const spec = { name: o.name, transport: read.transport };
@@ -129,10 +52,10 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     let judged = axes;
     let toolAxesReread;
     if (!axes.ok && storedToolAxes !== undefined) {
-        const again = readMcpToolAxes(storedToolAxes(o.toolAxes));
+        const again = readMcpToolAxes(storedToolAxes.mcp(o.toolAxes));
         if (again.ok) {
             judged = again;
-            toolAxesReread = axes.problem.replace(CONTROL_AND_BIDI_STRIP_RE, "");
+            toolAxesReread = stripControlAndBidi(axes.problem);
         }
     }
     if (!judged.ok)
@@ -146,12 +69,14 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
             noteBadOrigin(spec.name, o.contentOrigin);
     }
     Object.assign(spec, readMcpSourceLabel(spec.name, o.source));
+    if (o.startupTimeoutMs !== undefined)
+        spec.startupTimeoutMs = o.startupTimeoutMs;
     const faces = readMcpToolFaces(o.toolFaces);
     if (!faces.ok)
         return bad("toolFaces");
     if (faces.faces !== undefined)
         spec.toolFaces = faces.faces;
-    return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}) };
+    return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}), transportLost: read.lost };
 }
 export function validateRequestMcp(raw) {
     if (raw !== undefined && raw !== null && !Array.isArray(raw))
@@ -164,19 +89,22 @@ function validateRequestMcpEntries(raw, storedToolAxes) {
     const dropped = [];
     const badContentOrigin = [];
     const toolAxesReread = [];
+    const transportLost = [];
     for (const e of raw.slice(0, MAX_REQUEST_MCP_SERVERS)) {
         const v = normalizeServer(e, (server, value) => badContentOrigin.push({ server, value: describeBadContentOrigin(value) }), storedToolAxes);
         if (v.ok) {
             ok.push(v.spec);
             if (v.toolAxesReread !== undefined)
                 toolAxesReread.push({ server: v.spec.name, problem: v.toolAxesReread });
+            if (v.transportLost.length > 0)
+                transportLost.push({ server: v.spec.name, lost: v.transportLost.map((i) => i.path) });
         }
         else
             dropped.push({ server: declaredName(e), reason: "malformed_entry", field: v.field });
     }
     for (const e of raw.slice(MAX_REQUEST_MCP_SERVERS, MAX_REQUEST_MCP_SERVERS + MAX_REQUEST_MCP_DROP_NAMES))
         dropped.push({ server: declaredName(e), reason: "over_cap" });
-    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin, toolAxesReread };
+    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin, toolAxesReread, transportLost };
 }
 export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
     if (!lockedKeys.has("mcp"))
@@ -195,7 +123,7 @@ export function requestEntryIdentityIssue(entry) {
         return undefined;
     return mcpIdentityHeadersIssue(t);
 }
-export function requestEntryIdentityRefusal(entry, at) {
+function requestEntryIdentityRefusal(entry, at) {
     const issue = requestEntryIdentityIssue(entry);
     if (issue === undefined || !isRecord(entry))
         return undefined;
@@ -205,14 +133,44 @@ export function requestEntryIdentityRefusal(entry, at) {
     const value = isRecord(transport) ? transport.assertionHeader : undefined;
     return entryFieldRefusal(entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
 }
-export function assertRequestMcpEntries(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (let i = 0; i < Math.min(bodyMcp.length, MAX_REQUEST_MCP_SERVERS); i++) {
-        const refusal = requestEntryRefusal(bodyMcp[i], `mcpServers[${i}]`);
+export function requestMcpDeclarationRefusal(list) {
+    if (list === undefined || list === null)
+        return undefined;
+    if (!Array.isArray(list))
+        return listRefusal(`mcpServers is ${describeValueShape(list)}, not an array of MCP server declarations`);
+    if (list.length > MAX_REQUEST_MCP_SERVERS)
+        return listRefusal(`mcpServers carries ${list.length} declarations, above this deployment's ceiling of ${MAX_REQUEST_MCP_SERVERS}`);
+    for (let i = 0; i < list.length; i++) {
+        const refusal = requestEntryRefusal(list[i], `mcpServers[${i}]`);
         if (refusal !== undefined)
-            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
+            return refusal;
     }
+    return undefined;
+}
+export function assertRequestMcpEntries(bodyMcp) {
+    const refusal = requestMcpDeclarationRefusal(bodyMcp);
+    if (refusal !== undefined)
+        throw createCodedHttpError(400, refusal.errorCode, refusal.message, refusal.unknownKeys === undefined ? undefined : { unknownKeys: [...refusal.unknownKeys] });
+}
+const LIST_REFUSAL_TAIL = "The request is refused rather than acting on part of the list: declarations that silently did not apply would read as in effect to whoever sent them. " +
+    "Fix the list (an empty list declares none).";
+function listRefusal(head) {
+    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}` };
+}
+const ENTRY_KEY_SET = new Set(MCP_SERVER_ENTRY_KEYS);
+const STDIO_TRANSPORT_KEY_SET = new Set(STDIO_MCP_TRANSPORT_KEYS);
+const HTTP_TRANSPORT_KEY_SET = new Set(HTTP_MCP_TRANSPORT_KEYS);
+const NO_TOLERATED_KEYS = new Set();
+function entryUnknownKeys(entry, at) {
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(entry, `${at}.`, ENTRY_KEY_SET, NO_TOLERATED_KEYS, buckets);
+    const t = entry.transport;
+    if (isRecord(t)) {
+        const keys = t.kind === "stdio" ? STDIO_TRANSPORT_KEY_SET : t.kind === "http" ? HTTP_TRANSPORT_KEY_SET : undefined;
+        if (keys !== undefined)
+            scanKeyClosure(t, `${at}.transport.`, keys, NO_TOLERATED_KEYS, buckets);
+    }
+    return buckets.unknown.sort();
 }
 const ENTRY_KEY_JUDGES = {
     allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
@@ -222,14 +180,15 @@ const ENTRY_KEY_JUDGES = {
         ? undefined
         : {
             path: "contentOrigin",
-            reason: `must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(o.contentOrigin)}` +
+            reason: `must be one of ${MCP_CONTENT_ORIGINS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(o.contentOrigin)}` +
                 ` (omit the key for the default: this server's tools classify as external content)`,
         },
-    elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeShape(o.elicitation)}` }),
+    elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeValueShape(o.elicitation)}` }),
     name: (o) => (isUsableWireName(o.name) ? undefined : { path: "name", reason: `must be a non-empty string within the wire-name length bound — got ${describeBadWireName(o.name)}` }),
     source: (o) => o.source === undefined || isMcpSourceLabel(o.source)
         ? undefined
-        : { path: "source", reason: `must be a non-empty string of at most ${MCP_SOURCE_LABEL_MAX} characters (a display label) — got ${describeShape(o.source)}` },
+        : { path: "source", reason: `must be a non-empty string of at most ${MCP_SOURCE_LABEL_MAX} characters (a display label) — got ${describeValueShape(o.source)}` },
+    startupTimeoutMs: () => undefined,
     toolAxes: (o) => {
         const read = readMcpToolAxes(o.toolAxes);
         return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
@@ -239,7 +198,7 @@ const ENTRY_KEY_JUDGES = {
         return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
     },
     transport: (o) => {
-        const read = readRequestTransport(o.transport);
+        const read = readRequestMcpTransport(o.transport);
         return read.ok ? read.lost[0] : read.issue;
     },
 };
@@ -249,12 +208,22 @@ function entryFieldRefusal(entry, at, issue) {
     const server = echoKeyName("", declaredName(entry));
     return {
         errorCode: "request.field_invalid",
-        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${issue.reason.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ${ENTRY_REFUSAL_TAIL}`,
+        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${stripControlAndBidi(issue.reason)}. ${ENTRY_REFUSAL_TAIL}`,
     };
 }
 function requestEntryRefusal(entry, at) {
     if (!isRecord(entry))
-        return undefined;
+        return listRefusal(`${at} is ${describeValueShape(entry)}, not an MCP server declaration (an object)`);
+    const unknownKeys = entryUnknownKeys(entry, at);
+    if (unknownKeys.length > 0) {
+        return {
+            errorCode: "request.body_shape",
+            message: `body: unrecognized key(s) on an MCP declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+                `${keyClosureClause(unknownKeys, "unknown (not an mcpServers[] key — check the spelling)")}. ` +
+                `Accepted per entry: ${[...MCP_SERVER_ENTRY_KEYS].sort().join(",")} (transport.kind "stdio": ${[...STDIO_MCP_TRANSPORT_KEYS].sort().join(",")}; "http": ${[...HTTP_MCP_TRANSPORT_KEYS].sort().join(",")})`,
+            unknownKeys: unknownKeys.slice(0, MAX_KEY_ECHO),
+        };
+    }
     const identity = requestEntryIdentityRefusal(entry, at);
     if (identity !== undefined)
         return identity;
@@ -265,12 +234,6 @@ function requestEntryRefusal(entry, at) {
     }
     return undefined;
 }
-export function requestEntryToolAxesRefusal(entry, at) {
-    if (!isRecord(entry))
-        return undefined;
-    const issue = ENTRY_KEY_JUDGES.toolAxes(entry);
-    return issue === undefined ? undefined : entryFieldRefusal(entry, at, issue);
-}
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
 }
@@ -311,7 +274,7 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
     if (v.badContentOrigin.length > 0) {
         logger?.warn("mcp_content_class_dropped", {
             entries: v.badContentOrigin,
-            allowed: CONTENT_ORIGIN_WORDS,
+            allowed: MCP_CONTENT_ORIGINS,
             note: "declaration DROPPED — these servers keep the pre-378 default (external content, session gets marked); the servers themselves still mount",
         });
     }
@@ -319,7 +282,7 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
     const closed = deploymentClosedMcpNames(baseline, reservedNames);
     const blocked = v.ok.filter((s) => closed.has(s.name)).map((s) => s.name);
     for (const s of v.ok)
-        if (declaresMcpAssertionHeader(s) && !closed.has(s.name))
+        if (specWithholdsMcpAssertionHeader(s) && !closed.has(s.name))
             noteMcpAssertionHeaderNotSent(logger, s.name);
     const mounted = new Set(v.ok.filter((s) => !closed.has(s.name)).map((s) => s.name));
     for (const e of entries.slice(0, MAX_REQUEST_MCP_SERVERS)) {
@@ -337,6 +300,18 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
             note: "this replayed request was stored before the upgrade and its toolAxes declaration does not pass the engine's reader; while one-time migration M19 is open it is read the way the pre-upgrade server read it (members that did not fit are dropped, a declaration that is not an object counts as none) and the server stays mounted — once the window closes the same request leaves this server unmounted",
         });
     }
+    for (const t of v.transportLost) {
+        if (!mounted.has(t.server))
+            continue;
+        logger?.warn("mcp_transport_members_dropped", {
+            server: t.server,
+            lost: t.lost.slice(0, MAX_KEY_ECHO),
+            ...(t.lost.length > MAX_KEY_ECHO ? { lostTotal: t.lost.length } : {}),
+            note: "this replayed request carries parts of this server's transport declaration that cannot be handed to the engine — an env / headers record that is not a plain object of string values (left out whole, as the pre-upgrade server read it), " +
+                "a member named \"__proto__\" in env / headers (only that member is left out: the engine refuses the name), args that are not a list of strings, a principalHeader that is not a string; " +
+                "the server mounts with the rest. A new submission with the same entry is refused (400)",
+        });
+    }
     return {
         mcp: mergeRequestMcp(baseline, v.ok.map(toCoreMcpServerSpec), reservedNames),
         drops: [...v.dropped, ...blocked.map((server) => ({ server, reason: "name_reserved_by_deployment" }))],