@zackbart/connecta 0.10.5 → 0.11.0

package/dist/meta-tools.js

@@ -1,12 +1,10 @@
 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 { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
-import { closeConnectorScope, } from "./connector-scope.js";
-import { classifyCallError, messageLooksRetryable, } from "./errors.js";
+import { resolveDiscoveryConcurrency } from "./concurrency.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";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_MS, MAX_SEARCH_LIMIT, retryBackoffMs, };
 const RESULT_TTL_SECONDS = 900;
 const enc = new TextEncoder();
@@ -25,9 +23,6 @@ export function errorResult(message) {
 function msg(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function errorDetails(code, message) {
-    return { code, message, retryable: messageLooksRetryable(message) };
-}
 function discoveryErrorResult(error) {
     const result = jsonResult({
         error: {
@@ -606,17 +601,12 @@ async function stashResult(text, results, totalBytes) {
         resultId: id,
         totalBytes,
         hint: "use get_result {id, offset} to page, or re-call with fields to select less",
+        nextAction: {
+            tool: "get_result",
+            arguments: { id, offset: 0 },
+        },
     };
 }
-/** Keep an oversized batch's inline outcome summary at fixed string overhead. */
-function batchSummaryString(value) {
-    const bytes = enc.encode(value);
-    const maxBytes = 512;
-    if (bytes.length <= maxBytes)
-        return value;
-    const end = alignEndToCharBoundary(bytes, 0, maxBytes, bytes.length);
-    return `${dec.decode(bytes.slice(0, end))}…`;
-}
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
  * full text and return the first `cap` bytes followed by a JSON truncation
@@ -625,12 +615,18 @@ function batchSummaryString(value) {
  */
 async function guardEncoded(text, bytes, results, cap) {
     if (bytes.length <= cap) {
-        return { content: [{ type: "text", text }] };
+        return {
+            result: { content: [{ type: "text", text }] },
+            truncated: false,
+        };
     }
     const notice = await stashResult(text, results, bytes.length);
     const head = dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)));
     return {
-        content: [{ type: "text", text: `${head}\n${JSON.stringify(notice)}` }],
+        result: {
+            content: [{ type: "text", text: `${head}\n${JSON.stringify(notice)}` }],
+        },
+        truncated: true,
     };
 }
 /** {@link guardEncoded} over a string that has not been measured yet. */
@@ -648,8 +644,11 @@ async function guardValue(value, results, cap) {
     const text = serializeResultText(value);
     const bytes = enc.encode(text);
     if (bytes.length <= cap)
-        return value;
-    return stashResult(text, results, bytes.length);
+        return { result: value, truncated: false };
+    return {
+        result: await stashResult(text, results, bytes.length),
+        truncated: true,
+    };
 }
 /**
  * Bound a downstream MCP `content` array by `cap`, measuring the serialized
@@ -679,37 +678,48 @@ async function guardContent(content, results, cap) {
         // be measured, stashed, or paged either — there is nothing this guard could
         // do with it. Pass it through as the old text-only measure did, rather than
         // turning a call that used to succeed into result_processing_failed.
-        return { content };
+        return { result: { content }, truncated: false };
     }
     const bytes = enc.encode(text);
     // Under the cap the downstream blocks pass through untouched, non-text ones
     // included, in their original order.
-    if (bytes.length <= cap)
-        return { content };
+    if (bytes.length <= cap) {
+        return { result: { content }, truncated: false };
+    }
     if (content.every((b) => b.type === "text")) {
         return guardEncoded(text, bytes, results, cap);
     }
     const notice = await stashResult(text, results, bytes.length);
-    return { content: [{ type: "text", text: JSON.stringify(notice) }] };
+    return {
+        result: { content: [{ type: "text", text: JSON.stringify(notice) }] },
+        truncated: true,
+    };
+}
+/**
+ * The sentence that closes the OAuth handoff, telling the operator's agent how
+ * to confirm the flow landed through the one surface it can call.
+ */
+function oauthFollowUp(connectorId) {
+    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
 }
 /**
- * Every base meta-tool handler over a registry — all nine, whichever surface is
- * advertised, since folding a tool away only skips its registration and never
- * its handler. Exported for direct testing; registerMetaTools() wires the ones
- * this surface advertises onto an McpServer. `opts.defaultToolTimeoutMs`
- * supplies a deadline for calls that don't carry one. (execute_code is
- * registered separately by registerExecuteTool.)
+ * Every meta-tool handler over a registry, one per registered tool. Exported for
+ * direct testing; registerMetaTools() wires the six explicit tools onto an
+ * McpServer. `opts.defaultToolTimeoutMs` supplies a deadline for calls that
+ * don't carry one. (execute_code is registered separately by
+ * registerExecuteTool, and builds its own services over the same registry.)
+ *
+ * What execute_code shares with these handlers is the services layer beneath
+ * them — `CatalogService` and `InvocationService` — not the handlers, which no
+ * in-program path calls.
  *
  * Deployment-wide result-size caps are read off the registry view rather than
- * passed in: `ConnectaConfig.calls.maxResultBytes`, its per-connector override,
- * and the independent `calls.maxBatchResultBytes` final-envelope boundary each
- * have one runtime source of truth.
+ * passed in: `ConnectaConfig.calls.maxResultBytes` and its per-connector
+ * override each have one runtime source of truth.
  */
 export function createMetaTools(registry, baseUrl, opts = {}) {
-    const surface = opts.surface ?? "classic";
     // Already normalized and warned about at registry construction.
     const globalCap = registry.maxResultBytes;
-    const batchCap = registry.maxBatchResultBytes;
     const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
     const probeTimeoutMs = normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
     const discoveryConcurrency = resolveDiscoveryConcurrency(opts.discoveryConcurrency);
@@ -721,9 +731,10 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         requestScope,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
+        // searchRoute keeps its top-level default. In-program callers use a
+        // separate CatalogService configured for connecta.search.
     });
     const invocation = new InvocationService(registry, catalog, opts.activity);
-    const withProbeDeadline = (label, operation) => withAbortableTimeout((signal) => operation({ signal, timeoutMs: probeTimeoutMs }), probeTimeoutMs, label);
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
     async function runCall(call, source, options = {}) {
         const results = registry.resultsStorage();
@@ -745,7 +756,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             processResult: async (result, resolved) => {
                 // Result-size cap for THIS call: the connector's own override wins,
                 // then the deployment-wide value, then the built-in default (already
-                // folded into `globalCap`). Resolved per call so one batch_call can
+                // folded into `globalCap`). Resolved per call so one request can
                 // mix a tight-capped connector with siblings on the global cap. An
                 // override the registry already warned about at startup is dropped
                 // here, so the connector simply inherits `globalCap`.
@@ -754,10 +765,14 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     let value = fields
                         ? projectionValue(result, fields, resolved.definition.outputSchema)
                         : result;
-                    value = await guardValue(value, results, cap);
+                    const guarded = await guardValue(value, results, cap);
+                    value = guarded.result;
                     return {
                         toolResult: jsonResult({ ok: true, data: value }),
                         value,
+                        ...(guarded.truncated
+                            ? { friction: "result_too_large" }
+                            : {}),
                     };
                 }
                 if (resolved.connector.kind === "mcp") {
@@ -766,19 +781,32 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     if (fields) {
                         content = applyFieldsToContent(content, fields, resolved.definition.outputSchema);
                     }
-                    return { toolResult: await guardContent(content, results, cap) };
+                    const guarded = await guardContent(content, results, cap);
+                    return {
+                        toolResult: guarded.result,
+                        ...(guarded.truncated
+                            ? { friction: "result_too_large" }
+                            : {}),
+                    };
                 }
                 const value = fields
                     ? projectionValue(result, fields, resolved.definition.outputSchema)
                     : result;
+                const guarded = await guardText(serializeResultText(value), results, cap);
                 return {
-                    toolResult: await guardText(serializeResultText(value), results, cap),
+                    toolResult: guarded.result,
                     value,
+                    ...(guarded.truncated
+                        ? { friction: "result_too_large" }
+                        : {}),
                 };
             },
+            activityFriction: (processed) => processed.friction,
         });
         if (!outcome.ok) {
-            const failedResult = outcome.error.code === "auth_required" ||
+            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" ||
                 call.resultMode === "value"
@@ -790,7 +818,8 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(call.diagnostics ? { timing: outcome.timing } : {}),
                 })
                 : errorResult(outcome.error.message);
-            if (outcome.error.code === "auth_required" ||
+            if (structuredRecovery ||
+                outcome.error.code === "auth_required" ||
                 outcome.error.code === "invalid_args" ||
                 outcome.error.code === "input_required_unsupported") {
                 failedResult.isError = true;
@@ -831,134 +860,30 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         {
                             type: "text",
                             text: 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
-                                listSkills(connectors, surface)
+                                listSkills(connectors)
                                     .map((skill) => `- \`${skill.name}\` — ${skill.description}`)
                                     .join("\n"),
                         },
                     ],
                 };
             }
-            const skill = resolveSkill(args.name, connectors, surface);
+            const skill = resolveSkill(args.name, connectors);
             if (!skill.found)
                 return errorResult(skill.message);
             return { content: [{ type: "text", text: skill.content }] };
         },
-        async listConnectors(args = {}) {
-            const probe = args.probe ?? true;
-            // Live inventory owns a short-lived scope separate from the request's
-            // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
-            const connectors = registry.listConnectors();
-            const scope = probe ? {} : requestScope;
-            const inspect = async (c) => {
-                const statusStarted = Date.now();
-                const observed = registry.healthFor(c.id);
-                const drift = await registry.credentialDriftFor(c.id);
-                let status;
-                if (drift) {
-                    status = { state: "auth_required", message: drift };
-                }
-                else if (probe) {
-                    try {
-                        status = await withProbeDeadline(`list_connectors probe of "${c.id}"`, (options) => registry.statusFor(c.id, baseUrl, scope, options));
-                    }
-                    catch (err) {
-                        // A probe that outran probeTimeoutMs (or otherwise threw)
-                        // degrades this connector to an error status rather than
-                        // hanging the whole list_connectors call.
-                        status = { state: "error", message: msg(err) };
-                    }
-                }
-                else {
-                    const derived = observed?.consecutiveFailures && observed.consecutiveFailures > 0
-                        ? "error"
-                        : registry.hasObservedSuccess(c.id) || c.kind === "api"
-                            ? "ok"
-                            : "unknown";
-                    status = {
-                        state: derived,
-                        ...(observed?.lastError ? { message: observed.lastError } : {}),
-                    };
-                }
-                // Stamped after any live probe so the response reports when its
-                // observation completed, not when a potentially slow request began.
-                const checkedAt = new Date().toISOString();
-                let tools = registry.peekTools(c.id);
-                // An auth_required status may have just started OAuth. A second
-                // listTools probe would overwrite its state/verifier while returning
-                // the first (now stale) authorization URL.
-                if (probe && status.state === "ok") {
-                    try {
-                        tools = await withProbeDeadline(`list_connectors catalog refresh of "${c.id}"`, (options) => registry.refreshTools(c.id, baseUrl, scope, options));
-                        registry.recordSuccess(c.id, Date.now() - statusStarted);
-                    }
-                    catch (err) {
-                        const details = classifyCallError(err);
-                        if (details.code === "auth_required") {
-                            let authStatus;
-                            try {
-                                authStatus = await withProbeDeadline(`list_connectors authorization status of "${c.id}"`, (options) => registry.statusFor(c.id, baseUrl, scope, options));
-                            }
-                            catch {
-                                // The typed auth verdict is still authoritative; this second
-                                // read exists only to recover the connector's pending URL.
-                            }
-                            status =
-                                authStatus?.state === "auth_required"
-                                    ? authStatus
-                                    : {
-                                        state: "auth_required",
-                                        message: details.message,
-                                    };
-                        }
-                        else {
-                            status = { state: "error", message: msg(err) };
-                        }
-                        registry.recordFailure(c.id, Date.now() - statusStarted, err);
-                    }
-                }
-                const latencyMs = Date.now() - statusStarted;
-                const latestObserved = registry.healthFor(c.id);
-                return {
-                    id: c.id,
-                    ...(c.title ? { title: c.title } : {}),
-                    description: c.description,
-                    toolCount: tools?.length ?? 0,
-                    status: status.state,
-                    checkedAt,
-                    latencyMs,
-                    probe,
-                    ...(latestObserved ?? observed),
-                    ...("authorizationUrl" in status &&
-                        status.authorizationUrl && {
-                        authorizationUrl: status.authorizationUrl,
-                    }),
-                    ...(status.message && { message: status.message }),
-                };
-            };
-            const settled = await mapSettledWithConcurrency(connectors, discoveryConcurrency, inspect);
-            if (probe) {
-                await mapSettledWithConcurrency(connectors, discoveryConcurrency, (connector) => closeConnectorScope(connector, registry.contextFor(connector.id, baseUrl, scope), opts.defer));
-            }
-            const out = settled.map((result) => {
-                if (result.status === "rejected")
-                    throw result.reason;
-                return result.value;
-            });
-            return jsonResult({ connectors: out });
-        },
         async searchTools(args) {
             return discoveryResult(async () => groupedSearchResult(await catalog.search({
                 ...args,
                 includeSchemaKeys: args.includeSchemas !== undefined,
             })), "Request a smaller limit, omit fullDescriptions, or use compact schemas.");
         },
-        async describeTools(args) {
-            return discoveryResult(async () => ({ tools: await catalog.describe(args) }), 'Split the address list or use format: "compact".');
-        },
         async callTool(args) {
             return (await runCall(args, "call_tool")).toolResult;
         },
         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.
             return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
         },
         async getResult(args) {
@@ -1008,131 +933,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 text: slice,
             });
         },
-        async batchCall(args) {
-            const batchStarted = Date.now();
-            const settled = await Promise.allSettled(args.calls.map((c) => runCall({
-                ...c,
-                ...((c.resultMode ?? args.resultMode) !== undefined
-                    ? { resultMode: c.resultMode ?? args.resultMode }
-                    : {}),
-                ...((c.timeoutMs ?? args.timeoutMs) !== undefined
-                    ? { timeoutMs: c.timeoutMs ?? args.timeoutMs }
-                    : {}),
-                ...((c.maxRetries ?? args.maxRetries) !== undefined
-                    ? { maxRetries: c.maxRetries ?? args.maxRetries }
-                    : {}),
-                ...((c.diagnostics ?? args.diagnostics) !== undefined
-                    ? { diagnostics: c.diagnostics ?? args.diagnostics }
-                    : {}),
-            }, "batch_call")));
-            const results = settled.map((s, i) => {
-                const call = args.calls[i];
-                if (!call) {
-                    throw new Error("Batch result has no corresponding call");
-                }
-                const { address } = call;
-                if (s.status === "rejected") {
-                    return {
-                        address,
-                        ok: false,
-                        error: msg(s.reason),
-                        errorDetails: classifyCallError(s.reason, "batch_call_failed"),
-                    };
-                }
-                const r = s.value;
-                if (r.error) {
-                    return {
-                        address,
-                        ok: false,
-                        error: r.error.message,
-                        errorDetails: r.error,
-                        durationMs: r.durationMs,
-                        attempts: r.attempts,
-                        ...((call.diagnostics ?? args.diagnostics)
-                            ? { timing: r.timing }
-                            : {}),
-                    };
-                }
-                if ((call.resultMode ?? args.resultMode) === "value") {
-                    return {
-                        address,
-                        ok: true,
-                        data: r.value,
-                        durationMs: r.durationMs,
-                        attempts: r.attempts,
-                        ...((call.diagnostics ?? args.diagnostics)
-                            ? { timing: r.timing }
-                            : {}),
-                    };
-                }
-                return {
-                    address,
-                    ok: true,
-                    result: r.toolResult.content,
-                    durationMs: r.durationMs,
-                    attempts: r.attempts,
-                    ...((call.diagnostics ?? args.diagnostics)
-                        ? { timing: r.timing }
-                        : {}),
-                };
-            });
-            const envelope = {
-                results,
-                durationMs: Date.now() - batchStarted,
-            };
-            const text = serializeResultText(envelope);
-            const bytes = enc.encode(text);
-            if (bytes.length <= batchCap)
-                return jsonResult(envelope);
-            const notice = await stashResult(text, registry.resultsStorage(), bytes.length);
-            return jsonResult({
-                results: results.map((result) => {
-                    const common = {
-                        address: batchSummaryString(result.address),
-                        ok: !("error" in result),
-                        ...("durationMs" in result
-                            ? { durationMs: result.durationMs }
-                            : {}),
-                        ...("attempts" in result ? { attempts: result.attempts } : {}),
-                        ...("timing" in result ? { timing: result.timing } : {}),
-                    };
-                    if (!("error" in result))
-                        return common;
-                    const error = result.error ?? "Batch call failed";
-                    const details = result.errorDetails ??
-                        errorDetails("batch_call_failed", error);
-                    return {
-                        ...common,
-                        error: batchSummaryString(error),
-                        errorDetails: {
-                            code: batchSummaryString(details.code),
-                            message: batchSummaryString(details.message),
-                            retryable: details.retryable,
-                            ...(details.retryAfterMs !== undefined
-                                ? { retryAfterMs: details.retryAfterMs }
-                                : {}),
-                            ...(details.connector !== undefined
-                                ? { connector: batchSummaryString(details.connector) }
-                                : {}),
-                            ...(details.operation !== undefined
-                                ? { operation: batchSummaryString(details.operation) }
-                                : {}),
-                            ...(details.recovery !== undefined
-                                ? { recovery: details.recovery }
-                                : {}),
-                            ...(details.nextAction !== undefined
-                                ? { nextAction: details.nextAction }
-                                : {}),
-                            ...(details.retry !== undefined
-                                ? { retry: batchSummaryString(details.retry) }
-                                : {}),
-                        },
-                    };
-                }),
-                durationMs: envelope.durationMs,
-                ...notice,
-            });
-        },
         async authorizeConnector(args) {
             const connector = registry.getConnector(args.connector);
             if (!connector) {
@@ -1195,7 +995,8 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(status.authorizationUrl
                         ? {
                             authorizationUrl: status.authorizationUrl,
-                            instructions: "Have the operator open authorizationUrl in a browser and complete the consent flow. The provider then redirects back to this server's /oauth/callback/<connector> route, which finishes the flow automatically. Re-run list_connectors afterwards to confirm status is ok.",
+                            instructions: "Have the operator open authorizationUrl in a browser and complete the consent flow. The provider then redirects back to this server's /oauth/callback/<connector> route, which finishes the flow automatically. " +
+                                oauthFollowUp(connector.id),
                         }
                         : {}),
                     ...(status.message ? { message: status.message } : {}),
@@ -1212,29 +1013,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const LIST_DESC = "List connectors with status, cached tool count, and recent real-call health. Use probe=false for a fast inventory; use probe=true (default) only to diagnose live health or authorization.";
 const SEARCH_DESC = `Unknown address: use 2–4 distinctive action/object terms, not the full request; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}) and page only if needed, up to ${MAX_SEARCH_LIMIT}. Partial and no-match searches report term coverage and next-step guidance. safety="readOnly" returns only calls available to call_tool and generated code; "approvalRequired" returns everything else; omitted or "all" preserves the complete catalog. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, each bounded; plain-object schemas also expose inputKeys, requiredInputKeys, and outputKeys, while inputSchemaTruncated/outputSchemaTruncated mark shapes that need exact retrieval; matches also carry declared annotations. Call directly when sufficient. Empty query browses all.`;
-const DESCRIBE_DESC = `Only when search_tools omitted schemas, a compact shape is ambiguous, or exact JSON constraints are needed. Inspects up to ${MAX_DESCRIBE_ADDRESSES} addresses with schemas and annotations; "compact" is default, while "json" preserves exact constraints.`;
-const CALL_DESC = 'Use for one tool explicitly annotated readOnlyHint: true. For 2–10 independent read-only calls use batch_call; for dependent steps or data reduction use execute_code when available. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
-const CALL_DESTRUCTIVE_DESC = "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
-const GET_RESULT_DESC = "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
-const BATCH_DESC = "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call. An oversized final envelope returns ordered outcome summaries plus a get_result page handle.";
+const CALL_DESC = 'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
+const CALL_DESTRUCTIVE_DESC = "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. Include a short reason explaining the intended consequence for the human reviewer; it grants no authority and is never passed downstream. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
+const GET_RESULT_DESC = "Page a truncated result stashed by call_tool or call_destructive_tool; a program's oversized return is not paged, so reduce it in code instead. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
 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 concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
-/**
- * Code-first replacements for the descriptions that route work between tools.
- * Every one of these mentions a tool the consolidated surface removed, so on a
- * code-first deployment the routing sentence has to point at the in-program
- * function that took the work over — a description naming `batch_call` on a
- * surface without one teaches a call that cannot succeed.
- *
- * The classic strings above are left byte-for-byte alone: classic is the
- * compatibility surface and the eval's control arm, and rewording it would
- * change what that control measures.
- */
-const CODE_FIRST_SEARCH_DESC = `${SEARCH_DESC} Expand an ambiguous compact shape, or read exact JSON constraints, with connecta.describe inside execute_code.`;
-const CODE_FIRST_CALL_DESC = 'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
-const CODE_FIRST_GET_RESULT_DESC = "Page a truncated result stashed by call_tool or call_destructive_tool; a program's oversized return is not paged, so reduce it in code instead. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
+const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact shape, or read exact JSON constraints, with connecta.describe inside execute_code.`;
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1246,7 +1031,6 @@ const CODE_FIRST_GET_RESULT_DESC = "Page a truncated result stashed by call_tool
 const GUIDE_NOTES = {
     skills: ' skills({}) also lists this deployment\'s per-connector usage guides as "connector:<connectorId>"; fetch the guide for a connector before working with it for the first time.',
     search: " A connector group carrying `guide` has a usage guide; fetch it with skills({ name: <guide> }).",
-    describe: " An entry carrying `guide` belongs to a connector with a usage guide; fetch it with skills({ name: <guide> }).",
 };
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
 function describedFor(registry, base, note) {
@@ -1282,21 +1066,15 @@ const CALL_INPUT_SCHEMA = {
     diagnostics: z.boolean().optional(),
 };
 /**
- * Register the base meta-tools onto an McpServer instance: nine on the classic
- * surface, six on the code-first one, where `list_connectors`,
- * `describe_tools`, and `batch_call` have folded into the program surface
- * (`registerExecuteTool` adds the seventh, `execute_code`).
- *
- * Only the registrations differ. Every handler still exists on the object
- * `createMetaTools` returns, and a folded tool's behavior is reached through
- * `connecta.search` / `connecta.describe` / `connecta.batch` inside a program —
- * the same code paths, one layer down.
+ * Register the six explicit meta-tools onto an McpServer instance.
+ * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
+ * multi-call work is reached through `connecta.search` / `connecta.describe` /
+ * `connecta.batch` inside a program, which `execute_code` builds over the same
+ * `CatalogService` and `InvocationService` these handlers use — one shared
+ * services layer, two adapters above it.
  */
 export function registerMetaTools(server, registry, ctx) {
-    const surface = ctx.surface ?? "classic";
-    const codeFirst = surface === "code-first";
     const mt = createMetaTools(registry, ctx.baseUrl, {
-        surface,
         ...(ctx.defaultToolTimeoutMs !== undefined
             ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
             : {}),
@@ -1310,26 +1088,14 @@ export function registerMetaTools(server, registry, ctx) {
         ...(ctx.requestSignal !== undefined
             ? { requestSignal: ctx.requestSignal }
             : {}),
-        ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),
         inputSchema: z.object({ name: z.string().optional() }),
         annotations: READ_ONLY_LOCAL,
     }, async (args) => mt.skills(args));
-    // Folded on the code-first surface: a program browses the same inventory with
-    // connecta.search({}) (every catalog) or connecta.search({ connector }) (one).
-    // Live connector probing is an operator concern, not a model one — it stays on
-    // the operator pages and /health, which is where the ethos puts observability.
-    if (!codeFirst) {
-        server.registerTool("list_connectors", {
-            description: LIST_DESC,
-            inputSchema: z.object({ probe: z.boolean().optional() }),
-            annotations: READ_ONLY_REMOTE,
-        }, async (args) => mt.listConnectors(args));
-    }
     server.registerTool("search_tools", {
-        description: describedFor(registry, codeFirst ? CODE_FIRST_SEARCH_DESC : SEARCH_DESC, "search"),
+        description: describedFor(registry, SEARCH_WITH_DESCRIBE_DESC, "search"),
         inputSchema: z.object({
             query: z.string().optional(),
             connector: z.string().optional(),
@@ -1343,21 +1109,8 @@ export function registerMetaTools(server, registry, ctx) {
         }),
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.searchTools(args));
-    // Folded on the code-first surface: connecta.describe takes the same
-    // addresses, format, and per-address error reporting inside a program.
-    if (!codeFirst) {
-        server.registerTool("describe_tools", {
-            description: describedFor(registry, DESCRIBE_DESC, "describe"),
-            inputSchema: z.object({
-                addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
-                format: z.enum(["compact", "json"]).optional(),
-                fullDescriptions: z.boolean().optional(),
-            }),
-            annotations: READ_ONLY_REMOTE,
-        }, async (args) => mt.describeTools(args));
-    }
     server.registerTool("call_tool", {
-        description: codeFirst ? CODE_FIRST_CALL_DESC : CALL_DESC,
+        description: CALL_DESC,
         inputSchema: z.object(CALL_INPUT_SCHEMA),
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
@@ -1365,13 +1118,28 @@ export function registerMetaTools(server, registry, ctx) {
     }, async (args) => mt.callTool(args));
     server.registerTool("call_destructive_tool", {
         description: CALL_DESTRUCTIVE_DESC,
-        inputSchema: z.object(CALL_INPUT_SCHEMA),
+        inputSchema: z.object({
+            ...CALL_INPUT_SCHEMA,
+            // Bounded above, but with no lower bound: a model that sends `""` or
+            // whitespace has written no reason, and failing an entire consequential
+            // call over a cosmetic field the host merely displays is the wrong
+            // trade. It is normalized to absent below instead.
+            reason: z.string().max(500).optional(),
+        }),
         annotations: {
             destructiveHint: true,
             readOnlyHint: false,
             openWorldHint: true,
         },
-    }, async (args) => mt.callDestructiveTool(args));
+    }, async (args) => {
+        // `reason` is the host's to display and connecta's to keep out of the
+        // downstream call, so this destructuring is the whole of its handling:
+        // nothing below reads it. Dropping it is also what makes an empty or
+        // whitespace-only one "absent" rather than a validation failure — there
+        // is no field left for it to be absent from.
+        const { reason: _hostContext, ...call } = args;
+        return mt.callDestructiveTool(call);
+    });
     server.registerTool("authorize_connector", {
         description: AUTHORIZE_DESC,
         inputSchema: z.object({
@@ -1387,7 +1155,7 @@ export function registerMetaTools(server, registry, ctx) {
         },
     }, async (args) => mt.authorizeConnector(args));
     server.registerTool("get_result", {
-        description: codeFirst ? CODE_FIRST_GET_RESULT_DESC : GET_RESULT_DESC,
+        description: GET_RESULT_DESC,
         inputSchema: z.object({
             id: z.string(),
             // Both bounds are the shared rules (isValidResultOffset,
@@ -1399,25 +1167,5 @@ export function registerMetaTools(server, registry, ctx) {
         }),
         annotations: READ_ONLY_LOCAL,
     }, async (args) => mt.getResult(args));
-    // Folded on the code-first surface: connecta.batch runs the same 1–10
-    // parallel read-only calls and returns the same typed per-call outcomes.
-    if (!codeFirst) {
-        server.registerTool("batch_call", {
-            description: BATCH_DESC,
-            inputSchema: z.object({
-                calls: z
-                    .array(z.object(CALL_INPUT_SCHEMA))
-                    .min(1)
-                    .max(10),
-                resultMode: z.enum(["mcp", "value"]).optional(),
-                timeoutMs: z.number().int().positive().optional(),
-                maxRetries: z.number().int().min(0).max(2).optional(),
-                diagnostics: z.boolean().optional(),
-            }),
-            // Same gate as call_tool: every call in the batch must be explicitly
-            // read-only or the batch is refused.
-            annotations: READ_ONLY_REMOTE,
-        }, async (args) => mt.batchCall(args));
-    }
 }
 //# sourceMappingURL=meta-tools.js.map