@sezzlee/sdk-nestjs 0.0.0-stage → 0.2.0

package/dist/families.js

@@ -0,0 +1,157 @@
+import { declaredSchemaProblem, } from "@sezzlee/core";
+export class ToolFamilyOptions {
+    registered = new Map();
+    loadTimeoutMs = 10_000;
+    get sources() {
+        return this.registered;
+    }
+    provide(name, source) {
+        this.registered.set(name, source);
+        return this;
+    }
+}
+async function loadOne(source, timeoutMs) {
+    const signal = AbortSignal.timeout(timeoutMs);
+    const aborted = new Promise((_, reject) => {
+        signal.addEventListener("abort", () => reject(signal.reason), {
+            once: true,
+        });
+    });
+    return Promise.race([Promise.resolve(source({ signal })), aborted]);
+}
+/**
+ * Loads every registered source once.
+ *
+ * A failing source keeps the members it last returned: dropping a family because its source was
+ * briefly unreachable would take working tools offline on every transient error.
+ *
+ * @param previous the loads the current catalog was built from, or `undefined` before the first
+ */
+export async function loadFamilies(options, previous) {
+    const entries = await Promise.all([...options.sources].map(async ([name, source]) => {
+        try {
+            const members = await loadOne(source, options.loadTimeoutMs);
+            return [name, { state: "loaded", members }];
+        }
+        catch (error) {
+            const last = previous?.get(name);
+            return [
+                name,
+                last === undefined || last.state === "failed"
+                    ? { state: "failed", error }
+                    : { state: "stale", members: last.members, error },
+            ];
+        }
+    }));
+    return new Map(entries);
+}
+export const sdkFamilySeverities = {
+    unknown_family_source: "endpointDropped",
+    family_source_failed: "endpointDropped",
+    family_not_loaded: "endpointDropped",
+    family_source_stale: "warning",
+    family_member_rejected: "warning",
+};
+const diagnostic = (code, message) => ({ code, message });
+const toolNamePattern = /^[a-z][a-z0-9_]{0,255}$/;
+const reasonOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Lowers one operation's family declaration into the variants its members become.
+ *
+ * A defect in one member is that member's alone: the rest of the family stays published and the
+ * member is reported, because the members are host data and one bad row should not take every
+ * sibling offline. Only a defect in the declaration itself refuses the operation.
+ *
+ * @param owner the operation's identity in diagnostics
+ * @param declared the handler's own `@McpVariant`s; a member may not reuse their names
+ * @param loads the member loads, or `undefined` when the sources have not loaded yet
+ */
+export function resolveFamily(family, owner, declared, options, loads) {
+    const lowered = { parameter: family.parameter };
+    if (family.source === undefined) {
+        return {
+            kind: "members",
+            family: lowered,
+            variants: [],
+            diagnostics: [],
+        };
+    }
+    if (!options.sources.has(family.source)) {
+        return refused("unknown_family_source", `${owner} takes its members from source '${family.source}', which is not registered; register it with options.families.provide.`);
+    }
+    const load = loads?.get(family.source);
+    if (load === undefined) {
+        return refused("family_not_loaded", `${owner} was built before source '${family.source}' finished loading; the catalog is rebuilt when it does.`);
+    }
+    if (load.state === "failed") {
+        return refused("family_source_failed", `${owner} has no members: source '${family.source}' failed and has never returned any (${reasonOf(load.error)}).`);
+    }
+    const diagnostics = [];
+    if (load.state === "stale") {
+        diagnostics.push(diagnostic("family_source_stale", `${owner} keeps the members source '${family.source}' last returned; the latest load failed (${reasonOf(load.error)}).`));
+    }
+    const names = new Set(declared.map((variant) => variant.name));
+    const keys = new Set();
+    const variants = [];
+    for (const member of load.members) {
+        const problem = memberProblem(member, names, keys);
+        if (problem !== undefined) {
+            diagnostics.push(diagnostic("family_member_rejected", `${owner} drops member '${String(member.name)}': ${problem}.`));
+            continue;
+        }
+        names.add(member.name);
+        keys.add(JSON.stringify(member.key));
+        variants.push(lower(member, family.parameter));
+    }
+    return { kind: "members", family: lowered, variants, diagnostics };
+}
+function memberProblem(member, names, keys) {
+    if (typeof member.name !== "string" || !toolNamePattern.test(member.name)) {
+        return "its name does not match the tool-name pattern";
+    }
+    if (typeof member.description !== "string" ||
+        member.description.trim() === "") {
+        return "it has no description";
+    }
+    if (names.has(member.name)) {
+        return "another member or variant has the same name";
+    }
+    if (!(typeof member.key === "string" || Number.isFinite(member.key)) ||
+        keys.has(JSON.stringify(member.key))) {
+        return "its key is not a string or finite number, or repeats another member's";
+    }
+    const schema = member.body;
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        return "its body is not a JSON Schema object";
+    }
+    const invalid = declaredSchemaProblem(member.body);
+    return invalid === undefined ? undefined : `its body ${invalid}`;
+}
+function lower(member, parameter) {
+    const annotations = {
+        ...(member.readOnly === undefined ? {} : { readOnlyHint: member.readOnly }),
+        ...(member.destructive === undefined
+            ? {}
+            : { destructiveHint: member.destructive }),
+        ...(member.idempotent === undefined
+            ? {}
+            : { idempotentHint: member.idempotent }),
+    };
+    return {
+        name: member.name,
+        description: member.description,
+        arguments: [
+            { name: parameter, hidden: { kind: "constant", value: member.key } },
+        ],
+        requestBody: {
+            schema: member.body,
+            ...(member.bodyRequired === undefined
+                ? {}
+                : { required: member.bodyRequired }),
+        },
+        ...(Object.keys(annotations).length === 0 ? {} : { annotations }),
+    };
+}
+function refused(code, message) {
+    return { kind: "refused", diagnostic: diagnostic(code, message) };
+}

package/dist/files.d.ts

@@ -0,0 +1,43 @@
+import type { FileRefusalReason } from "@sezzlee/core";
+import type { InvokeTarget, McpCaller } from "./options.js";
+/** What a file resolver is asked to deliver. */
+export interface FileResolveRequest {
+    /** The string the agent sent. It is not a capability: authorize it against {@link caller}. */
+    readonly ref: string;
+    /** The multipart field the file travels in. */
+    readonly field: string;
+    readonly target: InvokeTarget;
+    readonly caller: McpCaller;
+    /** The per-file byte limit; answer `too_large` rather than loading more. */
+    readonly maxBytes: number;
+    /** Aborted when the invoke deadline expires or the caller cancels. */
+    readonly signal: AbortSignal;
+}
+export type FileResolution = {
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+    readonly filename?: string;
+    readonly mediaType?: string;
+} | {
+    readonly ok: false;
+    readonly reason: FileRefusalReason;
+};
+/**
+ * Turns a `ref` file argument into bytes. sezzlee names no storage: the host binds this port, and
+ * binding it is what makes `ref` appear in a file argument's schema.
+ */
+export interface FileResolver {
+    /** Shown to the agent as the `ref` key's description, so it knows what a ref is and where to get one. */
+    readonly refDescription: string;
+    resolve(request: FileResolveRequest): Promise<FileResolution>;
+}
+export interface SezzleeFileOptions {
+    resolver?: FileResolver;
+}
+/** Raised by the dispatcher when a `ref` was not delivered; the meta-tool layer turns it into an envelope. */
+export declare class SezzleeFileRefused extends Error {
+    readonly field: string;
+    readonly reason: FileRefusalReason;
+    readonly limit: number;
+    constructor(field: string, reason: FileRefusalReason, limit: number);
+}

package/dist/files.js

@@ -0,0 +1,13 @@
+/** Raised by the dispatcher when a `ref` was not delivered; the meta-tool layer turns it into an envelope. */
+export class SezzleeFileRefused extends Error {
+    field;
+    reason;
+    limit;
+    constructor(field, reason, limit) {
+        super(`sezzlee: file argument '${field}' was refused (${reason}).`);
+        this.field = field;
+        this.reason = reason;
+        this.limit = limit;
+        this.name = "SezzleeFileRefused";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+export { SezzleeModule } from "./sezzlee.module.js";
+export type { SezzleeModuleAsyncOptions } from "./sezzlee.module.js";
+export { SezzleeDispatcher } from "./dispatcher.js";
+export { SezzleeCatalog } from "./catalog.js";
+export type { CatalogEntry, CatalogSnapshot } from "./catalog.js";
+export { curate, hidden, McpIgnore, McpTool, McpToolFamily, McpVariant, } from "./decorators.js";
+export type { ArgumentRule, ArgumentRules, JsonValue, McpFileFieldOptions, McpResponseDeclaration, McpToolEffect, McpToolFamilyOptions, McpToolOptions, McpVariantOptions, } from "./decorators.js";
+export { ToolFamilyOptions } from "./families.js";
+export type { McpFamilyMember, McpFamilySource } from "./families.js";
+export { SezzleeFileRefused } from "./files.js";
+export type { FileResolution, FileResolveRequest, FileResolver, SezzleeFileOptions, } from "./files.js";
+export { ArgumentCurationOptions, callerOf } from "./options.js";
+export type { ArgumentValueProvider, CurationTarget, SezzleeSearchOptions, McpCaller, VerifiedToken, } from "./options.js";
+export type { RankCatalog, RankDocument, RankerFailureMode, RankRequest, ToolRanker, } from "@sezzlee/core";
+export { isSezzleeProbe, isSezzleeRequest } from "./markers.js";
+export { currentOuterConnection, type OuterConnection, } from "./outer-connection.js";
+export { catalogGenerationMetaKey, registerSezzleeTools, } from "./meta-tools.js";
+export type { MetaToolDependencies } from "./meta-tools.js";
+export { createRoutePaths, discoverEndpoints, modulePathOf, normalizeRoute, } from "./discovery/endpoint-discovery.js";
+export type { DiscoveredEndpoint, DiscoveryOptions, RoutePathMetadata, RoutePaths, VisibilityDeclaration, } from "./discovery/endpoint-discovery.js";
+export { NestTypeShapeBinder } from "./discovery/type-shape.js";
+export type { TypeShapeBinderOptions } from "./discovery/type-shape.js";
+export { severityOf } from "./discovery/diagnostics.js";
+export type { CatalogDiagnostic, CatalogSeverity, } from "./discovery/diagnostics.js";
+export { DeclarativeVisibilityEvaluator } from "./visibility/evaluator.js";
+export type { VisibilityEvaluator } from "./visibility/evaluator.js";
+export { SezzleeProbeEvaluator, SezzleeProbeInterceptor, } from "./visibility/probe.js";
+export type { ProbeEvaluator } from "./visibility/probe.js";
+export { CallerVisibilityProvider } from "./visibility/provider.js";
+export type { DispatchDeadline, DispatchResult, ProbeResult, } from "./dispatcher.js";
+export { SezzleeDispatchAborted } from "./synthetic-context.js";
+export type { DispatchAbortReason } from "./synthetic-context.js";
+export { ErrorMappingOptions, IdentityForwardingOptions, SezzleeOptions, SEZZLEE_OPTIONS, } from "./options.js";
+export { SezzleeConfigurationError, collectConfigurationFailures, validateSezzleeOptions, } from "./options-validation.js";
+export type { InvokeTarget, SezzleeInvokeOptions, SezzleeDiagnosticsOptions, SezzleeNamingOptions, SezzleeSelectionOptions, SezzleeVisibilityOptions, SezzleeVisibilityTier, } from "./options.js";
+export type { OuterRequest, SezzleeCacheOptions, SezzleeResourceServerOptions, SyntheticHeaders, SyntheticRequestOptions, } from "./options.js";
+export { extensionTokens, toProviders } from "./extension-points.js";
+export type { ExtensionOverrides, ExtensionPoints, OverrideProvider, } from "./extension-points.js";
+export { CarrierHashCallerScopeResolver, SEZZLEE_CACHE_INVALIDATOR, SezzleeCacheInvalidator, } from "./cache.js";
+export type { CallerScopeResolver } from "./cache.js";
+export { DefaultInvokeResultMapper } from "./invoke-result-mapper.js";
+export type { InvokeResultMapper } from "./invoke-result-mapper.js";
+export { SezzleeStreamableHttp } from "./transport/streamable-http.js";
+export type { SezzleeRequestHandler, SezzleeServerFactory, } from "./transport/streamable-http.js";
+export { withAudienceCheck } from "./transport/audience.js";
+export { protectedResourceMetadataHandler, protectedResourceMetadataPath, protectedResourceMetadataUrl, protectedResourceMetadataWellKnownPrefix, } from "./transport/protected-resource-metadata.js";
+export { compose, createRequestTemplate, isInvokeError, isMappedError, isSdkError, mapInvokeResult, SezzleeArgumentError, SezzleeTemplateError, } from "@sezzlee/core";
+export type { BackendErrorCode, BackendResponse, ComposedRequest, FieldError, InvokeOutcome, InvokeResult, InvokeSuccess, MappedError, ParameterBinding, ParameterKind, ParameterLocation, ParsedBody, Recognizer, RequestTemplate, RequestTemplateInput, SezzleeArgumentErrorCode, } from "@sezzlee/core";

package/dist/index.js

@@ -0,0 +1,26 @@
+export { SezzleeModule } from "./sezzlee.module.js";
+export { SezzleeDispatcher } from "./dispatcher.js";
+export { SezzleeCatalog } from "./catalog.js";
+export { curate, hidden, McpIgnore, McpTool, McpToolFamily, McpVariant, } from "./decorators.js";
+export { ToolFamilyOptions } from "./families.js";
+export { SezzleeFileRefused } from "./files.js";
+export { ArgumentCurationOptions, callerOf } from "./options.js";
+export { isSezzleeProbe, isSezzleeRequest } from "./markers.js";
+export { currentOuterConnection, } from "./outer-connection.js";
+export { catalogGenerationMetaKey, registerSezzleeTools, } from "./meta-tools.js";
+export { createRoutePaths, discoverEndpoints, modulePathOf, normalizeRoute, } from "./discovery/endpoint-discovery.js";
+export { NestTypeShapeBinder } from "./discovery/type-shape.js";
+export { severityOf } from "./discovery/diagnostics.js";
+export { DeclarativeVisibilityEvaluator } from "./visibility/evaluator.js";
+export { SezzleeProbeEvaluator, SezzleeProbeInterceptor, } from "./visibility/probe.js";
+export { CallerVisibilityProvider } from "./visibility/provider.js";
+export { SezzleeDispatchAborted } from "./synthetic-context.js";
+export { ErrorMappingOptions, IdentityForwardingOptions, SezzleeOptions, SEZZLEE_OPTIONS, } from "./options.js";
+export { SezzleeConfigurationError, collectConfigurationFailures, validateSezzleeOptions, } from "./options-validation.js";
+export { extensionTokens, toProviders } from "./extension-points.js";
+export { CarrierHashCallerScopeResolver, SEZZLEE_CACHE_INVALIDATOR, SezzleeCacheInvalidator, } from "./cache.js";
+export { DefaultInvokeResultMapper } from "./invoke-result-mapper.js";
+export { SezzleeStreamableHttp } from "./transport/streamable-http.js";
+export { withAudienceCheck } from "./transport/audience.js";
+export { protectedResourceMetadataHandler, protectedResourceMetadataPath, protectedResourceMetadataUrl, protectedResourceMetadataWellKnownPrefix, } from "./transport/protected-resource-metadata.js";
+export { compose, createRequestTemplate, isInvokeError, isMappedError, isSdkError, mapInvokeResult, SezzleeArgumentError, SezzleeTemplateError, } from "@sezzlee/core";

package/dist/invoke-result-mapper.d.ts

@@ -0,0 +1,16 @@
+import { type InvokeResult } from "@sezzlee/core";
+import type { DispatchResult } from "./dispatcher.js";
+import { SezzleeOptions } from "./options.js";
+/** The names a reported field may be canonicalised against. */
+export interface FieldVocabulary {
+    readonly fieldAliases?: Readonly<Record<string, string>>;
+    readonly hiddenFields?: readonly string[];
+}
+export interface InvokeResultMapper {
+    map(result: DispatchResult, knownFields: readonly string[], vocabulary?: FieldVocabulary): InvokeResult;
+}
+export declare class DefaultInvokeResultMapper implements InvokeResultMapper {
+    private readonly options;
+    constructor(options: SezzleeOptions);
+    map(result: DispatchResult, knownFields: readonly string[], vocabulary?: FieldVocabulary): InvokeResult;
+}

package/dist/invoke-result-mapper.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { mapInvokeResult } from "@sezzlee/core";
+import { SEZZLEE_OPTIONS, SezzleeOptions } from "./options.js";
+let DefaultInvokeResultMapper = class DefaultInvokeResultMapper {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    map(result, knownFields, vocabulary) {
+        return mapInvokeResult({
+            status: result.status,
+            contentType: result.contentType,
+            headers: result.headers,
+            body: result.body,
+        }, {
+            recognizers: this.options.errors.recognizers,
+            knownFields,
+            ...(vocabulary?.fieldAliases === undefined
+                ? {}
+                : { fieldAliases: vocabulary.fieldAliases }),
+            ...(vocabulary?.hiddenFields === undefined
+                ? {}
+                : { hiddenFields: vocabulary.hiddenFields }),
+        });
+    }
+};
+DefaultInvokeResultMapper = __decorate([
+    Injectable(),
+    __param(0, Inject(SEZZLEE_OPTIONS)),
+    __metadata("design:paramtypes", [SezzleeOptions])
+], DefaultInvokeResultMapper);
+export { DefaultInvokeResultMapper };

package/dist/markers.d.ts

@@ -0,0 +1,5 @@
+export declare function markSyntheticRequest(request: object, probe: boolean): void;
+export declare function markShortCircuited(request: object): void;
+export declare function isSezzleeRequest(request: unknown): boolean;
+export declare function isSezzleeProbe(request: unknown): boolean;
+export declare function wasShortCircuited(request: unknown): boolean;

package/dist/markers.js

@@ -0,0 +1,27 @@
+const SEZZLEE_REQUEST = Symbol("sezzlee.request");
+const SEZZLEE_PROBE = Symbol("sezzlee.probe");
+const SEZZLEE_SHORT_CIRCUIT = Symbol("sezzlee.probe.short-circuited");
+export function markSyntheticRequest(request, probe) {
+    const marked = request;
+    marked[SEZZLEE_REQUEST] = true;
+    if (probe) {
+        marked[SEZZLEE_PROBE] = true;
+    }
+}
+export function markShortCircuited(request) {
+    request[SEZZLEE_SHORT_CIRCUIT] = true;
+}
+export function isSezzleeRequest(request) {
+    return reads(request, SEZZLEE_REQUEST);
+}
+export function isSezzleeProbe(request) {
+    return reads(request, SEZZLEE_PROBE);
+}
+export function wasShortCircuited(request) {
+    return reads(request, SEZZLEE_SHORT_CIRCUIT);
+}
+function reads(request, key) {
+    return (typeof request === "object" &&
+        request !== null &&
+        request[key] === true);
+}

package/dist/meta-tools.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { catalogGenerationMetaKey } from "@sezzlee/core";
+import type { SezzleeCatalog } from "./catalog.js";
+import type { CallerScopeResolver } from "./cache.js";
+import type { SezzleeDispatcher } from "./dispatcher.js";
+import type { InvokeResultMapper } from "./invoke-result-mapper.js";
+import type { SezzleeOptions } from "./options.js";
+import type { CallerVisibilityProvider } from "./visibility/provider.js";
+export interface MetaToolDependencies {
+    readonly catalog: SezzleeCatalog;
+    readonly dispatcher: SezzleeDispatcher;
+    readonly mapper: InvokeResultMapper;
+    readonly visibility: CallerVisibilityProvider;
+    readonly scopes: CallerScopeResolver;
+    readonly options: SezzleeOptions;
+}
+export { catalogGenerationMetaKey };
+export declare function registerSezzleeTools(server: McpServer, deps: MetaToolDependencies): void;