@zackbart/connecta 0.10.2 → 0.10.3

package/src/invocation.ts

@@ -20,6 +20,7 @@ import { unwrapMcpResult } from "./mcp-result.js";
 import type { RegistryView } from "./registry.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type { ToolDef } from "./types.js";
+import { validateToolInput } from "./validate.js";
 
 /**
  * The longest the engine will park a synchronous inbound request in *waiting
@@ -299,6 +300,25 @@ export class InvocationService {
                 `Retry ${target.connector.id}.${target.toolName} after ` +
                 "the operator completes recovery.",
             }
+          : error.code === "invalid_args" && error.validation && target
+            ? {
+                ...error,
+                connector: target.connector.id,
+                operation: `${target.connector.id}.${target.toolName}`,
+                nextAction: {
+                  tool: "search_tools" as const,
+                  arguments: {
+                    query: target.toolName,
+                    connector: target.connector.id,
+                    includeSchemas: "compact" as const,
+                  },
+                  purpose:
+                    "Inspect the current input shape if the validation findings are not sufficient.",
+                },
+                retry:
+                  `Correct the listed arguments and retry ` +
+                  `${target.connector.id}.${target.toolName}.`,
+              }
           : error;
       record(
         details.code === "timeout"
@@ -362,6 +382,30 @@ export class InvocationService {
       );
     }
 
+    // Remote MCP tools advertise their input schema in the catalog. Validate
+    // against that same request-local definition before admission or provider
+    // dispatch, so a predictable mismatch stays structured instead of being
+    // flattened into provider-specific error prose. Unsupported schemas retain
+    // validateToolInput's fail-open behavior and reach the downstream normally.
+    if (
+      resolved.connector.kind === "mcp" &&
+      resolved.definition.inputSchema
+    ) {
+      const invalid = validateToolInput(
+        resolved.definition.inputSchema,
+        args ?? {},
+        {
+          address: `${resolved.connector.id}.${resolved.toolName}`,
+          logger: this.registry.contextFor(
+            resolved.connector.id,
+            this.catalog.baseUrl,
+            this.catalog.requestScope,
+          ).logger,
+        },
+      );
+      if (invalid) return failed(classifyCallError(invalid));
+    }
+
     try {
       context.beforeDispatch?.();
     } catch (error) {

package/src/meta-tools.ts

@@ -1114,6 +1114,7 @@ export function createMetaTools(
     if (!outcome.ok) {
       const failedResult =
         outcome.error.code === "auth_required" ||
+        outcome.error.code === "invalid_args" ||
         outcome.error.code === "input_required_unsupported" ||
         call.resultMode === "value"
           ? jsonResult({
@@ -1126,6 +1127,7 @@ export function createMetaTools(
           : errorResult(outcome.error.message);
       if (
         outcome.error.code === "auth_required" ||
+        outcome.error.code === "invalid_args" ||
         outcome.error.code === "input_required_unsupported"
       ) {
         failedResult.isError = true;

package/src/validate.ts

@@ -1,5 +1,10 @@
 import { Validator } from "@cfworker/json-schema";
 import { ConnectorCallError } from "./errors.js";
+import type {
+  ArgumentValidationDetails,
+  ArgumentValidationIssue,
+} from "./errors.js";
+import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
 import type { JsonSchema, Logger } from "./types.js";
 
 export interface ValidateToolInputOptions {
@@ -42,6 +47,128 @@ export interface PrecompileValidatorOptions {
 // breaking a working tool). A WeakMap so schemas belonging to a discarded
 // connector are collectable, the same pattern compactSchema uses.
 const validators = new WeakMap<JsonSchema, Validator | null>();
+const REQUIRED_PROPERTY_RE =
+  /^Instance does not have required property "([^"]+)"\.$/;
+
+interface ValidationUnit {
+  keyword: string;
+  keywordLocation: string;
+  instanceLocation: string;
+  error: string;
+}
+
+function decodePointerPart(value: string): string {
+  return value.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function encodePointerPart(value: string): string {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function pointerValue(value: unknown, pointer: string): unknown {
+  if (pointer === "#") return value;
+  if (!pointer.startsWith("#/")) return undefined;
+  let current = value;
+  for (const part of pointer.slice(2).split("/").map(decodePointerPart)) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function argumentPath(location: string): string {
+  if (location === "#") return "/";
+  return location.startsWith("#") ? location.slice(1) || "/" : "/";
+}
+
+function expectedType(schema: JsonSchema, unit: ValidationUnit): string | undefined {
+  if (unit.keyword === "type") {
+    const value = pointerValue(schema, unit.keywordLocation);
+    if (typeof value === "string") return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+      return value.join(" | ");
+    }
+  }
+  if (unit.keyword === "required") {
+    const missing = REQUIRED_PROPERTY_RE.exec(unit.error)?.[1];
+    if (!missing) return undefined;
+    const parentLocation = unit.keywordLocation.replace(/\/required$/, "");
+    const value = pointerValue(
+      schema,
+      `${parentLocation}/properties/${encodePointerPart(missing)}/type`,
+    );
+    if (typeof value === "string") return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+      return value.join(" | ");
+    }
+    return "present";
+  }
+  const fixed: Record<string, string> = {
+    additionalProperties: "no additional properties",
+    enum: "one of the declared values",
+    const: "the declared constant",
+    minLength: "the declared minimum length",
+    maxLength: "the declared maximum length",
+    minimum: "the declared minimum",
+    maximum: "the declared maximum",
+    pattern: "the declared string pattern",
+  };
+  return fixed[unit.keyword];
+}
+
+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) {
+    const missing =
+      unit.keyword === "required"
+        ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1]
+        : undefined;
+    const path =
+      missing !== undefined
+        ? `${argumentPath(unit.instanceLocation).replace(/\/$/, "")}/${encodePointerPart(missing)}`
+        : argumentPath(unit.instanceLocation);
+    const code = unit.keyword === "false" ? "additionalProperties" : unit.keyword;
+    const expected =
+      expectedType(schema, unit) ??
+      (code === "additionalProperties"
+        ? "no additional properties"
+        : "the declared schema constraint");
+    const issue = { path, code, expected };
+    if (
+      !issues.some(
+        (existing) =>
+          existing.path === issue.path &&
+          existing.code === issue.code &&
+          existing.expected === issue.expected,
+      )
+    ) {
+      issues.push(issue);
+    }
+  }
+  return {
+    issues: issues.slice(0, MAX_ARGUMENT_VALIDATION_ISSUES),
+    ...(issues.length > MAX_ARGUMENT_VALIDATION_ISSUES
+      ? { truncated: true as const }
+      : {}),
+  };
+}
 
 function unevaluableSchema(address: string): ConnectorCallError {
   return new ConnectorCallError(
@@ -127,6 +254,7 @@ export function validateToolInput(
     return new ConnectorCallError(
       "invalid_args",
       `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`,
+      { validation: validationDetails(schema, result.errors) },
     );
   }
   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.10.2";
+export const CONNECTA_VERSION = "0.10.3";

package/templates/node/package.json

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