@nanobpm/nano-workforce 0.158.0 → 0.159.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.158.0",
+  "version": "0.159.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -49,6 +49,8 @@
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "sync:nav": "node --experimental-strip-types scripts/sync-nav.ts",
     "sync:nav:check": "node --experimental-strip-types scripts/sync-nav.ts --check",
+    "gen:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts",
+    "check:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts --check",
     "dev": "urban dev",
     "pretest": "urban gen",
     "test": "node --experimental-strip-types --test",
@@ -73,7 +75,8 @@
     "conventional-changelog-conventionalcommits": "^8.0.0",
     "linkedom": "^0.18.13",
     "semantic-release": "^25.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "yaml": "^2.9.0"
   },
   "overrides": {
     "@semantic-release/npm": "^13.1.5"

package/pages/cockpit/mount.js

@@ -542,14 +542,14 @@ export function mountCockpit(host, opts = {}) {
     setNote(undefined);
   }
 
-  function setNote(text) {
+  function setNote(text, state = "waiting") {
     if (text == null) {
       terminalNote.textContent = "";
       terminalNote.setAttribute("data-terminal-note", "none");
       return;
     }
     terminalNote.textContent = text;
-    terminalNote.setAttribute("data-terminal-note", "waiting");
+    terminalNote.setAttribute("data-terminal-note", state);
   }
 
   function teardownTerminal() {
@@ -628,7 +628,14 @@ export function mountCockpit(host, opts = {}) {
       let session;
       const client = new RelayChannelClient({
         connect: connectRelay,
-        onRelay: (message) => session?.handle(message),
+        onRelay: (message) => {
+          // Promote the note to "waiting for live output" only once the hub ACKs the subscribe. Until
+          // then it honestly reads "connecting", so a socket that never opens/subscribes stops
+          // masquerading as a connected-but-quiet stream (#600). Gate on `!cleared` so a reconnect's
+          // resubscribe ack does not re-arm the note after real output has already flowed.
+          if (!cleared && message?.op === "subscribed") setNote("Waiting for live output…", "waiting");
+          session?.handle(message);
+        },
         onOpen: () => session?.attach(),
         onError,
       });
@@ -636,8 +643,10 @@ export function mountCockpit(host, opts = {}) {
       client.open();
       drill = { stream, client };
       setMode("live", stream);
-      // Arm the "waiting for output" note (after setMode, which clears it) until the first frame.
-      setNote("Connected — waiting for live output…");
+      // Arm the note as "connecting" (after setMode, which clears it) BEFORE the socket opens. It only
+      // becomes "waiting for live output" when the subscribe is ACKed (onRelay above) and clears on the
+      // first byte, so a dead socket reads as "connecting", never a falsely-"connected" quiet stream (#600).
+      setNote("Connecting…", "connecting");
     } catch (err) {
       // The new terminal failed to build after the prior one was torn down: reset the region to idle
       // (and drop any partially-built terminal) so the UI never shows a stale "live"/"replay"
@@ -811,7 +820,7 @@ export function mountCockpit(host, opts = {}) {
 }
 
 /**
- * Derive the channel WebSocket URL from the current origin (path `/agentic`).
+ * Derive the channel WebSocket URL module-relatively (path `/agentic`, anchored to import.meta.url).
  *
  * The agentic hub authenticates upgrades with an identity token only
  * (`sharedSecretAuthenticator({ requireCredential: false })`) — no capability credential is required.
@@ -824,10 +833,21 @@ export function mountCockpit(host, opts = {}) {
  * token (or an explicit `relayUrl`) for secured deployments.
  */
 function defaultRelayUrl(token, capability) {
-  const proto = location.protocol === "https:" ? "wss:" : "ws:";
-  const base = `${proto}//${location.host}/agentic`;
-  if (!token) return base;
-  const query = new URLSearchParams({ token });
-  if (capability) query.set("capability", capability);
-  return `${base}?${query}`;
+  // Anchor the relay endpoint to THIS MODULE's url (import.meta.url), NOT location.host — exactly as
+  // the HTTP endpoints (reportUrl/transcriptsUrl) are (#279/#467). mount.js is ALWAYS served at
+  // `<appMount>/cockpit/mount.js`, so `../agentic` resolves to `<appMount>/agentic` on every surface,
+  // then swap the scheme http→ws / https→wss:
+  //   • standalone / local App-View: `ws://<app-origin>/agentic` — byte-identical to the old behaviour.
+  //   • Studio console App-View:      `ws://<console>/console/app-view/<app>/agentic` — the app-view
+  //     -prefixed path the console proxies, NOT the console origin root.
+  // Deriving from `location.host` instead dialed the CONSOLE origin behind the App-View — which has no
+  // `/agentic` route (404) and whose app-view proxy refuses WS upgrades (501, ADR 0057 §3) — leaving
+  // the live terminal permanently dead behind the console (#600). This is the WS hop of the same
+  // failure class the HTTP endpoints already fixed by anchoring to import.meta.url.
+  const url = new URL("../agentic", import.meta.url);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (!token) return url.href;
+  url.searchParams.set("token", token);
+  if (capability) url.searchParams.set("capability", capability);
+  return url.href;
 }

package/scripts/inline-mcp-bodies.ts

@@ -0,0 +1,316 @@
+// Single source of truth for the projected MCP tool INPUT schemas (epic nano-workforce#605, S0).
+//
+// The Urban runtime projects this app's `openapi.yaml` into MCP tools (ADR 0067) — there is
+// intentionally ZERO MCP server code in nwf. The projector (`@nanobpm/urban`
+// `collectOperations` → `toolInputSchema`) copies each operation's request-body schema VERBATIM
+// into the tool's `inputSchema.properties.body`; it does NOT resolve `$ref`s. So a request body
+// authored as `schema: { $ref: "#/components/schemas/DeliveryGraph" }` projects as an opaque
+// `body: { "$ref": … }` a standard MCP client cannot resolve — and, unable to see it is an object,
+// the client stringifies the argument and the door rejects it (`expected object, got string`).
+// The upstream fix (a projector that bundles refs into self-contained schemas) is tracked in
+// nano-ide#501 (P0 #502 self-contained schemas, P1 #503 faithful object-body transport, P2 #504
+// real-spec conformance guard); THIS script is the nwf-side mitigation that keeps the surface
+// callable today: it authors each projected request body as a self-contained, `$ref`-free
+// `type: object` schema INLINE in `openapi.yaml`.
+//
+// Derivation over duplication (AGENTS.md): the `components.schemas` remain the single source of
+// truth. This script DERIVES the inline body by fully dereferencing that component (merging
+// `allOf`, inlining `oneOf` variants, dropping `discriminator` ref-mappings) and splicing the
+// result into the operation's `requestBody` between sentinel markers, in place, without
+// reformatting the rest of the hand-maintained file. Re-run it whenever a source component
+// changes:
+//
+//   node --experimental-strip-types scripts/inline-mcp-bodies.ts          # write openapi.yaml
+//   node --experimental-strip-types scripts/inline-mcp-bodies.ts --check  # verify (CI)
+//
+// The convention every projected request-body operation MUST follow (and every later slice that
+// adds one inherits): author the body as a SINGLE top-level `$ref` to a `components.schemas` entry,
+// yielding a `type: object` with inline `properties`, NO `$ref` in the projected schema, and a
+// description that carries the contract; the graph doors (`compileDeliveryGraph`/
+// `previewDeliveryGraph`) additionally carry a worked `example` (enforced by
+// `test/mcp-tool-schemas.test.ts`). `test/mcp-tool-schemas.test.ts` is the runtime drift guard — it
+// runs the REAL urban projector over the spec and fails if any projected tool body reintroduces a
+// `$ref` or loses its explicit type.
+//
+// Drift detection survives inlining: the generated `# BEGIN` sentinel records the source component
+// (`source=#/components/schemas/…`), so on every subsequent run the generator re-derives the inline
+// body from the CURRENT component — even though the operation's `schema:` no longer carries a
+// `$ref` — and `--check` fails if a source component changed but its inline body was not
+// regenerated. (Without the recorded source the check would be a permanent false green: once the
+// `$ref` is inlined there is nothing left to re-derive from.)
+//
+// Mirrors the repo's other derive/verify pairs (layout-bpmn --check, sync-nav --check,
+// check-contracts / reconcile-contracts).
+import { readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+// `yaml` (eemeli) is the SAME parser `@nanobpm/urban` uses to read this spec at runtime
+// (openapi/spec.ts), so a round-trip here matches what the projector sees.
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+const SPEC_PATH = `${ROOT}openapi.yaml`;
+
+const BEGIN_PREFIX = "# BEGIN generated:mcp-body";
+const BEGIN_TAIL = "(scripts/inline-mcp-bodies.ts — do not hand-edit)";
+const END = "# END generated:mcp-body";
+
+/** The `# BEGIN` sentinel for a block, embedding the source component so a later run can re-derive. */
+function beginMarker(sourceRef: string): string {
+  return `${BEGIN_PREFIX} source=${sourceRef} ${BEGIN_TAIL}`;
+}
+
+type Schema = Record<string, unknown>;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const HTTP_METHODS = ["get", "put", "post", "delete", "patch"] as const;
+
+/**
+ * Fully dereference a schema against `components.schemas`, producing a `$ref`-free equivalent:
+ *  - a `$ref` is replaced by the (recursively dereferenced) target component;
+ *  - an `allOf` is MERGED into one object (union of `properties`/`required`) so a node variant
+ *    like `DeliveryNodeAgent` (allOf [DeliveryNodeCommon, {inline}]) becomes one flat `type: object`;
+ *  - `oneOf`/`anyOf` members are dereferenced but kept as a union;
+ *  - `discriminator` is dropped (its `mapping` values are `#/components/...` pointers that would
+ *    dangle once inlined, and MCP clients do not need it);
+ *  - every other keyword is copied through, recursing into `properties`/`items`/arrays.
+ * Cycles (none today) are guarded by the visited-name set.
+ */
+function deref(node: unknown, comps: Record<string, unknown>, seen: ReadonlySet<string>): unknown {
+  if (Array.isArray(node)) return node.map((n) => deref(n, comps, seen));
+  if (!isRecord(node)) return node;
+
+  if (typeof node.$ref === "string") {
+    const m = node.$ref.match(/^#\/components\/schemas\/(.+)$/);
+    if (!m) throw new Error(`non-local $ref cannot be inlined: ${node.$ref}`);
+    const name = m[1];
+    if (seen.has(name)) throw new Error(`cyclic $ref: ${name}`);
+    const target = comps[name];
+    if (!target) throw new Error(`dangling $ref: ${node.$ref}`);
+    return deref(target, comps, new Set(seen).add(name));
+  }
+
+  if (Array.isArray(node.allOf)) {
+    const props: Record<string, unknown> = {};
+    const required: string[] = [];
+    const merged: Schema = { type: "object", properties: props, required };
+    let additionalProperties: unknown;
+    for (const part of node.allOf) {
+      const d = deref(part, comps, seen);
+      if (!isRecord(d)) continue;
+      if (isRecord(d.properties)) Object.assign(props, d.properties);
+      if (Array.isArray(d.required)) {
+        for (const r of d.required) if (typeof r === "string") required.push(r);
+      }
+      if ("additionalProperties" in d) additionalProperties = d.additionalProperties;
+      if (typeof d.type === "string") merged.type = d.type;
+    }
+    // Sibling keywords authored alongside `allOf` (e.g. `description`) win over the merged parts.
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "allOf") continue;
+      merged[k] = deref(v, comps, seen);
+    }
+    if (required.length === 0) delete merged.required;
+    else merged.required = [...new Set(required)];
+    if (additionalProperties !== undefined && !("additionalProperties" in node)) {
+      merged.additionalProperties = additionalProperties;
+    }
+    return merged;
+  }
+
+  const out: Schema = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "discriminator") continue;
+    out[k] = deref(v, comps, seen);
+  }
+  return out;
+}
+
+/** Does this (raw, un-dereferenced) schema contain a `$ref` anywhere? */
+function hasRef(node: unknown): boolean {
+  if (Array.isArray(node)) return node.some(hasRef);
+  if (!isRecord(node)) return false;
+  if (typeof node.$ref === "string") return true;
+  return Object.values(node).some(hasRef);
+}
+
+/** `false` iff the operation is `x-mcp`-excluded (operator-only door). */
+function isProjected(op: Record<string, unknown>): boolean {
+  const x = op["x-mcp"];
+  if (x === false) return false;
+  if (isRecord(x) && x.exclude === true) return false;
+  return true;
+}
+
+interface Target {
+  operationId: string;
+  sourceRef: string;
+  inline: Schema;
+}
+
+/**
+ * Recover `operationId -> source component $ref` from the `# BEGIN … source=…` sentinels already in
+ * the raw text. This is what lets `--check` keep detecting drift AFTER the `$ref` has been inlined:
+ * the operation's parsed `schema:` no longer carries a `$ref`, but the recorded source does, so the
+ * generator can re-derive the block from the current component. Scans by operation region (the same
+ * indentation-free `operationId:` split `spliceSchema` uses) so a block is attributed to its owner.
+ */
+function recordedSources(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const opRe = /^ *operationId: (\S+)/gm;
+  const ops: Array<{ id: string; at: number }> = [];
+  for (let m = opRe.exec(text); m !== null; m = opRe.exec(text)) {
+    ops.push({ id: m[1], at: m.index });
+  }
+  for (let i = 0; i < ops.length; i++) {
+    const end = i + 1 < ops.length ? ops[i + 1].at : text.length;
+    const region = text.slice(ops[i].at, end);
+    const bm = region.match(/# BEGIN generated:mcp-body source=(\S+)/);
+    if (bm) out.set(ops[i].id, bm[1]);
+  }
+  return out;
+}
+
+/**
+ * Collect the projected request-body operations to (re)generate. A body is a managed target when it
+ * is authored as a single top-level `$ref` (first authoring) OR already carries a generated block
+ * whose source component was recorded in its sentinel (subsequent runs). Either way the inline body
+ * is DERIVED from the CURRENT `components.schemas`, so a source-component change is always re-derived
+ * (and caught by `--check`). A projected body that leaks a NON-top-level `$ref` violates the
+ * single-top-level-`$ref` convention and is rejected loudly rather than silently half-inlined.
+ */
+function collectTargets(doc: Record<string, unknown>, recorded: Map<string, string>): Target[] {
+  const comps: Record<string, unknown> =
+    isRecord(doc.components) && isRecord(doc.components.schemas) ? doc.components.schemas : {};
+  const paths = isRecord(doc.paths) ? doc.paths : {};
+  const targets: Target[] = [];
+  for (const item of Object.values(paths)) {
+    if (!isRecord(item)) continue;
+    for (const method of HTTP_METHODS) {
+      const op = item[method];
+      if (!isRecord(op) || typeof op.operationId !== "string") continue;
+      if (!isProjected(op)) continue;
+      const body = isRecord(op.requestBody) ? op.requestBody : undefined;
+      const jsonNode =
+        body && isRecord(body.content) && isRecord(body.content["application/json"])
+          ? body.content["application/json"]
+          : undefined;
+      const json = isRecord(jsonNode) ? jsonNode.schema : undefined;
+      if (!isRecord(json)) continue;
+      let sourceRef: string | undefined;
+      if (typeof json.$ref === "string") {
+        sourceRef = json.$ref;
+      } else if (recorded.has(op.operationId)) {
+        sourceRef = recorded.get(op.operationId);
+      } else {
+        if (hasRef(json)) {
+          throw new Error(
+            `${op.operationId}: projected request body must be authored as a single top-level ` +
+              "`$ref` to a components.schemas entry (found a nested `$ref`) — see the MCP schema " +
+              "convention in openapi.yaml.",
+          );
+        }
+        continue;
+      }
+      if (sourceRef === undefined) continue;
+      const derefed = deref({ $ref: sourceRef }, comps, new Set());
+      const inline: Schema = isRecord(derefed) ? derefed : {};
+      if (typeof inline.type !== "string") {
+        // A `oneOf`/`anyOf` body root has no single `type`; every projected body IS an object, so
+        // pin the explicit `type: object` the MCP contract requires alongside the variant union.
+        inline.type = "object";
+      }
+      targets.push({ operationId: op.operationId, sourceRef, inline });
+    }
+  }
+  targets.sort((a, b) => a.operationId.localeCompare(b.operationId));
+  return targets;
+}
+
+/** Render an inline schema as a YAML block indented to `pad` spaces, wrapped in the sentinels. */
+function renderBlock(inline: Schema, pad: string, sourceRef: string): string {
+  const dumped = stringifyYaml(inline, { indent: 2, lineWidth: 0, singleQuote: true });
+  const body = dumped
+    .replace(/\n$/, "")
+    .split("\n")
+    .map((line) => (line.length ? pad + line : line))
+    .join("\n");
+  return `${pad}${beginMarker(sourceRef)}\n${body}\n${pad}${END}`;
+}
+
+/**
+ * Replace the `requestBody` → `application/json` → `schema:` value of `operationId` in the raw
+ * text with `block`, in place. Returns the new text. Boundaries are found by indentation, the same
+ * span technique `scripts/sync-nav.ts` uses, so nothing else in the file is reformatted.
+ */
+function spliceSchema(text: string, operationId: string, inline: Schema, sourceRef: string): string {
+  const opMarker = `operationId: ${operationId}\n`;
+  const opAt = text.indexOf(opMarker);
+  if (opAt < 0) throw new Error(`operationId not found in text: ${operationId}`);
+  // Bound the search to this operation (up to the next operationId).
+  const nextOp = text.indexOf("operationId: ", opAt + opMarker.length);
+  const region = nextOp < 0 ? text.slice(opAt) : text.slice(opAt, nextOp);
+  const rbRel = region.indexOf("requestBody:");
+  if (rbRel < 0) throw new Error(`requestBody not found for ${operationId}`);
+  // First `schema:` after requestBody is the request body schema.
+  const schemaRel = region.indexOf("schema:", rbRel);
+  if (schemaRel < 0) throw new Error(`request schema not found for ${operationId}`);
+  const schemaAbs = opAt + schemaRel;
+  const lineStart = text.lastIndexOf("\n", schemaAbs) + 1;
+  const schemaIndent = schemaAbs - lineStart; // columns before `schema:`
+  const pad = " ".repeat(schemaIndent + 2); // schema value is nested one level deeper
+  // The schema value spans from the end of the `schema:` line to the first following line whose
+  // indent is <= the `schema:` line's indent (a sibling/closing key), skipping blank lines.
+  const afterSchemaLine = text.indexOf("\n", schemaAbs) + 1;
+  const lines = text.slice(afterSchemaLine).split("\n");
+  let consumed = 0;
+  for (const line of lines) {
+    if (line.trim() === "") {
+      consumed += line.length + 1;
+      continue;
+    }
+    const indent = line.length - line.trimStart().length;
+    if (indent <= schemaIndent) break;
+    consumed += line.length + 1;
+  }
+  const valueEnd = afterSchemaLine + consumed;
+  const block = renderBlock(inline, pad, sourceRef);
+  return `${text.slice(0, afterSchemaLine)}${block}\n${text.slice(valueEnd)}`;
+}
+
+function generate(text: string): string {
+  const parsed = parseYaml(text);
+  const doc: Record<string, unknown> = isRecord(parsed) ? parsed : {};
+  const targets = collectTargets(doc, recordedSources(text));
+  let out = text;
+  for (const t of targets) out = spliceSchema(out, t.operationId, t.inline, t.sourceRef);
+  return out;
+}
+
+function main(): void {
+  const check = process.argv.includes("--check");
+  const original = readFileSync(SPEC_PATH, "utf8");
+  const next = generate(original);
+  if (check) {
+    if (next !== original) {
+      process.stderr.write(
+        "openapi.yaml projected MCP request bodies are STALE.\n" +
+          "A source component schema changed but its inline `body` was not regenerated.\n" +
+          "Run: npm run gen:mcp-bodies (node --experimental-strip-types scripts/inline-mcp-bodies.ts)\n",
+      );
+      process.exit(1);
+    }
+    process.stdout.write("openapi.yaml projected MCP request bodies are up to date.\n");
+    return;
+  }
+  if (next !== original) {
+    writeFileSync(SPEC_PATH, next);
+    process.stdout.write("openapi.yaml projected MCP request bodies regenerated.\n");
+  } else {
+    process.stdout.write("openapi.yaml projected MCP request bodies already up to date.\n");
+  }
+}
+
+main();

package/test/cockpit-embed-endpoints.test.ts

@@ -94,3 +94,87 @@ test("#279: embed.html forwards BOTH reportUrl and transcriptsUrl from the injec
     "embed.html must forward reportUrl: cfg.reportUrl",
   );
 });
+
+// #600: the relay WebSocket default is the WS hop of the SAME #279/#467 failure class. It used to be
+// derived from `location.host` — behind the Studio console that is the console origin (:8080), which
+// has no `/agentic` route (404) and whose app-view proxy refuses WS upgrades (501, ADR 0057 §3), so
+// the live terminal was permanently dead behind the console. The fix anchors it to import.meta.url
+// exactly like the HTTP endpoints, `../agentic` off `<appMount>/cockpit/mount.js`, then swaps the
+// scheme http→ws / https→wss. Unlike reportUrl/transcriptsUrl (inlined `.href`) it is BUILT from
+// `new URL("<spec>", import.meta.url)` so the scheme can be swapped, so it is matched separately.
+
+// Pull the module-relative relay spec out of `new URL("<spec>", import.meta.url);` in defaultRelayUrl()
+// (the HTTP defaults are `new URL(..., import.meta.url).href`, so `)\s*;` matches only the relay one).
+function relaySpec(): string {
+  const m = MOUNT_JS.match(/new URL\(\s*"([^"]*)"\s*,\s*import\.meta\.url\s*\)\s*;/);
+  assert(
+    m,
+    "mount.js defaultRelayUrl() must derive the relay default from new URL(\"<spec>\", import.meta.url), " +
+      "anchored to the module's own served location, not location.host (#600)",
+  );
+  return m![1];
+}
+
+// Resolve the relay spec against a REAL served mount url and swap the scheme, mirroring defaultRelayUrl().
+function resolveRelay(mount: string): string {
+  const url = new URL(relaySpec(), mount);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+}
+
+test("#600: defaultRelayUrl derives the relay target from import.meta.url, not location.host", () => {
+  assert(
+    !/\$\{location\.host\}/.test(MOUNT_JS),
+    "the relay default must not be interpolated from location.host: behind the console that is the " +
+      "console origin (:8080), which has no /agentic route (404) and refuses WS upgrades (501) (#600)",
+  );
+  const spec = relaySpec();
+  assert(
+    !spec.startsWith("/"),
+    `relay spec "${spec}" must not be absolute: a leading-slash path resolves against the iframe ORIGIN ` +
+      `(console :8080), not the app-view base the console proxies (#279 class)`,
+  );
+  assert(
+    spec.startsWith("../"),
+    `relay spec "${spec}" must step up out of /cockpit/ (mount.js is at <appMount>/cockpit/mount.js; the ` +
+      `hub is a sibling at <appMount>/agentic) (#467 class)`,
+  );
+});
+
+test("#600: relay default resolves to ws://<app-origin>/agentic standalone (behaviour unchanged)", () => {
+  assertEquals(
+    resolveRelay(STANDALONE_MOUNT),
+    "ws://127.0.0.1:3000/agentic",
+    "standalone the relay default must dial the app origin's /agentic exactly as it does today",
+  );
+});
+
+test("#600: relay default resolves onto the app-view base inside the Studio console iframe", () => {
+  assertEquals(
+    resolveRelay(STUDIO_MOUNT),
+    "ws://studio-host:8080/console/app-view/Workforce/agentic",
+    "behind the console the relay must dial the app-view-prefixed /agentic the console proxies, not the " +
+      "console origin root (#279 class) nor the /cockpit/ shell base (#467 class)",
+  );
+});
+
+test("#600: relay default swaps https→wss on a secure surface", () => {
+  assertEquals(
+    resolveRelay("https://studio-host:8443/console/app-view/Workforce/cockpit/mount.js"),
+    "wss://studio-host:8443/console/app-view/Workforce/agentic",
+    "an https surface must yield a wss relay url",
+  );
+});
+
+test("#600: an explicit relayUrl opt and injected __NANO_APP_VIEW__.relayUrl outrank the derived default", () => {
+  // Precedence is pinned in source: opts.relayUrl wins over the module-relative default, and embed.html
+  // forwards the console-injected cfg.relayUrl into that opt so it outranks the default behind the console.
+  assert(
+    /opts\.relayUrl\s*\?\?\s*defaultRelayUrl\(/.test(MOUNT_JS),
+    "mount.js must honour an explicit opts.relayUrl over the derived default (opts.relayUrl ?? defaultRelayUrl(...)) (#600)",
+  );
+  assert(
+    /relayUrl:\s*cfg\.relayUrl/.test(EMBED_HTML),
+    "embed.html must forward relayUrl: cfg.relayUrl so a console-injected __NANO_APP_VIEW__.relayUrl reaches the relay (#600)",
+  );
+});

package/test/mcp-tool-schemas.test.ts

@@ -0,0 +1,127 @@
+// Drift guard for the projected MCP tool INPUT schemas (epic nano-workforce#605, S0).
+//
+// The Urban runtime projects `openapi.yaml` into MCP tools (ADR 0067) and copies each operation's
+// request-body schema VERBATIM into the tool's `inputSchema.properties.body` — it does NOT resolve
+// `$ref`s. A leaked `$ref` is therefore unresolvable in a standard MCP client, and, unable to see
+// the body is an object, the client stringifies the argument and the door rejects it
+// (`expected object, got string`). This test drives the REAL projector (`collectOperations` from
+// `@nanobpm/urban`, plus the runtime's own `toolInputSchema` shape) over the checked-in spec and
+// fails the build if any projected tool body reintroduces a `$ref`, loses its explicit `type`, or a
+// graph door drops its worked example. It is the runtime counterpart to
+// `scripts/inline-mcp-bodies.ts --check` (which guards the derive step); together they keep the
+// convention every later slice inherits: `type: object`, inline `properties`, no `$ref`, an example.
+//
+// Extension seam: a sibling slice adding a projected request-body operation to `openapi.yaml` needs
+// no change here — this walks EVERY projected operation. A new graph door should be added to
+// GRAPH_DOORS so its example is required too.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { collectOperations, type OperationInfo, parseSpec } from "@nanobpm/urban/toolkit";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+// Parse the spec exactly as the runtime does (`@nanobpm/urban/toolkit` `parseSpec`), so this guard
+// sees precisely the document the MCP projector projects.
+const SPEC = parseSpec(readFileSync(`${ROOT}openapi.yaml`, "utf8"));
+
+/** Graph doors that MUST carry at least one worked example (epic #605 acceptance). */
+const GRAPH_DOORS = new Set(["compileDeliveryGraph", "previewDeliveryGraph"]);
+
+/** The client-visible tool `inputSchema`, reproduced exactly from the runtime's `toolInputSchema`
+ *  (mcp.ts) — path/query params plus the request body copied verbatim under `body`. */
+function toolInputSchema(op: OperationInfo): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const p of op.parameters) {
+    if (p.in === "path" || p.in === "query") {
+      properties[p.name] = p.schema ?? {};
+      if (p.required) required.push(p.name);
+    }
+  }
+  if (op.requestBodySchema) {
+    properties.body = op.requestBodySchema;
+    if (op.requestBodyRequired) required.push("body");
+  }
+  const schema: Record<string, unknown> = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+/** Every `$ref` string reachable in a schema, with a JSON-path for the failure message. */
+function findRefs(node: unknown, path: string, out: string[]): void {
+  if (Array.isArray(node)) {
+    node.forEach((n, i) => findRefs(n, `${path}[${i}]`, out));
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "$ref" && typeof v === "string") out.push(`${path}.$ref -> ${v}`);
+    else findRefs(v, `${path}.${k}`, out);
+  }
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The projected operations whose tool carries a request body (the object-body tools). */
+function projectedBodyOps(): OperationInfo[] {
+  return collectOperations(SPEC).filter((op) => !op.mcpExcluded && op.requestBodySchema);
+}
+
+test("every projected object-body tool schema is $ref-free (self-contained)", () => {
+  const ops = projectedBodyOps();
+  assert(ops.length >= 10, `expected the full projected object-body surface, saw ${ops.length}`);
+  for (const op of ops) {
+    const refs: string[] = [];
+    findRefs(toolInputSchema(op).properties, `${op.operationId}.properties`, refs);
+    assert(
+      refs.length === 0,
+      `${op.operationId}: projected tool schema leaks $ref(s) a standard MCP client cannot ` +
+        `resolve — inline the component(s) (run npm run gen:mcp-bodies): ${refs.join(", ")}`,
+    );
+  }
+});
+
+test("every projected object-body tool declares an explicit body type: object", () => {
+  for (const op of projectedBodyOps()) {
+    const body = op.requestBodySchema as Record<string, unknown>;
+    // A `oneOf`/`anyOf` body still carries an explicit `type: object` (the generator pins it) so a
+    // client knows to pass an object, not a string.
+    assert(
+      body.type === "object",
+      `${op.operationId}: request body must declare an explicit \`type: object\` (saw ` +
+        `type=${JSON.stringify(body.type)})`,
+    );
+    assert(
+      isRecord(body.properties) || Array.isArray(body.oneOf) || Array.isArray(body.anyOf),
+      `${op.operationId}: request body must expose inline \`properties\` (or a \`oneOf\`/\`anyOf\` ` +
+        "of object variants) so the shape is discoverable from the tool surface",
+    );
+  }
+});
+
+test("each graph door carries at least one worked example", () => {
+  const byId = new Map(projectedBodyOps().map((op) => [op.operationId, op]));
+  for (const door of GRAPH_DOORS) {
+    const op = byId.get(door);
+    assert(op, `expected graph door ${door} to be a projected object-body tool`);
+    const body = op!.requestBodySchema as Record<string, unknown>;
+    const hasExample =
+      "example" in body ||
+      "examples" in body ||
+      (isRecord(body.properties) &&
+        Object.values(body.properties).some((p) => isRecord(p) && "example" in p));
+    assert(hasExample, `${door}: request body must embed a worked \`example\` (§9.5 canonical graph)`);
+  }
+});
+
+test("operator-only delivery-graph doors stay withheld from the MCP tool surface", () => {
+  const excluded = new Set(
+    collectOperations(SPEC)
+      .filter((op) => op.mcpExcluded)
+      .map((op) => op.operationId),
+  );
+  for (const door of ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"]) {
+    assert(excluded.has(door), `${door} must remain x-mcp-excluded (operator-only dispatch gate)`);
+  }
+});