agentfootprint 11.4.0 → 11.5.0

package/dist/esm/mcp/replay.js

@@ -0,0 +1,401 @@
+/**
+ * replay — who may send an MCP tool call again, and what is known of what each
+ * attempt did: two facts, decided apart and recorded apart.
+ *
+ * Pattern: a declaration read once + one permission rule + one accumulator.
+ * Role:    Layer-3 tool transport. `mcpClient({ replay })` reads the app's
+ *          declaration (`replayDeclarationOf`) when the client is built. The
+ *          call's retry series (`throttleRetry.ts` · `Series`) asks `permit`
+ *          before every repeat and records the answer beside the attempt;
+ *          `SeriesKnowledge` carries what is known of the series' effect from
+ *          one attempt to the next.
+ *
+ * ── THE LAW ──────────────────────────────────────────────────────────────────
+ * PERMISSION to repeat comes only from the app: the (server, tool) pairs it
+ * declares — the server is the client the declaration is given to — and the
+ * failure kinds each tool may be repeated on. Never from the model, a tool's
+ * description or a server's annotations (`readOnlyHint`): nothing here reads
+ * them. It is configuration, read once when the client is built — never a
+ * per-call question.
+ *
+ * KNOWLEDGE of whether an attempt ran comes only from the record and from an
+ * established service guarantee. No reply this library reads is one. A 429 is
+ * not: RFC 6585 §4 defines it as rate limiting, and `Retry-After` says when to
+ * ask again, not that asking is safe. AgentCore Runtime's session-busy body is
+ * not either: AWS documents a retryable conflict while a session starts or
+ * stops, and the body is matched by its code and words, which a server behind
+ * the runtime can send after it ran the call. So every attempt that was sent
+ * and did not complete is `unknown`; `none` is only a request never sent. A
+ * vendor's own SDK may retry its own 429s because the vendor documents its own
+ * service; a generic MCP client cannot assume that of an arbitrary server.
+ *
+ * Neither is read from the other: a permission never makes an effect known,
+ * and an effect never grants a permission.
+ *
+ * ── WHAT A REPEAT IS ─────────────────────────────────────────────────────────
+ * The same validated, authorized request sent again: the same body — the same
+ * arguments — to the same server, in the same session, as the same identity.
+ * Nothing is re-planned. A credential the library vends, or a signature, is
+ * made afresh for each attempt (signatures expire), for that same identity.
+ *
+ * ── THE POLICIES ─────────────────────────────────────────────────────────────
+ *   'compatibility' — the 11.x default, today's behaviour by name: a 429 is
+ *       repeated for every tool, on the ASSUMPTION that the server refused it
+ *       before running it. Each such repeat records that assumption; the
+ *       attempt's effect stays `unknown`, and the caller sees the error it
+ *       always did.
+ *   'app-authorized' — opt-in now, the default in the next major: a 429 or a
+ *       network failure is repeated only when the app's entry for the tool
+ *       names it. What the caller sees follows footprintjs's law
+ *       (`RequestReplay` · `uncertain`, `callLifetime.ts`): a received refusal
+ *       or error keeps the server's error as it came, its effect still
+ *       `unknown`; a call that genuinely lacked an answer somewhere — an
+ *       attempt with no response, or a request accepted over HTTP whose
+ *       JSON-RPC answer never came — and then fails, fails with
+ *       `UnknownEffectError`, its final error the cause. That needs each
+ *       request matched to its call and each answer seen; a connection that
+ *       cannot give both refuses the call before it is sent
+ *       (`replayUnavailable.ts`), so the contract never silently weakens.
+ *
+ * Under both, the adapter the app chose retries its own refusal within the
+ * budget — AgentCore's session-busy reply — as the ADAPTER's policy, on an
+ * assumption it records the same way (`permission: { by: 'adapter', assumes }`),
+ * never as evidence. And THE SIDE-EFFECT GUARD holds: a tool the app declares
+ * as making changes is never repeated automatically unless the server is
+ * declared to deduplicate by an idempotency key the call carries —
+ * footprintjs's law, a retry of an effect without a key can apply it twice. A
+ * key protects only when the server uses it; the library cannot check that.
+ *
+ * The protocol's own requests (`initialize`, `tools/list`, notifications) run
+ * no tool. The declaration does not govern them, and a 429 on one is asked
+ * again under both policies, as it always was. They file no record.
+ */
+import { errorCategory } from 'footprintjs';
+/** @internal No declaration: the compatibility policy, no tool named. */
+export const COMPATIBILITY = Object.freeze({
+    policy: 'compatibility',
+    tools: new Map(),
+});
+const POLICIES = new Set(['app-authorized', 'compatibility']);
+const KINDS = new Set(['throttle', 'network']);
+/**
+ * @internal `options` read as a declaration — `undefined` is the compatibility
+ * policy with nothing named.
+ *
+ * @throws TypeError naming the field, never echoing a value, for anything the
+ *   rule cannot mean: an unknown field, a policy or kind it does not know, an
+ *   argument name that is not one.
+ */
+export function replayDeclarationOf(options, where) {
+    if (options === undefined)
+        return COMPATIBILITY;
+    const read = new DeclarationReader(`${where}: \`replay\``);
+    const top = read.record(options, '', ['policy', 'tools', 'deduplicates']);
+    const policy = top.policy === undefined ? 'compatibility' : read.policy(top.policy);
+    const tools = new Map();
+    if (top.tools !== undefined) {
+        const named = read.record(top.tools, '.tools', undefined);
+        for (const [tool, entry] of Object.entries(named)) {
+            if (tool.length === 0)
+                read.refuse('.tools', 'tool names that are not empty');
+            tools.set(tool, read.tool(entry, tool));
+        }
+    }
+    const keyArgument = top.deduplicates === undefined ? undefined : read.deduplication(top.deduplicates);
+    return Object.freeze({
+        policy,
+        tools,
+        ...(keyArgument !== undefined && { keyArgument }),
+    });
+}
+/** Reads one declaration, refusing by field what it cannot mean. */
+class DeclarationReader {
+    where;
+    constructor(where) {
+        this.where = where;
+    }
+    /** A plain object, its own keys within `allowed` (any key when `undefined`). */
+    record(value, at, allowed) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            this.refuse(at, 'an object');
+        }
+        const record = value;
+        if (allowed !== undefined) {
+            for (const key of Object.keys(record)) {
+                if (!allowed.includes(key)) {
+                    this.refuse(at, `an object with only ${allowed.map((k) => `\`${k}\``).join(', ')}`);
+                }
+            }
+        }
+        return record;
+    }
+    policy(value) {
+        if (typeof value === 'string' && POLICIES.has(value))
+            return value;
+        return this.refuse('.policy', "'app-authorized' or 'compatibility'");
+    }
+    tool(value, tool) {
+        const at = `.tools[${JSON.stringify(tool)}]`;
+        const entry = this.record(value, at, ['on', 'changes']);
+        const on = new Set();
+        if (entry.on !== undefined) {
+            if (!Array.isArray(entry.on))
+                this.refuse(`${at}.on`, "an array of 'throttle' or 'network'");
+            for (const kind of entry.on) {
+                if (typeof kind !== 'string' || !KINDS.has(kind)) {
+                    this.refuse(`${at}.on`, "an array of 'throttle' or 'network'");
+                }
+                on.add(kind);
+            }
+        }
+        if (entry.changes !== undefined && typeof entry.changes !== 'boolean') {
+            this.refuse(`${at}.changes`, 'a boolean');
+        }
+        return Object.freeze({ on, changes: entry.changes === true });
+    }
+    deduplication(value) {
+        const declared = this.record(value, '.deduplicates', ['argument']);
+        const { argument } = declared;
+        if (typeof argument === 'string' &&
+            argument.length >= 1 &&
+            argument.length <= 128 &&
+            !hasControl(argument)) {
+            return argument;
+        }
+        return this.refuse('.deduplicates.argument', 'an argument name of 1–128 characters with no control character');
+    }
+    refuse(at, wanted) {
+        throw new TypeError(`${this.where}${at} must be ${wanted}.`);
+    }
+}
+/**
+ * @internal Whether the declaration needs a retry series even with the 429
+ * rule off (`retryOnThrottle: false`): a tool declared repeatable on
+ * `'network'`, or the `'app-authorized'` policy — its record and its "may have
+ * run" rest on the series.
+ */
+export function needsSeries(declaration) {
+    if (declaration.policy === 'app-authorized')
+        return true;
+    for (const entry of declaration.tools.values())
+        if (entry.on.has('network'))
+            return true;
+    return false;
+}
+const PROTOCOL = Object.freeze({ kind: 'protocol' });
+/** A request that may be a tool call and names no tool the rule can read: no entry applies. */
+const UNNAMED_TOOL = Object.freeze({ kind: 'tool', keyCarried: false });
+/**
+ * @internal `body` — the request exactly as it will be sent — read as a
+ * target. A declaration that names nothing under `'compatibility'` decides the
+ * same for every request, so its bodies are never parsed.
+ */
+export function replayTargetOf(body, declaration) {
+    if (declaration.policy === 'compatibility' && declaration.tools.size === 0)
+        return UNNAMED_TOOL;
+    if (body === undefined || body === null)
+        return PROTOCOL;
+    if (typeof body !== 'string')
+        return UNNAMED_TOOL;
+    let message;
+    try {
+        message = JSON.parse(body);
+    }
+    catch {
+        return UNNAMED_TOOL;
+    }
+    if (Array.isArray(message))
+        return message.some(isToolCall) ? UNNAMED_TOOL : PROTOCOL;
+    if (!isToolCall(message))
+        return PROTOCOL;
+    const params = message.params;
+    if (!isRecord(params))
+        return UNNAMED_TOOL;
+    const { name, arguments: args } = params;
+    const { keyArgument } = declaration;
+    return {
+        kind: 'tool',
+        ...(typeof name === 'string' && { name }),
+        keyCarried: keyArgument !== undefined && carriesKey(args, keyArgument),
+    };
+}
+function isToolCall(message) {
+    return isRecord(message) && message.method === 'tools/call';
+}
+/** The arguments hold a key under `argument`: a non-empty string. The server judges the rest. */
+function carriesKey(args, argument) {
+    if (!isRecord(args) || !Object.prototype.hasOwnProperty.call(args, argument))
+        return false;
+    const key = args[argument];
+    return typeof key === 'string' && key.length > 0;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** @internal A thrown failure the rule can read: footprintjs's `network` category, or nothing. */
+export function thrownFailure(error) {
+    return errorCategory(error) === 'network' ? { kind: 'network' } : undefined;
+}
+/**
+ * @internal THE rule: may the series send `target` again after `failure`?
+ * Asked before every repeat; the budget is asked after it.
+ */
+export function permit(declaration, target, failure) {
+    if (target.kind === 'protocol') {
+        // No tool runs: a refusal is asked again as it always was, a failure is not.
+        return failure.kind === 'network' ? NOT_RETRYABLE : REPEAT_PROTOCOL;
+    }
+    const entry = target.name === undefined ? undefined : declaration.tools.get(target.name);
+    // The side-effect guard comes first, under every policy and every permission.
+    if (entry?.changes === true && (declaration.keyArgument === undefined || !target.keyCarried)) {
+        return CHANGES_WITHOUT_KEY;
+    }
+    const keyed = entry?.changes === true;
+    if (failure.assumes !== undefined) {
+        return repeat({ by: 'adapter', assumes: failure.assumes }, keyed);
+    }
+    if (failure.kind !== 'session-busy' && entry?.on.has(failure.kind) === true) {
+        return repeat({ by: 'declaration', on: failure.kind }, keyed);
+    }
+    if (failure.kind === 'throttle' && declaration.policy === 'compatibility') {
+        return repeat({ by: 'compatibility', assumes: 'refused-before-execution' }, keyed);
+    }
+    return failure.kind === 'throttle' ? NOT_PERMITTED : NOT_RETRYABLE;
+}
+const REPEAT_PROTOCOL = Object.freeze({ repeat: true });
+const NOT_RETRYABLE = Object.freeze({ repeat: false, declined: 'not-retryable' });
+const NOT_PERMITTED = Object.freeze({ repeat: false, declined: 'not-permitted' });
+const CHANGES_WITHOUT_KEY = Object.freeze({
+    repeat: false,
+    declined: 'changes-without-key',
+});
+function repeat(permission, deduplicated) {
+    return {
+        repeat: true,
+        permission: Object.freeze({ ...permission, ...(deduplicated && { deduplicated: true }) }),
+    };
+}
+// ─── What is known of a series' effect ───────────────────────────────
+/**
+ * @internal What is known of a whole series' effect, one attempt at a time.
+ * Uncertainty survives: once any attempt is `unknown`, the series is, whatever
+ * later attempts show — a proven refusal does not resolve it, and a success
+ * does not prove the operation happened only once. Evidence that something ran
+ * (`applied`) is never erased by a later failure.
+ */
+export class SeriesKnowledge {
+    unknown = false;
+    applied = false;
+    note(effect) {
+        if (effect === 'unknown')
+            this.unknown = true;
+        else if (effect === 'applied')
+            this.applied = true;
+    }
+    get effect() {
+        if (this.unknown)
+            return 'unknown';
+        return this.applied ? 'applied' : 'none';
+    }
+}
+/**
+ * @internal One `tools/call` request's replay facts, shared by the series that
+ * sends it, the ledger that watches its answer, and the call that waits for it
+ * — the ledger hands all three the same object (`requestLedger.ts`).
+ *
+ * TWO LAYERS, KEPT APART. The series sees HTTP: whether an attempt got a
+ * response at all, and the status of the one it delivered. A response is not
+ * the MCP call's answer — a 202, or a stream, can be accepted and never carry
+ * it — so the ledger watches the connection's incoming messages for the
+ * JSON-RPC response to THIS request's id. And "its effect is unknown" is not
+ * "it lacked an answer": a received 429 or error is an answer whose effect is
+ * unknown.
+ *
+ * Each fact is written once, by its owner: the series (what it sent, whether an
+ * attempt lacked any response, what it delivered, the policy), the ledger (the
+ * logical answer), the call (how it settled).
+ */
+export class RequestReplay {
+    id;
+    requests = 0;
+    appAuthorized = false;
+    attemptUnanswered = false;
+    delivered;
+    logical;
+    settled;
+    failedAsMayHaveRun = false;
+    /**
+     * @param id the request's JSON-RPC id, how its answer is found.
+     * @param watched whether the connection's incoming messages are observed —
+     *   without that, the logical layer is unknown and never decides anything.
+     */
+    constructor(id, watched) {
+        this.id = id;
+        this.logical = watched ? 'awaited' : 'unwatched';
+    }
+    /** The series sent the request once more. */
+    sentOne() {
+        this.requests += 1;
+    }
+    /** The series runs under the `'app-authorized'` policy. */
+    appAuthorizedPolicy() {
+        this.appAuthorized = true;
+    }
+    /**
+     * The series: an attempt genuinely lacked an answer — no response arrived
+     * (a lost connection, a timeout, a cut). A received refusal is never this.
+     */
+    noAnswer() {
+        this.attemptUnanswered = true;
+    }
+    /** The series handed the MCP SDK a response with this status. */
+    deliveredStatus(status) {
+        this.delivered = status;
+    }
+    /** The ledger: the JSON-RPC response to this request's id arrived. */
+    answered() {
+        if (this.logical === 'awaited')
+            this.logical = 'answered';
+    }
+    /** The call settled; `mayHaveRun` when it failed as "may have run". The first word stands. */
+    settle(verdict, mayHaveRun) {
+        if (this.settled !== undefined)
+            return;
+        this.settled = verdict;
+        this.failedAsMayHaveRun = mayHaveRun;
+    }
+    get sent() {
+        return this.requests;
+    }
+    /**
+     * Under `'app-authorized'`, a call that does not complete fails as "may have
+     * run" when the call genuinely lacked an answer somewhere: an attempt got no
+     * response, or the HTTP layer accepted the request (a 2xx) and the JSON-RPC
+     * response never came. A chain of received refusals and errors is an answer
+     * throughout: it keeps the server's error.
+     */
+    get uncertain() {
+        return this.appAuthorized && (this.attemptUnanswered || this.acceptedWithoutAnswer);
+    }
+    /** The HTTP layer took the request (2xx), and the logical answer never arrived. */
+    get acceptedWithoutAnswer() {
+        const status = this.delivered;
+        return this.logical === 'awaited' && status !== undefined && status >= 200 && status < 300;
+    }
+    get verdict() {
+        return this.settled;
+    }
+    get mayHaveRun() {
+        return this.failedAsMayHaveRun;
+    }
+}
+/** Whether `text` holds a control character (C0, DEL or C1). */
+function hasControl(text) {
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=replay.js.map

package/dist/esm/mcp/replay.js.map

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

package/dist/esm/mcp/replayUnavailable.d.ts

@@ -0,0 +1,55 @@
+/**
+ * replayUnavailable — when a connection cannot keep the `'app-authorized'`
+ * contract, a call under it is refused BEFORE it is sent, and the error says why.
+ *
+ * Pattern: a readiness rule + one typed refusal.
+ * Role:    Under `'app-authorized'`, a call that genuinely lacked an answer and
+ *          then fails is raised as "may have run" (`callLifetime.ts`). That
+ *          rests on two things the library must ESTABLISH for every call,
+ *          never assume:
+ *
+ *   1. ITS REQUEST IS MATCHED to the call, by the call's private marker, taken
+ *      at the transport's `send` (`callMarker.ts`, `requestLedger.ts`).
+ *      - `'requests-unwatched'`: the library cannot watch this transport's
+ *        `send` at all (stdio, or a transport that refuses the wrap).
+ *      - `'request-unmatched'`: a request reached `send` without its call's
+ *        marker (an SDK that rebuilt the params and dropped `_meta`), so it
+ *        cannot be tied to any call.
+ *   2. ITS ANSWER IS SEEN: the JSON-RPC response to the request's id, read as
+ *      it arrives. This is checked once the connection is initialized: the
+ *      `initialize` answer must have passed the library's observer.
+ *      - `'answers-unobserved'`: it did not. An MCP SDK whose `connect`
+ *        REPLACES the transport's `onmessage` handler instead of keeping it
+ *        (SDK 1.10's `Protocol.connect` does) leaves the observer out.
+ *
+ * Without either, a request the server accepted and never answered would reach
+ * the caller as a plain timeout: the strict contract, silently weakened. So the
+ * call is refused instead, and nothing is sent. `'compatibility'` asks none of
+ * this and keeps its behaviour.
+ */
+/** Why a call under `'app-authorized'` was refused before it was sent. */
+export type McpReplayUnavailableReason = 'requests-unwatched' | 'answers-unobserved' | 'request-unmatched';
+/**
+ * A tool call refused before it was sent, because this connection cannot keep
+ * the `'app-authorized'` replay contract (`reason`). Nothing reached the server.
+ * Names the server and the tool, never an argument.
+ */
+export declare class McpReplayUnavailableError extends Error {
+    readonly reason: McpReplayUnavailableReason;
+    readonly server: string;
+    readonly tool: string;
+    readonly code: "ERR_MCP_REPLAY_UNAVAILABLE";
+    /** Nothing was sent: the refusal came before the request left the client. */
+    readonly sent: false;
+    constructor(reason: McpReplayUnavailableReason, server: string, tool: string);
+}
+/**
+ * Why a connection cannot take a call under `'app-authorized'` before anything
+ * is sent — `undefined` when it can. `ledger` is the connection's request
+ * ledger: absent when the library could not watch the transport's requests.
+ * A request that reaches the transport without its marker is refused there, by
+ * the ledger (`'request-unmatched'`).
+ */
+export declare function unavailableBeforeSending(ledger: {
+    readonly answersObserved: boolean;
+} | undefined): McpReplayUnavailableReason | undefined;

package/dist/esm/mcp/replayUnavailable.js

@@ -0,0 +1,74 @@
+/**
+ * replayUnavailable — when a connection cannot keep the `'app-authorized'`
+ * contract, a call under it is refused BEFORE it is sent, and the error says why.
+ *
+ * Pattern: a readiness rule + one typed refusal.
+ * Role:    Under `'app-authorized'`, a call that genuinely lacked an answer and
+ *          then fails is raised as "may have run" (`callLifetime.ts`). That
+ *          rests on two things the library must ESTABLISH for every call,
+ *          never assume:
+ *
+ *   1. ITS REQUEST IS MATCHED to the call, by the call's private marker, taken
+ *      at the transport's `send` (`callMarker.ts`, `requestLedger.ts`).
+ *      - `'requests-unwatched'`: the library cannot watch this transport's
+ *        `send` at all (stdio, or a transport that refuses the wrap).
+ *      - `'request-unmatched'`: a request reached `send` without its call's
+ *        marker (an SDK that rebuilt the params and dropped `_meta`), so it
+ *        cannot be tied to any call.
+ *   2. ITS ANSWER IS SEEN: the JSON-RPC response to the request's id, read as
+ *      it arrives. This is checked once the connection is initialized: the
+ *      `initialize` answer must have passed the library's observer.
+ *      - `'answers-unobserved'`: it did not. An MCP SDK whose `connect`
+ *        REPLACES the transport's `onmessage` handler instead of keeping it
+ *        (SDK 1.10's `Protocol.connect` does) leaves the observer out.
+ *
+ * Without either, a request the server accepted and never answered would reach
+ * the caller as a plain timeout: the strict contract, silently weakened. So the
+ * call is refused instead, and nothing is sent. `'compatibility'` asks none of
+ * this and keeps its behaviour.
+ */
+/** The fixed sentence each reason reads as. Never an argument, a header or an answer. */
+const BECAUSE = {
+    'requests-unwatched': "the library cannot watch this transport's requests, so it cannot match a request to its call",
+    'answers-unobserved': "this connection's answers do not pass the library's observer: the MCP SDK replaced the " +
+        "transport's message handler when it connected",
+    'request-unmatched': "the request reached the transport without its call's marker: the MCP SDK rebuilt the " +
+        "request's params",
+};
+/**
+ * A tool call refused before it was sent, because this connection cannot keep
+ * the `'app-authorized'` replay contract (`reason`). Nothing reached the server.
+ * Names the server and the tool, never an argument.
+ */
+export class McpReplayUnavailableError extends Error {
+    reason;
+    server;
+    tool;
+    code = 'ERR_MCP_REPLAY_UNAVAILABLE';
+    /** Nothing was sent: the refusal came before the request left the client. */
+    sent = false;
+    constructor(reason, server, tool) {
+        super(`mcpClient[${server}]: the call to '${tool}' was not sent. The 'app-authorized' replay ` +
+            `policy needs each request matched to its call and each answer seen, and ` +
+            `${BECAUSE[reason]}.`);
+        this.reason = reason;
+        this.server = server;
+        this.tool = tool;
+        this.name = 'McpReplayUnavailableError';
+    }
+}
+/**
+ * Why a connection cannot take a call under `'app-authorized'` before anything
+ * is sent — `undefined` when it can. `ledger` is the connection's request
+ * ledger: absent when the library could not watch the transport's requests.
+ * A request that reaches the transport without its marker is refused there, by
+ * the ledger (`'request-unmatched'`).
+ */
+export function unavailableBeforeSending(ledger) {
+    if (ledger === undefined)
+        return 'requests-unwatched';
+    if (!ledger.answersObserved)
+        return 'answers-unobserved';
+    return undefined;
+}
+//# sourceMappingURL=replayUnavailable.js.map

package/dist/esm/mcp/replayUnavailable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayUnavailable.js","sourceRoot":"","sources":["../../../src/mcp/replayUnavailable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,yFAAyF;AACzF,MAAM,OAAO,GAAyD;IACpE,oBAAoB,EAClB,8FAA8F;IAChG,oBAAoB,EAClB,yFAAyF;QACzF,+CAA+C;IACjD,mBAAmB,EACjB,uFAAuF;QACvF,kBAAkB;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAMvC;IACA;IACA;IAPF,IAAI,GAAG,4BAAqC,CAAC;IACtD,6EAA6E;IACpE,IAAI,GAAG,KAAc,CAAC;IAE/B,YACW,MAAkC,EAClC,MAAc,EACd,IAAY;QAErB,KAAK,CACH,aAAa,MAAM,mBAAmB,IAAI,8CAA8C;YACtF,0EAA0E;YAC1E,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CACxB,CAAC;QARO,WAAM,GAAN,MAAM,CAA4B;QAClC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QAOrB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAyD;IAEzD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,oBAAoB,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,eAAe;QAAE,OAAO,oBAAoB,CAAC;IACzD,OAAO,SAAS,CAAC;AACnB,CAAC"}