@zackbart/connecta 0.14.1 → 0.15.0

package/documentation/connectors.md

@@ -128,7 +128,12 @@ Connecta deliberately sits between protocol generations
   remains stateless in both cases.
 - **Outbound:** `remoteMcp()` probes modern downstreams and falls back to the
   byte-compatible legacy flow. Legacy downstreams are normal supported
-  deployments, not a temporary exception.
+  deployments, not a temporary exception. Automatic negotiation remains the
+  default. A known-legacy server that crashes or returns a server error for the
+  pre-initialize probe can set `versionNegotiation: "legacy"` on that one
+  connector; Connecta then starts directly with `initialize` and never sends
+  `server/discover`. Keep the default unless the downstream requires this
+  compatibility concession, so modern protocol support is still discovered.
 - **Legacy sessions:** Connecta's own endpoint creates no protocol session, but
   a stateful legacy downstream can still issue `Mcp-Session-Id`. Closing a
   request scope explicitly sends the legacy DELETE before closing its transport.

package/documentation/meta-tools.md

@@ -46,6 +46,18 @@ read-only calls and returns typed outcomes, and an unfiltered
 `connecta.search({})` browses every catalog a program can reach. Live connector
 probing is an operator concern: the operator pages and `/health` own it.
 
+The three discovery routes use deliberately different envelopes. These are
+their smallest successful one-tool shapes:
+
+```js
+// Top-level search_tools
+{ connectors: [{ id: "ci", tools: [{ name: "get_run", address: "ci.get_run" }] }], total: 1, offset: 0, limit: 8, hasMore: false }
+
+// Inside execute_code
+{ tools: [{ name: "get_run", address: "ci.get_run" }], total: 1, offset: 0, limit: 8, hasMore: false } // connecta.search
+{ tools: [{ name: "get_run", address: "ci.get_run", inputSchema: "{ runId: integer }" }] } // connecta.describe
+```
+
 ## Discovery context
 
 Start an unknown-address lookup with two to four distinctive action/object
@@ -60,8 +72,10 @@ or setting it to `"all"`, preserves the complete configured catalog. This is
 only a discovery filter: it neither grants authority nor changes invocation admission.
 `includeSchemas: "compact"` adds each match's input and any declared output
 shape. Bounded plain-object schemas also expose `inputKeys`,
-`requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
-list rather than repeating a large partial inventory. Matches carry declared
+`requiredInputKeys`, and `outputKeys`; a zero-input object keeps
+`requiredInputKeys: []`, while an output object with no declared properties
+omits `outputKeys`. A truncated shape omits its corresponding list rather than
+repeating a large partial inventory. Matches carry declared
 behavior annotations. Lexical rank is only one signal: select a candidate whose
 required inputs are available, whose schema is complete enough for the call,
 and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
@@ -75,11 +89,17 @@ Compact search is deliberately a routing view, not a second copy of connector
 documentation. Tool purposes are capped at 160 characters, connector
 descriptions and property prose are omitted, required input fields render
 before optional ones, and each input or output shape is capped at 1,024 UTF-8
-bytes. A capped object becomes a valid required-first shape with `unknown`
-types; other shapes become `unknown /* truncated */`. The match also carries
+bytes. Within that unchanged total, each enum node may spend at most 256 UTF-8
+bytes. This lets about three near-cap enum nodes coexist while reserving the
+remaining quarter for surrounding syntax; the global fallback still applies
+when the complete shape exceeds 1,024 bytes. A large enum keeps the longest
+whole-value prefix that fits, then adds `unknown` and a comment with the exact
+omitted-value count. An empty enum renders as the valid `never` type. A capped
+object becomes a valid required-first shape with `unknown` types; other shapes
+become `unknown /* truncated */`. Either cap marks the match with
 `inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
 `includeSchemas: "json"` or use the existing describe path when exact
-constraints matter.
+constraints matter. Small enums and both exact paths remain complete.
 
 ## Connector guide selection
 
@@ -176,13 +196,34 @@ set of inflectional variants preserves singular/plural and verb-form recall
 without allowing arbitrary mid-word substring matches. Ranking weights each
 query term by its document frequency across the available catalogs in that
 search, so a rare domain term outranks a ubiquitous action while action terms
-still distinguish `get`, `list`, `search`, and write operations. If no tool
-covers every non-conversational term, the same scorer falls back to any-term
-matching and marks the result `matchMode: "partial"`.
-
-Every partial or no-match lexical search also returns bounded `queryAnalysis`;
-an all-term result needs no recovery advice. `representedTerms` occur in the
-current page, `otherResultTerms` occur only in another result, and
+still distinguish `get`, `list`, `search`, and write operations. The scorer
+always evaluates useful near-matches instead of letting one broad all-term
+description hide them. Complete matches rank before ordinary partial matches;
+a partial candidate whose complete normalized tool name occurs in the
+normalized raw query competes with complete matches by score, and other
+candidates covering at least two terms fill the remaining page after them.
+Conversational cleanup applies only to scoring terms, never to the exact-name
+phrase check. If no tool covers every non-conversational term, the same scorer
+preserves the wider any-term fallback and marks the result
+`matchMode: "partial"`.
+
+Returned tool rows expose neither lexical scores nor per-result query coverage.
+The mixed complete/partial scorer still ranks rare domain terms, action terms,
+and exact tool-name phrases. Select from the returned purpose, address, schema,
+safety, and output shape. Page-level `queryAnalysis` remains the recovery path
+when no single result covers every term or no match exists.
+
+Only an empty or whitespace-only query browses. A non-empty query that
+normalizes to no ASCII lexical terms returns no tools instead of unrelated
+browse results. Its bounded `queryAnalysis.unmatchedTerms` contains the clipped
+raw query and guidance asks for ASCII action/object terms. A mixed query still
+searches with its ASCII terms; unsupported characters do not become false
+matches or per-tool coverage terms.
+
+Every partial or no-match lexical search also returns bounded page-level
+`queryAnalysis`; an all-term result needs no recovery advice.
+`representedTerms` occur in the current page, `otherResultTerms` occur only in
+another result, and
 `unmatchedTerms` have no lexical match in the catalogs that answered. Partial
 results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
@@ -331,7 +372,9 @@ exist. `nextAction` points to discovery scoped to the same connector and tool
 name when the compact schema is needed — routed like any other miss, so a
 program is sent to `connecta.search` and a top-level call to `search_tools` —
 while `retry` says to correct the listed arguments and reissue the original
-operation. A schema the local
+operation. A declared property reports only its failed schema keyword, while a
+truly undeclared property reports `additionalProperties`; validator-internal
+duplicate `additionalProperties` branches never reach the caller. A schema the local
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.

package/ethos.md

@@ -91,6 +91,7 @@ proposing one without a new argument is not.
 | `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove; a program can shrink anything ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Stabilized workflows (programs → versioned scripts/skills) | gated | earns a surface only once real traffic shows programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
 | Semantic tool search | gated | keyword search has not been shown to be the thing failing; earns its way in through [#222](https://github.com/zackbart/connecta/issues/222)'s harness ([#27](https://github.com/zackbart/connecta/issues/27)) |
+| Per-result lexical query coverage | removed | verbose, indexed, and trailing shapes did not earn their response-token cost: the coverage-off arm beat the verbose wire, the first compact wire regressed efficiency, and the trailing wire failed its precommitted 30-run clean-route gate (13/30 vs 9/30, +13.3 pp, Fisher p=0.422); preserve the mixed complete/partial ranking from [#326](https://github.com/zackbart/connecta/issues/326), but do not revive serialized coverage without new causal evidence ([#322](https://github.com/zackbart/connecta/issues/322), [#323](https://github.com/zackbart/connecta/issues/323)) |
 | MRTR / `input_required` passthrough | gated | statelessly relayable via `requestState`, but no host or downstream emits it yet; fails loudly until adoption evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size; paging on a polling extension adds round trips for nothing ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | fixed TTL + fingerprint is battle-tested and catalog reads are ~3 ms; earns its way in with refresh-churn evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/src/catalog-service.ts

@@ -45,11 +45,29 @@ export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
-const MAX_QUERY_ANALYSIS_TERMS = 8;
-const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
+const MAX_QUERY_TERMS = 8;
+const MAX_QUERY_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
+/** Clip one echoed query term without splitting a non-BMP code point. */
+function boundedQueryTerm(term: string): {
+  text: string;
+  truncated: boolean;
+} {
+  const characters: string[] = [];
+  for (const character of term) {
+    characters.push(character);
+    if (characters.length > MAX_QUERY_TERM_LENGTH) {
+      return {
+        text: `${characters.slice(0, MAX_QUERY_TERM_LENGTH - 1).join("")}…`,
+        truncated: true,
+      };
+    }
+  }
+  return { text: characters.join(""), truncated: false };
+}
+
 /**
  * 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
@@ -261,7 +279,9 @@ function schemaKeyMetadata(
           requiredInputKeys: inputKeys.required,
         }
       : {}),
-    ...(outputKeys ? { outputKeys: outputKeys.properties } : {}),
+    ...(outputKeys && outputKeys.properties.length > 0
+      ? { outputKeys: outputKeys.properties }
+      : {}),
   };
 }
 
@@ -647,6 +667,9 @@ export class CatalogService {
       tool: ToolDef;
       score: number;
       order: number;
+      exactName: boolean;
+      matchedTermCount: number;
+      complete: boolean;
     }> = [];
     let matchMode: "all" | "partial" = "all";
     const statistics = lexicalCorpusStatistics(
@@ -655,8 +678,19 @@ export class CatalogService {
       ),
       retrievalQuery,
     );
+    const trimmedQuery = query.trim();
+    const isBrowse = trimmedQuery.length === 0;
+    const queryTerms = lexicalQueryTerms(retrievalQuery);
+    const queryTermCount = queryTerms.length;
+    const unsearchableQuery = !isBrowse && queryTermCount === 0;
+    const analysisTerms = unsearchableQuery ? [trimmedQuery] : queryTerms;
+    const analyzedTerms = analysisTerms.slice(0, MAX_QUERY_TERMS);
+    const displayTerm = (term: string) => boundedQueryTerm(term).text;
+    const queryMetadataTruncated =
+      analysisTerms.length > analyzedTerms.length ||
+      analyzedTerms.some((term) => boundedQueryTerm(term).truncated);
     const collectMatches = (mode: "all" | "partial") => {
-      matches.length = 0;
+      const collected: typeof matches = [];
       let orderBase = 0;
       searchableCatalogs.forEach((catalog, connectorIndex) => {
         const connector = connectors[connectorIndex];
@@ -669,25 +703,59 @@ export class CatalogService {
             retrievalQuery,
             mode,
             statistics,
+            query,
           )) {
-            matches.push({
+            collected.push({
               connector,
               tool: ranked.tool,
               score: ranked.score,
               order: orderBase + ranked.order,
+              exactName: ranked.exactName,
+              matchedTermCount: ranked.matchedTermCount,
+              complete:
+                isBrowse || ranked.matchedTermCount === queryTermCount,
             });
           }
         }
         orderBase +=
           catalog.status === "fulfilled" ? catalog.value.length : 1;
       });
+      return collected;
     };
-    collectMatches("all");
-    if (query.trim() && matches.length === 0) {
+    // A non-empty query that normalizes to no lexical terms is not a browse.
+    // Ranking an empty phrase would otherwise return every tool as an
+    // unrelated zero-score match, with no coverage to explain the result.
+    const rankedMatches = unsearchableQuery
+      ? []
+      : collectMatches(isBrowse ? "all" : "partial");
+    const completeMatchCount = rankedMatches.filter(
+      (match) => match.complete,
+    ).length;
+    matches.push(
+      ...rankedMatches.filter(
+        (match) =>
+          match.complete ||
+          completeMatchCount === 0 ||
+          match.exactName ||
+          match.matchedTermCount >= 2,
+      ),
+    );
+    if (!isBrowse && !unsearchableQuery && completeMatchCount === 0) {
       matchMode = "partial";
-      collectMatches(matchMode);
     }
-    matches.sort((a, b) => b.score - a.score || a.order - b.order);
+    // Complete matches and exact tool-name phrases share the first rank tier.
+    // This lets a strong action/object name beat a weak description-only
+    // decoy. Other partial matches fill the remaining page only after every
+    // complete match, regardless of a rare-term score spike.
+    matches.sort((a, b) => {
+      const aFirstTier = a.complete || a.exactName;
+      const bFirstTier = b.complete || b.exactName;
+      return (
+        Number(bFirstTier) - Number(aFirstTier) ||
+        b.score - a.score ||
+        a.order - b.order
+      );
+    });
     const pageMatches = matches.slice(offset, offset + limit);
     const entries = pageMatches.map((match) => {
       const input = match.tool.inputSchema ?? { type: "object" };
@@ -769,12 +837,6 @@ export class CatalogService {
       offset + entries.length < matches.length
         ? offset + entries.length
         : undefined;
-    const queryTerms = lexicalQueryTerms(retrievalQuery);
-    const analyzedTerms = queryTerms.slice(0, MAX_QUERY_ANALYSIS_TERMS);
-    const displayTerm = (term: string) =>
-      term.length <= MAX_QUERY_ANALYSIS_TERM_LENGTH
-        ? term
-        : `${term.slice(0, MAX_QUERY_ANALYSIS_TERM_LENGTH - 1)}…`;
     const pageTools = new Set(pageMatches.map((match) => match.tool));
     const matchingTools = (term: string) =>
       new Set([
@@ -844,19 +906,24 @@ export class CatalogService {
       args.connector && !scopedConnector
         ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
         : undefined;
-    // Term-bearing searches report analysis only when the scorer had to
-    // degrade; a browse has no terms to analyse and normally reports none at
-    // all. But neither "this catalog is unavailable" nor "there is no such
-    // connector" is a statement about terms, and answering either browse with
-    // an empty entry list alone is indistinguishable from a connector that
-    // simply exposes no tools. The term partitions stay empty on those paths
-    // because there were no terms — the scope fields carry the whole message.
+    // Searchable queries report analysis when the scorer had to degrade. A
+    // non-empty query with no searchable terms reports the bounded raw input
+    // as unmatched instead of silently becoming a browse. A real browse has
+    // no terms to analyse and normally reports none at all. Scope failures are
+    // the exception, because an empty result alone looks like a connector that
+    // correctly exposes no tools.
     const reportsQueryAnalysis =
-      queryTerms.length > 0
+      unsearchableQuery ||
+      (queryTerms.length > 0
         ? matchMode === "partial"
-        : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0;
+        : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
     const guidance =
-      queryTerms.length === 0
+      unsearchableQuery
+        ? (unknownConnectorGuidance ??
+          (scopedConnector && unavailableCatalogs > 0
+            ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+            : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query."))
+        : queryTerms.length === 0
         ? // A browse has no terms to advise about, so it stays silent unless
           // the scope itself failed: the guidance on a scoped miss recommends
           // browsing with an empty query, and that advice must not lead into a
@@ -901,10 +968,7 @@ export class CatalogService {
               representedTerms,
               otherResultTerms,
               unmatchedTerms,
-              ...(queryTerms.length > analyzedTerms.length ||
-              analyzedTerms.some(
-                (term) => term.length > MAX_QUERY_ANALYSIS_TERM_LENGTH,
-              )
+              ...(queryMetadataTruncated
                 ? { truncated: true as const }
                 : {}),
               ...(args.connector ? { connectorScope: args.connector } : {}),

package/src/catalog.ts

@@ -3,6 +3,8 @@ import type { JsonSchema, ToolDef } from "./types.js";
 const DEFAULT_DESCRIPTION_LENGTH = 240;
 const DISCOVERY_DESCRIPTION_LENGTH = 160;
 export const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1_024;
+const MAX_COMPACT_DISCOVERY_ENUM_BYTES =
+  MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const schemaEncoder = new TextEncoder();
 const COMPACT_DISCOVERY_TRUNCATION = " /* truncated */";
 
@@ -126,6 +128,8 @@ export interface RankedTool {
   tool: ToolDef;
   score: number;
   order: number;
+  exactName: boolean;
+  matchedTermCount: number;
 }
 
 const searchIndexes = new WeakMap<ToolDef[], SearchIndex>();
@@ -304,8 +308,8 @@ function scoreDocument(
   terms: string[],
   mode: LexicalMatchMode,
   statistics: LexicalCorpusStatistics,
-): number | null {
-  if (!phrase) return 0;
+): { score: number; matchedTermCount: number } | null {
+  if (!phrase) return { score: 0, matchedTermCount: 0 };
   const matchedTerms = terms.filter((term) =>
     statistics.nameMatches.get(term)?.has(doc.tool) ||
     statistics.descriptionMatches.get(term)?.has(doc.tool),
@@ -343,10 +347,19 @@ function scoreDocument(
       score += 1.5 * weight;
     }
   }
-  return score;
+  return { score, matchedTermCount: matchedTerms.length };
 }
 
-/** Rank a connector's tools while caching its normalized plain-data index. */
+function queryContainsExactName(doc: SearchDocument, phrase: string): boolean {
+  if (!doc.name || !phrase) return false;
+  return (` ${phrase} `).includes(` ${doc.name} `);
+}
+
+/**
+ * Rank a connector's tools while caching its normalized plain-data index.
+ * `exactNameQuery` may retain framing removed from the scoring query: those
+ * words are weak term evidence, but remain part of a real tool-name phrase.
+ */
 export function rankTools(
   tools: ToolDef[],
   query: string,
@@ -355,13 +368,23 @@ export function rankTools(
     [tools],
     query,
   ),
+  exactNameQuery: string = query,
 ): RankedTool[] {
   const phrase = normalized(query);
+  const exactNamePhrase = normalized(exactNameQuery);
   const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
   const ranked: RankedTool[] = [];
   documentsFor(tools).forEach((doc, order) => {
-    const score = scoreDocument(doc, phrase, terms, mode, statistics);
-    if (score !== null) ranked.push({ tool: doc.tool, score, order });
+    const scored = scoreDocument(doc, phrase, terms, mode, statistics);
+    if (scored !== null) {
+      ranked.push({
+        tool: doc.tool,
+        score: scored.score,
+        order,
+        exactName: queryContainsExactName(doc, exactNamePhrase),
+        matchedTermCount: scored.matchedTermCount,
+      });
+    }
   });
   return ranked;
 }
@@ -405,6 +428,36 @@ function grouped(part: string): string {
   return part;
 }
 
+function renderEnum(
+  values: unknown[],
+  byteLimit: number | undefined,
+  onTruncated: (() => void) | undefined,
+): string {
+  if (values.length === 0) return "never";
+  const renderedValues = values.map((value) => JSON.stringify(value));
+  const full = renderedValues.join(" | ");
+  if (
+    byteLimit === undefined ||
+    schemaEncoder.encode(full).length <= byteLimit
+  ) {
+    return full;
+  }
+
+  onTruncated?.();
+  const marker = (omitted: number) =>
+    `unknown /* ${omitted} enum ${omitted === 1 ? "value" : "values"} omitted */`;
+  let rendered = `(${marker(values.length)})`;
+  const prefix: string[] = [];
+  for (let index = 0; index < renderedValues.length - 1; index += 1) {
+    prefix.push(renderedValues[index] as string);
+    const omitted = renderedValues.length - prefix.length;
+    const candidate = `(${prefix.join(" | ")} | ${marker(omitted)})`;
+    if (schemaEncoder.encode(candidate).length > byteLimit) break;
+    rendered = candidate;
+  }
+  return rendered;
+}
+
 function renderSchema(
   schema: unknown,
   defs: Record<string, unknown>,
@@ -413,6 +466,8 @@ function renderSchema(
   options: {
     propertyDescriptions: boolean;
     requiredFirst: boolean;
+    enumByteLimit?: number;
+    onEnumTruncated?: () => void;
   },
 ): string {
   if (depth > 4) return "…";
@@ -463,7 +518,7 @@ function renderSchema(
     );
   }
   if (Array.isArray(s.enum)) {
-    return s.enum.map((value) => JSON.stringify(value)).join(" | ");
+    return renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
   }
   // Checked before type/properties so a discriminator like
   // { type: "string", const: "emoji" } renders as "emoji" rather than string.
@@ -602,10 +657,18 @@ export function compactDiscoverySchema(
     ...(schema.definitions as Record<string, unknown>),
   };
   let rendered: string;
+  let enumTruncated = false;
   try {
     rendered = renderSchema(schema, defs, new Set(), 0, {
       propertyDescriptions: false,
       requiredFirst: true,
+      // Three near-cap enums spend about three quarters of the complete shape
+      // budget, leaving the final quarter for surrounding syntax before the
+      // unchanged global fallback applies. Whole values keep this UTF-8 safe.
+      enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
+      onEnumTruncated: () => {
+        enumTruncated = true;
+      },
     });
   } catch {
     rendered = JSON.stringify(schema);
@@ -613,7 +676,7 @@ export function compactDiscoverySchema(
   const bytes = schemaEncoder.encode(rendered);
   let result: CompactDiscoverySchema;
   if (bytes.length <= MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
-    result = { text: rendered, truncated: false };
+    result = { text: rendered, truncated: enumTruncated };
   } else {
     result = {
       text: truncatedDiscoverySchema(schema),

package/src/connectors/api.ts

@@ -86,10 +86,10 @@ export interface ApiOptions {
  * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
  *
  * Arguments are validated against `inputSchema` before the handler runs
- * (disable with `validateArgs: false`). This is deliberately asymmetric with
- * remote MCP connectors, which stay pass-through: the downstream server is
- * authoritative for its own schemas, and re-validating with our JSON Schema
- * draft/format semantics could reject calls the downstream would accept.
+ * (disable with `validateArgs: false`). Remote MCP inputs are also validated,
+ * but in the shared invocation path against the request-local downstream
+ * catalog. These API-only controls stay here because hand-written handlers may
+ * deliberately accept loose coercion or choose fail-closed schema handling.
  */
 export function api(id: string, opts: ApiOptions): Connector {
   const defs: ToolDef[] = opts.tools.map((t) => ({

package/src/connectors/remote-mcp.ts

@@ -54,6 +54,14 @@ export interface RemoteMcpOptions {
    */
   usageGuide?: string | ConnectorUsageGuide;
   auth?: RemoteMcpAuth;
+  /**
+   * Downstream MCP version-negotiation mode. Defaults to `"auto"`, which
+   * probes with `server/discover` and falls back to the legacy lifecycle when
+   * the response identifies a legacy server. Set `"legacy"` only for a known
+   * legacy downstream that cannot safely receive the discovery probe; that
+   * path starts directly with the ordinary 2025 `initialize` handshake.
+   */
+  versionNegotiation?: "auto" | "legacy";
   /**
    * Downstream HTTP redirect policy. Defaults to `"none"`: every redirect is
    * rejected. `"same-origin"` follows at most five redirects while preserving
@@ -665,7 +673,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         const c = new Client(
           { name: "connecta", version: CONNECTA_VERSION },
           {
-            versionNegotiation: { mode: "auto" },
+            versionNegotiation: {
+              mode: opts.versionNegotiation ?? "auto",
+            },
             // Connecta has no interactive relay. Surface the result manually
             // below as one structured, non-retryable connector failure.
             inputRequired: { autoFulfill: false },

package/src/execute.ts

@@ -1274,19 +1274,20 @@ function discardedEmitsText(emitted: EmitCollector): string {
 const executeDescription = (
   emitBudgets: { maxBytes: number; maxBlocks: number },
   connectorGuides: boolean,
-) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool; a known address uses call_tool directly. This is the primary surface for everything wider. If any result will be reduced — even from one connector call — or work has dependent/multiple calls, loops, joins, or branches, make exactly one execute_code call that searches, selects, calls, and reduces before returning. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool; a known address uses call_tool directly. This is the primary surface for everything wider. For any reduction, dependency, multiple calls, loop, join, or branch, make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
 
-Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- Connector globals call <connectorId>.<toolName>(args) with one schema-matching args object. Sanitization: non-[A-Za-z0-9_$] → "_" (my-service.get.thing → my_service.get_thing), leading digit → "_" prefix, reserved word → "_" suffix.
-- connecta.call(address, args) and connecta.batch(calls) — call raw addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure that, not a bare result.
-- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Require address/description to match the operation, then check requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Choose the best compatible match; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Compatible means every required key has a task/prior-result value; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. Use displayed names; [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. connecta.describe takes { address: "<connectorId>.<toolName>" } or { addresses: [...] }. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. A missing key list means a non-object shape, not no fields — read the schema.${connectorGuides ? " A match with guideRequired: true is a hard stop: do not call it; describing the exact schema clears only a schema_truncated reason, so for any other reason return the exact guide name, fetch that guide with the top-level skills tool, then write the informed call." : ""}
+Write an async arrow function. NO network, filesystem, timers, or imports; only:
+- Connector globals call <connectorId>.<toolName>(args). Sanitization: non-[A-Za-z0-9_$] → "_" (my-service.get.thing → my_service.get_thing); prefix a leading digit; suffix a reserved word.
+- connecta.call(address, args) and connecta.batch(calls) use canonical addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure it.
+- top-level search_tools returns { connectors: [{ id, tools }], total, offset, limit, hasMore }; connecta.search returns { tools, total, offset, limit, hasMore }; connecta.describe returns { tools }.
+- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Require address/description to match the operation, then check requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Select by fit; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Every required key needs task/prior-result data; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. connecta.describe takes { address: "<connectorId>.<toolName>" } or { addresses: [...] }. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. Missing key list = non-object, not no fields; read the schema.${connectorGuides ? " guideRequired: true = stop. Describe clears only schema_truncated; otherwise return its exact guide, fetch with top-level skills, then write the informed call." : ""}
 - connecta.emit(block) — emit exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only, no host call, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid or over-budget throws before accepting.
-- connecta.ui(html, options?) — one success-only view. One arg is display-only; live reads use { reads: { name: { address, fixedArgs?, viewArgs? } } }, then markup calls connecta.read(name, args). Read admission is enforced; fixed keys cannot be overridden and undeclared keys fail. It shares the ${emitBudgets.maxBytes}-byte emit budget — one budget, not two; a second, over-budget, or invalid call throws catchably. Bytes stay out of context, so the model reads the return value, not the view: return the initial summary from its variables; later reads update only the view.
+- connecta.ui(html, options?) — one success-only view; one arg is display-only. Reads declare { reads: { name: { address, fixedArgs?, viewArgs? } } }; markup calls connecta.read(name, args). Admission applies. It shares the ${emitBudgets.maxBytes}-byte emit budget: one budget, not two; a second, over-budget, or invalid call throws catchably. Bytes stay out; the model reads the return value, not the view; return the initial summary from its variables.
 - console.log(...) — captured and returned with the result.
 
 Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }
 
-Calls return plain values (JSON-parsing MCP text when possible) and throw; catch errors. A thrown error is only a message; connecta.batch tells a policy refusal from a transient failure. Never retry retryable: false or rate_limited immediately — there are no timers. Return JSON; large results truncate, so reduce instead of returning raw payloads.
+Calls return plain values (JSON-parsing MCP text when possible) and throw; catch errors. A thrown error is only a message; connecta.batch tells a policy refusal from a transient failure. Never retry retryable: false, or rate_limited immediately; no timers. Return JSON; reduce large results before they truncate.
 
 Plain JS, no TypeScript. Compact schemas are TypeScript-like, not JSON Schema: write the property names they display; never guess positions or aliases.`;
 

package/src/meta-tools.ts

@@ -1372,7 +1372,7 @@ export function createMetaTools(
   };
 }
 
-const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty query browses all.`;
+const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty or whitespace-only query browses all; non-empty input with no ASCII terms returns no match.`;
 const CALL_DESC =
   'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. 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 =