@zackbart/connecta 0.10.5 → 0.11.0

package/src/meta-tools.ts

@@ -14,19 +14,8 @@ import {
   MAX_DISCOVERY_RESULT_BYTES,
   MAX_SEARCH_LIMIT,
 } from "./catalog-service.js";
-import {
-  mapSettledWithConcurrency,
-  resolveDiscoveryConcurrency,
-} from "./concurrency.js";
-import {
-  closeConnectorScope,
-  type DeferredWork,
-} from "./connector-scope.js";
-import {
-  classifyCallError,
-  messageLooksRetryable,
-  type CallErrorDetails,
-} from "./errors.js";
+import { resolveDiscoveryConcurrency } from "./concurrency.js";
+import type { CallErrorDetails } from "./errors.js";
 import {
   InvocationService,
   MAX_RETRY_BACKOFF_MS,
@@ -47,13 +36,8 @@ import {
 import {
   DEFAULT_PROBE_TIMEOUT_MS,
   normalizeTimeoutMs,
-  withAbortableTimeout,
 } from "./timeout.js";
-import type {
-  ConnectaSurface,
-  ConnectorStatus,
-  KVStorage,
-} from "./types.js";
+import type { KVStorage } from "./types.js";
 
 export {
   MAX_DESCRIBE_ADDRESSES,
@@ -95,10 +79,6 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-function errorDetails(code: string, message: string): CallErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
-
 function discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
   const result = jsonResult({
     error: {
@@ -132,7 +112,6 @@ async function discoveryResult(
   }
 }
 
-
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
 function isContinuationByte(b: number | undefined): boolean {
   return b !== undefined && (b & 0xc0) === 0x80;
@@ -786,6 +765,10 @@ async function stashResult(
   resultId: string;
   totalBytes: number;
   hint: string;
+  nextAction: {
+    tool: "get_result";
+    arguments: { id: string; offset: 0 };
+  };
 }> {
   const id = crypto.randomUUID();
   await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
@@ -794,16 +777,16 @@ async function stashResult(
     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: string): string {
-  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))}…`;
+interface GuardedResult<T> {
+  result: T;
+  truncated: boolean;
 }
 
 /**
@@ -817,16 +800,22 @@ async function guardEncoded(
   bytes: Uint8Array,
   results: KVStorage,
   cap: number,
-): Promise<ToolResult> {
+): Promise<GuardedResult<ToolResult>> {
   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,
   };
 }
 
@@ -835,7 +824,7 @@ async function guardText(
   text: string,
   results: KVStorage,
   cap: number,
-): Promise<ToolResult> {
+): Promise<GuardedResult<ToolResult>> {
   // `JSON.stringify`'s type says `string` where its behavior says `string |
   // undefined`, so TypeScript alone does not keep a non-string out of here.
   // Normalizing at the door means the size check below always measures exactly
@@ -851,11 +840,14 @@ async function guardValue(
   value: unknown,
   results: KVStorage,
   cap: number,
-): Promise<unknown> {
+): Promise<GuardedResult<unknown>> {
   const text = serializeResultText(value);
   const bytes = enc.encode(text);
-  if (bytes.length <= cap) return value;
-  return stashResult(text, results, bytes.length);
+  if (bytes.length <= cap) return { result: value, truncated: false };
+  return {
+    result: await stashResult(text, results, bytes.length),
+    truncated: true,
+  };
 }
 
 /**
@@ -880,7 +872,7 @@ async function guardContent(
   content: TextContent[],
   results: KVStorage,
   cap: number,
-): Promise<ToolResult> {
+): Promise<GuardedResult<ToolResult>> {
   let text: string;
   try {
     text = JSON.stringify(content);
@@ -889,17 +881,22 @@ async function guardContent(
     // 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,
+  };
 }
 
 // --- compact schema rendering (feature 3a) --------------------------------
@@ -915,17 +912,6 @@ export interface SearchArgs {
   fullDescriptions?: boolean;
   includeSchemas?: "compact" | "json";
 }
-export type DescribeArgs = (
-  | { address: string; addresses?: never }
-  | { address?: never; addresses: string[] }
-) & {
-  format?: "compact" | "json";
-  fullDescriptions?: boolean;
-};
-export interface ListArgs {
-  /** When false, return cached/observed health without downstream I/O. */
-  probe?: boolean;
-}
 type ResultMode = "mcp" | "value";
 export interface CallArgs {
   address: string;
@@ -938,6 +924,10 @@ export interface CallArgs {
   /** Include connector/catalog/result-processing timing segments. */
   diagnostics?: boolean;
 }
+export interface DestructiveCallArgs extends CallArgs {
+  /** Short model-authored context for the host's approval UI; never downstream input. */
+  reason?: string;
+}
 export interface GetResultArgs {
   id: string;
   /**
@@ -948,14 +938,6 @@ export interface GetResultArgs {
   /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
   maxBytes?: number;
 }
-export type BatchCall = CallArgs;
-export interface BatchArgs {
-  calls: BatchCall[];
-  resultMode?: ResultMode;
-  timeoutMs?: number;
-  maxRetries?: number;
-  diagnostics?: boolean;
-}
 export interface AuthorizeArgs {
   connector: string;
   force?: boolean;
@@ -965,17 +947,27 @@ export interface SkillArgs {
 }
 
 /**
- * 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.)
+ * 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: string): string {
+  return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
+}
+
+/**
+ * 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: RegistryView,
@@ -983,27 +975,17 @@ export function createMetaTools(
   opts: {
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
     defaultToolTimeoutMs?: number;
-    /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+    /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
     probeTimeoutMs?: number;
     /** Maximum simultaneous connector discovery operations. Default 4. */
     discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
-    /** Inbound request cancellation shared by direct and batch child calls. */
+    /** Inbound request cancellation shared by every call this request makes. */
     requestSignal?: AbortSignal;
-    /** Runtime continuation for the bounded tail of probe-owned teardown. */
-    defer?: DeferredWork;
-    /**
-     * The advertised surface, which the `skills` guidance must match: a
-     * code-first deployment never gets guidance naming a tool it does not
-     * advertise. Default `classic`.
-     */
-    surface?: ConnectaSurface;
   } = {},
 ) {
-  const surface: ConnectaSurface = 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;
@@ -1018,20 +1000,10 @@ export function createMetaTools(
     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 = <T>(
-    label: string,
-    operation: (options: {
-      signal: AbortSignal;
-      timeoutMs: number;
-    }) => Promise<T>,
-  ) =>
-    withAbortableTimeout(
-      (signal) => operation({ signal, timeoutMs: probeTimeoutMs }),
-      probeTimeoutMs,
-      label,
-    );
 
   interface RunCallOutcome {
     toolResult: ToolResult;
@@ -1045,11 +1017,17 @@ export function createMetaTools(
   interface ProcessedCallResult {
     toolResult: ToolResult;
     value?: unknown;
+    /**
+     * Friction on a call that *succeeded*. It travels as a friction class, not
+     * as an `errorCode`, so persistence keyed on "this row has an error code"
+     * keeps counting failures rather than truncations.
+     */
+    friction?: "result_too_large";
   }
 
   /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
   async function runCall(
-    call: BatchCall,
+    call: CallArgs,
     source: ActivityCallSource,
     options: { allowDestructive?: boolean } = {},
   ): Promise<RunCallOutcome> {
@@ -1075,7 +1053,7 @@ export function createMetaTools(
         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`.
@@ -1091,10 +1069,14 @@ export function createMetaTools(
                   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" as const }
+                : {}),
             };
           }
           if (resolved.connector.kind === "mcp") {
@@ -1107,7 +1089,13 @@ export function createMetaTools(
                 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" as const }
+                : {}),
+            };
           }
           const value = fields
             ? projectionValue(
@@ -1116,19 +1104,26 @@ export function createMetaTools(
                 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" as const }
+              : {}),
           };
         },
+        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" ||
@@ -1142,6 +1137,7 @@ export function createMetaTools(
             })
           : errorResult(outcome.error.message);
       if (
+        structuredRecovery ||
         outcome.error.code === "auth_required" ||
         outcome.error.code === "invalid_args" ||
         outcome.error.code === "input_required_unsupported"
@@ -1187,143 +1183,18 @@ export function createMetaTools(
               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: ListArgs = {}): Promise<ToolResult> {
-      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: (typeof connectors)[number]) => {
-        const statusStarted = Date.now();
-        const observed = registry.healthFor(c.id);
-        const drift = await registry.credentialDriftFor(c.id);
-        let status:
-          | ConnectorStatus
-          | { state: "ok" | "error" | "unknown"; message?: string };
-        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" as const)
-              : registry.hasObservedSuccess(c.id) || c.kind === "api"
-                ? ("ok" as const)
-                : ("unknown" as const);
-          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: ConnectorStatus | undefined;
-              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" as const,
-                      message: details.message,
-                    };
-            } else {
-              status = { state: "error" as const, 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: SearchArgs): Promise<ToolResult> {
       return discoveryResult(
         async () =>
@@ -1337,18 +1208,13 @@ export function createMetaTools(
       );
     },
 
-    async describeTools(args: DescribeArgs): Promise<ToolResult> {
-      return discoveryResult(
-        async () => ({ tools: await catalog.describe(args) }),
-        'Split the address list or use format: "compact".',
-      );
-    },
-
     async callTool(args: CallArgs): Promise<ToolResult> {
       return (await runCall(args, "call_tool")).toolResult;
     },
 
-    async callDestructiveTool(args: CallArgs): Promise<ToolResult> {
+    async callDestructiveTool(args: DestructiveCallArgs): Promise<ToolResult> {
+      // `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;
@@ -1413,143 +1279,6 @@ export function createMetaTools(
       });
     },
 
-    async batchCall(args: BatchArgs): Promise<ToolResult> {
-      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: AuthorizeArgs): Promise<ToolResult> {
       const connector = registry.getConnector(args.connector);
       if (!connector) {
@@ -1626,7 +1355,8 @@ export function createMetaTools(
             ? {
                 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.",
+                  "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 } : {}),
@@ -1642,39 +1372,19 @@ export function createMetaTools(
   };
 }
 
-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.';
+  '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. 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.";
+  "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/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.";
+  "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
@@ -1689,8 +1399,6 @@ const GUIDE_NOTES = {
     ' 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> }).",
 } as const;
 
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
@@ -1735,15 +1443,12 @@ const CALL_INPUT_SCHEMA = {
 };
 
 /**
- * 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: McpServer,
@@ -1755,15 +1460,9 @@ export function registerMetaTools(
     discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
-    defer?: DeferredWork;
-    /** The advertised surface. Default `classic`. */
-    surface?: ConnectaSurface;
   },
 ): void {
-  const surface: ConnectaSurface = ctx.surface ?? "classic";
-  const codeFirst = surface === "code-first";
   const mt = createMetaTools(registry, ctx.baseUrl, {
-    surface,
     ...(ctx.defaultToolTimeoutMs !== undefined
       ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
       : {}),
@@ -1777,7 +1476,6 @@ export function registerMetaTools(
     ...(ctx.requestSignal !== undefined
       ? { requestSignal: ctx.requestSignal }
       : {}),
-    ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
   });
 
   server.registerTool(
@@ -1790,28 +1488,12 @@ export function registerMetaTools(
     async (args) => mt.skills(args as SkillArgs),
   );
 
-  // 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 as ListArgs),
-    );
-  }
-
   server.registerTool(
     "search_tools",
     {
       description: describedFor(
         registry,
-        codeFirst ? CODE_FIRST_SEARCH_DESC : SEARCH_DESC,
+        SEARCH_WITH_DESCRIBE_DESC,
         "search",
       ),
       inputSchema: z.object({
@@ -1830,28 +1512,10 @@ export function registerMetaTools(
     async (args) => mt.searchTools(args as SearchArgs),
   );
 
-  // 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 as DescribeArgs),
-    );
-  }
-
   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.
@@ -1864,14 +1528,29 @@ export function registerMetaTools(
     "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 as CallArgs),
+    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 as DestructiveCallArgs;
+      return mt.callDestructiveTool(call);
+    },
   );
 
   server.registerTool(
@@ -1896,7 +1575,7 @@ export function registerMetaTools(
   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,
@@ -1910,29 +1589,4 @@ export function registerMetaTools(
     },
     async (args) => mt.getResult(args as GetResultArgs),
   );
-
-  // 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 as BatchArgs),
-    );
-  }
 }