@zackbart/connecta 0.24.4 → 0.25.0

package/examples/worker/wrangler.jsonc

@@ -27,15 +27,27 @@
     { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
   ],
 
-  // Activity history. Create with `wrangler d1 create connecta-activity`,
-  // paste the id, apply the schema in README.md, then uncomment the matching
-  // lines in src/index.ts. Off by default so this example deploys without a
-  // database.
+  // D1 databases, off by default so this example deploys without one.
+  // Uncomment the array and keep the entries you use.
+  //
+  // ACTIVITY_DB: activity history. Create with `wrangler d1 create
+  // connecta-activity`, paste the id, apply the schema in README.md, then
+  // uncomment the matching lines in src/index.ts.
+  //
+  // STORAGE_DB: strongly consistent storage with compare-and-set, in place of
+  // CONNECTA_KV. Create with `wrangler d1 create connecta-storage`, paste the
+  // id, apply the schema in README.md § "Strongly consistent storage", then
+  // pass `d1Storage(env.STORAGE_DB)` as `storage` in src/index.ts.
   // "d1_databases": [
   //   {
   //     "binding": "ACTIVITY_DB",
   //     "database_name": "connecta-activity",
   //     "database_id": "replace-with-d1-database-id"
+  //   },
+  //   {
+  //     "binding": "STORAGE_DB",
+  //     "database_name": "connecta-storage",
+  //     "database_id": "replace-with-d1-database-id"
   //   }
   // ],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.4",
+  "version": "0.25.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -116,7 +116,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build:operator-ui": "node scripts/build-operator-ui.mjs",
     "check:operator-ui": "node scripts/build-operator-ui.mjs --check",
-    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json && node scripts/prune-declarations.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.operator-ui.json --noEmit",
     "test": "vitest run",
     "test:browser:install": "playwright install chromium",
@@ -129,9 +129,16 @@
     "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
+    "check:declarations": "node scripts/check-declarations.mjs --dist .",
+    "check:bundle": "node scripts/bundle-size.mjs",
     "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
     "drift:check": "tsx scripts/drift-check.mjs",
-    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",
+    "eval:selftest": "tsx eval/selftest.ts",
+    "eval:agent": "tsx eval/run-agent.ts",
+    "eval:smoke": "tsx eval/run-smoke.ts",
+    "eval:perf": "tsx eval/run-perf.ts",
+    "eval:report": "tsx eval/report.ts",
+    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run test:browser && npm run build && npm run check:declarations && npm run check:bundle && npm run check:examples",
     "release:check": "npm run check && npm run check:security && npm run check:package",
     "prepack": "npm run check"
   },
@@ -139,6 +146,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
+    "effect": "4.0.0-rc.117",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.4",
+    "@zackbart/connecta": "0.25.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/dist/auth/downstream-oauth.d.ts

@@ -1,200 +0,0 @@
-import type { FetchLike, OAuthClientInformationContext, OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthDiscoveryState, OAuthTokens } from "@modelcontextprotocol/client";
-import type { KVStorage } from "../types.js";
-type OAuthRefreshFlightOutcome = {
-    status: "refreshed";
-} | {
-    status: "retired";
-} | {
-    status: "failed";
-    error: unknown;
-};
-interface OAuthRefreshFlight {
-    done: Promise<OAuthRefreshFlightOutcome>;
-    release: (outcome: OAuthRefreshFlightOutcome) => void;
-    stopObservingOwnerAbort: () => void;
-    mutationId: object;
-    writing: boolean;
-    /**
-     * Set once the token endpoint answered with valid tokens: the authorization
-     * server has consumed the rotating refresh token, so if the SDK's own
-     * saveTokens never arrives (owner cancelled, redirected, or invalidated),
-     * `fail` persists this copy itself rather than stranding the marker or
-     * letting a contender redeem the retired token.
-     */
-    acceptedTokens?: OAuthTokens;
-    persist?: (tokens: OAuthTokens) => Promise<void>;
-}
-/**
- * Share one rotating-token redemption within one connector runtime and OAuth
- * generation. The first request still owns the real fetch and response. Its
- * abort signal has one bounded listener until the exact flight settles, so a
- * cancellation after the response cannot strand waiters during token storage.
- * Followers wait for that provider to save tokens, then re-read storage. The
- * map never retains a token response or transport.
- *
- * This is intentionally runtime-local. KVStorage has no atomic coordination
- * operation, so a second isolate can still race the same refresh token.
- */
-export declare class OAuthRefreshCoordinator {
-    private readonly flights;
-    /** Opaque identities only: no request promise, signal, callback, or response. */
-    private readonly pendingMutations;
-    /** One bounded latest-success slot, containing only generation + identity. */
-    private successfulRefresh;
-    /** Replaced on every map mutation, closing flight/pending ABA across awaits. */
-    private stateRevision;
-    private advanceStateRevision;
-    private observeAuthoritativeGeneration;
-    private settle;
-    private markMutationPending;
-    private finishMutation;
-    /** @internal Opaque basis for issuer-aware provider token reads. */
-    successfulRefreshIdentity(generation: string): object | undefined;
-    coordinatedFetch(provider: KvOAuthProvider, baseFetch: FetchLike, requestSignal?: AbortSignal): FetchLike;
-    /** Start storage only while this owner still holds its exact flight. */
-    beginMutation(generation: string, flight: OAuthRefreshFlight): boolean;
-    /** Publish one exact owner's successful save without disturbing a newer try. */
-    succeedMutation(generation: string, flight: OAuthRefreshFlight): void;
-    /** Give joined callers a fetch/flow failure, without rejecting the gate. */
-    fail(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
-    /** Finish an exact failed credential write, then publish its failure. */
-    failMutation(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
-    /** Force reauthorization fences and wakes every waiter on the retired epoch. */
-    retire(generation: string): void;
-}
-/**
- * Physical key for an OAuth value in one authorization epoch. Legacy values
- * keep their historical names so upgrades can read an existing grant. Modern
- * values get an epoch-specific namespace: a stale write or delete can then
- * affect only its own flow, even if it lands after a replacement flow.
- */
-export declare function oauthValueStorageKey(key: string, generation: string | null): string;
-/**
- * OAuthClientProvider implemented over KVStorage for a single downstream
- * connector. Keys live in the connector's namespace as `oauth:<field>`.
- *
- * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
- * STORES the authorization URL; the registry surfaces it as status
- * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
- * drives transport.finishAuth(code).
- */
-export declare class KvOAuthProvider implements OAuthClientProvider {
-    private readonly connectorId;
-    private readonly storage;
-    private readonly redirectUri;
-    private readonly refreshCoordinator?;
-    private readonly allowAuthorization;
-    /**
-     * The reset generation this provider's flow started under. Every OAuth value
-     * it writes carries this epoch, so a late write can land after a reset without
-     * becoming readable under the new generation.
-     */
-    private capturedGeneration;
-    private refreshFlight;
-    /** Tokens this request's issuer-aware auth flow decided to refresh. */
-    private refreshBasis;
-    constructor(connectorId: string, storage: KVStorage, redirectUri: string, refreshCoordinator?: OAuthRefreshCoordinator | undefined, allowAuthorization?: boolean);
-    /**
-     * Stamp the force-reauth generation the current connect flow started under.
-     * Called by the connector once per connect, before c.connect(). The callback
-     * path captures the generation stored beside its verified state instead.
-     */
-    captureGeneration(gen: string): void;
-    /** The generation captured for this flow, before a concurrent reset. */
-    flowGeneration(): Promise<string>;
-    /** @internal Record the refresh attempt this provider owns. */
-    captureRefreshFlight(generation: string, flight: OAuthRefreshFlight): void;
-    private failRefreshFlight;
-    /** True when another request saved a refresh result after this flow's read. */
-    refreshBasisChanged(current: OAuthTokens, generation: string): boolean;
-    /**
-     * The epoch this provider writes under. Direct unit/custom use lazily captures
-     * the current generation; connector-driven connect and callback paths stamp it
-     * explicitly before the SDK can write.
-     */
-    private writeGeneration;
-    /**
-     * Store a value in the flow's physical epoch namespace. The pre-write check
-     * avoids needless stale residue. The namespaced key closes the remaining
-     * check-then-write race: a late old write cannot overwrite a replacement
-     * flow's value because the two writes have different physical keys.
-     */
-    private writeValue;
-    /**
-     * Read a value only when it belongs to the active generation. Plain legacy
-     * values remain readable until the first v2 reset, so upgrades do not discard
-     * an existing grant; once a modern epoch exists, untagged residue fails
-     * closed.
-     */
-    private readValue;
-    /**
-     * Read credentials only for the authorization server that issued them.
-     *
-     * Values written before issuer binding are bound on their first read with a
-     * validated SDK issuer, preserving an existing grant across this upgrade.
-     * A later issuer change is different: publish a new generation before
-     * returning no credentials, so every isolate drops the old registration and
-     * token set and the SDK starts authorization from scratch.
-     */
-    private readIssuerBoundValue;
-    /** Attempt every key deletion, then report the first backend failure. */
-    private deleteAll;
-    private cleanupBacklog;
-    private rememberRetiredGeneration;
-    private valueKeysForGeneration;
-    get redirectUrl(): string;
-    get clientMetadata(): OAuthClientMetadata;
-    clientInformation(ctx?: OAuthClientInformationContext): Promise<OAuthClientInformationMixed | undefined>;
-    saveClientInformation(info: OAuthClientInformationMixed, ctx?: OAuthClientInformationContext): Promise<void>;
-    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
-    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
-    tokens(ctx?: OAuthClientInformationContext): Promise<OAuthTokens | undefined>;
-    saveTokens(tokens: OAuthTokens, ctx?: OAuthClientInformationContext): Promise<void>;
-    /**
-     * OAuth `state`. The SDK calls this (when present) and appends the value to
-     * the authorization URL. We generate a fresh random value and persist it so
-     * the public /oauth/callback route can prove the callback belongs to a flow
-     * WE started. Without it, anyone holding a pending authorization URL could
-     * complete consent with their own account (login CSRF) — PKCE does not help,
-     * since the verifier belongs to connecta, not the attacker. Cleared in
-     * clearPending() once the flow completes.
-     */
-    state(): Promise<string>;
-    /**
-     * Constant-time check of a callback's `state` against the stored one-shot
-     * value. Absent stored state or absent candidate → false (fail closed).
-     */
-    verifyState(candidate: string | null): Promise<boolean>;
-    saveCodeVerifier(verifier: string): Promise<void>;
-    codeVerifier(): Promise<string>;
-    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
-    /** The stored authorization URL, if a flow is pending. */
-    pendingAuthorizationUrl(): Promise<string | undefined>;
-    /** Clear one-shot flow state after the callback completes. */
-    clearPending(): Promise<void>;
-    /**
-     * Force-reauth epoch shared across isolates through storage. Old numeric
-     * generations remain valid strings for migration; new resets use unique
-     * nonces, avoiding the lost-update race of read/increment/write.
-     */
-    generation(): Promise<string>;
-    /** True only after an operator disconnect, until an explicit authorization starts. */
-    operatorDisconnected(): Promise<boolean>;
-    /** Interpret a generation already read by a connector without another KV lookup. */
-    isOperatorDisconnectedGeneration(generation: string): boolean;
-    /** Publish a unique active epoch without a read/modify/write race. */
-    bumpGeneration(): Promise<string>;
-    /**
-     * Fence every flow that could still write, then remove all durable and
-     * one-shot authorization state. The generation is intentionally retained:
-     * it is the epoch fence that tells another isolate not to resurrect
-     * credentials it read before this reset.
-     *
-     * Once the fence is durable, attempt every deletion even if one fails. A
-     * partial backend outage should not leave unrelated secrets behind merely
-     * because an earlier key happened to be the first failed delete.
-     */
-    resetAuthorization(operatorDisconnected?: boolean): Promise<void>;
-    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
-}
-export {};

package/dist/catalog-fingerprint.d.ts

@@ -1,19 +0,0 @@
-import type { ToolDef } from "./types.js";
-export interface CatalogSnapshot {
-    tools: ToolDef[];
-    /** SHA-256 over the exact serialized tool array, prefixed with its size. */
-    fingerprint: string;
-    /** UTF-8 form reused by hashing, size enforcement, and chunking. */
-    serializedBytes: Uint8Array;
-}
-/** Fingerprint an already serialized catalog without parsing/reserializing it. */
-export declare function fingerprintSerializedCatalog(serializedTools: string): Promise<{
-    fingerprint: string;
-    byteLength: number;
-}>;
-/**
- * Capture every persisted/discovered field in one deterministic snapshot.
- * Object key order is allowed to cause a conservative extra write; changing
- * any serialized field must change the digest.
- */
-export declare function snapshotCatalog(tools: ToolDef[]): Promise<CatalogSnapshot>;

package/dist/catalog-limits.d.ts

@@ -1,9 +0,0 @@
-/** Complete-catalog ceiling shared by dynamically listed connector catalogs. */
-export declare const MAX_CATALOG_TOOLS = 100000;
-/**
- * Large enough to cross a single Workers KV value boundary while keeping the
- * serialized form at one quarter of a 128 MiB Worker heap.
- */
-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;

package/dist/catalog-service.d.ts

@@ -1,263 +0,0 @@
-import type { CallErrorDetails } from "./errors.js";
-import type { ConnectorOperationOptions, RegistryView } from "./registry.js";
-import type { DeferredWork } from "./connector-scope.js";
-import type { Connector, ToolDef } from "./types.js";
-export declare const DEFAULT_SEARCH_LIMIT = 8;
-export declare const MAX_SEARCH_LIMIT = 100;
-export declare const MAX_DESCRIBE_ADDRESSES = 100;
-export declare const MAX_DISCOVERY_RESULT_BYTES = 256000;
-/**
- * The discovery route a routing failure should send a caller back through. Same
- * catalog logic serves both the top-level `search_tools` path and the
- * in-program `connecta.search` path, so callers pass the route they own.
- */
-export type SearchRoute = "search_tools" | "connecta.search";
-export declare class DiscoveryPolicyError extends Error {
-    readonly code: "invalid_args" | "result_too_large";
-    constructor(code: "invalid_args" | "result_too_large", message: string);
-}
-/** Serialize once and count the exact bytes the MCP adapter would emit. */
-export declare function boundedDiscoveryText(value: unknown, hint: string): string;
-export interface CatalogSearchArgs {
-    query?: string;
-    connector?: string;
-    /**
-     * Result classification only; never changes which tools exist or what may
-     * execute. Omitted and "all" preserve the complete configured catalog.
-     */
-    safety?: "readOnly" | "approvalRequired" | "all";
-    limit?: number;
-    offset?: number;
-    fullDescriptions?: boolean;
-    includeSchemas?: "compact" | "json";
-    /** Code-mode helper metadata; never exposed by the public search_tools schema. */
-    includeSchemaKeys?: boolean;
-}
-export interface CatalogDescribeArgs {
-    address?: unknown;
-    addresses?: unknown;
-    format?: "compact" | "json";
-    fullDescriptions?: boolean;
-}
-interface CatalogSearchEntry {
-    connector: Connector;
-    guide?: string;
-    guideSummary?: string;
-    tool: {
-        name: string;
-        address: string;
-        description?: string;
-        inputSchema?: unknown;
-        outputSchema?: unknown;
-        outputSchemaSource?: "observed";
-        inputSchemaTruncated?: true;
-        outputSchemaTruncated?: true;
-        inputKeys?: string[];
-        requiredInputKeys?: string[];
-        outputKeys?: string[];
-        annotations?: ToolDef["annotations"];
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-    };
-}
-type GuideRequiredReason = "connector_required" | "approval_required" | "schema_truncated";
-/**
- * The classified-failure subset a scoped search may echo: enough to tell a
- * transient outage from one an operator must clear, and nothing more. Kept as
- * its own type rather than `CallErrorDetails` so widening the call-path
- * classifier cannot widen this discovery-surface field by accident.
- */
-interface CatalogFailureDetail {
-    code: string;
-    message: string;
-    retryable: boolean;
-    retryAfterMs?: number;
-}
-interface CatalogDescriptionFailureDetail extends CatalogFailureDetail {
-    nextAction?: NonNullable<CallErrorDetails["nextAction"]>;
-    /** Nearby canonical addresses, ranked deterministically by tool name. */
-    suggestions?: string[];
-}
-export interface CatalogSearchPage {
-    entries: CatalogSearchEntry[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    nextOffset?: number;
-    matchMode?: "partial";
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-}
-export interface CatalogDescription {
-    address: string;
-    name?: string;
-    description?: string;
-    guide?: string;
-    guideSummary?: string;
-    guideRequired?: true;
-    guideRequiredReasons?: GuideRequiredReason[];
-    inputSchema?: unknown;
-    outputSchema?: unknown;
-    outputSchemaSource?: "observed";
-    inputSchemaTruncated?: true;
-    outputSchemaTruncated?: true;
-    annotations?: ToolDef["annotations"];
-    error?: string;
-    errorDetails?: CatalogDescriptionFailureDetail;
-}
-export interface ResolvedCatalogTool {
-    connector: Connector;
-    toolName: string;
-    definition: ToolDef;
-}
-export type CatalogResolution = {
-    ok: true;
-    resolved: ResolvedCatalogTool;
-    catalogMs: number;
-} | {
-    ok: false;
-    error: CallErrorDetails;
-    catalogMs: number;
-    connector?: Connector;
-    toolName?: string;
-    cause?: unknown;
-};
-/**
- * Request-local catalog operations shared by MCP meta-tools and code mode.
- * Successful catalogs may be reused inside this request; failures are not
- * retained, and the service itself never escapes its request adapter.
- */
-export declare class CatalogService {
-    private readonly registry;
-    readonly baseUrl: string;
-    readonly requestScope: object;
-    private readonly probeTimeoutMs;
-    private readonly concurrency;
-    private readonly searchRoute;
-    private readonly readOptions;
-    private readonly loaded;
-    private readonly loading;
-    constructor(registry: RegistryView, baseUrl: string, options?: {
-        requestScope?: object | undefined;
-        probeTimeoutMs?: number | undefined;
-        concurrency?: number | undefined;
-        /** The discovery route recovery records name. Default `search_tools`. */
-        searchRoute?: SearchRoute | undefined;
-        /** Runtime-owned tail for stale-while-revalidate catalog reads. */
-        defer?: DeferredWork | undefined;
-    });
-    /**
-     * Send a caller back to discovery through the surface it can actually reach.
-     * Both variants carry the same scoping arguments because `connecta.search`
-     * takes the same ones `search_tools` does; only the key naming the callable
-     * differs, the way the ambiguous-alias record already names a function.
-     *
-     * Not private: `InvocationService` builds the same class of record when a
-     * call fails schema validation, and it is this catalog's route that decides
-     * which key that record carries. Duplicating the branch there would let the
-     * two drift.
-     */
-    searchRecovery(args: {
-        query: string;
-        connector?: string;
-    }, purpose: string): NonNullable<CallErrorDetails["nextAction"]>;
-    loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
-    private loadForDiscovery;
-    private outputSchema;
-    private unknownAddressFailure;
-    private catalogLoadFailure;
-    private unknownToolFailure;
-    resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;
-    search(args: CatalogSearchArgs): Promise<CatalogSearchPage>;
-    describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]>;
-}
-export declare function groupedSearchResult(page: CatalogSearchPage): {
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-    matchMode?: "partial";
-    nextOffset?: number;
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    connectors: {
-        id: string;
-        title?: string;
-        guide?: string;
-        guideSummary?: string;
-        tools: CatalogSearchEntry["tool"][];
-    }[];
-};
-export declare function flatSearchResult(page: CatalogSearchPage): {
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-    matchMode?: "partial";
-    nextOffset?: number;
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    tools: {
-        guideSummary?: string;
-        guide?: string;
-        connectorTitle?: string;
-        name: string;
-        address: string;
-        description?: string;
-        inputSchema?: unknown;
-        outputSchema?: unknown;
-        outputSchemaSource?: "observed";
-        inputSchemaTruncated?: true;
-        outputSchemaTruncated?: true;
-        inputKeys?: string[];
-        requiredInputKeys?: string[];
-        outputKeys?: string[];
-        annotations?: ToolDef["annotations"];
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-    }[];
-};
-export {};

package/dist/catalog.d.ts

@@ -1,87 +0,0 @@
-import type { JsonSchema, ToolDef } from "./types.js";
-export declare const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1024;
-export declare function summarizeDescription(text: string | undefined, full: boolean): string | undefined;
-export declare function summarizeDiscoveryDescription(text: string | undefined, full: boolean): string | undefined;
-/** Distinct normalized terms in query order, shared by ranking and feedback. */
-export declare function lexicalQueryTerms(query: string): string[];
-/**
- * Remove conversational framing before the all-term/partial decision. If
- * every term is framing, retain the original query rather than turning a
- * search into an unfiltered catalog browse.
- */
-export declare function lexicalSearchQuery(query: string): string;
-export type LexicalMatchMode = "all" | "partial";
-export interface RankedTool {
-    tool: ToolDef;
-    score: number;
-    order: number;
-    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>;
-    nameMatches: ReadonlyMap<string, ReadonlySet<ToolDef>>;
-    descriptionMatches: ReadonlyMap<string, ReadonlySet<ToolDef>>;
-}
-/**
- * Compute query-specific document frequencies across every available catalog.
- * The caller does this once per search and shares the result with each
- * connector rank, so ubiquitous words contribute less than discriminative
- * ones without making any action word a stopword.
- */
-export declare function lexicalCorpusStatistics(toolSets: ToolDef[][], query: string): LexicalCorpusStatistics;
-/**
- * Rank a connector's tools while caching its normalized plain-data index.
- * `exactNameQuery` may retain framing removed from the scoring query: those
- * words are weak term evidence, but remain part of a real tool-name phrase.
- */
-export declare function rankTools(tools: ToolDef[], query: string, mode?: LexicalMatchMode, statistics?: LexicalCorpusStatistics, exactNameQuery?: string): RankedTool[];
-/** Render and cache a compact TypeScript-like representation of JSON Schema. */
-export declare function compactSchema(schema: JsonSchema): string;
-/** Describe allows 8 KiB for property prose, with the same work cap as search. */
-export declare function compactDescriptionSchema(schema: JsonSchema): CompactDiscoverySchema;
-export interface CompactDiscoverySchema {
-    text: string;
-    truncated: boolean;
-}
-/**
- * Render the schema shape carried by search results.
- *
- * Search is a routing step, so repeated property prose does not earn its
- * context cost there. Required inputs render first, and the result has a hard
- * UTF-8 budget; exact JSON and the prose-rich compact rendering remain
- * available through the existing full retrieval paths.
- */
-export declare function compactDiscoverySchema(schema: JsonSchema): CompactDiscoverySchema;
-/** The property and required names a schema resolves to, or undefined. */
-export interface SchemaObjectKeys {
-    properties: string[];
-    required: string[];
-}
-/**
- * Walk a schema the way renderSchema does — composing `allOf` and resolving
- * `$ref` against the root's `$defs`/`definitions` — and collect the top-level
- * property names it would render. A shallow `Object.keys(schema.properties)`
- * disagrees with the rendered compact schema for exactly the shapes real
- * connectors emit (a top-level `$ref` to a `$defs` entry, or the OpenAPI
- * "extend this base" `allOf`), which is worse than no metadata at all: it
- * reports an empty field list for a tool that plainly has fields.
- *
- * Returns undefined when the schema is not an object shape at all — a union,
- * array, enum, or unresolvable `$ref`. Absent metadata tells a caller to read
- * the rendered schema instead; an empty array would claim the tool takes no
- * fields.
- */
-export declare function schemaObjectKeys(schema: JsonSchema | undefined): SchemaObjectKeys | undefined;

package/dist/concurrency.d.ts

@@ -1,3 +0,0 @@
-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>[]>;