@zackbart/connecta 0.15.1 → 0.16.1

package/dist/catalog-drift.js

@@ -0,0 +1,251 @@
+// Web-API only, like the rest of the core: a manifest comparison that ran on
+// Node but not on Workers would leave half the deployments unable to tell a
+// stale allowlist from a current one.
+import { boundedEchoText } from "./errors.js";
+/**
+ * Byte budget for the one string a drift report carries. An ISO timestamp is
+ * 24 bytes; anything near this bound is a plugin sending something else.
+ */
+const MAX_OBSERVED_AT_BYTES = 64;
+/** A count, or 0 when the seam returned something that is not one. */
+function boundedCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.trunc(value))
+        : 0;
+}
+/**
+ * Rebuild a drift report as four counts and a bounded timestamp.
+ *
+ * `Connector.catalogDrift()` sits on the open plugin seam, and what it returns
+ * lands in the body of unauthenticated `/health` and on connector status.
+ * TypeScript constrains neither an extra enumerable property nor the length of
+ * `observedAt` at runtime, so "counts and nothing else" is *made* true here —
+ * at the boundary where third-party output becomes a response — rather than
+ * trusted. The activity path reconstructs its five fields for the same reason.
+ */
+export function boundedCatalogDrift(report) {
+    if (!report || typeof report !== "object")
+        return undefined;
+    return {
+        observedAt: boundedEchoText(typeof report.observedAt === "string" ? report.observedAt : "", MAX_OBSERVED_AT_BYTES),
+        unclassifiedTools: boundedCount(report.unclassifiedTools),
+        unservedTools: boundedCount(report.unservedTools),
+        annotationConflicts: boundedCount(report.annotationConflicts),
+        schemaChanges: boundedCount(report.schemaChanges),
+    };
+}
+const encoder = new TextEncoder();
+/** Deterministic JSON: object keys sorted, so key order is not a schema change. */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value === null || typeof value !== "object")
+        return value;
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item)]));
+}
+/**
+ * Digest the schemas of one downstream tool.
+ *
+ * Canonical rather than literal, unlike the catalog fingerprint in
+ * `src/catalog-fingerprint.ts`: that one is deliberately conservative because a
+ * spurious cache write is cheap, while a spurious drift finding spends a
+ * maintainer's attention on a downstream that reordered its JSON keys.
+ * Description and annotations are excluded — a reworded description is P1's
+ * business, and an annotation change is already its own drift category.
+ */
+export async function vettedSchemaDigest(tool) {
+    const bytes = encoder.encode(JSON.stringify(canonicalize({
+        inputSchema: tool.inputSchema ?? null,
+        outputSchema: tool.outputSchema ?? null,
+    })));
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return `sha256:${[...digest]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+/**
+ * Build a provider's manifest from the lists it already maintains.
+ *
+ * Throws when a name is classified twice, because a tool that is both a read
+ * and a write is a review mistake that must not boot: the annotation the
+ * connector would apply depends on which branch runs first, and "safe by
+ * default" cannot be decided by ordering.
+ */
+export function vettedCatalog(input) {
+    const tools = new Map();
+    const digestFor = (name) => input.schemaDigests?.[name];
+    for (const name of input.reads) {
+        const digest = digestFor(name);
+        tools.set(name, {
+            verdict: "read-only",
+            ...(digest !== undefined ? { schemaDigest: digest } : {}),
+        });
+    }
+    for (const [name, verdict] of input.writes) {
+        if (tools.has(name)) {
+            throw new Error(`vettedCatalog() classified "${name}" as both a read and a write.`);
+        }
+        const digest = digestFor(name);
+        tools.set(name, {
+            verdict,
+            ...(digest !== undefined ? { schemaDigest: digest } : {}),
+        });
+    }
+    for (const name of Object.keys(input.schemaDigests ?? {})) {
+        if (!tools.has(name)) {
+            throw new Error(`vettedCatalog() recorded a schema digest for unclassified tool "${name}".`);
+        }
+    }
+    return { version: 1, tools };
+}
+/**
+ * Fill in downstream silence; keep reviewed destructive tools fail-closed.
+ *
+ * Silence is what a vetted classification is for, and an explicit downstream
+ * annotation otherwise wins in both directions. `destructiveHint: true` or
+ * `readOnlyHint: false` on a classified read is the downstream telling us this
+ * release's allowlist is stale; `readOnlyHint: true` on a name no release has
+ * classified says the same thing from the other side. The single place a
+ * vetted verdict still overrides the downstream is a name this release
+ * reviewed and filed destructive: there connecta knows what the tool does, and
+ * a claim to the contrary is a downstream bug rather than news
+ * ([#310](https://github.com/zackbart/connecta/issues/310),
+ * [#315](https://github.com/zackbart/connecta/issues/315)).
+ */
+function applyVettedSafety(catalog, definition) {
+    const downstream = definition.annotations ?? {};
+    const record = catalog.tools.get(definition.name);
+    if (record?.verdict === "read-only") {
+        if (downstream.destructiveHint === true ||
+            downstream.readOnlyHint === false) {
+            return definition;
+        }
+        return {
+            ...definition,
+            annotations: {
+                ...downstream,
+                readOnlyHint: true,
+                destructiveHint: downstream.destructiveHint ?? false,
+            },
+        };
+    }
+    if (record?.verdict === "destructive") {
+        return {
+            ...definition,
+            annotations: {
+                ...downstream,
+                readOnlyHint: false,
+                destructiveHint: true,
+            },
+        };
+    }
+    // Maintained additive creates and tools this release has never seen land
+    // here alike. Fill-in only: a silent tool is not read-only, so drift still
+    // fails closed onto `call_destructive_tool`, and neither population gets a
+    // `destructiveHint` it has not earned. A tool that arrives explicitly
+    // read-only keeps that annotation — on a name no release has reviewed, the
+    // downstream's own word is the only evidence there is, and rewriting it
+    // would be an overrule rather than a fill-in.
+    return {
+        ...definition,
+        annotations: {
+            ...downstream,
+            readOnlyHint: downstream.readOnlyHint ?? false,
+        },
+    };
+}
+/**
+ * Whether the downstream's own annotation contradicts what a release reviewed.
+ *
+ * Only an *explicit* contradiction counts. Silence is the ordinary case the
+ * classification exists to fill, and an unclassified tool is already counted
+ * as an addition rather than twice.
+ */
+function contradicts(record, definition) {
+    const downstream = definition.annotations ?? {};
+    if (record.verdict === "read-only") {
+        return (downstream.readOnlyHint === false || downstream.destructiveHint === true);
+    }
+    return downstream.readOnlyHint === true;
+}
+/**
+ * Compare a live catalog with the manifest and count what moved.
+ *
+ * Counts only, and by construction: there is nowhere here to put a tool name,
+ * a schema, or a downstream string, so no later surface has to remember to
+ * strip one. Reads nothing but the tools it was handed — the caller already
+ * fetched them to serve a request, and this function never fetches anything.
+ */
+export async function detectCatalogDrift(catalog, tools) {
+    let unclassifiedTools = 0;
+    let annotationConflicts = 0;
+    let schemaChanges = 0;
+    const served = new Set();
+    for (const definition of tools) {
+        served.add(definition.name);
+        const record = catalog.tools.get(definition.name);
+        if (!record) {
+            unclassifiedTools += 1;
+            continue;
+        }
+        if (contradicts(record, definition))
+            annotationConflicts += 1;
+        // A manifest that recorded no digest for this tool cannot have an opinion
+        // about its schema, so it does not pay for a hash either.
+        if (record.schemaDigest !== undefined &&
+            record.schemaDigest !== (await vettedSchemaDigest(definition))) {
+            schemaChanges += 1;
+        }
+    }
+    let unservedTools = 0;
+    for (const name of catalog.tools.keys()) {
+        if (!served.has(name))
+            unservedTools += 1;
+    }
+    return {
+        unclassifiedTools,
+        unservedTools,
+        annotationConflicts,
+        schemaChanges,
+    };
+}
+/**
+ * Wrap a hosted-MCP connector in its vetted manifest: the classification the
+ * catalog is normalized with, and the drift check that rides the same listing.
+ *
+ * The check happens where the tools are already in hand and still unmodified —
+ * after the downstream answered, before the classification is applied. It adds
+ * no request of its own, which is the whole boundary: connecta watches a
+ * contract while it is serving a refresh the deployment asked for, and never
+ * initiates one to go looking ([#179](https://github.com/zackbart/connecta/issues/179),
+ * [#343](https://github.com/zackbart/connecta/issues/343)).
+ */
+export function withVettedCatalog(connector, catalog) {
+    let observed;
+    return {
+        ...connector,
+        async listTools(ctx) {
+            const downstream = await connector.listTools(ctx);
+            try {
+                observed = {
+                    observedAt: new Date().toISOString(),
+                    ...(await detectCatalogDrift(catalog, downstream)),
+                };
+            }
+            catch (error) {
+                // A drift check is a report about a catalog, never a condition for
+                // serving one. Keep the last good observation rather than replacing it
+                // with a lie, and let the refresh through.
+                ctx.logger.warn(`[connecta] connector "${connector.id}" catalog drift check failed: ` +
+                    (error instanceof Error ? error.message : String(error)));
+            }
+            return downstream.map((definition) => applyVettedSafety(catalog, definition));
+        },
+        catalogDrift() {
+            return observed;
+        },
+    };
+}

package/dist/catalog-fingerprint.d.ts

@@ -17,4 +17,3 @@ export declare function fingerprintSerializedCatalog(serializedTools: string): P
  * any serialized field must change the digest.
  */
 export declare function snapshotCatalog(tools: ToolDef[]): Promise<CatalogSnapshot>;
-//# sourceMappingURL=catalog-fingerprint.d.ts.map

package/dist/catalog-fingerprint.js

@@ -31,4 +31,3 @@ export async function snapshotCatalog(tools) {
         serializedBytes: bytes,
     };
 }
-//# sourceMappingURL=catalog-fingerprint.js.map

package/dist/catalog-limits.d.ts

@@ -7,4 +7,3 @@ export declare const MAX_CATALOG_TOOLS = 100000;
 export declare const MAX_SERIALIZED_CATALOG_BYTES: number;
 /** Persisted values stay comfortably below platform per-value limits. */
 export declare const MAX_CATALOG_CHUNK_BYTES: number;
-//# sourceMappingURL=catalog-limits.d.ts.map

package/dist/catalog-limits.js

@@ -7,4 +7,3 @@ export const MAX_CATALOG_TOOLS = 100_000;
 export const MAX_SERIALIZED_CATALOG_BYTES = 32 * 1024 * 1024;
 /** Persisted values stay comfortably below platform per-value limits. */
 export const MAX_CATALOG_CHUNK_BYTES = 1024 * 1024;
-//# sourceMappingURL=catalog-limits.js.map

package/dist/catalog-service.d.ts

@@ -247,4 +247,3 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
     hasMore: boolean;
 };
 export {};
-//# sourceMappingURL=catalog-service.d.ts.map

package/dist/catalog-service.js

@@ -1,4 +1,4 @@
-import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
+import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
@@ -10,6 +10,12 @@ export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
 const MAX_QUERY_TERMS = 8;
 const MAX_QUERY_TERM_LENGTH = 64;
+/**
+ * Connector IDs a no-match search will name back. Three is enough to point at
+ * the connector the query already named without turning a miss into a listing
+ * of the deployment.
+ */
+const MAX_IDENTITY_CONNECTORS = 3;
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -561,6 +567,36 @@ export class CatalogService {
                 required: connectorGuideRequired(scopedConnector),
             }
             : undefined;
+        // A connector's own id — the address prefix the caller already has — and
+        // the title it is displayed under are the most natural first query terms,
+        // and neither is a document in the lexical index. Indexing them would move
+        // ranking for every query that already matches tools, so instead a search
+        // that matched nothing asks the same lexical question of connector
+        // identity and corrects its own sentence: the deployment plainly has this
+        // capability, and one scoped browse away are its tools. Unscoped only —
+        // guidance for an explicit scope already names that connector rather than
+        // claiming the deployment has nothing.
+        const identityConnectorIds = matches.length === 0 && !isBrowse && !unsearchableQuery && !scopedConnector
+            ? connectors
+                // The full query, not `analyzedTerms`: that cap exists to bound
+                // the serialized term fields, and ranking already reads every
+                // term. A ninth term is a real search term, and a search that
+                // ranked against it must not deny the connector it names.
+                .filter((connector) => queryTerms.some((term) => matchesLexicalTerm(connector.id, term) ||
+                (connector.title !== undefined &&
+                    matchesLexicalTerm(connector.title, term))))
+                .map((connector) => connector.id)
+            : [];
+        const namedIdentityConnectors = identityConnectorIds
+            .slice(0, MAX_IDENTITY_CONNECTORS)
+            .map((id) => `"${id}"`)
+            .join(", ");
+        const unnamedIdentityConnectors = identityConnectorIds.length - MAX_IDENTITY_CONNECTORS;
+        const identityGuidance = identityConnectorIds.length === 0
+            ? undefined
+            : `No matching ${safetyLabel}capability was found${unavailableCatalogs === 0 ? "" : " in the catalogs that answered"}, but the query names configured connector${identityConnectorIds.length === 1 ? "" : "s"} ${namedIdentityConnectors}${unnamedIdentityConnectors > 0
+                ? ` and ${unnamedIdentityConnectors} more`
+                : ""}. Scope by connector and browse with an empty query to list the tools there.${filterRecovery}`;
         // A scope that resolved to nothing is the same silence one step earlier in
         // the lookup: no connector resolved, so no catalog was even attempted, so
         // no catalog failed and the unavailable path below never fires. Echo only
@@ -604,9 +640,10 @@ export class CatalogService {
                                 : 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}`
-                            : 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}`))
+                            : (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.`
@@ -786,4 +823,3 @@ export function flatSearchResult(page) {
         ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
     };
 }
-//# sourceMappingURL=catalog-service.js.map

package/dist/catalog.d.ts

@@ -18,6 +18,17 @@ export interface RankedTool {
     exactName: boolean;
     matchedTermCount: number;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export declare function matchesLexicalTerm(text: string, term: string): boolean;
 export interface LexicalCorpusStatistics {
     documentCount: number;
     documentFrequency: ReadonlyMap<string, number>;
@@ -72,4 +83,3 @@ export interface SchemaObjectKeys {
  * fields.
  */
 export declare function schemaObjectKeys(schema: JsonSchema | undefined): SchemaObjectKeys | undefined;
-//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -166,6 +166,26 @@ function matchingTokenCandidates(term) {
     }
     return candidates;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export function matchesLexicalTerm(text, term) {
+    const tokens = new Set(lexicalTokens(text));
+    if (tokens.size === 0)
+        return false;
+    for (const candidate of matchingTokenCandidates(term)) {
+        if (tokens.has(candidate))
+            return true;
+    }
+    return false;
+}
 /**
  * Compute query-specific document frequencies across every available catalog.
  * The caller does this once per search and shares the result with each
@@ -636,4 +656,3 @@ function objectKeys(schema, defs, seen, depth) {
     }
     return undefined;
 }
-//# sourceMappingURL=catalog.js.map

package/dist/concurrency.d.ts

@@ -1,4 +1,3 @@
 export declare function resolveDiscoveryConcurrency(value: number | undefined): number;
 /** Run `fn` over `items` with at most `limit` operations in flight. */
 export declare function mapSettledWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]>;
-//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.js

@@ -28,4 +28,3 @@ export async function mapSettledWithConcurrency(items, limit, fn) {
     await Promise.all(workers);
     return settled;
 }
-//# sourceMappingURL=concurrency.js.map

package/dist/connector-scope.d.ts

@@ -13,4 +13,3 @@ export type DeferredWork = (promise: Promise<unknown>) => void;
  * again after this returns.
  */
 export declare function closeConnectorScope(connector: Connector, ctx: ConnectorContext, defer?: DeferredWork): Promise<void>;
-//# sourceMappingURL=connector-scope.d.ts.map

package/dist/connector-scope.js

@@ -52,4 +52,3 @@ export async function closeConnectorScope(connector, ctx, defer) {
         // The scope is over whether or not the connector managed to clean it up.
     }
 }
-//# sourceMappingURL=connector-scope.js.map

package/dist/connectors/api.d.ts

@@ -1,16 +1,30 @@
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorCredentialConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, CredentialTestResult, JsonSchema, ToolAnnotations } from "../types.js";
 export interface ApiTool {
     name: string;
-    description?: string;
-    /** A plain JSON Schema object describing the tool input. */
+    /**
+     * Required, non-empty. Discovery has nothing else to go on: a nameless
+     * capability costs the agent a guess, and a guess costs a wrong call.
+     */
+    description: string;
+    /**
+     * A plain JSON Schema object describing the tool input. Optional, but what
+     * you supply must be a schema the validator can compile — `api()` refuses to
+     * construct otherwise.
+     */
     inputSchema?: JsonSchema;
     /** A plain JSON Schema object describing the tool's structured output. */
     outputSchema?: JsonSchema;
     /**
-     * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
-     * admits the tool to call_tool and execute_code.
+     * Standard MCP-style behavior hints, with an explicit `readOnlyHint`
+     * required: `true` declares a read and admits the tool to call_tool and
+     * execute_code, `false` declares work that must cross
+     * `call_destructive_tool` where a host can ask a human. Connecta never
+     * infers the classification from a name, a description, a schema, or the
+     * other annotations.
      */
-    annotations?: ToolAnnotations;
+    annotations: ToolAnnotations & {
+        readOnlyHint: boolean;
+    };
     handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
 }
 export interface ApiOptions {
@@ -47,16 +61,6 @@ export interface ApiOptions {
      * on loose coercion.
      */
     validateArgs?: boolean;
-    /**
-     * Fail-closed on a tool whose `inputSchema` the validator cannot evaluate
-     * (default false). The default surfaces such a schema as a one-time warning
-     * and then passes the raw arguments through, so a broken schema never breaks
-     * an otherwise working tool. Set true to instead reject those calls with a
-     * non-retryable `invalid_args` ConnectorCallError, so a schema that cannot be
-     * enforced never silently admits unvalidated input. Only consulted when
-     * `validateArgs` is not false.
-     */
-    strictValidation?: boolean;
     tools: ApiTool[];
 }
 /**
@@ -64,11 +68,15 @@ export interface ApiOptions {
  * 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.
  *
- * Arguments are validated against `inputSchema` before the handler runs
- * (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.
+ * 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.
  */
 export declare function api(id: string, opts: ApiOptions): Connector;
-//# sourceMappingURL=api.d.ts.map

package/dist/connectors/api.js

@@ -1,34 +1,58 @@
-import { precompileValidator, validateToolInput } from "../validate.js";
+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.
+ */
+function checkToolContract(id, tool) {
+    const address = `${id}.${tool.name}`;
+    if (typeof tool.description !== "string" || tool.description.trim() === "") {
+        throw new Error(`api() tool "${address}" needs a non-empty description — it is what an ` +
+            "agent reads to choose the tool (convention: imperative one-liner, " +
+            'e.g. "Send an email via Resend").');
+    }
+    if (typeof tool.annotations?.readOnlyHint !== "boolean") {
+        throw new Error(`api() tool "${address}" needs an explicit annotations.readOnlyHint: ` +
+            "true for a read, false for work that must cross " +
+            "call_destructive_tool. Connecta never infers the classification " +
+            "from a tool name, description, schema, or other annotations.");
+    }
+    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.
  *
- * Arguments are validated against `inputSchema` before the handler runs
- * (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.
+ * 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.
  */
 export function api(id, opts) {
+    for (const t of opts.tools)
+        checkToolContract(id, t);
     const defs = opts.tools.map((t) => ({
         name: t.name,
-        ...(t.description !== undefined ? { description: t.description } : {}),
+        description: t.description,
         ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
         ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
-        ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
+        annotations: t.annotations,
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
-    const strictValidation = opts.strictValidation ?? false;
-    if (validateArgs) {
-        // Compile each schema now so a validator-hostile inputSchema surfaces once
-        // here rather than silently on its first call. Warning-only; never throws.
-        for (const t of opts.tools) {
-            if (t.inputSchema)
-                precompileValidator(t.inputSchema, { address: `${id}.${t.name}` });
-        }
-    }
     return {
         id,
         ...(opts.title !== undefined ? { title: opts.title } : {}),
@@ -64,7 +88,10 @@ export function api(id, opts) {
                 const invalid = validateToolInput(tool.inputSchema, input, {
                     address: `${id}.${name}`,
                     logger: ctx.logger,
-                    failClosed: strictValidation,
+                    // Always: the schema compiled at construction, so anything that
+                    // fails here is a schema that cannot be enforced, and a surface we
+                    // wrote ourselves does not get to admit unvalidated input quietly.
+                    failClosed: true,
                 });
                 if (invalid)
                     throw invalid;
@@ -77,4 +104,3 @@ export function api(id, opts) {
         },
     };
 }
-//# sourceMappingURL=api.js.map