@zackbart/connecta 0.10.4 → 0.10.6

package/src/catalog-service.ts

@@ -13,7 +13,11 @@ import {
   mapSettledWithConcurrency,
   resolveDiscoveryConcurrency,
 } from "./concurrency.js";
-import { classifyCallError, framingError } from "./errors.js";
+import {
+  boundedEchoText,
+  classifyCallError,
+  framingError,
+} from "./errors.js";
 import type { CallErrorDetails } from "./errors.js";
 import type {
   ConnectorOperationOptions,
@@ -44,6 +48,26 @@ const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
+/**
+ * The tool a describe-path error should name when it tells a caller to retry.
+ * This is the route the *caller* took, not the deployment's advertised surface:
+ * a classic deployment with an executor serves `describe_tools` at top level
+ * while every in-program describe still arrives through `connecta.describe`, so
+ * one CatalogService cannot infer the answer from `surface` alone. Callers pass
+ * the route they own.
+ */
+export type DescribeRoute = "describe_tools" | "connecta.describe";
+
+/**
+ * The discovery route a routing failure should send a caller back through. Same
+ * rule as {@link DescribeRoute} — the route the *caller* took, not the
+ * deployment's advertised surface — with one difference worth keeping the two
+ * options separate for: `search_tools` exists on both advertised surfaces, so a
+ * top-level handler never has to derive this one, while an in-program caller
+ * still has to be told about `connecta.search` because it cannot call a tool.
+ */
+export type SearchRoute = "search_tools" | "connecta.search";
+
 export class DiscoveryPolicyError extends Error {
   constructor(
     readonly code: "invalid_args" | "result_too_large",
@@ -71,23 +95,52 @@ function discoverySearchLimit(value: unknown): number {
   return value;
 }
 
-/** Validate the raw list so duplicate addresses consume the same bound. */
-function discoveryAddresses(value: unknown): unknown[] {
+/** Normalize the single-address convenience form, then validate the bounded list. */
+function discoveryAddresses(
+  args: CatalogDescribeArgs,
+  describeRoute: DescribeRoute,
+): unknown[] {
+  if (args.address !== undefined && args.addresses !== undefined) {
+    throw new DiscoveryPolicyError(
+      "invalid_args",
+      "describe takes either address or addresses, not both.",
+    );
+  }
+  const value =
+    args.address !== undefined
+      ? typeof args.address === "string"
+        ? [args.address]
+        : undefined
+      : args.addresses;
   if (!Array.isArray(value)) {
     throw new DiscoveryPolicyError(
       "invalid_args",
-      'describe takes { addresses: ["<connectorId>.<toolName>", ...] }; addresses must be an array.',
+      'describe takes { address: "<connectorId>.<toolName>" } or { addresses: ["<connectorId>.<toolName>", ...] }.',
     );
   }
   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.`,
+      `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across ${describeRoute} calls.`,
     );
   }
   return value;
 }
 
+/**
+ * Search terms derived from an address the catalog could not resolve. Bounded
+ * because the address is entirely caller-authored: an invented one can be any
+ * length, and this string is copied into a recovery record that is itself
+ * copied into both halves of the result envelope.
+ */
+function recoveryQuery(address: string): string {
+  const separator = address.indexOf(".");
+  const candidate = separator >= 0 ? address.slice(separator + 1) : address;
+  return boundedEchoText(
+    candidate.replaceAll(/[._-]+/g, " ").trim() || address,
+  );
+}
+
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value: unknown, hint: string): string {
   const text = JSON.stringify(value);
@@ -150,6 +203,7 @@ function toolsForSafety(
 }
 
 export interface CatalogDescribeArgs {
+  address?: unknown;
   addresses?: unknown;
   format?: "compact" | "json";
   fullDescriptions?: boolean;
@@ -273,6 +327,8 @@ export class CatalogService {
   readonly requestScope: object;
   private readonly probeTimeoutMs: number;
   private readonly concurrency: number;
+  private readonly describeRoute: DescribeRoute;
+  private readonly searchRoute: SearchRoute;
   private readonly loaded = new Map<string, ToolDef[]>();
   private readonly loading = new Map<string, Promise<ToolDef[]>>();
 
@@ -283,12 +339,43 @@ export class CatalogService {
       requestScope?: object;
       probeTimeoutMs?: number;
       concurrency?: number;
+      /** The tool describe-path errors name. Default `describe_tools`. */
+      describeRoute?: DescribeRoute;
+      /** The discovery route recovery records name. Default `search_tools`. */
+      searchRoute?: SearchRoute;
     } = {},
   ) {
     this.requestScope = options.requestScope ?? {};
     this.probeTimeoutMs =
       normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
     this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
+    this.describeRoute = options.describeRoute ?? "describe_tools";
+    this.searchRoute = options.searchRoute ?? "search_tools";
+  }
+
+  /**
+   * Send a caller back to discovery through the surface it can actually reach.
+   * Both variants carry the same scoping arguments because `connecta.search`
+   * takes the same ones `search_tools` does; only the key naming the callable
+   * differs, the way the ambiguous-alias record already names a function.
+   *
+   * Not private: `InvocationService` builds the same class of record when a
+   * call fails schema validation, and it is this catalog's route that decides
+   * which key that record carries. Duplicating the branch there would let the
+   * two drift.
+   */
+  searchRecovery(
+    args: { query: string; connector?: string },
+    purpose: string,
+  ): NonNullable<CallErrorDetails["nextAction"]> {
+    const searchArgs = {
+      query: args.query,
+      ...(args.connector !== undefined ? { connector: args.connector } : {}),
+      includeSchemas: "compact" as const,
+    };
+    return this.searchRoute === "connecta.search"
+      ? { function: "connecta.search", arguments: searchArgs, purpose }
+      : { tool: "search_tools", arguments: searchArgs, purpose };
   }
 
   async loadConnector(
@@ -332,10 +419,16 @@ export class CatalogService {
     if (!resolved) {
       return {
         ok: false,
-        error: framingError(
-          "unknown_address",
-          `Unknown address "${address}"`,
-        ),
+        error: {
+          ...framingError(
+            "unknown_address",
+            `Unknown address "${boundedEchoText(address)}"`,
+          ),
+          nextAction: this.searchRecovery(
+            { query: recoveryQuery(address) },
+            "Find the configured canonical address before retrying.",
+          ),
+        },
         catalogMs: 0,
       };
     }
@@ -357,10 +450,19 @@ export class CatalogService {
     if (!definition) {
       return {
         ok: false,
-        error: framingError(
-          "unknown_tool",
-          `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-        ),
+        error: {
+          ...framingError(
+            "unknown_tool",
+            `Unknown tool "${boundedEchoText(resolved.toolName)}" on connector "${resolved.connector.id}"`,
+          ),
+          nextAction: this.searchRecovery(
+            {
+              query: recoveryQuery(resolved.toolName),
+              connector: resolved.connector.id,
+            },
+            "Find the connector's current canonical tool address.",
+          ),
+        },
         catalogMs: Date.now() - started,
         connector: resolved.connector,
         toolName: resolved.toolName,
@@ -392,10 +494,16 @@ export class CatalogService {
     if (!connector) {
       return {
         ok: false,
-        error: framingError(
-          "unknown_address",
-          `Unknown address "${connectorId}.${alias}"`,
-        ),
+        error: {
+          ...framingError(
+            "unknown_address",
+            `Unknown address "${boundedEchoText(`${connectorId}.${alias}`)}"`,
+          ),
+          nextAction: this.searchRecovery(
+            { query: recoveryQuery(alias) },
+            "Find the configured canonical address before retrying.",
+          ),
+        },
         catalogMs: 0,
       };
     }
@@ -419,10 +527,16 @@ export class CatalogService {
     if (!definition) {
       return {
         ok: false,
-        error: framingError(
-          "unknown_tool",
-          `Unknown tool "${alias}" on connector "${connector.id}"`,
-        ),
+        error: {
+          ...framingError(
+            "unknown_tool",
+            `Unknown tool "${boundedEchoText(alias)}" on connector "${connector.id}"`,
+          ),
+          nextAction: this.searchRecovery(
+            { query: recoveryQuery(alias), connector: connector.id },
+            "Find the connector's current canonical tool address.",
+          ),
+        },
         catalogMs: Date.now() - started,
         connector,
         toolName: alias,
@@ -436,8 +550,16 @@ export class CatalogService {
         ok: false,
         error: {
           code: "ambiguous_tool_alias",
-          message: `Tool alias "${alias}" is ambiguous on connector "${connector.id}" because ${names} sanitize to the same name. Use connecta.call with an exact address.`,
+          message: `Tool alias "${boundedEchoText(alias)}" is ambiguous on connector "${connector.id}" because ${names} sanitize to the same name. Use connecta.call with an exact address.`,
           retryable: false,
+          nextAction: {
+            function: "connecta.call",
+            addresses: [definition, ...collisions].map(
+              (tool) => `${connector.id}.${tool.name}`,
+            ),
+            purpose:
+              "Choose the intended canonical address and call it with the original arguments.",
+          },
         },
         catalogMs: Date.now() - started,
         connector,
@@ -473,6 +595,10 @@ export class CatalogService {
       connectors,
       this.concurrency,
       (connector) =>
+        // Unlike the describe path, this label never reaches a caller: search
+        // only counts rejected catalogs (`unavailableCatalogs` below) and
+        // renders its own guidance, so the folded name here stays internal and
+        // needs no surface awareness.
         this.loadForDiscovery(
           connector.id,
           `search_tools probe of "${connector.id}"`,
@@ -542,6 +668,10 @@ export class CatalogService {
         args.includeSchemas && match.tool.outputSchema
           ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
           : undefined;
+      const schemaKeys =
+        args.includeSchemas && args.includeSchemaKeys
+          ? schemaKeyMetadata(input, match.tool.outputSchema)
+          : undefined;
       const description = summarizeDiscoveryDescription(
         match.tool.description,
         args.fullDescriptions === true,
@@ -571,8 +701,18 @@ export class CatalogService {
           ...(renderedOutput?.truncated
             ? { outputSchemaTruncated: true as const }
             : {}),
-          ...(args.includeSchemas && args.includeSchemaKeys
-            ? schemaKeyMetadata(input, match.tool.outputSchema)
+          ...(schemaKeys && !renderedInput?.truncated
+            ? {
+                ...(schemaKeys.inputKeys
+                  ? { inputKeys: schemaKeys.inputKeys }
+                  : {}),
+                ...(schemaKeys.requiredInputKeys
+                  ? { requiredInputKeys: schemaKeys.requiredInputKeys }
+                  : {}),
+              }
+            : {}),
+          ...(schemaKeys?.outputKeys && !renderedOutput?.truncated
+            ? { outputKeys: schemaKeys.outputKeys }
             : {}),
           ...(match.tool.annotations
             ? { annotations: match.tool.annotations }
@@ -677,7 +817,7 @@ export class CatalogService {
   }
 
   async describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]> {
-    const addresses = discoveryAddresses(args.addresses);
+    const addresses = discoveryAddresses(args, this.describeRoute);
     const format = args.format ?? "compact";
     const resolved = addresses.map((rawAddress) => {
       const address = String(rawAddress);
@@ -694,7 +834,7 @@ export class CatalogService {
       connectorIds,
       this.concurrency,
       (id) =>
-        this.loadForDiscovery(id, `describe_tools probe of "${id}"`),
+        this.loadForDiscovery(id, `${this.describeRoute} probe of "${id}"`),
     );
     const catalogs = new Map<string, ToolDef[] | Error>();
     loaded.forEach((result, index) => {

package/src/errors.ts

@@ -43,6 +43,76 @@ function boundedIssueText(
   };
 }
 
+/**
+ * How many bytes of the caller's own arguments an error envelope will echo
+ * back to it. Small on purpose: an error result is not size-guarded the way a
+ * *result* is, so an unbounded echo turns a 50 KB argument object into a 100 KB
+ * refusal against a deployment that capped results at 1 KB — twice over, since
+ * the payload lands in both the text content and `structuredContent`. The agent
+ * already holds what it sent; the echo is a convenience, never the record.
+ */
+const MAX_ECHOED_ARGS_BYTES = 512;
+
+/**
+ * The same budget spent on caller-authored *text* — the address it mistyped,
+ * the discovery query derived from it — rather than on its arguments.
+ *
+ * Text is clamped where {@link echoedCallArgs} drops: an address is the thing
+ * the refusal exists to correct, so a refusal that named nothing would be
+ * useless, while a clipped one still carries the prefix that identifies the
+ * mistake. The marker says it was clipped, so nothing reads a clamped address
+ * as the address that was sent. Arguments get the opposite rule because they
+ * end at a human approving one specific call.
+ *
+ * The number is not cosmetic. An error result is not size-guarded the way a
+ * result is, and every echoed byte lands twice (text content *and*
+ * `structuredContent`), so an unbounded address turned a 50 KB typo into a
+ * 200 KB refusal against a deployment that capped results at 1 KB.
+ */
+const MAX_ECHOED_TEXT_BYTES = 512;
+
+const echoEncoder = new TextEncoder();
+const echoDecoder = new TextDecoder();
+
+/**
+ * Clamp a string to a UTF-8 byte budget, appending `…` when it clipped.
+ * Short strings — the common case, and the one that has to stay exact — are
+ * returned unchanged and untagged.
+ */
+export function boundedEchoText(
+  value: string,
+  maxBytes: number = MAX_ECHOED_TEXT_BYTES,
+): string {
+  const bytes = echoEncoder.encode(value);
+  if (bytes.length <= maxBytes) return value;
+  // Never split a codepoint: walk back off UTF-8 continuation bytes (10xxxxxx)
+  // so the clamp cannot manufacture a replacement character.
+  let end = Math.max(0, maxBytes);
+  while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
+  return `${echoDecoder.decode(bytes.slice(0, end))}…`;
+}
+
+/**
+ * `{ args }` when the caller's arguments fit {@link MAX_ECHOED_ARGS_BYTES},
+ * `{}` when they do not. All or nothing: a clipped echo would be a *different*
+ * call than the one that was refused, and the routes this feeds end at a human
+ * approving one. Unserializable arguments are treated the same way as oversized
+ * ones — there is nothing honest to put in the field.
+ */
+export function echoedCallArgs(args: unknown): { args?: unknown } {
+  if (args === undefined) return {};
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(args);
+  } catch {
+    return {};
+  }
+  if (text === undefined) return {};
+  return echoEncoder.encode(text).length <= MAX_ECHOED_ARGS_BYTES
+    ? { args }
+    : {};
+}
+
 function boundedValidation(
   details: ArgumentValidationDetails | undefined,
 ): ArgumentValidationDetails | undefined {
@@ -179,10 +249,41 @@ export interface CallErrorDetails {
     tool: "search_tools";
     arguments: {
       query: string;
-      connector: string;
+      connector?: string;
       includeSchemas: "compact";
     };
     purpose: string;
+  } | {
+    tool: "call_destructive_tool";
+    arguments: {
+      address: string;
+      /**
+       * The caller's own arguments, echoed only when they fit
+       * {@link MAX_ECHOED_ARGS_BYTES} — and then whole, never clipped. Absent
+       * means "re-send exactly what you sent": a half-copied argument object
+       * routed into a human approval prompt would describe a call nobody made.
+       */
+      args?: unknown;
+    };
+    purpose: string;
+  } | {
+    /**
+     * The same scoped discovery as the `search_tools` route above, addressed to
+     * a caller inside `execute_code`, which cannot call a tool. Which of the two
+     * a routing failure emits follows the route the caller took, not the
+     * deployment's advertised surface.
+     */
+    function: "connecta.search";
+    arguments: {
+      query: string;
+      connector?: string;
+      includeSchemas: "compact";
+    };
+    purpose: string;
+  } | {
+    function: "connecta.call";
+    addresses: string[];
+    purpose: string;
   };
   /** Explicit retry guidance; recovery never retries or mutates by itself. */
   retry?: string;