@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

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

@@ -1,18 +1,8 @@
-/**
- * `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';
+import { redactCredentials } from '../../errors/redact-credentials.js';
+import { activeSiteFromResolution, withActiveSiteKey } from '../active-site.js';
 function stringify(value) {
     try {
         return JSON.stringify(value, null, 2);
@@ -21,37 +11,7 @@ function stringify(value) {
         return String(value);
     }
 }
-/**
- * F80 (2026-06-10): the size at/above which a JSON-document text body is
- * split off into its own content block instead of carrying the in-band
- * `[label @ host] ` site-prefix.
- *
- * Why a threshold rather than "all JSON": a tool host (Claude Code, …)
- * spills only OVERSIZED tool results to a temp file. That file is read
- * back with `jq`, so the bytes must be pure JSON — an in-band prefix
- * corrupts the first line and breaks the parse (the observed F80
- * friction on `page_get_layout`, a multi-kB layout dump). Small JSON
- * envelopes (error results, single-element confirms, short lists) are
- * NEVER dumped, so they keep the in-band prefix — which preserves the
- * long-standing contract that `content[0].text` is the directly-parseable
- * JSON for those results (141 error-matrix / handler tests depend on it).
- *
- * 8 kB is comfortably below any host's spill threshold yet above every
- * small structured envelope this surface emits.
- */
 export const SITE_PREFIX_JSON_SPLIT_THRESHOLD = 8 * 1024;
-/**
- * Detect whether a text body is a PURE JSON DOCUMENT (object or array)
- * LARGE enough that a host might spill it to a `jq`-read temp file.
- * Tools like `page_get_layout` emit `jsonResult(data)` whose
- * `content[0].text` IS the JSON payload; for a large layout that text
- * lands in the dump verbatim, so an in-band `[label @ host] ` prefix
- * would corrupt the first bytes.
- *
- * Only OBJECT / ARRAY documents qualify (a bare scalar like `"hello"`
- * stays in-band). The cheap length + first-glyph pre-checks avoid a
- * JSON.parse on every human-readable table on the hot path.
- */
 function isLargeJsonDocumentText(text) {
     if (text.length < SITE_PREFIX_JSON_SPLIT_THRESHOLD)
         return false;
@@ -67,13 +27,6 @@ function isLargeJsonDocumentText(text) {
         return false;
     }
 }
-/**
- * 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 {
@@ -81,8 +34,27 @@ export function jsonResult(payload, options = {}) {
         ...(options.isError === true ? { isError: true } : {}),
     };
 }
-/** Extract `(message, status?, code?)` from any thrown value, honouring
- * `RestError` / `NetworkError` shape distinctions. */
+export function rejectionOnBothLegs(payload) {
+    const safe = sanitizeSecrets(redactStrings(payload));
+    const r = jsonResult(safe, { isError: true });
+    if (safe === null || typeof safe !== 'object' || Array.isArray(safe))
+        return r;
+    return { ...r, structuredContent: safe };
+}
+function redactStrings(value) {
+    if (typeof value === 'string')
+        return redactCredentials(value);
+    if (Array.isArray(value))
+        return value.map(redactStrings);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactStrings(v);
+        }
+        return out;
+    }
+    return value;
+}
 function describeError(e) {
     if (e instanceof RestError)
         return { message: e.message, status: e.status, code: e.code };
@@ -92,15 +64,6 @@ function describeError(e) {
         return { message: e.message };
     return { message: stringify(e) };
 }
-/**
- * G7 — pull the whitelisted nearest-path self-correction keys out of a thrown
- * value's `RestError.body`, if present. GENERIC: the moment any plugin version
- * emits the envelope on a 404, the Node HTTP path forwards it — mirroring the
- * already-self-correcting in-process path. Only `RestError` carries a parsed
- * upstream body; every other thrown value yields an empty envelope. The four
- * keys are individually type-guarded (a `null` `nearest_path` is preserved as a
- * legitimate "no candidate" signal); unknown keys never leak through.
- */
 function nearestPathFromError(e) {
     if (!(e instanceof RestError))
         return {};
@@ -119,27 +82,10 @@ function nearestPathFromError(e) {
     if (Array.isArray(b.available_paths) && b.available_paths.every((p) => typeof p === 'string')) {
         out.available_paths = b.available_paths;
     }
-    // N4: the canonical id-form a bare-numeric not-found should re-address with.
     if (typeof b.expected_id_form === 'string')
         out.expected_id_form = b.expected_id_form;
     return out;
 }
-/**
- * ELEMENT_WRITE-2 — pull the CURRENT resource ETag out of a 412 RestError so a
- * stale-ETag write can be retried MECHANICALLY (copy `current_etag` from the
- * error, retry) instead of forcing an extra `get_etag` round-trip.
- *
- * A 412 (precondition-failed) write carries the live ETag in TWO possible
- * shapes: a structured `body.data.current_etag` (the canonical field a PHP host
- * emits) OR, on a host that only put it in prose, the message
- * `…does not match current resource ETag (…-r346)`. Both are checked; the
- * structured field wins. Returns the empty string sentinel `undefined` when the
- * error is not a 412 or carries no recoverable ETag, so the caller spreads
- * nothing on the happy path.
- *
- * Only `RestError` at status 412 is considered — a non-412 message that happens
- * to contain the phrase is never mined (it would surface a misleading value).
- */
 function currentEtagFromError(e) {
     if (!(e instanceof RestError) || e.status !== 412)
         return {};
@@ -163,20 +109,7 @@ function currentEtagFromError(e) {
     }
     return {};
 }
-/**
- * MM-2 / BUG-2 — the transport-side bound on a forwarded candidate list.
- *
- * Mirrors PHP's `AMBIGUITY_CANDIDATE_CAP = 10`, which BOTH producers already
- * apply before the list ever leaves the host, so in practice this is never
- * reached. It exists so a newer (or hostile) host cannot blow the error
- * envelope — and when it IS reached, `candidates_truncated` says so, because a
- * silently-shortened chooser would let an agent conclude it had seen every
- * option after trying the tenth.
- */
 const CANDIDATE_FORWARD_CAP = 10;
-/** Type-guard ONE candidate row. All three members are load-bearing: `id` is
- * what the retry addresses, `label` is what the user is shown, `type` is how
- * the two are told apart in a mixed page/template/category list. */
 function isAmbiguityCandidate(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -186,28 +119,6 @@ function isAmbiguityCandidate(value) {
         && typeof row.label === 'string'
         && typeof row.type === 'string');
 }
-/**
- * MM-2 / BUG-2 — pull the AMBIGUITY CANDIDATE LIST out of a thrown value's
- * `RestError.body`.
- *
- * `title_ambiguous` (both platforms) and `blog_ambiguous` (Joomla) answer 409
- * with a list of distinct, addressable pages, and the MESSAGE they carry tells
- * the agent to pick one of them. Both in-process handlers already forward it
- * (`McpPagesResolveHandler` / `McpPagesAuditHandler`); without this the Node
- * transport handed the agent prose promising a list it never received — the
- * same tool answering the same site differently per transport.
- *
- * `data.candidates` is checked FIRST because it is where both CMSes actually
- * put it: WordPress via `WP_Error`'s data bag
- * (`PagesController::targetErrorResponse()`) and Joomla via
- * `JoomlaJsonResponse::error()`, which merges its `$data` into the SAME
- * WP-compatible `data:{…}` envelope. The top-level fallback costs one lookup
- * and covers any flatter envelope a future host emits.
- *
- * ALL-OR-NOTHING on shape: a list the agent renders as a chooser has to be
- * trustworthy, so one unusable row drops the whole list rather than presenting
- * a chooser with a dead option in it (the prose message still names the count).
- */
 function candidatesFromError(e) {
     if (!(e instanceof RestError))
         return {};
@@ -227,74 +138,254 @@ function candidatesFromError(e) {
         ? { candidates: raw.slice(0, CANDIDATE_FORWARD_CAP), candidates_truncated: true }
         : { candidates: [...raw] };
 }
-/**
- * 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.
- */
+function isPlacementWay(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.placement === 'string'
+        && typeof v.reach === 'string'
+        && typeof v.summary === 'string'
+        && (v.can_limit_to_pages === undefined || typeof v.can_limit_to_pages === 'boolean'));
+}
+function waysFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? (nested.ways ?? b.ways)
+        : b.ways;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return {};
+    if (!raw.every(isPlacementWay))
+        return {};
+    return { ways: raw };
+}
+function notesFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? (nested.notes ?? b.notes)
+        : b.notes;
+    if (!isStringArray(raw) || raw.length === 0)
+        return {};
+    return { notes: [...raw] };
+}
+function isRemovalIntent(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.intent === 'string'
+        && typeof v.effect === 'string'
+        && typeof v.reversible === 'boolean'
+        && typeof v.native_name === 'string'
+        && (v.restore_call === undefined
+            || v.restore_call === null
+            || typeof v.restore_call === 'string'));
+}
+function intentsFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? (nested.intents ?? b.intents)
+        : b.intents;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return {};
+    if (!raw.every(isRemovalIntent))
+        return {};
+    return { intents: [...raw] };
+}
+function currentStateFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? (nested.current_state ?? b.current_state)
+        : b.current_state;
+    return typeof raw === 'string' && raw !== '' ? { current_state: raw } : {};
+}
+function declaredPositionsFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? (nested.declared_positions ?? b.declared_positions)
+        : b.declared_positions;
+    if (!isStringArray(raw) || raw.length === 0)
+        return {};
+    return { declared_positions: [...raw] };
+}
+const UNKNOWN_SOURCE_LIST_CAP = CANDIDATE_FORWARD_CAP;
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+function unknownSourceFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const data = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? nested
+        : b;
+    const given = data.given;
+    const didYouMean = data.did_you_mean;
+    const allPublished = data.all_published_sources;
+    if (typeof given !== 'string')
+        return {};
+    if (!isStringArray(didYouMean) || !isStringArray(allPublished))
+        return {};
+    const truncated = allPublished.length > UNKNOWN_SOURCE_LIST_CAP;
+    return {
+        given,
+        did_you_mean: didYouMean.slice(0, UNKNOWN_SOURCE_LIST_CAP),
+        all_published_sources: allPublished.slice(0, UNKNOWN_SOURCE_LIST_CAP),
+        ...(truncated ? { all_published_sources_truncated: true } : {}),
+    };
+}
+function serverHintFromError(error) {
+    const body = error?.body;
+    if (body === null || typeof body !== 'object')
+        return {};
+    const b = body;
+    const nested = b.data;
+    const raw = typeof b.hint === 'string'
+        ? b.hint
+        : nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+            ? nested.hint
+            : undefined;
+    return typeof raw === 'string' && raw.trim() !== '' ? { server_hint: raw } : {};
+}
+export const PASSTHROUGH_ERROR_KEYS = [
+    'element_path',
+    'expected_etag',
+    'error_code',
+    'retry_after',
+    'retry_after_ms',
+    'retry_after_seconds',
+    'limit',
+    'window_seconds',
+    'required_scope',
+    'token_scope',
+    'remediation',
+    'min_client',
+    'current_client',
+];
+const RESERVED_RESULT_KEYS = new Set(['error', 'status', 'code', 'context', 'hint']);
+for (const key of PASSTHROUGH_ERROR_KEYS) {
+    if (RESERVED_RESULT_KEYS.has(key)) {
+        throw new Error(`PASSTHROUGH_ERROR_KEYS must never shadow the fixed errorResult() key "${key}"`);
+    }
+}
+const PASSTHROUGH_VALUE_MAX_JSON_LENGTH = 2000;
+function isForwardableScalar(value) {
+    if (typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return typeof value === 'string';
+}
+function passthroughFieldsFromError(e) {
+    if (!(e instanceof RestError))
+        return {};
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    const nested = b.data;
+    const data = nested !== null && typeof nested === 'object' && !Array.isArray(nested)
+        ? nested
+        : undefined;
+    const out = {};
+    for (const key of PASSTHROUGH_ERROR_KEYS) {
+        const raw = data?.[key] ?? b[key];
+        if (!isForwardableScalar(raw))
+            continue;
+        if (stringify(raw).length > PASSTHROUGH_VALUE_MAX_JSON_LENGTH)
+            continue;
+        out[key] = raw;
+    }
+    return out;
+}
 export function errorResult(opts) {
     const { message, status, code } = describeError(opts.error);
-    // G7 (self-correcting errors): forward the shared nearest-path envelope when
-    // the upstream 404 body carried it, so the agent retries IN-LOOP — the SAME
-    // contract the in-process MCP surfaces emit. Spread LAST so it rides
-    // alongside (never clobbers) error/status/code/context/hint; absent on every
-    // non-enriched failure (empty envelope → no extra keys).
+    const passthrough = passthroughFieldsFromError(opts.error);
     const nearest = nearestPathFromError(opts.error);
-    // MM-2: the ambiguity candidate list rides the SAME way — spread last,
-    // alongside (never over) error/status/code/context/hint, and absent
-    // entirely on every non-ambiguous failure.
+    const unknownSource = unknownSourceFromError(opts.error);
     const candidates = candidatesFromError(opts.error);
-    // ELEMENT_WRITE-2 / PAGES_LIBRARY_MEDIA-7: a 412 write carries the live
-    // ETag; surface it as `current_etag` so a retry is mechanical (no extra
-    // get_etag round-trip). Spread last, alongside (never over) the other keys;
-    // absent on every non-412 failure.
     const currentEtag = currentEtagFromError(opts.error);
+    const serverHintRaw = serverHintFromError(opts.error);
+    const serverHint = serverHintRaw.server_hint !== undefined && serverHintRaw.server_hint !== opts.hint
+        ? serverHintRaw
+        : {};
+    const ways = waysFromError(opts.error);
+    const notes = notesFromError(opts.error);
+    const declaredPositions = declaredPositionsFromError(opts.error);
+    const intents = intentsFromError(opts.error);
+    const currentState = currentStateFromError(opts.error);
     return jsonResult({
         error: sanitizeForLogs(message),
         ...(status !== undefined ? { status } : {}),
         ...(code !== undefined ? { code } : {}),
         context: sanitizeSecrets(opts.context),
         hint: opts.hint,
+        ...passthrough,
+        ...unknownSource,
         ...nearest,
         ...candidates,
         ...currentEtag,
+        ...ways,
+        ...notes,
+        ...declaredPositions,
+        ...intents,
+        ...currentState,
+        ...serverHint,
     }, { 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.
- *
- * F131 (Wave 4a): the blocked-state result is now STRUCTURALLY distinct
- * from a successful mutation. Previously the preview was a plain
- * `jsonResult` with no `isError` — envelope-identical to a success — so a
- * model that did not parse `preview:true` read "delete succeeded" and
- * silently left the element in place (the dry-run / silent-no-op footgun
- * class). Three redundant signals now make the block unmistakable:
- *   1. result-level `isError: true` (hosts that only read the error flag),
- *   2. body `applied: false` + `requires_confirmation: true` (structured
- *      consumers),
- *   3. a leading "NOT EXECUTED" line in the human-readable warning text
- *      (models that skim prose).
- */
 export function confirmGuard(opts) {
-    return jsonResult({
+    const warning = `NOT EXECUTED — DESTRUCTIVE operation requires confirmation. ` +
+        `The "${opts.operation}" call was BLOCKED and nothing was changed.`;
+    const instruction = 'Ask the user to confirm, then call again with `confirm: true`.';
+    return structuredResult(jsonResult({
         preview: true,
         applied: false,
         requires_confirmation: true,
-        warning: `NOT EXECUTED — DESTRUCTIVE operation requires confirmation. The "${opts.operation}" call was BLOCKED and nothing was changed.`,
+        warning,
         operation: opts.operation,
         details: opts.details,
-        instruction: 'Ask the user to confirm, then call again with `confirm: true`.',
-    }, { isError: true });
+        instruction,
+    }), {
+        ...opts.structured,
+        ...opts.structuredExtra,
+        applied: false,
+        requires_confirmation: true,
+        warning,
+        instruction,
+    });
 }
-/**
- * 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;
@@ -305,76 +396,9 @@ function sanitizeContentItem(item) {
         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 builder result (`tableResult` / `detailResult` /
- * `statsResult` / etc.) with a domain-typed `structuredContent` payload. The
- * result satisfies both Rich-Card hosts (read `_meta.ui`, present only when
- * the call site opted in) 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.
- *
- * T-C3c (native `@getimo/mcp-toolkit@1.2.0` migration): `includeMeta` is no
- * longer decided HERE. Every call site now threads it straight into its OWN
- * builder call (`tableResult(items, { ...opts, includeMeta })`, etc.), so the
- * toolkit either allocates the Rich-Card `_meta.ui` + embedded base64 marker
- * or never allocates them at all — nothing is stripped after the fact.
- * Replaces the T-C3 / T-C3b consumer-side shim (this file's own
- * `STRUCTURED_META_MARKER_RE` regex + `stripStructuredMetaItem`), which
- * duplicated the toolkit's marker format and risked drifting out of sync
- * with a future toolkit version. `toolkitResult._meta` is simply whatever
- * the builder decided to attach (or omit) — this function only sanitises and
- * merges it.
- */
-/**
- * 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 function withSiteMeta(result, site) {
     const displayLabel = site.label ?? site.id;
     let host;
@@ -384,20 +408,11 @@ export function withSiteMeta(result, site) {
     catch {
         host = site.url;
     }
-    // F178 (2026-06-12): when a call was routed via the PROCESS-WIDE
-    // default/override (i.e. the caller omitted `site_id`), append a
-    // ` · default` marker INSIDE the visible prefix so the human SEES the
-    // call was not isolated from concurrent `use_site` switches. An
-    // explicit `site_id` (or a legacy fixture without `resolvedVia`) gets
-    // the plain prefix.
-    const routedViaSharedDefault = site.resolvedVia === 'registry_default'
-        || site.resolvedVia === 'active_override';
-    const marker = routedViaSharedDefault ? ' · default' : '';
+    const marker = site.resolvedVia === 'active_override' ? ' · active override, not the configured default'
+        : site.resolvedVia === 'registry_default' ? ' · default'
+            : '';
     const prefix = `[${displayLabel} @ ${host}${marker}] `;
-    // `resolved_site_id` is stamped LÜCKENLOS on every site-bound result
-    // (it mirrors `site_id` but names the concept the agent reasons about
-    // — "which site did this call actually land on"). `resolved_via` is
-    // only stamped when known, so legacy fixtures add no noise.
+    const active = activeSiteFromResolution(site.id, site.resolvedVia);
     const meta = {
         site_id: site.id,
         site_url: site.url,
@@ -406,24 +421,12 @@ export function withSiteMeta(result, site) {
         ...(site.resolvedVia !== undefined
             ? { resolved_via: site.resolvedVia }
             : {}),
+        ...(active !== undefined ? { active_site: active } : {}),
     };
-    // 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.
-    //
-    // F80 (2026-06-10): the SAME synthetic-block path is taken when the
-    // first text body is a PURE JSON DOCUMENT (page_get_layout etc.).
-    // Concatenating the prefix in-band there yields `[label @ host] {...}`
-    // — not valid JSON — which corrupts the harness's file-dump of an
-    // oversized result and breaks `jq`. Routing JSON documents through the
-    // synthetic block keeps the JSON byte-pure while the human still sees
-    // the marker first. Human-readable text (tables / details / prose)
-    // keeps the in-band prefix unchanged.
+    const structured = result.structuredContent;
+    const enrichedStructured = active !== undefined && structured !== undefined && structured !== null && !Array.isArray(structured)
+        ? withActiveSiteKey(structured, active)
+        : structured;
     const firstItem = result.content[0];
     const firstIsLargeJsonDoc = firstItem !== undefined
         && firstItem.type === 'text'
@@ -446,12 +449,6 @@ export function withSiteMeta(result, site) {
             const existingText = typeof item.text === 'string' ? item.text : '';
             return { ...item, text: prefix + existingText };
         });
-    // Site meta merges into the RESULT-level `_meta` (next to the
-    // toolkit's `_meta.ui`), NEVER into `structuredContent`. The latter
-    // is validated by the host against the tool's `outputSchema`
-    // (additionalProperties:false); an undeclared key there triggers a
-    // `-32602` "Failed to call tool" reject even on success. The result
-    // envelope `_meta` is the spec's free-form metadata channel.
     const baseTopMeta = result._meta;
     const mergedTopMeta = baseTopMeta !== undefined && baseTopMeta !== null && typeof baseTopMeta === 'object'
         ? { ...baseTopMeta, ...meta }
@@ -459,13 +456,11 @@ export function withSiteMeta(result, site) {
     return {
         ...result,
         content: newContent,
+        ...(enrichedStructured !== undefined ? { structuredContent: enrichedStructured } : {}),
         _meta: mergedTopMeta,
     };
 }
 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