@bevel-software/platform-mcp-core 0.25.2 → 0.27.0

package/dist/schema-validity.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Is a connected tool's input schema valid JSON Schema?
+ *
+ * AI clients ask this question themselves, and when the answer is no they drop
+ * the tool WITHOUT SAYING SO: the tool is simply missing for the agent, with
+ * nothing in Hexis to look at. So Hexis asks it first, when a server's tools
+ * are loaded, and keeps such a tool off every agent surface with a marker the
+ * server's owner can read.
+ *
+ * The check is the JSON Schema META-SCHEMA (2020-12, the draft the MCP
+ * specification names), run by `ajv` — the same validator the MCP SDK and the
+ * clients use, so a tool is hidden on exactly the violations a client would
+ * also refuse, and the reason is quoted in the words the client reports. The
+ * three refusals this started from reproduce to the character:
+ *
+ *   /properties/…/socialLinks/items/anyOf  must be an array
+ *   /properties/…/value/anyOf/0/required/0 must be a string
+ *   /properties/…/value/properties/table/type  must be equal to one of the allowed values
+ *
+ * One thing the meta-schema does not cover is checked beside it: a `pattern`
+ * (or a `patternProperties` key) that is not a compilable regular expression.
+ * The meta-schema says only that it is a string, while a client COMPILES it and
+ * drops the tool when that throws — see {@link regexDefect}.
+ *
+ * NOT a repair. Nothing here rewrites a schema — the proxy passes a connected
+ * server's schema through as sent, and an invalid one is reported, never fixed.
+ */
+/** Where a schema is not valid JSON Schema, and why. */
+export interface SchemaDefect {
+    /** JSON Pointer into the schema, e.g. `/properties/value/required/0`. */
+    path: string;
+    /** The violation in the validator's own words, e.g. `must be a string`. */
+    reason: string;
+}
+/**
+ * The first place `schema` is not valid JSON Schema, or `null` when it is.
+ *
+ * FAIL-OPEN: a schema the validator itself cannot process (an unknown
+ * `$schema` dialect, say) is reported as having no defect. A validator fault
+ * is not evidence against the tool, and the cost of being wrong here is one
+ * tool hidden from every agent.
+ */
+export declare function inputSchemaDefect(schema: unknown): SchemaDefect | null;
+/**
+ * The sentence the tool's owner reads, wherever the marker is shown — the tool
+ * setup page and `list_tool_setup` say the same thing in the same words,
+ * because they are the same finding.
+ */
+export declare function schemaDefectMarker(defect: SchemaDefect): string;
+//# sourceMappingURL=schema-validity.d.ts.map

package/dist/schema-validity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validity.d.ts","sourceRoot":"","sources":["../src/schema-validity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAwBtE;AA8ID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAE/D"}

package/dist/schema-validity.js

@@ -0,0 +1,254 @@
+/**
+ * Is a connected tool's input schema valid JSON Schema?
+ *
+ * AI clients ask this question themselves, and when the answer is no they drop
+ * the tool WITHOUT SAYING SO: the tool is simply missing for the agent, with
+ * nothing in Hexis to look at. So Hexis asks it first, when a server's tools
+ * are loaded, and keeps such a tool off every agent surface with a marker the
+ * server's owner can read.
+ *
+ * The check is the JSON Schema META-SCHEMA (2020-12, the draft the MCP
+ * specification names), run by `ajv` — the same validator the MCP SDK and the
+ * clients use, so a tool is hidden on exactly the violations a client would
+ * also refuse, and the reason is quoted in the words the client reports. The
+ * three refusals this started from reproduce to the character:
+ *
+ *   /properties/…/socialLinks/items/anyOf  must be an array
+ *   /properties/…/value/anyOf/0/required/0 must be a string
+ *   /properties/…/value/properties/table/type  must be equal to one of the allowed values
+ *
+ * One thing the meta-schema does not cover is checked beside it: a `pattern`
+ * (or a `patternProperties` key) that is not a compilable regular expression.
+ * The meta-schema says only that it is a string, while a client COMPILES it and
+ * drops the tool when that throws — see {@link regexDefect}.
+ *
+ * NOT a repair. Nothing here rewrites a schema — the proxy passes a connected
+ * server's schema through as sent, and an invalid one is reported, never fixed.
+ */
+import Ajv2020 from 'ajv/dist/2020.js';
+/**
+ * One validator for the process. `strict: false` keeps this to the
+ * meta-schema: ajv's strict mode objects to things no client refuses (an
+ * unknown keyword, a `required` naming an undeclared property), and hiding a
+ * tool that works is worse than listing one whose schema is merely unusual.
+ *
+ * `validateFormats: false` is the same rule applied to the META-schema's own
+ * `format` annotations (`$id` and `$ref` as `uri-reference`, `pattern` as
+ * `regex`). Switching them on is INERT, which is worth knowing before anyone
+ * reaches for it: `validateSchema` does not assert the meta-schema's formats
+ * at all, so every schema gets the same verdict with `validateFormats: true`
+ * as with it off — including `pattern: "["`, which ajv-formats' own `regex`
+ * function rejects when called directly. The switch changes configuration,
+ * not behaviour; `__tests__/schema-validity.test.ts` pins that.
+ *
+ * It would be the wrong thing to want in any case. An AI client never
+ * meta-validates the schema document: the MCP SDK's validator runs
+ * `{ strict: false, validateFormats: true, validateSchema: false }`
+ * (`validation/ajv-provider.js`) — formats on the INSTANCE, the schema
+ * document itself never checked against the meta-schema — so a malformed
+ * `$id` or `$ref` compiles there without complaint, and flagging one here
+ * would hide a tool every client accepts. The one URI-valued construct a
+ * client really refuses is a `$ref` it cannot RESOLVE (`can't resolve
+ * reference …` out of `compile`), and no format assertion catches that one
+ * either; none is ever offered, because `sanitizeInputSchema` replaces an
+ * unresolvable or non-local `$ref` with `{}` before the listing goes out.
+ * Each half is pinned where it belongs: what this check does NOT flag in
+ * `__tests__/schema-validity.test.ts`, and what the proxy offers in place of
+ * such a `$ref` in `__tests__/schema-pass-through.test.ts`.
+ *
+ * So the one format that does decide a client's verdict is `regex` — a client
+ * COMPILES a `pattern` — and because the meta-check misses it under either
+ * setting, it is checked directly, below.
+ */
+const ajv = new Ajv2020({ strict: false, allErrors: false, validateFormats: false });
+/**
+ * The first place `schema` is not valid JSON Schema, or `null` when it is.
+ *
+ * FAIL-OPEN: a schema the validator itself cannot process (an unknown
+ * `$schema` dialect, say) is reported as having no defect. A validator fault
+ * is not evidence against the tool, and the cost of being wrong here is one
+ * tool hidden from every agent.
+ */
+export function inputSchemaDefect(schema) {
+    // MCP requires an OBJECT input schema. `true`/`false` are legal JSON Schema
+    // but not legal here, and an array or a string is neither. Only `undefined`
+    // is ABSENT: a server that advertises `"inputSchema": null` has declared one
+    // and declared it wrong, which is a thing its owner wants to hear about.
+    if (schema === undefined)
+        return null; // absent: `toListedTool` supplies `{}`
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        return { path: '/', reason: 'must be an object' };
+    }
+    let valid;
+    try {
+        valid = ajv.validateSchema(schema);
+    }
+    catch {
+        return null;
+    }
+    if (!valid) {
+        const first = ajv.errors?.[0];
+        if (!first)
+            return null;
+        return {
+            path: first.instancePath || '/',
+            reason: withArticle(first.message ?? 'is not valid JSON Schema'),
+        };
+    }
+    return regexDefect(schema);
+}
+/** JSON Schema keywords whose value is a schema, or a list of schemas. */
+const SCHEMA_VALUED_KEYWORDS = [
+    'additionalItems',
+    'additionalProperties',
+    'allOf',
+    'anyOf',
+    'contains',
+    'contentSchema',
+    'else',
+    'if',
+    'items',
+    'not',
+    'oneOf',
+    'prefixItems',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+];
+/**
+ * Keywords whose value is a MAP of schemas: the keys are names, the values
+ * schemas. `$defs`/`definitions` are NOT walked as such: an entry there is a
+ * schema only once a reference reaches it (ajv compiles nothing else, and the
+ * listing the proxy serves drops the block and inlines only what a `$ref`
+ * reaches), so the walk follows the references instead — see
+ * {@link regexDefect}.
+ */
+const SCHEMA_MAP_KEYWORDS = ['dependentSchemas', 'patternProperties', 'properties'];
+/**
+ * A bound on the walk below, for a schema whose shape is the sender's choice.
+ * It caps the QUEUE, so neither depth nor breadth can make the check cost more
+ * than this many entries.
+ */
+const MAX_REGEX_CHECK_NODES = 50_000;
+/**
+ * The first regex-bearing keyword in `schema` that does not compile, or `null`.
+ *
+ * The meta-schema does NOT catch these: `{ "type": "string", "pattern": "[" }`
+ * is a perfectly well-formed schema document. But a client does not merely read
+ * a `pattern` — it COMPILES it (the MCP SDK's own validator is `ajv.compile`),
+ * so that schema throws there and the tool is dropped just as silently as one
+ * the meta-schema rejects. Hexis has to find it for the same reason it finds
+ * the others.
+ *
+ * Tested with the `u` flag, which is how ajv compiles a `pattern`
+ * (`unicodeRegExp`, on by default) — so the verdict matches the validator the
+ * clients actually run rather than a looser reading. The walk is iterative and
+ * only ever descends through keywords whose value IS a schema, so a tool's own
+ * field named `pattern` (or a `pattern` string inside a `const` value) is data
+ * and is left alone.
+ *
+ * A `$defs`/`definitions` entry is reached only through a local `$ref` (or
+ * `$dynamicRef`) that names it, and reported at ITS OWN path — the place in
+ * the schema the server sent, which is what its owner edits. An entry nothing
+ * references is never compiled by a client and never listed by the proxy, so
+ * a bad regex in it hides no tool anywhere and is not a defect here: this
+ * module's contract is "hidden on exactly what a client would refuse".
+ */
+function regexDefect(schema) {
+    const queue = [{ node: schema, path: '' }];
+    // Each node once, by path: two references to one entry are one schema.
+    const seen = new Set(['']);
+    // The cap bounds what is ENQUEUED, not only what is dequeued: a wide schema
+    // reaches its limit by breadth rather than depth, and a queue entry costs a
+    // path string that the node it describes does not. Past the cap the check
+    // simply stops looking, which is the fail-open rule this whole file follows.
+    const enqueue = (node, path) => {
+        if (seen.has(path) || queue.length >= MAX_REGEX_CHECK_NODES)
+            return;
+        seen.add(path);
+        queue.push({ node, path });
+    };
+    for (let i = 0; i < queue.length; i += 1) {
+        const { node, path } = queue[i];
+        if (typeof node.pattern === 'string' && !compiles(node.pattern)) {
+            return { path: `${path}/pattern`, reason: 'must be a valid regular expression' };
+        }
+        for (const keyword of ['$ref', '$dynamicRef']) {
+            const reference = node[keyword];
+            if (typeof reference !== 'string' || !reference.startsWith('#/'))
+                continue;
+            const target = resolveLocalPointer(schema, reference);
+            if (isSchemaObject(target))
+                enqueue(target, reference.slice(1));
+        }
+        for (const keyword of SCHEMA_MAP_KEYWORDS) {
+            const map = node[keyword];
+            if (!isSchemaObject(map))
+                continue;
+            for (const [key, value] of Object.entries(map)) {
+                if (keyword === 'patternProperties' && !compiles(key)) {
+                    return { path: `${path}/patternProperties/${pointerPart(key)}`, reason: 'must be a valid regular expression' };
+                }
+                if (isSchemaObject(value))
+                    enqueue(value, `${path}/${keyword}/${pointerPart(key)}`);
+            }
+        }
+        for (const keyword of SCHEMA_VALUED_KEYWORDS) {
+            const value = node[keyword];
+            if (Array.isArray(value)) {
+                value.forEach((item, index) => {
+                    if (isSchemaObject(item))
+                        enqueue(item, `${path}/${keyword}/${index}`);
+                });
+            }
+            else if (isSchemaObject(value)) {
+                enqueue(value, `${path}/${keyword}`);
+            }
+        }
+    }
+    return null;
+}
+function isSchemaObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The node a local JSON Pointer (`#/$defs/x`) names in `root`, or undefined. */
+function resolveLocalPointer(root, pointer) {
+    let node = root;
+    for (const part of pointer.slice(2).split('/')) {
+        if (!isSchemaObject(node) && !Array.isArray(node))
+            return undefined;
+        const key = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        // Own members only: `#/__proto__` must name nothing, not `Object.prototype`.
+        if (!Object.prototype.hasOwnProperty.call(node, key))
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+function compiles(pattern) {
+    try {
+        new RegExp(pattern, 'u');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A JSON Pointer path segment: `~` and `/` in a name have to be escaped. */
+function pointerPart(name) {
+    return name.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * The sentence the tool's owner reads, wherever the marker is shown — the tool
+ * setup page and `list_tool_setup` say the same thing in the same words,
+ * because they are the same finding.
+ */
+export function schemaDefectMarker(defect) {
+    return `Hidden from agents: its schema is invalid at ${defect.path} (${defect.reason}).`;
+}
+/** ajv says `must be string`; a sentence a person reads says `must be a string`. */
+function withArticle(message) {
+    return message.replace(/^must be (array|boolean|integer|null|number|object|string)$/, (_full, type) => `must be a${/^[aeiou]/.test(type) ? 'n' : ''} ${type}`);
+}
+//# sourceMappingURL=schema-validity.js.map

package/dist/schema-validity.js.map

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

package/dist/tool-interface.d.ts

@@ -0,0 +1,137 @@
+/**
+ * A tool's INTERFACE, in the two forms an agent needs it: the one-line call
+ * example that opens every description, and the argument list a refusal shows
+ * when a call did not match.
+ *
+ * Both are derived from the tool's own input schema and nothing else. A
+ * hand-written example drifts from the schema the moment either changes, and a
+ * connected server's tools would have none at all — so there is one generator
+ * here, used by the platform's own tools, by a deployment's, and by every
+ * connected server's alike.
+ *
+ * Pure: no IO, no clock, no client. The surfaces that list tools call
+ * {@link withCallExample}; the argument check beside it (`call-guards.ts`)
+ * calls {@link argumentsDoNotMatchMessage}.
+ */
+/** What every tool description starts with, on a line of its own. */
+export declare const CALL_LINE_PREFIX = "Call: ";
+/** The `kind` an arguments-do-not-match refusal carries, for a client that branches on it. */
+export declare const ARGUMENTS_DO_NOT_MATCH_KIND = "arguments-do-not-match";
+/**
+ * The sentence that leads the mismatches when every argument was wrapped in a
+ * `body` the tool does not have — the single most common wrong call, because
+ * the platform's own tools DO take their arguments that way and a connector
+ * tool's arguments are flat.
+ */
+export declare const BODY_AT_TOP_LEVEL_LINE = "This tool takes its arguments at the top level, not under \"body\".";
+/**
+ * The mirror of {@link BODY_AT_TOP_LEVEL_LINE}: the same mistake the other way
+ * round, by an agent that learned the flat shape and used it on a tool whose
+ * arguments ride a `body` envelope. The platform's route-hosted tools take that
+ * envelope, and the arguments of a flat call reach their route as query
+ * parameters instead of a body — which is how the route tells this apart from a
+ * call that simply left everything out, and can say which it was.
+ */
+export declare const ARGS_UNDER_BODY_LINE = "This tool takes its arguments under \"body\", not at the top level.";
+type Dict = Record<string, unknown>;
+/**
+ * The arguments the call example passes: one placeholder per REQUIRED
+ * argument, in the order the schema requires them, and nothing else.
+ *
+ * This is the example as a VALUE, which is what makes the example testable —
+ * every tool the platform declares is checked with it against its own schema,
+ * so an example an agent copies is one the check accepts.
+ */
+export declare function exampleArguments(inputs: unknown, depth?: number): Dict;
+/**
+ * The call example for one tool: the namespace this connection exposes, the
+ * tool's name, and its required arguments with a placeholder each, in the shape
+ * the tool really takes.
+ *
+ * `utcpName` is the tool's registered UTCP name (`<manual>.<tool>`); the
+ * namespace and name come from the same mapping the chain runtime uses, so the
+ * example is literally callable inside `call_tool_chain`. Optional arguments
+ * are left out — the example is the shortest call that can work, not a catalog.
+ */
+export declare function callExample(utcpName: string, inputs: unknown): string;
+/** The `Call:` line as it appears at the top of a description. */
+export declare function callLine(utcpName: string, inputs: unknown): string;
+/**
+ * A description with its call example ahead of it. Idempotent: a description
+ * that already opens with a `Call:` line keeps the one it has, so a surface
+ * that lists the same tool through two layers cannot stack two examples.
+ */
+export declare function withCallExample(description: string | undefined, utcpName: string, inputs: unknown): string;
+/**
+ * Split a description into its `Call:` line and the rest, so a caller that
+ * prepends text of its own (the knowledge-base tools' purpose prefix) can keep
+ * the example first — the line only does its job if it is the first thing read.
+ */
+export declare function splitCallLine(description: string): {
+    call: string | null;
+    rest: string;
+};
+/**
+ * The tool's interface as lines: every argument with its type, whether it is
+ * required, and its description — the top level, then one level below it,
+ * indented. This is what an agent needs in order to correct its call, and it
+ * is the schema's own content, never prose about it.
+ */
+export declare function describeInterface(inputs: unknown, depth?: number, indent?: string): string[];
+/**
+ * The whole refusal: one sentence that the arguments do not match, the
+ * mismatches one per line, the interface, and the call example last — the order
+ * an agent reads it in, ending with the line it can copy.
+ */
+export declare function argumentsDoNotMatchMessage(toolName: string, utcpName: string, inputs: unknown, mismatches: string[], options?: {
+    /**
+     * The schema the CALL EXAMPLE is generated from, when that is not the
+     * schema the arguments were checked against. A route-hosted tool is checked
+     * against its FLAT arguments — the ones its handler receives, and so the
+     * ones the mismatch lines and the interface name — while the example still
+     * has to show the `{ body: { … } }` envelope an agent actually types.
+     * Default: one schema for both.
+     */
+    exampleInputs?: unknown;
+}): string;
+/**
+ * A compiled check for one input schema: either the rules to check a call
+ * against, or the reason this schema cannot be used for checking.
+ *
+ * Compiled once per distinct schema and kept (see {@link checkFor}), so the
+ * check costs a walk of the arguments and nothing else per call.
+ */
+export type CompiledCheck = {
+    checkable: false;
+    reason: string;
+} | {
+    checkable: true;
+    check: (args: Dict) => string[];
+};
+/**
+ * Compile one input schema into a check, or decide it cannot be checked.
+ *
+ * Deliberately conservative: anything this module cannot reason about with
+ * certainty — a combinator, a `$ref`, a schema that is not an object — switches
+ * the check OFF rather than guessing. A checker that refuses valid calls would
+ * take tools away from every agent at once, so every rule here is one a call
+ * cannot satisfy by any reading of the schema.
+ */
+export declare function compileCheck(inputs: unknown, depth?: number): CompiledCheck;
+/**
+ * Could this pattern backtrack catastrophically? True for a group that repeats
+ * (`*`, `+`, `{…}`) and itself contains a quantifier or an
+ * alternation — `(a+)+`, `(a|a)*`, `(\w+\s?)*` — and for a backreference.
+ *
+ * JavaScript's matcher backtracks, so such a pattern, which comes from a
+ * schema someone else wrote, could hold the event loop for seconds on one
+ * caller's string. The test is a conservative over-approximation (it flags
+ * some patterns that would in fact be fast); a flagged pattern is simply not
+ * asserted, which is what this module does with any keyword it cannot judge
+ * safely.
+ */
+export declare function patternMayBacktrack(source: string): boolean;
+/** The compiled check for one input schema, compiled at most once per schema. */
+export declare function checkFor(inputs: unknown): CompiledCheck;
+export {};
+//# sourceMappingURL=tool-interface.d.ts.map

package/dist/tool-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-interface.d.ts","sourceRoot":"","sources":["../src/tool-interface.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,wEAAsE,CAAC;AAE1G;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,wEAAsE,CAAC;AAqBxG,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAqGpC;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,IAAI,CAiBjE;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAErE;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAI1G;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAKxF;AAYD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAI,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAmBnF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,GAAE;IACP;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACpB,GACL,MAAM,CASR;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,EAAE,CAAA;CAAE,CAAC;AAkBzD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,aAAa,CAmFtE;AAmHD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA6C3D;AA+CD,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CAOvD"}