@zackbart/connecta 0.28.0 → 0.29.0

package/dist/validate.js

@@ -1,6 +1,7 @@
 import { Validator } from "@cfworker/json-schema";
 import { boundedEchoText, ConnectorCallError } from "./errors.js";
 import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
+import { failureRecord, logFailure } from "./operator-record.js";
 // Lazy validator cache keyed by the schema object itself; null marks a schema
 // the validator rejected (warned once, then passed through rather than
 // breaking a working tool). A WeakMap so schemas belonging to a discarded
@@ -43,12 +44,7 @@ function argumentPath(location) {
     return location.startsWith("#") ? location.slice(1) || "/" : "/";
 }
 function validationUnitKey(unit) {
-    return JSON.stringify([
-        unit.keyword,
-        unit.keywordLocation,
-        unit.instanceLocation,
-        unit.error,
-    ]);
+    return JSON.stringify([unit.keyword, unit.keywordLocation, unit.instanceLocation, unit.error]);
 }
 function childPropertyName(parentLocation, childLocation) {
     const prefix = parentLocation === "#" ? "#/" : `${parentLocation}/`;
@@ -70,9 +66,7 @@ function schemaDeclaresProperty(schema, property) {
         return true;
     }
     const patterns = record.patternProperties;
-    if (patterns === null ||
-        typeof patterns !== "object" ||
-        Array.isArray(patterns)) {
+    if (patterns === null || typeof patterns !== "object" || Array.isArray(patterns)) {
         return false;
     }
     for (const pattern of Object.keys(patterns)) {
@@ -116,32 +110,26 @@ function normalizedValidationUnits(schema, units) {
         return true;
     });
 }
-function agentFacingValidationError(unit) {
-    return unit.keyword === "false"
-        ? "Value is not allowed by the declared schema."
-        : unit.error;
+const JSON_TYPES = new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
+/** A schema's `type`, when it names JSON types and nothing else. */
+function declaredType(value) {
+    const types = typeof value === "string" ? [value] : value;
+    return Array.isArray(types) &&
+        types.length > 0 &&
+        types.every((item) => typeof item === "string" && JSON_TYPES.has(item))
+        ? types.join(" | ")
+        : undefined;
 }
 function expectedType(schema, unit) {
     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(" | ");
-        }
+        return declaredType(pointerValue(schema, unit.keywordLocation));
     }
     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";
+        return (declaredType(pointerValue(schema, `${parentLocation}/properties/${encodePointerPart(missing)}/type`)) ?? "present");
     }
     const fixed = {
         additionalProperties: "no additional properties",
@@ -158,29 +146,288 @@ function expectedType(schema, unit) {
 function validationDetails(schema, units) {
     const issues = [];
     for (const unit of units) {
-        const missing = unit.keyword === "required"
-            ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1]
-            : undefined;
+        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");
+            (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)) {
+        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 }
-            : {}),
+        ...(issues.length > MAX_ARGUMENT_VALIDATION_ISSUES ? { truncated: true } : {}),
+    };
+}
+function schemaObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function receivedType(value) {
+    return value === undefined ? "missing" : value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+const BOUND_KEYWORDS = [
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minLength",
+    "maxLength",
+    "minItems",
+    "maxItems",
+    "minProperties",
+    "maxProperties",
+];
+/** No caller values are used to invent an example. A candidate must validate. */
+function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, active: new Set() }) {
+    if (--budget.remaining < 0)
+        throw new Error("Example synthesis budget exhausted");
+    if (depth > 12 || schema === false)
+        return undefined;
+    const node = schemaObject(schema);
+    if (budget.active.has(node))
+        throw new Error("Recursive schema cannot produce a bounded example");
+    budget.active.add(node);
+    try {
+        if (typeof node.$ref === "string") {
+            return exampleCandidate(pointerValue(root, node.$ref), root, depth + 1, budget);
+        }
+        if (Object.hasOwn(node, "const"))
+            return node.const;
+        if (Array.isArray(node.enum))
+            return node.enum[0];
+        const type = Array.isArray(node.type) ? node.type[0] : node.type;
+        const variants = Array.isArray(node.oneOf) ? node.oneOf : node.anyOf;
+        if (Array.isArray(variants) && variants.length) {
+            return mergeExample(exampleCandidate({ ...node, oneOf: undefined, anyOf: undefined }, root, depth + 1, budget), exampleCandidate(variants[0], root, depth + 1, budget));
+        }
+        if (Array.isArray(node.examples) && node.examples.length)
+            return node.examples[0];
+        if (Object.hasOwn(node, "default"))
+            return node.default;
+        let candidate;
+        if (type === "object" || node.properties || node.required || node.allOf) {
+            const properties = schemaObject(node.properties);
+            const required = Array.isArray(node.required) ? node.required : [];
+            candidate = Object.fromEntries(required
+                .filter((key) => typeof key === "string")
+                .slice(0, 30)
+                .map((key) => [key, exampleCandidate(properties[key], root, depth + 1, budget)]));
+            if (Array.isArray(node.allOf)) {
+                for (const branch of node.allOf.slice(0, 20)) {
+                    candidate = mergeExample(candidate, exampleCandidate(branch, root, depth + 1, budget));
+                }
+            }
+            const object = schemaObject(candidate);
+            const dependencies = schemaObject(node.dependentRequired ?? node.dependencies);
+            for (const [key, needs] of Object.entries(dependencies)) {
+                if (Object.hasOwn(object, key) && Array.isArray(needs)) {
+                    for (const need of needs.slice(0, 30)) {
+                        if (typeof need === "string" && !Object.hasOwn(object, need)) {
+                            Object.defineProperty(object, need, {
+                                value: exampleCandidate(properties[need], root, depth + 1, budget),
+                                enumerable: true,
+                                configurable: true,
+                                writable: true,
+                            });
+                        }
+                    }
+                }
+            }
+            if (node.if) {
+                try {
+                    const matches = new Validator(node.if, "2020-12", false).validate(candidate).valid;
+                    candidate = mergeExample(candidate, exampleCandidate(matches ? node.then : node.else, root, depth + 1, budget));
+                }
+                catch {
+                    // An unevaluable branch cannot establish a valid example.
+                }
+            }
+            // Branches may declare required keys while their types live on the parent.
+            for (const key of Object.keys(schemaObject(candidate))) {
+                if (schemaObject(candidate)[key] === undefined) {
+                    schemaObject(candidate)[key] = exampleCandidate(properties[key], root, depth + 1, budget);
+                }
+            }
+        }
+        else if (type === "array") {
+            const count = typeof node.minItems === "number" ? node.minItems : 0;
+            candidate = Array.from({ length: Math.min(count, 20) }, (_, index) => exampleCandidate(Array.isArray(node.prefixItems) ? node.prefixItems[index] : node.items, root, depth + 1, budget));
+        }
+        else if (type === "number" || type === "integer") {
+            let number = typeof node.minimum === "number" ? node.minimum : 0;
+            if (typeof node.exclusiveMinimum === "number")
+                number = node.exclusiveMinimum + (type === "integer" ? 1 : 0.5);
+            if (typeof node.maximum === "number")
+                number = Math.min(number, node.maximum);
+            if (typeof node.exclusiveMaximum === "number")
+                number = Math.min(number, node.exclusiveMaximum - 1);
+            if (typeof node.multipleOf === "number" && node.multipleOf > 0)
+                number = Math.ceil(number / node.multipleOf) * node.multipleOf;
+            candidate = type === "integer" ? Math.ceil(number) : number;
+        }
+        else if (type === "boolean")
+            candidate = false;
+        else if (type === "null")
+            candidate = null;
+        else if (type === "string") {
+            const formats = {
+                date: "2000-01-01",
+                "date-time": "2000-01-01T00:00:00Z",
+                email: "a@example.com",
+                uri: "https://example.com",
+                uuid: "00000000-0000-4000-8000-000000000000",
+            };
+            candidate =
+                typeof node.format === "string" && formats[node.format]
+                    ? formats[node.format]
+                    : "x".repeat(Math.min(typeof node.minLength === "number" ? node.minLength : 0, 128));
+        }
+        return candidate;
+    }
+    finally {
+        budget.active.delete(node);
+    }
+}
+function mergeExample(a, b) {
+    if (a !== null &&
+        b !== null &&
+        typeof a === "object" &&
+        typeof b === "object" &&
+        !Array.isArray(a) &&
+        !Array.isArray(b)) {
+        return { ...a, ...b };
+    }
+    return b === undefined ? a : b;
+}
+/** Remove optional sample fields only when the complete example stays valid. */
+function minimizeExample(example, validator) {
+    let attempts = 0;
+    const valid = () => {
+        try {
+            return validator.validate(example).valid;
+        }
+        catch {
+            return false;
+        }
+    };
+    const visit = (value, depth) => {
+        if (depth > 12 || value === null || typeof value !== "object" || attempts >= 60)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value.slice(0, 20))
+                visit(item, depth + 1);
+            while (value.length > 0 && attempts++ < 60) {
+                const last = value.pop();
+                if (!valid()) {
+                    value.push(last);
+                    break;
+                }
+            }
+            return;
+        }
+        const object = value;
+        for (const key of Object.keys(object)) {
+            if (attempts++ >= 60)
+                break;
+            const original = object[key];
+            delete object[key];
+            if (!valid()) {
+                Object.defineProperty(object, key, { value: original, enumerable: true, configurable: true, writable: true });
+                visit(original, depth + 1);
+            }
+        }
+    };
+    visit(example, 0);
+}
+function repairDetails(schema, args, units, validator) {
+    const root = schemaObject(schema);
+    const keys = (node) => Object.entries(schemaObject(node.properties))
+        .filter(([, value]) => value !== false)
+        .map(([key]) => key);
+    const issues = units.slice(0, MAX_ARGUMENT_VALIDATION_ISSUES).map((unit) => {
+        const missing = unit.keyword === "required" ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1] : undefined;
+        const location = missing === undefined ? unit.instanceLocation : `${unit.instanceLocation}/${encodePointerPart(missing)}`;
+        const parentLocation = unit.keywordLocation.replace(/\/[^/]+$/, "");
+        const parent = schemaObject(pointerValue(schema, parentLocation));
+        const node = missing === undefined ? parent : schemaObject(schemaObject(parent.properties)[missing]);
+        const bounds = Object.fromEntries(BOUND_KEYWORDS.flatMap((key) => (typeof node[key] === "number" ? [[key, node[key]]] : [])));
+        // A false subschema under additionalProperties names its parent object's keys.
+        const closedParent = unit.keyword === "false" && unit.keywordLocation.endsWith("/additionalProperties")
+            ? schemaObject(pointerValue(schema, unit.keywordLocation.slice(0, -"/additionalProperties".length)))
+            : node;
+        const acceptedKeys = keys(closedParent);
+        return {
+            path: argumentPath(location),
+            receivedType: receivedType(pointerValue(args, location)),
+            ...(acceptedKeys.length ? { acceptedKeys } : {}),
+            ...(Array.isArray(node.enum) ? { enumValues: node.enum } : {}),
+            ...(Object.keys(bounds).length ? { bounds } : {}),
+        };
+    });
+    const conditionalRequirements = [];
+    const visit = (value, path, depth) => {
+        if (depth > 12 || conditionalRequirements.length >= 20)
+            return;
+        const node = schemaObject(value);
+        for (const [key, required] of Object.entries(schemaObject(node.dependentRequired ?? node.dependencies))) {
+            if (Array.isArray(required) && required.every((key) => typeof key === "string")) {
+                conditionalRequirements.push({ path, condition: { required: [key] }, required });
+            }
+        }
+        for (const [key, branch] of Object.entries(schemaObject(node.dependentSchemas))) {
+            const required = schemaObject(branch).required;
+            if (Array.isArray(required) && required.every((key) => typeof key === "string")) {
+                conditionalRequirements.push({ path, condition: { required: [key] }, required });
+            }
+        }
+        for (const [branch, condition] of [
+            [node.then, node.if],
+            [node.else, node.if ? { not: node.if } : undefined],
+        ]) {
+            const required = schemaObject(branch).required;
+            if (condition && Array.isArray(required) && required.every((key) => typeof key === "string")) {
+                conditionalRequirements.push({ path, condition, required });
+            }
+        }
+        for (const [key, child] of Object.entries(schemaObject(node.properties)))
+            visit(child, `${path === "/" ? "" : path}/${encodePointerPart(key)}`, depth + 1);
+        // Alternatives can make a dependency branch-specific. Do not state its
+        // requirements without proving the complete branch condition.
+        for (const key of ["allOf"]) {
+            if (Array.isArray(node[key]))
+                for (const child of node[key])
+                    visit(child, path, depth + 1);
+        }
+    };
+    visit(schema, "/", 0);
+    let example;
+    let valid = false;
+    try {
+        // Serialization makes the validation cover exactly what the agent receives.
+        example = JSON.parse(JSON.stringify(exampleCandidate(schema, schema)));
+        valid = validator.validate(example).valid;
+        if (valid) {
+            minimizeExample(example, validator);
+            valid = validator.validate(example).valid;
+        }
+    }
+    catch {
+        valid = false;
+        // Unsatisfiable or complex schemas do not get a made-up valid example.
+    }
+    return {
+        ...(root.properties ? { acceptedKeys: keys(root) } : {}),
+        issues,
+        ...(conditionalRequirements.length ? { conditionalRequirements } : {}),
+        ...(valid
+            ? { example }
+            : { exampleUnavailable: "No valid example could be synthesized. Inspect the published inputSchema." }),
+        ...(units.length > MAX_ARGUMENT_VALIDATION_ISSUES ? { truncated: true } : {}),
     };
 }
 function unevaluableSchema(address) {
@@ -191,9 +438,15 @@ function unusableSchema(address, detail) {
         `(${detail}) — fix the schema or drop it; a schema that cannot be ` +
         "enforced must not ship as one that can.");
 }
-function disableValidation(schema, address, logger, err) {
+/**
+ * The validator's account of an unusable schema quotes the schema (an
+ * unresolvable `$ref`, an invalid `pattern`), and a downstream wrote that
+ * schema, so the log records only the tool's catalog entry and the error's
+ * class.
+ */
+function disableValidation(schema, subject, logger, err) {
     validators.set(schema, null);
-    logger.warn(`[connecta] tool "${address}" has an inputSchema the validator cannot use (${err instanceof Error ? err.message : String(err)}) — arguments are not validated`);
+    logFailure(logger, "input schema unusable; arguments are not validated", failureRecord(subject, err));
 }
 /**
  * Validate call arguments against a tool's JSON Schema.
@@ -221,6 +474,14 @@ function disableValidation(schema, address, logger, err) {
  * the `Connector` interface directly.
  */
 export function validateToolInput(schema, args, opts) {
+    return validateCatalogToolInput(schema, args, opts, {});
+}
+/**
+ * `validateToolInput` for a tool connecta resolved in a catalog. `subject`
+ * names it in the log record when the schema is unusable; a caller's own
+ * address never reaches the log.
+ */
+export function validateCatalogToolInput(schema, args, opts, subject) {
     const logger = opts.logger ?? console;
     let validator = validators.get(schema);
     if (validator === undefined) {
@@ -229,7 +490,7 @@ export function validateToolInput(schema, args, opts) {
             validators.set(schema, validator);
         }
         catch (err) {
-            disableValidation(schema, opts.address, logger, err);
+            disableValidation(schema, subject, logger, err);
             validator = null;
         }
     }
@@ -244,17 +505,18 @@ export function validateToolInput(schema, args, opts) {
     }
     catch (err) {
         // e.g. an unresolvable $ref — surfaces on first validate, not compile.
-        disableValidation(schema, opts.address, logger, err);
+        disableValidation(schema, subject, logger, err);
         return opts.failClosed ? unevaluableSchema(opts.address) : null;
     }
     if (result && !result.valid) {
         const units = normalizedValidationUnits(schema, result.errors);
         const nestedUnits = units.filter((unit) => unit.instanceLocation !== "#");
-        const detail = boundedEchoText((nestedUnits.length > 0 ? nestedUnits : units)
-            .slice(0, MAX_ARGUMENT_VALIDATION_ISSUES)
-            .map((unit) => `${unit.instanceLocation}: ${agentFacingValidationError(unit)}`)
-            .join("; "), 256);
-        return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation: validationDetails(schema, units) });
+        // Told from the reviewed findings, never the validator's own sentences,
+        // which quote the schema's types, enums, and patterns.
+        const validation = validationDetails(schema, units);
+        const shown = nestedUnits.length > 0 ? validationDetails(schema, nestedUnits) : validation;
+        const detail = boundedEchoText(shown.issues.map((issue) => `${issue.path}: expected ${issue.expected} (${issue.code})`).join("; "), 256);
+        return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation, repair: repairDetails(schema, args, units, validator) });
     }
     return null;
 }

package/dist/version.d.ts

@@ -1,7 +1 @@
-/**
- * The package version, as a Workers-safe constant — no filesystem read, no
- * import assertion. `test/version.test.ts` asserts it matches package.json, so
- * a bump that forgets this file fails the build rather than shipping a stale
- * version to `/health` and to downstream MCP handshakes.
- */
-export declare const CONNECTA_VERSION = "0.28.0";
+export declare const CONNECTA_VERSION = "0.29.0";

package/dist/version.js

@@ -1,7 +1,3 @@
-/**
- * The package version, as a Workers-safe constant — no filesystem read, no
- * import assertion. `test/version.test.ts` asserts it matches package.json, so
- * 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.28.0";
+// Generated from package.json by scripts/generate-version.mjs.
+// Workers-safe: no runtime filesystem read or deployment override.
+export const CONNECTA_VERSION = "0.29.0";

package/dist/worker.d.ts

@@ -0,0 +1,11 @@
+import { type DynamicWorkerExecutorOptions } from "@cloudflare/codemode";
+import { type AdmissionControllerOptions } from "./executor-admission.js";
+import type { AdmittingExecutor } from "./types.js";
+interface WorkerExecutorOptions {
+    loader: DynamicWorkerExecutorOptions["loader"];
+    timeout?: number;
+    admission?: AdmissionControllerOptions;
+}
+/** Loader-only upstream sandbox whose lease disposes handles at run end. */
+export declare function workerExecutor(options: WorkerExecutorOptions): AdmittingExecutor;
+export {};