@novorb/mcp-core 2.1.1 → 3.0.0

package/dist/resources.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @novorb/mcp-core - Resources (static resources and URI templates), resource links, subscriptions
+ *
+ * `registerResources` mirrors `registerTools`: definitions go onto the SDK's own
+ * `McpServer.registerResource` (so `resources/list`, `resources/templates/list`, `resources/read`,
+ * template matching, completion of template variables and the `ResourceNotFoundError` are the SDK's),
+ * and mcp-core adds only what the SDK lacks:
+ *
+ * - one wrapper per resource: `Resource read: <uri or uri template>` / `Resource result: ...` log
+ *   lines (name, template, duration, size; never the content and never the filled-in URI);
+ * - thrown errors become JSON-RPC errors through `mapError` (masked, never a stack);
+ * - degraded mode: a resource whose `requires` env keys are missing is still listed and answers the
+ *   uniform `<server> is not configured: set <KEYS>`;
+ * - a size cap on every read (default `MCP_MAX_RESULT_BYTES`, per resource `maxBytes`): an oversized
+ *   read is an actionable error, never a truncated document;
+ * - shorthand results (a string is text, bytes are a blob, both with the definition's `mimeType`);
+ * - `resources/subscribe` / `resources/unsubscribe` for 2025-era clients (`subscribe: true`); updates
+ *   are published with `notify.resourceUpdated(uri)` (see `notifications.ts`);
+ * - the list pagination of `resources/list` and `resources/templates/list` (C1, `createMcpServer`).
+ *
+ *   registerResources(server, [
+ *     defineResource({ name: 'readme', uri: 'repo://readme', mimeType: 'text/markdown',
+ *       read: async () => readme }),
+ *     defineResourceTemplate({ name: 'file', uriTemplate: 'repo://files/{path}', mimeType: 'text/plain',
+ *       complete: { path: (prefix) => paths.filter((p) => p.startsWith(prefix)) },
+ *       read: async ({ variables }) => readFile(String(variables.path)) }),
+ *   ], { env, serverName: 'repo-mcp', subscribe: true });
+ *
+ * Tools point at resources instead of inlining large payloads with `resourceLink(...)` /
+ * `embeddedResource(...)`, and `createResultSpill()` connects the tool result byte cap (`onOversize`)
+ * to a resource link automatically.
+ */
+import { type AuthInfo, type CacheHint, type CallToolResult, type CompleteResourceTemplateCallback, type EmbeddedResource, type Icon, type InputRequiredResult, type ListResourcesResult, type ReadResourceResult, type RegisteredResource, type RegisteredResourceTemplate, type Resource, type ResourceLink, type ScopeChallengeHandler, type ServerContext, type Variables } from '@modelcontextprotocol/server';
+import { type RequestEra } from './client-input.js';
+import { type RuntimeSurface } from './notifications.js';
+import { type MapError } from './protocol-errors.js';
+import type { OversizeInfo } from './result-limits.js';
+import type { McpServer } from './server.js';
+import type { RequestContext } from './transport.js';
+import type { LoadedEnv } from './utils/envLoader.js';
+import { type Logger } from './utils/logger.js';
+/** What a resource read handler may return: a result, an input-required result, text, or bytes. */
+export type ResourceReadOutcome = ReadResourceResult | InputRequiredResult | string | Uint8Array;
+/** Per-read context. */
+export interface ResourceContext {
+    /** The definition name. */
+    name: string;
+    /** The URI being read (the filled-in template for a template). */
+    uri: URL;
+    /** The template variables (empty for a static resource). */
+    variables: Variables;
+    /** Aborted when the client cancels or disconnects. */
+    signal: AbortSignal;
+    /** Caller identity when the transport supplies one. */
+    authInfo?: AuthInfo;
+    /** The protocol era (undefined when invoked directly). */
+    era?: RequestEra;
+    logger: Logger;
+    /** The raw SDK context (undefined when invoked directly). */
+    sdk?: ServerContext;
+}
+interface ResourceBase {
+    name: string;
+    title?: string;
+    description?: string;
+    /** Applied to shorthand results and to contents that carry no `mimeType`. */
+    mimeType?: string;
+    /** Size in bytes, when known (advertised in `resources/list`). */
+    size?: number;
+    annotations?: Resource['annotations'];
+    icons?: Icon[];
+    _meta?: Record<string, unknown>;
+    /** 2026-07-28 cache hint for this resource's reads. */
+    cacheHint?: CacheHint;
+    /** SDK scope gate (for example `requireScopes('files:read')`). */
+    scopeChallenge?: ScopeChallengeHandler;
+    /** Env keys that must be configured; otherwise reads answer the uniform "not configured" error. */
+    requires?: readonly string[];
+    /** Max serialized bytes of one read (default MCP_MAX_RESULT_BYTES / the `maxBytes` option). */
+    maxBytes?: number;
+}
+/** A resource at a fixed URI. */
+export interface ResourceDefinition extends ResourceBase {
+    uri: string;
+    read: (ctx: ResourceContext) => Promise<ResourceReadOutcome>;
+}
+/** A family of resources under an RFC 6570 URI template (`repo://files/{path}`). */
+export interface ResourceTemplateDefinition extends ResourceBase {
+    uriTemplate: string;
+    /** Enumerate concrete resources for `resources/list` (omit when the family is not enumerable). */
+    list?: (ctx: ServerContext) => Promise<Resource[] | ListResourcesResult>;
+    /** Completion per template variable (`completion/complete` with a `ref/resource`). */
+    complete?: Record<string, CompleteResourceTemplateCallback>;
+    read: (ctx: ResourceContext) => Promise<ResourceReadOutcome>;
+}
+export type AnyResourceDefinition = ResourceDefinition | ResourceTemplateDefinition;
+/** Identity helper for a static resource definition. */
+export declare function defineResource(definition: ResourceDefinition): ResourceDefinition;
+/** Identity helper for a resource template definition. */
+export declare function defineResourceTemplate(definition: ResourceTemplateDefinition): ResourceTemplateDefinition;
+export interface RegisterResourcesOptions {
+    /** The loaded env; required for `requires`. */
+    env?: LoadedEnv;
+    /** Register only these resource names. */
+    enabled?: readonly string[];
+    /** Server name in the degraded-mode message (default "this server"). */
+    serverName?: string;
+    /** Per-service wording for thrown errors (the `registerTools` signature). */
+    mapError?: MapError;
+    /** Server-wide read cap in bytes (default MCP_MAX_RESULT_BYTES); a definition's `maxBytes` wins. */
+    maxBytes?: number;
+    /**
+     * Advertise `resources.subscribe` and serve `resources/subscribe` / `resources/unsubscribe` (2025-era
+     * clients; 2026-07-28 clients subscribe through `subscriptions/listen`). Not advertised on a 2025-era
+     * stateless HTTP instance (pass `request`), where no update could ever be delivered.
+     */
+    subscribe?: boolean;
+    /** The factory's request context (lets `subscribe` skip 2025-era stateless HTTP). */
+    request?: RequestContext;
+    /** Runtime enable/disable state (see `createRuntimeSurface`). */
+    surface?: RuntimeSurface;
+}
+/** A text resource contents entry. */
+export declare function textContents(uri: string, text: string, mimeType?: string): ReadResourceResult['contents'][number];
+/** A binary resource contents entry (base64). */
+export declare function blobContents(uri: string, data: Uint8Array, mimeType?: string): ReadResourceResult['contents'][number];
+/** Map a read outcome onto a `ReadResourceResult` (shorthands, default mimeType). */
+export declare function normalizeReadOutcome(outcome: ResourceReadOutcome, uri: string, mimeType?: string): ReadResourceResult | InputRequiredResult;
+/** A `resource_link` content block for a tool result (the client reads it with `resources/read`). */
+export declare function resourceLink(resource: {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+}): ResourceLink;
+/** An embedded `resource` content block (the contents inline in the tool result). */
+export declare function embeddedResource(contents: ReadResourceResult['contents'][number]): EmbeddedResource;
+/** Register `defs` on `server`; returns the SDK handles by name (`enable` / `disable` / `update` / `remove`). */
+export declare function registerResources(server: McpServer, defs: readonly AnyResourceDefinition[], opts?: RegisterResourcesOptions): Map<string, RegisteredResource | RegisteredResourceTemplate>;
+/**
+ * Advertise `resources.subscribe` and serve the 2025-era `resources/subscribe` / `resources/unsubscribe`
+ * on this instance (the subscribed URIs filter `notify.resourceUpdated` on a 2025-era connection).
+ * Call before the instance is connected. Idempotent.
+ */
+export declare function enableResourceSubscriptions(server: McpServer): void;
+export interface ResultSpillOptions {
+    /** URI prefix of spilled results (default `mcp-core://results/`); the template is `<prefix>{id}`. */
+    uriPrefix?: string;
+    /** How long a spilled result stays readable (default 15 minutes). */
+    ttlMs?: number;
+    /** Max spilled results kept (default 100; the oldest is dropped first). */
+    maxEntries?: number;
+    /** Max bytes of one spilled result (default 16 MiB); a larger one keeps the default isError. */
+    maxBytes?: number;
+    /** Max bytes of all spilled results together (default 64 MiB; the oldest is dropped first). */
+    maxTotalBytes?: number;
+    /** Resource name (default `tool-result`). */
+    name?: string;
+    /** Clock (tests). */
+    now?: () => number;
+}
+export interface ResultSpill {
+    /** Pass as `registerTools(..., { onOversize: spill.onOversize })`. */
+    onOversize: (info: OversizeInfo) => CallToolResult | undefined;
+    /** Register this template so clients can read the spilled results (`registerResources`). */
+    resource: ResourceTemplateDefinition;
+    /** Drop every spilled result. */
+    clear(): void;
+}
+/**
+ * Connect the tool result byte cap to resource links: an oversized result is kept in memory and the
+ * tool answers a short text plus a `resource_link` the client reads with `resources/read` (bounded by
+ * `maxBytes`, bound to the caller's `clientId`, expiring after `ttlMs`). In-memory, so on a
+ * multi-instance HTTP deployment the read must reach the same process (sticky routing) or the client
+ * gets "not found"; use a shared store in the host for that case.
+ */
+export declare function createResultSpill(options?: ResultSpillOptions): ResultSpill;
+export {};
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/dist/resources.js

@@ -0,0 +1,302 @@
+/**
+ * @novorb/mcp-core - Resources (static resources and URI templates), resource links, subscriptions
+ *
+ * `registerResources` mirrors `registerTools`: definitions go onto the SDK's own
+ * `McpServer.registerResource` (so `resources/list`, `resources/templates/list`, `resources/read`,
+ * template matching, completion of template variables and the `ResourceNotFoundError` are the SDK's),
+ * and mcp-core adds only what the SDK lacks:
+ *
+ * - one wrapper per resource: `Resource read: <uri or uri template>` / `Resource result: ...` log
+ *   lines (name, template, duration, size; never the content and never the filled-in URI);
+ * - thrown errors become JSON-RPC errors through `mapError` (masked, never a stack);
+ * - degraded mode: a resource whose `requires` env keys are missing is still listed and answers the
+ *   uniform `<server> is not configured: set <KEYS>`;
+ * - a size cap on every read (default `MCP_MAX_RESULT_BYTES`, per resource `maxBytes`): an oversized
+ *   read is an actionable error, never a truncated document;
+ * - shorthand results (a string is text, bytes are a blob, both with the definition's `mimeType`);
+ * - `resources/subscribe` / `resources/unsubscribe` for 2025-era clients (`subscribe: true`); updates
+ *   are published with `notify.resourceUpdated(uri)` (see `notifications.ts`);
+ * - the list pagination of `resources/list` and `resources/templates/list` (C1, `createMcpServer`).
+ *
+ *   registerResources(server, [
+ *     defineResource({ name: 'readme', uri: 'repo://readme', mimeType: 'text/markdown',
+ *       read: async () => readme }),
+ *     defineResourceTemplate({ name: 'file', uriTemplate: 'repo://files/{path}', mimeType: 'text/plain',
+ *       complete: { path: (prefix) => paths.filter((p) => p.startsWith(prefix)) },
+ *       read: async ({ variables }) => readFile(String(variables.path)) }),
+ *   ], { env, serverName: 'repo-mcp', subscribe: true });
+ *
+ * Tools point at resources instead of inlining large payloads with `resourceLink(...)` /
+ * `embeddedResource(...)`, and `createResultSpill()` connects the tool result byte cap (`onOversize`)
+ * to a resource link automatically.
+ */
+import { randomUUID } from 'node:crypto';
+import { isInputRequiredResult, ProtocolError, ProtocolErrorCode, ResourceTemplate, } from '@modelcontextprotocol/server';
+import { requestEra } from './client-input.js';
+import { resolveLimits } from './limits.js';
+import { bindToSurface, resourceSubscriptions } from './notifications.js';
+import { toProtocolError } from './protocol-errors.js';
+import { runWithRequestContext } from './protocol-logging.js';
+import { notConfiguredMessage } from './tools.js';
+import { getLogger } from './utils/logger.js';
+/** Identity helper for a static resource definition. */
+export function defineResource(definition) {
+    return definition;
+}
+/** Identity helper for a resource template definition. */
+export function defineResourceTemplate(definition) {
+    return definition;
+}
+function isTemplate(def) {
+    return 'uriTemplate' in def;
+}
+function contentBytes(result) {
+    let bytes = 0;
+    for (const c of result.contents) {
+        if ('text' in c && typeof c.text === 'string')
+            bytes += Buffer.byteLength(c.text, 'utf8');
+        if ('blob' in c && typeof c.blob === 'string')
+            bytes += c.blob.length;
+    }
+    return bytes;
+}
+/** A text resource contents entry. */
+export function textContents(uri, text, mimeType) {
+    return { uri, text, ...(mimeType !== undefined ? { mimeType } : {}) };
+}
+/** A binary resource contents entry (base64). */
+export function blobContents(uri, data, mimeType) {
+    return { uri, blob: Buffer.from(data).toString('base64'), ...(mimeType !== undefined ? { mimeType } : {}) };
+}
+/** Map a read outcome onto a `ReadResourceResult` (shorthands, default mimeType). */
+export function normalizeReadOutcome(outcome, uri, mimeType) {
+    if (typeof outcome === 'string')
+        return { contents: [textContents(uri, outcome, mimeType)] };
+    if (outcome instanceof Uint8Array)
+        return { contents: [blobContents(uri, outcome, mimeType)] };
+    if (isInputRequiredResult(outcome))
+        return outcome;
+    if (mimeType === undefined)
+        return outcome;
+    return { ...outcome, contents: outcome.contents.map((c) => (c.mimeType === undefined ? { ...c, mimeType } : c)) };
+}
+/** A `resource_link` content block for a tool result (the client reads it with `resources/read`). */
+export function resourceLink(resource) {
+    return { type: 'resource_link', ...resource };
+}
+/** An embedded `resource` content block (the contents inline in the tool result). */
+export function embeddedResource(contents) {
+    return { type: 'resource', resource: contents };
+}
+/** Register `defs` on `server`; returns the SDK handles by name (`enable` / `disable` / `update` / `remove`). */
+export function registerResources(server, defs, opts = {}) {
+    const handles = new Map();
+    const enabled = opts.enabled ? new Set(opts.enabled) : undefined;
+    const serverName = opts.serverName ?? 'this server';
+    const declared = new Set(opts.env?.schema.map((s) => s.key));
+    for (const def of defs) {
+        if (enabled && !enabled.has(def.name))
+            continue;
+        const requires = def.requires ?? [];
+        if (requires.length > 0 && !opts.env) {
+            throw new Error(`registerResources: resource ${def.name} declares requires but no env was passed`);
+        }
+        const undeclared = requires.filter((k) => !declared.has(k));
+        if (undeclared.length > 0) {
+            throw new Error(`registerResources: resource ${def.name} requires ${undeclared.join(', ')}, which the env schema does not declare`);
+        }
+        const label = isTemplate(def) ? def.uriTemplate : def.uri;
+        const maxBytes = def.maxBytes ?? opts.maxBytes ?? resolveLimits().maxResultBytes;
+        const read = async (uri, variables, sdk) => {
+            const log = getLogger();
+            const started = Date.now();
+            log.info(`Resource read: ${label}`, 'Resources', { resource: def.name });
+            let isError = true;
+            let bytes = 0;
+            try {
+                const missing = requires.filter((k) => !opts.env?.has(k));
+                if (missing.length > 0) {
+                    throw new ProtocolError(ProtocolErrorCode.InternalError, notConfiguredMessage(serverName, missing));
+                }
+                const ctx = {
+                    name: def.name,
+                    uri,
+                    variables,
+                    signal: sdk.mcpReq.signal,
+                    era: requestEra(sdk),
+                    logger: log,
+                    sdk,
+                    ...(sdk.http?.authInfo ? { authInfo: sdk.http.authInfo } : {}),
+                };
+                const result = normalizeReadOutcome(await def.read(ctx), uri.href, def.mimeType);
+                if (isInputRequiredResult(result)) {
+                    isError = false;
+                    return result;
+                }
+                bytes = contentBytes(result);
+                if (bytes > maxBytes) {
+                    throw new ProtocolError(ProtocolErrorCode.InternalError, `${def.name}: the resource is ${bytes} bytes, over the ${maxBytes} byte limit per response; read a narrower resource (a smaller range or a sub-path)`);
+                }
+                isError = false;
+                return result;
+            }
+            catch (err) {
+                throw toProtocolError(err, opts.mapError);
+            }
+            finally {
+                const meta = { resource: def.name, isError, durationMs: Math.round(Date.now() - started), bytes };
+                if (isError)
+                    log.warn(`Resource result: ${label}`, 'Resources', meta);
+                else
+                    log.info(`Resource result: ${label}`, 'Resources', meta);
+            }
+        };
+        const scoped = (uri, variables, sdk) => runWithRequestContext(sdk, () => read(uri, variables, sdk));
+        const metadata = {
+            ...(def.title !== undefined ? { title: def.title } : {}),
+            ...(def.description !== undefined ? { description: def.description } : {}),
+            ...(def.mimeType !== undefined ? { mimeType: def.mimeType } : {}),
+            ...(def.size !== undefined ? { size: def.size } : {}),
+            ...(def.annotations !== undefined ? { annotations: def.annotations } : {}),
+            ...(def.icons !== undefined ? { icons: def.icons } : {}),
+            ...(def._meta !== undefined ? { _meta: def._meta } : {}),
+            ...(def.cacheHint !== undefined ? { cacheHint: def.cacheHint } : {}),
+            ...(def.scopeChallenge !== undefined ? { scopeChallenge: def.scopeChallenge } : {}),
+        };
+        let handle;
+        if (isTemplate(def)) {
+            const list = def.list;
+            const template = new ResourceTemplate(def.uriTemplate, {
+                list: list
+                    ? async (ctx) => {
+                        const listed = await list(ctx);
+                        return Array.isArray(listed) ? { resources: listed } : listed;
+                    }
+                    : undefined,
+                ...(def.complete !== undefined ? { complete: def.complete } : {}),
+            });
+            handle = server.registerResource(def.name, template, metadata, (uri, variables, sdk) => scoped(uri, variables, sdk));
+        }
+        else {
+            handle = server.registerResource(def.name, def.uri, metadata, (uri, sdk) => scoped(uri, {}, sdk));
+        }
+        if (opts.surface)
+            bindToSurface(server, opts.surface, 'resource', def.name, handle);
+        handles.set(def.name, handle);
+    }
+    const legacyStatelessHttp = opts.request?.era === 'legacy' && opts.request.requestInfo !== undefined;
+    if (opts.subscribe && !legacyStatelessHttp)
+        enableResourceSubscriptions(server);
+    return handles;
+}
+const SUBSCRIBE_INSTALLED = Symbol.for('@novorb/mcp-core/resourceSubscribe');
+/**
+ * Advertise `resources.subscribe` and serve the 2025-era `resources/subscribe` / `resources/unsubscribe`
+ * on this instance (the subscribed URIs filter `notify.resourceUpdated` on a 2025-era connection).
+ * Call before the instance is connected. Idempotent.
+ */
+export function enableResourceSubscriptions(server) {
+    const low = server.server;
+    if (low[SUBSCRIBE_INSTALLED])
+        return;
+    low[SUBSCRIBE_INSTALLED] = true;
+    const listChanged = low.getCapabilities().resources?.listChanged;
+    low.registerCapabilities({ resources: { subscribe: true, ...(listChanged !== undefined ? { listChanged } : {}) } });
+    const subscriptions = resourceSubscriptions(server);
+    low.setRequestHandler('resources/subscribe', (request) => {
+        subscriptions.add(request.params.uri);
+        return {};
+    });
+    low.setRequestHandler('resources/unsubscribe', (request) => {
+        subscriptions.delete(request.params.uri);
+        return {};
+    });
+}
+/**
+ * Connect the tool result byte cap to resource links: an oversized result is kept in memory and the
+ * tool answers a short text plus a `resource_link` the client reads with `resources/read` (bounded by
+ * `maxBytes`, bound to the caller's `clientId`, expiring after `ttlMs`). In-memory, so on a
+ * multi-instance HTTP deployment the read must reach the same process (sticky routing) or the client
+ * gets "not found"; use a shared store in the host for that case.
+ */
+export function createResultSpill(options = {}) {
+    const prefix = options.uriPrefix ?? 'mcp-core://results/';
+    const ttlMs = options.ttlMs ?? 15 * 60_000;
+    const maxEntries = options.maxEntries ?? 100;
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    const maxTotalBytes = options.maxTotalBytes ?? 64 * 1024 * 1024;
+    const name = options.name ?? 'tool-result';
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    let totalBytes = 0;
+    const drop = (id) => {
+        const e = entries.get(id);
+        if (!e)
+            return;
+        totalBytes -= e.bytes;
+        entries.delete(id);
+    };
+    const prune = () => {
+        const t = now();
+        for (const [id, e] of entries)
+            if (e.expiresAt <= t)
+                drop(id);
+        while (entries.size > maxEntries || totalBytes > maxTotalBytes) {
+            const oldest = entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            drop(oldest);
+        }
+    };
+    return {
+        onOversize(info) {
+            const payload = info.result.structuredContent ?? info.result.content;
+            const json = JSON.stringify(payload);
+            const bytes = Buffer.byteLength(json, 'utf8');
+            if (bytes > maxBytes || bytes > maxTotalBytes)
+                return undefined;
+            const id = randomUUID();
+            entries.set(id, { json, bytes, owner: info.authInfo?.clientId, expiresAt: now() + ttlMs, tool: info.tool });
+            totalBytes += bytes;
+            prune();
+            const uri = `${prefix}${id}`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${info.tool}: the result is ${info.bytes} bytes, over the ${info.maxBytes} byte limit per response; it is available as the resource ${uri} for ${Math.round(ttlMs / 60_000)} minutes`,
+                    },
+                    resourceLink({
+                        uri,
+                        name,
+                        mimeType: 'application/json',
+                        size: bytes,
+                        description: `Full result of ${info.tool}`,
+                    }),
+                ],
+            };
+        },
+        resource: {
+            name,
+            uriTemplate: `${prefix}{id}`,
+            description: 'Tool results too large to return inline',
+            mimeType: 'application/json',
+            maxBytes,
+            read: async ({ variables, authInfo, uri }) => {
+                prune();
+                const id = String(variables.id);
+                const entry = entries.get(id);
+                // A foreign caller's entry answers exactly like a missing one (no existence leak).
+                if (!entry || (entry.owner !== undefined && entry.owner !== authInfo?.clientId)) {
+                    throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Resource ${uri.href} not found or expired`);
+                }
+                return entry.json;
+            },
+        },
+        clear: () => {
+            entries.clear();
+            totalBytes = 0;
+        },
+    };
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAQL,qBAAqB,EAErB,aAAa,EACb,iBAAiB,EAMjB,gBAAgB,GAIjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAmB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAuB,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAiB,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAe,MAAM,mBAAmB,CAAC;AA+D3D,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,UAA8B;IAC3D,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,sBAAsB,CAAC,UAAsC;IAC3E,OAAO,UAAU,CAAC;AACpB,CAAC;AAyBD,SAAS,UAAU,CAAC,GAA0B;IAC5C,OAAO,aAAa,IAAI,GAAG,CAAC;AAC9B,CAAC;AAED,SAAS,YAAY,CAAC,MAA0B;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1F,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,IAAY,EAAE,QAAiB;IACvE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,IAAgB,EAAE,QAAiB;IAC3E,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9G,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAClC,OAA4B,EAC5B,GAAW,EACX,QAAiB;IAEjB,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC7F,IAAI,OAAO,YAAY,UAAU;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC/F,IAAI,qBAAqB,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACnD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpH,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,QAO5B;IACC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,QAAQ,EAAE,CAAC;AAChD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,QAAgD;IAC/E,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,IAAsC,EACtC,OAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2D,CAAC;IACnF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAE7D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAChD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,IAAI,0CAA0C,CAAC,CAAC;QACrG,CAAC;QACD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,+BAA+B,GAAG,CAAC,IAAI,aAAa,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,yCAAyC,CACnH,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QAC1D,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,IAAI,aAAa,EAAE,CAAC,cAAc,CAAC;QAEjF,MAAM,IAAI,GAAG,KAAK,EAAE,GAAQ,EAAE,SAAoB,EAAE,GAAkB,EAA+B,EAAE;YACrG,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,kBAAkB,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACzE,IAAI,OAAO,GAAG,IAAI,CAAC;YACnB,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC1D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC,aAAa,EAAE,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;gBACtG,CAAC;gBACD,MAAM,GAAG,GAAoB;oBAC3B,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,GAAG;oBACH,SAAS;oBACT,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM;oBACzB,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC;oBACpB,MAAM,EAAE,GAAG;oBACX,GAAG;oBACH,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC/D,CAAC;gBACF,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACjF,IAAI,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC;oBAClC,OAAO,GAAG,KAAK,CAAC;oBAChB,OAAO,MAAuC,CAAC;gBACjD,CAAC;gBACD,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;gBAC7B,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;oBACrB,MAAM,IAAI,aAAa,CACrB,iBAAiB,CAAC,aAAa,EAC/B,GAAG,GAAG,CAAC,IAAI,qBAAqB,KAAK,oBAAoB,QAAQ,oFAAoF,CACtJ,CAAC;gBACJ,CAAC;gBACD,OAAO,GAAG,KAAK,CAAC;gBAChB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5C,CAAC;oBAAS,CAAC;gBACT,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;gBAClG,IAAI,OAAO;oBAAE,GAAG,CAAC,IAAI,CAAC,oBAAoB,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;;oBACjE,GAAG,CAAC,IAAI,CAAC,oBAAoB,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;YAChE,CAAC;QACH,CAAC,CAAC;QACF,MAAM,MAAM,GAAG,CAAC,GAAQ,EAAE,SAAoB,EAAE,GAAkB,EAA+B,EAAE,CACjG,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;QAE9D,MAAM,QAAQ,GAAG;YACf,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpF,CAAC;QAEF,IAAI,MAAuD,CAAC;QAC5D,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACtB,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,WAAW,EAAE;gBACrD,IAAI,EAAE,IAAI;oBACR,CAAC,CAAC,KAAK,EAAE,GAAkB,EAAgC,EAAE;wBACzD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;wBAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;oBAChE,CAAC;oBACH,CAAC,CAAC,SAAS;gBACb,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClE,CAAC,CAAC;YACH,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CACrF,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAC5B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACpG,CAAC;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC;IACrG,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,mBAAmB;QAAE,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAChF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,MAAmE,CAAC;IACvF,IAAI,GAAG,CAAC,mBAAmB,CAAC;QAAE,OAAO;IACrC,GAAG,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;IAChC,MAAM,WAAW,GAAG,GAAG,CAAC,eAAe,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC;IACjE,GAAG,CAAC,oBAAoB,CAAC,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACpH,MAAM,aAAa,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpD,GAAG,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,EAAE;QACvD,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,iBAAiB,CAAC,uBAAuB,EAAE,CAAC,OAAO,EAAE,EAAE;QACzD,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzC,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAoCD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,IAAI,qBAAqB,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,GAAG,MAAM,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;IACtD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;IAChE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC;IAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,MAAM,IAAI,GAAG,CAAC,EAAU,EAAQ,EAAE;QAChC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;QAChB,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC;gBAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC,IAAI,GAAG,UAAU,IAAI,UAAU,GAAG,aAAa,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC3C,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,MAAM,CAAC,CAAC;QACf,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,UAAU,CAAC,IAAI;YACb,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YACrE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACrC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9C,IAAI,KAAK,GAAG,QAAQ,IAAI,KAAK,GAAG,aAAa;gBAAE,OAAO,SAAS,CAAC;YAChE,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;YACxB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC5G,UAAU,IAAI,KAAK,CAAC;YACpB,KAAK,EAAE,CAAC;YACR,MAAM,GAAG,GAAG,GAAG,MAAM,GAAG,EAAE,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,mBAAmB,IAAI,CAAC,KAAK,oBAAoB,IAAI,CAAC,QAAQ,6DAA6D,GAAG,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU;qBAC7L;oBACD,YAAY,CAAC;wBACX,GAAG;wBACH,IAAI;wBACJ,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,KAAK;wBACX,WAAW,EAAE,kBAAkB,IAAI,CAAC,IAAI,EAAE;qBAC3C,CAAC;iBACH;aACF,CAAC;QACJ,CAAC;QACD,QAAQ,EAAE;YACR,IAAI;YACJ,WAAW,EAAE,GAAG,MAAM,MAAM;YAC5B,WAAW,EAAE,yCAAyC;YACtD,QAAQ,EAAE,kBAAkB;YAC5B,QAAQ;YACR,IAAI,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE;gBAC3C,KAAK,EAAE,CAAC;gBACR,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC9B,mFAAmF;gBACnF,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;oBAChF,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC,aAAa,EAAE,YAAY,GAAG,CAAC,IAAI,uBAAuB,CAAC,CAAC;gBACxG,CAAC;gBACD,OAAO,KAAK,CAAC,IAAI,CAAC;YACpB,CAAC;SACF;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,UAAU,GAAG,CAAC,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/result-limits.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @novorb/mcp-core - Tool result limits
+ *
+ * `registerTools` enforces two caps on every tool result, by default:
+ *
+ * - items: a list-shaped result (`structuredContent` of the `PagedResult` shape `{ items, nextCursor?,
+ *   total? }`) carries at most `maxItems` items (MCP_MAX_RESULT_ITEMS, default 100; a smaller `limit`
+ *   argument wins). The rest is reached through an opaque `nextCursor`.
+ * - bytes: the serialized result is at most `maxBytes` (MCP_MAX_RESULT_BYTES, default 256 KiB). A
+ *   list-shaped result is first paged smaller; anything still too large becomes an actionable isError
+ *   result (never a truncated, invalid or schema-breaking body).
+ *
+ * Cursors are stateless. mcp-core's cursor records the tool, a fingerprint of the other arguments, the
+ * offset inside the handler's page, and the handler's own cursor for that page; on the next call the
+ * handler is re-run with its own cursor (as `args.cursor` and `ctx.cursor`) and mcp-core serves the next
+ * slice, or wraps the handler's own `nextCursor` once its page is exhausted. A cursor for another tool or
+ * other arguments, or a malformed one, is refused (`Invalid cursor: ...`), so an edited cursor can only
+ * ever address the caller's own result set. The handler must be a deterministic read for a given cursor
+ * (list tools are).
+ */
+import type { AuthInfo, CallToolResult, StandardSchemaWithJSON } from '@modelcontextprotocol/server';
+/** Per-tool overrides of the response caps. */
+export interface ToolLimits {
+    /** Max items in a list-shaped result. */
+    maxItems?: number;
+    /** Max serialized bytes of one result. */
+    maxBytes?: number;
+}
+/**
+ * A result that carries its payload under one `structuredContent` member (an envelope such as
+ * `{ data }`). The item cap applies to that member when it is an array or a PagedResult (refused, not
+ * paged: an envelope tool has no mcp-core cursor), a text block that only repeats it is counted once in
+ * the byte cap, and `hint` names the caller's real lever in both refusals.
+ */
+export interface ResultEnvelope {
+    key: string;
+    /** Advice appended to the refusals, for example "page it with query.limit and query.offset". */
+    hint?: string;
+}
+/** What `onOversize` receives when a result cannot be brought under the byte cap. */
+export interface OversizeInfo {
+    tool: string;
+    bytes: number;
+    maxBytes: number;
+    result: CallToolResult;
+    /** The caller, when the transport authenticated one (bind a spilled result to it). */
+    authInfo?: AuthInfo;
+}
+/** The decoded mcp-core tool cursor. */
+export interface ToolCursor {
+    /** Offset inside the handler's page. */
+    o: number;
+    /** The handler's own cursor for that page (absent = its first page). */
+    c?: string;
+}
+/** A short fingerprint of the arguments other than `cursor` / `limit` (binds a cursor to its query). */
+export declare function argsFingerprint(args: unknown): string;
+/**
+ * Decode `cursor` as an mcp-core tool cursor. Returns undefined when it is not one (a handler's own
+ * cursor; only allowed when `strict` is false). Throws `InvalidCursorError` for a mismatch.
+ */
+export declare function decodeToolCursor(tool: string, args: unknown, cursor: string, strict: boolean): ToolCursor | undefined;
+/** The arguments handed to the handler: `cursor` = its own cursor (or none), `limit` capped. */
+export declare function handlerArgs(args: unknown, decoded: ToolCursor | undefined, maxItems: number): unknown;
+export interface EnforceContext {
+    tool: string;
+    /** The client's arguments (cursor and limit as sent). */
+    args: unknown;
+    decoded: ToolCursor | undefined;
+    maxItems: number;
+    maxBytes: number;
+    onOversize?: (info: OversizeInfo) => CallToolResult | undefined;
+    authInfo?: AuthInfo;
+    envelope?: ResultEnvelope;
+}
+/** Apply the item and byte caps to one handler result. */
+export declare function enforceResultLimits(ctx: EnforceContext, result: CallToolResult): CallToolResult;
+/** Whether an input schema declares `cursor` and `limit` properties (required for `paginated` tools). */
+export declare function declaresPageArgs(schema: StandardSchemaWithJSON): boolean;
+//# sourceMappingURL=result-limits.d.ts.map

package/dist/result-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-limits.d.ts","sourceRoot":"","sources":["../src/result-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAIrG,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,gGAAgG;IAChG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,cAAc,CAAC;IACvB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,wEAAwE;IACxE,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAyBD,wGAAwG;AACxG,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQrD;AAcD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CASrH;AAQD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CASrG;AAUD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,cAAc,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAmFD,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,GAAG,cAAc,CAqD/F;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CASxE"}