@nanobpm/nano-workforce 0.158.1 → 0.159.0

package/.github/workflows/ci.yml

@@ -72,6 +72,14 @@ jobs:
       - name: Check contract registry (no synonyms / undeclared keys)
         run: npm run check:contracts
 
+      # MCP tool-schema gate (epic #605, S0): every projected (non-`x-mcp`) request-body operation
+      # must carry a self-contained, `$ref`-free inline `body` schema — the runtime projector copies
+      # it VERBATIM into the tool `inputSchema`, so a leaked `$ref` is unresolvable in a standard MCP
+      # client (nano-ide#502). The inline bodies are DERIVED from `components.schemas` by
+      # scripts/inline-mcp-bodies.ts; this fails if a source component changed without regenerating.
+      - name: Check MCP tool-body schemas (inline, $ref-free)
+        run: npm run check:mcp-bodies
+
       # Runs the full *.test.ts suite under Node's built-in test runner (node:test), which strips
       # TypeScript types on the fly (Node >= 22.6) — no build step.
       - name: Test (Node)

package/.github/workflows/invariants.yml

@@ -77,6 +77,13 @@ jobs:
       - name: Check navigation index freshness
         run: npm run sync:nav:check
 
+      # Projected MCP tool bodies (openapi.yaml) are a checked-in derived artifact too (epic #605 S0):
+      # each is DERIVED from `components.schemas` by scripts/inline-mcp-bodies.ts. Two branches can
+      # each edit a source component and its inline body in isolation yet leave the merged tree stale;
+      # re-assert freshness on the merged tree so a $ref cannot silently re-leak into the tool surface.
+      - name: Check MCP tool-body schemas freshness
+        run: npm run check:mcp-bodies
+
       # Backstop: catch ANY other committed generated file that the merged sources render stale, even
       # one without its own `--check` script above. A clean tree is the whole-repo invariant.
       - name: No stale committed artifacts on the merged tree

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.159.0](https://github.com/nanobpm/nano-workforce/compare/v0.158.1...v0.159.0) (2026-08-29)
+
+### Features
+
+* **openapi:** self-contained, $ref-free projected MCP tool schemas (S0) ([#614](https://github.com/nanobpm/nano-workforce/issues/614)) ([2018020](https://github.com/nanobpm/nano-workforce/commit/2018020a290c2f416e703e3584b27f92ccf27753)), closes [#605](https://github.com/nanobpm/nano-workforce/issues/605) [nano-ide#501](https://github.com/nanobpm/nano-ide/issues/501) [503/#504](https://github.com/503/nano-workforce/issues/504) [#606](https://github.com/nanobpm/nano-workforce/issues/606)
+
 ## [0.158.1](https://github.com/nanobpm/nano-workforce/compare/v0.158.0...v0.158.1) (2026-08-29)
 
 ### Bug Fixes

package/docs/mcp-runbook.md

@@ -124,6 +124,24 @@ cockpit *is* the approval (ADR 0005 Decision 7), so an agent cannot dispatch a d
 graph through MCP. Agents author graphs through the pure `compileDeliveryGraph` /
 `previewDeliveryGraph` doors, which stay exposed.
 
+**Projected tool schemas are self-contained (epic #605, S0).** The projector copies each
+operation's request-body schema *verbatim* into the tool's `inputSchema.properties.body`
+and does **not** resolve `$ref`s, so every projected (non-`x-mcp`) request-body operation
+in `openapi.yaml` presents an inline `type: object` body with no `$ref`; the two graph doors
+additionally carry a worked `example` — an agent discovers the body shape (and calls the tool
+with a real object, not a
+stringified one) from the surface alone. The two graph doors split by convention:
+`compileDeliveryGraph` takes the **structured `DeliveryGraph` object** (and *stages*);
+`previewDeliveryGraph` takes the **text shape `{ "graphJson": "<serialized DeliveryGraph>" }`**
+(and is *pure*). Every validation failure returns `issues`/`errors` as `[{ path, message }]`.
+The inline bodies are **derived** from `components.schemas` by
+`scripts/inline-mcp-bodies.ts` (single source of truth; run `npm run gen:mcp-bodies` after
+editing a component), and `npm run check:mcp-bodies` + `test/mcp-tool-schemas.test.ts` (which
+runs the real projector) fail CI if a `$ref` ever re-leaks. The upstream projector fix that
+would make this mitigation unnecessary is tracked in
+[nano-ide#501](https://github.com/nanobpm/nano-ide/issues/501) (#502 self-contained schemas,
+#503 faithful object-body transport, #504 real-spec conformance guard).
+
 ## 5. Fallback
 
 Agents without MCP are unchanged — resolve the instance, then
@@ -131,3 +149,31 @@ Agents without MCP are unchanged — resolve the instance, then
 [`nano-workforce` skill](../skills/nano-workforce/SKILL.md), which fetches the same
 live guide. `GET /app/api/agent` and `GET /app/api/agent/skill` keep working exactly as
 before.
+
+## 6. Regression harness — pin the MCP surface from nwf's side
+
+The MCP projection layer (schema shape, argument encoding, session handshake) is
+covered end-to-end by a reusable e2e harness (epic #605 slice S1, issue #607):
+`e2e/support/mcp-harness.ts`. It boots a hermetic in-process instance and drives
+the **real** `/app/mcp` endpoint over the full Streamable-HTTP client handshake —
+`initialize` → capture `Mcp-Session-Id` → `notifications/initialized` →
+`tools/list` → `tools/call` — asserting the client-visible contract every agent
+depends on:
+
+- every projected tool schema is `$ref`-free with an explicit `type` (a leaked
+  `$ref` is unresolvable in the MCP context);
+- an object argument arrives **as an object**, never coerced to a string;
+- validation failures answer uniformly with `issues[{path,message}]`;
+- side-effecting calls stage nothing, so the suite is safe to re-run.
+
+It runs in CI under `npm run e2e` (hermetic — no socket, no GitHub), so a
+reintroduced `$ref` or a stringified object body fails the build instead of
+reaching an agent.
+
+**Extending it (new per-tool case).** Import `bootMcpHarness` from
+`e2e/support/mcp-harness.ts` in your own `e2e/<slice>.e2e.ts` and drive
+`harness.listTools()` / `harness.callTool(name, args)` — the handshake, session
+management and teardown are owned by the harness, so you add a `test(...)`, never
+a second transport. The module header documents the seam and the exported
+assertion helpers (`assertSchemaSelfContained`, `assertObjectBodyAccepted`,
+`assertValidationIssues`) in full; `e2e/mcp-surface.e2e.ts` is the worked example.

package/e2e/mcp-surface.e2e.ts

@@ -0,0 +1,235 @@
+// MCP surface end-to-end regression net (epic #605 slice S1, issue #607).
+//
+// Drives the app's REAL runtime-served MCP endpoint (`/app/mcp`, ADR 0067) over the full
+// Streamable-HTTP client handshake — `initialize` → `Mcp-Session-Id` → `notifications/initialized`
+// → `tools/list` → `tools/call` — against a hermetic in-process instance, via the reusable
+// `e2e/support/mcp-harness.ts` module. It PINS the client-visible contract the S0 defect broke:
+//
+//   • every projected tool schema is `$ref`-free with an explicit `type` (S0 / nano-ide#502);
+//   • an object argument arrives AS AN OBJECT, never coerced to a string (S0 / nano-ide#503);
+//   • validation failures answer uniformly with `issues[{path,message}]`;
+//   • the reads parse; the mutating framework tools are gated; side-effecting calls leave NO live
+//     staged proposal behind (safe to run repeatedly).
+//
+// It is the harness siblings extend: S2 (#608), S4 (#610) and S5 (#611) add their own per-tool case
+// by importing `bootMcpHarness` — they do NOT re-implement the handshake. See the module header of
+// `support/mcp-harness.ts` for the extension seam.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+  assertObjectBodyAccepted,
+  assertSchemaSelfContained,
+  assertValidationIssues,
+  bootMcpHarness,
+  type McpHarness,
+  type McpTool,
+  MINIMAL_VALID_GRAPH,
+  schemaHasRef,
+  STRINGIFIED_BODY_MESSAGE,
+} from "./support/mcp-harness.ts";
+
+// The read tools the surface must expose and answer (issue #607 scope). Each is safe and repeatable.
+const READ_TOOLS = [
+  "getVersion",
+  "getAgentInstructions",
+  "listActivePrs",
+  "listStagedProposals",
+  "getLineage",
+] as const;
+
+// The object-body doors covered by a `tools/call` (issue #607 scope). `previewDeliveryGraph` is the
+// PURE positive proof (a valid graph, nothing staged). The rest are side-EFFECTING (they stage a
+// proposal or start a process on a VALID body), so the harness drives them with a deliberately
+// INVALID — but object-shaped — body: validation rejects it, which (a) proves the object argument
+// reached the door AS AN OBJECT and (b) persists nothing, keeping the harness repeatable.
+const OBJECT_BODY_DOORS = [
+  "compileDeliveryGraph",
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "startFeature",
+  "agentCompleteEscalation",
+  "appendBlackboard",
+] as const;
+
+// S0-PENDING self-containment allowlist (issue #606 / upstream nano-ide#502).
+// --------------------------------------------------------------------------
+// S1 (this harness) and S0 (openapi.yaml restructuring) are the two WAVE-0 scaffold slices and land
+// in parallel — so this test must be GREEN on `main` whether or not S0 has merged yet. On the
+// pre-S0 spec these object-body tools still project a leaked `$ref` (`body: { $ref: <component> }`);
+// S0 inlines them. For each, the audit tolerates EITHER the self-contained shape (post-S0) OR
+// EXACTLY the one known pre-S0 `$ref` (this map's value) — and FAILS on any OTHER `$ref` shape (a
+// novel leak, a wrong target). Once S0 lands, delete the graduated entries here so they fall under
+// the hard self-containment assertion like every other tool. A tool NOT in this map is hard-asserted
+// self-contained NOW — so reintroducing a `$ref` into any clean tool (or a sibling's NEW tool) fails
+// the build immediately.
+const KNOWN_PENDING_S0: Readonly<Record<string, string>> = {
+  compileDeliveryGraph: "#/components/schemas/DeliveryGraph",
+  previewDeliveryGraph: "#/components/schemas/DeliveryGraphPreviewSubmit",
+  startConvergenceLoop: "#/components/schemas/ConvergenceStart",
+  startPlanFanout: "#/components/schemas/PlanStart",
+  startEpicSet: "#/components/schemas/EpicSetStart",
+  startFeature: "#/components/schemas/FeatureStart",
+  agentCompleteEscalation: "#/components/schemas/AgentCompleteRequest",
+  appendBlackboard: "#/components/schemas/BlackboardAppendRequest",
+  saveToLibrary: "#/components/schemas/SaveToLibrarySubmit",
+  importToLibrary: "#/components/schemas/ImportToLibrarySubmit",
+  previewProposalBpmn: "#/components/schemas/DeliveryGraphProposalBpmnRequest",
+  enrolAgenticWorker: "#/components/schemas/EnrolRequest",
+  revertEscalationCompletion: "#/components/schemas/RevertCompletionRequest",
+};
+
+/** Collect every `$ref` string anywhere in a parsed JSON Schema. */
+function collectRefs(schema: unknown, acc: string[] = []): string[] {
+  if (Array.isArray(schema)) {
+    for (const item of schema) collectRefs(item, acc);
+  } else if (schema && typeof schema === "object") {
+    for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
+      if (key === "$ref" && typeof value === "string") acc.push(value);
+      else collectRefs(value, acc);
+    }
+  }
+  return acc;
+}
+
+/** Audit one tool's projected schema against the S0 self-containment contract, tolerating exactly
+ *  the one documented pre-S0 leak for a {@link KNOWN_PENDING_S0} tool (see that map's comment). */
+function auditToolSchema(tool: McpTool): void {
+  const pendingRef = KNOWN_PENDING_S0[tool.name];
+  if (pendingRef === undefined) {
+    // Not pending an S0 fix → the schema must already be self-contained. This is the live guard that
+    // fails the build the moment a `$ref` is (re)introduced into a clean or newly-added tool.
+    assertSchemaSelfContained(tool.inputSchema, tool.name);
+    return;
+  }
+  // Pending an S0 fix: accept the post-S0 clean shape, OR the exact known pre-S0 `$ref`.
+  if (!schemaHasRef(tool.inputSchema)) {
+    assertSchemaSelfContained(tool.inputSchema, tool.name);
+    return;
+  }
+  const refs = collectRefs(tool.inputSchema);
+  const unexpected = refs.filter((r) => r !== pendingRef);
+  assert.equal(
+    unexpected.length,
+    0,
+    `tool "${tool.name}": unexpected \`$ref\`(s) ${JSON.stringify(unexpected)} — only the known ` +
+      `pre-S0 leak "${pendingRef}" is tolerated (issue #606 / nano-ide#502). Any other \`$ref\` is a defect.`,
+  );
+}
+
+describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S1 / #607)", () => {
+  let h: McpHarness;
+  let tools: McpTool[];
+  let toolNames: Set<string>;
+
+  before(async () => {
+    h = await bootMcpHarness();
+    tools = await h.listTools();
+    toolNames = new Set(tools.map((t) => t.name));
+  });
+
+  after(async () => {
+    await h?.stop();
+  });
+
+  test("initialize handshake succeeds and tools/list projects the covered tools", () => {
+    assert.ok(h.sessionId, "the initialize handshake must yield an Mcp-Session-Id");
+    assert.ok(tools.length > 0, "tools/list must project at least one tool");
+    for (const name of [...READ_TOOLS, ...OBJECT_BODY_DOORS, "previewDeliveryGraph"]) {
+      assert.ok(toolNames.has(name), `tools/list must expose "${name}"`);
+    }
+    // The operator-only doors stay OFF the MCP surface (ADR 0067 §2 — `x-mcp` excluded).
+    for (const excluded of ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"]) {
+      assert.ok(!toolNames.has(excluded), `"${excluded}" is operator-only and must NOT be projected`);
+    }
+  });
+
+  test("every projected tool schema is $ref-free with an explicit type (S0 contract)", () => {
+    for (const tool of tools) auditToolSchema(tool);
+  });
+
+  test("read tools answer with parseable responses", async () => {
+    for (const name of READ_TOOLS) {
+      const res = await h.callTool(name, {});
+      assert.ok(!res.isError, `read "${name}" must not error: ${res.text}`);
+      assert.ok(res.text.length > 0, `read "${name}" must return content`);
+      // Every read but the markdown guide answers JSON; the guide answers a non-empty string.
+      if (name !== "getAgentInstructions") {
+        assert.notEqual(res.json, undefined, `read "${name}" must return parseable JSON: ${res.text.slice(0, 120)}`);
+      }
+    }
+  });
+
+  test("previewDeliveryGraph accepts a structured object body and stays pure (nothing staged)", async () => {
+    const res = await h.callTool("previewDeliveryGraph", { body: { graphJson: JSON.stringify(MINIMAL_VALID_GRAPH) } });
+    assertObjectBodyAccepted(res, "previewDeliveryGraph");
+    assert.ok(!res.isError, `previewDeliveryGraph must compile a valid graph: ${res.text}`);
+    const json = res.json as { ok?: boolean; staged?: boolean } | undefined;
+    assert.equal(json?.ok, true, `previewDeliveryGraph must report ok:true: ${res.text}`);
+    assert.equal(json?.staged, false, "previewDeliveryGraph is a PURE preview — it must never stage");
+  });
+
+  test("object-body doors receive the argument as an object, not a string (uniform validation)", async () => {
+    // A deliberately-invalid-but-object body per door: validation rejects it (persisting nothing),
+    // which proves the object argument reached the door AS AN OBJECT — never the S0 stringified body.
+    for (const name of OBJECT_BODY_DOORS) {
+      const args = name === "appendBlackboard" ? { token: "harness-invalid", body: {} } : { body: {} };
+      const res = await h.callTool(name, args);
+      assert.ok(res.isError, `door "${name}" must reject an empty body with a validation error`);
+      assertValidationIssues(res, name); // also asserts the object body was NOT stringified
+    }
+  });
+
+  test("mutating framework tools are gated without the shared secret (set-variables)", async () => {
+    const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
+    assert.ok(res.isError, "urban_debug_set_variables must refuse a credential-free mutation");
+    assert.match(
+      res.text,
+      /shared secret|allowMutations/i,
+      `the refusal must name the guard: ${res.text}`,
+    );
+  });
+
+  // The falsifiable core (issue #607 acceptance): DELIBERATELY reintroducing either half of the S0
+  // defect makes the harness fail. These pin the detector's teeth independently of whether S0 has
+  // landed — so the guard cannot silently rot into a no-op.
+  describe("reintroducing the S0 defect fails the build", () => {
+    test("a $ref in a tool schema is caught by the self-containment assertion", () => {
+      const good = { type: "object", properties: { body: { type: "object", properties: { n: { type: "number" } } } } };
+      assert.doesNotThrow(() => assertSchemaSelfContained(good, "synthetic-clean"));
+      const withRef = { type: "object", properties: { body: { $ref: "#/components/schemas/DeliveryGraph" } }, required: ["body"] };
+      assert.throws(() => assertSchemaSelfContained(withRef, "synthetic-ref"), /\$ref/, "a reintroduced $ref must throw");
+    });
+
+    test("a typeless schema is caught by the self-containment assertion", () => {
+      const typeless = { properties: { body: { type: "object" } } };
+      assert.throws(() => assertSchemaSelfContained(typeless, "synthetic-typeless"), /type/, "a typeless schema must throw");
+    });
+
+    test("a stringified object body is rejected by the door and caught by assertObjectBodyAccepted", async () => {
+      // Simulate the S0 client coercion: send the body as a JSON STRING instead of an object.
+      const res = await h.callTool("compileDeliveryGraph", { body: JSON.stringify(MINIMAL_VALID_GRAPH) });
+      assert.ok(res.isError, "a stringified object body must be rejected by the door");
+      assert.ok(
+        res.text.includes(STRINGIFIED_BODY_MESSAGE),
+        `the door must report "${STRINGIFIED_BODY_MESSAGE}": ${res.text}`,
+      );
+      // The harness's guard must recognize that signature as a failure.
+      assert.throws(
+        () => assertObjectBodyAccepted(res, "compileDeliveryGraph"),
+        /stringified/,
+        "assertObjectBodyAccepted must flag a stringified-body result",
+      );
+    });
+  });
+
+  test("side-effecting calls leave no live staged proposals behind (repeatable)", async () => {
+    const res = await h.callTool("listStagedProposals", {});
+    assert.ok(!res.isError, `listStagedProposals must not error: ${res.text}`);
+    const json = res.json as { count?: number; proposals?: unknown[] } | undefined;
+    assert.equal(json?.count, 0, `the harness must stage nothing: ${res.text}`);
+    assert.deepEqual(json?.proposals, [], "no live staged proposals may remain");
+  });
+});