@wootsup/yt-builder-mcp 1.0.1 → 1.1.0

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,93 @@
+/**
+ * `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. **`structuredContent._meta` SECONDARY surface** — `_meta:
+ *      {site_id, site_url, platform}` is merged into the structured
+ *      payload. MCP-spec-conform metadata channel; future host
+ *      versions are expected to surface this natively.
+ *
+ * Pure function: never mutates the input result. Non-text blocks
+ * (resource / image / etc.) pass through verbatim. Existing
+ * `structuredContent` fields are preserved — only `_meta` is added or
+ * augmented. Empty `content[]` is tolerated and produces a
+ * prefix-free result (the meta still lands in structuredContent).
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CAyDH;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"}

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

@@ -0,0 +1,211 @@
+/**
+ * `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 { NetworkError, RestError } from '../../errors.js';
+import { sanitizeForLogs } from '../../errors/mask.js';
+import { sanitizeSecrets } from '../../errors/sanitize.js';
+function stringify(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * 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 function jsonResult(payload, options = {}) {
+    const safe = sanitizeSecrets(payload);
+    return {
+        content: [{ type: 'text', text: stringify(safe) }],
+        ...(options.isError === true ? { isError: true } : {}),
+    };
+}
+/** Extract `(message, status?, code?)` from any thrown value, honouring
+ * `RestError` / `NetworkError` shape distinctions. */
+function describeError(e) {
+    if (e instanceof RestError)
+        return { message: e.message, status: e.status, code: e.code };
+    if (e instanceof NetworkError)
+        return { message: e.message };
+    if (e instanceof Error)
+        return { message: e.message };
+    return { message: stringify(e) };
+}
+/**
+ * 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 function errorResult(opts) {
+    const { message, status, code } = describeError(opts.error);
+    return jsonResult({
+        error: sanitizeForLogs(message),
+        ...(status !== undefined ? { status } : {}),
+        ...(code !== undefined ? { code } : {}),
+        context: sanitizeSecrets(opts.context),
+        hint: opts.hint,
+    }, { isError: true });
+}
+/**
+ * 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 function confirmGuard(opts) {
+    return jsonResult({
+        preview: true,
+        warning: 'DESTRUCTIVE — Confirmation required',
+        operation: opts.operation,
+        details: opts.details,
+        instruction: 'Ask the user to confirm, then call again with `confirm: true`.',
+    });
+}
+/**
+ * Sanitise a single content item from a toolkit builder. Text items
+ * frequently embed a JSON-stringified payload — if it parses, deep-walk
+ * and re-stringify; otherwise leave as-is (toolkit-rendered tables /
+ * details are already domain-mapped at the call site).
+ */
+function sanitizeContentItem(item) {
+    if (item.type !== 'text' || typeof item.text !== 'string')
+        return item;
+    const text = item.text;
+    try {
+        const parsed = JSON.parse(text);
+        const safe = sanitizeSecrets(parsed);
+        return { ...item, text: stringify(safe) };
+    }
+    catch {
+        // Not JSON — toolkit-rendered text. No structural redaction
+        // possible without false-positives; the caller has already
+        // mapped raw secrets out via field-projection helpers.
+        return item;
+    }
+}
+/**
+ * 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. **`structuredContent._meta` SECONDARY surface** — `_meta:
+ *      {site_id, site_url, platform}` is merged into the structured
+ *      payload. MCP-spec-conform metadata channel; future host
+ *      versions are expected to surface this natively.
+ *
+ * Pure function: never mutates the input result. Non-text blocks
+ * (resource / image / etc.) pass through verbatim. Existing
+ * `structuredContent` fields are preserved — only `_meta` is added or
+ * augmented. Empty `content[]` is tolerated and produces a
+ * prefix-free result (the meta still lands in structuredContent).
+ *
+ * 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 function withSiteMeta(result, site) {
+    const displayLabel = site.label ?? site.id;
+    let host;
+    try {
+        host = new URL(site.url).host;
+    }
+    catch {
+        host = site.url;
+    }
+    const prefix = `[${displayLabel} @ ${host}] `;
+    const meta = {
+        site_id: site.id,
+        site_url: site.url,
+        platform: site.platform.kind,
+    };
+    // W12-R1.2 (A4-F2): site-awareness is the LOAD-BEARING surface for
+    // Claude-Desktop users. When the wrapped result has no text content
+    // (e.g. an image-only / resource-only / empty-list response), the
+    // prefix would otherwise be lost and the agent would have no visible
+    // signal of which site the call ran against. Prepend a synthetic
+    // text block so the prefix is ALWAYS the first visible glyph.
+    // Trim the trailing space — a standalone prefix block reads better
+    // without it.
+    const firstItem = result.content[0];
+    const needsSynthetic = result.content.length === 0
+        || firstItem === undefined
+        || firstItem.type !== 'text';
+    const newContent = needsSynthetic
+        ? [
+            { type: 'text', text: prefix.trimEnd() },
+            ...result.content,
+        ]
+        : result.content.map((item, idx) => {
+            if (idx !== 0)
+                return item;
+            if (item.type !== 'text')
+                return item;
+            const existingText = typeof item.text === 'string' ? item.text : '';
+            return { ...item, text: prefix + existingText };
+        });
+    const baseStructured = result.structuredContent ?? {};
+    const existingMeta = baseStructured._meta;
+    const mergedMeta = existingMeta !== undefined && existingMeta !== null && typeof existingMeta === 'object'
+        ? { ...existingMeta, ...meta }
+        : meta;
+    return {
+        ...result,
+        content: newContent,
+        structuredContent: {
+            ...baseStructured,
+            _meta: mergedMeta,
+        },
+    };
+}
+export function structuredResult(toolkitResult, structuredContent) {
+    // Wave G.6.4b — deep-walk-sanitise all three legs (text content,
+    // _meta.ui, structuredContent) so regressing sources never bypass
+    // the LLM-boundary mask.
+    const safeContent = toolkitResult.content.map(sanitizeContentItem);
+    const safeStructured = sanitizeSecrets(structuredContent);
+    const safeMeta = toolkitResult._meta !== undefined
+        ? sanitizeSecrets(toolkitResult._meta)
+        : undefined;
+    return {
+        content: safeContent,
+        ...(safeMeta !== undefined ? { _meta: safeMeta } : {}),
+        ...(toolkitResult.isError === true ? { isError: true } : {}),
+        structuredContent: safeStructured,
+    };
+}
+//# sourceMappingURL=results.js.map

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

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