@zackbart/connecta 0.14.2 → 0.15.1

package/documentation/stripe.md

@@ -137,18 +137,18 @@ exists rather than a fresh object appearing beside it. Additive writes
 `readOnlyHint: false` already routes them through `call_destructive_tool`, and
 asserting destruction only inflates the approval copy the host shows a human.
 
-That classification is **fill-in only**, and unconditionally so: it supplies
-the annotations Stripe leaves unset — Stripe documents no MCP annotations at
-all — and contradicts an explicit downstream annotation in neither direction. A
-tool on the read allowlist arriving with `destructiveHint: true` or
-`readOnlyHint: false` keeps exactly what the downstream said and stays behind
-`call_destructive_tool`. A tool on neither maintained list arriving with
-`readOnlyHint: true` keeps that too, and stays callable from `execute_code`.
-Both are the downstream telling you this release's allowlist is stale, and on a
-name no release has reviewed its word is the only evidence there is. The one
-classification that still outranks the downstream is a name this release
-reviewed and filed destructive: a `create_refund` claiming `readOnlyHint: true`
-is a downstream bug rather than news, and stays on the approval path.
+That classification fills in downstream silence and otherwise preserves
+explicit annotations. It supplies the annotations Stripe leaves unset — Stripe
+documents no MCP annotations at all. A tool on the read allowlist arriving with
+`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
+downstream said and stays behind `call_destructive_tool`. A tool on neither
+maintained list arriving with `readOnlyHint: true` keeps that too, and stays
+callable from `execute_code`. Both are the downstream telling you this release's
+allowlist is stale, and on a name no release has reviewed its word is the only
+evidence there is. One narrow fail-closed exception applies to a name this
+release reviewed and filed destructive: a `create_refund` claiming
+`readOnlyHint: true` is a downstream bug rather than news, and stays on the
+approval path.
 
 An unfamiliar tool that annotates nothing fails closed onto
 `call_destructive_tool` until a Connecta release reviews it. That is not

package/ethos.md

@@ -69,7 +69,7 @@ proposing one without a new argument is not.
 | Multi-tenancy / account model | refused | one deployment per tenant; deploy again instead |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
-| Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and never overrule an explicit one; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and otherwise preserve explicit annotations, with one fail-closed exception: a release-reviewed destructive classification outranks a contradictory downstream `readOnlyHint: true`, because Connecta has independently established that the tool mutates existing state; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297), [#315](https://github.com/zackbart/connecta/issues/315)) |
 | Guarded raw REST escape hatches in a prebuilt connection | accepted | a large, fast-moving provider cannot be honestly represented by a small frozen list: a GET-only tool may expose provider-relative reads, while JSON mutations and explicit-content uploads stay separate and always cross the destructive boundary; the connector owns authentication, rate limits, error mapping, URL confinement, and safe method classification, while the provider token remains the capability boundary — this is not schema ingestion, runtime connector registration, or permission widening |
 | Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Protocol sessions & server push | refused | stateless per request |
@@ -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.2",
+  "version": "0.15.1",
   "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/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 =