@zackbart/connecta 0.18.3 → 0.20.0

package/dist/catalog-service.js

@@ -2,7 +2,7 @@ import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexical
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withDeadline, } from "./timeout.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
@@ -261,10 +261,13 @@ export class CatalogService {
         return loading;
     }
     loadForDiscovery(id, label) {
-        return withAbortableTimeout((signal) => this.loadConnector(id, {
+        return withDeadline((signal) => this.loadConnector(id, {
             signal,
             timeoutMs: this.probeTimeoutMs,
-        }), this.probeTimeoutMs, label);
+        }), {
+            timeoutMs: this.probeTimeoutMs,
+            timeoutError: new Error(`${label} timed out after ${this.probeTimeoutMs}ms`),
+        });
     }
     outputSchema(connectorId, tool) {
         if (tool.outputSchema)
@@ -274,17 +277,42 @@ export class CatalogService {
             ? { schema: observed, source: "observed" }
             : {};
     }
+    unknownAddressFailure(address, query) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(query) }, "Find the configured canonical address before retrying."),
+            },
+            catalogMs: 0,
+        };
+    }
+    catalogLoadFailure(cause, started, connector, toolName) {
+        return {
+            ok: false,
+            error: classifyCallError(cause, "catalog_lookup_failed"),
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+            cause,
+        };
+    }
+    unknownToolFailure(toolName, connector, started) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
+            },
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+        };
+    }
     async resolveTool(address, callOptions = {}) {
         const resolved = this.registry.resolveAddress(address);
         if (!resolved) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(address, address);
         }
         const started = Date.now();
         let tools;
@@ -292,30 +320,11 @@ export class CatalogService {
             tools = await this.loadConnector(resolved.connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, resolved.connector, resolved.toolName);
         }
         const definition = tools.find((tool) => tool.name === resolved.toolName);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(resolved.toolName)}" on connector "${resolved.connector.id}"`),
-                    nextAction: this.searchRecovery({
-                        query: recoveryQuery(resolved.toolName),
-                        connector: resolved.connector.id,
-                    }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-            };
+            return this.unknownToolFailure(resolved.toolName, resolved.connector, started);
         }
         return {
             ok: true,
@@ -335,14 +344,7 @@ export class CatalogService {
     async resolveToolAlias(connectorId, alias, aliasFor, callOptions = {}) {
         const connector = this.registry.getConnector(connectorId);
         if (!connector) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(`${connectorId}.${alias}`)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(`${connectorId}.${alias}`, alias);
         }
         const started = Date.now();
         let tools;
@@ -350,27 +352,11 @@ export class CatalogService {
             tools = await this.loadConnector(connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, connector, alias);
         }
         const [definition, ...collisions] = tools.filter((tool) => aliasFor(tool.name) === alias);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(alias)}" on connector "${connector.id}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias), connector: connector.id }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-            };
+            return this.unknownToolFailure(alias, connector, started);
         }
         if (collisions.length > 0) {
             const names = [definition, ...collisions]
@@ -494,18 +480,19 @@ export class CatalogService {
                 a.order - b.order);
         });
         const pageMatches = matches.slice(offset, offset + limit);
+        const withSchemas = args.includeSchemas;
         const entries = pageMatches.map((match) => {
-            const output = args.includeSchemas
+            const output = withSchemas
                 ? this.outputSchema(match.connector.id, match.tool)
                 : {};
             const input = match.tool.inputSchema ?? { type: "object" };
-            const renderedInput = args.includeSchemas
-                ? renderSearchSchema(input, args.includeSchemas)
+            const renderedInput = withSchemas
+                ? renderSearchSchema(input, withSchemas)
                 : undefined;
-            const renderedOutput = args.includeSchemas && output.schema
-                ? renderSearchSchema(output.schema, args.includeSchemas)
+            const renderedOutput = withSchemas && output.schema
+                ? renderSearchSchema(output.schema, withSchemas)
                 : undefined;
-            const schemaKeys = args.includeSchemas && args.includeSchemaKeys
+            const schemaKeys = withSchemas && args.includeSchemaKeys
                 ? schemaKeyMetadata(input, output.schema)
                 : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
@@ -523,7 +510,7 @@ export class CatalogService {
                     name: match.tool.name,
                     address: `${match.connector.id}.${match.tool.name}`,
                     ...(description !== undefined ? { description } : {}),
-                    ...(args.includeSchemas
+                    ...(withSchemas
                         ? {
                             inputSchema: renderedInput?.schema,
                         }
@@ -531,12 +518,12 @@ export class CatalogService {
                     ...(renderedInput?.truncated
                         ? { inputSchemaTruncated: true }
                         : {}),
-                    ...(args.includeSchemas && output.schema
+                    ...(withSchemas && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
                         : {}),
-                    ...(args.includeSchemas && output.source
+                    ...(withSchemas && output.source
                         ? { outputSchemaSource: output.source }
                         : {}),
                     ...(renderedOutput?.truncated
@@ -671,41 +658,46 @@ export class CatalogService {
             (queryTerms.length > 0
                 ? matchMode === "partial"
                 : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
-        const guidance = unsearchableQuery
-            ? (unknownConnectorGuidance ??
-                (scopedConnector && unavailableCatalogs > 0
+        const searchGuidance = () => {
+            if (unknownConnectorGuidance)
+                return unknownConnectorGuidance;
+            if (unsearchableQuery) {
+                return 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
-                    // dead end that looks like a connector with no tools.
-                    (unknownConnectorGuidance ??
-                        (unavailableCatalogs === 0
-                            ? undefined
-                            : scopedConnector
-                                ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                                : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`))
-                : matches.length === 0
-                    ? (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.`
-                                : scopedGuide?.required
-                                    ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
-                                    : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
-                            : (identityGuidance ??
-                                (unavailableCatalogs === 0
-                                    ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
-                                    : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`))))
-                    : matchMode === "partial"
-                        ? scopedConnector
-                            ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
-                            : unavailableCatalogs === 0
-                                ? "No single tool matched every term. Split distinct intents into separate searches."
-                                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches."
-                        : undefined;
+                    : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query.";
+            }
+            if (queryTerms.length === 0) {
+                if (unavailableCatalogs === 0)
+                    return undefined;
+                return scopedConnector
+                    ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                    : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`;
+            }
+            if (matches.length === 0) {
+                if (scopedConnector) {
+                    if (unavailableCatalogs > 0) {
+                        return `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`;
+                    }
+                    return scopedGuide?.required
+                        ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
+                        : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`;
+                }
+                if (identityGuidance)
+                    return identityGuidance;
+                return unavailableCatalogs === 0
+                    ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                    : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`;
+            }
+            if (matchMode !== "partial")
+                return undefined;
+            if (scopedConnector) {
+                return `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`;
+            }
+            return unavailableCatalogs === 0
+                ? "No single tool matched every term. Split distinct intents into separate searches."
+                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches.";
+        };
+        const guidance = searchGuidance();
         return {
             entries,
             total: matches.length,
@@ -859,6 +851,17 @@ export class CatalogService {
         });
     }
 }
+function pageTail(page) {
+    return {
+        total: page.total,
+        offset: page.offset,
+        limit: page.limit,
+        hasMore: page.hasMore,
+        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
+        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+    };
+}
 export function groupedSearchResult(page) {
     const groups = [];
     const byConnector = new Map();
@@ -884,13 +887,7 @@ export function groupedSearchResult(page) {
     }
     return {
         connectors: groups,
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }
 export function flatSearchResult(page) {
@@ -902,12 +899,6 @@ export function flatSearchResult(page) {
                 ? { guideSummary: entry.guideSummary }
                 : {}),
         })),
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }

package/dist/catalog.js

@@ -123,9 +123,6 @@ function indexFor(tools) {
     }
     return index;
 }
-function documentsFor(tools) {
-    return indexFor(tools).documents;
-}
 /**
  * Whole-token equality is the ordinary lexical match. A deliberately narrow
  * inflection check retains useful singular/plural and past-tense recall
@@ -293,7 +290,7 @@ export function rankTools(tools, query, mode = "all", statistics = lexicalCorpus
     const exactNamePhrase = normalized(exactNameQuery);
     const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
     const ranked = [];
-    documentsFor(tools).forEach((doc, order) => {
+    indexFor(tools).documents.forEach((doc, order) => {
         const scored = scoreDocument(doc, phrase, terms, mode, statistics);
         if (scored !== null) {
             ranked.push({
@@ -425,6 +422,9 @@ function renderSchema(schema, defs, seen, depth, options) {
         return JSON.stringify(schema);
     }
     const s = schema;
+    const constrain = (rendered) => options.renderConstraints
+        ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+        : rendered;
     // allOf composes rather than replaces: it is checked before every other
     // keyword, and renders the schema's own shape alongside its members instead
     // of returning early. A schema carrying both allOf and properties (the usual
@@ -457,9 +457,7 @@ function renderSchema(schema, defs, seen, depth, options) {
         seen.add(name);
         const rendered = renderSchema(target, defs, seen, depth, options);
         seen.delete(name);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     const union = (s.oneOf ?? s.anyOf);
     if (Array.isArray(union)) {
@@ -467,15 +465,11 @@ function renderSchema(schema, defs, seen, depth, options) {
             .map((u) => renderSchema(u, defs, seen, depth + 1, options))
             .join(" | ") ||
             "unknown";
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
         const rendered = renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     // Checked before type/properties so a discriminator like
     // { type: "string", const: "emoji" } renders as "emoji" rather than string.
@@ -483,9 +477,7 @@ function renderSchema(schema, defs, seen, depth, options) {
     // `const: undefined` must fall through to the regular type rendering.
     if (s.const !== undefined) {
         const rendered = JSON.stringify(s.const);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     const type = s.type;
     if (type === "array" || s.items) {
@@ -519,15 +511,11 @@ function renderSchema(schema, defs, seen, depth, options) {
             .join(", ")} }`;
     }
     if (typeof type === "string") {
-        return options.renderConstraints
-            ? renderConstraints(type, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : type;
+        return constrain(type);
     }
     if (Array.isArray(type)) {
         const rendered = type.join(" | ");
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
         return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
@@ -535,15 +523,18 @@ function renderSchema(schema, defs, seen, depth, options) {
     return JSON.stringify(schema);
 }
 const compactSchemas = new WeakMap();
+function defsOf(schema) {
+    return {
+        ...schema.$defs,
+        ...schema.definitions,
+    };
+}
 /** Render and cache a compact TypeScript-like representation of JSON Schema. */
 export function compactSchema(schema) {
     const cached = compactSchemas.get(schema);
     if (cached)
         return cached;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    const defs = defsOf(schema);
     let rendered;
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
@@ -603,24 +594,24 @@ export function compactDiscoverySchema(schema) {
     const cached = compactDiscoverySchemas.get(schema);
     if (cached)
         return cached;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    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;
+        },
+    };
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
-            propertyDescriptions: false,
-            requiredFirst: true,
+            ...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.
-            enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-            onEnumTruncated: () => {
-                enumTruncated = true;
-            },
             renderConstraints: true,
             constraintByteLimit: MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
             onConstraintTruncated: () => {
@@ -635,12 +626,7 @@ export function compactDiscoverySchema(schema) {
         MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
         try {
             rendered = renderSchema(schema, defs, new Set(), 0, {
-                propertyDescriptions: false,
-                requiredFirst: true,
-                enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-                onEnumTruncated: () => {
-                    enumTruncated = true;
-                },
+                ...base,
                 renderConstraints: false,
             });
             constraintTruncated = true;
@@ -683,10 +669,7 @@ export function compactDiscoverySchema(schema) {
 export function schemaObjectKeys(schema) {
     if (!schema)
         return undefined;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    const defs = defsOf(schema);
     try {
         return objectKeys(schema, defs, new Set(), 0);
     }

package/dist/connector-scope.js

@@ -1,3 +1,4 @@
+import { sleep } from "./timeout.js";
 /** Enough for local transport abort/close without letting cleanup own latency. */
 const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
 /**
@@ -11,13 +12,7 @@ const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
 const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
 /** Resolve when `work` settles or `budgetMs` expires; never reject. */
 function waitAtMost(work, budgetMs) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, budgetMs);
-        work.then(() => {
-            clearTimeout(timer);
-            resolve();
-        });
-    });
+    return Promise.race([work, sleep(budgetMs)]).then(() => { });
 }
 /**
  * Tell a connector that a scope owned by the core has ended.

package/dist/connectors/api.d.ts

@@ -1,4 +1,7 @@
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorCredentialConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, CredentialTestResult, JsonSchema, ToolAnnotations } from "../types.js";
+export declare function defined<T extends object>(value: T): {
+    [K in keyof T]?: Exclude<T[K], undefined>;
+};
 export interface ApiTool {
     name: string;
     /**
@@ -63,20 +66,5 @@ export interface ApiOptions {
     validateArgs?: boolean;
     tools: ApiTool[];
 }
-/**
- * A connector defined entirely in code: static tool defs + fetch handlers.
- * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
- * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
- *
- * Every tool declares a description and an explicit `annotations.readOnlyHint`,
- * and any `inputSchema` it carries must compile — a tool that fails the
- * contract throws here rather than reaching a catalog. Arguments are then
- * validated against `inputSchema` before the handler runs (disable with
- * `validateArgs: false`, which opts out of enforcement, not out of the schema
- * being real), and a schema that only reveals itself as unenforceable on first
- * use — an unresolvable `$ref`, say — fails the call rather than passing raw
- * arguments through. Remote MCP inputs are also validated, but in the shared
- * invocation path against the request-local downstream catalog, where a
- * downstream's schema is its own affair and stays fail-open.
- */
+/** A static connector; see provider conventions' two construction-time checks. */
 export declare function api(id: string, opts: ApiOptions): Connector;

package/dist/connectors/api.js

@@ -1,14 +1,8 @@
 import { compileValidator, validateToolInput } from "../validate.js";
-/**
- * Enforce the construction contract for one hand-written tool.
- *
- * Everything here is something only the author can supply and no runtime can
- * guess: what the tool does, and whether calling it needs a human's blessing.
- * Guessing either one is how a deployment boots into the wrong shape, so this
- * throws instead. Note what it does *not* do — it never reads a name, verb, or
- * HTTP method to infer a safety class. An unclassified tool is a bug in the
- * deployment, not a puzzle for connecta to solve.
- */
+export function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+/** Enforce provider conventions' two construction-time checks. */
 function checkToolContract(id, tool) {
     const address = `${id}.${tool.name}`;
     if (typeof tool.description !== "string" || tool.description.trim() === "") {
@@ -25,55 +19,34 @@ function checkToolContract(id, tool) {
     if (tool.inputSchema)
         compileValidator(tool.inputSchema, { address });
 }
-/**
- * A connector defined entirely in code: static tool defs + fetch handlers.
- * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
- * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
- *
- * Every tool declares a description and an explicit `annotations.readOnlyHint`,
- * and any `inputSchema` it carries must compile — a tool that fails the
- * contract throws here rather than reaching a catalog. Arguments are then
- * validated against `inputSchema` before the handler runs (disable with
- * `validateArgs: false`, which opts out of enforcement, not out of the schema
- * being real), and a schema that only reveals itself as unenforceable on first
- * use — an unresolvable `$ref`, say — fails the call rather than passing raw
- * arguments through. Remote MCP inputs are also validated, but in the shared
- * invocation path against the request-local downstream catalog, where a
- * downstream's schema is its own affair and stays fail-open.
- */
+/** A static connector; see provider conventions' two construction-time checks. */
 export function api(id, opts) {
     for (const t of opts.tools)
         checkToolContract(id, t);
     const defs = opts.tools.map((t) => ({
         name: t.name,
         description: t.description,
-        ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
-        ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
+        ...defined({
+            inputSchema: t.inputSchema,
+            outputSchema: t.outputSchema,
+        }),
         annotations: t.annotations,
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
     return {
         id,
-        ...(opts.title !== undefined ? { title: opts.title } : {}),
+        ...defined({ title: opts.title }),
         kind: "api",
-        ...(opts.description !== undefined
-            ? { description: opts.description }
-            : {}),
-        ...(opts.maxResultBytes !== undefined
-            ? { maxResultBytes: opts.maxResultBytes }
-            : {}),
-        ...(opts.callAdmission !== undefined
-            ? { callAdmission: opts.callAdmission }
-            : {}),
-        ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
-        ...(opts.credential !== undefined ? { credential: opts.credential } : {}),
-        ...(opts.testCredential !== undefined
-            ? { testCredential: opts.testCredential }
-            : {}),
-        ...(opts.testCredentials !== undefined
-            ? { testCredentials: opts.testCredentials }
-            : {}),
+        ...defined({
+            description: opts.description,
+            maxResultBytes: opts.maxResultBytes,
+            callAdmission: opts.callAdmission,
+            usageGuide: opts.usageGuide,
+            credential: opts.credential,
+            testCredential: opts.testCredential,
+            testCredentials: opts.testCredentials,
+        }),
         staticTools: defs,
         async listTools() {
             return defs;