@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/testing/behavioral/journeys.livePack.e2e.test.ts

@@ -0,0 +1,129 @@
+/**
+ * E3 (AV-231, Backlog E) — the network-gated, NON-BLOCKING live-pack job.
+ *
+ * A handful of behaviours can only be confirmed against a REAL oxigraph store
+ * built from the REAL default pack: result ordering (A3/A9), which language a
+ * multilingual label resolves to under real store order (A7), ke truncation of
+ * long literals, and `buildIndex`'s `Promise.all` re-entrancy when the same pack
+ * is built concurrently. Those depend on the network (fetching the shipped pack)
+ * and on real build cost, so this suite is GATED OFF by default — it never runs
+ * (or flakes) in the ordinary `bun test` pass. Set `PRAGMA_LIVE_PACK=1` to run
+ * it (a dedicated, non-required CI job).
+ *
+ * The assertions here run against the VENDORED default pack as a faithful local
+ * proxy for the shipped one, so a maintainer who flips the gate gets real signal
+ * today. Each carries a TODO for wiring the ACTUAL network pack fetch — the one
+ * piece this environment cannot provide.
+ *
+ * TODO(AV-231/E3): resolve the real shipped default pack (git/npm source) here
+ * instead of the vendored TTL, so ordering/truncation are asserted against the
+ * bytes agents actually receive.
+ */
+
+import { describe, expect, it } from "vitest";
+import { buildPack } from "../../kernel/runtime/graphpack/build.js";
+import {
+  DEFAULT_PACK_PREFIXES,
+  DEFAULT_PACK_TTL,
+} from "../fixtures/graph/defaultPack.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+
+/** Non-blocking gate: skipped unless a maintainer opts in (or CI's live job). */
+const liveGate = process.env.PRAGMA_LIVE_PACK ? describe : describe.skip;
+
+liveGate(
+  "live-pack journey — real oxigraph ordering + build re-entrancy (E3)",
+  () => {
+    it("a SELECT ... ORDER BY returns a STABLE, deterministic ordering (A3/A9)", async () => {
+      const fixture = await bootFixtureRuntime({ ttl: DEFAULT_PACK_TTL });
+      try {
+        const query =
+          "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name";
+        const first = await fixture.runtime.query.sparql(query);
+        const second = await fixture.runtime.query.sparql(query);
+        const names = (result: typeof first): string[] =>
+          result.type === "select"
+            ? result.bindings.map((binding) => String(binding.name))
+            : [];
+        // Repeated evaluation is identical, and ORDER BY is honoured.
+        expect(names(first)).toEqual(names(second));
+        expect(names(first)).toEqual(["Beta Badge", "Button", "Orphan Widget"]);
+      } finally {
+        await fixture.dispose();
+      }
+    });
+
+    it("a multilingual label resolves to a SINGLE, tag-stripped value under real store order (A7)", async () => {
+      // TODO(AV-231/E3): against the live pack, pin the EXACT language the store
+      // yields first, so the index-label choice is a confirmed contract rather than
+      // the store-order accident it is today (see the A7 note in the E1 journey).
+      const fixture = await bootFixtureRuntime({ ttl: DEFAULT_PACK_TTL });
+      try {
+        const result = await fixture.runtime.query.sparql(
+          "SELECT ?l WHERE { ds:button rdfs:label ?l } ORDER BY ?l",
+        );
+        const labels =
+          result.type === "select"
+            ? result.bindings.map((binding) => String(binding.l))
+            : [];
+        expect(labels).toEqual(["Bouton", "Button"]);
+      } finally {
+        await fixture.dispose();
+      }
+    });
+
+    it("building the same sources CONCURRENTLY is re-entrant — one hash, no torn pack (buildIndex Promise.all)", async () => {
+      // buildIndex fans out four bulk SPARQL queries under Promise.all, and buildPack
+      // publishes atomically; N concurrent builds of identical sources must converge
+      // on ONE content hash with every pack complete (no half-written cache).
+      const inputs = [
+        { path: "concurrent/pack.ttl", content: DEFAULT_PACK_TTL },
+      ];
+      const options = {
+        name: "pragma",
+        version: "0.0.0-e3",
+        sourceRef: "e3-reentrancy",
+        prefixes: DEFAULT_PACK_PREFIXES,
+      };
+      const results = await Promise.all(
+        Array.from({ length: 5 }, () => buildPack(inputs, options)),
+      );
+      const hashes = new Set(results.map((result) => result.contentHash));
+      expect(hashes.size).toBe(1);
+      for (const result of results) {
+        expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+      }
+    });
+
+    it("a long literal survives the build round-trip without silent ke truncation", async () => {
+      // TODO(AV-231/E3): confirm against the live pack, whose real summaries/guidelines
+      // are long enough to trip any downstream ke truncation (A7/A9 tail).
+      const longText = "x".repeat(20_000);
+      const ttl = `@prefix ds: <https://ds.canonical.com/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+ds:Component a owl:Class .
+ds:summary a owl:DatatypeProperty ; rdfs:range xsd:string .
+ds:big a ds:Component ; ds:summary "${longText}" .`;
+      let fixture: FixtureGraph | undefined;
+      try {
+        fixture = await bootFixtureRuntime({ ttl });
+        const result = await fixture.runtime.query.sparql(
+          "SELECT ?s WHERE { ds:big ds:summary ?s }",
+        );
+        const value =
+          result.type === "select"
+            ? String(
+                (result.bindings.at(0) as { s?: string } | undefined)?.s ?? "",
+              )
+            : "";
+        expect(value.length).toBe(longText.length);
+      } finally {
+        await fixture?.dispose();
+      }
+    });
+  },
+);

package/src/testing/behavioral/journeys.mcpLifecycle.mcp.test.ts

@@ -0,0 +1,176 @@
+/**
+ * E2 (AV-231, Backlog E) — the MCP lifecycle journey over a LONG-LIVED,
+ * in-process server.
+ *
+ * Fresh-runtime unit tests structurally cannot catch the MCP memoization bugs:
+ * they build a new runtime per assertion, so a store/config memo that outlives a
+ * mutation is never exercised. The real MCP server boots ONE runtime for its
+ * whole lifetime and shares it across every tool call — the exact condition
+ * under which a cold-store rejection could be memoized forever, or a stale config
+ * layer could survive a `config_set`. This file drives that server the way an
+ * agent does, over a single connection:
+ *
+ *  - COLD read → STORE_UNAVAILABLE → `sources_update` (confirm) → the SAME
+ *    server's retry read SUCCEEDS. Guards C1: a rejected boot must NOT be
+ *    memoized, and a real mutation must invalidate the shared store so the next
+ *    read re-boots against the freshly built pack.
+ *  - `config_set` → a subsequent `config_show` on the same server sees the new
+ *    value. Guards C2: the mutation must drop the config memo the store boot
+ *    depends on.
+ *  - The discovery sequence resolves from a COLD store (the storeless
+ *    `capabilities` catalog boots with no pack), then browse → inspect works once
+ *    the store is warm.
+ *
+ * Uses the in-process `projectMcp` harness (SDK in-memory transport) — no stdio,
+ * no network — over the vendored default pack.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { readLock } from "../../kernel/runtime/lock.js";
+import { DEFAULT_PACK_TTL } from "../fixtures/graph/defaultPack.js";
+import { type McpHarness, projectMcp } from "../helpers/projectMcp.js";
+
+/** The transient roots one test creates; removed in `afterEach`. */
+let roots: string[] = [];
+const tempDir = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+/**
+ * A COLD project directory: a `pragma.config.ts` pointing at a real file
+ * package, but NO lock yet — so the store boots cold until `sources_update`.
+ */
+function coldProject(ttl: string): string {
+  const pkg = tempDir("e2-pkg-");
+  mkdirSync(join(pkg, "definitions"), { recursive: true });
+  writeFileSync(join(pkg, "definitions", "pack.ttl"), ttl);
+  const cwd = tempDir("e2-proj-");
+  writeFileSync(
+    join(cwd, "pragma.config.ts"),
+    `export default { packages: [{ name: "default", source: "file://${pkg}" }] };\n`,
+  );
+  return cwd;
+}
+
+let mcp: McpHarness | undefined;
+beforeEach(() => {
+  roots = [];
+});
+afterEach(async () => {
+  await mcp?.cleanup();
+  mcp = undefined;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)", () => {
+  it("a cold read fails STORE_UNAVAILABLE with the sources_update recovery, then the retry succeeds", async () => {
+    const cwd = coldProject(DEFAULT_PACK_TTL);
+    mcp = await projectMcp(capabilities, cwd);
+
+    // 1) COLD: the store has no pack — a store-backed read must fail cleanly,
+    //    pointing the agent at the recovery TOOL (not just a CLI string).
+    const cold = await mcp.callTool("block_list");
+    expect(cold.ok).toBe(false);
+    const error = cold.error as {
+      code: string;
+      recovery?: { mcp?: { tool?: string } };
+    };
+    expect(error.code).toBe("STORE_UNAVAILABLE");
+    expect(error.recovery?.mcp?.tool).toBe("sources_update");
+    expect(readLock(cwd)).toBeUndefined();
+
+    // 2) The agent runs the recovery tool for real (confirm) — it builds the pack.
+    const update = await mcp.callTool("sources_update", { confirm: true });
+    expect(update.ok).toBe(true);
+    // A real execution, not a plan-only preview.
+    expect(update.meta).not.toMatchObject({ planOnly: true });
+    expect((update.data as { contentHash: string }).contentHash).toMatch(
+      /^[0-9a-f]{64}$/,
+    );
+    expect(readLock(cwd)?.contentHash).toMatch(/^[0-9a-f]{64}$/);
+
+    // 3) RETRY on the SAME server: the shared store was invalidated by the
+    //    mutation, so the memoized cold rejection is gone and the read re-boots
+    //    against the new pack. This is the guarantee a fresh-runtime test cannot
+    //    make.
+    const warm = await mcp.callTool("block_list");
+    expect(warm.ok).toBe(true);
+    const names = (warm.data as { name: string }[])
+      .map((row) => row.name)
+      .sort();
+    expect(names).toEqual(["Button", "Card"]);
+  });
+});
+
+describe("MCP lifecycle — config_set is visible to the next read (E2, C2)", () => {
+  it("config_set updates the layer a subsequent config_show reads on the same server", async () => {
+    const cwd = tempDir("e2-cfg-");
+    mcp = await projectMcp(capabilities, cwd);
+
+    // Before: the default channel, from the default (unset) origin.
+    const before = await mcp.callTool("config_show");
+    const beforeData = before.data as {
+      config: { channel: string };
+      origins: { channel: string };
+    };
+    expect(beforeData.config.channel).toBe("normal");
+    expect(beforeData.origins.channel).toBe("default");
+
+    // Mutate: set the channel for real (confirm).
+    const set = await mcp.callTool("config_set", {
+      key: "channel",
+      value: "experimental",
+      confirm: true,
+    });
+    expect(set.ok).toBe(true);
+
+    // After: the SAME long-lived server's read reflects the write — proving the
+    // mutation dropped the config memo the boot depends on (not a stale layer).
+    const after = await mcp.callTool("config_show");
+    const afterData = after.data as {
+      config: { channel: string };
+      origins: { channel: string };
+    };
+    expect(afterData.config.channel).toBe("experimental");
+    // The write landed in the global layer, so the origin flips accordingly.
+    expect(afterData.origins.channel).toBe("global");
+  });
+});
+
+describe("MCP lifecycle — discovery from a cold store (E2)", () => {
+  it("the capabilities catalog resolves cold, then browse -> inspect works once warm", async () => {
+    const cwd = coldProject(DEFAULT_PACK_TTL);
+    mcp = await projectMcp(capabilities, cwd);
+
+    // Discovery is storeless: the capabilities catalog answers even with a cold
+    // store, so an agent can orient before the pack exists.
+    const catalog = await mcp.callTool("capabilities");
+    expect(catalog.ok).toBe(true);
+    const catalogData = catalog.data as {
+      discovery_sequence: unknown;
+      tools: unknown;
+    };
+    expect(catalogData.discovery_sequence).toBeDefined();
+    expect(catalogData.tools).toBeDefined();
+
+    // Warm the store, then follow a browse -> inspect discovery step end to end.
+    await mcp.callTool("sources_update", { confirm: true });
+    const list = await mcp.callTool("block_list");
+    expect(list.ok).toBe(true);
+    const first = (list.data as { name: string }[]).at(0);
+    expect(first?.name).toBeDefined();
+
+    const lookup = await mcp.callTool("block_lookup", {
+      name: [first?.name ?? ""],
+    });
+    expect(lookup.ok).toBe(true);
+    const results = (lookup.data as { results: { name: string }[] }).results;
+    expect(results.at(0)?.name).toBe(first?.name);
+  });
+});

package/src/testing/behavioral/mcpSurface.test.ts

@@ -92,7 +92,7 @@ function representativeValue(
     );
     return entity?.prefixed ?? entity?.name ?? "";
   }
-  // An enum positional (e.g. `config channel <name>`, `config set <key>`) must
+  // An enum positional (e.g. `config set <key>`) must
   // get a real member — a placeholder would fail the tool's zod schema at the
   // SDK layer, before the handler, yielding a protocol error rather than a
   // well-formed envelope.

package/src/testing/behavioral/staleCommands.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Stale-command gate: the published README and every doc under `docs/` must be
+ * free of the retired v1 vocabulary. This is an ENFORCED test, not a lint — a
+ * doc that reintroduces a removed command (or the retired `--llm` flag) fails
+ * the build. The live `--format llm` form is deliberately NOT banned.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/** The package root (`packages/cli/pragma/`), resolved from this test's URL. */
+const packageRoot = fileURLToPath(new URL("../../../", import.meta.url));
+
+/** Recursively collect every `.md` file under a directory. */
+function collectMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...collectMarkdown(full));
+    else if (entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+/** One retired pattern and a human-readable reason for the failure message. */
+interface BannedPattern {
+  readonly pattern: RegExp;
+  readonly reason: string;
+}
+
+/** The retired v1 vocabulary. The live `--format llm` form is intentionally absent. */
+const BANNED: readonly BannedPattern[] = [
+  {
+    pattern: /\bupdate-refs\b/,
+    reason: "retired `update-refs` (now `sources update`)",
+  },
+  { pattern: /pragma\s+llm\b/, reason: "retired `llm` tool" },
+  { pattern: /pragma\s+data\b/, reason: "retired `data` noun (now `sources`)" },
+  {
+    pattern: /pragma\s+tokens\b/,
+    reason: "retired plural `tokens` noun (now singular `token`)",
+  },
+  {
+    pattern: /\btokens_(list|lookup|sample|add-config)\b/,
+    reason: "retired plural `tokens_*` tools (now `token_*`)",
+  },
+  {
+    pattern: /--llm\b/,
+    reason:
+      "retired `--llm` flag (now the `--format llm` form, auto-detected when piped)",
+  },
+];
+
+// Every shipped doc must be free of retired vocabulary: the README plus every
+// page under `docs/`. CHANGELOG.md (at the package root, outside `docs/`) is
+// DELIBERATELY exempt — its migration table legitimately cites the retired
+// names (`data`, `update-refs`, plural `tokens`) to tell readers what they
+// became, so scanning it would false-positive on that historical vocabulary.
+const files = [
+  join(packageRoot, "README.md"),
+  ...collectMarkdown(join(packageRoot, "docs")),
+];
+
+describe("stale-command gate — docs never mention retired v1 commands", () => {
+  for (const file of files) {
+    const rel = relative(packageRoot, file);
+    it(`${rel} is free of retired commands`, () => {
+      const content = readFileSync(file, "utf-8");
+      for (const { pattern, reason } of BANNED) {
+        expect(pattern.test(content), `${rel}: ${reason}`).toBe(false);
+      }
+    });
+  }
+});

package/src/testing/eval/__snapshots__/eval.test.ts.snap

@@ -103,7 +103,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "prompt-set-tier-maps-to-config-tier",
+    "id": "prompt-set-tier-maps-to-config-set",
     "kind": "prompt",
     "passed": true,
   },
@@ -138,7 +138,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "tool-config-tier-is-plan-first",
+    "id": "tool-config-set-is-plan-first",
     "kind": "tool",
     "passed": true,
   },

package/src/testing/eval/cases/assembly.ts

@@ -163,11 +163,11 @@ export const assemblyEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "prompt-set-tier-maps-to-config-tier",
+    id: "prompt-set-tier-maps-to-config-set",
     kind: "prompt",
-    input: '"Set the active tier" should map to `config_tier`.',
+    input: '"Set the active tier" should map to `config_set` (B3).',
     async expect({ mcp }) {
-      assertIntentTool(await mcp.listTools(), "config_tier", /tier/i);
+      assertIntentTool(await mcp.listTools(), "config_set", /tier/i);
     },
   },
   {

package/src/testing/eval/cases/effectful.ts

@@ -70,12 +70,15 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "tool-config-tier-is-plan-first",
+    id: "tool-config-set-is-plan-first",
     kind: "tool",
     input:
-      "config_tier without `confirm` returns a plan (planOnly) and writes nothing — the uniform plan-first mutation contract.",
+      "config_set without `confirm` returns a plan (planOnly) and writes nothing — the uniform plan-first mutation contract.",
     async expect({ mcp }) {
-      const result = await mcp.callTool("config_tier", { path: "apps/lxd" });
+      const result = await mcp.callTool("config_set", {
+        key: "tier",
+        value: "apps/lxd",
+      });
       assert.equal(result.ok, true);
       const meta = result.meta as { planOnly?: boolean };
       assert.equal(meta.planOnly, true);

package/src/testing/eval/cases/readNouns.ts

@@ -90,16 +90,19 @@ export const readNounEvalCases: readonly EvalCase[] = [
     id: "content-canonical-graph-has-4-components",
     kind: "content",
     input:
-      "the canonical fixture graph carries exactly 4 ds:Component individuals, including Button and Beta Widget.",
+      "the canonical fixture graph carries 4 ds:Component individuals (Button, Modal, LXD Panel, Beta Widget); block list --all-tiers also surfaces the untiered Button Icon subcomponent (A2).",
     async expect() {
       await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
         const result = await mcp.callTool("block_list", { allTiers: true });
         const names = (result.data as { name: string }[])
           .map((r) => r.name)
           .sort();
+        // --all-tiers now reveals the untiered Button Icon subcomponent
+        // alongside the 4 tiered components (A2).
         assert.deepEqual(names, [
           "Beta Widget",
           "Button",
+          "Button Icon",
           "LXD Panel",
           "Modal",
         ]);

package/src/testing/fixtures/fixtureCapability.ts

@@ -173,3 +173,159 @@ export const fixtureEffectsModule: CapabilityModule = {
     },
   ],
 };
+
+/**
+ * A synthetic module that exercises every RENDER path of `emitReference` (D8 —
+ * never listed in `src/capabilities/index.ts`). Distinct from `fixtureModule`,
+ * which only exercises `emitSurface`: this one carries the doc-only shapes the
+ * reference generator reads and the machine surface ignores — a rich `doc`,
+ * examples with and without notes, a {@link DisclosureSpec}, every param kind
+ * as a flag (including a repeatable `string[]` flag), an OPTIONAL variadic
+ * positional, a destructive mutation AND a non-destructive one (the two
+ * `formatToolAnnotations` mutation branches), a visible MCP-withheld verb, a
+ * self-verb, a hidden verb the emitter must drop, and — so `renderNonToolSurface`
+ * renders both its optional bullets — an `mcpResources` template surface and an
+ * `mcpPrompts` native-prompt surface. The `register` hooks are no-ops: the
+ * reference emitter reads only `mcpResources.surface.templates` and the presence
+ * of `mcpPrompts`, never invoking either.
+ */
+export const fixtureReferenceModule: CapabilityModule = {
+  name: "fixture-reference",
+  verbs: [
+    {
+      path: ["gizmo", "scan"],
+      summary: "Scan the gizmos.",
+      doc: "Scan every gizmo under the active scope, optionally narrowing to named targets. Reads nothing off disk.",
+      params: [
+        {
+          kind: "string[]",
+          name: "targets",
+          doc: "Gizmo names to scan (all when omitted).",
+          positional: true,
+        },
+        {
+          kind: "enum",
+          name: "mode",
+          doc: "Scan mode.",
+          values: ["fast", "slow"],
+          default: "fast",
+        },
+        { kind: "number", name: "limit", doc: "Maximum gizmos to scan." },
+        { kind: "string", name: "label", doc: "Label to stamp on the report." },
+        { kind: "string[]", name: "include", doc: "Extra globs to include." },
+        { kind: "boolean", name: "deep", doc: "Recurse into sub-gizmos." },
+      ],
+      output: { formatters: passthroughFormatters },
+      examples: [
+        { cmd: "pragma gizmo scan", note: "scan everything" },
+        { cmd: "pragma gizmo scan alpha --mode slow" },
+      ],
+      disclosure: { levels: ["summary", "detailed"], default: "summary" },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ scanned: true }),
+    },
+    {
+      path: ["gizmo", "wipe"],
+      summary: "Wipe a gizmo.",
+      params: [
+        {
+          kind: "string",
+          name: "path",
+          doc: "The gizmo path to wipe.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: true,
+        mutates: true,
+        destructive: true,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ wiped: true }),
+    },
+    {
+      path: ["gizmo", "tidy"],
+      summary: "Tidy the gizmo cache.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        destructive: false,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ tidied: true }),
+    },
+    {
+      path: ["gizmo", "local"],
+      summary: "A visible gizmo verb withheld from MCP.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "CLI-only local helper" },
+      },
+      run: async () => ({ local: true }),
+    },
+    {
+      path: ["ping"],
+      summary: "Ping the gizmo host.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ pong: true }),
+    },
+    {
+      path: ["gizmo", "hidden"],
+      summary: "Hidden gizmo probe.",
+      hidden: true,
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "internal probe" },
+      },
+      run: async () => ({ ok: true }),
+    },
+  ],
+  // A non-tool MCP surface, so `renderNonToolSurface` emits its Resources bullet.
+  // `register` is a no-op — the emitter reads only `surface.templates`.
+  mcpResources: {
+    surface: { templates: ["gizmo:{+uri}"] },
+    register: () => {},
+  },
+  // A native prompt surface, so `renderNonToolSurface` emits its Prompts bullet.
+  mcpPrompts: { register: () => {} },
+};