@sema-agent/server 7.136.0 → 7.138.0

package/dist/web-admin-client/skills-mcp.d.ts

@@ -1,6 +1,7 @@
 import { type A2aServerSpec, type McpServerSpec, type SkillSpec } from "@sema-agent/core";
 import type { CenterMcp, ScopedA2aPeer } from "../config-types.js";
 import type { Logger } from "../observability/logger.js";
+import { type PeerDesk, type PeerLease } from "../peer-seat.js";
 import type { LoadedSkill } from "../capabilities/skills.js";
 import type { ConfigProvider } from "../config-provider.js";
 import type { CenterA2aPeer, CenterMcpServer, CenterSkillManifest } from "./types.js";
@@ -53,14 +54,16 @@ export declare function applySkillsManifest(baseline: LoadedSkill[], manifest: {
 }, bodies: SkillBodySource, logger?: Logger): Promise<LoadedSkill[]>;
 /**
  * Resolve center MCP servers (`/effective.mcp`) into core `McpServerSpec`s + the scenarios each applies to.
- * env-NAME refs → real values from THIS service's env (secret boundary unchanged); a server with any missing
+ * env-NAME refs → real values from THIS service's env (secret boundary unchanged), registered on `desk` under `rosterLease`
+ * (the desk's one minting point `mintDeclaration`, called only for an entry that mounts — after every judge below has passed, so a skipped
+ * entry never holds a registration): the spec carries the minted reference, never the values. A server with any missing
  * ref is skipped (`resolveRefs` → null). `enabled:false` skipped. A server whose `toolFaces` / `toolAxes` declaration is
  * malformed is skipped whole (both are trust-root declarations — the engine's `readToolFaces` / `readMcpToolAxes` judge them). Restart-to-apply
  * (filtered per scenario in `resolveSpec` via `mcpForScenario`).
  */
 export declare function resolveMcpServers(mcp: {
     servers: CenterMcpServer[];
-}, logger?: Logger): CenterMcp;
+}, desk: Pick<PeerDesk, "declare">, rosterLease: PeerLease, logger?: Logger): CenterMcp;
 /** The MCP servers applicable to a scenario: tagged with it, or untagged (global). undefined when none.
  *  [ref]:alias 窗撤销,单键命中(同 `skillsForScenario`)。 */
 export declare function mcpForScenario(center: CenterMcp | undefined, scenario: string): McpServerSpec[] | undefined;
@@ -68,7 +71,8 @@ export declare function mcpForScenario(center: CenterMcp | undefined, scenario:
  * DESIGN-269 §2.1 —— resolve center A2A peers (`/effective.a2a`) into core `A2aServerSpec`s + the scenarios
  * each applies to. Exact sibling of {@link resolveMcpServers}, same three rules:
  *   · header-NAME refs → real values from THIS service's env (the secret boundary is unchanged — the center
- *     never holds the bearer). A peer with ANY missing ref is SKIPPED wholesale (`resolveRefs` → null):
+ *     never holds the bearer), registered on `desk` under `rosterLease` (`mintDeclaration`, only for a peer that mounts); the spec carries the minted
+ *     reference, never the values. A peer with ANY missing ref is SKIPPED wholesale (`resolveRefs` → null):
  *     dialing a remote AGENT with half the credentials is the wrong failure direction.
  *   · `enabled:false` skipped.
  *   · restart-to-apply (filtered per scenario in `resolveSpec` via {@link a2aForScenario}).
@@ -83,7 +87,7 @@ export declare function mcpForScenario(center: CenterMcp | undefined, scenario:
  */
 export declare function resolveA2aPeers(a2a: {
     peers: CenterA2aPeer[];
-}, logger?: Logger): ScopedA2aPeer[];
+}, desk: Pick<PeerDesk, "declare">, rosterLease: PeerLease, logger?: Logger): ScopedA2aPeer[];
 /** The A2A peers applicable to a scenario: tagged with it, or untagged (global). undefined when none.
  *  Twin of {@link mcpForScenario} — `undefined` (not `[]`) is load-bearing: an empty array would put an
  *  `a2a: []` key on the spec, i.e. "this deployment declares an empty peer set", where absence means

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

@@ -1,8 +1,9 @@
 import { readMcpSourceLabel } from "../mcp-source-label.js";
 import { skillContentHash } from "@sema-agent/settings-schema";
-import { readMcpToolAxes, readToolFaces } from "@sema-agent/core";
+import { judgeSessionMetaKey, readMcpToolAxes, readToolFaces } from "@sema-agent/core";
 import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, isContentOriginWord, isUsableWireName } from "@sema-agent/settings-schema";
-import { noteMcpAssertionHeaderNotSent, sentMcpAssertionHeaderMember, withholdsMcpAssertionHeader } from "../mcp-assertion-header.js";
+import { noteMcpAssertionHeaderNotSent, withholdsMcpAssertionHeader } from "../mcp-assertion-header.js";
+import { mintDeclaration, peerSentence } from "../peer-seat.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
 export function skillToolListsOf(source) {
     return {
@@ -115,7 +116,7 @@ function resolveRefs(refs, server, kind, logger, event = "web_admin_mcp_env_miss
     }
     return out;
 }
-export function resolveMcpServers(mcp, logger) {
+export function resolveMcpServers(mcp, desk, rosterLease, logger) {
     const out = [];
     const reservedNames = (mcp.servers ?? []).map((s) => s.name);
     for (const s of mcp.servers ?? []) {
@@ -147,7 +148,7 @@ export function resolveMcpServers(mcp, logger) {
         if (!facesRead.ok) {
             logger?.warn("web_admin_mcp_tool_faces_invalid", {
                 server: s.name,
-                problem: facesRead.problem,
+                problem: peerSentence(facesRead.problem),
                 note: "server SKIPPED — a toolFaces overlay is a NARROWING declaration (its pathTarget is what the sensitive-path / write fences read); mounting the server without it would silently drop the protection you declared. Fix the entry and republish.",
             });
             continue;
@@ -157,20 +158,31 @@ export function resolveMcpServers(mcp, logger) {
         if (!axesRead.ok) {
             logger?.warn("web_admin_mcp_tool_axes_invalid", {
                 server: s.name,
-                problem: axesRead.problem,
+                problem: peerSentence(axesRead.problem),
                 note: "server SKIPPED — a toolAxes declaration is a TRUST-ROOT declaration (it can lower an effect so a call skips the approval fence, or raise one); mounting the server without it, or with a half of it, would silently change what you declared. Fix the entry and republish.",
             });
             continue;
         }
         const toolAxes = axesRead.toolAxes === undefined ? {} : { toolAxes: axesRead.toolAxes };
+        const metaKey = judgeSessionMetaKey(s.sessionMetaKey);
+        if ("problem" in metaKey) {
+            logger?.warn("web_admin_mcp_session_meta_key_invalid", {
+                server: s.name,
+                problem: peerSentence(metaKey.problem),
+                note: "server SKIPPED — its sessionMetaKey cannot ride (the engine's judge refused it); mounting the server without the key would silently drop the session id it declared it needs. Fix the entry and republish.",
+            });
+            continue;
+        }
+        const sessionMetaKey = metaKey.key === undefined ? {} : { sessionMetaKey: metaKey.key };
         if (s.transport.kind === "stdio") {
             const env = resolveRefs(s.transport.envRefs, s.name, "env", logger);
             if (env === null)
                 continue;
-            out.push({
-                scenarios: s.scenarios ?? [],
-                spec: { name: s.name, transport: { kind: "stdio", command: s.transport.command, args: s.transport.args, ...(Object.keys(env).length ? { env } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
-            });
+            const draft = {
+                spec: { name: s.name, transport: { kind: "stdio", command: s.transport.command, args: s.transport.args }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes, ...sessionMetaKey },
+                pieces: env,
+            };
+            out.push({ scenarios: s.scenarios ?? [], spec: mintDeclaration(desk, draft, rosterLease) });
         }
         else {
             const headers = resolveRefs(s.transport.headerRefs, s.name, "header", logger);
@@ -178,10 +190,11 @@ export function resolveMcpServers(mcp, logger) {
                 continue;
             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 } : {}), ...sentMcpAssertionHeaderMember(s.transport.assertionHeader) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
-            });
+            const draft = {
+                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes, ...sessionMetaKey },
+                pieces: headers,
+            };
+            out.push({ scenarios: s.scenarios ?? [], spec: mintDeclaration(desk, draft, rosterLease) });
         }
     }
     if (out.length > 0)
@@ -195,7 +208,7 @@ export function mcpForScenario(center, scenario) {
     const hit = servers.filter((s) => s.scenarios.length === 0 || s.scenarios.includes(scenario)).map((s) => s.spec);
     return hit.length > 0 ? hit : undefined;
 }
-export function resolveA2aPeers(a2a, logger) {
+export function resolveA2aPeers(a2a, desk, rosterLease, logger) {
     const out = [];
     for (const p of a2a.peers ?? []) {
         if (p.enabled === false)
@@ -210,17 +223,17 @@ export function resolveA2aPeers(a2a, logger) {
         const headers = resolveRefs(p.headerRefs, p.name, "header", logger, "web_admin_a2a_env_missing", "skipping this A2A peer — referenced env var is unset in this service");
         if (headers === null)
             continue;
-        out.push({
-            scenarios: p.scenarios ?? [],
+        const draft = {
             spec: {
                 name: p.name,
                 url: p.url,
                 ...(p.cardUrl ? { cardUrl: p.cardUrl } : {}),
-                ...(Object.keys(headers).length ? { headers } : {}),
                 ...(p.principalHeader ? { principalHeader: p.principalHeader } : {}),
                 ...(p.allowSkills && p.allowSkills.length > 0 ? { allowSkills: p.allowSkills } : {}),
             },
-        });
+            pieces: headers,
+        };
+        out.push({ scenarios: p.scenarios ?? [], spec: mintDeclaration(desk, draft, rosterLease) });
     }
     if (out.length > 0)
         logger?.info("web_admin_a2a", { peers: out.map((p) => p.spec.name) });

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

@@ -75,11 +75,11 @@ export interface CenterModel {
      *  the ONLY way to keep per-model tuning that lived in env (`MODEL_FREQUENCY_PENALTY` etc.) — see the
      *  review-gw heterogeneous-roster migration. MUST be static per published version (prompt-cache prefix). */
     extraBody?: Record<string, unknown>;
-    /** registry-core 0.10.13 ([ref]/[ref]⑤c): per-model behavior-slot mitigation sentences, mirrors core
-     *  `Model.promptGuidance` (core 1.303+ assembles them into the volatile tail's per-model position).
-     *  Same category as `extraBody`: logical model metadata, carried verbatim — without this projection the
-     *  configured sentences parse fine in registry-core but never reach the assembly face ([ref]① 排雷:
-     *  the missing leg made every promptGuidance pilot a false control). */
+    /** registry-core 0.10.13 ([ref]/[ref]⑤c): per-model behavior-slot sentences. core 7.56.0 ([ref]) retired the engine seat
+     *  (`Model.promptGuidance`; per-model guidance is now a prompt overlay keyed on the model's declared traits), while the
+     *  settings-schema `ModelEntry` still accepts the key. It is carried here ONLY so the [ref] judge (`judgeCatalogEntry`)
+     *  can see it: a non-empty list refuses the entry (`config.model_entry_invalid`, field `promptGuidance`) instead of the
+     *  sentences being silently dropped; `toModel` never mints it onto a core `Model`. */
     promptGuidance?: string[];
     /**
      * [ref](7.108.0)—— 这条条目发给供应商的**附加请求头**(部署 ↔ 供应商的契约;今天只有 `anthropic-beta`),上 core 的 per-model
@@ -170,6 +170,11 @@ export interface CenterMcpServer {
      * (同批解析透明键 `authForm` / `entryKind` 的语义归连接器,本层仍只承载。)
      */
     toolAxes?: unknown;
+    /**
+     * core 7.58.0 `McpServerSpec.sessionMetaKey` —— 声明了它的服务器,引擎在每次 `tools/call` 的 `_meta` 下以这把键放这条腿的会话 id。
+     * 承载形 `unknown`(与 {@link CenterMcpServer.toolAxes} 同姿):判官只有引擎根导出的 `judgeSessionMetaKey`(`resolveMcpServers` 在铸 spec 那一刻问它;坏形整条 server 不进)。
+     */
+    sessionMetaKey?: unknown;
     transport: {
         kind: "stdio";
         command: string;

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -18,8 +18,11 @@ dials the device, so the device needs no inbound port, no public address and no
 
 **Discovery before you connect**: `GET /v1/capabilities` carries a `deviceExecutor` key — either `false`
 (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
+wsPath, management, relayUrl? }`. 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. `relayUrl` (server 7.137.0+) is present
+only when the operator declared one (`DEVICE_RELAY_URL`): the engine sits behind a relay or gateway and the device
+must dial that absolute `ws://` / `wss://` URL verbatim instead of the engine's own address — do not rebuild it from
+the engine address and `wsPath`. Absent ⇒ dial the engine's own address at `wsPath`, as before. `protocolVersion` tells you
 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).
 
@@ -136,7 +139,8 @@ Ask for a new enrollment token and try again."* Do not retry the same token afte
 
 ### 1.2 Connecting
 
-Open a WebSocket to `wsPath` (`GET`, standard upgrade). The server refuses the upgrade with `404` for any
+Open a WebSocket to `relayUrl` when the capability carries one, otherwise to `wsPath` on the engine's own
+address (`GET`, standard upgrade). The server refuses the upgrade with `404` for any
 other path, and with `503` while the replica is draining or when its pre-auth connection caps are full.
 There is no authentication in the upgrade headers — the handshake happens **inside** the protocol.
 
@@ -336,7 +340,7 @@ 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` | `2` | the protocol revision this server speaks (the highest it accepts) |
+| `DEVICE_PROTOCOL_VERSION` | `3` | 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) |
 
@@ -365,6 +369,7 @@ the union of the rows up to *N*, and the full set at the current revision is the
 |---|---|
 | `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` |
+| `3` | `name_too_long` |
 
 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
@@ -560,7 +565,7 @@ 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
+This is the full set at the current revision (`3`); 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 -->
@@ -574,6 +579,7 @@ with, and an executor sends only the words of the revision it declared (§1.2).
 | `invalid` | the arguments do not make sense for this target (e.g. `readLink` on a non-symlink) |
 | `is_directory` | a file operation hit a directory |
 | `liveness_no_output` | **you** killed the command because it produced no output for your own silence window (a hung command); the wall-clock budget `timeoutMs` running out stays `timeout`. The frame has no field for the window length — do not invent one |
+| `name_too_long` | a component of the path is longer than the filesystem's name limit (`NAME_MAX`, 255 bytes; POSIX `ENAMETOOLONG` for such a component) — no directory can hold that name, so it is read upstream as an absence, like `not_found`. A path that is only too long as a whole while every component is short stays `unknown` (such a file may exist, reached from a directory below it). On an exec instruction it is a protocol violation (use `spawn_error` when the process could not be started) and the server reads it as `unknown` |
 | `not_directory` | a directory operation hit a non-directory |
 | `not_found` | the path does not exist |
 | `not_supported` | you do not implement this face (prefer simply not declaring it) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.136.0",
+  "version": "7.138.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",
@@ -69,8 +69,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.55.0",
-    "@sema-agent/settings-schema": "14.5.0",
+    "@sema-agent/core": "7.59.0",
+    "@sema-agent/settings-schema": "14.7.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",