@sezzlee/sdk-nestjs 0.0.0-stage → 0.1.0

package/dist/catalog.js

@@ -0,0 +1,456 @@
+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, Optional, RequestMethod, } from "@nestjs/common";
+import { ApplicationConfig, DiscoveryService, HttpAdapterHost, ModulesContainer, } from "@nestjs/core";
+import { assertCatalogValid, buildCatalog, combineMarkers, matchesRoute, SezzleeTemplateError, textMediaType, urlEncodedMediaType, } from "@sezzlee/core";
+import { severityOf } from "./discovery/diagnostics.js";
+import { createRoutePaths, discoverEndpoints, modulePathOf, normalizeRoute, } from "./discovery/endpoint-discovery.js";
+import { loadFamilies, resolveFamily, } from "./families.js";
+import { SEZZLEE_OPTIONS, } from "./options.js";
+import { extensionTokens } from "./extension-points.js";
+import { protectedResourceMetadataPath } from "./transport/protected-resource-metadata.js";
+export { cleanTags } from "@sezzlee/core";
+let SezzleeCatalog = class SezzleeCatalog {
+    discovery;
+    modules;
+    applicationConfig;
+    options;
+    adapterHost;
+    toolRanker;
+    snapshot;
+    currentGeneration = 0;
+    listeners = new Set();
+    loads;
+    pending = Promise.resolve();
+    constructor(discovery, modules, applicationConfig, options, adapterHost, toolRanker = null) {
+        this.discovery = discovery;
+        this.modules = modules;
+        this.applicationConfig = applicationConfig;
+        this.options = options;
+        this.adapterHost = adapterHost;
+        this.toolRanker = toolRanker;
+    }
+    get ranker() {
+        return this.toolRanker;
+    }
+    get generation() {
+        return this.currentGeneration;
+    }
+    get current() {
+        this.snapshot ??= this.build(this.loads);
+        return this.snapshot;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Rebuilds the catalog, loading family members first when any source is registered.
+     *
+     * Without a source the rebuild happens before this returns, as it always has. With one, reloads
+     * run one at a time, and a rebuild that would turn a valid catalog fatal is refused and the
+     * current catalog kept ([tool-families.md] §Membership): member data added under a name another
+     * tool already has would otherwise take every tool offline.
+     *
+     * @throws SezzleeCatalogError through the returned promise when the rebuild is refused
+     */
+    reload() {
+        if (this.options.families.sources.size === 0) {
+            this.commit(this.build(this.loads));
+            return Promise.resolve();
+        }
+        return this.enqueue(async () => {
+            const loads = await loadFamilies(this.options.families, this.loads);
+            const candidate = this.build(loads);
+            if (candidate.fatal.length > 0 && this.current.fatal.length === 0) {
+                assertCatalogValid(candidate.fatal);
+            }
+            this.loads = loads;
+            this.commit(candidate);
+        });
+    }
+    /**
+     * Loads family members once the application's own providers are ready, since a source usually
+     * reads from one of them. A catalog built earlier carries `family_not_loaded` and is rebuilt
+     * here, which signals `listChanged`.
+     */
+    async onApplicationBootstrap() {
+        if (this.options.families.sources.size === 0) {
+            return;
+        }
+        await this.enqueue(async () => {
+            this.loads = await loadFamilies(this.options.families, this.loads);
+            if (this.snapshot !== undefined) {
+                this.commit(this.build(this.loads));
+            }
+        });
+    }
+    enqueue(task) {
+        const next = this.pending.then(task);
+        this.pending = next.catch(() => undefined);
+        return next;
+    }
+    commit(snapshot) {
+        this.snapshot = snapshot;
+        this.currentGeneration += 1;
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+    get diagnostics() {
+        return this.current.diagnostics;
+    }
+    find(name) {
+        return this.current.byName.get(name);
+    }
+    ensureValid() {
+        assertCatalogValid(this.current.fatal);
+    }
+    /**
+     * Guard: Express 5 defaults `query parser` to `simple`, which does not parse
+     * brackets — `?filter[status]=x` then arrives as one literal key and the DTO
+     * binds nothing. A tool that composes a filter the backend silently ignores
+     * returns an unfiltered result set, which is the failure
+     * `unresolved_query_shape` exists to prevent, so this is fatal rather than a
+     * warning. Only Express is checked: `getInstance().get` is a route
+     * registrar on Fastify, not a settings reader.
+     */
+    reportUnparsedBrackets(entries, report) {
+        const bracketed = entries.filter((entry) => (entry.descriptor.parameters ?? []).some((parameter) => parameter.style === "deepObject" &&
+            (parameter.objectNotation ?? "bracket") === "bracket"));
+        if (bracketed.length === 0) {
+            return;
+        }
+        const adapter = this.adapterHost?.httpAdapter;
+        if (adapter === undefined || adapter.getType() !== "express") {
+            return;
+        }
+        const instance = adapter.getInstance();
+        const parser = instance.get("query parser");
+        if (parser === "extended" || typeof parser === "function") {
+            return;
+        }
+        report({
+            code: "query_parser_not_extended",
+            message: `Tool '${bracketed[0]?.tool.name}' composes a bracketed query object, but this application's Express 'query parser' is '${String(parser)}', which delivers one literal key instead of an object. Call app.set('query parser', 'extended'), or declare objectNotation on the parameter.`,
+        });
+    }
+    /**
+     * Guard: Express parses a body only for the media types a registered parser declares, and an
+     * unparsed body reaches the handler as `req.body === undefined` with no error (form-body-probe
+     * N6) — a tool the backend answers as if every field were absent. The default parsers are
+     * `jsonParser` and `urlencodedParser`, visible by name on the router stack (N7); a text body
+     * needs `app.useBodyParser('text')`. Only Express is checked, for `reportUnparsedBrackets`'s
+     * reason.
+     */
+    lacksBodyParser(descriptor) {
+        const contentType = descriptor.requestBody?.contentType;
+        const needed = contentType === textMediaType
+            ? "textParser"
+            : contentType === urlEncodedMediaType
+                ? "urlencodedParser"
+                : undefined;
+        const adapter = this.adapterHost?.httpAdapter;
+        if (needed === undefined ||
+            adapter === undefined ||
+            adapter.getType() !== "express") {
+            return undefined;
+        }
+        const instance = adapter.getInstance();
+        const stack = instance.router?.stack ?? instance._router?.stack ?? [];
+        return stack.some((layer) => layer.name === needed) ? undefined : needed;
+    }
+    build(loads) {
+        const prior = [];
+        const report = (diagnostic) => {
+            prior.push(diagnostic);
+        };
+        const routePaths = createRoutePaths(this.applicationConfig);
+        const globalPrefix = this.applicationConfig.getGlobalPrefix();
+        const versioningOptions = this.applicationConfig.getVersioning();
+        const mcpPath = this.options.resourceServer?.mcpPath ?? "/mcp";
+        this.checkMetadataPath(globalPrefix, mcpPath, routePaths, report);
+        const refDescription = this.options.files.resolver?.refDescription;
+        const files = refDescription === undefined ? undefined : { refDescription };
+        const applicationId = this.modules.applicationId;
+        const controllers = this.discovery
+            .getControllers()
+            .filter((wrapper) => typeof wrapper.metatype === "function")
+            .map((wrapper) => {
+            const modulePath = modulePathOf(wrapper.host?.metatype, applicationId);
+            return {
+                metatype: wrapper.metatype,
+                ...(modulePath === undefined ? {} : { modulePath }),
+            };
+        });
+        const discovered = discoverEndpoints(controllers, {
+            ...(this.options.schema === undefined
+                ? {}
+                : { schema: this.options.schema }),
+            ...(versioningOptions === undefined ? {} : { versioningOptions }),
+            globalPrefix,
+            routePaths,
+            severity: (code) => severityOf(code, this.options.diagnostics),
+            queryGrouping: this.options.query.grouping,
+            report,
+        });
+        const reserved = routePaths
+            .create({ globalPrefix, methodPath: mcpPath }, RequestMethod.ALL)
+            .map(normalizeRoute);
+        const families = new Map();
+        const routed = discovered.filter((endpoint) => {
+            if (reserved.some((path) => endpoint.descriptor.route.startsWith(path))) {
+                return false;
+            }
+            const family = endpoint.hints.family;
+            if (family === undefined) {
+                return true;
+            }
+            const resolution = resolveFamily(family, `${endpoint.controller.name}.${endpoint.handlerName}`, endpoint.hints.variants ?? [], this.options.families, loads);
+            if (resolution.kind === "refused") {
+                report(resolution.diagnostic);
+                return false;
+            }
+            if (resolution.kind === "members") {
+                resolution.diagnostics.forEach(report);
+                families.set(endpoint, resolution);
+            }
+            return true;
+        });
+        const built = buildCatalog(routed.map((endpoint) => {
+            const tags = endpoint.hints.tags ?? this.options.tags?.(endpoint.controller.name);
+            const searchTerms = endpoint.hints.searchTerms ??
+                this.options.searchTerms?.(endpoint.controller.name);
+            return {
+                source: {
+                    controller: endpoint.controller,
+                    handlerName: endpoint.handlerName,
+                },
+                owner: `${endpoint.controller.name}.${endpoint.handlerName}`,
+                descriptor: endpoint.descriptor,
+                ...markersOf(endpoint),
+                ...(tags === undefined ? {} : { tags }),
+                ...(searchTerms === undefined ? {} : { searchTerms }),
+                declare: (cleaned) => declaredDescriptor(endpoint, this.curationFor(endpoint), cleaned, families.get(endpoint)),
+            };
+        }), {
+            selection: this.options.selection,
+            prefixMode: this.options.naming.prefixMode,
+            ...(files === undefined ? {} : { files }),
+            providers: this.options.arguments.providers,
+            severity: (code) => severityOf(code, this.options.diagnostics),
+            failOn: this.options.diagnostics.failOn ?? "fatal",
+            prior,
+            admit: (descriptor, name) => {
+                const missingParser = this.lacksBodyParser(descriptor);
+                return missingParser === undefined
+                    ? undefined
+                    : {
+                        code: "body_parser_missing",
+                        message: `Tool '${name}' sends a ${descriptor.requestBody?.contentType ?? ""} body, but this application registers no ${missingParser}; the handler would receive no body. Register the parser with app.useBodyParser(), or declare another media type.`,
+                    };
+            },
+            inspect: (entries, inspectReport) => this.reportUnparsedBrackets(entries, inspectReport),
+        });
+        return { ...built, discovered: discovered.length };
+    }
+    checkMetadataPath(globalPrefix, mcpPath, routePaths, report) {
+        if (this.options.resourceServer === undefined || globalPrefix === "") {
+            return;
+        }
+        const metadataPath = protectedResourceMetadataPath(mcpPath);
+        const [served] = routePaths.create({ globalPrefix, methodPath: metadataPath }, RequestMethod.GET);
+        if (served === metadataPath) {
+            return;
+        }
+        report({
+            code: "prm_path_prefixed",
+            message: `The global prefix moves the protected-resource metadata to '${String(served)}', but RFC 9728 requires it at '${metadataPath}'; clients cannot discover the authorization server. Pass it to setGlobalPrefix's exclude list: setGlobalPrefix('${globalPrefix}', { exclude: ['${metadataPath}'] }).`,
+        });
+    }
+    /**
+     * Applies the declaration ladder, least specific first, with sealed fields last.
+     *
+     * Merging is per argument and per field, so a global rule that hides a tenant identifier and a
+     * method-level rule that renames a page number both survive. A decorator wins a tie against a
+     * central rule of the same specificity: it is nearer the code and that is the reading a
+     * maintainer expects.
+     */
+    curationFor(endpoint) {
+        const central = this.options.arguments.rules
+            .filter((rule) => matchesTarget(rule, endpoint))
+            .sort((a, b) => a.specificity - b.specificity);
+        assertUnambiguous(central, endpoint);
+        const layers = [
+            ...central.filter((rule) => !rule.sealed),
+            { rules: endpoint.hints.arguments ?? {}, sealed: false },
+            ...central.filter((rule) => rule.sealed),
+        ];
+        /**
+         * Collected before the merge, not during it: sealed rules are applied last so that they win,
+         * which means a check that learns the sealed names as it goes can never see an override.
+         */
+        const sealed = new Set(central
+            .filter((rule) => rule.sealed)
+            .flatMap((rule) => Object.keys(rule.rules)));
+        const merged = new Map();
+        for (const layer of layers) {
+            for (const [name, rule] of Object.entries(layer.rules)) {
+                if (sealed.has(name) && !layer.sealed) {
+                    throw new SezzleeTemplateError("sealed_curation_overridden", `Argument '${name}' is sealed on ${endpoint.controller.name}.${endpoint.handlerName}; a sealed rule cannot be overridden.`);
+                }
+                merged.set(name, rule);
+            }
+        }
+        return toCuration(Object.fromEntries(merged));
+    }
+};
+SezzleeCatalog = __decorate([
+    Injectable(),
+    __param(3, Inject(SEZZLEE_OPTIONS)),
+    __param(4, Optional()),
+    __param(5, Optional()),
+    __param(5, Inject(extensionTokens.toolRanker)),
+    __metadata("design:paramtypes", [DiscoveryService,
+        ModulesContainer,
+        ApplicationConfig, Function, HttpAdapterHost, Object])
+], SezzleeCatalog);
+export { SezzleeCatalog };
+function markersOf(endpoint) {
+    const container = combineMarkers(endpoint.containerMarkers.includes(true), endpoint.containerMarkers.includes(false));
+    const operation = combineMarkers(endpoint.operationMarkers.includes(true), endpoint.operationMarkers.includes(false));
+    return {
+        ...(container === undefined ? {} : { container }),
+        ...(operation === undefined ? {} : { operation }),
+    };
+}
+/**
+ * Rejects two central rules that set the same argument differently at the same specificity.
+ *
+ * Between levels the nearer rule simply wins, silently and by design. Within one level there is no
+ * nearer rule, so a merge would have to pick by registration order and the host would be reading a
+ * ladder that does not decide anything.
+ */
+function assertUnambiguous(rules, endpoint) {
+    const claimed = new Map();
+    for (const rule of rules) {
+        for (const [name, declaration] of Object.entries(rule.rules)) {
+            const key = `${rule.specificity}|${rule.sealed ? "sealed" : "open"}|${name}`;
+            const written = JSON.stringify(declaration);
+            const existing = claimed.get(key);
+            if (existing !== undefined && existing !== written) {
+                throw new SezzleeTemplateError("ambiguous_curation", `Two curation rules of equal specificity declare argument '${name}' differently on ${endpoint.controller.name}.${endpoint.handlerName}; narrow one of their targets.`);
+            }
+            claimed.set(key, written);
+        }
+    }
+}
+/**
+ * Folds the decorator's declarations into the descriptor.
+ *
+ * Discovery reports facts; declarations are reduced here, the same way `toolName` and
+ * `containerPrefix` are. The curation list arrives resolved because the ladder that produces it
+ * needs the host's central rules, which are not a property of the endpoint; a family's members
+ * arrive already lowered, because they were loaded from a source rather than declared.
+ */
+export function declaredDescriptor(endpoint, curation, tags, family) {
+    const hints = endpoint.hints;
+    const annotations = annotationsOf(hints);
+    const declaredFamily = family?.family ??
+        (hints.family === undefined
+            ? undefined
+            : { parameter: hints.family.parameter });
+    const variants = [
+        ...(hints.variants ?? []).map(declaredVariant),
+        ...(family?.variants ?? []),
+    ];
+    return {
+        ...endpoint.descriptor,
+        ...(hints.name === undefined ? {} : { toolName: hints.name }),
+        ...(hints.prefix === undefined ? {} : { containerPrefix: hints.prefix }),
+        ...(tags === undefined ? {} : { tags: [...tags] }),
+        ...(curation.length === 0 ? {} : { arguments: [...curation] }),
+        ...(variants.length === 0
+            ? {}
+            : { variants: variants }),
+        ...(declaredFamily === undefined ? {} : { family: declaredFamily }),
+        ...(annotations === undefined ? {} : { annotations }),
+    };
+}
+function declaredVariant(variant) {
+    const annotations = annotationsOf(variant);
+    return {
+        name: variant.name,
+        description: variant.description,
+        ...(variant.arguments === undefined
+            ? {}
+            : { arguments: toCuration(variant.arguments) }),
+        ...(variant.body === undefined
+            ? {}
+            : {
+                requestBody: {
+                    schema: variant.body,
+                    ...(variant.bodyRequired === undefined
+                        ? {}
+                        : { required: variant.bodyRequired }),
+                },
+            }),
+        ...(annotations === undefined ? {} : { annotations }),
+    };
+}
+function annotationsOf(declared) {
+    const annotations = {
+        ...(declared.readOnly === undefined
+            ? {}
+            : { readOnlyHint: declared.readOnly }),
+        ...(declared.destructive === undefined
+            ? {}
+            : { destructiveHint: declared.destructive }),
+        ...(declared.idempotent === undefined
+            ? {}
+            : { idempotentHint: declared.idempotent }),
+    };
+    return Object.keys(annotations).length === 0 ? undefined : annotations;
+}
+export function toCuration(rules) {
+    return Object.entries(rules).map(([name, rule]) => ({
+        name,
+        ...(rule.hide === undefined
+            ? {
+                ...(rule.as === undefined ? {} : { as: rule.as }),
+                ...(rule.description === undefined
+                    ? {}
+                    : { description: rule.description }),
+            }
+            : { hidden: rule.hide }),
+    }));
+}
+function matchesTarget(rule, endpoint) {
+    const target = rule.target;
+    if (target.controller !== undefined &&
+        target.controller !== endpoint.controller) {
+        return false;
+    }
+    if (target.handler !== undefined && target.handler !== endpoint.handlerName) {
+        return false;
+    }
+    if (target.method !== undefined &&
+        target.method.toUpperCase() !== endpoint.descriptor.method) {
+        return false;
+    }
+    if (target.route !== undefined &&
+        !matchesRoute(target.route, endpoint.descriptor.route)) {
+        return false;
+    }
+    return true;
+}

package/dist/decorators.d.ts

@@ -0,0 +1,172 @@
+import type { ArgumentFill, EndpointDescriptor, JsonSchemaObject } from "@sezzlee/core";
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * A curation rule for one argument.
+ *
+ * The union is what makes "hidden but also renamed" unrepresentable: a hidden argument has no
+ * agent-facing name or description to carry.
+ */
+export type ArgumentRule = {
+    readonly hide?: undefined;
+    readonly as?: string;
+    readonly description?: string;
+} | {
+    readonly hide: ArgumentFill;
+};
+export declare const hidden: {
+    readonly value: (value: JsonValue) => ArgumentRule;
+    readonly from: (source: string) => ArgumentRule;
+    readonly omit: () => ArgumentRule;
+};
+export type ArgumentRules<T> = {
+    readonly [K in keyof T & string]?: ArgumentRule;
+};
+/**
+ * Key-checks a curation against a DTO's own keys.
+ *
+ * Optional: `arguments` accepts a plain record. Reaching for this moves the
+ * `curation_unresolved` diagnostic from startup to compile time, which is where a typo belongs.
+ */
+export declare function curate<T>(rules: ArgumentRules<T>): ArgumentRules<T>;
+type DescriptorParameter = NonNullable<EndpointDescriptor["parameters"]>[number];
+export interface McpParameterOptions {
+    readonly required?: boolean;
+    readonly style?: DescriptorParameter["style"];
+    readonly explode?: boolean;
+}
+/**
+ * What one status code returns.
+ *
+ * A bare class is bound through the same TypeShape reader the request body uses; a one-element
+ * tuple declares a collection of it; `{ schema }` supplies a schema verbatim; `{}` declares a
+ * status that carries no body.
+ */
+export type McpResponseDeclaration = NewableFunction | readonly [NewableFunction] | {
+    readonly schema: JsonSchemaObject;
+} | Record<string, never>;
+export interface McpFileFieldOptions {
+    /** A `FilesInterceptor` field, sent as repeated parts. */
+    readonly multiple?: boolean;
+    readonly required?: boolean;
+    readonly description?: string;
+    /** The media type the backend expects; it becomes the part's default. */
+    readonly mediaType?: string;
+}
+export interface McpToolOptions {
+    readonly name?: string;
+    readonly prefix?: string;
+    readonly description?: string;
+    readonly body?: JsonSchemaObject;
+    /**
+     * What the endpoint returns, keyed by status code.
+     *
+     * A declaration is needed because a handler's return type is not readable at runtime: TypeScript
+     * emits `design:returntype` with the generic erased, so an `async` handler reports `Promise` and
+     * a collection reports `Array`. Discovery falls back to `@nestjs/swagger`'s response metadata and
+     * then to `design:returntype`, but only a declaration here is guaranteed to be exact.
+     */
+    readonly responses?: Readonly<Record<string, McpResponseDeclaration>>;
+    /**
+     * Whether the backend requires a body at all, as distinct from requiring the
+     * fields inside it. `false` makes omitting the body expressible: the agent
+     * then sends no body rather than an empty object.
+     */
+    readonly bodyRequired?: boolean;
+    /**
+     * Per-parameter declarations keyed by parameter name. Nest exposes no runtime
+     * signal that proves a named `@Query`/`@Headers` is required, nor how an
+     * array-valued one is serialised, so both are declarations rather than
+     * inferences.
+     */
+    readonly parameters?: Readonly<Record<string, McpParameterOptions>>;
+    /**
+     * Curation declarations keyed by wire name: a parameter, a flattened body field, or the body
+     * root argument. Distinct from `parameters`, which corrects a discovered fact; these declare the
+     * agent-facing surface and span the body too.
+     */
+    readonly arguments?: Readonly<Record<string, ArgumentRule>>;
+    /**
+     * The operation's grouping labels, replacing the one derived from the container rather than
+     * adding to it, so a host can remove a grouping it did not choose. They are `search_tools`
+     * filter keys and search index vocabulary at once ([search-semantics.md]).
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Search vocabulary the operation's own text does not contain. Indexed like the description,
+     * never a filter key and never shown to the agent ([search-semantics.md]).
+     */
+    readonly searchTerms?: readonly string[];
+    /**
+     * The body's media type, replacing the one discovery chooses. It is the host's own claim that a
+     * parser for it is registered; when `@ApiConsumes` also lists types, it must be one of them.
+     */
+    readonly consumes?: string;
+    /**
+     * The multipart file fields, keyed by the name the file interceptor reads. `FileInterceptor`
+     * keeps that name in a closure, so without a declaration here or an `@ApiBody` schema marking
+     * the field `format: "binary"` the endpoint is dropped rather than guessed at.
+     */
+    readonly files?: Readonly<Record<string, McpFileFieldOptions>>;
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    readonly idempotent?: boolean;
+    readonly variants?: readonly McpVariantOptions[];
+    readonly family?: McpToolFamilyOptions;
+}
+/**
+ * The operation dispatches on one parameter, and each of its variants is a member that writes its
+ * own key there ([tool-families.md]).
+ *
+ * @param parameter the dispatch parameter's wire name
+ * @param source the name a member source was registered under with `options.families.provide`;
+ * without one the members are the handler's `@McpVariant`s alone
+ */
+export interface McpToolFamilyOptions {
+    readonly parameter: string;
+    readonly source?: string;
+}
+/**
+ * Behaviour hints a member declares. The union keeps a read-only member from also claiming to be
+ * destructive, which MCP defines as meaningless.
+ */
+export type McpToolEffect = {
+    readonly readOnly: true;
+    readonly destructive?: never;
+    readonly idempotent?: boolean;
+} | {
+    readonly readOnly?: false;
+    readonly destructive?: boolean;
+    readonly idempotent?: boolean;
+};
+/**
+ * One of several tools produced from a single operation.
+ *
+ * `name` and `description` are non-optional because one description cannot honestly describe two
+ * tools whose arguments are hidden differently; `tsc` therefore enforces the rule at the
+ * declaration site.
+ */
+export interface McpVariantOptions {
+    readonly name: string;
+    readonly description: string;
+    readonly arguments?: Readonly<Record<string, ArgumentRule>>;
+    /** A family member's own body; refused on a variant of an operation that is not a family. */
+    readonly body?: JsonSchemaObject;
+    readonly bodyRequired?: boolean;
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    readonly idempotent?: boolean;
+}
+export interface McpSelectionMarker {
+    readonly include: boolean;
+    readonly options: McpToolOptions;
+}
+export declare const MCP_SELECTION = "sezzlee:selection";
+export declare function McpVariant(options: McpVariantOptions): MethodDecorator;
+export declare function McpToolFamily(options: McpToolFamilyOptions): MethodDecorator;
+type Target = object | ((...args: never[]) => unknown);
+export declare function McpTool(options?: McpToolOptions): ClassDecorator & MethodDecorator;
+export declare function McpIgnore(): ClassDecorator & MethodDecorator;
+export declare function markersOf(target: Target | undefined): McpSelectionMarker[];
+export {};