@sezzlee/sdk-nestjs 0.0.0-stage → 0.2.0

package/dist/discovery/type-shape.d.ts

@@ -0,0 +1,21 @@
+import type { TypeNode, TypeShape } from "@sezzlee/core";
+export interface TypeShapeDiagnostic {
+    readonly code: string;
+    readonly message: string;
+}
+export interface TypeShapeBinderOptions {
+    readonly typeShape?: (target: NewableFunction) => TypeShape | TypeNode | undefined;
+    readonly report?: (diagnostic: TypeShapeDiagnostic) => void;
+}
+export declare class NestTypeShapeBinder {
+    private readonly options;
+    private readonly types;
+    private readonly keys;
+    constructor(options?: TypeShapeBinderOptions);
+    bind(target: unknown): TypeShape;
+    private node;
+    private declare;
+    private members;
+    private member;
+    private fromValidators;
+}

package/dist/discovery/type-shape.js

@@ -0,0 +1,297 @@
+import { createRequire } from "node:module";
+const load = createRequire(import.meta.url);
+function scalar(kind, format) {
+    return format === undefined
+        ? { kind: "scalar", scalar: kind }
+        : { kind: "scalar", scalar: kind, format };
+}
+function unreadable(reason) {
+    return { kind: "unknown", reason };
+}
+const byConstructor = new Map([
+    [String, () => scalar("string")],
+    [Number, () => scalar("number")],
+    [Boolean, () => scalar("boolean")],
+    [Date, () => scalar("string", "date-time")],
+]);
+export class NestTypeShapeBinder {
+    options;
+    types = {};
+    keys = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    bind(target) {
+        return { root: this.node(target, undefined), types: this.types };
+    }
+    node(target, owner) {
+        if (typeof target !== "function") {
+            return unreadable(owner === undefined
+                ? "No runtime type is available for this body."
+                : `No runtime type is available for member '${owner}'.`);
+        }
+        const declared = this.options.typeShape?.(target);
+        if (declared !== undefined) {
+            return "root" in declared ? declared.root : declared;
+        }
+        const mapped = byConstructor.get(target);
+        if (mapped !== undefined) {
+            return mapped();
+        }
+        if (target === Array) {
+            return {
+                kind: "array",
+                items: unreadable("Array element type is erased at runtime; declare @Type(() => X)."),
+            };
+        }
+        if (target === Object) {
+            return unreadable("'Object' carries no readable shape; any JSON value is accepted.");
+        }
+        return { kind: "ref", ref: this.declare(target) };
+    }
+    declare(target) {
+        const existing = this.keys.get(target);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const key = target.name;
+        this.keys.set(target, key);
+        this.types[key] = { name: target.name, members: [] };
+        this.types[key] = { name: target.name, members: this.members(target) };
+        return key;
+    }
+    members(target) {
+        const validation = groupValidators(target);
+        if (validation.size === 0) {
+            this.options.report?.({
+                code: "unreadable_shape",
+                message: `'${target.name}' carries no class-validator metadata; its shape cannot be read. Decorate its properties, or declare options.schema.typeShape.`,
+            });
+            return [];
+        }
+        return [...validation].map(([property, entries]) => this.member(target, property, entries));
+    }
+    member(target, property, entries) {
+        const nested = nestedType(target, property);
+        const reflected = Reflect.getMetadata("design:type", target.prototype, property);
+        const inner = nested !== undefined
+            ? this.node(nested, property)
+            : this.fromValidators(entries, reflected, property);
+        const each = entries.some((entry) => entry.each === true);
+        const type = each ? { kind: "array", items: inner } : inner;
+        const constraints = constraintsOf(entries);
+        return {
+            name: property,
+            type,
+            required: !entries.some((entry) => entry.type === "conditionalValidation"),
+            readOnly: false,
+            constructorBound: false,
+            ...(constraints === undefined ? {} : { constraints }),
+        };
+    }
+    fromValidators(entries, reflected, property) {
+        const enumFacts = enumFactsOf(entries);
+        if (enumFacts !== undefined) {
+            return { kind: "enum", enumFacts };
+        }
+        for (const entry of entries) {
+            const mapped = validatorScalar(entry.name);
+            if (mapped !== undefined) {
+                return mapped;
+            }
+        }
+        if (reflected !== undefined && reflected !== Array) {
+            return this.node(reflected, property);
+        }
+        return unreadable(`Member '${property}' has no readable type; add a class-validator type decorator or @Type(() => X).`);
+    }
+}
+/**
+ * Reads the members a `@IsEnum` or `@IsIn` decorator allows.
+ *
+ * @returns the allowed values, or `undefined` when the decorator declares none this layer can read.
+ */
+function enumValuesOf(entry) {
+    if (entry.name === "isIn") {
+        const values = entry.constraints?.[0];
+        return Array.isArray(values) ? values : undefined;
+    }
+    if (entry.name !== "isEnum") {
+        return undefined;
+    }
+    const declared = entry.constraints?.[1];
+    if (Array.isArray(declared)) {
+        return declared;
+    }
+    return memberEntriesOf(entry)?.map(([, value]) => value);
+}
+function memberEntriesOf(entry) {
+    const entity = entry.constraints?.[0];
+    if (typeof entity !== "object" || entity === null) {
+        return undefined;
+    }
+    return Object.entries(entity).filter(([key]) => Number.isNaN(Number.parseInt(key, 10)));
+}
+/**
+ * Derives {@link EnumFacts} from the first readable enum-shaped validator on a member.
+ *
+ * class-validator hands `@IsEnum` the enum object in `constraints[0]` and the already
+ * reverse-mapping-filtered value list in `constraints[1]`; the second is what the schema needs, and
+ * recomputing it from the first is only a fallback for a class-validator that predates it.
+ *
+ * A numeric enum resolves to the **integer** wire form even though `isEnum` also accepts the member
+ * name at runtime (it validates against `Object.keys(entity).map(k => entity[k])`, which on a
+ * numeric enum contains the names too). Reporting `unresolved` would publish an `anyOf` that invites
+ * the agent to send `"Active"`, which passes validation and then compares unequal to `Status.Active`
+ * everywhere in the handler. The narrower form is the honest one.
+ *
+ * @returns the facts, or `undefined` when no member list is readable or a value is not a string or
+ * an integer — a float or an object cannot be written as a JSON Schema `enum` of a single type.
+ */
+function enumFactsOf(entries) {
+    for (const entry of entries) {
+        const values = enumValuesOf(entry);
+        if (values === undefined || values.length === 0) {
+            continue;
+        }
+        const names = new Set();
+        const numbers = new Set();
+        let readable = true;
+        for (const value of values) {
+            if (typeof value === "string") {
+                names.add(value);
+            }
+            else if (typeof value === "number" && Number.isInteger(value)) {
+                numbers.add(value);
+            }
+            else {
+                readable = false;
+                break;
+            }
+        }
+        if (!readable) {
+            continue;
+        }
+        if (names.size > 0 && numbers.size > 0) {
+            return {
+                wireForm: "unresolved",
+                names: [...names],
+                numbers: [...numbers],
+            };
+        }
+        if (numbers.size > 0) {
+            return {
+                wireForm: "integer",
+                names: memberEntriesOf(entry)?.map(([key]) => key) ?? [],
+                numbers: [...numbers],
+            };
+        }
+        return { wireForm: "string", names: [...names], numbers: [] };
+    }
+    return undefined;
+}
+function validatorScalar(name) {
+    switch (name) {
+        case "isString":
+        case "isEmail":
+        case "isUrl":
+            return scalar("string");
+        case "isInt":
+            return scalar("integer");
+        case "isNumber":
+            return scalar("number");
+        case "isBoolean":
+            return scalar("boolean");
+        case "isUuid":
+            return scalar("string", "uuid");
+        case "isDate":
+        case "isDateString":
+            return scalar("string", "date-time");
+        default:
+            return undefined;
+    }
+}
+function constraintsOf(entries) {
+    const found = {};
+    const number = (value) => typeof value === "number" ? value : undefined;
+    for (const entry of entries) {
+        const first = entry.constraints?.[0];
+        switch (entry.name) {
+            case "minLength":
+            case "arrayMinSize":
+                found["minSize"] = number(first) ?? found["minSize"];
+                break;
+            case "maxLength":
+            case "arrayMaxSize":
+                found["maxSize"] = number(first) ?? found["maxSize"];
+                break;
+            case "min":
+                found["minimum"] = number(first) ?? found["minimum"];
+                break;
+            case "max":
+                found["maximum"] = number(first) ?? found["maximum"];
+                break;
+            case "matches":
+                if (first instanceof RegExp) {
+                    found["pattern"] = first.source;
+                }
+                break;
+            case "isEmail":
+                found["format"] = "email";
+                break;
+            case "isUrl":
+                found["format"] = "uri";
+                break;
+            default:
+                break;
+        }
+    }
+    for (const key of Object.keys(found)) {
+        if (found[key] === undefined) {
+            delete found[key];
+        }
+    }
+    return Object.keys(found).length === 0 ? undefined : found;
+}
+let validators;
+let transforms;
+function groupValidators(target) {
+    const grouped = new Map();
+    if (validators === undefined) {
+        try {
+            validators = load("class-validator").getMetadataStorage();
+        }
+        catch {
+            validators = null;
+        }
+    }
+    if (validators === null) {
+        return grouped;
+    }
+    const entries = validators.getTargetValidationMetadatas(target, target.name, true, false);
+    for (const entry of entries) {
+        const list = grouped.get(entry.propertyName);
+        if (list === undefined) {
+            grouped.set(entry.propertyName, [entry]);
+        }
+        else {
+            list.push(entry);
+        }
+    }
+    return grouped;
+}
+function nestedType(target, property) {
+    if (transforms === undefined) {
+        try {
+            transforms = load("class-transformer/cjs/storage").defaultMetadataStorage;
+        }
+        catch {
+            transforms = null;
+        }
+    }
+    if (transforms === null) {
+        return undefined;
+    }
+    const metadata = transforms.findTypeMetadata(target, property);
+    return metadata?.typeFunction?.();
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,29 @@
+import { HttpAdapterHost } from "@nestjs/core";
+import { type DispatchDeadline, type RequestTemplate } from "@sezzlee/core";
+import { SezzleeOptions, type InvokeTarget, type OuterRequest } from "./options.js";
+export interface DispatchResult {
+    readonly status: number;
+    readonly body: string;
+    readonly contentType?: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface ProbeResult extends DispatchResult {
+    readonly shortCircuited: boolean;
+}
+export type { DispatchDeadline };
+/** What an invocation's body needs beyond its arguments: the budgets and whom a `ref` is resolved for. */
+export interface DispatchFiles {
+    readonly target: InvokeTarget;
+    readonly maxInlineFileBytes: number;
+    readonly maxFileBytes: number;
+}
+export declare class SezzleeDispatcher {
+    private readonly adapterHost;
+    private readonly options;
+    constructor(adapterHost: HttpAdapterHost, options: SezzleeOptions);
+    dispatch(method: string, path: string, outer?: OuterRequest, deadline?: DispatchDeadline): Promise<DispatchResult>;
+    dispatch(template: RequestTemplate, args: unknown, outer?: OuterRequest, deferred?: Readonly<Record<string, unknown>>, deadline?: DispatchDeadline, files?: DispatchFiles): Promise<DispatchResult>;
+    probe(method: string, path: string, outer?: OuterRequest, deadline?: DispatchDeadline): Promise<ProbeResult>;
+    private run;
+    private refResolver;
+}

package/dist/dispatcher.js

@@ -0,0 +1,182 @@
+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 { HttpAdapterHost } from "@nestjs/core";
+import { armDeadline, compose, mergeCookieHeader, SezzleeDispatchAborted, untilAbandoned, writeBody, } from "@sezzlee/core";
+import { SezzleeFileRefused } from "./files.js";
+import { callerOf, SEZZLEE_OPTIONS, SezzleeOptions, } from "./options.js";
+import { markSyntheticRequest, wasShortCircuited } from "./markers.js";
+import { createSyntheticContext } from "./synthetic-context.js";
+const safeFilename = /^[^"\r\n\0/\\]+$/;
+const safeMediaType = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*(?:\s*;\s*[A-Za-z0-9!#$&^_.+-]+=(?:[A-Za-z0-9!#$&^_.+-]+|"[^"\r\n\\]*"))*$/;
+/**
+ * Guard: a resolver is host code, but its filename and media type land in a part header. One that
+ * would break the header, or carries a path, is skipped for the next rung of the ladder rather than
+ * written.
+ */
+function usableFilename(value) {
+    return value !== undefined && safeFilename.test(value) ? value : undefined;
+}
+function usableMediaType(value) {
+    return value !== undefined && safeMediaType.test(value) ? value : undefined;
+}
+const defaultUserAgent = "sezzlee/0.0.0";
+let SezzleeDispatcher = class SezzleeDispatcher {
+    adapterHost;
+    options;
+    constructor(adapterHost, options) {
+        this.adapterHost = adapterHost;
+        this.options = options;
+    }
+    async dispatch(target, second, outer, third, fourth, files) {
+        let method;
+        let composed;
+        let deadline;
+        if (typeof target === "string") {
+            method = target.toUpperCase();
+            composed = { pathAndQuery: second, headers: {} };
+            deadline = third;
+        }
+        else {
+            method = target.method;
+            composed = compose(target, second, third, files === undefined
+                ? undefined
+                : { maxInlineFileBytes: files.maxInlineFileBytes });
+            deadline = fourth;
+        }
+        return this.run(method, composed, outer, false, deadline, files);
+    }
+    async probe(method, path, outer, deadline) {
+        const result = await this.run(method.toUpperCase(), { pathAndQuery: path, headers: {} }, outer, true, deadline);
+        return result;
+    }
+    async run(method, composed, outer, probe, deadline, files) {
+        const pipeline = this.adapterHost.httpAdapter?.getInstance();
+        if (!pipeline) {
+            throw new Error("sezzlee: HTTP adapter is not available; initialize the Nest application before dispatching.");
+        }
+        const synthetic = this.options.synthetic;
+        const scheme = synthetic.scheme ?? (outer?.protocol || "http");
+        const outerHost = typeof outer?.headers.host === "string" ? outer.headers.host : undefined;
+        const host = synthetic.host ?? outerHost ?? "localhost";
+        const headers = { host };
+        if (synthetic.accept) {
+            headers["accept"] = synthetic.accept;
+        }
+        headers["user-agent"] = synthetic.userAgent ?? defaultUserAgent;
+        if (outer) {
+            for (const trace of ["traceparent", "tracestate"]) {
+                const value = outer.headers[trace];
+                if (typeof value === "string") {
+                    headers[trace] = value;
+                }
+            }
+            for (const carrier of this.options.identity.carriers) {
+                const value = outer.headers[carrier];
+                if (value !== undefined) {
+                    headers[carrier] = Array.isArray(value) ? value.join(", ") : value;
+                }
+            }
+            this.options.identity.projector?.(outer, headers);
+        }
+        for (const [name, value] of Object.entries(composed.headers)) {
+            const key = name.toLowerCase();
+            if (key === "cookie") {
+                const merged = mergeCookieHeader(headers.cookie, value);
+                if (merged !== undefined) {
+                    headers.cookie = merged;
+                }
+                continue;
+            }
+            headers[key] = value;
+        }
+        const deadlineState = armDeadline(deadline);
+        try {
+            /**
+             * Guard: the deadline is armed before any `ref` is resolved, so a resolver that hangs is
+             * bounded exactly like a backend that hangs. Resolving earlier — during the validating
+             * composition — would let it outlive the call it serves.
+             */
+            const written = composed.body === undefined
+                ? undefined
+                : await untilAbandoned(writeBody(composed.body, this.refResolver(outer, files, deadlineState.signal)), deadlineState.signal, deadlineState.reason);
+            const abandoned = deadlineState.reason();
+            if (abandoned !== undefined) {
+                throw new SezzleeDispatchAborted(abandoned);
+            }
+            if (written !== undefined) {
+                headers["content-type"] = written.contentType;
+            }
+            const { req, res, result, abort } = createSyntheticContext(method, composed.pathAndQuery, headers, scheme, written?.bytes, outer?.connection);
+            markSyntheticRequest(req, probe);
+            deadlineState.onAbandon(abort);
+            try {
+                pipeline(req, res);
+            }
+            catch (error) {
+                abort("pipeline");
+                /**
+                 * Settling the context rejects `result`, which nothing awaits on this path because the
+                 * pipeline's own error is the useful one. Without this no-op handler that rejection is
+                 * unhandled and crashes the process under Node's default policy.
+                 */
+                result.catch(() => undefined);
+                throw error;
+            }
+            const dispatched = await result;
+            return { ...dispatched, shortCircuited: wasShortCircuited(req) };
+        }
+        finally {
+            deadlineState.dispose();
+        }
+    }
+    refResolver(outer, files, signal) {
+        return async (file, field) => {
+            const resolver = this.options.files.resolver;
+            if (resolver === undefined || files === undefined) {
+                throw new Error(`sezzlee: file argument '${field}' is a ref but no file resolver is bound.`);
+            }
+            const limit = files.maxFileBytes;
+            const outcome = await resolver.resolve({
+                ref: file.ref,
+                field,
+                target: files.target,
+                caller: callerOf(outer),
+                maxBytes: limit,
+                signal,
+            });
+            if (!outcome.ok) {
+                throw new SezzleeFileRefused(field, outcome.reason, limit);
+            }
+            if (outcome.bytes.byteLength > limit) {
+                throw new SezzleeFileRefused(field, "too_large", limit);
+            }
+            return {
+                bytes: outcome.bytes,
+                filename: file.filename ??
+                    usableFilename(outcome.filename) ??
+                    file.fallbackFilename,
+                mediaType: file.mediaType ??
+                    usableMediaType(outcome.mediaType) ??
+                    file.fallbackMediaType,
+            };
+        };
+    }
+};
+SezzleeDispatcher = __decorate([
+    Injectable(),
+    __param(1, Inject(SEZZLEE_OPTIONS)),
+    __metadata("design:paramtypes", [HttpAdapterHost,
+        SezzleeOptions])
+], SezzleeDispatcher);
+export { SezzleeDispatcher };

package/dist/extension-points.d.ts

@@ -0,0 +1,34 @@
+import type { InjectionToken, Provider, Type } from "@nestjs/common";
+import type { SezzleeCache, ToolRanker } from "@sezzlee/core";
+import type { CallerScopeResolver } from "./cache.js";
+import type { InvokeResultMapper } from "./invoke-result-mapper.js";
+import type { VisibilityEvaluator } from "./visibility/evaluator.js";
+import type { ProbeEvaluator } from "./visibility/probe.js";
+export interface ExtensionPoints {
+    cache: SezzleeCache;
+    callerScopeResolver: CallerScopeResolver;
+    invokeResultMapper: InvokeResultMapper;
+    visibilityEvaluator: VisibilityEvaluator;
+    probeEvaluator: ProbeEvaluator;
+    toolRanker: ToolRanker | null;
+}
+export declare const extensionTokens: {
+    readonly cache: symbol;
+    readonly callerScopeResolver: symbol;
+    readonly invokeResultMapper: symbol;
+    readonly visibilityEvaluator: symbol;
+    readonly probeEvaluator: symbol;
+    readonly toolRanker: symbol;
+};
+export type OverrideProvider<T> = {
+    useClass: Type<T>;
+} | {
+    useFactory: (...args: never[]) => T | Promise<T>;
+    inject?: InjectionToken[];
+} | {
+    useValue: T;
+};
+export type ExtensionOverrides = Partial<{
+    [K in keyof ExtensionPoints]: OverrideProvider<ExtensionPoints[K]>;
+}>;
+export declare function toProviders(overrides?: ExtensionOverrides): Provider[];

package/dist/extension-points.js

@@ -0,0 +1,35 @@
+export const extensionTokens = {
+    cache: Symbol("SEZZLEE_CACHE"),
+    callerScopeResolver: Symbol("SEZZLEE_CALLER_SCOPE_RESOLVER"),
+    invokeResultMapper: Symbol("SEZZLEE_INVOKE_RESULT_MAPPER"),
+    visibilityEvaluator: Symbol("SEZZLEE_VISIBILITY_EVALUATOR"),
+    probeEvaluator: Symbol("SEZZLEE_PROBE_EVALUATOR"),
+    toolRanker: Symbol("SEZZLEE_TOOL_RANKER"),
+};
+export function toProviders(overrides) {
+    if (overrides === undefined) {
+        return [];
+    }
+    const providers = [];
+    for (const key of Object.keys(extensionTokens)) {
+        const override = overrides[key];
+        if (override === undefined) {
+            continue;
+        }
+        const token = extensionTokens[key];
+        if ("useValue" in override) {
+            providers.push({ provide: token, useValue: override.useValue });
+        }
+        else if ("useFactory" in override) {
+            providers.push({
+                provide: token,
+                useFactory: override.useFactory,
+                inject: override.inject ?? [],
+            });
+        }
+        else {
+            providers.push({ provide: token, useClass: override.useClass });
+        }
+    }
+    return providers;
+}

package/dist/families.d.ts

@@ -0,0 +1,77 @@
+import { type CatalogDiagnostic, type JsonSchemaObject, type ToolFamily, type ToolVariant } from "@sezzlee/core";
+import type { McpToolEffect, McpVariantOptions } from "./decorators.js";
+/**
+ * One capability behind a dispatching operation, as a host's member source returns it.
+ *
+ * @param key the value written into the dispatch parameter; it never reaches the agent
+ * @param body the member's own request body, published as its input schema
+ */
+export type McpFamilyMember = {
+    readonly key: string | number;
+    readonly name: string;
+    readonly description: string;
+    readonly body: JsonSchemaObject;
+    readonly bodyRequired?: boolean;
+} & McpToolEffect;
+export type McpFamilySource = (context: {
+    readonly signal: AbortSignal;
+}) => Promise<readonly McpFamilyMember[]> | readonly McpFamilyMember[];
+export type FamilyLoad = {
+    readonly state: "loaded";
+    readonly members: readonly McpFamilyMember[];
+} | {
+    readonly state: "stale";
+    readonly members: readonly McpFamilyMember[];
+    readonly error: unknown;
+} | {
+    readonly state: "failed";
+    readonly error: unknown;
+};
+export type FamilyLoads = ReadonlyMap<string, FamilyLoad>;
+export declare class ToolFamilyOptions {
+    private readonly registered;
+    loadTimeoutMs: number;
+    get sources(): ReadonlyMap<string, McpFamilySource>;
+    provide(name: string, source: McpFamilySource): this;
+}
+/**
+ * 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 declare function loadFamilies(options: ToolFamilyOptions, previous: FamilyLoads | undefined): Promise<FamilyLoads>;
+export type FamilyResolution = {
+    readonly kind: "none";
+} | {
+    readonly kind: "members";
+    readonly family: ToolFamily;
+    readonly variants: readonly ToolVariant[];
+    readonly diagnostics: readonly CatalogDiagnostic[];
+} | {
+    readonly kind: "refused";
+    readonly diagnostic: CatalogDiagnostic;
+};
+export declare const sdkFamilySeverities: {
+    readonly unknown_family_source: "endpointDropped";
+    readonly family_source_failed: "endpointDropped";
+    readonly family_not_loaded: "endpointDropped";
+    readonly family_source_stale: "warning";
+    readonly family_member_rejected: "warning";
+};
+/**
+ * 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 declare function resolveFamily(family: ToolFamily & {
+    readonly source?: string;
+}, owner: string, declared: readonly McpVariantOptions[], options: ToolFamilyOptions, loads: FamilyLoads | undefined): FamilyResolution;