@sema-agent/server 7.132.0 → 7.133.0

package/dist/web-admin-client/apply-effective.js

@@ -64,7 +64,27 @@ export function mutateInPlace(target, source) {
     Object.assign(target, source);
 }
 const appliedGeneration = new WeakMap();
-const envRolesBaseline = new WeakMap();
+const envModelPlane = new WeakMap();
+function envModelPlaneOf(config) {
+    let snap = envModelPlane.get(config);
+    if (snap === undefined) {
+        snap = {
+            models: { ...config.models },
+            model: config.envModel,
+            modelApiKeyEnv: { ...config.modelApiKeyEnv },
+            modelApiKeys: { ...config.modelApiKeys },
+            modelRefusals: { ...config.modelRefusals },
+            droppedCatalogEntries: [...config.droppedCatalogEntries],
+            quotaWeights: { ...config.modelQuotaWeights },
+            roles: { ...config.roles },
+            activeTiers: { ...config.tiers },
+            atMention: config.atMention,
+            infoLine: {},
+        };
+        envModelPlane.set(config, snap);
+    }
+    return snap;
+}
 function stageAtMention(raw, usableNames, logger) {
     const read = readAtMention(raw);
     if (read === undefined) {
@@ -172,7 +192,7 @@ function commitStaged(config, staged) {
         config.droppedCatalogEntries = mp.droppedCatalogEntries;
         mutateInPlace(config.modelQuotaWeights, mp.quotaWeights);
         mutateInPlace(config.models, mp.models);
-        config.model = config.models.default;
+        config.model = mp.model;
         mutateInPlace(config.roles, mp.roles);
         mutateInPlace(config.tiers, mp.activeTiers);
         config.atMention = mp.atMention;
@@ -227,7 +247,38 @@ function modelPlaneGroupReport(group) {
     };
 }
 const ROLE_BINDING_UNAVAILABLE_HINT = "tasks resolving this role fail: alias/tier expansion cannot mint this name; the engine refuses it loud — bind the role to a usable model, or make the entry usable (see the entry's own warn)";
+export const NO_CENTER_EFFECTIVE = deepFreeze({ version: 0, updatedAt: "", models: { models: [], roles: {} }, mcp: { servers: [] } });
+export const isNoCenterEffective = (eff) => eff === NO_CENTER_EFFECTIVE;
+function deepFreeze(v) {
+    if (v !== null && typeof v === "object") {
+        for (const x of Object.values(v))
+            deepFreeze(x);
+        Object.freeze(v);
+    }
+    return v;
+}
+function stageEnvModelPlane(config) {
+    if (servedModelTableLeg(config) === "env")
+        return { stages: {} };
+    const snap = envModelPlane.get(config);
+    if (snap === undefined)
+        throw new Error("applyEffective: the center model plane is in force but no env snapshot was taken — the model plane was written outside applyEffective, so the no-center tier has no baseline to return to");
+    return {
+        stages: {
+            models: {
+                ...snap,
+                modelApiKeyEnv: { ...snap.modelApiKeyEnv },
+                modelApiKeys: { ...snap.modelApiKeys },
+                modelRefusals: { ...snap.modelRefusals },
+                droppedCatalogEntries: [...snap.droppedCatalogEntries],
+                infoLine: { source: "no-center-baseline", default: snap.model.id, roles: Object.keys(snap.roles), tiers: [], atMention: snap.atMention.mode },
+            },
+        },
+    };
+}
 function stageModelPlane(config, eff, logger, sealedKeys) {
+    if (isNoCenterEffective(eff))
+        return stageEnvModelPlane(config);
     const enabled = (eff.models?.models ?? []).filter((m) => m.enabled !== false);
     const verdict = judgeCatalogEntries(enabled, { anthropicRouteMounted: config.anthropic !== undefined }, eff.models?.droppedCatalogEntries);
     if (enabled.length === 0 && verdict.malformed.length === 0 && verdict.dropped.every((row) => row.identity?.enabled === false))
@@ -293,8 +344,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
                     quotaWeights[m.id] = qw;
             }
         }
-        if (!envRolesBaseline.has(config))
-            envRolesBaseline.set(config, { ...config.roles });
+        const envPlane = envModelPlaneOf(config);
         const centerRoles = {};
         for (const [role, tgt] of Object.entries(eff.models.roles ?? {})) {
             if ("model" in tgt)
@@ -302,7 +352,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
             else if ("select" in tgt)
                 centerRoles[role] = { select: tgt.select };
         }
-        const roles = { ...envRolesBaseline.get(config), ...centerRoles };
+        const roles = { ...envPlane.roles, ...centerRoles };
         const activeTiers = {};
         for (const [tier, target] of Object.entries(resolveActiveTiers(eff.models) ?? {})) {
             if (models[target] !== undefined) {
@@ -365,6 +415,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
         const defaultModel = models.default;
         const plane = {
             models,
+            model: defaultModel,
             modelApiKeyEnv,
             modelApiKeys,
             modelRefusals: { ...verdict.refused },

package/dist/web-admin-client/facade.d.ts

@@ -48,7 +48,7 @@
  * importers to update, which was done in the same commit.
  */
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
-export { mutateInPlace, applyEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
+export { mutateInPlace, applyEffective, NO_CENTER_EFFECTIVE, isNoCenterEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type EngineRestartSignal, } from "./restart-signal.js";
 export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS, type CenterReadFaceApply, type CenterReadFaceReport, type ReadFaceBaseline, type ReadFaceSeat } from "./read-face.js";

package/dist/web-admin-client/facade.js

@@ -1,5 +1,5 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
-export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
+export { mutateInPlace, applyEffective, NO_CENTER_EFFECTIVE, isNoCenterEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, } from "./restart-signal.js";
 export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS } from "./read-face.js";

package/dist/web-admin-client/read-face.js

@@ -1,4 +1,5 @@
 import { compileReadDeny, isSwappableDepSeat, resolveReadDenyBuiltins } from "@sema-agent/core";
+import { readReadDenyEntry } from "../read-deny-entry.js";
 export function buildReadFaceBaseline(config) {
     return {
         ...(config.readFace !== undefined ? { readFace: config.readFace } : {}),
@@ -44,15 +45,10 @@ function normalizeDenyPatterns(raw) {
     if (!Array.isArray(raw))
         throw new ReadFaceDomainError("readFace.denyPatterns must be an array of \"pattern\" strings or {pattern, caseSensitive?} objects");
     return raw.map((it, i) => {
-        if (typeof it === "string")
-            return { pattern: it, caseSensitive: false };
-        if (typeof it !== "object" || it === null || typeof it.pattern !== "string") {
-            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}] must be a string or an object with a string 'pattern'`);
-        }
-        const cs = it.caseSensitive;
-        if (cs !== undefined && typeof cs !== "boolean")
-            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}].caseSensitive must be boolean when present`);
-        return { pattern: it.pattern, caseSensitive: cs === true };
+        const read = readReadDenyEntry(it);
+        if (!read.ok)
+            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}]${read.after}`);
+        return read.entry;
     });
 }
 function assertFace(raw) {

package/dist/web-admin-client/skills-mcp.js

@@ -2,9 +2,8 @@ import { readMcpSourceLabel } from "../mcp-source-label.js";
 import { readMcpToolFaces } from "../mcp-tool-faces.js";
 import { skillContentHash } from "@sema-agent/settings-schema";
 import { readMcpToolAxes } from "@sema-agent/core";
-import { MCP_CONTENT_ORIGINS, isContentOriginWord, isUsableWireName } from "@sema-agent/settings-schema";
-import { describeBadContentOrigin, describeBadWireName } from "../caller-text-echo.js";
-import { noteMcpAssertionHeaderNotSent } from "../mcp-assertion-header.js";
+import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, isContentOriginWord, isUsableWireName } from "@sema-agent/settings-schema";
+import { noteMcpAssertionHeaderNotSent, sentMcpAssertionHeaderMember, withholdsMcpAssertionHeader } from "../mcp-assertion-header.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
 function skillBodyPresent(body) {
     return body !== undefined && body !== "";
@@ -150,11 +149,11 @@ export function resolveMcpServers(mcp, logger) {
             const headers = resolveRefs(s.transport.headerRefs, s.name, "header", logger);
             if (headers === null)
                 continue;
-            if (s.transport.assertionHeader !== undefined)
+            if (withholdsMcpAssertionHeader(s.transport.assertionHeader))
                 noteMcpAssertionHeaderNotSent(logger, s.name);
             out.push({
                 scenarios: s.scenarios ?? [],
-                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
+                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}), ...sentMcpAssertionHeaderMember(s.transport.assertionHeader) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
             });
         }
     }

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -20,7 +20,8 @@ dials the device, so the device needs no inbound port, no public address and no
 (this deployment has no device lane) or an object `{ enabled: true, protocolVersion, maxInflightPerDevice,
 wsPath, management }`. Read `wsPath` from there rather than hardcoding it: the path is part of the wire
 contract and reading it means a future path change is not a cross-repo break. `protocolVersion` tells you
-which version the server speaks before you spend a handshake finding out.
+which protocol **revision** the server speaks before you spend a handshake finding out (§2.1: the revision decides
+which `errorCode` words the server accepts from you).
 
 ---
 
@@ -144,6 +145,13 @@ The server sends `challenge` immediately on open. From the moment the socket ope
 the handshake completes, **frames are capped at `maxPreAuthFrameBytes` (4096 bytes)** and a malformed
 pre-auth frame closes the connection outright.
 
+**Which revision to declare.** `challenge.protocolVersion` is the highest protocol revision this server speaks
+(`DEVICE_MIN_PROTOCOL_VERSION` is the lowest it accepts, §2.1). Put the highest revision *you* implement that is
+not above `challenge.protocolVersion` into `hello.protocolVersion` — the same integer you sign (§1.3) — and emit
+only the `errorCode` words of that revision (the revision table in §2.1). Nothing is renegotiated after `hello`:
+the revision you declared is the contract for the whole connection. If the highest revision you implement is below
+`DEVICE_MIN_PROTOCOL_VERSION`, the server answers `helloReject: protocol_version_unsupported` (§1.4).
+
 ### 1.3 The `hello` signature (byte-exact — do not improvise)
 
 Sign with the device private key over exactly these bytes:
@@ -245,18 +253,32 @@ backoff, exponential to a 60 s ceiling, jittered — except for `revoked`, which
 
 `helloAck` carries:
 
+<!-- closed-set: DEVICE_HELLO_ACK_BOUNDS -->
+
 | Field | Form | Meaning |
 |---|---|---|
 | `ok` | always `true` | — |
-| `heartbeatIntervalMs` | integer ms | how often you should send `heartbeat` (deployment default 15000) |
-| `maxInflight` | integer | how many instructions the server will have outstanding on this device at once (deployment default 4) |
+| `heartbeatIntervalMs` | `integer ms ≥ 1` | how often you should send `heartbeat` (deployment default 15000) |
+| `maxInflight` | `integer ≥ 1` | how many instructions the server will have outstanding on this device at once (deployment default 4) |
 | `gen` | **canonical decimal string** (`"7"`, never `7`, never `"07"`) | the connection generation. Stamp it on every frame you send |
 | `pendingInstructions` | `string[]` | instruction ids the server still considers in flight for you — see §5 R2 |
 | `chunkWatermarks` | `{ [instructionId]: number }` | per instruction, the highest **contiguous** `streamSeq` the server has already accepted. `-1` means "nothing accepted yet" |
-| `reconnectGraceMs` | integer ms | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
-| `cancelGraceMs` | integer ms | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
-| `chunkGapTimeoutMs` | integer ms | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
-| `executionCeilingGraceMs` | integer ms | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+| `reconnectGraceMs` | `integer ms ≥ 0` | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
+| `cancelGraceMs` | `integer ms ≥ 0` | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
+| `chunkGapTimeoutMs` | `integer ms ≥ 0` | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
+| `executionCeilingGraceMs` | `integer ms ≥ 0` | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+
+**Bounds.** The six numeric fields above are validated by the server when it starts: a deployment whose knob (or
+embedding option) is outside its row's range refuses to boot — the value is never clamped and never replaced by a
+default — so a `helloAck` on the wire is always in range, and every number in it is the value the server's own
+timers and slot counts are armed with. Every `ms` field is also at most `2147483647` (the largest delay a
+timer can hold; a larger value would be silently collapsed to 1 ms); `maxInflight` has no ceiling beyond an
+integer JSON represents exactly (at most `9007199254740991`). A `0` grace means "no grace": that timer
+fires at once. An executor that reads a value outside its row's range must treat it as a protocol violation — the executor-side twin
+of the server's `bad_shape` refusal (§2.4): close the connection and reconnect with backoff — and must **not** read the
+out-of-range value as the default.
+`deviceHelloAckNumberFlaw` (from `@sema-agent/server/device-protocol`) is the same check the server applies.
+The *absence* of one of the four grace fields is a different case, described below, and still means "not told".
 
 The four grace fields are the values the server's own timers are armed with — not documentation defaults. Size
 your reconnect backoff ceiling, your `cancel` answer deadline, your retransmission cadence and your own
@@ -314,8 +336,8 @@ base64 inside JSON fields.
 | Constant | Value | Meaning |
 |---|---|---|
 | `DEVICE_WS_PATH` | `/v1/device/ws` | the upgrade path (prefer the `wsPath` from `/v1/capabilities`) |
-| `DEVICE_PROTOCOL_VERSION` | `1` | the version this server speaks |
-| `DEVICE_MIN_PROTOCOL_VERSION` | `1` | the lowest version it accepts; below it, a loud `helloReject` — never a silent downgrade |
+| `DEVICE_PROTOCOL_VERSION` | `2` | the protocol revision this server speaks (the highest it accepts) |
+| `DEVICE_MIN_PROTOCOL_VERSION` | `1` | the lowest revision it accepts; below it (or above the highest), a loud `helloReject` — never a silent downgrade |
 | `DEVICE_HELLO_DOMAIN_TAG` | `sema.device.hello.v1` | the handshake signature domain tag (§1.3) |
 
 <!-- closed-set: DEVICE_WS_LIMITS -->
@@ -330,6 +352,29 @@ base64 inside JSON fields.
 Note the asymmetry: the transport cap is 1 MiB, and the 4096-byte pre-auth cap is applied **after** the
 frame has been reassembled. Keep `hello` small; it is not a place for long `supports` prose.
 
+#### Protocol revisions and the `errorCode` set
+
+The protocol revision is the only thing an executor can read *before* it sends `hello` (the `challenge` frame
+carries it), so the set of `errorCode` words the server accepts from you is a function of the revision, not a
+separate list. The table gives, per revision, the words **added** at that revision; the set at revision *N* is
+the union of the rows up to *N*, and the full set at the current revision is the §3.3 table.
+
+<!-- closed-set: DEVICE_OUTCOME_ERROR_CODES_BY_REVISION -->
+
+| Revision | `errorCode` words added at this revision |
+|---|---|
+| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` |
+| `2` | `liveness_no_output` |
+
+Rules: adding a frame or a field is additive and does not raise the revision; adding a word to a closed set the
+server *accepts from you* (today: the `errorCode` set) raises `DEVICE_PROTOCOL_VERSION` and adds a row here; a
+released row never changes. Declare a revision as §1.2 says and send only the words of that revision: an executor
+that declared revision 1 never sends `liveness_no_output` (the server does not police this per connection — it
+decodes every connection against the current revision's full set — but a word above your declared revision is outside
+your contract). The same sets are importable:
+`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` and `deviceOutcomeErrorCodesAt(revision)` from
+`@sema-agent/server/device-protocol`.
+
 ### 2.2 Device → server frames
 
 <!-- closed-set: DEVICE_FRAME_TYPES -->
@@ -515,6 +560,9 @@ a moment ago. If you omit `created`, the consumer reports the weaker of the two
 
 `message` is required on the failure arm and is shown to the model — make it specific.
 
+This is the full set at the current revision (`2`); the revision table in §2.1 says which revision each word arrived
+with, and an executor sends only the words of the revision it declared (§1.2).
+
 <!-- closed-set: DEVICE_OUTCOME_ERROR_CODES -->
 
 | `errorCode` | Use it when |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.132.0",
+  "version": "7.133.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -18,6 +18,10 @@
       "types": "./dist/device-protocol.d.ts",
       "default": "./dist/device-protocol.js"
     },
+    "./model-route-env": {
+      "types": "./dist/model-route-env.d.ts",
+      "default": "./dist/model-route-env.js"
+    },
     "./package.json": "./package.json",
     "./deploy/sema-up/lanes.json": "./deploy/sema-up/lib/lanes.json"
   },
@@ -65,7 +69,7 @@
   },
   "dependencies": {
     "@sema-agent/core": "7.53.0",
-    "@sema-agent/settings-schema": "14.0.0",
+    "@sema-agent/settings-schema": "14.2.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",
@@ -80,7 +84,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "23.1.0",
+    "@sema-agent/sdk": "24.0.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",