@zackbart/connecta 0.10.5 → 0.11.0

package/src/activity.ts

@@ -1,8 +1,33 @@
+import { boundedEchoText } from "./errors.js";
 import type { Logger } from "./types.js";
 
+/**
+ * How long an identity field may be before the store stops believing it.
+ *
+ * `connectorId` and `toolName` are ordinarily operator- and connector-authored,
+ * and 128 bytes is far past any real one. But an address that resolved to
+ * nothing is recorded *as written*, which puts a caller-authored string in both
+ * fields — and "payload-free by construction" has to mean the event type has
+ * nowhere to put a payload, not merely that connecta declines to. A 40 KB
+ * invented connector id is a payload wearing an id's clothing.
+ *
+ * Clamped rather than dropped: the invented id is precisely what an operator
+ * needs to see, and its first 128 bytes identify the mistake as well as all
+ * 40,000 would. The `…` marker keeps a clamped value from reading as a real one.
+ */
+const MAX_ACTIVITY_NAME_BYTES = 128;
+
+/** Two names and the dot between them. */
+const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
+
 export type ActivityCallSource =
   | "call_tool"
   | "call_destructive_tool"
+  // Read-only history. Nothing emits `batch_call` since issue #273 removed the
+  // tool, but activity storage is append-only: rows written by older
+  // deployments are still read back — the D1 example maps a stored row straight
+  // into this type — and an operator's timeline should not have to lie about
+  // where a call came from. Never widen this member back into a live source.
   | "batch_call"
   | "execute_code";
 
@@ -12,6 +37,35 @@ export type ActivityOutcome =
   | "timeout"
   | "cancelled";
 
+export type AgentFriction =
+  | "tool_not_found"
+  | "schema_retry"
+  | "destructive_reroute"
+  | "auth_required"
+  | "result_too_large";
+
+/** Coarse recovery class derived without inspecting payloads or error prose. */
+export function agentFrictionForCode(
+  code: string | undefined,
+): AgentFriction | undefined {
+  switch (code) {
+    case "unknown_address":
+    case "unknown_tool":
+    case "ambiguous_tool_alias":
+      return "tool_not_found";
+    case "invalid_args":
+      return "schema_retry";
+    case "destructive_tool_requires_approval":
+      return "destructive_reroute";
+    case "auth_required":
+      return "auth_required";
+    case "result_too_large":
+      return "result_too_large";
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Authenticated identity attached to an activity event. `id` is intentionally
  * optional: open deployments and shared bearer tokens cannot honestly identify
@@ -48,7 +102,14 @@ export interface ToolCallActivityEvent {
   outcome: ActivityOutcome;
   durationMs: number;
   attempts: number;
+  /** Set only when the call actually failed; a truncated success has none. */
   errorCode?: string;
+  /**
+   * Payload-free recovery class. Usually derived from `errorCode`, but it can
+   * also stand alone: a result too large to return inline is friction for the
+   * agent while remaining an `outcome: "success"` call with no error code.
+   */
+  friction?: AgentFriction;
   serverName: string;
   serverVersion: string;
   deploymentId?: string;
@@ -121,6 +182,7 @@ export type ActivityEventInput = Pick<
   | "durationMs"
   | "attempts"
   | "errorCode"
+  | "friction"
 >;
 
 /**
@@ -133,20 +195,24 @@ export function recordToolActivity(
   input: ActivityEventInput,
 ): void {
   if (!context) return;
+  // A caller-supplied class wins because it knows something the code table
+  // cannot: friction that belongs to a call which did not fail.
+  const friction = input.friction ?? agentFrictionForCode(input.errorCode);
   const event: ToolCallActivityEvent = {
     schemaVersion: 1,
     id: crypto.randomUUID(),
     occurredAt: new Date().toISOString(),
     requestId: context.requestId,
     actor: context.actor,
-    connectorId: input.connectorId,
-    toolName: input.toolName,
-    address: input.address,
+    connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
+    toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
+    address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
     source: input.source,
     outcome: input.outcome,
     durationMs: Math.max(0, Math.trunc(input.durationMs)),
     attempts: Math.max(1, Math.trunc(input.attempts)),
     ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+    ...(friction ? { friction } : {}),
     serverName: context.serverInfo.name,
     serverVersion: context.serverInfo.version,
     ...(context.deploymentId

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,13 @@ const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
+/**
+ * The discovery route a routing failure should send a caller back through. Same
+ * catalog logic serves both the top-level `search_tools` path and the
+ * in-program `connecta.search` path, so callers pass the route they own.
+ */
+export type SearchRoute = "search_tools" | "connecta.search";
+
 export class DiscoveryPolicyError extends Error {
   constructor(
     readonly code: "invalid_args" | "result_too_large",
@@ -94,12 +105,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 connecta.describe 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 +311,7 @@ export class CatalogService {
   readonly requestScope: object;
   private readonly probeTimeoutMs: number;
   private readonly concurrency: number;
+  private readonly searchRoute: SearchRoute;
   private readonly loaded = new Map<string, ToolDef[]>();
   private readonly loading = new Map<string, Promise<ToolDef[]>>();
 
@@ -296,12 +322,40 @@ export class CatalogService {
       requestScope?: object;
       probeTimeoutMs?: number;
       concurrency?: number;
+      /** 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.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 +399,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 +430,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 +474,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 +507,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 +530,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 +575,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}"`,
@@ -721,7 +814,7 @@ export class CatalogService {
       connectorIds,
       this.concurrency,
       (id) =>
-        this.loadForDiscovery(id, `describe_tools probe of "${id}"`),
+        this.loadForDiscovery(id, `connecta.describe probe of "${id}"`),
     );
     const catalogs = new Map<string, ToolDef[] | Error>();
     loaded.forEach((result, index) => {

package/src/connectors/api.ts

@@ -20,7 +20,7 @@ export interface ApiTool {
   outputSchema?: JsonSchema;
   /**
    * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
-   * admits the tool to call_tool, batch_call, and execute_code.
+   * admits the tool to call_tool and execute_code.
    */
   annotations?: ToolAnnotations;
   handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
@@ -32,7 +32,7 @@ export interface ApiOptions {
   description?: string;
   /**
    * Max inline result size (bytes) for this connector's tools before
-   * call_tool/batch_call truncate and stash the full text for get_result
+   * call_tool truncates and stashes the full text for get_result
    * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
    * it. Must be a whole number of bytes >= 1; anything else warns at startup
    * and is ignored.

package/src/connectors/remote-mcp.ts

@@ -38,7 +38,7 @@ export interface RemoteMcpOptions {
   description?: string;
   /**
    * Max inline result size (bytes) for this connector's tools before
-   * call_tool/batch_call truncate and stash the full text for get_result
+   * call_tool truncates and stashes the full text for get_result
    * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
    * it. Must be a whole number of bytes >= 1; anything else warns at startup
    * and is ignored.

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 {
@@ -151,7 +221,7 @@ export class ConnectorCallError extends Error {
   }
 }
 
-/** The `error` object surfaced in call_tool/batch_call value-mode results. */
+/** The `error` object surfaced in value-mode call results and connecta.batch entries. */
 export interface CallErrorDetails {
   code: string;
   message: string;
@@ -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;
@@ -221,7 +322,7 @@ const RETRYABLE_MESSAGE_RE =
 const TIMEOUT_MESSAGE_RE = /timed out|timeout/i;
 
 /** Message-text fallback used when an error carries no typed classification. */
-export function messageLooksRetryable(message: string): boolean {
+function messageLooksRetryable(message: string): boolean {
   return RETRYABLE_MESSAGE_RE.test(message);
 }