@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/tools/sparse-fields.js

@@ -0,0 +1,165 @@
+/**
+ * Sparse-fields helper — projects per-item field whitelists onto tool
+ * responses and exposes per-tool default-sets that the AI client can rely
+ * on when calling read tools without a `fields` parameter.
+ *
+ * Design references:
+ *
+ *   - §3.5 Sparse-Fields Adaption: 4 read tools opt-in to `fields[]`;
+ *     the toolkit's `pickFields` is used directly; `projected_fields` is
+ *     echoed in the result envelope so the LLM can confirm exactly which
+ *     keys were kept.
+ *   - §4.4.1 — when used together with `flat: true` projection runs
+ *     AFTER the depth-first walk so paths are stable before narrowing.
+ *
+ * Reference implementation pattern: `connections.ts:721, 779-792, 810`
+ * in `@wootsup/apimapper-mcp`.
+ *
+ * The defaults are pure constants so they can be imported, exported, and
+ * asserted against in tests without any side-effects.
+ *
+ * @license MIT
+ */
+import { pickFields } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+// ─── Schema ──────────────────────────────────────────────────────────
+/**
+ * Optional whitelist of fields. Per Design §3.5 the cap is 40 to stop
+ * runaway prompts from blowing up the request size; nested paths
+ * (`props.title`) are supported by the toolkit's `pickFields`.
+ */
+export const FIELDS = z
+    .array(z.string().min(1))
+    .max(40)
+    .optional()
+    .describe('Optional whitelist of fields to keep per item (supports nested paths like ' +
+    '"props.title"). Default: tool-specific compact set (echoed in projected_fields). ' +
+    'Cuts response size — e.g. fields:["path","element_type","label"] for a minimal ' +
+    'navigation view.');
+/**
+ * Flag enabling client-side flattening on `page_get_layout`. When true
+ * the response shape switches from `{layout, etag}` to
+ * `{elements: [...], etag}` and `fields[]` projection becomes meaningful.
+ */
+export const FLAT = z
+    .boolean()
+    .default(false)
+    .describe('When true, response is a flat [{path, element_type, ...}] array. Enables ' +
+    'fields[] projection. Default: false (nested layout, no projection).');
+// ─── Default field-sets per tool ─────────────────────────────────────
+/**
+ * Default fields echoed when the caller omits `fields`. Following the
+ * apimapper-mcp convention these are **echo-only** — projection itself
+ * is skipped (default-all preserved) but `projected_fields` still
+ * surfaces the implicit compact set so the AI can plan future requests.
+ */
+export const DEFAULT_FIELDS_PAGES_LIST = [
+    'id',
+    'label',
+    'type',
+    'elements_count',
+    'modified_at',
+];
+export const DEFAULT_FIELDS_ELEMENT_LIST = [
+    'path',
+    'element_type',
+    'label',
+];
+export const DEFAULT_FIELDS_SCHEMA = [
+    'path',
+    'element_type',
+    'label',
+];
+export const DEFAULT_FIELDS_SOURCES_LIST = [
+    'name',
+    'label',
+    'origin',
+    'kind',
+];
+export const DEFAULT_FIELDS_TYPES_LIST = [
+    'name',
+    'label',
+    'origin',
+    'has_children_support',
+];
+/**
+ * element_get defaults to "all" because the AI often needs the full
+ * props payload for follow-up edits; sparse projection here is opt-in
+ * with nested-path support.
+ */
+export const DEFAULT_FIELDS_ELEMENT_GET = undefined;
+// ─── Pure projection helpers ─────────────────────────────────────────
+/**
+ * Project an array of items to the requested fields. Returns items
+ * unchanged when `fields` is undefined (default-all). Skips non-object
+ * entries without crashing (they pass through as-is).
+ *
+ * @param items - The items to project.
+ * @param fields - The whitelist; `undefined` skips projection.
+ * @param _defaults - Per-tool default set, accepted for interface symmetry
+ *   with `projectedFieldsEcho` (unused for actual projection — default-all
+ *   semantics matches the apimapper-mcp reference, see `connections.ts:789`).
+ */
+export function projectFields(items, fields, _defaults) {
+    if (fields === undefined) {
+        return [...items];
+    }
+    const mutable = [...fields];
+    return items.map((item) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            return item;
+        }
+        return pickFields(item, mutable);
+    });
+}
+/**
+ * Project a single object via the same `pickFields` rules. Returns the
+ * object unchanged when `fields` is undefined.
+ */
+export function projectFieldsSingle(obj, fields, _defaults) {
+    if (fields === undefined) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return obj;
+    }
+    return pickFields(obj, [...fields]);
+}
+/**
+ * Compute the `projected_fields` echo. Returns the caller-requested
+ * fields when provided; otherwise returns the per-tool default set so
+ * the AI client knows exactly which compact view it implicitly opted into.
+ *
+ * @returns `undefined` only when neither `requested` nor `defaults` was set
+ *   (e.g. `element_get` with no opt-in) — callers should omit
+ *   `projected_fields` from the structuredContent in that case.
+ */
+export function projectedFieldsEcho(requested, defaults) {
+    if (requested !== undefined)
+        return requested;
+    if (defaults !== undefined)
+        return defaults;
+    return undefined;
+}
+export function projectionFeedback(items, requested) {
+    if (requested === undefined || requested.length === 0)
+        return undefined;
+    const seen = new Set();
+    for (const item of items) {
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+            for (const k of Object.keys(item))
+                seen.add(k);
+        }
+    }
+    const available = [...seen].sort();
+    // A leaf-path counts as "known" if its TOP level matches a key on any
+    // item (the toolkit `pickFields` walks dotted paths — `props.title`
+    // is reachable as long as `props` exists; per-item depth would be
+    // overkill here).
+    const unknown = requested.filter((f) => {
+        const top = f.split('.')[0];
+        return top !== undefined && !seen.has(top);
+    });
+    return { available_fields: available, unknown_fields: unknown };
+}
+//# sourceMappingURL=sparse-fields.js.map

package/dist/tools/sparse-fields.js.map

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

package/dist/tools/tool-builder/annotations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `tool-builder/annotations` — annotation builders that produce the
+ * MCP `ToolAnnotations` shape. Each helper encodes a verified
+ * read/write/destructive policy so call-sites in domain tools (pages,
+ * elements, sources, …) get a single one-liner instead of repeating
+ * the four-flag pattern verbatim.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * Audit-v3 / Stream D3 T3 (2026-05-22) — per Anthropic MCP spec
+ * 2026-03-16 "Tool Annotations", every registered tool MUST advertise
+ * the full 4-tuple `{readOnlyHint, destructiveHint, idempotentHint,
+ * openWorldHint}`. Hosts treat `undefined` hints as "potentially
+ * destructive" — defaulting `destructiveHint:false` and
+ * `idempotentHint:true/false` explicitly removes that ambiguity for
+ * read-only and additive tools.
+ *
+ * `openWorldHint:false` reflects the closed Builder domain: the REST
+ * surface writes to a single local `wp_option('yootheme')` blob —
+ * there is no external network side-effect or world-modifying action.
+ * The gateway (`yootheme_builder_advanced`) is the exception (its
+ * effective behaviour is dynamic, decided at call-time).
+ *
+ * @license MIT
+ */
+import type { ToolAnnotations } from './types.js';
+/**
+ * Build a `readOnly` annotation.
+ *
+ * Reads are idempotent by definition — repeating a read returns the
+ * same data (modulo concurrent writes). Setting `idempotentHint:true`
+ * is informative for hosts that surface a "safe-to-retry" badge.
+ */
+export declare function readOnly(title?: string): ToolAnnotations;
+/**
+ * Build a `mutating` annotation for idempotent updates (PUT-style
+ * writes — full replacement semantics where repeating the call with
+ * the same inputs yields the same end-state).
+ */
+export declare function mutating(title?: string): ToolAnnotations;
+/**
+ * Build a `creating` annotation for non-idempotent creates (POST-style
+ * writes — repeating the call produces additional elements / new IDs).
+ */
+export declare function creating(title?: string): ToolAnnotations;
+/**
+ * Build a `destructive` annotation. Callers MUST also expose a
+ * `confirm` param + preview guard (see annotations-pin.test.ts).
+ *
+ * Destructive ops are inherently non-idempotent (the first call
+ * removes data; the second call hits a 404 / already-gone state).
+ */
+export declare function destructive(title?: string): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/tools/tool-builder/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQxD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQxD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQ3D"}

package/dist/tools/tool-builder/annotations.js

@@ -0,0 +1,86 @@
+/**
+ * `tool-builder/annotations` — annotation builders that produce the
+ * MCP `ToolAnnotations` shape. Each helper encodes a verified
+ * read/write/destructive policy so call-sites in domain tools (pages,
+ * elements, sources, …) get a single one-liner instead of repeating
+ * the four-flag pattern verbatim.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * Audit-v3 / Stream D3 T3 (2026-05-22) — per Anthropic MCP spec
+ * 2026-03-16 "Tool Annotations", every registered tool MUST advertise
+ * the full 4-tuple `{readOnlyHint, destructiveHint, idempotentHint,
+ * openWorldHint}`. Hosts treat `undefined` hints as "potentially
+ * destructive" — defaulting `destructiveHint:false` and
+ * `idempotentHint:true/false` explicitly removes that ambiguity for
+ * read-only and additive tools.
+ *
+ * `openWorldHint:false` reflects the closed Builder domain: the REST
+ * surface writes to a single local `wp_option('yootheme')` blob —
+ * there is no external network side-effect or world-modifying action.
+ * The gateway (`yootheme_builder_advanced`) is the exception (its
+ * effective behaviour is dynamic, decided at call-time).
+ *
+ * @license MIT
+ */
+/**
+ * Build a `readOnly` annotation.
+ *
+ * Reads are idempotent by definition — repeating a read returns the
+ * same data (modulo concurrent writes). Setting `idempotentHint:true`
+ * is informative for hosts that surface a "safe-to-retry" badge.
+ */
+export function readOnly(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
+}
+/**
+ * Build a `mutating` annotation for idempotent updates (PUT-style
+ * writes — full replacement semantics where repeating the call with
+ * the same inputs yields the same end-state).
+ */
+export function mutating(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
+}
+/**
+ * Build a `creating` annotation for non-idempotent creates (POST-style
+ * writes — repeating the call produces additional elements / new IDs).
+ */
+export function creating(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    };
+}
+/**
+ * Build a `destructive` annotation. Callers MUST also expose a
+ * `confirm` param + preview guard (see annotations-pin.test.ts).
+ *
+ * Destructive ops are inherently non-idempotent (the first call
+ * removes data; the second call hits a 404 / already-gone state).
+ */
+export function destructive(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
+    };
+}
+//# sourceMappingURL=annotations.js.map

package/dist/tools/tool-builder/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO;QACH,KAAK;QACL,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO;QACH,KAAK;QACL,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO;QACH,KAAK;QACL,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,KAAK;KACvB,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACtC,OAAO;QACH,KAAK;QACL,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,IAAI;QACrB,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,KAAK;KACvB,CAAC;AACN,CAAC"}

package/dist/tools/tool-builder/define.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `tool-builder/define` — the `defineTool` identity helper plus the
+ * progress-reporter re-export.
+ *
+ * `defineTool` is intentionally trivial at runtime (returns its
+ * argument verbatim) — its only job is to preserve the inferred Zod
+ * schema shape so each tool's handler is fully type-checked against
+ * its inputSchema. The wrapping/sanitising work happens in
+ * `results.ts`.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+import { createProgressReporter as toolkitCreateProgressReporter } from '@getimo/mcp-toolkit';
+import type { ZodRawShape } from 'zod';
+import type { ToolDefinition } from './types.js';
+/**
+ * Re-export the toolkit's `createProgressReporter` under a stable
+ * local symbol so every write-handler in this package depends on a
+ * single import path. Returns `null` when the caller sent no
+ * `progressToken` — handlers then no-op via `progress?.report(...)`.
+ */
+export declare const createProgressReporter: typeof toolkitCreateProgressReporter;
+/**
+ * `defineTool` — preserves the inferred Zod-schema shape so each
+ * tool's handler is fully type-checked against its inputSchema.
+ */
+export declare function defineTool<TSchema extends ZodRawShape>(def: ToolDefinition<TSchema>): ToolDefinition<TSchema>;
+//# sourceMappingURL=define.d.ts.map

package/dist/tools/tool-builder/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,sBAAsB,IAAI,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,sCAAgC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,WAAW,EAClD,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,GAC7B,cAAc,CAAC,OAAO,CAAC,CAEzB"}

package/dist/tools/tool-builder/define.js

@@ -0,0 +1,31 @@
+/**
+ * `tool-builder/define` — the `defineTool` identity helper plus the
+ * progress-reporter re-export.
+ *
+ * `defineTool` is intentionally trivial at runtime (returns its
+ * argument verbatim) — its only job is to preserve the inferred Zod
+ * schema shape so each tool's handler is fully type-checked against
+ * its inputSchema. The wrapping/sanitising work happens in
+ * `results.ts`.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+import { createProgressReporter as toolkitCreateProgressReporter } from '@getimo/mcp-toolkit';
+/**
+ * Re-export the toolkit's `createProgressReporter` under a stable
+ * local symbol so every write-handler in this package depends on a
+ * single import path. Returns `null` when the caller sent no
+ * `progressToken` — handlers then no-op via `progress?.report(...)`.
+ */
+export const createProgressReporter = toolkitCreateProgressReporter;
+/**
+ * `defineTool` — preserves the inferred Zod-schema shape so each
+ * tool's handler is fully type-checked against its inputSchema.
+ */
+export function defineTool(def) {
+    return def;
+}
+//# sourceMappingURL=define.js.map

package/dist/tools/tool-builder/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,sBAAsB,IAAI,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAI9F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAEpE;;;GAGG;AACH,MAAM,UAAU,UAAU,CACtB,GAA4B;IAE5B,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/tools/tool-builder/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `tool-builder/index` — barrel re-export for the split
+ * tool-definition system.
+ *
+ * Round-1.5: structural split of the former monolithic
+ * `tool-builder.ts` (320 LoC). Cohesion is preserved by topic:
+ *
+ *   - `types.ts`        — pure type declarations (no runtime imports
+ *                         beyond type-only `zod` + SDK notifications)
+ *   - `annotations.ts`  — `readOnly` / `mutating` / `creating` /
+ *                         `destructive` annotation builders
+ *   - `results.ts`      — `jsonResult` / `errorResult` /
+ *                         `structuredResult` / `confirmGuard` envelope
+ *                         builders + the shared `sanitizeContentItem`
+ *                         helper (single LLM-boundary mask)
+ *   - `define.ts`       — `defineTool` identity helper + progress-
+ *                         reporter re-export
+ *
+ * The parent file `../tool-builder.ts` re-exports this barrel so
+ * existing `./tool-builder.js` imports keep working without churn.
+ *
+ * @license MIT
+ */
+export type { AnyToolDefinition, HandlerExtra, ToolAnnotations, ToolContent, ToolDefinition, ToolHandler, ToolResult, } from './types.js';
+export { creating, destructive, mutating, readOnly, } from './annotations.js';
+export { confirmGuard, errorResult, jsonResult, structuredResult, withSiteMeta, } from './results.js';
+export { createProgressReporter, defineTool } from './define.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/tool-builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EACR,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACH,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/tools/tool-builder/index.js

@@ -0,0 +1,27 @@
+/**
+ * `tool-builder/index` — barrel re-export for the split
+ * tool-definition system.
+ *
+ * Round-1.5: structural split of the former monolithic
+ * `tool-builder.ts` (320 LoC). Cohesion is preserved by topic:
+ *
+ *   - `types.ts`        — pure type declarations (no runtime imports
+ *                         beyond type-only `zod` + SDK notifications)
+ *   - `annotations.ts`  — `readOnly` / `mutating` / `creating` /
+ *                         `destructive` annotation builders
+ *   - `results.ts`      — `jsonResult` / `errorResult` /
+ *                         `structuredResult` / `confirmGuard` envelope
+ *                         builders + the shared `sanitizeContentItem`
+ *                         helper (single LLM-boundary mask)
+ *   - `define.ts`       — `defineTool` identity helper + progress-
+ *                         reporter re-export
+ *
+ * The parent file `../tool-builder.ts` re-exports this barrel so
+ * existing `./tool-builder.js` imports keep working without churn.
+ *
+ * @license MIT
+ */
+export { creating, destructive, mutating, readOnly, } from './annotations.js';
+export { confirmGuard, errorResult, jsonResult, structuredResult, withSiteMeta, } from './results.js';
+export { createProgressReporter, defineTool } from './define.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/tool-builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EACH,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/tools/tool-builder/results.d.ts

@@ -0,0 +1,104 @@
+/**
+ * `tool-builder/results` — envelope builders (`jsonResult`,
+ * `errorResult`, `structuredResult`, `confirmGuard`) + the shared
+ * `sanitizeContentItem` helper. Every payload accepted here runs
+ * through the `sanitizeSecrets` / `sanitizeForLogs` boundary so an
+ * upstream regression can never land in the LLM context. The mask
+ * is concentrated here — `define.ts` and call-sites do not re-mask.
+ *
+ * Split from `tool-builder.ts` in Round-1.5.
+ *
+ * @license MIT
+ */
+import type { ResolvedSite } from '../../sites/registry.js';
+import type { ToolContent, ToolResult } from './types.js';
+/**
+ * Convert any JSON-serializable value into the MCP content envelope
+ * (2-space JSON). Wave G.6.4b: every payload is deep-walked through
+ * `sanitizeSecrets` before stringification so an upstream regression
+ * (REST handler surfacing `oauth_refresh_token`, `auth_data`, etc.)
+ * can never land in the LLM context.
+ */
+export declare function jsonResult(payload: unknown, options?: {
+    isError?: boolean;
+}): ToolResult;
+/**
+ * Render a structured error result with `context` (echoed input) and a
+ * recovery `hint`. Wave G.6.3 defense-in-depth: message is
+ * mask-and-truncate'd; context is deep-walked so an input param that
+ * accidentally echoed a secret-bearing value cannot leak.
+ */
+export declare function errorResult(opts: {
+    error: unknown;
+    context: Record<string, unknown>;
+    hint: string;
+}): ToolResult;
+/**
+ * Confirm-guard preview helper for destructive tools. Returns the
+ * preview `ToolResult` when `confirm` is false; callers `return` it
+ * before executing the destructive REST call.
+ */
+export declare function confirmGuard(opts: {
+    operation: string;
+    details: Record<string, unknown>;
+}): ToolResult;
+/**
+ * Merge a toolkit `StructuredCallToolResult` (carries `content[0].text`
+ * + `_meta.ui`) with a domain-typed `structuredContent` payload. The
+ * result satisfies both Rich-Card hosts (read `_meta.ui`) AND
+ * structured-output hosts (read `structuredContent`, may validate
+ * against `outputSchema`). Single envelope-merger from every migrated
+ * tool's handler — toolkit builders are wrapped, not modified.
+ */
+/**
+ * W6.2 — site-awareness envelope wrapper.
+ *
+ * Stamps a resolved-site descriptor onto a tool result so the human +
+ * agent both know which connected site the call ran against. Two
+ * channels:
+ *
+ *   1. **text-prefix PRIMARY surface** — `[<label or site_id> @
+ *      <hostname>] ` is injected at the start of `content[0].text`
+ *      when that block is a text item. Per the W6 web-research
+ *      addendum (HCFV §B, Claude-Desktop UI gap doc'd in plan
+ *      Z.1329-1332), `_meta` is read by the agent but NOT rendered as
+ *      a UI widget today — so the prefix is the only thing Maria the
+ *      Claude-Desktop-user reliably SEES. LOAD-BEARING.
+ *
+ *   2. **result-level `_meta` SECONDARY surface** — `_meta:
+ *      {site_id, site_url, platform}` is merged into the RESULT-level
+ *      `_meta` (alongside the toolkit's `_meta.ui`). This is the
+ *      MCP-spec metadata channel: free-form and NOT validated against
+ *      the tool's `outputSchema`.
+ *
+ *      W12-R2 fix: site meta was previously merged into
+ *      `structuredContent._meta`. That broke real hosts. Every tool's
+ *      `outputSchema` is generated with `additionalProperties:false`,
+ *      so an undeclared `_meta` key inside `structuredContent` fails
+ *      client-side schema validation (`-32602`) and surfaces as a
+ *      "Failed to call tool" toast in Claude Desktop EVEN ON A
+ *      SUCCESSFUL CALL. `live-verify.mjs` never caught it because raw
+ *      JSON-RPC calls skip the host's structuredContent↔outputSchema
+ *      validation. `structuredContent` must stay schema-pure.
+ *
+ * Pure function: never mutates the input result. Non-text blocks
+ * (resource / image / etc.) pass through verbatim. `structuredContent`
+ * is passed through UNTOUCHED so it always validates against
+ * `outputSchema`. Empty `content[]` is tolerated and produces a
+ * prefix-free result (the meta still lands in result-level `_meta`).
+ *
+ * Label-fallback: `site.label` wins; falls back to `site.id`.
+ *
+ * Hostname extraction defaults to `new URL(site.url).host`. A
+ * malformed URL falls back to the raw site.url string so the prefix
+ * remains user-readable even when the registry was hand-edited.
+ */
+export declare function withSiteMeta<R extends ToolResult>(result: R, site: ResolvedSite): R;
+export declare function structuredResult(toolkitResult: {
+    content: ToolContent[];
+    _meta?: {
+        ui?: unknown;
+    } & Record<string, unknown>;
+    isError?: boolean;
+}, structuredContent: Record<string, unknown>): ToolResult;
+//# sourceMappingURL=results.d.ts.map

package/dist/tools/tool-builder/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAYb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,UAAU,CAQb;AAuBD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CA2DH;AAED,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,EACD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,UAAU,CAgBZ"}