@zackbart/connecta 0.18.3 → 0.20.0

package/dist/meta-tools.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, groupedSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
+import { msg } from "./errors.js";
+import { serializeResultText } from "./executor-result.js";
 import { InvocationService, MAX_RETRY_BACKOFF_MS, retryBackoffMs, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
@@ -9,9 +11,9 @@ export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_M
 const RESULT_TTL_SECONDS = 900;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
-export function jsonResult(obj) {
+export function jsonResult(obj, text = JSON.stringify(obj)) {
     return {
-        content: [{ type: "text", text: JSON.stringify(obj) }],
+        content: [{ type: "text", text }],
         ...(obj !== null && typeof obj === "object" && !Array.isArray(obj)
             ? { structuredContent: obj }
             : {}),
@@ -20,9 +22,6 @@ export function jsonResult(obj) {
 export function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
-function msg(err) {
-    return err instanceof Error ? err.message : String(err);
-}
 function discoveryErrorResult(error) {
     const result = jsonResult({
         error: {
@@ -38,12 +37,7 @@ async function discoveryResult(operation, hint) {
     try {
         const value = await operation();
         const text = boundedDiscoveryText(value, hint);
-        return {
-            content: [{ type: "text", text }],
-            ...(value !== null && typeof value === "object" && !Array.isArray(value)
-                ? { structuredContent: value }
-                : {}),
-        };
+        return jsonResult(value, text);
     }
     catch (err) {
         if (err instanceof DiscoveryPolicyError) {
@@ -58,20 +52,8 @@ function isContinuationByte(b) {
 }
 /** Smallest accepted `get_result` byte offset. */
 const MIN_RESULT_OFFSET = 0;
-/**
- * The one definition of a usable `get_result` offset: a whole number of bytes
- * at or past {@link MIN_RESULT_OFFSET}. Shared by the registered zod schema and
- * the handler's own check, the way `isValidMaxResultBytes` is shared across the
- * cap's intake points (issue #32) — so a value valid at the wire is valid in
- * process, and the two cannot drift.
- *
- * Everything else is rejected rather than coerced, because coercion is how an
- * out-of-domain offset used to void a result silently: `Math.max(0, NaN)` is
- * `NaN`, which slices to nothing, serializes as `"offset": null`, and reports
- * no `nextOffset` — a caller sees a successful, empty result instead of an
- * error. An offset past the end of the payload stays legal: it is a whole
- * number of bytes, and it answers with an empty final page.
- */
+/** Whole-byte offset accepted by the result representation documented in
+ * documentation/meta-tools.md#result-representation. */
 function isValidResultOffset(value) {
     return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
 }
@@ -93,21 +75,8 @@ export function alignStartToCharBoundary(bytes, offset) {
         o--;
     return o;
 }
-/**
- * Move a byte `end` back to the nearest UTF-8 codepoint boundary in
- * `(offset, total]`, so decoding `bytes[offset, end)` never splits a codepoint
- * (which would emit U+FFFD and break byte-exact reassembly). If backing up
- * would make no progress — a single codepoint wider than the window — extend
- * forward to the end of that codepoint instead so paging always advances.
- * Assumes `offset` is itself a codepoint boundary (offsets are the prior
- * `nextOffset`, which this function guarantees, and 0 is always a boundary).
- *
- * The return is always `> offset` while `offset < total`, whatever `end` is
- * asked for. That is the belt-and-braces half of issue #32: cap validation
- * keeps an empty window from arising in the first place, and this keeps an
- * empty window from turning into a `nextOffset === offset` paging loop if one
- * ever does. Exported for direct testing of that invariant.
- */
+/** End boundary for UTF-8-safe, forward-progressing result pages. See
+ * documentation/meta-tools.md#result-representation. */
 export function alignEndToCharBoundary(bytes, offset, end, total) {
     if (end >= total)
         return total;
@@ -125,480 +94,6 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-/** Resolve a dot-path and retain misses below every `[]` boundary. */
-function resolvePath(value, segments) {
-    const seg = segments[0];
-    if (seg === undefined) {
-        return value === undefined
-            ? { status: "unmatched" }
-            : { status: "matched", value };
-    }
-    const rest = segments.slice(1);
-    const isArr = seg.endsWith("[]");
-    const key = isArr ? seg.slice(0, -2) : seg;
-    let next = value;
-    if (key !== "") {
-        if (value === null || typeof value !== "object") {
-            return { status: "unmatched" };
-        }
-        next = value[key];
-    }
-    if (isArr) {
-        if (!Array.isArray(next))
-            return { status: "unmatched" };
-        if (next.length === 0)
-            return { status: "matched", value: [] };
-        const elements = next.map((el) => resolvePath(el, rest));
-        const matched = elements.some((element) => element.status !== "unmatched");
-        const missed = elements.some((element) => element.status !== "matched");
-        if (!matched)
-            return { status: "unmatched" };
-        return {
-            status: missed ? "partial" : "matched",
-            // Undefined placeholders retain the historical array positions in the
-            // partial value. JSON renders them as null; partialFields says they are
-            // unresolved rather than genuine downstream nulls.
-            value: elements.map((element) => element.status === "unmatched" ? undefined : element.value),
-        };
-    }
-    return resolvePath(next, rest);
-}
-const MAX_PROJECTION_AVAILABLE_FIELDS = 20;
-const MAX_PROJECTION_SCHEMA_DEPTH = 12;
-const MAX_PROJECTION_SCHEMA_NODES = 200;
-const MAX_PROJECTION_SCHEMA_PATHS = 100;
-const MAX_PROJECTION_PATH_CHARS = 256;
-const MAX_PROJECTION_PATH_BYTES = 512;
-const MAX_PROJECTION_TOTAL_PATH_CHARS = 512;
-const MAX_PROJECTION_TOTAL_PATH_BYTES = 768;
-const JSON_SCHEMA_TYPES = new Set([
-    "array",
-    "boolean",
-    "integer",
-    "null",
-    "number",
-    "object",
-    "string",
-]);
-const NON_SEMANTIC_REF_SIBLINGS = new Set([
-    "$anchor",
-    "$comment",
-    "$defs",
-    "$id",
-    "$ref",
-    "$schema",
-    "default",
-    "definitions",
-    "deprecated",
-    "description",
-    "examples",
-    "readOnly",
-    "title",
-    "writeOnly",
-]);
-function localSchemaRef(root, ref) {
-    if (ref === "#")
-        return root;
-    if (!ref.startsWith("#/") ||
-        ref.length > 2_048 ||
-        /~(?![01])/.test(ref)) {
-        return undefined;
-    }
-    const segments = ref.slice(2).split("/");
-    if (segments.length > MAX_PROJECTION_SCHEMA_DEPTH)
-        return undefined;
-    let current = root;
-    for (const encoded of segments) {
-        if (current === null || typeof current !== "object")
-            return undefined;
-        const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");
-        if (!Object.prototype.hasOwnProperty.call(current, key))
-            return undefined;
-        current = current[key];
-    }
-    return current;
-}
-function hasSchemaType(schema, wanted) {
-    return (schema.type === wanted ||
-        (Array.isArray(schema.type) && schema.type.includes(wanted)));
-}
-function selectableFieldName(name) {
-    return name.length > 0 && !name.includes(".") && !name.endsWith("[]");
-}
-/**
- * Collect selectable output paths without trusting a schema more than JSON
- * Schema permits. Traversal is iterative and budgeted before sorting or
- * rendering, so a cyclic, extremely deep, or extremely broad downstream
- * schema cannot turn projection feedback into unbounded host work.
- */
-function analyzeSchemaFields(root) {
-    const pending = [
-        { schema: root, prefix: "", depth: 0, ancestors: new Set() },
-    ];
-    const paths = new Set();
-    let nodes = 0;
-    let totalPathChars = 0;
-    let totalPathBytes = 0;
-    let complete = true;
-    let truncated = false;
-    const addPath = (path) => {
-        if (paths.has(path))
-            return true;
-        // Check UTF-16 length before encoding, so a hostile multi-megabyte key
-        // never causes a same-sized temporary allocation merely to reject it.
-        if (path.length > MAX_PROJECTION_PATH_CHARS ||
-            totalPathChars + path.length > MAX_PROJECTION_TOTAL_PATH_CHARS) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        const pathBytes = enc.encode(path).length;
-        if (pathBytes > MAX_PROJECTION_PATH_BYTES ||
-            totalPathBytes + pathBytes > MAX_PROJECTION_TOTAL_PATH_BYTES ||
-            paths.size >= MAX_PROJECTION_SCHEMA_PATHS) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        paths.add(path);
-        totalPathChars += path.length;
-        totalPathBytes += pathBytes;
-        return true;
-    };
-    const enqueue = (item) => {
-        if (nodes + pending.length >= MAX_PROJECTION_SCHEMA_NODES) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        pending.push(item);
-        return true;
-    };
-    while (pending.length > 0) {
-        const item = pending.pop();
-        if (item.depth > MAX_PROJECTION_SCHEMA_DEPTH) {
-            complete = false;
-            truncated = true;
-            continue;
-        }
-        if (++nodes > MAX_PROJECTION_SCHEMA_NODES) {
-            complete = false;
-            truncated = true;
-            break;
-        }
-        if (item.schema === false)
-            continue;
-        if (item.schema === true ||
-            item.schema === null ||
-            typeof item.schema !== "object" ||
-            item.ancestors.has(item.schema)) {
-            complete = false;
-            continue;
-        }
-        const schema = item.schema;
-        const ancestors = new Set(item.ancestors).add(item.schema);
-        let recognized = false;
-        if (schema.type !== undefined &&
-            !((typeof schema.type === "string" &&
-                JSON_SCHEMA_TYPES.has(schema.type)) ||
-                (Array.isArray(schema.type) &&
-                    schema.type.length > 0 &&
-                    schema.type.every((type) => typeof type === "string" && JSON_SCHEMA_TYPES.has(type))))) {
-            complete = false;
-        }
-        if (schema.$ref !== undefined) {
-            recognized = true;
-            let hasSemanticSiblings = false;
-            for (const key in schema) {
-                if (Object.prototype.hasOwnProperty.call(schema, key) &&
-                    !NON_SEMANTIC_REF_SIBLINGS.has(key)) {
-                    hasSemanticSiblings = true;
-                    break;
-                }
-            }
-            if (hasSemanticSiblings) {
-                // Modern JSON Schema applies $ref siblings as an intersection. A
-                // compact field walker cannot prove that intersection's selectable
-                // paths, so do not publish paths from either half as available.
-                complete = false;
-                continue;
-            }
-            const target = typeof schema.$ref === "string"
-                ? localSchemaRef(root, schema.$ref)
-                : undefined;
-            if (target === undefined)
-                complete = false;
-            else {
-                enqueue({
-                    schema: target,
-                    prefix: item.prefix,
-                    depth: item.depth + 1,
-                    ancestors,
-                });
-            }
-        }
-        for (const keyword of ["allOf", "anyOf", "oneOf"]) {
-            const variants = schema[keyword];
-            if (!Array.isArray(variants))
-                continue;
-            recognized = true;
-            // Combining schemas can close or conditionally expose fields in ways
-            // this compact recovery walker intentionally does not prove.
-            complete = false;
-            for (const variant of variants) {
-                if (!enqueue({
-                    schema: variant,
-                    prefix: item.prefix,
-                    depth: item.depth + 1,
-                    ancestors,
-                })) {
-                    break;
-                }
-            }
-        }
-        if (truncated)
-            break;
-        const properties = schema.properties;
-        const propertyRecord = properties !== null &&
-            typeof properties === "object" &&
-            !Array.isArray(properties)
-            ? properties
-            : undefined;
-        if (properties !== undefined && propertyRecord === undefined) {
-            complete = false;
-        }
-        const objectShape = hasSchemaType(schema, "object") || propertyRecord !== undefined;
-        if (objectShape) {
-            recognized = true;
-            const patterns = schema.patternProperties;
-            let hasPatterns = false;
-            if (patterns !== undefined &&
-                (patterns === null ||
-                    typeof patterns !== "object" ||
-                    Array.isArray(patterns))) {
-                complete = false;
-            }
-            else if (patterns !== undefined) {
-                for (const key in patterns) {
-                    if (Object.prototype.hasOwnProperty.call(patterns, key)) {
-                        hasPatterns = true;
-                        break;
-                    }
-                }
-            }
-            if (schema.additionalProperties !== false || hasPatterns) {
-                complete = false;
-            }
-            if (propertyRecord) {
-                for (const key in propertyRecord) {
-                    if (!Object.prototype.hasOwnProperty.call(propertyRecord, key)) {
-                        continue;
-                    }
-                    if (++nodes > MAX_PROJECTION_SCHEMA_NODES) {
-                        complete = false;
-                        truncated = true;
-                        break;
-                    }
-                    if (key.length > MAX_PROJECTION_PATH_CHARS) {
-                        complete = false;
-                        truncated = true;
-                        break;
-                    }
-                    if (!selectableFieldName(key)) {
-                        complete = false;
-                        continue;
-                    }
-                    const child = propertyRecord[key];
-                    // A false property schema forbids the property; advertising its name
-                    // as selectable would turn an impossible value into a valid hint.
-                    if (child === false)
-                        continue;
-                    const path = item.prefix ? `${item.prefix}.${key}` : key;
-                    if (!addPath(path))
-                        break;
-                    if (!enqueue({
-                        schema: child,
-                        prefix: path,
-                        depth: item.depth + 1,
-                        ancestors,
-                    })) {
-                        break;
-                    }
-                }
-            }
-        }
-        if (truncated)
-            break;
-        const arrayShape = hasSchemaType(schema, "array") ||
-            schema.items !== undefined ||
-            schema.prefixItems !== undefined;
-        if (arrayShape) {
-            recognized = true;
-            const arrayPath = `${item.prefix}[]`;
-            if (addPath(arrayPath)) {
-                if (Array.isArray(schema.prefixItems)) {
-                    complete = false;
-                    for (const child of schema.prefixItems) {
-                        if (!enqueue({
-                            schema: child,
-                            prefix: arrayPath,
-                            depth: item.depth + 1,
-                            ancestors,
-                        })) {
-                            break;
-                        }
-                    }
-                }
-                if (schema.items === undefined) {
-                    if (!Array.isArray(schema.prefixItems))
-                        complete = false;
-                }
-                else if (schema.items === true || Array.isArray(schema.items)) {
-                    complete = false;
-                    const children = Array.isArray(schema.items)
-                        ? schema.items
-                        : [];
-                    for (const child of children) {
-                        if (!enqueue({
-                            schema: child,
-                            prefix: arrayPath,
-                            depth: item.depth + 1,
-                            ancestors,
-                        })) {
-                            break;
-                        }
-                    }
-                }
-                else if (schema.items !== false) {
-                    enqueue({
-                        schema: schema.items,
-                        prefix: arrayPath,
-                        depth: item.depth + 1,
-                        ancestors,
-                    });
-                }
-            }
-        }
-        const types = Array.isArray(schema.type)
-            ? schema.type
-            : schema.type === undefined
-                ? []
-                : [schema.type];
-        const primitiveOnly = types.length > 0 &&
-            types.every((type) => type === "string" ||
-                type === "number" ||
-                type === "integer" ||
-                type === "boolean" ||
-                type === "null");
-        if (!recognized && !primitiveOnly)
-            complete = false;
-        if (truncated)
-            break;
-    }
-    return {
-        paths: [...paths].sort(),
-        complete,
-        truncated,
-    };
-}
-function schemaProjectionFeedback(outputSchema, unmatchedFields) {
-    const analysis = analyzeSchemaFields(outputSchema);
-    const available = new Set(analysis.paths);
-    const invalidFields = analysis.complete
-        ? unmatchedFields.filter((field) => !available.has(field))
-        : [];
-    const missingArrayMarker = unmatchedFields.some((field) => analysis.paths.some((availableField) => availableField.includes("[]") &&
-        availableField.replaceAll("[]", "") === field));
-    return {
-        ...(missingArrayMarker
-            ? {
-                hint: 'Traverse arrays with [] after the array field name, for example "results[].id".',
-            }
-            : {}),
-        schemaDeclared: true,
-        schemaCoverage: analysis.complete ? "complete" : "partial",
-        ...(invalidFields.length > 0 ? { invalidFields } : {}),
-        ...(analysis.paths.length > 0
-            ? {
-                availableFields: analysis.paths.slice(0, MAX_PROJECTION_AVAILABLE_FIELDS),
-            }
-            : {}),
-        ...(analysis.truncated ||
-            analysis.paths.length > MAX_PROJECTION_AVAILABLE_FIELDS
-            ? { availableFieldsTruncated: true }
-            : {}),
-    };
-}
-/** Select the given dot-paths, retaining both matches and exact misses. */
-function applyFields(value, fields) {
-    const out = {};
-    const unmatchedFields = [];
-    const partialFields = [];
-    for (const path of fields) {
-        const resolved = resolvePath(value, path.split("."));
-        if (resolved.status === "unmatched") {
-            unmatchedFields.push(path);
-        }
-        else {
-            out[path] = resolved.value;
-            if (resolved.status === "partial")
-                partialFields.push(path);
-        }
-    }
-    return { data: out, unmatchedFields, partialFields };
-}
-/**
- * Keep the historical flat projection when every path resolves. A miss gets a
- * wrapper with a reserved discriminator so neither `{}` nor downstream fields
- * named `data` / `projection` can be mistaken for projection feedback.
- */
-function projectionValue(value, fields, outputSchema) {
-    const projected = applyFields(value, fields);
-    // `$connecta` is reserved at the top level of a projection. Even a fully
-    // matched downstream field with that exact name is escaped below `data`, so
-    // no user-controlled value can impersonate Connecta's discriminator.
-    const reservedCollision = Object.prototype.hasOwnProperty.call(projected.data, "$connecta");
-    if (projected.unmatchedFields.length === 0 &&
-        projected.partialFields.length === 0 &&
-        !reservedCollision) {
-        return projected.data;
-    }
-    const problemFields = [
-        ...projected.unmatchedFields,
-        ...projected.partialFields,
-    ];
-    return {
-        data: projected.data,
-        $connecta: {
-            type: "field_projection",
-            unmatchedFields: projected.unmatchedFields,
-            ...(projected.partialFields.length > 0
-                ? { partialFields: projected.partialFields }
-                : {}),
-            ...(outputSchema
-                ? schemaProjectionFeedback(outputSchema, problemFields)
-                : {}),
-        },
-    };
-}
-/** Apply fields to each JSON-parseable text block; non-JSON blocks pass through. */
-function applyFieldsToContent(content, fields, outputSchema) {
-    return content.map((b) => {
-        if (b.type !== "text")
-            return b;
-        let parsed;
-        try {
-            parsed = JSON.parse(b.text);
-        }
-        catch {
-            return b;
-        }
-        return {
-            ...b,
-            text: JSON.stringify(projectionValue(parsed, fields, outputSchema)),
-        };
-    });
-}
 // --- result-size guard + get_result (feature 1) ---------------------------
 /**
  * The one serialization every result guard measures, stashes, and pages: JSON
@@ -615,10 +110,6 @@ function applyFieldsToContent(content, fields, outputSchema) {
  * the three give one answer to the same question. A value JSON cannot serialize
  * at all (a BigInt) still throws, as before, and is reported as a failure.
  */
-function serializeResultText(value) {
-    const serialized = JSON.stringify(value);
-    return serialized === undefined ? String(value) : serialized;
-}
 /**
  * Stash `text` under `result:<uuid>` (ttl 900s) and describe it as the
  * truncation notice every over-cap path hands back.
@@ -630,7 +121,7 @@ async function stashResult(text, results, totalBytes) {
         truncated: true,
         resultId: id,
         totalBytes,
-        hint: "use get_result {id, offset} to page, or re-call with fields to select less",
+        hint: "use get_result {id, offset} to page the complete direct-call result",
         nextAction: {
             tool: "get_result",
             arguments: { id, offset: 0 },
@@ -761,7 +252,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         requestScope,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
-        ...(opts.defer ? { defer: opts.defer } : {}),
+        defer: opts.defer,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
@@ -769,7 +260,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
     async function runCall(call, source, options = {}) {
         const results = registry.resultsStorage();
-        const fields = call.fields && call.fields.length > 0 ? call.fields : null;
         const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
@@ -792,54 +282,38 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 // override the registry already warned about at startup is dropped
                 // here, so the connector simply inherits `globalCap`.
                 const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
+                const processed = (toolResult, truncated, value) => ({
+                    toolResult,
+                    ...value,
+                    ...(truncated ? { friction: "result_too_large" } : {}),
+                });
                 if (call.resultMode === "value") {
-                    let value = fields
-                        ? projectionValue(result, fields, resolved.definition.outputSchema)
-                        : result;
+                    let value = result;
                     const guarded = await guardValue(value, results, cap);
                     value = guarded.result;
-                    return {
-                        toolResult: jsonResult({ ok: true, data: value }),
-                        value,
-                        ...(guarded.truncated
-                            ? { friction: "result_too_large" }
-                            : {}),
-                    };
+                    return processed(jsonResult({ ok: true, data: value }), guarded.truncated, { value });
                 }
                 if (resolved.connector.kind === "mcp") {
                     const mcpResult = result;
-                    let content = mcpResult?.content ?? [];
-                    if (fields) {
-                        content = applyFieldsToContent(content, fields, resolved.definition.outputSchema);
-                    }
+                    const content = mcpResult?.content ?? [];
                     const guarded = await guardContent(content, results, cap);
-                    return {
-                        toolResult: guarded.result,
-                        ...(guarded.truncated
-                            ? { friction: "result_too_large" }
-                            : {}),
-                    };
+                    return processed(guarded.result, guarded.truncated);
                 }
-                const value = fields
-                    ? projectionValue(result, fields, resolved.definition.outputSchema)
-                    : result;
+                const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
-                return {
-                    toolResult: guarded.result,
-                    value,
-                    ...(guarded.truncated
-                        ? { friction: "result_too_large" }
-                        : {}),
-                };
+                return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
         });
         if (!outcome.ok) {
             const structuredRecovery = outcome.error.nextAction !== undefined;
-            const failedResult = structuredRecovery ||
-                outcome.error.code === "auth_required" ||
-                outcome.error.code === "invalid_args" ||
-                outcome.error.code === "input_required_unsupported" ||
+            const recoveryRequired = structuredRecovery ||
+                [
+                    "auth_required",
+                    "invalid_args",
+                    "input_required_unsupported",
+                ].includes(outcome.error.code);
+            const failedResult = recoveryRequired ||
                 call.resultMode === "value"
                 ? jsonResult({
                     ok: false,
@@ -849,10 +323,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(call.diagnostics ? { timing: outcome.timing } : {}),
                 })
                 : errorResult(outcome.error.message);
-            if (structuredRecovery ||
-                outcome.error.code === "auth_required" ||
-                outcome.error.code === "invalid_args" ||
-                outcome.error.code === "input_required_unsupported") {
+            if (recoveryRequired) {
                 failedResult.isError = true;
             }
             return {
@@ -914,7 +385,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
         async callDestructiveTool(args) {
             // `reason` is read by the host's approval view and stops there — runCall
-            // forwards only the call fields, so it never reaches the connector.
+            // forwards only the call arguments, so it never reaches the connector.
             return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
         },
         async getResult(args) {
@@ -1045,12 +516,11 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     };
 }
 const SEARCH_DESC = `Use top-level search for one unknown-address read before call_tool, or for approval-required work before call_destructive_tool. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. For multiple, dependent, or reduced read-only calls, use one execute_code program instead. Empty query browses.`;
-const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. fields projects JSON dot-paths; use [] through arrays. A truncated result carries a get_result action.';
+const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns text, offset, nextOffset when more remains, and totalBytes.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
 const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage once per task for program syntax, selection, repair, examples, and runtime details.';
-const SEARCH_WITH_DESCRIBE_DESC = SEARCH_DESC;
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1091,7 +561,6 @@ const READ_ONLY_LOCAL = {
 const CALL_INPUT_SCHEMA = {
     address: z.string(),
     args: z.record(z.string(), z.unknown()).optional(),
-    fields: z.array(z.string()).optional(),
     resultMode: z.enum(["mcp", "value"]).optional(),
     timeoutMs: z.number().int().positive().optional(),
     maxRetries: z.number().int().min(0).max(2).optional(),
@@ -1107,20 +576,12 @@ const CALL_INPUT_SCHEMA = {
  */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
-        ...(ctx.defaultToolTimeoutMs !== undefined
-            ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
-            : {}),
-        ...(ctx.probeTimeoutMs !== undefined
-            ? { probeTimeoutMs: ctx.probeTimeoutMs }
-            : {}),
-        ...(ctx.discoveryConcurrency !== undefined
-            ? { discoveryConcurrency: ctx.discoveryConcurrency }
-            : {}),
-        ...(ctx.activity !== undefined ? { activity: ctx.activity } : {}),
-        ...(ctx.requestSignal !== undefined
-            ? { requestSignal: ctx.requestSignal }
-            : {}),
-        ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
+        defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
+        probeTimeoutMs: ctx.probeTimeoutMs,
+        discoveryConcurrency: ctx.discoveryConcurrency,
+        activity: ctx.activity,
+        requestSignal: ctx.requestSignal,
+        defer: ctx.defer,
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),
@@ -1129,7 +590,7 @@ export function registerMetaTools(server, registry, ctx) {
         _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.skills(args));
     server.registerTool("search_tools", {
-        description: describedFor(registry, SEARCH_WITH_DESCRIBE_DESC, "search"),
+        description: describedFor(registry, SEARCH_DESC, "search"),
         inputSchema: z.object({
             query: z.string().optional(),
             connector: z.string().optional(),
@@ -1150,10 +611,8 @@ export function registerMetaTools(server, registry, ctx) {
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
         annotations: READ_ONLY_REMOTE,
-        // The trusted program-view shell delegates bounded named reads here.
-        // It is already one of the seven model tools; app visibility adds no
-        // tool and this handler repeats ordinary fail-closed read admission.
-        _meta: { ui: { visibility: ["model", "app"] } },
+        // Omission defaults to model + app. Display-only views may call no tool.
+        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.callTool(args));
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),