@zackbart/connecta 0.7.8 → 0.8.0

package/src/meta-tools.ts

@@ -1,22 +1,37 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
-import {
-  recordToolActivity,
-  type ActivityCallSource,
-  type ActivityRequestContext,
+import type {
+  ActivityCallSource,
+  ActivityRequestContext,
 } from "./activity.js";
+import {
+  boundedDiscoveryText,
+  CatalogService,
+  DiscoveryPolicyError,
+  groupedSearchResult,
+  MAX_DESCRIBE_ADDRESSES,
+  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 { unwrapMcpResult } from "./mcp-result.js";
 import {
   classifyCallError,
-  ConnectorCallError,
   messageLooksRetryable,
   type CallErrorDetails,
 } from "./errors.js";
+import {
+  InvocationService,
+  MAX_RETRY_BACKOFF_MS,
+  retryBackoffMs,
+  type InvocationTiming,
+} from "./invocation.js";
 import {
   isValidMaxResultBytes,
   MIN_MAX_RESULT_BYTES,
@@ -24,8 +39,6 @@ import {
   type RegistryView,
 } from "./registry.js";
 import {
-  connectorGuide,
-  connectorSkillName,
   hasConnectorGuides,
   listSkills,
   resolveSkill,
@@ -36,7 +49,16 @@ import {
   withAbortableTimeout,
 } from "./timeout.js";
 import { credentialVerdictApplies } from "./credential-health.js";
-import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
+import type { ConnectorStatus, KVStorage } from "./types.js";
+
+export {
+  MAX_DESCRIBE_ADDRESSES,
+  MAX_DISCOVERY_RESULT_BYTES,
+  MAX_RETRY_BACKOFF_MS,
+  MAX_SEARCH_LIMIT,
+  DiscoveryPolicyError,
+  retryBackoffMs,
+};
 
 interface TextContent {
   type: "text";
@@ -50,6 +72,8 @@ export interface ToolResult {
 }
 
 const RESULT_TTL_SECONDS = 900;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
 
 export function jsonResult(obj: unknown): ToolResult {
   return {
@@ -68,95 +92,8 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-export const DEFAULT_SEARCH_LIMIT = 25;
-/**
- * A discovery page is for choosing the next tool, not exporting the catalog.
- * One hundred leaves room for broad browsing while keeping each deliberate
- * page far below the catalog sizes Connecta supports.
- */
-export const MAX_SEARCH_LIMIT = 100;
-/** Same one-request work bound for address-based discovery. */
-export const MAX_DESCRIBE_ADDRESSES = 100;
-/**
- * Final UTF-8 ceiling for a generated search/describe response. The count
- * limits are the ordinary guard; this catches unusually large full schemas or
- * descriptions that make even a bounded page expensive.
- */
-export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
-const enc = new TextEncoder();
-const dec = new TextDecoder();
-
-type ErrorDetails = CallErrorDetails;
-
-export class DiscoveryPolicyError extends Error {
-  constructor(
-    readonly code: "invalid_args" | "result_too_large",
-    message: string,
-  ) {
-    super(message);
-    this.name = "DiscoveryPolicyError";
-  }
-}
-
-/** Validate before ranking so a huge page request does no proportional work. */
-export function discoverySearchLimit(value: unknown): number {
-  if (value === undefined) return DEFAULT_SEARCH_LIMIT;
-  if (
-    typeof value !== "number" ||
-    !Number.isInteger(value) ||
-    value < 1 ||
-    value > MAX_SEARCH_LIMIT
-  ) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      `limit must be a whole number from 1 through ${MAX_SEARCH_LIMIT}. Page through larger catalogs with offset.`,
-    );
-  }
-  return value;
-}
-
-/** Validate the raw list so duplicate addresses consume the same bound. */
-export function discoveryAddresses(value: unknown): unknown[] {
-  if (!Array.isArray(value)) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      "addresses must be an array.",
-    );
-  }
-  if (value.length > MAX_DESCRIBE_ADDRESSES) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across describe_tools calls.`,
-    );
-  }
-  return value;
-}
-
-/** Serialize once and count the exact bytes jsonResult would emit. */
-function boundedDiscoveryText(
-  value: unknown,
-  hint: string,
-): string {
-  const text = JSON.stringify(value, null, 2);
-  if (text === undefined) {
-    throw new TypeError("Discovery result is not JSON-serializable.");
-  }
-  const bytes = enc.encode(text).length;
-  if (bytes > MAX_DISCOVERY_RESULT_BYTES) {
-    throw new DiscoveryPolicyError(
-      "result_too_large",
-      `Discovery result is ${bytes} UTF-8 bytes, over the ${MAX_DISCOVERY_RESULT_BYTES}-byte ceiling. ${hint}`,
-    );
-  }
-  return text;
-}
-
-/** Apply the same final result guard to code-mode discovery helpers. */
-export function assertDiscoveryResultSize(
-  value: unknown,
-  hint: string,
-): void {
-  boundedDiscoveryText(value, hint);
+function errorDetails(code: string, message: string): CallErrorDetails {
+  return { code, message, retryable: messageLooksRetryable(message) };
 }
 
 function discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
@@ -188,53 +125,14 @@ function discoveryResult(value: unknown, hint: string): ToolResult {
   }
 }
 
-/**
- * The longest the engine will park a synchronous inbound request in *waiting
- * alone*. The engine already treats ~15 s as the outer bound of one reasonable
- * connector call (EXECUTE_HOST_CALL_TIMEOUT_MS), so sleeping for minutes trades
- * a fast, informative failure for a hung one. A connector-reported window this
- * long isn't truncated — it's declined (see `retryBackoffMs`) and reported
- * verbatim as `error.retryAfterMs`, so the agent, which can afford to wait,
- * decides when to re-issue.
- */
-export const MAX_RETRY_BACKOFF_MS = 10_000;
-
-/**
- * How long to wait before the next attempt, or `undefined` for "don't retry".
- *
- * A connector that read a `Retry-After` header knows the window exactly, so it
- * is honoured **exactly or not at all**: truncating an exponential *guess* is
- * harmless, but truncating a *known* window means deliberately retrying inside
- * a rate limit — the harm this channel exists to prevent. A window longer than
- * `MAX_RETRY_BACKOFF_MS` therefore declines the retry rather than shortening
- * it. (`retryAfterMs` is normalized non-negative, so `0` means "retry now".)
- * Connectors that report no window keep the historical exponential guess.
- *
- * Waits are per attempt, matching the per-attempt `timeoutMs` race in
- * `runCall`. Exported for direct testing.
- */
-export function retryBackoffMs(
-  attempt: number,
-  retryAfterMs: number | undefined,
-): number | undefined {
-  if (retryAfterMs === undefined) {
-    return Math.min(250 * 2 ** (attempt - 1), 1_000);
-  }
-  return retryAfterMs <= MAX_RETRY_BACKOFF_MS ? retryAfterMs : undefined;
-}
-
-/** Details for failures that never reached a connector (no thrown value). */
-function errorDetails(code: string, message: string): ErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
 
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
-function isContinuationByte(b: number): boolean {
-  return (b & 0xc0) === 0x80;
+function isContinuationByte(b: number | undefined): boolean {
+  return b !== undefined && (b & 0xc0) === 0x80;
 }
 
 /** Smallest accepted `get_result` byte offset. */
-export const MIN_RESULT_OFFSET = 0;
+const MIN_RESULT_OFFSET = 0;
 
 /**
  * The one definition of a usable `get_result` offset: a whole number of bytes
@@ -250,7 +148,7 @@ export const MIN_RESULT_OFFSET = 0;
  * 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.
  */
-export function isValidResultOffset(value: number): boolean {
+function isValidResultOffset(value: number): boolean {
   return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
 }
 
@@ -314,8 +212,9 @@ export function alignEndToCharBoundary(
 
 /** Resolve a dot-path (segments) against a value; `key[]` maps the tail over an array. */
 function resolvePath(value: unknown, segments: string[]): unknown {
-  if (segments.length === 0) return value;
-  const [seg, ...rest] = segments;
+  const seg = segments[0];
+  if (seg === undefined) return value;
+  const rest = segments.slice(1);
   const isArr = seg.endsWith("[]");
   const key = isArr ? seg.slice(0, -2) : seg;
   let next: unknown = value;
@@ -377,7 +276,7 @@ function applyFieldsToContent(
  * 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.
  */
-export function serializeResultText(value: unknown): string {
+function serializeResultText(value: unknown): string {
   const serialized = JSON.stringify(value, null, 2);
   return serialized === undefined ? String(value) : serialized;
 }
@@ -532,7 +431,7 @@ export interface ListArgs {
   /** When false, return cached/observed health without downstream I/O. */
   probe?: boolean;
 }
-export type ResultMode = "mcp" | "value";
+type ResultMode = "mcp" | "value";
 export interface CallArgs {
   address: string;
   args?: Record<string, unknown>;
@@ -597,7 +496,11 @@ export function createMetaTools(
     defaultToolTimeoutMs?: number;
     /** Per-connector deadline for the list/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. */
+    requestSignal?: AbortSignal;
     /** Runtime continuation for the bounded tail of probe-owned teardown. */
     defer?: DeferredWork;
   } = {},
@@ -608,10 +511,19 @@ export function createMetaTools(
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
+  const discoveryConcurrency = resolveDiscoveryConcurrency(
+    opts.discoveryConcurrency,
+  );
   // createMetaTools() is called once per inbound MCP request. Sharing this
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
   const requestScope = {};
+  const catalog = new CatalogService(registry, baseUrl, {
+    requestScope,
+    probeTimeoutMs,
+    concurrency: discoveryConcurrency,
+  });
+  const invocation = new InvocationService(registry, catalog, opts.activity);
   const withProbeDeadline = <T>(
     label: string,
     operation: (options: {
@@ -629,281 +541,115 @@ export function createMetaTools(
     toolResult: ToolResult;
     durationMs: number;
     attempts: number;
-    timing: {
-      catalogMs: number;
-      connectorMs: number;
-      backoffMs: number;
-      resultProcessingMs: number;
-      totalMs: number;
-    };
+    timing: InvocationTiming;
     value?: unknown;
-    error?: ErrorDetails;
+    error?: CallErrorDetails;
   }
 
-  /** Shared call path used by call tools and batch_call: safety → fields → size guard. */
+  interface ProcessedCallResult {
+    toolResult: ToolResult;
+    value?: unknown;
+  }
+
+  /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
   async function runCall(
     call: BatchCall,
     source: ActivityCallSource,
     options: { allowDestructive?: boolean } = {},
   ): Promise<RunCallOutcome> {
-    const started = Date.now();
-    let catalogMs = 0;
-    let connectorMs = 0;
-    let backoffMs = 0;
-    let resultProcessingMs = 0;
-    let attempts = 0;
-    const timing = () => ({
-      catalogMs,
-      connectorMs,
-      backoffMs,
-      resultProcessingMs,
-      totalMs: Date.now() - started,
-    });
-    const resolved = registry.resolveAddress(call.address);
-    const record = (
-      outcome: "success" | "error" | "timeout",
-      errorCode?: string,
-    ) => {
-      if (!resolved) return;
-      recordToolActivity(opts.activity, {
-        connectorId: resolved.connector.id,
-        toolName: resolved.toolName,
-        address: `${resolved.connector.id}.${resolved.toolName}`,
+    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<ProcessedCallResult>(
+      call.address,
+      call.args ?? {},
+      {
         source,
-        outcome,
-        durationMs: Date.now() - started,
-        attempts,
-        ...(errorCode ? { errorCode } : {}),
-      });
-    };
-    const failed = (error: ErrorDetails): RunCallOutcome => {
-      const durationMs = Date.now() - started;
-      const diagnostics = timing();
-      record(error.code === "timeout" ? "timeout" : "error", error.code);
+        ...(options.allowDestructive !== undefined
+          ? { allowDestructive: options.allowDestructive }
+          : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(call.maxRetries !== undefined
+          ? { maxRetries: call.maxRetries }
+          : {}),
+        ...(opts.requestSignal !== undefined
+          ? { requestSignal: opts.requestSignal }
+          : {}),
+        unwrapResult: call.resultMode === "value",
+        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
+          // 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`.
+          const cap = resolveMaxResultBytes(
+            resolved.connector.maxResultBytes,
+            globalCap,
+          );
+          if (call.resultMode === "value") {
+            let value = fields ? applyFields(result, fields) : result;
+            value = await guardValue(value, results, cap);
+            return {
+              toolResult: jsonResult({ ok: true, data: value }),
+              value,
+            };
+          }
+          if (resolved.connector.kind === "mcp") {
+            const mcpResult = result as { content?: TextContent[] };
+            let content = mcpResult?.content ?? [];
+            if (fields) content = applyFieldsToContent(content, fields);
+            return { toolResult: await guardContent(content, results, cap) };
+          }
+          const value = fields ? applyFields(result, fields) : result;
+          return {
+            toolResult: await guardText(
+              serializeResultText(value),
+              results,
+              cap,
+            ),
+            value,
+          };
+        },
+      },
+    );
+    if (!outcome.ok) {
       return {
         toolResult:
           call.resultMode === "value"
             ? jsonResult({
                 ok: false,
-                error,
-                durationMs,
-                attempts,
-                ...(call.diagnostics ? { timing: diagnostics } : {}),
+                error: outcome.error,
+                durationMs: outcome.durationMs,
+                attempts: outcome.attempts,
+                ...(call.diagnostics ? { timing: outcome.timing } : {}),
               })
-            : errorResult(error.message),
-        durationMs,
-        attempts,
-        timing: diagnostics,
-        error,
+            : errorResult(outcome.error.message),
+        durationMs: outcome.durationMs,
+        attempts: outcome.attempts,
+        timing: outcome.timing,
+        error: outcome.error,
       };
-    };
-    if (!resolved) {
-      return failed(
-        errorDetails("unknown_address", `Unknown address "${call.address}"`),
-      );
     }
-    const results = registry.resultsStorage();
-    // 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 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`.
-    const cap = resolveMaxResultBytes(
-      resolved.connector.maxResultBytes,
-      globalCap,
-    );
-    const fields = call.fields && call.fields.length > 0 ? call.fields : null;
-    // An explicit per-call deadline always wins; the config default only fills
-    // the gap, and stays off entirely when the deployment sets none.
-    const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
-    const maxRetries = Math.min(
-      2,
-      Math.max(0, Math.trunc(call.maxRetries ?? 0)),
-    );
-    const catalogStarted = Date.now();
-    let definition: ToolDef | undefined;
-    try {
-      definition = (
-        await registry.getTools(resolved.connector.id, baseUrl, requestScope)
-      ).find((tool) => tool.name === resolved.toolName);
-    } catch (err) {
-      catalogMs += Date.now() - catalogStarted;
-      // A connector whose catalog cannot be fetched is as unusable as one whose
-      // execution fails, so it feeds health accounting the same way the
-      // execution catch below does — otherwise a connector every call_tool
-      // fails against (a revoked downstream grant, say) still reads clean from
-      // the cheap `list_connectors({ probe: false })` signal.
-      //
-      // Recorded HERE rather than inside the registry's catalog fetch on
-      // purpose: `registry` is this connection's VIEW, so a toolkit-scoped
-      // session records into its own log as well as the deployment-wide one,
-      // which `Registry.refreshTools` could not reach. A cache hit that avoids
-      // a live listTools call therefore records nothing either way — it is not
-      // evidence of health, and success stays what it has always been: an
-      // actual downstream call that returned.
-      registry.recordFailure(resolved.connector.id, Date.now() - started, err);
-      // classifyCallError so a typed auth_required thrown while listing tools
-      // (e.g. a revoked downstream OAuth grant) keeps its code.
-      return failed(classifyCallError(err, "catalog_lookup_failed"));
-    }
-    catalogMs += Date.now() - catalogStarted;
-    if (!definition) {
-      return failed(
-        errorDetails(
-          "unknown_tool",
-          `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-        ),
-      );
-    }
-    const explicitlyReadOnly =
-      definition.annotations?.readOnlyHint === true &&
-      definition.annotations?.destructiveHint !== true;
-    if (!explicitlyReadOnly && !options.allowDestructive) {
-      return failed(
-        errorDetails(
-          "destructive_tool_requires_approval",
-          `Tool "${call.address}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`,
-        ),
-      );
-    }
-    const retrySafe =
-      definition.annotations?.readOnlyHint === true ||
-      definition.annotations?.idempotentHint === true;
-
-    let result: unknown;
-    while (true) {
-      attempts++;
-      const controller = timeoutMs ? new AbortController() : undefined;
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const ctx = registry.contextFor(
-        resolved.connector.id,
-        baseUrl,
-        requestScope,
-        { signal: controller?.signal, timeoutMs },
-      );
-      const connectorStarted = Date.now();
-      try {
-        const pending = resolved.connector.callTool(
-          resolved.toolName,
-          call.args ?? {},
-          ctx,
-        );
-        result = timeoutMs
-          ? await Promise.race([
-              pending,
-              new Promise<never>((_, reject) => {
-                timer = setTimeout(() => {
-                  reject(
-                    new ConnectorCallError(
-                      "timeout",
-                      `Tool call timed out after ${timeoutMs}ms`,
-                    ),
-                  );
-                  controller?.abort();
-                }, timeoutMs);
-              }),
-            ])
-          : await pending;
-        connectorMs += Date.now() - connectorStarted;
-        const mcpResult = result as {
-          content?: TextContent[];
-          isError?: boolean;
-        };
-        if (resolved.connector.kind === "mcp" && mcpResult?.isError) {
-          throw new Error(
-            mcpResult.content?.map((block) => block.text).join("") ||
-              "Downstream tool call failed",
-          );
-        }
-        break;
-      } catch (err) {
-        // Includes connector setup, downstream execution, and timeout wait.
-        connectorMs += Date.now() - connectorStarted;
-        const details = classifyCallError(err);
-        if (attempts <= maxRetries && retrySafe && details.retryable) {
-          const wait = retryBackoffMs(attempts, details.retryAfterMs);
-          if (wait !== undefined) {
-            const backoffStarted = Date.now();
-            if (wait > 0) {
-              await new Promise((resolve) => setTimeout(resolve, wait));
-            }
-            backoffMs += Date.now() - backoffStarted;
-            continue;
-          }
-          // The reported window is longer than the engine will park a
-          // synchronous request for. Fall through to failure with
-          // retryAfterMs reported verbatim so the agent can re-issue.
-        }
-        registry.recordFailure(
-          resolved.connector.id,
-          Date.now() - started,
-          err,
-        );
-        return failed(details);
-      } finally {
-        if (timer) clearTimeout(timer);
-      }
-    }
-
-    registry.recordSuccess(resolved.connector.id, Date.now() - started);
-    const processingStarted = Date.now();
-    try {
-      const mr = result as { content?: TextContent[]; isError?: boolean };
-      if (call.resultMode === "value") {
-        let value = unwrapMcpResult(resolved.connector.kind, result);
-        if (fields) value = applyFields(value, fields);
-        value = await guardValue(value, results, cap);
-        resultProcessingMs += Date.now() - processingStarted;
-        const durationMs = Date.now() - started;
-        const diagnostics = timing();
-        record("success");
-        return {
-          toolResult: jsonResult({
+    const valueModeResult =
+      call.resultMode === "value"
+        ? jsonResult({
             ok: true,
-            data: value,
-            durationMs,
-            attempts,
-            ...(call.diagnostics ? { timing: diagnostics } : {}),
-          }),
-          durationMs,
-          attempts,
-          timing: diagnostics,
-          value,
-        };
-      }
-      if (resolved.connector.kind === "mcp") {
-        let content = mr?.content ?? [];
-        if (fields) content = applyFieldsToContent(content, fields);
-        const toolResult = await guardContent(content, results, cap);
-        resultProcessingMs += Date.now() - processingStarted;
-        record("success");
-        return {
-          toolResult,
-          durationMs: Date.now() - started,
-          attempts,
-          timing: timing(),
-        };
-      }
-      const value = fields ? applyFields(result, fields) : result;
-      const toolResult = await guardText(
-        serializeResultText(value),
-        results,
-        cap,
-      );
-      resultProcessingMs += Date.now() - processingStarted;
-      record("success");
-      return {
-        toolResult,
-        durationMs: Date.now() - started,
-        attempts,
-        timing: timing(),
-        value,
-      };
-    } catch (err) {
-      resultProcessingMs += Date.now() - processingStarted;
-      return failed(errorDetails("result_processing_failed", msg(err)));
-    }
+            data: outcome.value.value,
+            durationMs: outcome.durationMs,
+            attempts: outcome.attempts,
+            ...(call.diagnostics ? { timing: outcome.timing } : {}),
+          })
+        : outcome.value.toolResult;
+    return {
+      toolResult: valueModeResult,
+      durationMs: outcome.durationMs,
+      attempts: outcome.attempts,
+      timing: outcome.timing,
+      ...(Object.prototype.hasOwnProperty.call(outcome.value, "value")
+        ? { value: outcome.value.value }
+        : {}),
+    };
   }
 
   return {
@@ -934,181 +680,184 @@ export function createMetaTools(
       // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
       const connectors = registry.listConnectors();
       const scope = probe ? {} : requestScope;
-      const pending = connectors.map(
-        async (c) => {
-          const statusStarted = Date.now();
-          const observed = registry.healthFor(c.id);
-          const verdict = await registry.credentialHealthFor(c.id);
-          let status:
-            | ConnectorStatus
-            | { state: "ok" | "error" | "unknown"; message?: string };
-          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 if (
-            verdict &&
-            // Deployment-wide, deliberately, like `hasObservedSuccess` beside
-            // it: a sibling toolkit's successful call proves the shared
-            // credential works, and a verdict retired for one view but not
-            // another would make the same connector read differently per scope
-            // for a reason that has nothing to do with scope.
-            credentialVerdictApplies(verdict, registry.observedSuccessAt(c.id))
-          ) {
-            // The proactive layer (issue #24): a liveness check already found
-            // the stored credential dead, so say so on the cheap path instead of
-            // waiting for an agent's real call to discover it. Only while it is
-            // the freshest evidence — a successful call since then retires it.
-            status = {
-              state: verdict.state,
-              ...(verdict.message ? { message: verdict.message } : {}),
-              ...(verdict.authorizationUrl
-                ? { authorizationUrl: verdict.authorizationUrl }
-                : {}),
-            };
-          } else {
-            // "error" comes from THIS view's own observations — a sibling
-            // toolkit's failure is not this session's experience — while
-            // ok/unknown may lean on the deployment-wide success signal, since
-            // "the connector answers at all" is a fact about the connector.
-            // Unscoped, the two are the same log, so this is unchanged there.
-            const derived =
-              observed?.consecutiveFailures && observed.consecutiveFailures > 0
-                ? ("error" as const)
-                : registry.hasObservedSuccess(c.id) || c.kind === "api"
-                  ? ("ok" as const)
-                  : ("unknown" as const);
-            status = {
-              // A successful liveness check upgrades "unknown" — nothing has
-              // been called yet, but the credential was verified, which is how
-              // re-authorization shows up here as ok rather than as an absence
-              // of evidence. It never DOWNgrades an observed failure: a real
-              // call that failed is stronger evidence than a background check.
-              state:
-                derived === "unknown" && verdict?.state === "ok"
-                  ? ("ok" as const)
-                  : derived,
-              ...(observed?.lastError ? { message: observed.lastError } : {}),
-            };
-          }
-          // Stamped where the observation actually happened — after the status
-          // probe, not before it. A 30-second probe stamped at its start would
-          // report a verdict older than it is, and would lose the race against a
-          // real call that succeeded WHILE it ran (that success must retire the
-          // verdict, and only an honest timestamp says so).
-          const checkedAt = new Date().toISOString();
-          // A live status probe IS a liveness observation of the stored
-          // credential, so it updates the same verdict a background check
-          // writes: the cached read afterwards agrees with what the operator
-          // just saw, and they are not swept again moments later. Recorded from
-          // the STATUS phase only, and only when the connector actually answered
-          // — a catalog refresh below is not a credential check (the sweep never
-          // fetches one), it is already counted in the health log, and letting
-          // its failure land here would spend the freshness budget on it. The
-          // registry ignores this for connectors storing no credential of ours.
-          if (probe && (status.state === "ok" || status.state === "auth_required")) {
-            await registry.recordCredentialHealth(c.id, {
-              state: status.state,
-              checkedAt,
-              ...(status.message ? { message: status.message } : {}),
-              ...("authorizationUrl" in status && status.authorizationUrl
-                ? { authorizationUrl: status.authorizationUrl }
-                : {}),
-            });
+      const inspect = async (c: (typeof connectors)[number]) => {
+        const statusStarted = Date.now();
+        const observed = registry.healthFor(c.id);
+        const verdict = await registry.credentialHealthFor(c.id);
+        let status:
+          | ConnectorStatus
+          | { state: "ok" | "error" | "unknown"; message?: string };
+        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) };
           }
-          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,
-                      };
-                await registry.recordCredentialHealth(c.id, {
-                  state: "auth_required",
-                  checkedAt,
-                  ...(status.message ? { message: status.message } : {}),
-                  ...("authorizationUrl" in status &&
-                  status.authorizationUrl
-                    ? { authorizationUrl: status.authorizationUrl }
-                    : {}),
-                });
-              } 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);
-          const credentialCheck = probe
-            ? await registry.credentialHealthFor(c.id)
-            : verdict;
-          return {
-            id: c.id,
-            ...(c.title ? { title: c.title } : {}),
-            description: c.description,
-            toolCount: tools?.length ?? 0,
-            status: status.state,
+        } else if (
+          verdict &&
+          // Deployment-wide, deliberately, like `hasObservedSuccess` beside
+          // it: a sibling toolkit's successful call proves the shared
+          // credential works, and a verdict retired for one view but not
+          // another would make the same connector read differently per scope
+          // for a reason that has nothing to do with scope.
+          credentialVerdictApplies(verdict, registry.observedSuccessAt(c.id))
+        ) {
+          // The proactive layer (issue #24): a liveness check already found
+          // the stored credential dead, so say so on the cheap path instead of
+          // waiting for an agent's real call to discover it. Only while it is
+          // the freshest evidence — a successful call since then retires it.
+          status = {
+            state: verdict.state,
+            ...(verdict.message ? { message: verdict.message } : {}),
+            ...(verdict.authorizationUrl
+              ? { authorizationUrl: verdict.authorizationUrl }
+              : {}),
+          };
+        } else {
+          // "error" comes from THIS view's own observations — a sibling
+          // toolkit's failure is not this session's experience — while
+          // ok/unknown may lean on the deployment-wide success signal, since
+          // "the connector answers at all" is a fact about the connector.
+          // Unscoped, the two are the same log, so this is unchanged there.
+          const derived =
+            observed?.consecutiveFailures && observed.consecutiveFailures > 0
+              ? ("error" as const)
+              : registry.hasObservedSuccess(c.id) || c.kind === "api"
+                ? ("ok" as const)
+                : ("unknown" as const);
+          status = {
+            // A successful liveness check upgrades "unknown" — nothing has
+            // been called yet, but the credential was verified, which is how
+            // re-authorization shows up here as ok rather than as an absence
+            // of evidence. It never DOWNgrades an observed failure: a real
+            // call that failed is stronger evidence than a background check.
+            state:
+              derived === "unknown" && verdict?.state === "ok"
+                ? ("ok" as const)
+                : derived,
+            ...(observed?.lastError ? { message: observed.lastError } : {}),
+          };
+        }
+        // Stamped where the observation actually happened — after the status
+        // probe, not before it. A 30-second probe stamped at its start would
+        // report a verdict older than it is, and would lose the race against a
+        // real call that succeeded WHILE it ran (that success must retire the
+        // verdict, and only an honest timestamp says so).
+        const checkedAt = new Date().toISOString();
+        // A live status probe IS a liveness observation of the stored
+        // credential, so it updates the same verdict a background check
+        // writes: the cached read afterwards agrees with what the operator
+        // just saw, and they are not swept again moments later. Recorded from
+        // the STATUS phase only, and only when the connector actually answered
+        // — a catalog refresh below is not a credential check (the sweep never
+        // fetches one), it is already counted in the health log, and letting
+        // its failure land here would spend the freshness budget on it. The
+        // registry ignores this for connectors storing no credential of ours.
+        if (probe && (status.state === "ok" || status.state === "auth_required")) {
+          await registry.recordCredentialHealth(c.id, {
+            state: status.state,
             checkedAt,
-            latencyMs,
-            probe,
-            ...(latestObserved ?? observed ?? {}),
-            ...(credentialCheck ? { credentialCheck } : {}),
+            ...(status.message ? { message: status.message } : {}),
             ...("authorizationUrl" in status && status.authorizationUrl
               ? { authorizationUrl: status.authorizationUrl }
               : {}),
-            ...(status.message ? { message: status.message } : {}),
-          };
-        },
+          });
+        }
+        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,
+                    };
+              await registry.recordCredentialHealth(c.id, {
+                state: "auth_required",
+                checkedAt,
+                ...(status.message && { message: status.message }),
+                ...("authorizationUrl" in status &&
+                status.authorizationUrl
+                  ? { authorizationUrl: status.authorizationUrl }
+                  : {}),
+              });
+            } 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);
+        const credentialCheck = probe
+          ? await registry.credentialHealthFor(c.id)
+          : verdict;
+        return {
+          id: c.id,
+          ...(c.title ? { title: c.title } : {}),
+          description: c.description,
+          toolCount: tools?.length ?? 0,
+          status: status.state,
+          checkedAt,
+          latencyMs,
+          probe,
+          ...(latestObserved ?? observed),
+          ...(credentialCheck ? { credentialCheck } : {}),
+          ...("authorizationUrl" in status &&
+            status.authorizationUrl && {
+              authorizationUrl: status.authorizationUrl,
+            }),
+          ...(status.message && { message: status.message }),
+        };
+      };
+      const settled = await mapSettledWithConcurrency(
+        connectors,
+        discoveryConcurrency,
+        inspect,
       );
-      if (!probe) {
-        return jsonResult({ connectors: await Promise.all(pending) });
+      if (probe) {
+        await mapSettledWithConcurrency(
+          connectors,
+          discoveryConcurrency,
+          (connector) =>
+            closeConnectorScope(
+              connector,
+              registry.contextFor(connector.id, baseUrl, scope),
+              opts.defer,
+            ),
+        );
       }
-      const settled = await Promise.allSettled(pending);
-      await Promise.all(
-        connectors.map((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;
@@ -1117,235 +866,31 @@ export function createMetaTools(
     },
 
     async searchTools(args: SearchArgs): Promise<ToolResult> {
-      const q = args.query ?? "";
-      let limit: number;
       try {
-        limit = discoverySearchLimit(args.limit);
+        return discoveryResult(
+          groupedSearchResult(await catalog.search(args)),
+          "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+        );
       } catch (err) {
         if (err instanceof DiscoveryPolicyError) {
           return discoveryErrorResult(err);
         }
         throw err;
       }
-      const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-      const conns = args.connector
-        ? [registry.getConnector(args.connector)].filter(
-            (c): c is NonNullable<typeof c> => Boolean(c),
-          )
-        : registry.listConnectors();
-      const matches: Array<{
-        connectorId: string;
-        connectorTitle?: string;
-        connectorDescription?: string;
-        connectorGuideSkill?: string;
-        tool: ToolDef;
-        score: number;
-        order: number;
-      }> = [];
-      const catalogs = await Promise.allSettled(
-        conns.map((c) =>
-          withProbeDeadline(
-            `search_tools probe of "${c.id}"`,
-            (options) =>
-              registry.getTools(c.id, baseUrl, requestScope, options),
-          ),
-        ),
-      );
-      let matchMode: "all" | "partial" = "all";
-      const collectMatches = (mode: "all" | "partial") => {
-        matches.length = 0;
-        let orderBase = 0;
-        catalogs.forEach((catalog, connectorIndex) => {
-          const c = conns[connectorIndex];
-          if (catalog.status === "fulfilled") {
-            for (const ranked of rankTools(catalog.value, q, mode)) {
-              matches.push({
-                connectorId: c.id,
-                connectorTitle: c.title,
-                connectorDescription: c.description,
-                ...(connectorGuide(c)
-                  ? { connectorGuideSkill: connectorSkillName(c.id) }
-                  : {}),
-                tool: ranked.tool,
-                score: ranked.score,
-                order: orderBase + ranked.order,
-              });
-            }
-          }
-          orderBase +=
-            catalog.status === "fulfilled" ? catalog.value.length : 1;
-        });
-      };
-      collectMatches("all");
-      if (q.trim() && matches.length === 0) {
-        matchMode = "partial";
-        collectMatches(matchMode);
-      }
-      matches.sort((a, b) => b.score - a.score || a.order - b.order);
-      const page = matches.slice(offset, offset + limit);
-      const groups: {
-        id: string;
-        title?: string;
-        description?: string;
-        /** Skill name of this connector's usage guide, when it has one. */
-        guide?: string;
-        tools: Array<{
-          name: string;
-          address: string;
-          description?: string;
-          inputSchema?: unknown;
-          outputSchema?: unknown;
-          annotations?: ToolDef["annotations"];
-        }>;
-      }[] = [];
-      const byConnector = new Map<string, (typeof groups)[number]>();
-      for (const match of page) {
-        let group = byConnector.get(match.connectorId);
-        if (!group) {
-          group = {
-            id: match.connectorId,
-            ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
-            description: match.connectorDescription,
-            ...(match.connectorGuideSkill
-              ? { guide: match.connectorGuideSkill }
-              : {}),
-            tools: [],
-          };
-          byConnector.set(match.connectorId, group);
-          groups.push(group);
-        }
-        const schema = match.tool.inputSchema ?? { type: "object" };
-        group.tools.push({
-          name: match.tool.name,
-          address: `${match.connectorId}.${match.tool.name}`,
-          description: summarizeDescription(
-            match.tool.description,
-            args.fullDescriptions === true,
-          ),
-          ...(args.includeSchemas
-            ? {
-                inputSchema:
-                  args.includeSchemas === "json"
-                    ? schema
-                    : compactSchema(schema),
-              }
-            : {}),
-          ...(args.includeSchemas && match.tool.outputSchema
-            ? {
-                outputSchema:
-                  args.includeSchemas === "json"
-                    ? match.tool.outputSchema
-                    : compactSchema(match.tool.outputSchema),
-              }
-            : {}),
-          ...(match.tool.annotations
-            ? { annotations: match.tool.annotations }
-            : {}),
-        });
-      }
-      const nextOffset =
-        offset + page.length < matches.length
-          ? offset + page.length
-          : undefined;
-      return discoveryResult(
-        {
-          connectors: groups,
-          total: matches.length,
-          offset,
-          limit,
-          hasMore: nextOffset !== undefined,
-          ...(nextOffset !== undefined ? { nextOffset } : {}),
-          ...(matchMode === "partial" && matches.length > 0
-            ? { matchMode }
-            : {}),
-        },
-        "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
-      );
     },
 
     async describeTools(args: DescribeArgs): Promise<ToolResult> {
       try {
-        discoveryAddresses(args.addresses);
+        return discoveryResult(
+          { tools: await catalog.describe(args) },
+          'Split the address list or use format: "compact".',
+        );
       } catch (err) {
         if (err instanceof DiscoveryPolicyError) {
           return discoveryErrorResult(err);
         }
         throw err;
       }
-      const format = args.format ?? "compact";
-      const resolved = args.addresses.map((address) => ({
-        address,
-        resolved: registry.resolveAddress(address),
-      }));
-      const connectorIds = [
-        ...new Set(
-          resolved
-            .map((entry) => entry.resolved?.connector.id)
-            .filter((id): id is string => Boolean(id)),
-        ),
-      ];
-      const loaded = await Promise.allSettled(
-        connectorIds.map((id) =>
-          withProbeDeadline(
-            `describe_tools probe of "${id}"`,
-            (options) =>
-              registry.getTools(id, baseUrl, requestScope, options),
-          ),
-        ),
-      );
-      const catalogs = new Map<string, ToolDef[] | Error>();
-      loaded.forEach((result, index) => {
-        catalogs.set(
-          connectorIds[index],
-          result.status === "fulfilled"
-            ? result.value
-            : result.reason instanceof Error
-              ? result.reason
-              : new Error(String(result.reason)),
-        );
-      });
-      const out = resolved.map(({ address, resolved }) => {
-        if (!resolved) {
-          return { address, error: `Unknown address "${address}"` };
-        }
-        const catalog = catalogs.get(resolved.connector.id);
-        if (catalog instanceof Error) {
-          return { address, error: catalog.message };
-        }
-        const tool = catalog?.find((t) => t.name === resolved.toolName);
-        if (!tool) {
-          return {
-            address,
-            error: `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-          };
-        }
-        const schema = tool.inputSchema ?? { type: "object" };
-        return {
-          address,
-          name: tool.name,
-          description: summarizeDescription(
-            tool.description,
-            args.fullDescriptions === true,
-          ),
-          ...(connectorGuide(resolved.connector)
-            ? { guide: connectorSkillName(resolved.connector.id) }
-            : {}),
-          inputSchema: format === "json" ? schema : compactSchema(schema),
-          ...(tool.outputSchema
-            ? {
-                outputSchema:
-                  format === "json"
-                    ? tool.outputSchema
-                    : compactSchema(tool.outputSchema),
-              }
-            : {}),
-          ...(tool.annotations ? { annotations: tool.annotations } : {}),
-        };
-      });
-      return discoveryResult(
-        { tools: out },
-        'Split the address list or use format: "compact".',
-      );
     },
 
     async callTool(args: CallArgs): Promise<ToolResult> {
@@ -1424,17 +969,29 @@ export function createMetaTools(
           runCall(
             {
               ...c,
-              resultMode: c.resultMode ?? args.resultMode,
-              timeoutMs: c.timeoutMs ?? args.timeoutMs,
-              maxRetries: c.maxRetries ?? args.maxRetries,
-              diagnostics: c.diagnostics ?? args.diagnostics,
+              ...((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 address = args.calls[i].address;
+        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,
@@ -1452,19 +1009,19 @@ export function createMetaTools(
             errorDetails: r.error,
             durationMs: r.durationMs,
             attempts: r.attempts,
-            ...((args.calls[i].diagnostics ?? args.diagnostics)
+            ...((call.diagnostics ?? args.diagnostics)
               ? { timing: r.timing }
               : {}),
           };
         }
-        if ((args.calls[i].resultMode ?? args.resultMode) === "value") {
+        if ((call.resultMode ?? args.resultMode) === "value") {
           return {
             address,
             ok: true,
             data: r.value,
             durationMs: r.durationMs,
             attempts: r.attempts,
-            ...((args.calls[i].diagnostics ?? args.diagnostics)
+            ...((call.diagnostics ?? args.diagnostics)
               ? { timing: r.timing }
               : {}),
           };
@@ -1475,7 +1032,7 @@ export function createMetaTools(
           result: r.toolResult.content,
           durationMs: r.durationMs,
           attempts: r.attempts,
-          ...((args.calls[i].diagnostics ?? args.diagnostics)
+          ...((call.diagnostics ?? args.diagnostics)
             ? { timing: r.timing }
             : {}),
         };
@@ -1539,7 +1096,10 @@ export function createMetaTools(
       }
       const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
       try {
-        const status = await connector.startAuth(ctx, { force: args.force });
+        const status = await connector.startAuth(
+          ctx,
+          args.force !== undefined ? { force: args.force } : {},
+        );
         // startAuth just spoke to the downstream about this exact credential, so
         // its answer replaces any older liveness verdict — including the stale
         // `auth_required` that sent the agent here, once it reports ok.
@@ -1656,15 +1216,27 @@ export function registerMetaTools(
     baseUrl: string;
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
+    discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
+    requestSignal?: AbortSignal;
     defer?: DeferredWork;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
-    defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
-    probeTimeoutMs: ctx.probeTimeoutMs,
-    activity: ctx.activity,
-    defer: ctx.defer,
+    ...(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 } : {}),
   });
 
   server.registerTool(