@zackbart/connecta 0.24.2 → 0.24.4

package/dist/catalog.js

@@ -5,6 +5,53 @@ const MAX_COMPACT_DISCOVERY_ENUM_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const schemaEncoder = new TextEncoder();
 const COMPACT_DISCOVERY_TRUNCATION = " /* truncated */";
+const MAX_COMPACT_DESCRIPTION_SCHEMA_BYTES = 8_192;
+const MAX_SCHEMA_WORK = 2_000;
+const schemaWorkExceeded = Symbol("schema work budget exceeded");
+const schemaSizeExceeded = Symbol("schema byte budget exceeded");
+class SchemaWork {
+    byteLimit;
+    remaining = MAX_SCHEMA_WORK;
+    truncated = false;
+    refs = new Map();
+    constructor(byteLimit = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
+        this.byteLimit = byteLimit;
+    }
+    visit() {
+        if (this.remaining-- <= 0)
+            throw schemaWorkExceeded;
+    }
+    text(value) {
+        // Check code units first so encoding a hostile scalar is itself bounded.
+        if (value.length > this.byteLimit ||
+            schemaEncoder.encode(value).length > this.byteLimit) {
+            throw schemaSizeExceeded;
+        }
+        return value;
+    }
+    json(value) {
+        // The raw-JSON fallback and const/enum values must spend the same work
+        // budget as schema nodes, including values nested inside unknown keywords.
+        const visit = this.visit.bind(this);
+        const text = this.text.bind(this);
+        const ancestors = [];
+        return this.text(JSON.stringify(value, function (key, item) {
+            visit();
+            text(key);
+            if (typeof item === "string")
+                text(item);
+            if (item !== null && typeof item === "object") {
+                while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
+                    ancestors.pop();
+                }
+                if (ancestors.length > 32)
+                    throw schemaWorkExceeded;
+                ancestors.push(item);
+            }
+            return item;
+        }));
+    }
+}
 export function summarizeDescription(text, full) {
     return summarizeToLength(text, full, DEFAULT_DESCRIPTION_LENGTH);
 }
@@ -315,6 +362,13 @@ function refName(ref) {
  */
 function declaresShape(s) {
     return (typeof s.$ref === "string" ||
+        typeof s.$dynamicRef === "string" ||
+        Array.isArray(s.allOf) ||
+        Array.isArray(s.prefixItems) ||
+        s.dependentSchemas !== undefined ||
+        s.if !== undefined ||
+        s.then !== undefined ||
+        s.else !== undefined ||
         Array.isArray(s.oneOf) ||
         Array.isArray(s.anyOf) ||
         Array.isArray(s.enum) ||
@@ -342,30 +396,42 @@ function grouped(part) {
     }
     return part;
 }
-function renderEnum(values, byteLimit, onTruncated) {
+function renderEnum(values, work, byteLimit, onTruncated) {
     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 limit = byteLimit ?? MAX_COMPACT_DISCOVERY_ENUM_BYTES;
     const marker = (omitted) => `unknown /* ${omitted} enum ${omitted === 1 ? "value" : "values"} omitted */`;
     let rendered = `(${marker(values.length)})`;
     const prefix = [];
-    for (let index = 0; index < renderedValues.length - 1; index += 1) {
-        prefix.push(renderedValues[index]);
-        const omitted = renderedValues.length - prefix.length;
-        const candidate = `(${prefix.join(" | ")} | ${marker(omitted)})`;
-        if (schemaEncoder.encode(candidate).length > byteLimit)
+    for (let index = 0; index < values.length; index += 1) {
+        let value;
+        try {
+            value = work.json(values[index]);
+        }
+        catch (error) {
+            if (error !== schemaSizeExceeded)
+                throw error;
+            break;
+        }
+        prefix.push(value);
+        const full = prefix.join(" | ");
+        if (schemaEncoder.encode(full).length > limit)
             break;
-        rendered = candidate;
+        if (index === values.length - 1)
+            return full;
+        const omitted = values.length - prefix.length;
+        const candidate = `(${full} | ${marker(omitted)})`;
+        if (schemaEncoder.encode(candidate).length <= limit)
+            rendered = candidate;
     }
+    onTruncated?.();
     return rendered;
 }
 function safeConstraintValue(value) {
+    if (value.length > MAX_COMPACT_DESCRIPTION_SCHEMA_BYTES) {
+        // This placeholder only participates in the byte check and is dropped whole.
+        return "x".repeat(MAX_COMPACT_DESCRIPTION_SCHEMA_BYTES + 1);
+    }
     return JSON.stringify(value).replaceAll("*/", "*\\/");
 }
 function constraintEntries(schema) {
@@ -416,17 +482,36 @@ function renderConstraints(base, schema, byteLimit, onTruncated) {
         : `${grouped(base)} /* ${kept.join("; ")} */`;
 }
 function renderSchema(schema, defs, seen, depth, options) {
+    options.work.visit();
+    return options.work.text(renderSchemaNode(schema, defs, seen, depth, options));
+}
+function renderSchemaNode(schema, defs, seen, depth, options) {
     if (depth > 4)
         return "…";
     if (schema === null || typeof schema !== "object") {
-        return JSON.stringify(schema);
+        return options.work.json(schema);
     }
     const s = schema;
     const constrain = (rendered) => options.renderConstraints
         ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
         : rendered;
+    // Conditions cannot be expressed by a single static shape. Preserve the
+    // base and send callers to the exact schema instead of hiding the rules.
+    if (s.dependentSchemas !== undefined || s.if !== undefined ||
+        s.then !== undefined || s.else !== undefined) {
+        options.work.truncated = true;
+        const base = Object.create(null);
+        for (const key of propertyNames(s, options.work)) {
+            if (!["dependentSchemas", "if", "then", "else"].includes(key))
+                base[key] = s[key];
+        }
+        const rendered = declaresShape(base)
+            ? renderSchema(base, defs, seen, depth, options)
+            : "unknown";
+        return `${rendered} /* conditional */`;
+    }
     // allOf composes rather than replaces: it is checked before every other
-    // keyword, and renders the schema's own shape alongside its members instead
+    // shape keyword, and renders the schema's own shape alongside its members instead
     // of returning early. A schema carrying both allOf and properties (the usual
     // OpenAPI-derived "extend this base" shape, and equally legal with $ref,
     // enum, const, or items) would otherwise silently drop whichever half lost
@@ -434,7 +519,11 @@ function renderSchema(schema, defs, seen, depth, options) {
     // specific half, and is rendered at the current depth because its members
     // sit at this nesting level, not one below.
     if (Array.isArray(s.allOf)) {
-        const { allOf: _members, ...own } = s;
+        const own = Object.create(null);
+        for (const key of propertyNames(s, options.work)) {
+            if (key !== "allOf")
+                own[key] = s[key];
+        }
         const parts = declaresShape(own)
             ? [renderSchema(own, defs, seen, depth, options)]
             : [];
@@ -447,16 +536,27 @@ function renderSchema(schema, defs, seen, depth, options) {
             return parts[0];
         return parts.map(grouped).join(" & ");
     }
-    if (typeof s.$ref === "string") {
-        const name = refName(s.$ref);
+    const reference = s.$ref ?? s.$dynamicRef;
+    if (typeof reference === "string") {
+        const dynamic = s.$ref === undefined;
+        const rawName = refName(options.work.text(reference));
+        const name = dynamic ? rawName.replace(/^#/, "") : rawName;
         if (seen.has(name))
             return name;
-        const target = defs[name];
-        if (target === undefined)
-            return name;
-        seen.add(name);
-        const rendered = renderSchema(target, defs, seen, depth, options);
-        seen.delete(name);
+        const target = resolveDefinition(defs, name);
+        if (target === undefined) {
+            if (dynamic)
+                options.work.truncated = true;
+            return dynamic ? "unknown" : name;
+        }
+        const cacheKey = JSON.stringify([name, depth, [...seen]]);
+        let rendered = options.work.refs.get(cacheKey);
+        if (rendered === undefined) {
+            seen.add(name);
+            rendered = renderSchema(target, defs, seen, depth, options);
+            seen.delete(name);
+            options.work.refs.set(cacheKey, rendered);
+        }
         return constrain(rendered);
     }
     const union = (s.oneOf ?? s.anyOf);
@@ -468,7 +568,7 @@ function renderSchema(schema, defs, seen, depth, options) {
         return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
-        const rendered = renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
+        const rendered = renderEnum(s.enum, options.work, options.enumByteLimit, options.onEnumTruncated);
         return constrain(rendered);
     }
     // Checked before type/properties so a discriminator like
@@ -476,10 +576,20 @@ function renderSchema(schema, defs, seen, depth, options) {
     // JSON.stringify(undefined) returns undefined (not a string), so an explicit
     // `const: undefined` must fall through to the regular type rendering.
     if (s.const !== undefined) {
-        const rendered = JSON.stringify(s.const);
+        const rendered = options.work.json(s.const);
         return constrain(rendered);
     }
     const type = s.type;
+    if (Array.isArray(s.prefixItems)) {
+        const parts = s.prefixItems.map((item) => renderSchema(item, defs, seen, depth + 1, options));
+        if (s.items !== false) {
+            const rest = s.items === undefined || s.items === true
+                ? "unknown"
+                : renderSchema(s.items, defs, seen, depth + 1, options);
+            parts.push(`...${grouped(rest)}[]`);
+        }
+        return `[${parts.join(", ")}]`;
+    }
     if (type === "array" || s.items) {
         const items = s.items
             ? renderSchema(s.items, defs, seen, depth + 1, options)
@@ -488,8 +598,8 @@ function renderSchema(schema, defs, seen, depth, options) {
     }
     if (type === "object" || s.properties) {
         const props = (s.properties ?? {});
-        const required = new Set((Array.isArray(s.required) ? s.required : []));
-        const declaredKeys = Object.keys(props);
+        const required = new Set(schemaRequired(s, options.work));
+        const declaredKeys = propertyNames(props, options.work);
         const keys = options.requiredFirst
             ? [
                 ...declaredKeys.filter((key) => required.has(key)),
@@ -503,6 +613,10 @@ function renderSchema(schema, defs, seen, depth, options) {
             const optional = required.has(key) ? "" : "?";
             const rendered = renderSchema(props[key], defs, seen, depth + 1, options);
             const description = props[key]?.description;
+            if (options.propertyDescriptions && typeof description === "string") {
+                options.work.text(description);
+            }
+            options.work.text(key);
             const comment = options.propertyDescriptions && typeof description === "string"
                 ? ` // ${description}`
                 : "";
@@ -511,43 +625,40 @@ function renderSchema(schema, defs, seen, depth, options) {
             .join(", ")} }`;
     }
     if (typeof type === "string") {
-        return constrain(type);
+        return constrain(options.work.text(type));
     }
     if (Array.isArray(type)) {
-        const rendered = type.join(" | ");
+        const rendered = type.map((item) => {
+            options.work.visit();
+            return options.work.text(String(item));
+        }).join(" | ");
         return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
         return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
     }
-    return JSON.stringify(schema);
+    return options.work.json(schema);
 }
 const compactSchemas = new WeakMap();
-function defsOf(schema) {
-    return {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+function resolveDefinition(schema, name) {
+    const definitions = schema.definitions;
+    const defs = schema.$defs;
+    return definitions && Object.hasOwn(definitions, name)
+        ? definitions[name]
+        : defs && Object.hasOwn(defs, name) ? defs[name] : undefined;
 }
 /** Render and cache a compact TypeScript-like representation of JSON Schema. */
 export function compactSchema(schema) {
+    return compactDescriptionSchema(schema).text;
+}
+/** Describe allows 8 KiB for property prose, with the same work cap as search. */
+export function compactDescriptionSchema(schema) {
     const cached = compactSchemas.get(schema);
     if (cached)
         return cached;
-    const defs = defsOf(schema);
-    let rendered;
-    try {
-        rendered = renderSchema(schema, defs, new Set(), 0, {
-            propertyDescriptions: true,
-            requiredFirst: false,
-            renderConstraints: true,
-        });
-    }
-    catch {
-        rendered = JSON.stringify(schema);
-    }
-    compactSchemas.set(schema, rendered);
-    return rendered;
+    const result = boundedCompactSchema(schema, true);
+    compactSchemas.set(schema, result);
+    return result;
 }
 const compactDiscoverySchemas = new WeakMap();
 /**
@@ -558,8 +669,12 @@ const compactDiscoverySchemas = new WeakMap();
  * Types become `unknown`: pretending a severed nested type is exact would be
  * worse than making the existing truncation flag's recovery route explicit.
  */
-function truncatedDiscoverySchema(schema) {
-    const keys = schemaObjectKeys(schema);
+function truncatedDiscoverySchema(schema, work) {
+    let keys;
+    try {
+        keys = objectKeys(schema, schema, new Set(), 0, work);
+    }
+    catch { /* An exhausted walk has no reliable key inventory. */ }
     if (!keys)
         return `unknown${COMPACT_DISCOVERY_TRUNCATION}`;
     const required = new Set(keys.required);
@@ -594,63 +709,44 @@ export function compactDiscoverySchema(schema) {
     const cached = compactDiscoverySchemas.get(schema);
     if (cached)
         return cached;
-    const defs = defsOf(schema);
-    let rendered;
-    let enumTruncated = false;
-    let constraintTruncated = false;
-    const base = {
-        propertyDescriptions: false,
-        requiredFirst: true,
-        enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-        onEnumTruncated: () => {
-            enumTruncated = true;
-        },
+    const result = boundedCompactSchema(schema, false);
+    compactDiscoverySchemas.set(schema, result);
+    return result;
+}
+function boundedCompactSchema(schema, description) {
+    const work = new SchemaWork(description ? MAX_COMPACT_DESCRIPTION_SCHEMA_BYTES : MAX_COMPACT_DISCOVERY_SCHEMA_BYTES);
+    const options = {
+        work,
+        propertyDescriptions: description,
+        requiredFirst: !description,
+        enumByteLimit: description ? work.byteLimit : MAX_COMPACT_DISCOVERY_ENUM_BYTES,
+        onEnumTruncated: () => { work.truncated = true; },
+        renderConstraints: true,
+        constraintByteLimit: description ? work.byteLimit : MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
+        onConstraintTruncated: () => { work.truncated = true; },
     };
     try {
-        rendered = renderSchema(schema, defs, new Set(), 0, {
-            ...base,
-            // 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.
-            renderConstraints: true,
-            constraintByteLimit: MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
-            onConstraintTruncated: () => {
-                constraintTruncated = true;
-            },
-        });
-    }
-    catch {
-        rendered = JSON.stringify(schema);
-    }
-    if (schemaEncoder.encode(rendered).length >
-        MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
-        try {
-            rendered = renderSchema(schema, defs, new Set(), 0, {
-                ...base,
-                renderConstraints: false,
-            });
-            constraintTruncated = true;
-        }
-        catch {
-            rendered = JSON.stringify(schema);
+        const text = renderSchema(schema, schema, new Set(), 0, options);
+        return { text, truncated: work.truncated };
+    }
+    catch (error) {
+        // A constraint-free retry shares the original work budget. Repeated refs
+        // are memoized only within each pass because their text includes constraints.
+        if (error === schemaSizeExceeded && !description) {
+            work.refs.clear();
+            try {
+                return {
+                    text: renderSchema(schema, schema, new Set(), 0, {
+                        ...options,
+                        renderConstraints: false,
+                    }),
+                    truncated: true,
+                };
+            }
+            catch { /* Fall through to a bounded key-only shape. */ }
         }
+        return { text: truncatedDiscoverySchema(schema, work), truncated: true };
     }
-    const bytes = schemaEncoder.encode(rendered);
-    let result;
-    if (bytes.length <= MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
-        result = {
-            text: rendered,
-            truncated: enumTruncated || constraintTruncated,
-        };
-    }
-    else {
-        result = {
-            text: truncatedDiscoverySchema(schema),
-            truncated: true,
-        };
-    }
-    compactDiscoverySchemas.set(schema, result);
-    return result;
 }
 /**
  * Walk a schema the way renderSchema does — composing `allOf` and resolving
@@ -669,9 +765,8 @@ export function compactDiscoverySchema(schema) {
 export function schemaObjectKeys(schema) {
     if (!schema)
         return undefined;
-    const defs = defsOf(schema);
     try {
-        return objectKeys(schema, defs, new Set(), 0);
+        return objectKeys(schema, schema, new Set(), 0, new SchemaWork());
     }
     catch {
         return undefined;
@@ -687,19 +782,27 @@ function mergedKeys(parts) {
     };
 }
 /** The key-collecting twin of renderSchema; the branch order must match it. */
-function objectKeys(schema, defs, seen, depth) {
+function objectKeys(schema, defs, seen, depth, work) {
+    work.visit();
     if (depth > 4)
         return undefined;
     if (schema === null || typeof schema !== "object")
         return undefined;
     const s = schema;
     if (Array.isArray(s.allOf)) {
-        const { allOf: _members, ...own } = s;
+        const own = Object.create(null);
+        for (const key of propertyNames(s, work)) {
+            if (key !== "allOf")
+                own[key] = s[key];
+        }
         const parts = declaresShape(own)
-            ? [objectKeys(own, defs, seen, depth)]
+            ? [objectKeys(own, defs, seen, depth, work)]
             : [];
         for (const member of s.allOf) {
-            parts.push(objectKeys(member, defs, seen, depth + 1));
+            const keys = objectKeys(member, defs, seen, depth + 1, work);
+            if (!keys)
+                return undefined;
+            parts.push(keys);
         }
         // An allOf whose members are not all object shapes renders as an
         // intersection with a non-object half; no single key list describes it.
@@ -707,15 +810,17 @@ function objectKeys(schema, defs, seen, depth) {
             ? mergedKeys(parts)
             : undefined;
     }
-    if (typeof s.$ref === "string") {
-        const name = refName(s.$ref);
+    const reference = s.$ref ?? s.$dynamicRef;
+    if (typeof reference === "string") {
+        const rawName = refName(work.text(reference));
+        const name = s.$ref === undefined ? rawName.replace(/^#/, "") : rawName;
         if (seen.has(name))
             return undefined;
-        const target = defs[name];
+        const target = resolveDefinition(defs, name);
         if (target === undefined)
             return undefined;
         seen.add(name);
-        const resolved = objectKeys(target, defs, seen, depth);
+        const resolved = objectKeys(target, defs, seen, depth, work);
         seen.delete(name);
         return resolved;
     }
@@ -725,19 +830,39 @@ function objectKeys(schema, defs, seen, depth) {
         return undefined;
     if (s.const !== undefined)
         return undefined;
-    if (s.type === "array" || s.items)
+    if (s.type === "array" || s.items || Array.isArray(s.prefixItems))
         return undefined;
     if (s.type === "object" || s.properties) {
         const props = s.properties;
         if (props === null || Array.isArray(props) || typeof props !== "object") {
             return { properties: [], required: [] };
         }
+        const properties = propertyNames(props, work);
+        const declared = new Set(properties);
         return {
-            properties: Object.keys(props),
-            required: Array.isArray(s.required)
-                ? s.required.filter((key) => typeof key === "string")
-                : [],
+            properties,
+            required: schemaRequired(s, work).filter((key) => declared.has(key)),
         };
     }
     return undefined;
 }
+function propertyNames(props, work) {
+    const names = [];
+    for (const name in props) {
+        work.visit();
+        if (Object.hasOwn(props, name))
+            names.push(work.text(name));
+    }
+    return names;
+}
+function schemaRequired(schema, work) {
+    if (!Array.isArray(schema.required))
+        return [];
+    const names = [];
+    for (const key of schema.required) {
+        work.visit();
+        if (typeof key === "string")
+            names.push(work.text(key));
+    }
+    return names;
+}

package/dist/connectors/api.d.ts

@@ -68,5 +68,5 @@ export interface ApiOptions {
     validateArgs?: boolean;
     tools: ApiTool[];
 }
-/** A static connector; see provider conventions' two construction-time checks. */
+/** A static connector; every tool passes {@link checkToolContract} first. */
 export declare function api(id: string, opts: ApiOptions): Connector;

package/dist/connectors/api.js

@@ -1,8 +1,17 @@
+import { ConnectorCallError, networkErrorCode, unavailableCallError, } from "../errors.js";
 import { compileValidator, validateToolInput } from "../validate.js";
 export function defined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
-/** Enforce provider conventions' two construction-time checks. */
+/**
+ * Three things a hand-written surface is refused for at construction rather
+ * than in production (#340): no description (discovery has nothing to route on
+ * and a guess costs a call), no explicit `readOnlyHint` (connecta never infers
+ * the safety class, so an unclassified tool is a deployment bug), and an
+ * `inputSchema` the validator cannot compile (declaring one is optional;
+ * declaring an unenforceable one is not). None of this reaches a proxied
+ * catalog — the contract binds the surfaces we write, not the ones we relay.
+ */
 function checkToolContract(id, tool) {
     const address = `${id}.${tool.name}`;
     if (typeof tool.description !== "string" || tool.description.trim() === "") {
@@ -19,7 +28,7 @@ function checkToolContract(id, tool) {
     if (tool.inputSchema)
         compileValidator(tool.inputSchema, { address });
 }
-/** A static connector; see provider conventions' two construction-time checks. */
+/** A static connector; every tool passes {@link checkToolContract} first. */
 export function api(id, opts) {
     for (const t of opts.tools)
         checkToolContract(id, t);
@@ -74,7 +83,16 @@ export function api(id, opts) {
             // its first await never sits handler-less for the thenable-adoption
             // microtask — workerd and vitest both report that gap as an unhandled
             // rejection even though the caller catches the failure.
-            return await tool.handler(input, ctx);
+            try {
+                return await tool.handler(input, ctx);
+            }
+            catch (error) {
+                // A handler owns its destinations. ctx.baseUrl is Connecta's inbound
+                // URL, so it must never masquerade as the failed downstream host.
+                if (error instanceof ConnectorCallError || !networkErrorCode(error))
+                    throw error;
+                throw unavailableCallError(error);
+            }
         },
     };
 }

package/dist/connectors/guarded-fetch.d.ts

@@ -51,7 +51,7 @@ interface GuardedResponse {
         parseError: unknown;
     }>;
 }
-/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export declare function retryAfterMs(headers: Headers): number | undefined;
 /**
  * Turn one response into the provider's own result, or throw the provider's
@@ -87,6 +87,10 @@ export interface GuardedFetchOptions {
 }
 /** Send one guarded request and map its response with provider knowledge. */
 export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
-/** Build the guarded transport described in documentation/connectors.md. */
+/**
+ * Build the transport a connector sends every request through. `maxResponseBytes`
+ * is required rather than defaulted: what counts as an absurd response is a fact
+ * about the API, not about HTTP.
+ */
 export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
 export {};