@zackbart/connecta 0.14.2 → 0.15.0

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 =

package/src/validate.ts

@@ -57,6 +57,18 @@ interface ValidationUnit {
   error: string;
 }
 
+const CONTAINER_VALIDATION_KEYWORDS = new Set([
+  "properties",
+  "items",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "if",
+  "not",
+  "patternProperties",
+  "additionalProperties",
+]);
+
 function decodePointerPart(value: string): string {
   return value.replaceAll("~1", "/").replaceAll("~0", "~");
 }
@@ -81,6 +93,110 @@ function argumentPath(location: string): string {
   return location.startsWith("#") ? location.slice(1) || "/" : "/";
 }
 
+function validationUnitKey(unit: ValidationUnit): string {
+  return JSON.stringify([
+    unit.keyword,
+    unit.keywordLocation,
+    unit.instanceLocation,
+    unit.error,
+  ]);
+}
+
+function childPropertyName(
+  parentLocation: string,
+  childLocation: string,
+): string | undefined {
+  const prefix = parentLocation === "#" ? "#/" : `${parentLocation}/`;
+  if (!childLocation.startsWith(prefix)) return undefined;
+  const encoded = childLocation.slice(prefix.length);
+  return !encoded.includes("/") ? decodePointerPart(encoded) : undefined;
+}
+
+function schemaDeclaresProperty(schema: unknown, property: string): boolean {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    return false;
+  }
+  const record = schema as Record<string, unknown>;
+  const properties = record.properties;
+  if (
+    properties !== null &&
+    typeof properties === "object" &&
+    !Array.isArray(properties) &&
+    Object.hasOwn(properties, property)
+  ) {
+    return true;
+  }
+  const patterns = record.patternProperties;
+  if (
+    patterns === null ||
+    typeof patterns !== "object" ||
+    Array.isArray(patterns)
+  ) {
+    return false;
+  }
+  for (const pattern of Object.keys(patterns)) {
+    try {
+      if (new RegExp(pattern).test(property)) return true;
+    } catch {
+      // The validator owns schema support. An unusable pattern cannot prove
+      // that this additional-properties branch is a duplicate.
+    }
+  }
+  return false;
+}
+
+function isDuplicateAdditionalPropertiesBranch(
+  schema: JsonSchema,
+  units: ValidationUnit[],
+  index: number,
+): boolean {
+  const unit = units[index];
+  const wrapper = units[index - 1];
+  if (
+    unit?.keyword !== "false" ||
+    wrapper?.keyword !== "additionalProperties" ||
+    !wrapper.keywordLocation.endsWith("/additionalProperties")
+  ) {
+    return false;
+  }
+  const property = childPropertyName(
+    wrapper.instanceLocation,
+    unit.instanceLocation,
+  );
+  if (property === undefined) return false;
+  const parentSchemaLocation = wrapper.keywordLocation.slice(
+    0,
+    -"/additionalProperties".length,
+  );
+  return schemaDeclaresProperty(
+    pointerValue(schema, parentSchemaLocation || "#"),
+    property,
+  );
+}
+
+function normalizedValidationUnits(
+  schema: JsonSchema,
+  units: ValidationUnit[],
+): ValidationUnit[] {
+  const seen = new Set<string>();
+  return units.filter((unit, index) => {
+    if (CONTAINER_VALIDATION_KEYWORDS.has(unit.keyword)) return false;
+    if (isDuplicateAdditionalPropertiesBranch(schema, units, index)) {
+      return false;
+    }
+    const key = validationUnitKey(unit);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function agentFacingValidationError(unit: ValidationUnit): string {
+  return unit.keyword === "false"
+    ? "Value is not allowed by the declared schema."
+    : unit.error;
+}
+
 function expectedType(schema: JsonSchema, unit: ValidationUnit): string | undefined {
   if (unit.keyword === "type") {
     const value = pointerValue(schema, unit.keywordLocation);
@@ -120,22 +236,8 @@ function validationDetails(
   schema: JsonSchema,
   units: ValidationUnit[],
 ): ArgumentValidationDetails {
-  const leafUnits = units.filter(
-    (unit) =>
-      ![
-        "properties",
-        "items",
-        "allOf",
-        "anyOf",
-        "oneOf",
-        "if",
-        "not",
-        "patternProperties",
-        "additionalProperties",
-      ].includes(unit.keyword),
-  );
   const issues: ArgumentValidationIssue[] = [];
-  for (const unit of leafUnits) {
+  for (const unit of units) {
     const missing =
       unit.keyword === "required"
         ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1]
@@ -246,15 +348,18 @@ export function validateToolInput(
     return opts.failClosed ? unevaluableSchema(opts.address) : null;
   }
   if (result && !result.valid) {
-    const units = result.errors.filter((u) => u.instanceLocation !== "#");
-    const detail = (units.length > 0 ? units : result.errors)
-      .slice(0, 3)
-      .map((u) => `${u.instanceLocation}: ${u.error}`)
+    const units = normalizedValidationUnits(schema, result.errors);
+    const nestedUnits = units.filter((unit) => unit.instanceLocation !== "#");
+    const detail = (nestedUnits.length > 0 ? nestedUnits : units)
+      .slice(0, MAX_ARGUMENT_VALIDATION_ISSUES)
+      .map((unit) =>
+        `${unit.instanceLocation}: ${agentFacingValidationError(unit)}`,
+      )
       .join("; ");
     return new ConnectorCallError(
       "invalid_args",
       `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`,
-      { validation: validationDetails(schema, result.errors) },
+      { validation: validationDetails(schema, units) },
     );
   }
   return null;

package/src/version.ts

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

package/templates/node/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.14.2",
+    "@zackbart/connecta": "0.15.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {