@zackbart/connecta 0.7.7 → 0.7.8

package/src/index.ts

@@ -94,7 +94,7 @@ export interface ConnectaDiscoveryConfig {
   probeTimeoutMs?: number;
 }
 
-/** Deployment-wide call deadlines and inline-result paging threshold. */
+/** Deployment-wide call deadlines and inline-result paging thresholds. */
 export interface ConnectaCallsConfig {
   /**
    * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
@@ -111,6 +111,13 @@ export interface ConnectaCallsConfig {
    * 50_000. Connectors may override it individually.
    */
   maxResultBytes?: number;
+  /**
+   * Max serialized `batch_call` envelope size (bytes) before the full batch is
+   * stashed for `get_result` and only an ordered outcome summary is returned
+   * inline. Must be a finite whole number >= 1; invalid values warn and fall
+   * back to 100_000. This cap is independent of per-connector child caps.
+   */
+  maxBatchResultBytes?: number;
 }
 
 export interface AdmissionPoolConfig {
@@ -544,6 +551,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     persistToolCatalog: config.discovery?.persistCatalog,
     toolCatalogStaleSeconds: config.discovery?.staleCatalogSeconds,
     maxResultBytes: config.calls?.maxResultBytes,
+    maxBatchResultBytes: config.calls?.maxBatchResultBytes,
     credentialHealth: config.credentials?.health,
   });
   // Throws on every structural mistake it can see (see resolveToolkits): a

package/src/meta-tools.ts

@@ -406,6 +406,15 @@ async function stashResult(
   };
 }
 
+/** Keep an oversized batch's inline outcome summary at fixed string overhead. */
+function batchSummaryString(value: string): string {
+  const bytes = enc.encode(value);
+  const maxBytes = 512;
+  if (bytes.length <= maxBytes) return value;
+  const end = alignEndToCharBoundary(bytes, 0, maxBytes, bytes.length);
+  return `${dec.decode(bytes.slice(0, end))}…`;
+}
+
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
  * full text and return the first `cap` bytes followed by a JSON truncation
@@ -575,10 +584,10 @@ export interface SkillArgs {
  * supplies a deadline for calls that don't carry one. (execute_code, the
  * optional tenth tool, is registered separately by registerExecuteTool.)
  *
- * The deployment-wide result-size cap is read off the registry view rather than
- * passed in: `ConnectaConfig.calls.maxResultBytes` and the per-connector
- * override are the only places a cap is set, so there is one answer to where a
- * deployment sets it (issue #44).
+ * Deployment-wide result-size caps are read off the registry view rather than
+ * passed in: `ConnectaConfig.calls.maxResultBytes`, its per-connector override,
+ * and the independent `calls.maxBatchResultBytes` final-envelope boundary each
+ * have one runtime source of truth.
  */
 export function createMetaTools(
   registry: RegistryView,
@@ -595,6 +604,7 @@ export function createMetaTools(
 ) {
   // Already normalized and warned about at registry construction.
   const globalCap = registry.maxResultBytes;
+  const batchCap = registry.maxBatchResultBytes;
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -1141,26 +1151,36 @@ export function createMetaTools(
           ),
         ),
       );
-      let orderBase = 0;
-      catalogs.forEach((catalog, connectorIndex) => {
-        const c = conns[connectorIndex];
-        if (catalog.status === "fulfilled") {
-          for (const ranked of rankTools(catalog.value, q)) {
-            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,
-            });
+      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;
-      });
+          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: {
@@ -1235,6 +1255,9 @@ export function createMetaTools(
           limit,
           hasMore: nextOffset !== undefined,
           ...(nextOffset !== undefined ? { nextOffset } : {}),
+          ...(matchMode === "partial" && matches.length > 0
+            ? { matchMode }
+            : {}),
         },
         "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
       );
@@ -1457,9 +1480,50 @@ export function createMetaTools(
             : {}),
         };
       });
-      return jsonResult({
+      const envelope = {
         results,
         durationMs: Date.now() - batchStarted,
+      };
+      const text = serializeResultText(envelope);
+      const bytes = enc.encode(text);
+      if (bytes.length <= batchCap) return jsonResult(envelope);
+
+      const notice = await stashResult(
+        text,
+        registry.resultsStorage(),
+        bytes.length,
+      );
+      return jsonResult({
+        results: results.map((result) => {
+          const common = {
+            address: batchSummaryString(result.address),
+            ok: !("error" in result),
+            ...("durationMs" in result
+              ? { durationMs: result.durationMs }
+              : {}),
+            ...("attempts" in result ? { attempts: result.attempts } : {}),
+            ...("timing" in result ? { timing: result.timing } : {}),
+          };
+          if (!("error" in result)) return common;
+          const error = result.error ?? "Batch call failed";
+          const details =
+            result.errorDetails ??
+            errorDetails("batch_call_failed", error);
+          return {
+            ...common,
+            error: batchSummaryString(error),
+            errorDetails: {
+              code: batchSummaryString(details.code),
+              message: batchSummaryString(details.message),
+              retryable: details.retryable,
+              ...(details.retryAfterMs !== undefined
+                ? { retryAfterMs: details.retryAfterMs }
+                : {}),
+            },
+          };
+        }),
+        durationMs: envelope.durationMs,
+        ...notice,
       });
     },
 
@@ -1527,7 +1591,7 @@ const CALL_DESTRUCTIVE_DESC =
 const GET_RESULT_DESC =
   "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
 const BATCH_DESC =
-  "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call.";
+  "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call. An oversized final envelope returns ordered outcome summaries plus a get_result page handle.";
 const AUTHORIZE_DESC =
   "Use after a connector reports auth_required. Starts downstream OAuth and returns an authorizationUrl for the operator to open. force=true wipes stored credentials first and restarts consent.";
 const SKILLS_DESC =

package/src/registry.ts

@@ -25,6 +25,8 @@ const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
 export const DEFAULT_MAX_RESULT_BYTES = 50_000;
+/** Independent final-envelope boundary for `batch_call`. */
+export const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
 
 /**
  * Smallest accepted inline-result cap. One byte is pathological but harmless:
@@ -143,6 +145,11 @@ export interface RegistryOptions {
    * to the default 50_000.
    */
   maxResultBytes?: number;
+  /**
+   * Cap on the complete serialized batch_call envelope. Must be a whole number
+   * of bytes >= 1; anything else warns and falls back to 100_000.
+   */
+  maxBatchResultBytes?: number;
   /** Tuning for the credential liveness checks (issue #24). */
   credentialHealth?: CredentialHealthConfig;
 }
@@ -179,6 +186,8 @@ type ConnectorOperationOptions = Pick<
 export interface RegistryView {
   /** Deployment-wide result-size cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
+  /** Independent cap for the complete serialized batch_call envelope. */
+  readonly maxBatchResultBytes: number;
   listConnectors(): Connector[];
   getConnector(id: string): Connector | undefined;
   resolveAddress(
@@ -246,6 +255,8 @@ export class Registry implements RegistryView {
   private readonly persistToolCatalog: boolean;
   /** Result-size guard cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
+  /** Final batch envelope cap threaded to the meta-tools. */
+  readonly maxBatchResultBytes: number;
   /** Proactive liveness checks over stored downstream credentials (issue #24). */
   private readonly credentialHealth: CredentialHealthChecker;
 
@@ -262,6 +273,10 @@ export class Registry implements RegistryView {
       opts.maxResultBytes,
       DEFAULT_MAX_RESULT_BYTES,
     );
+    this.maxBatchResultBytes = resolveMaxResultBytes(
+      opts.maxBatchResultBytes,
+      DEFAULT_MAX_BATCH_RESULT_BYTES,
+    );
     for (const c of connectors) {
       if (!ID_RE.test(c.id)) {
         throw new Error(
@@ -274,7 +289,11 @@ export class Registry implements RegistryView {
       this.connectors.set(c.id, c);
     }
     this.checkConventions(opts.logger);
-    this.checkResultCaps(opts.logger, opts.maxResultBytes);
+    this.checkResultCaps(
+      opts.logger,
+      opts.maxResultBytes,
+      opts.maxBatchResultBytes,
+    );
     this.credentialHealth = new CredentialHealthChecker(
       {
         listConnectors: () => this.listConnectors(),
@@ -300,6 +319,7 @@ export class Registry implements RegistryView {
   private checkResultCaps(
     logger: Logger,
     configured: number | undefined,
+    configuredBatch: number | undefined,
   ): void {
     if (configured !== undefined && !isValidMaxResultBytes(configured)) {
       logger.warn(
@@ -309,6 +329,17 @@ export class Registry implements RegistryView {
           `default ${DEFAULT_MAX_RESULT_BYTES} instead.`,
       );
     }
+    if (
+      configuredBatch !== undefined &&
+      !isValidMaxResultBytes(configuredBatch)
+    ) {
+      logger.warn(
+        `[connecta] calls.maxBatchResultBytes ${configuredBatch} is not a whole ` +
+          `number of bytes >= ${MIN_MAX_RESULT_BYTES}: it would leave the final ` +
+          "batch envelope unbounded or serve an unusable page. Using the " +
+          `default ${DEFAULT_MAX_BATCH_RESULT_BYTES} instead.`,
+      );
+    }
     for (const c of this.connectors.values()) {
       if (
         c.maxResultBytes !== undefined &&
@@ -831,6 +862,10 @@ export class ScopedRegistry implements RegistryView {
     return this.base.maxResultBytes;
   }
 
+  get maxBatchResultBytes(): number {
+    return this.base.maxBatchResultBytes;
+  }
+
   /** In scope AND actually registered. */
   private visible(id: string): boolean {
     return (

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.7.7";
+export const CONNECTA_VERSION = "0.7.8";