@zackbart/connecta 0.10.5 → 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",
@@ -72,7 +96,10 @@ function discoverySearchLimit(value: unknown): number {
 }
 
 /** Normalize the single-address convenience form, then validate the bounded list. */
-function discoveryAddresses(args: CatalogDescribeArgs): unknown[] {
+function discoveryAddresses(
+  args: CatalogDescribeArgs,
+  describeRoute: DescribeRoute,
+): unknown[] {
   if (args.address !== undefined && args.addresses !== undefined) {
     throw new DiscoveryPolicyError(
       "invalid_args",
@@ -94,12 +121,26 @@ function discoveryAddresses(args: CatalogDescribeArgs): unknown[] {
   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);
@@ -286,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[]>>();
 
@@ -296,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(
@@ -345,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,
       };
     }
@@ -370,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,
@@ -405,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,
       };
     }
@@ -432,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,
@@ -449,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,
@@ -486,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}"`,
@@ -704,7 +817,7 @@ export class CatalogService {
   }
 
   async describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]> {
-    const addresses = discoveryAddresses(args);
+    const addresses = discoveryAddresses(args, this.describeRoute);
     const format = args.format ?? "compact";
     const resolved = addresses.map((rawAddress) => {
       const address = String(rawAddress);
@@ -721,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;