@bevel-software/platform-mcp-core 0.23.0 → 0.24.0

package/dist/chain-example.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The example call in `call_tool_chain`'s description, derived from the live
+ * catalog — the NAME and the ARGUMENTS both.
+ *
+ * The name alone was not enough. A first pass read the callable name off the
+ * catalog (which the two surfaces spell differently: `KNOWLEDGE_BASE.read_file`
+ * on the hosted endpoint, `hexis.hexis_read_file` through the local server) but
+ * kept the arguments as fixed text, `{ body: { path: '…' } }`. Every knowledge-
+ * base tool declares `branch` REQUIRED, so an agent copying that example got
+ * `400 … \`branch\` is required` — the acceptance criterion is that a copied
+ * example WORKS, and a right name with wrong arguments fails it just as
+ * squarely as a wrong name.
+ *
+ * So the arguments come from the tool's own input schema, and only when the
+ * schema determines them. `branch` is a free-form required string with no
+ * `default` and no `enum`: nothing in the catalog says WHICH branch, and
+ * `'main'` would be a guess that breaks on any deployment whose default branch
+ * is named otherwise — as would a guessed `path`, which has to name a file that
+ * exists. A tool like that is therefore not used for the example at all.
+ * Instead the example is the simplest call the catalog fully determines, which
+ * in practice is a no-argument discovery tool (`start_session({ body: {} })`):
+ * it demonstrates the namespace, the dotted name and the `{ body: … }` wrapper
+ * — the three things an agent actually gets wrong — and it cannot be stale,
+ * because every value in it was read from the schema rather than invented.
+ */
+/** One tool of the surface's catalog, as both surfaces already hold it. */
+export interface ChainExampleTool {
+    /** The UTCP name, e.g. `KNOWLEDGE_BASE.read_file`. */
+    utcpName: string;
+    /** The tool's UTCP input schema (`ProxiedTool.inputSchema`). */
+    inputSchema?: unknown;
+}
+export interface ChainExample {
+    /** The namespace, as the chain runtime spells it. */
+    namespace: string;
+    /**
+     * A callable NAME from the catalog — safe to print on its own, no arguments
+     * implied. Null when the catalog affords none (it is empty, or every name in
+     * it is shared by two tools): a name nothing here serves is the very thing
+     * an agent copies into a chain and watches die of `ReferenceError`.
+     */
+    name: string | null;
+    /**
+     * A complete call that works as written, or null when the catalog affords
+     * none. Null prints no example at all rather than a call that would fail:
+     * an example an agent cannot trust is worse than the shape plus `tools_info`.
+     */
+    call: string | null;
+}
+/**
+ * The namespace, a callable name and a working call for this connection.
+ *
+ * This connection's OWN namespace is used when it has any tools: a third-party
+ * `.tool` is a worse example than a core tool, since what an agent most needs
+ * demonstrated is how to reach the knowledge base.
+ */
+export declare function chainExample(namespace: string, tools: readonly ChainExampleTool[]): ChainExample;
+//# sourceMappingURL=chain-example.d.ts.map

package/dist/chain-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-example.d.ts","sourceRoot":"","sources":["../src/chain-example.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AA0ND;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,YAAY,CAqChG"}

package/dist/chain-example.js

@@ -0,0 +1,259 @@
+import { sanitizeIdentifier, utcpNameToTsInterfaceName } from './code-mode-names.js';
+/** How deep into a schema to look before giving up on writing a value for it. */
+const MAX_DEPTH = 6;
+/**
+ * The one name preferred as the example call when several are equally simple.
+ *
+ * `start_session` is the call an external agent is told to make first in any
+ * case, and the one with no preconditions — no branch, no path, no per-user
+ * credential, nothing that has to already exist. Among no-argument tools that
+ * makes it the one least able to fail for a reason the schema cannot see.
+ */
+const PREFERRED_EXAMPLE_TOOLS = ['start_session'];
+/**
+ * A single-quoted JavaScript string, safe to paste into chain source AND into
+ * the Markdown code span the description prints the example inside.
+ *
+ * Every escape here is load-bearing. A raw line terminator inside a
+ * single-quoted literal is a SyntaxError, so a schema `default` or `enum` entry
+ * carrying one would print a chain that cannot even parse; a backtick would
+ * close the `` `return …;` `` span the example is printed in and truncate the
+ * call halfway. U+2028/U+2029 are the pair worth naming: line terminators to a
+ * JavaScript parser, invisible to everything else.
+ */
+function quote(text) {
+    let out = '';
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === "'")
+            out += "\\'";
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '`')
+            out += '\\x60';
+        else if (cp < 0x20 || cp === 0x7f)
+            out += `\\x${cp.toString(16).padStart(2, '0')}`;
+        else if (cp === 0x2028 || cp === 0x2029)
+            out += `\\u${cp.toString(16)}`;
+        else
+            out += ch;
+    }
+    return `'${out}'`;
+}
+/** Whether `value` is of JSON Schema `type`. An unrecognised type word matches nothing. */
+function matchesJsonType(value, type) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'number':
+            return typeof value === 'number';
+        case 'null':
+            return value === null;
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        default:
+            return false;
+    }
+}
+/**
+ * Whether `value` satisfies the constraints declared BESIDE the `default` or
+ * `enum` it was read from.
+ *
+ * A schema is free to contradict itself — `enum: [1, 5]` with `minimum: 5`
+ * makes the first entry invalid — and the whole point of reading a value off
+ * the schema instead of inventing one is that the printed call works. So a
+ * candidate that fails any sibling bound is not used, and a keyword this does
+ * not know is not assumed to pass: an unrecognised `type` word, or a `pattern`
+ * this runtime cannot compile, rejects the candidate rather than advertising a
+ * call the server may refuse.
+ */
+function satisfiesConstraints(value, s) {
+    const declared = Array.isArray(s.type)
+        ? s.type.filter((t) => typeof t === 'string')
+        : typeof s.type === 'string'
+            ? [s.type]
+            : [];
+    if (declared.length > 0 && !declared.some((t) => matchesJsonType(value, t)))
+        return false;
+    if ('const' in s && s.const !== value)
+        return false;
+    if (typeof value === 'number') {
+        if (typeof s.minimum === 'number' && value < s.minimum)
+            return false;
+        if (typeof s.maximum === 'number' && value > s.maximum)
+            return false;
+        if (typeof s.exclusiveMinimum === 'number' && value <= s.exclusiveMinimum)
+            return false;
+        if (typeof s.exclusiveMaximum === 'number' && value >= s.exclusiveMaximum)
+            return false;
+        if (typeof s.multipleOf === 'number' && s.multipleOf > 0 && !Number.isInteger(value / s.multipleOf))
+            return false;
+    }
+    if (typeof value === 'string') {
+        if (typeof s.minLength === 'number' && value.length < s.minLength)
+            return false;
+        if (typeof s.maxLength === 'number' && value.length > s.maxLength)
+            return false;
+        if (typeof s.pattern === 'string') {
+            try {
+                if (!new RegExp(s.pattern).test(value))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/** `value` as JavaScript source, or null when it is not a plain scalar. */
+function scalarLiteral(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return quote(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+/**
+ * An object key, bare when it is an identifier and quoted when it is not.
+ *
+ * `__proto__` is neither. In an object literal, `__proto__: v` does not create
+ * a property — it SETS THE PROTOTYPE, and quoting it (`'__proto__': v`) does
+ * exactly the same. So a copied example would send the tool an object without
+ * the argument its schema requires. Only the computed form is an ordinary own
+ * property.
+ */
+function propertyKey(key) {
+    if (key === '__proto__')
+        return `[${quote(key)}]`;
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? key : quote(key);
+}
+/**
+ * The smallest value that satisfies `schema`, as JavaScript source, or null
+ * when the schema does not say enough to write one.
+ *
+ * Only the REQUIRED properties are written: an optional argument an agent did
+ * not ask for has no business in an example. A free-form required string,
+ * number or boolean returns null — the schema names a type, not a value, and
+ * inventing one is exactly how the example stopped working.
+ */
+function satisfyingValue(schema, depth) {
+    if (depth > MAX_DEPTH || !schema || typeof schema !== 'object' || Array.isArray(schema))
+        return null;
+    const s = schema;
+    // A `default`, or a closed `enum`, is the schema itself naming a value —
+    // but only a value its OWN siblings accept (see `satisfiesConstraints`).
+    if ('default' in s) {
+        const literal = scalarLiteral(s.default);
+        if (literal !== null && satisfiesConstraints(s.default, s))
+            return { source: literal, scalars: 1 };
+    }
+    if (Array.isArray(s.enum) && s.enum.length > 0) {
+        // Every entry, not just the first: a schema may list one its own bounds
+        // forbid, and any entry that satisfies them is an equally good example.
+        for (const candidate of s.enum) {
+            const literal = scalarLiteral(candidate);
+            if (literal !== null && satisfiesConstraints(candidate, s))
+                return { source: literal, scalars: 1 };
+        }
+    }
+    const declared = Array.isArray(s.type) ? s.type.find((t) => typeof t === 'string') : s.type;
+    const type = typeof declared === 'string' ? declared : s.properties ? 'object' : undefined;
+    if (type === 'object') {
+        const properties = (s.properties ?? {});
+        const required = Array.isArray(s.required) ? s.required.filter((k) => typeof k === 'string') : [];
+        const parts = [];
+        let scalars = 0;
+        for (const key of required) {
+            const child = satisfyingValue(properties[key], depth + 1);
+            // A required argument whose value the schema does not determine
+            // disqualifies the whole tool: a call missing it is a call that 400s.
+            if (!child)
+                return null;
+            parts.push(`${propertyKey(key)}: ${child.source}`);
+            scalars += child.scalars;
+        }
+        // A schema may demand more properties than it names in `required` — an
+        // example satisfying only `required` would then be refused for being too
+        // thin, and which properties to add is not something the schema says.
+        if (typeof s.minProperties === 'number' && parts.length < s.minProperties)
+            return null;
+        return { source: parts.length > 0 ? `{ ${parts.join(', ')} }` : '{}', scalars };
+    }
+    if (type === 'array') {
+        // An empty array satisfies an array that demands no minimum. One that does
+        // needs an element whose value the schema has not named.
+        const min = typeof s.minItems === 'number' ? s.minItems : 0;
+        return min === 0 ? { source: '[]', scalars: 0 } : null;
+    }
+    if (type === 'null')
+        return { source: 'null', scalars: 1 };
+    return null;
+}
+/** Where `name` sits in {@link PREFERRED_EXAMPLE_TOOLS}; past the end when absent. */
+function preference(name) {
+    const index = PREFERRED_EXAMPLE_TOOLS.findIndex((p) => name === p || name.endsWith(`.${p}`) || name.endsWith(`_${p}`));
+    return index === -1 ? PREFERRED_EXAMPLE_TOOLS.length : index;
+}
+/**
+ * The namespace, a callable name and a working call for this connection.
+ *
+ * This connection's OWN namespace is used when it has any tools: a third-party
+ * `.tool` is a worse example than a core tool, since what an agent most needs
+ * demonstrated is how to reach the knowledge base.
+ */
+export function chainExample(namespace, tools) {
+    const ns = sanitizeIdentifier(namespace);
+    const callable = tools
+        .map((t) => ({ name: utcpNameToTsInterfaceName(t.utcpName), schema: t.inputSchema }))
+        // Sorted so that every tie below breaks the same way on every request —
+        // a description that changed between two listings of the same catalog
+        // would be its own small puzzle.
+        .sort((a, b) => a.name.localeCompare(b.name));
+    // A sanitized name that TWO catalog entries share is no use as an example:
+    // the runtime binds one of them and the description cannot say which, so a
+    // copied call might reach a tool whose arguments are not the schema the
+    // example was derived from. Both halves are drawn from the rest.
+    const occurrences = new Map();
+    for (const t of callable)
+        occurrences.set(t.name, (occurrences.get(t.name) ?? 0) + 1);
+    const unambiguous = callable.filter((t) => occurrences.get(t.name) === 1);
+    const own = unambiguous.filter((t) => t.name.startsWith(`${ns}.`));
+    const pool = own.length > 0 ? own : unambiguous;
+    // The NAME example. `read_file` is preferred because every surface has it
+    // and an agent reading the description recognises it; printed without
+    // arguments, so its required `branch` is not at stake here. From the pool or
+    // not at all: with nothing to draw on, `<namespace>.read_file` would be a
+    // name this surface invented.
+    const name = pool.find((t) => t.name.endsWith('read_file'))?.name ?? pool[0]?.name ?? null;
+    // The CALL example: the simplest call the catalog fully determines.
+    let best;
+    for (const tool of pool) {
+        const value = satisfyingValue(tool.schema, 0);
+        if (!value)
+            continue;
+        if (!best ||
+            value.scalars < best.value.scalars ||
+            (value.scalars === best.value.scalars && preference(tool.name) < preference(best.name))) {
+            best = { name: tool.name, value };
+        }
+    }
+    return { namespace: ns, name, call: best ? `${best.name}(${best.value.source})` : null };
+}
+//# sourceMappingURL=chain-example.js.map

package/dist/chain-example.js.map

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

package/dist/chain-runtime.d.ts

@@ -0,0 +1,122 @@
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+/**
+ * What runs a `call_tool_chain` chain, for every surface that offers one: the
+ * hosted MCP proxy, the local `hexis-mcp` server and the in-process agent's
+ * Mastra tool.
+ *
+ * Three things live here because all three surfaces need them to be the same:
+ *
+ *  - the BROWSER GLOBALS a chain is promised (`atob`, `btoa`, `TextEncoder`,
+ *    `TextDecoder`). `@utcp/code-mode` runs the chain in a bare `isolated-vm`
+ *    isolate — plain V8, so no Node globals (`Buffer`) and no web platform
+ *    (`atob`), and a chain could not decode base64 or bytes at all. They are
+ *    added as a PRELUDE to the chain's own source rather than injected into
+ *    the isolate's context, because the isolate is created inside
+ *    `callToolChain` and is reachable from nowhere else (see
+ *    {@link CHAIN_RUNTIME_PRELUDE});
+ *  - the ANSWER for a chain that failed. `callToolChain` does not throw when
+ *    the chain dies: it resolves `{ result: null, logs: ['[ERROR] Code
+ *    execution failed: …'] }`, so a surface that read only `result` reported
+ *    `success: true` with a null result and the agent was told nothing. Every
+ *    failure — a timeout, an undefined namespace, a tool that threw — becomes
+ *    an error that says what happened;
+ *  - the promise that a chain ALWAYS answers. A request that never settles is
+ *    what reaches an agent as a dropped connection rather than as something it
+ *    can act on, so the runner is raced against a watchdog (see
+ *    {@link WATCHDOG_GRACE_MS}).
+ */
+/**
+ * The largest `timeout` a chain may ask for, in milliseconds. One constant: it
+ * is the schema's bound on every surface AND the figure the timeout error tells
+ * the agent it may raise `timeout` to, and those two drifting apart would send
+ * an agent to retry with a value the schema then clamps straight back down.
+ */
+export declare const CHAIN_TIMEOUT_MAX_MS = 120000;
+/** The smallest `timeout` a chain may ask for, in milliseconds. */
+export declare const CHAIN_TIMEOUT_MIN_MS = 1000;
+/** The `timeout` a chain that does not ask for one gets, in milliseconds. */
+export declare const CHAIN_TIMEOUT_DEFAULT_MS = 30000;
+/**
+ * The browser globals, as ONE physical line of plain ES5 JavaScript.
+ *
+ * One line on purpose. The prelude is prepended to the agent's own chain
+ * source, and a failed chain is reported with its stack in it; a multi-line
+ * prelude would shift every line number in that stack and point the agent at
+ * the wrong line of its own code. Prepended WITHOUT a trailing newline for the
+ * same reason, so the chain's first line stays line one. (The one casualty is
+ * a `'use strict'` directive written as a chain's first statement, which is no
+ * longer in first position and so no longer applies. A chain is a handful of
+ * statements against a tool catalog, and strict mode is not something the
+ * chain protocol ever offered.)
+ *
+ * `atob`/`btoa` follow WHATWG forgiving-base64: ASCII whitespace is stripped,
+ * the padding is optional, and anything else throws rather than decoding to
+ * silent garbage. `TextEncoder`/`TextDecoder` are UTF-8 only — that is the
+ * encoding the Specification asks for, and a decoder that took a `label` it
+ * then ignored would quietly answer mojibake. `TextDecoder` drops a leading
+ * byte-order mark the way a browser's default does, and keeps it under
+ * `{ ignoreBOM: true }`: a chain decoding a UTF-8 file written on Windows would
+ * otherwise find a stray `\uFEFF` at the front of it, which breaks a
+ * `JSON.parse` and every exact-match comparison. It honours `{ stream: true }`:
+ * a chain that decodes bytes in pieces gets a character whose bytes straddle
+ * two pieces whole, where a decoder that started afresh on every call returned
+ * two replacement characters for it — and a call without the option ends the
+ * stream, answering a sequence left unfinished as one. Each is defined only when the
+ * runtime does not already have it, so a future `@utcp/code-mode` that ships
+ * them natively wins.
+ */
+export declare const CHAIN_RUNTIME_PRELUDE: string;
+/**
+ * The agent's chain source with the runtime prelude in front of it, on the same
+ * physical line, so a stack from the chain still names the chain's own line
+ * numbers (see {@link CHAIN_RUNTIME_PRELUDE}).
+ */
+export declare function withChainRuntime(code: string): string;
+/** The outcome of a chain: either its value, or the reason it has none. */
+export type ToolChainOutcome = {
+    ok: true;
+    result: unknown;
+    logs: string[];
+} | {
+    ok: false;
+    error: string;
+    logs: string[];
+    status?: number;
+    data?: unknown;
+};
+/** The namespaces and bare functions a chain can call, as the runtime spells them. */
+export interface ChainNamespaces {
+    namespaces: string[];
+    bare: string[];
+}
+/**
+ * What a chain can actually call. `@utcp/code-mode` gives every tool whose UTCP
+ * name is `MANUAL.tool` a `global.MANUAL` object, so the namespaces are the
+ * sanitized manual names — and a tool registered under a bare name becomes a
+ * global function rather than a namespace, which is why those are listed apart.
+ */
+export declare function chainNamespaces(client: CodeModeUtcpClient): Promise<ChainNamespaces>;
+/** What a chain is told when it timed out: the limit it hit, and how to raise it. */
+export declare function chainTimeoutMessage(timeoutMs: number): string;
+/** What a chain is told when it exhausted the isolate's heap. */
+export declare function chainOutOfMemoryMessage(reason: string): string;
+/** What a chain is told when it named something the runtime has no binding for. */
+export declare function unknownNamespaceMessage(identifier: string, found: ChainNamespaces): string;
+/**
+ * Turn the runner's reason into the sentence the agent reads. A timeout, an
+ * exhausted heap and an undefined namespace each get their own; anything else
+ * passes through exactly as the runner reported it, so a real cause is never
+ * replaced by a guess.
+ */
+export declare function describeChainFailure(client: CodeModeUtcpClient, reason: string, timeoutMs: number): Promise<string>;
+/**
+ * Run a chain and ALWAYS answer: with its value, or with the reason it has
+ * none. Never throws, and never leaves a caller waiting past the chain's own
+ * timeout plus {@link WATCHDOG_GRACE_MS}.
+ *
+ * What the caller does with an error is still the caller's (the hosted proxy
+ * maps a retired tool's name onto its own message first, for instance); this
+ * decides only whether there IS one and what it says about the runtime.
+ */
+export declare function runToolChain(client: CodeModeUtcpClient, code: string, timeoutMs: number): Promise<ToolChainOutcome>;
+//# sourceMappingURL=chain-runtime.d.ts.map

package/dist/chain-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-runtime.d.ts","sourceRoot":"","sources":["../src/chain-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAE5C,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,QAAS,CAAC;AA0B/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAoE1B,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAElF,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAU1F;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM7D;AAED,iEAAiE;AACjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAW1F;AA4BD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAuE3B"}