@zackbart/connecta 0.7.0 → 0.7.3

package/src/execute.ts

@@ -3,6 +3,9 @@ import { z } from "zod";
 import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, type ActivityRequestContext } from "./activity.js";
 import {
+  assertDiscoveryResultSize,
+  discoveryAddresses,
+  discoverySearchLimit,
   errorResult,
   jsonResult,
   serializeResultText,
@@ -369,7 +372,7 @@ export async function buildSandboxProviders(
         }
         matches.sort((a, b) => b.score - a.score || a.order - b.order);
         const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-        const limit = Math.max(1, Math.trunc(args.limit ?? 25));
+        const limit = discoverySearchLimit(args.limit);
         const page = matches.slice(offset, offset + limit).map((match) => {
           const input = match.tool.inputSchema ?? { type: "object" };
           return {
@@ -404,7 +407,7 @@ export async function buildSandboxProviders(
           offset + page.length < matches.length
             ? offset + page.length
             : undefined;
-        return {
+        const result = {
           tools: page,
           total: matches.length,
           offset,
@@ -412,6 +415,11 @@ export async function buildSandboxProviders(
           hasMore: nextOffset !== undefined,
           ...(nextOffset !== undefined ? { nextOffset } : {}),
         };
+        assertDiscoveryResultSize(
+          result,
+          "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+        );
+        return result;
       },
       describe: async (raw: unknown) => {
         const args = (raw ?? {}) as {
@@ -419,12 +427,10 @@ export async function buildSandboxProviders(
           format?: "compact" | "json";
           fullDescriptions?: boolean;
         };
-        if (!Array.isArray(args.addresses)) {
-          throw new Error("addresses must be an array");
-        }
+        const addresses = discoveryAddresses(args.addresses);
         const format = args.format ?? "compact";
-        return {
-          tools: args.addresses.map((rawAddress) => {
+        const result = {
+          tools: addresses.map((rawAddress) => {
             const address = String(rawAddress);
             const resolved = registry.resolveAddress(address);
             if (!resolved) {
@@ -457,6 +463,11 @@ export async function buildSandboxProviders(
             };
           }),
         };
+        assertDiscoveryResultSize(
+          result,
+          'Split the address list or use format: "compact".',
+        );
+        return result;
       },
     },
   });

package/src/executors/quickjs.ts

@@ -40,11 +40,39 @@ const MAX_LOG_ENTRIES = 200;
 // keeps the worst case — 200 maxed-out entries — bounded well under a MiB.
 const MAX_LOG_ENTRY_CHARS = 8_000;
 const MAX_LOG_TOTAL_CHARS = 256_000;
+// Keep one host result below the range where quickjs-emscripten@0.32.0 can
+// nondeterministically fail during runtime disposal under concurrent load.
+// This still lets guest code reduce data more than ten times larger than
+// connecta's final response budget.
+const MAX_HOST_RESULT_BYTES = 256 * 1024;
 
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function exceedsUtf8ByteLimit(value: string, limit: number): boolean {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) bytes += 1;
+    else if (code <= 0x7ff) bytes += 2;
+    else if (
+      code >= 0xd800 &&
+      code <= 0xdbff &&
+      index + 1 < value.length &&
+      value.charCodeAt(index + 1) >= 0xdc00 &&
+      value.charCodeAt(index + 1) <= 0xdfff
+    ) {
+      bytes += 4;
+      index += 1;
+    } else {
+      bytes += 3;
+    }
+    if (bytes > limit) return true;
+  }
+  return false;
+}
+
 /** Normalize model output into an async-arrow expression: strip markdown fences, wrap bare bodies. */
 export function normalizeCode(code: string): string {
   let c = code.trim();
@@ -118,6 +146,25 @@ function armWake(bridge: HostBridge): void {
   });
 }
 
+function waitForHostOrDeadline(
+  waitForSettle: Promise<void>,
+  remainingMs: number,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let done = false;
+    const timer = setTimeout(() => {
+      done = true;
+      resolve(false);
+    }, remainingMs);
+    void waitForSettle.then(() => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
 function installBridge(
   ctx: QuickJSContext,
   providers: ExecutorProvider[],
@@ -176,7 +223,20 @@ function installBridge(
       if (!f) throw new Error(`Unknown function ${ns}.${fn}`);
       const args = JSON.parse(argsJson) as unknown[];
       const value = await f(...args);
-      return JSON.stringify({ ok: true, value });
+      let json: string;
+      try {
+        json = JSON.stringify({ ok: true, value });
+      } catch (err) {
+        throw new Error(
+          `Host result from ${ns}.${fn} could not be serialized: ${msg(err)}`,
+        );
+      }
+      if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
+        throw new Error(
+          `Host result from ${ns}.${fn} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`,
+        );
+      }
+      return json;
     } catch (err) {
       return JSON.stringify({ ok: false, error: msg(err) });
     }
@@ -326,10 +386,10 @@ export function quickJsExecutor(
           if (remaining <= 0) {
             return { result: undefined, error: timeoutError };
           }
-          const settled = await Promise.race([
-            bridge.waitForSettle.then(() => true),
-            new Promise<boolean>((r) => setTimeout(() => r(false), remaining)),
-          ]);
+          const settled = await waitForHostOrDeadline(
+            bridge.waitForSettle,
+            remaining,
+          );
           if (settled) armWake(bridge);
           else {
             return { result: undefined, error: timeoutError };

package/src/index.ts

@@ -82,7 +82,8 @@ export interface ConnectaDiscoveryConfig {
    * Deadline (ms) for each downstream probe/catalog call fanned out by
    * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
    * 30_000. A timed-out connector degrades independently; this does not apply
-   * to tool calls or currently abort the underlying fetch.
+   * to tool calls. Catalog walks receive the same cancellation signal, which
+   * aborts an in-flight page where supported and prevents another from starting.
    */
   probeTimeoutMs?: number;
 }
@@ -574,7 +575,11 @@ export type {
   CredentialHealthRecord,
 } from "./credential-health.js";
 
-export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
+export type {
+  RemoteMcpOptions,
+  RemoteMcpAuth,
+  RemoteMcpRedirectPolicy,
+} from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
 export type {
   Connector,

package/src/meta-tools.ts

@@ -30,7 +30,7 @@ import {
 import {
   DEFAULT_PROBE_TIMEOUT_MS,
   normalizeTimeoutMs,
-  withTimeout,
+  withAbortableTimeout,
 } from "./timeout.js";
 import { credentialVerdictApplies } from "./credential-health.js";
 import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
@@ -65,12 +65,126 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-const DEFAULT_SEARCH_LIMIT = 25;
+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 discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
+  const result = jsonResult({
+    error: {
+      code: error.code,
+      message: error.message,
+      retryable: false,
+    },
+  });
+  result.isError = true;
+  return result;
+}
+
+function discoveryResult(value: unknown, hint: string): ToolResult {
+  try {
+    const text = boundedDiscoveryText(value, hint);
+    return {
+      content: [{ type: "text", text }],
+      ...(value !== null && typeof value === "object" && !Array.isArray(value)
+        ? { structuredContent: value as Record<string, unknown> }
+        : {}),
+    };
+  } catch (err) {
+    if (err instanceof DiscoveryPolicyError) {
+      return discoveryErrorResult(err);
+    }
+    throw err;
+  }
+}
+
 /**
  * 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
@@ -483,6 +597,18 @@ export function createMetaTools(
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
   const requestScope = {};
+  const withProbeDeadline = <T>(
+    label: string,
+    operation: (options: {
+      signal: AbortSignal;
+      timeoutMs: number;
+    }) => Promise<T>,
+  ) =>
+    withAbortableTimeout(
+      (signal) => operation({ signal, timeoutMs: probeTimeoutMs }),
+      probeTimeoutMs,
+      label,
+    );
 
   interface RunCallOutcome {
     toolResult: ToolResult;
@@ -793,8 +919,8 @@ export function createMetaTools(
       // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
       const connectors = registry.listConnectors();
       const scope = probe ? {} : requestScope;
-      const out = await Promise.all(
-        connectors.map(async (c) => {
+      const pending = connectors.map(
+        async (c) => {
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
           const verdict = await registry.credentialHealthFor(c.id);
@@ -803,10 +929,10 @@ export function createMetaTools(
             | { state: "ok" | "error" | "unknown"; message?: string };
           if (probe) {
             try {
-              status = await withTimeout(
-                registry.statusFor(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              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)
@@ -890,14 +1016,45 @@ export function createMetaTools(
           // the first (now stale) authorization URL.
           if (probe && status.state === "ok") {
             try {
-              tools = await withTimeout(
-                registry.refreshTools(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              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) {
-              status = { state: "error" as const, message: msg(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);
             }
           }
@@ -922,24 +1079,38 @@ export function createMetaTools(
               : {}),
             ...(status.message ? { message: status.message } : {}),
           };
-        }),
-      ).finally(async () => {
-        if (!probe) return;
-        await Promise.all(
-          connectors.map((connector) =>
-            closeConnectorScope(
-              connector,
-              registry.contextFor(connector.id, baseUrl, scope),
-            ),
+        },
+      );
+      if (!probe) {
+        return jsonResult({ connectors: await Promise.all(pending) });
+      }
+      const settled = await Promise.allSettled(pending);
+      await Promise.all(
+        connectors.map((connector) =>
+          closeConnectorScope(
+            connector,
+            registry.contextFor(connector.id, baseUrl, scope),
           ),
-        );
+        ),
+      );
+      const out = settled.map((result) => {
+        if (result.status === "rejected") throw result.reason;
+        return result.value;
       });
       return jsonResult({ connectors: out });
     },
 
     async searchTools(args: SearchArgs): Promise<ToolResult> {
       const q = args.query ?? "";
-      const limit = Math.max(1, Math.trunc(args.limit ?? DEFAULT_SEARCH_LIMIT));
+      let limit: number;
+      try {
+        limit = discoverySearchLimit(args.limit);
+      } 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(
@@ -957,10 +1128,10 @@ export function createMetaTools(
       }> = [];
       const catalogs = await Promise.allSettled(
         conns.map((c) =>
-          withTimeout(
-            registry.getTools(c.id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `search_tools probe of "${c.id}"`,
+            (options) =>
+              registry.getTools(c.id, baseUrl, requestScope, options),
           ),
         ),
       );
@@ -1050,17 +1221,28 @@ export function createMetaTools(
         offset + page.length < matches.length
           ? offset + page.length
           : undefined;
-      return jsonResult({
-        connectors: groups,
-        total: matches.length,
-        offset,
-        limit,
-        hasMore: nextOffset !== undefined,
-        ...(nextOffset !== undefined ? { nextOffset } : {}),
-      });
+      return discoveryResult(
+        {
+          connectors: groups,
+          total: matches.length,
+          offset,
+          limit,
+          hasMore: nextOffset !== undefined,
+          ...(nextOffset !== undefined ? { nextOffset } : {}),
+        },
+        "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+      );
     },
 
     async describeTools(args: DescribeArgs): Promise<ToolResult> {
+      try {
+        discoveryAddresses(args.addresses);
+      } catch (err) {
+        if (err instanceof DiscoveryPolicyError) {
+          return discoveryErrorResult(err);
+        }
+        throw err;
+      }
       const format = args.format ?? "compact";
       const resolved = args.addresses.map((address) => ({
         address,
@@ -1075,10 +1257,10 @@ export function createMetaTools(
       ];
       const loaded = await Promise.allSettled(
         connectorIds.map((id) =>
-          withTimeout(
-            registry.getTools(id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `describe_tools probe of "${id}"`,
+            (options) =>
+              registry.getTools(id, baseUrl, requestScope, options),
           ),
         ),
       );
@@ -1131,7 +1313,10 @@ export function createMetaTools(
           ...(tool.annotations ? { annotations: tool.annotations } : {}),
         };
       });
-      return jsonResult({ tools: out });
+      return discoveryResult(
+        { tools: out },
+        'Split the address list or use format: "compact".',
+      );
     },
 
     async callTool(args: CallArgs): Promise<ToolResult> {
@@ -1327,10 +1512,8 @@ export function createMetaTools(
 
 const LIST_DESC =
   "List connectors with status, cached tool count, and recent real-call health. Use probe=false for a fast inventory; use probe=true (default) only to diagnose live health or authorization.";
-const SEARCH_DESC =
-  'Start here when a tool address is unknown. Exact/name matches rank above description matches; an empty query browses all. includeSchemas="compact" usually removes the describe_tools round trip.';
-const DESCRIBE_DESC =
-  'Inspect known tool addresses when search_tools did not include a sufficient schema. Returns descriptions, input/output schemas, and behavior annotations; format "compact" is the default.';
+const SEARCH_DESC = `Start here when a tool address is unknown. Exact/name matches rank above description matches; an empty query browses all. Pages contain at most ${MAX_SEARCH_LIMIT} tools. includeSchemas="compact" usually removes the describe_tools round trip.`;
+const DESCRIBE_DESC = `Inspect up to ${MAX_DESCRIBE_ADDRESSES} known tool addresses when search_tools did not include a sufficient schema. Returns descriptions, input/output schemas, and behavior annotations; format "compact" is the default.`;
 const CALL_DESC =
   'Use for one tool explicitly annotated readOnlyHint: true. For 2–10 independent read-only calls use batch_call; for dependent steps or data reduction use execute_code when available. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths, resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
 const CALL_DESTRUCTIVE_DESC =
@@ -1444,7 +1627,7 @@ export function registerMetaTools(
       inputSchema: {
         query: z.string().optional(),
         connector: z.string().optional(),
-        limit: z.number().int().positive().optional(),
+        limit: z.number().int().positive().max(MAX_SEARCH_LIMIT).optional(),
         offset: z.number().int().nonnegative().optional(),
         fullDescriptions: z.boolean().optional(),
         includeSchemas: z.enum(["compact", "json"]).optional(),
@@ -1459,7 +1642,7 @@ export function registerMetaTools(
     {
       description: describedFor(registry, DESCRIBE_DESC, "describe"),
       inputSchema: {
-        addresses: z.array(z.string()),
+        addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
         format: z.enum(["compact", "json"]).optional(),
         fullDescriptions: z.boolean().optional(),
       },