@cyanheads/mcp-ts-core 0.9.14 → 0.9.16

package/dist/mcp-server/tools/utils/toolDefinition.d.ts

@@ -47,6 +47,41 @@ export interface ToolAnnotations {
     title?: string;
     [key: string]: unknown;
 }
+/**
+ * Per-field rendering config for the `enrichment` block's `content[]` trailer,
+ * keyed to the declared enrichment field names. The success-path analogue of how
+ * `format()` controls `output` rendering: `enrichment` is the data contract,
+ * `enrichmentTrailer` is its presentation.
+ *
+ * Scope: this shapes the `content[]` trailer text ONLY. It never affects
+ * `structuredContent`, which always carries the raw validated enrichment value
+ * (the object/array/scalar exactly as declared) — never the rendered markdown.
+ *
+ * Each entry is optional and may set:
+ *   - `render` — maps the field's validated value to trailer markdown. Wins over
+ *     the kind-tag and the generic `**key:** value` fallback. Use it to stop a
+ *     structured (object/array) field from collapsing to a JSON blob in
+ *     `content[]`; `structuredContent` always keeps the full structured value.
+ *   - `label` — overrides the field-name shown in the generic / `delta` rendering
+ *     (e.g. `Total Found` for a `totalFound` field, instead of the raw key).
+ *
+ * Resolves to `never` when no `enrichment` block is declared — `enrichmentTrailer`
+ * requires one.
+ */
+export type EnrichmentTrailerConfig<TEnrich extends ZodRawShape | undefined> = TEnrich extends ZodRawShape ? {
+    [K in keyof TEnrich]?: {
+        label?: string;
+        /**
+         * Declared with method syntax (not an arrow property) for the same
+         * reason as `format` / `handler`: method parameters are checked
+         * bivariantly, so a concrete tool's narrow `render` value stays
+         * assignable to the type-erased `AnyToolDefinition` (whose param
+         * widens to `unknown`). An arrow property would be variance-strict
+         * and break `createApp({ tools: [...] })` for every enrichment tool.
+         */
+        render?(value: z.infer<TEnrich[K]>): string;
+    };
+} : never;
 /**
  * Represents the complete, self-contained definition of an MCP tool.
  *
@@ -89,6 +124,19 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
      * otherwise silently override).
      */
     enrichment?: TEnrich;
+    /**
+     * Per-field `content[]` trailer rendering for the `enrichment` block — the
+     * presentation layer to `enrichment`'s data contract (mirrors `output` /
+     * `format`).
+     *
+     * Supply a `render` to stop a structured (object/array) enrichment field from
+     * collapsing to a JSON blob in `content[]` (it renders as bulleted markdown
+     * instead; `structuredContent` is unaffected), or a `label` to show a
+     * human-readable field name. Keyed to the declared `enrichment` fields and
+     * type-checked against them. The `enrichment-trailer-render` lint rule requires
+     * a `render` for any non-scalar enrichment field that isn't a `delta` shape.
+     */
+    enrichmentTrailer?: EnrichmentTrailerConfig<TEnrich>;
     /**
      * Declarative contract describing the failure modes this tool can surface.
      *

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,KAAK,gBAAgB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,uBAAuB,CAAC,OAAO,SAAS,WAAW,GAAG,SAAS,IACzE,OAAO,SAAS,WAAW,GACvB;KACG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf;;;;;;;WAOG;QACH,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;KAC7C;CACF,GACD,KAAK,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC/D,OAAO,SAAS,SAAS,aAAa,EAAE,GAAG,SAAS,GAAG,SAAS,EAChE,OAAO,SAAS,WAAW,GAAG,SAAS,GAAG,SAAS;IAEnD,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACrD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,YAAY,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACL,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EACtB,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAC5C,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,aAAa,EAAE,GAAG,SAAS,EACpC,WAAW,GAAG,SAAS,CACxB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,IAAI,CAClB,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EACrC,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EACtC,KAAK,CAAC,OAAO,SAAS,SAAS,aAAa,EAAE,GAAG,SAAS,GAAG,SAAS,EACtE,KAAK,CAAC,OAAO,SAAS,WAAW,GAAG,SAAS,GAAG,SAAS,EAEzD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACvE,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAEnD"}

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA2KzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAMlB,IAAY,EACZ,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA+NzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAMlB,IAAY,EACZ,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAY,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAGpF;AAoCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAevD;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CA6G9E"}
+{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAY,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAGpF;AAmED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAkBvD;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CA6G9E"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.js

@@ -103,13 +103,34 @@ function formatEnrichmentScalar(value) {
 /**
  * Renders accumulated enrichment as a single `content[]` trailer block, so
  * `content[]`-only clients see the same context `structuredContent` clients get
- * from the merged output. Field-helpers tag a render kind (notice → blockquote,
- * total → "N total", echo → "Query: …"); bare `enrich({...})` fields render as
- * `**key:** value`. Returns `[]` when nothing was enriched.
+ * from the merged output. Per field, rendering resolves in order:
+ *   1. a per-field `enrichmentTrailer.render` (the author's full control; wins
+ *      over everything — the escape hatch for structured fields that would
+ *      otherwise JSON-blob),
+ *   2. the kind-tag set by a field-helper (notice → blockquote, total →
+ *      "N total", echo → "Query: …", delta → "field: before → after"),
+ *   3. the generic `**key:** value` fallback (key overridable via `label`),
+ *      `JSON.stringify`-ing non-scalars.
+ *
+ * `parsed` is the validated effective output, so renderers receive the typed,
+ * post-parse value rather than the raw accumulator entry. The rendered markdown
+ * is appended to `content[]` only — `structuredContent` is built separately from
+ * the raw merged values and never carries this trailer text. Returns `[]` when
+ * nothing was enriched.
  */
-function renderEnrichmentTrailer(store) {
+function renderEnrichmentTrailer(store, trailer, parsed) {
     const lines = [];
-    for (const [key, value] of Object.entries(store.values)) {
+    for (const key of Object.keys(store.values)) {
+        // Skip keys the effective-output parse stripped (enriched but not declared in
+        // the block) — the trailer mirrors what reached structuredContent.
+        if (!(key in parsed))
+            continue;
+        const value = parsed[key];
+        const cfg = trailer?.[key];
+        if (cfg?.render) {
+            lines.push(cfg.render(value));
+            continue;
+        }
         switch (store.kinds.get(key)) {
             case 'notice':
                 lines.push(`> ${String(value)}`);
@@ -120,8 +141,13 @@ function renderEnrichmentTrailer(store) {
             case 'echo':
                 lines.push(`Query: ${String(value)}`);
                 break;
+            case 'delta': {
+                const d = (value ?? {});
+                lines.push(`**${cfg?.label ?? key}:** ${formatEnrichmentScalar(d.before)} → ${formatEnrichmentScalar(d.after)}`);
+                break;
+            }
             default:
-                lines.push(`**${key}:** ${formatEnrichmentScalar(value)}`);
+                lines.push(`**${cfg?.label ?? key}:** ${formatEnrichmentScalar(value)}`);
         }
     }
     return lines.length > 0 ? [{ type: 'text', text: lines.join('\n') }] : [];
@@ -149,7 +175,9 @@ export function buildToolSuccessResult(def, ctx, domainValidated, domainContent)
         ...domainValidated,
         ...values,
     });
-    const trailer = store && Object.keys(values).length > 0 ? renderEnrichmentTrailer(store) : [];
+    const trailer = store && Object.keys(values).length > 0
+        ? renderEnrichmentTrailer(store, def.enrichmentTrailer, structuredContent)
+        : [];
     return {
         structuredContent,
         content: trailer.length > 0 ? [...domainContent, ...trailer] : domainContent,

package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -21,6 +21,7 @@
     "scripts/tree.ts",
     "skills/",
     "templates/",
+    "AGENTS.md",
     "CLAUDE.md",
     "tsconfig.base.json",
     "vitest.config.base.mjs",
@@ -134,7 +135,8 @@
     "lint": "biome check",
     "lint:mcp": "bun run scripts/lint-mcp.ts",
     "lint:packaging": "bun run scripts/lint-packaging.ts",
-    "format": "biome check --write --unsafe",
+    "format": "biome check --write .",
+    "format:unsafe": "biome check --write --unsafe .",
     "typecheck": "bunx tsc --noEmit",
     "typecheck:scripts": "bunx tsc --project tsconfig.scripts.json --noEmit",
     "tree": "bun run scripts/tree.ts",
@@ -169,7 +171,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@cloudflare/vitest-pool-workers": "^0.16.10",
-    "@cloudflare/workers-types": "^4.20260529.1",
+    "@cloudflare/workers-types": "^4.20260530.1",
     "@duckdb/node-api": "^1.5.3-r.2",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",

package/scripts/build-changelog.ts

@@ -198,7 +198,9 @@ function reportMissingSummaries(missing: string[]): void {
   console.warn(`\nWarning: ${missing.length} file(s) missing 'summary' frontmatter:`);
   for (const file of shown) console.warn(`  - ${file}`);
   if (extra > 0) console.warn(`  ... and ${extra} more`);
-  console.warn(`\nBackfill these — see CLAUDE.md § Changelog for the frontmatter format.`);
+  console.warn(
+    `\nBackfill these — see CLAUDE.md/AGENTS.md § Changelog for the frontmatter format.`,
+  );
 }
 
 function main(): void {

package/scripts/check-skills-sync.ts

@@ -5,15 +5,17 @@
  * updates `skills/` for downstream servers; the mirrors are what local agent
  * toolchains actually read, and silent drift means agents run on stale guidance.
  *
- * Propagation is one-way (`skills/` → mirrors), so only missing or
- * content-drifted files are reported. Files that exist *only* in a mirror are
- * typically unrelated skills (globally installed, other sources) and are left
- * alone.
+ * Propagation is one-way (`skills/` → mirrors), so missing or content-drifted
+ * files are reported. A skill that exists *only* in a mirror is left alone when
+ * it's externally sourced (globally installed, other tools), but flagged as
+ * stale when its `SKILL.md` carries `metadata.audience: external` — a framework
+ * skill removed from `skills/` upstream that the mirror never had pruned.
  *
  * Behavior:
  *   • In sync                          → pass
  *   • Mirrors missing entirely         → skip (no mirrors to sync)
  *   • Drift (missing or changed files) → exit 1 with details (devcheck demotes to warning)
+ *   • Stale framework skill in mirror  → exit 1 (mirror-only dir with audience: external)
  *
  * Ignore specific skills or files via `devcheck.config.json`:
  *
@@ -79,6 +81,20 @@ function walkFiles(root: string): string[] {
   return files;
 }
 
+/** Top-level skill directory names under a path (empty when the path is absent). */
+function skillDirNames(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+}
+
+/** True when a skill is framework-managed — its SKILL.md carries `audience: external`. */
+function isFrameworkManaged(skillMdPath: string): boolean {
+  if (!existsSync(skillMdPath)) return false;
+  return /^\s*audience:\s*external\s*$/m.test(readFileSync(skillMdPath, 'utf-8'));
+}
+
 if (!existsSync(SKILLS_DIR)) {
   console.log('Skipped: no skills/ directory.');
   process.exit(0);
@@ -114,11 +130,26 @@ for (const mirror of presentMirrors) {
   if (driftedHere.length) drifted[mirror.label] = driftedHere.sort();
 }
 
+// Stale framework skills: a skill dir present only in a mirror (absent from
+// canonical skills/) is fine when externally sourced, but stale when it carries
+// `audience: external` — a framework skill removed from skills/ that was never
+// pruned from the mirror. User/external skills (no marker) are left alone.
+const canonicalDirs = new Set(skillDirNames(SKILLS_DIR));
+const stale: Record<string, string[]> = {};
+for (const mirror of presentMirrors) {
+  const staleHere = skillDirNames(mirror.path)
+    .filter((name) => !canonicalDirs.has(name) && !isIgnored(name, ignore))
+    .filter((name) => isFrameworkManaged(resolve(mirror.path, name, 'SKILL.md')))
+    .sort();
+  if (staleHere.length) stale[mirror.label] = staleHere;
+}
+
 const totals = {
   missing: Object.values(missing).reduce((n, arr) => n + arr.length, 0),
   drifted: Object.values(drifted).reduce((n, arr) => n + arr.length, 0),
+  stale: Object.values(stale).reduce((n, arr) => n + arr.length, 0),
 };
-const driftCount = totals.missing + totals.drifted;
+const driftCount = totals.missing + totals.drifted + totals.stale;
 
 if (driftCount === 0) {
   console.log(`skills/ is in sync with ${presentMirrors.map((m) => m.label).join(' and ')}.`);
@@ -128,7 +159,7 @@ if (driftCount === 0) {
 const lines: string[] = [];
 lines.push(
   `skills/ has drifted from ${presentMirrors.length > 1 ? 'mirrors' : 'its mirror'} ` +
-    `(${totals.missing} missing, ${totals.drifted} changed).`,
+    `(${totals.missing} missing, ${totals.drifted} changed, ${totals.stale} stale).`,
 );
 
 const renderSection = (title: string, groups: Record<string, string[]>) => {
@@ -141,10 +172,13 @@ const renderSection = (title: string, groups: Record<string, string[]>) => {
 
 renderSection('Missing in', missing);
 renderSection('Content differs in', drifted);
+renderSection('Stale framework skill (deleted upstream) in', stale);
 
 lines.push('');
-lines.push('Fix: propagate skills/ to the mirror(s), or add entries to');
-lines.push('     devcheck.config.json `skillsSync.ignore` to silence specific paths.');
+lines.push('Fix: propagate skills/ to the mirror(s) and delete stale framework skills from them,');
+lines.push(
+  '     or add entries to devcheck.config.json `skillsSync.ignore` to silence specific paths.',
+);
 
 console.log(lines.join('\n'));
 process.exit(1);

package/skills/add-app-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold an MCP App tool + UI resource pair. Use when the user asks to add a tool with interactive UI, create an MCP App, or build a visual/interactive tool.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -30,7 +30,7 @@ MCP Apps extend the standard tool pattern with an interactive HTML UI rendered i
 
 Both builders are exported from `@cyanheads/mcp-ts-core`. They handle `_meta.ui.resourceUri`, the compat key (`ui/resourceUri`), and the correct MIME type (`text/html;profile=mcp-app`) automatically.
 
-For the full API, Context interface, and error codes, read the framework's `CLAUDE.md` (loaded at session start).
+For the full API, Context interface, and error codes, read the framework's `CLAUDE.md`/`AGENTS.md` (loaded at session start).
 
 ## Steps
 

package/skills/add-export/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Add a new subpath export to the @cyanheads/mcp-ts-core package. Use when creating a new public API surface that consumers import from a dedicated subpath (e.g., @cyanheads/mcp-ts-core/newutil).
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: internal
   type: reference
 ---
 
 ## Context
 
-Subpath exports are defined in `package.json` under the `exports` field. Each subpath maps to a source entry point that gets compiled to `dist/`. The exports catalog in `CLAUDE.md` must stay in sync with `package.json`.
+Subpath exports are defined in `package.json` under the `exports` field. Each subpath maps to a source entry point that gets compiled to `dist/`. The exports catalog in `CLAUDE.md`/`AGENTS.md` must stay in sync with `package.json`.
 
 The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src` and `include: ["src/**/*"]`. This means every source file at `src/foo/bar.ts` compiles to `dist/foo/bar.js` — the `dist/` path in each export entry must match wherever `tsc` produces the compiled output for the named source file. Choose your source file location to produce the `dist/` path you want in the export entry.
 

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.5"
+  version: "1.6"
   audience: external
   type: reference
 ---
@@ -15,7 +15,7 @@ Services use the init/accessor pattern: initialized once in `createApp`'s `setup
 
 Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
 
-For the full service pattern, `CoreServices`, and `Context` interface, read the framework's `CLAUDE.md` (loaded at session start).
+For the full service pattern, `CoreServices`, and `Context` interface, read the framework's `CLAUDE.md`/`AGENTS.md` (loaded at session start).
 
 ## Steps
 

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.10"
+  version: "2.11"
   audience: external
   type: reference
 ---
@@ -237,6 +237,21 @@ async handler(input, ctx) {
 
 A *required* enrichment field the handler never populates fails the effective-output parse — surfacing the bug rather than dropping it silently. Enrichment keys must be disjoint from `output` keys (lint-enforced). The sections below are applications of this rule.
 
+**Trailer rendering is a per-field call.** Each field's `content[]` trailer line resolves as: its kind-tag if set (`notice`/`total`/`echo`/`delta`), else the definition's per-field `enrichmentTrailer.render`/`label`, else the generic `**key:** value` (objects/arrays `JSON.stringify`'d). A structured (object/array) field with no `render` ships as a one-line JSON blob — the `enrichment-trailer-render` lint rule errors on that. Give it a renderer, or a `label` to relabel a scalar key:
+
+```typescript
+enrichment: {
+  totalFound: z.number().describe('Matches before the page limit.'),
+  appliedFilters: z.object({ /* … */ }).describe('Filters the server applied.'),
+},
+enrichmentTrailer: {
+  totalFound: { label: 'Total Found' },                                  // → "**Total Found:** 2990"
+  appliedFilters: { render: (f) => `### Filters\n- Range: ${f.dateRange}` }, // markdown, not JSON
+},
+```
+
+`structuredContent` always keeps the full structured value; `enrichmentTrailer` only controls the human-facing `content[]` line.
+
 ### Communicate filtering and exclusions
 
 If the tool omitted, truncated, or filtered anything, say what and how to get it back. Silent omission is invisible to the agent — it can't act on what it doesn't know about.
@@ -329,6 +344,19 @@ output: z.object({
 
 The agent reads `created: true, previousSizeInBytes: 0, currentSizeInBytes: 68` and knows: brand new target, the full file content is the body. If that matches intent, fine; if not (typo path, uninitialized periodic note), the agent self-corrects without re-fetching. Anti-pattern: server-side `>=` integrity throws on mutators — the server can't distinguish intentional shrink from bug, so it throws on every shrink, including the deliberate ones.
 
+When the before/after is agent-facing context rather than primary payload, the `enrichment`-native form is `ctx.enrich.delta({ field, before, after })` — it writes `{ before, after }` to `structuredContent` and renders `**field:** before → after` in the `content[]` trailer. Declare the field in the `enrichment` block as `z.object({ before, after })`; the linter recognizes the shape, so it needs no custom `enrichmentTrailer.render`. Same stance — surface raw state, never a verdict:
+
+```typescript
+enrichment: {
+  sizeInBytes: z.object({
+    before: z.number().describe('Byte size before the mutation.'),
+    after: z.number().describe('Byte size after the mutation.'),
+  }).describe('Raw size before/after — the agent judges whether a shrink was intended.'),
+},
+// handler:
+ctx.enrich.delta({ field: 'sizeInBytes', before: prev, after: next });
+```
+
 ### Sparse upstream data must stay honest
 
 When tool output comes from a third-party API, don't overstate certainty. Upstream systems often omit fields entirely; the tool schema and `format()` should preserve that uncertainty instead of collapsing it into fake `false`, `0`, or empty-string facts.
@@ -492,7 +520,7 @@ throw invalidParams(
 
 Counts, applied filters, truncation notices, and chaining IDs help the agent decide its next action without extra round trips.
 
-Counts, applied-filter summaries, and query echo that describe the *result set* (rather than being the result) are textbook `enrichment` — `ctx.enrich.total(n)`, `ctx.enrich.echo(parsedQuery)`, or `ctx.enrich({ appliedFilters })` put them on both client surfaces with no `format()` entry. Reserve domain `output` for the payload itself and post-action state (e.g. `currentStatus` after a write), as below:
+Counts, applied-filter summaries, and query echo that describe the *result set* (rather than being the result) are textbook `enrichment` — `ctx.enrich.total(n)`, `ctx.enrich.echo(parsedQuery)`, or `ctx.enrich({ appliedFilters })` put them on both client surfaces with no `format()` entry (a structured field like `appliedFilters` also needs an `enrichmentTrailer.render` so its trailer line is markdown, not a JSON blob — see **Tool Response Design**). Reserve domain `output` for the payload itself and post-action state (e.g. `currentStatus` after a write), as below:
 
 ```typescript
 return {

package/skills/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`, `ctx.enrich`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -214,7 +214,7 @@ Use this only when downstream code is structured around `ctx.sessionId` and acce
 
 ### Capability-token model
 
-Surfacing `sessionId` does not change the framework's capability-as-token rule (possession of an opaque ID grants access — see CLAUDE.md `# Core Rules`). It is an opt-in *discovery-scoping* axis, not an access boundary.
+Surfacing `sessionId` does not change the framework's capability-as-token rule (possession of an opaque ID grants access — see CLAUDE.md/AGENTS.md `# Core Rules`). It is an opt-in *discovery-scoping* axis, not an access boundary.
 
 - Tokens shared across sessions (e.g. `df_<uuid>` handed from Agent A to Agent B) still resolve on the receiving side. The lookup key is the token, not the session.
 - Session-scoped *enumeration* (e.g. `dataframe_describe` returning only items registered by the current session) is a per-server pattern: maintain a session-keyed lookup of known names, gate list-all on it, but route direct lookups against the shared backing store.
@@ -564,6 +564,7 @@ ctx.enrich(fields: Partial<z.infer<ZodObject<E>>>): void
 ctx.enrich.notice(text: string): void      // writes `notice`         → blockquote
 ctx.enrich.total(count: number): void       // writes `totalCount`     → "N total"
 ctx.enrich.echo(query: string): void        // writes `effectiveQuery`  → "Query: …"
+ctx.enrich.delta({ field, before, after }): void  // writes `{before, after}` → "field: before → after"
 ```
 
 ### Behavior
@@ -577,6 +578,7 @@ ctx.enrich.echo(query: string): void        // writes `effectiveQuery`  → "Que
 | No block | Calling `ctx.enrich` on a tool that declared no `enrichment` is a silent no-op (values are stripped by the parse) — the price of service-layer callability. |
 | Service usage | Services accepting `ctx: Context` can call `ctx.enrich(...)`; the value reaches `structuredContent` exactly as if the handler had. |
 | `format-parity` | Enrichment lives outside `output`, so the `format-parity` lint never requires it in `format()`. |
+| Trailer rendering | Per field: kind-tag if set (notice/total/echo/delta), else the definition's `enrichmentTrailer.render`/`label`, else `**key:** value` (objects/arrays `JSON.stringify`'d). A structured field with no `render` errors under `enrichment-trailer-render` — supply one so it renders as markdown; `structuredContent` keeps the full value regardless. |
 
 See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
 

package/skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -53,7 +53,7 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Handler body | `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error` | [Handler body rules](#handler-body-rules) |
 | Error contract (structural) | `error-contract-type`, `error-contract-empty`, `error-contract-entry-type`, `error-contract-code-type`, `error-contract-code-unknown`, `error-contract-code-unknown-error`, `error-contract-reason-required`, `error-contract-reason-format`, `error-contract-reason-unique`, `error-contract-when-required`, `error-contract-retryable-type`, `error-contract-recovery-required`, `error-contract-recovery-empty`, `error-contract-recovery-min-words` | [Error contract rules](#error-contract-rules) |
 | Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail` | [Error contract rules](#error-contract-rules) |
-| Enrichment | `enrichment-type`, `enrichment-empty`, `enrichment-field-type`, `enrichment-output-collision`, `enrichment-prefer-block` | [Enrichment rules](#enrichment-rules) |
+| Enrichment | `enrichment-type`, `enrichment-empty`, `enrichment-field-type`, `enrichment-output-collision`, `enrichment-prefer-block`, `enrichment-trailer-render`, `enrichment-trailer-orphan`, `enrichment-trailer-unknown-field` | [Enrichment rules](#enrichment-rules) |
 | server.json | ~40 rules prefixed `server-json-*` | [server.json rules](#server-json-rules) |
 
 ---
@@ -515,7 +515,7 @@ Heuristic source-text checks that scan `handler.toString()` for common error-han
 
 Fires when a handler contains `throw new Error(...)`. Plain `Error` doesn't carry a JSON-RPC code — the framework's auto-classifier degrades to `InternalError`, hiding the actual failure mode.
 
-Plain `Error` is acceptable for "don't care" cases where the specific code doesn't matter (per CLAUDE.md: "plain `Error` for don't-care cases"). This rule targets domain-specific failures that deserve a concrete code — upgrade those to factories or `ctx.fail`, and accept the warning for the rest.
+Plain `Error` is acceptable for "don't care" cases where the specific code doesn't matter (per CLAUDE.md/AGENTS.md: "plain `Error` for don't-care cases"). This rule targets domain-specific failures that deserve a concrete code — upgrade those to factories or `ctx.fail`, and accept the warning for the rest.
 
 **Fix:** use `McpError` or a factory for domain-specific failures:
 
@@ -753,6 +753,30 @@ Advisory. Fires when a tool has **no** `enrichment` block but an `output` field
 
 **Fix:** move the field into an `enrichment` block and populate it via `ctx.enrich(...)` — it reaches both client surfaces without a `format()` entry. Ignore if the field is genuinely domain data. Deliberately conservative — common domain fields like `totalCount` are not flagged.
 
+### enrichment-trailer-render
+
+**Severity:** error
+
+Fires when a non-scalar (object/array) enrichment field has no `enrichmentTrailer.render`. It would `JSON.stringify` into a one-line blob in the `content[]` trailer (`structuredContent` keeps the full value either way). The `delta` shape (`z.object({ before, after })`, populated by `ctx.enrich.delta()`) is exempt — it renders natively as `field: before → after`.
+
+**Fix:** add a renderer — `enrichmentTrailer: { <field>: { render: (v) => … } }` — use `ctx.enrich.delta()` for before/after state, or opt into the JSON blob explicitly with `render: (v) => JSON.stringify(v)`.
+
+### enrichment-trailer-orphan
+
+**Severity:** error
+
+Fires when `enrichmentTrailer` is declared without an `enrichment` block — trailer config only renders enrichment fields.
+
+**Fix:** add the `enrichment` block, or drop the `enrichmentTrailer`.
+
+### enrichment-trailer-unknown-field
+
+**Severity:** error
+
+Fires when an `enrichmentTrailer` key doesn't match any declared `enrichment` field (a typo or drift the `keyof`-typed config already catches for TS authors).
+
+**Fix:** rename the trailer key to a declared enrichment field, or remove it.
+
 ---
 
 ## Escape hatches

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.13"
+  version: "2.14"
   audience: external
   type: workflow
 ---
@@ -351,7 +351,7 @@ output: z.object({
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
 - **Spill big tabular results to a queryable surface.** When a tool's row set can exceed any reasonable context budget — paginated APIs, streamed exports, big query results — pair an inline preview with a `DataCanvas` table holding the full set, returned as a token the agent can SQL. Compute distributions or refinement hints across the full result, not the preview, so aggregate signal stays honest. See `api-canvas` for the `spillover()` helper.
 - **`format()` is the markdown twin of `structuredContent` — make both content-complete.** Different MCP clients forward different surfaces to the model: some (e.g., Claude Code) read `structuredContent` from `output`, others (e.g., Claude Desktop) read `content[]` from `format()`. Both must carry the same data so every client sees the same picture — `format()` just dresses it up with markdown. A thin `format()` that returns only a count or title leaves `content[]`-only clients blind to data that `structuredContent` clients can see. Render all fields the LLM needs, with structured markdown (headers, bold labels, lists) for readability.
-- **Agent-facing context must reach both client surfaces — put it in `enrichment`.** `structuredContent` (from `output`) and `content[]` (from `format()`) are read by different clients. Empty-result notices, the query/filter as the server parsed it, and pagination totals — the context the agent *reasons with*, distinct from the domain payload — reach only `content[]` if hand-authored into `format()` text alone, leaving `structuredContent`-only clients (Claude Code) blind. (The reverse can't happen: `format-parity` drags every `output` field into `format()`, so `output`-authored context already reaches both.) An `enrichment` block — the success-path counterpart to `errors[]`, populated via `ctx.enrich(...)` — reaches both automatically: merged into `structuredContent`, advertised as `output.extend(enrichment)`, mirrored into a `content[]` trailer, no `format()` entry needed. See `add-tool`'s **Tool Response Design**.
+- **Agent-facing context must reach both client surfaces — put it in `enrichment`.** `structuredContent` (from `output`) and `content[]` (from `format()`) are read by different clients. Empty-result notices, the query/filter as the server parsed it, and pagination totals — the context the agent *reasons with*, distinct from the domain payload — reach only `content[]` if hand-authored into `format()` text alone, leaving `structuredContent`-only clients (Claude Code) blind. (The reverse can't happen: `format-parity` drags every `output` field into `format()`, so `output`-authored context already reaches both.) An `enrichment` block — the success-path counterpart to `errors[]`, populated via `ctx.enrich(...)` — reaches both automatically: merged into `structuredContent`, advertised as `output.extend(enrichment)`, mirrored into a `content[]` trailer, no `format()` entry needed. How each field renders in that trailer is a per-tool call — a kind-tag (`notice`/`total`/`echo`/`delta`) when a canonical form fits, a domain key like `totalFound` otherwise, and an `enrichmentTrailer.render` for any structured (object/array) field so it doesn't ship as a JSON blob. See `add-tool`'s **Tool Response Design**.
 
 #### Batch input design