@tidblink/server 0.3.0-rc.0 → 0.4.0-rc.0

package/dist/audio.d.ts

@@ -2,6 +2,7 @@ import { HttpClient } from "./http.js";
 import { OutcomeUnknownError } from "./errors.js";
 import type { BillingTag, ClarificationItem } from "./session.js";
 import type { OperationRecord, TurnFailure } from "./history.js";
+import { type ClientToolCallPayload } from "./events.js";
 import type { RequestOptions } from "./organization.js";
 export interface AudioTurnInput extends RequestOptions {
     bytes: Uint8Array;
@@ -39,6 +40,14 @@ export type AudioTurnEvent = AudioEnvelope<"turn_started", {
     messageId: string;
     text: string;
     clarificationItem?: ClarificationItem;
+}>
+/**
+ * Client Tool calls the audio Turn published. Answer them the way the
+ * Session's Client Tools are answered; this event authorizes nothing by
+ * itself.
+ */
+ | AudioEnvelope<"client_tool_calls", {
+    calls: ClientToolCallPayload[];
 }> | AudioEnvelope<"turn_error", TurnFailure> | AudioEnvelope<"turn_finished", {
     status: "succeeded" | "failed" | "interrupted";
 }>;

package/dist/audio.d.ts.map

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

package/dist/audio.js

@@ -2,6 +2,7 @@ import { HttpClient, requireKnownKeys } from "./http.js";
 import { OutcomeUnknownError, TiDBLinkApiError, TurnFailedError, TurnInterruptedError, TiDBLinkError, } from "./errors.js";
 import { decodeSse } from "./sse.js";
 import { validClarification } from "./turn.js";
+import { isClientToolCallsPayload, } from "./events.js";
 /** Audio owns its response: losing or closing it may request remote interruption. */
 export class AudioTurnStoppedError extends OutcomeUnknownError {
     constructor(sessionId, turnId, requestId, cause) {
@@ -48,7 +49,7 @@ export async function* streamAudio(http, sessionId, input) {
     let sequence = -1;
     let response;
     try {
-        ({ response, requestId } = await http.rawResponse(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/turns/audio`, {
+        ({ response, requestId } = await http.rawResponse(`/sessions/${encodeURIComponent(sessionId)}/turns/audio`, {
             method: "POST",
             body: upload.body,
             headers: {
@@ -86,6 +87,7 @@ export async function* streamAudio(http, sessionId, input) {
                     "assistant_draft",
                     "operation_step",
                     "assistant_message",
+                    "client_tool_calls",
                     "turn_error",
                     "turn_finished",
                 ].includes(event.event))
@@ -102,6 +104,9 @@ export async function* streamAudio(http, sessionId, input) {
                     (event.payload.clarificationItem !== undefined &&
                         !validClarification(event.payload.clarificationItem))))
                 throw new TiDBLinkError("Audio response returned an invalid final Message");
+            if (event.event === "client_tool_calls" &&
+                !isClientToolCallsPayload(event.payload))
+                throw new TiDBLinkError("Audio response returned invalid Client Tool calls");
             if (event.event === "turn_finished" &&
                 !["succeeded", "failed", "interrupted"].includes(event.payload.status))
                 throw new TiDBLinkError("Audio response returned an invalid terminal status");

package/dist/audio.js.map

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

package/dist/backend-connection.d.ts

@@ -0,0 +1,89 @@
+import { BackendConnectionClosedError } from "./errors.js";
+/**
+ * One Backend Connection (ADR 0109): a WebSocket from this Application Server
+ * process to the core, carrying one JSON-RPC 2.0 message per text frame.
+ * The published definition is the core's `docs/backend-connection-v1.schema.json`.
+ */
+export declare const BACKEND_CONNECTION_PATH = "/api/v1/org/backend/ws";
+export declare const BACKEND_CONNECTION_SUBPROTOCOL = "tidb-link.backend.v1";
+/** The part of the WHATWG WebSocket the SDK uses. */
+export interface BackendWebSocket {
+    readonly protocol: string;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code: number;
+        reason: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+}
+/**
+ * A WebSocket constructor that accepts upgrade headers, like Node.js's
+ * global `WebSocket` (undici). The SDK sends the Organization API Key in the
+ * `Authorization` header, never in the URL.
+ */
+export type WebSocketConstructor = new (url: string, init: any) => BackendWebSocket;
+/** Connection parameters the core announces in `hello`. */
+export interface BackendConnectionHello {
+    connectionId: string;
+    /** Most Session Attachments this connection may hold. */
+    maxSessions: number;
+    /** How long a published Client Tool call waits for its claim. */
+    claimWindowMs: number;
+    /** Interval of the core's WebSocket pings. */
+    heartbeatMs: number;
+    /** Largest frame the core accepts. */
+    maxFrameBytes: number;
+}
+export type BackendNotificationHandler = (method: string, params: Record<string, unknown>) => void;
+export interface OpenBackendTransportInput {
+    /** `ws:` or `wss:` URL of the Backend Connection route. */
+    url: string;
+    apiKey: string;
+    WebSocket?: WebSocketConstructor | undefined;
+    /** Receives every core notification after `hello`, in arrival order. */
+    onNotification: BackendNotificationHandler;
+    /** Give up when `hello` has not arrived by then. Default 15 seconds. */
+    openTimeoutMs?: number;
+}
+/** Close code the SDK uses when the core stopped answering liveness probes. */
+export declare const CLIENT_HEARTBEAT_CLOSE = 4000;
+/** Derive the Backend Connection URL from the SDK's HTTP(S) base URL. */
+export declare const backendConnectionUrl: (baseUrl: string) => string;
+/**
+ * One open Backend Connection: JSON-RPC request and response pairing,
+ * notifications, liveness and close. It never reconnects; the connection
+ * pool replaces a closed transport.
+ *
+ * Liveness: the core pings at the WebSocket layer, which the WHATWG
+ * WebSocket answers but does not expose. So when nothing has arrived for one
+ * heartbeat interval, the transport sends a `ping` request; any answer, even
+ * "method not found", proves the connection alive. With no frame for a
+ * further interval it closes the connection.
+ */
+export declare class BackendTransport {
+    #private;
+    readonly hello: BackendConnectionHello;
+    /** Resolves once with why the connection ended, local closes included. */
+    readonly closed: Promise<BackendConnectionClosedError>;
+    private constructor();
+    /** Open a connection and wait for the core's `hello`. */
+    static open(input: OpenBackendTransportInput): Promise<BackendTransport>;
+    /** Whether requests can still be sent. */
+    get open(): boolean;
+    /** Requests sent and not yet answered. */
+    get pendingRequests(): number;
+    /**
+     * Send a request and wait for its answer. A JSON-RPC error rejects with a
+     * BackendRequestError; a connection that ends first rejects with its
+     * BackendConnectionClosedError, and the request's outcome is then unknown.
+     */
+    request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+    /** Close the connection. Pending requests reject at once. */
+    close(code?: number, reason?: string): void;
+}
+//# sourceMappingURL=backend-connection.d.ts.map

package/dist/backend-connection.d.ts.map

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

package/dist/backend-connection.js

@@ -0,0 +1,300 @@
+import { BackendConnectionClosedError, BackendRequestError, TiDBLinkError, } from "./errors.js";
+/**
+ * One Backend Connection (ADR 0109): a WebSocket from this Application Server
+ * process to the core, carrying one JSON-RPC 2.0 message per text frame.
+ * The published definition is the core's `docs/backend-connection-v1.schema.json`.
+ */
+export const BACKEND_CONNECTION_PATH = "/api/v1/org/backend/ws";
+export const BACKEND_CONNECTION_SUBPROTOCOL = "tidb-link.backend.v1";
+/** Close code the SDK uses when the core stopped answering liveness probes. */
+export const CLIENT_HEARTBEAT_CLOSE = 4000;
+const DEFAULT_OPEN_TIMEOUT_MS = 15_000;
+/** Bounds the liveness interval whatever `hello.heartbeatMs` says. */
+const MIN_PROBE_INTERVAL_MS = 1_000;
+const MAX_PROBE_INTERVAL_MS = 60_000;
+const encoder = new TextEncoder();
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isPositiveInteger = (value) => Number.isSafeInteger(value) && value > 0;
+const parseHello = (params) => {
+    if (!isObject(params))
+        return undefined;
+    const { connectionId, maxSessions, claimWindowMs, heartbeatMs, maxFrameBytes } = params;
+    if (typeof connectionId !== "string" ||
+        !connectionId ||
+        !isPositiveInteger(maxSessions) ||
+        !isPositiveInteger(claimWindowMs) ||
+        !isPositiveInteger(heartbeatMs) ||
+        !isPositiveInteger(maxFrameBytes))
+        return undefined;
+    return { connectionId, maxSessions, claimWindowMs, heartbeatMs, maxFrameBytes };
+};
+/** Derive the Backend Connection URL from the SDK's HTTP(S) base URL. */
+export const backendConnectionUrl = (baseUrl) => {
+    const url = new URL(baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    return `${url.toString().replace(/\/$/, "")}${BACKEND_CONNECTION_PATH}`;
+};
+/**
+ * One open Backend Connection: JSON-RPC request and response pairing,
+ * notifications, liveness and close. It never reconnects; the connection
+ * pool replaces a closed transport.
+ *
+ * Liveness: the core pings at the WebSocket layer, which the WHATWG
+ * WebSocket answers but does not expose. So when nothing has arrived for one
+ * heartbeat interval, the transport sends a `ping` request; any answer, even
+ * "method not found", proves the connection alive. With no frame for a
+ * further interval it closes the connection.
+ */
+export class BackendTransport {
+    hello;
+    /** Resolves once with why the connection ended, local closes included. */
+    closed;
+    #socket;
+    #pending = new Map();
+    #onNotification;
+    #nextId = 1;
+    #lastFrameAt = performance.now();
+    #probing = false;
+    #timer;
+    #error;
+    #settleClosed;
+    constructor(socket, hello, onNotification) {
+        this.#socket = socket;
+        this.hello = hello;
+        this.#onNotification = onNotification;
+        this.closed = new Promise((resolve) => {
+            this.#settleClosed = resolve;
+        });
+        const interval = Math.min(MAX_PROBE_INTERVAL_MS, Math.max(MIN_PROBE_INTERVAL_MS, hello.heartbeatMs));
+        this.#timer = setInterval(() => this.#checkLiveness(interval), interval);
+        this.#timer.unref?.();
+    }
+    /** Open a connection and wait for the core's `hello`. */
+    static open(input) {
+        const WebSocketClass = input.WebSocket ??
+            globalThis.WebSocket;
+        if (typeof WebSocketClass !== "function")
+            throw new TypeError("Backend Connections need a WebSocket constructor; pass the WebSocket option");
+        const timeoutMs = input.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            let transport;
+            let settled = false;
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(error);
+            };
+            let socket;
+            try {
+                socket = new WebSocketClass(input.url, {
+                    protocols: [BACKEND_CONNECTION_SUBPROTOCOL],
+                    headers: { authorization: `Bearer ${input.apiKey}` },
+                });
+            }
+            catch (cause) {
+                reject(new BackendConnectionClosedError({
+                    code: 1006,
+                    message: "Could not open a Backend Connection",
+                    cause,
+                }));
+                return;
+            }
+            const timer = setTimeout(() => {
+                fail(new BackendConnectionClosedError({
+                    code: 1006,
+                    message: `Backend Connection sent no hello within ${timeoutMs} ms`,
+                }));
+                closeQuietly(socket, 1000);
+            }, timeoutMs);
+            socket.addEventListener("message", ({ data }) => {
+                if (transport)
+                    return transport.#receive(data);
+                const message = typeof data === "string" ? safeParse(data) : undefined;
+                const hello = message?.method === "hello" && !("id" in message)
+                    ? parseHello(message.params)
+                    : undefined;
+                if (!hello) {
+                    fail(new BackendConnectionClosedError({
+                        code: 1002,
+                        message: "Backend Connection did not start with a valid hello",
+                    }));
+                    closeQuietly(socket, 1002);
+                    return;
+                }
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                transport = new BackendTransport(socket, hello, input.onNotification);
+                resolve(transport);
+            });
+            socket.addEventListener("close", ({ code, reason }) => {
+                const error = new BackendConnectionClosedError({ code, reason });
+                if (transport)
+                    transport.#end(error);
+                else
+                    fail(error);
+            });
+            // Once open, an error is followed by close, which carries the code. A
+            // refused upgrade may report only the error (Node.js 22).
+            socket.addEventListener("error", (event) => {
+                if (transport)
+                    return;
+                fail(new BackendConnectionClosedError({
+                    code: 1006,
+                    message: "Could not open a Backend Connection",
+                    cause: event.error ?? event,
+                }));
+                closeQuietly(socket, 1000);
+            });
+        });
+    }
+    /** Whether requests can still be sent. */
+    get open() {
+        return this.#error === undefined;
+    }
+    /** Requests sent and not yet answered. */
+    get pendingRequests() {
+        return this.#pending.size;
+    }
+    /**
+     * Send a request and wait for its answer. A JSON-RPC error rejects with a
+     * BackendRequestError; a connection that ends first rejects with its
+     * BackendConnectionClosedError, and the request's outcome is then unknown.
+     */
+    request(method, params) {
+        if (this.#error)
+            return Promise.reject(this.#error);
+        const id = this.#nextId++;
+        const text = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+        if (encoder.encode(text).byteLength > this.hello.maxFrameBytes)
+            return Promise.reject(new TiDBLinkError(`${method} exceeds the Backend Connection frame limit of ${this.hello.maxFrameBytes} bytes`));
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            try {
+                this.#socket.send(text);
+            }
+            catch (cause) {
+                this.#pending.delete(id);
+                reject(new BackendConnectionClosedError({
+                    code: 1006,
+                    message: "Could not send on the Backend Connection",
+                    cause,
+                }));
+            }
+        });
+    }
+    /** Close the connection. Pending requests reject at once. */
+    close(code = 1000, reason = "") {
+        if (this.#error)
+            return;
+        this.#end(new BackendConnectionClosedError({
+            code,
+            reason,
+            message: reason || "Backend Connection closed by this process",
+        }));
+        closeQuietly(this.#socket, code, reason);
+    }
+    #receive(data) {
+        if (this.#error)
+            return;
+        this.#lastFrameAt = performance.now();
+        this.#probing = false;
+        const message = typeof data === "string" ? safeParse(data) : undefined;
+        if (!message || message.jsonrpc !== "2.0") {
+            this.close(1002, "invalid frame");
+            return;
+        }
+        if (typeof message.method === "string") {
+            if ("id" in message) {
+                // The core sends no requests in this protocol revision.
+                this.#send({
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    error: { code: -32601, message: "Method not found" },
+                });
+                return;
+            }
+            this.#onNotification(message.method, isObject(message.params) ? message.params : {});
+            return;
+        }
+        if (typeof message.id !== "number")
+            return;
+        const pending = this.#pending.get(message.id);
+        if (!pending)
+            return;
+        this.#pending.delete(message.id);
+        if (isObject(message.error)) {
+            const { code, message: text, data } = message.error;
+            const reason = isObject(data) && typeof data.reason === "string" ? data.reason : undefined;
+            pending.reject(new BackendRequestError({
+                code: typeof code === "number" ? code : -32603,
+                message: typeof text === "string" && text ? text : "Backend Connection request failed",
+                ...(reason === undefined ? {} : { reason }),
+                ...(isObject(data) && "details" in data ? { details: data.details } : {}),
+            }));
+        }
+        else
+            pending.resolve(message.result);
+    }
+    #checkLiveness(interval) {
+        if (this.#error)
+            return;
+        if (performance.now() - this.#lastFrameAt < interval)
+            return;
+        if (this.#probing) {
+            this.#end(new BackendConnectionClosedError({
+                code: CLIENT_HEARTBEAT_CLOSE,
+                message: `Backend Connection was silent for ${2 * interval} ms`,
+            }));
+            closeQuietly(this.#socket, CLIENT_HEARTBEAT_CLOSE, "heartbeat timeout");
+            return;
+        }
+        this.#probing = true;
+        // Any answer, including "method not found" from a core without `ping`, counts.
+        this.request("ping", {}).catch(() => undefined);
+    }
+    #send(message) {
+        try {
+            this.#socket.send(JSON.stringify(message));
+        }
+        catch {
+            // The close event follows.
+        }
+    }
+    #end(error) {
+        if (this.#error)
+            return;
+        this.#error = error;
+        clearInterval(this.#timer);
+        this.#onNotification = () => undefined;
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+        this.#settleClosed(error);
+    }
+}
+function safeParse(text) {
+    try {
+        const value = JSON.parse(text);
+        return isObject(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function closeQuietly(socket, code, reason = "") {
+    try {
+        // A client may only send 1000 or an application code in 3000-4999.
+        socket.close(code === 1000 || (code >= 3000 && code <= 4999) ? code : 1000, reason);
+    }
+    catch {
+        // Already closing.
+    }
+}
+//# sourceMappingURL=backend-connection.js.map

package/dist/backend-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-connection.js","sourceRoot":"","sources":["../src/backend-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAChE,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AA0DrE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,uBAAuB,GAAG,MAAM,CAAC;AACvC,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,KAAK,CAAC;AACpC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAErC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACvE,MAAM,iBAAiB,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC5D,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAK,KAAgB,GAAG,CAAC,CAAC;AAEvD,MAAM,UAAU,GAAG,CAAC,MAAe,EAAsC,EAAE;IACzE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,GAC5E,MAAM,CAAC;IACT,IACE,OAAO,YAAY,KAAK,QAAQ;QAChC,CAAC,YAAY;QACb,CAAC,iBAAiB,CAAC,WAAW,CAAC;QAC/B,CAAC,iBAAiB,CAAC,aAAa,CAAC;QACjC,CAAC,iBAAiB,CAAC,WAAW,CAAC;QAC/B,CAAC,iBAAiB,CAAC,aAAa,CAAC;QAEjC,OAAO,SAAS,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAClF,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAe,EAAU,EAAE;IAC9D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1D,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,uBAAuB,EAAE,CAAC;AAC1E,CAAC,CAAC;AAOF;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAgB;IAClB,KAAK,CAAyB;IACvC,0EAA0E;IACjE,MAAM,CAAwC;IAE9C,OAAO,CAAmB;IAC1B,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IACtD,eAAe,CAA6B;IAC5C,OAAO,GAAG,CAAC,CAAC;IACZ,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACjC,QAAQ,GAAG,KAAK,CAAC;IACjB,MAAM,CAA6C;IACnD,MAAM,CAA2C;IACjD,aAAa,CAAiD;IAE9D,YACE,MAAwB,EACxB,KAA6B,EAC7B,cAA0C;QAE1C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACpC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC/B,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,qBAAqB,EACrB,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,KAAK,CAAC,WAAW,CAAC,CACnD,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;QACxE,IAAI,CAAC,MAAiC,CAAC,KAAK,EAAE,EAAE,CAAC;IACpD,CAAC;IAED,yDAAyD;IACzD,MAAM,CAAC,IAAI,CAAC,KAAgC;QAC1C,MAAM,cAAc,GAClB,KAAK,CAAC,SAAS;YACd,UAA8D,CAAC,SAAS,CAAC;QAC5E,IAAI,OAAO,cAAc,KAAK,UAAU;YACtC,MAAM,IAAI,SAAS,CACjB,6EAA6E,CAC9E,CAAC;QACJ,MAAM,SAAS,GAAG,KAAK,CAAC,aAAa,IAAI,uBAAuB,CAAC;QACjE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,SAAuC,CAAC;YAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,IAAI,GAAG,CAAC,KAAmC,EAAE,EAAE;gBACnD,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,CAAC;YACF,IAAI,MAAwB,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE;oBACrC,SAAS,EAAE,CAAC,8BAA8B,CAAC;oBAC3C,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE,EAAE;iBACrD,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CACJ,IAAI,4BAA4B,CAAC;oBAC/B,IAAI,EAAE,IAAI;oBACV,OAAO,EAAE,qCAAqC;oBAC9C,KAAK;iBACN,CAAC,CACH,CAAC;gBACF,OAAO;YACT,CAAC;YACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CACF,IAAI,4BAA4B,CAAC;oBAC/B,IAAI,EAAE,IAAI;oBACV,OAAO,EAAE,2CAA2C,SAAS,KAAK;iBACnE,CAAC,CACH,CAAC;gBACF,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC7B,CAAC,EAAE,SAAS,CAAC,CAAC;YACd,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;gBAC9C,IAAI,SAAS;oBAAE,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC/C,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACvE,MAAM,KAAK,GACT,OAAO,EAAE,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,CAAC;oBAC/C,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;oBAC5B,CAAC,CAAC,SAAS,CAAC;gBAChB,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,IAAI,CACF,IAAI,4BAA4B,CAAC;wBAC/B,IAAI,EAAE,IAAI;wBACV,OAAO,EAAE,qDAAqD;qBAC/D,CAAC,CACH,CAAC;oBACF,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;oBAC3B,OAAO;gBACT,CAAC;gBACD,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,SAAS,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;gBACtE,OAAO,CAAC,SAAS,CAAC,CAAC;YACrB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;gBACpD,MAAM,KAAK,GAAG,IAAI,4BAA4B,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBACjE,IAAI,SAAS;oBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;oBAChC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YACH,sEAAsE;YACtE,0DAA0D;YAC1D,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBACzC,IAAI,SAAS;oBAAE,OAAO;gBACtB,IAAI,CACF,IAAI,4BAA4B,CAAC;oBAC/B,IAAI,EAAE,IAAI;oBACV,OAAO,EAAE,qCAAqC;oBAC9C,KAAK,EAAG,KAA6B,CAAC,KAAK,IAAI,KAAK;iBACrD,CAAC,CACH,CAAC;gBACF,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;IACnC,CAAC;IAED,0CAA0C;IAC1C,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAc,MAAc,EAAE,MAA+B;QAClE,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACpE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa;YAC5D,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,aAAa,CACf,GAAG,MAAM,kDAAkD,IAAI,CAAC,KAAK,CAAC,aAAa,QAAQ,CAC5F,CACF,CAAC;QACJ,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE;gBACpB,OAAO,EAAE,OAAmC;gBAC5C,MAAM;aACP,CAAC,CAAC;YACH,IAAI,CAAC;gBACH,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACzB,MAAM,CACJ,IAAI,4BAA4B,CAAC;oBAC/B,IAAI,EAAE,IAAI;oBACV,OAAO,EAAE,0CAA0C;oBACnD,KAAK;iBACN,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,GAAG,EAAE;QAC5B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,IAAI,CACP,IAAI,4BAA4B,CAAC;YAC/B,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,MAAM,IAAI,2CAA2C;SAC/D,CAAC,CACH,CAAC;QACF,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,QAAQ,CAAC,IAAa;QACpB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACvC,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC;gBACpB,wDAAwD;gBACxD,IAAI,CAAC,KAAK,CAAC;oBACT,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE;iBACrD,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,IAAI,CAAC,eAAe,CAClB,OAAO,CAAC,MAAM,EACd,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAC/C,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ;YAAE,OAAO;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;YACpD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3F,OAAO,CAAC,MAAM,CACZ,IAAI,mBAAmB,CAAC;gBACtB,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK;gBAC9C,OAAO,EAAE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mCAAmC;gBACtF,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;gBAC3C,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1E,CAAC,CACH,CAAC;QACJ,CAAC;;YAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,cAAc,CAAC,QAAgB;QAC7B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,GAAG,QAAQ;YAAE,OAAO;QAC7D,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CACP,IAAI,4BAA4B,CAAC;gBAC/B,IAAI,EAAE,sBAAsB;gBAC5B,OAAO,EAAE,qCAAqC,CAAC,GAAG,QAAQ,KAAK;aAChE,CAAC,CACH,CAAC;YACF,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,CAAC,CAAC;YACxE,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,+EAA+E;QAC/E,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,OAAgB;QACpB,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAmC;QACtC,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC;QACvC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpE,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;CACF;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAwB,EAAE,IAAY,EAAE,MAAM,GAAG,EAAE;IACvE,IAAI,CAAC;QACH,mEAAmE;QACnE,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,mBAAmB;IACrB,CAAC;AACH,CAAC"}

package/dist/backend-pool.d.ts

@@ -0,0 +1,93 @@
+import { type WebSocketConstructor } from "./backend-connection.js";
+/** The answer of a `session.attach` that took effect. */
+export interface AttachResult {
+    /** The Session's attachment generation. */
+    generation: number;
+    /** Position of the Session's latest event when the attachment took effect. */
+    cursor: string;
+}
+/** Why the pool stopped serving an attachment. It does not retry it. */
+export type AttachmentEnd = 
+/** An executing attachment on another connection took the Session. */
+{
+    reason: "superseded";
+}
+/** The Session was deleted. */
+ | {
+    reason: "session_deleted";
+}
+/** `OrganizationClient.close()` closed every Backend Connection. */
+ | {
+    reason: "closed";
+}
+/** Re-attaching failed for good, for example after a revoked Key. */
+ | {
+    reason: "error";
+    error: unknown;
+};
+/** Requests over one Backend Connection. */
+export interface BackendLink {
+    readonly open: boolean;
+    request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+}
+/**
+ * The pool's view of one Session Attachment. The pool calls it; a Session
+ * connection implements it.
+ */
+export interface PoolAttachment {
+    readonly sessionId: string;
+    /** Parameters of the next `session.attach`, recomputed for every (re)attach. */
+    attachParams(): Record<string, unknown>;
+    /** A (re)attach took effect on `link`, which now delivers the Session. */
+    attached(result: AttachResult, link: BackendLink): void;
+    /** A notification for this Session from the connection that holds it. */
+    notify(method: string, params: Record<string, unknown>, link: BackendLink): void;
+    /** The pool gave the attachment up; called at most once, never after `detach()`. */
+    ended(end: AttachmentEnd): void;
+}
+export interface BackendConnectionPoolOptions {
+    baseUrl: string;
+    apiKey: string;
+    WebSocket?: WebSocketConstructor | undefined;
+    /** Close a connection that has held nothing for this long. Default 5 seconds. */
+    idleCloseMs?: number;
+    /** See `OpenBackendTransportInput.openTimeoutMs`. */
+    openTimeoutMs?: number;
+}
+/**
+ * The Backend Connections of one OrganizationClient. Connections open on
+ * demand and hold up to the `maxSessions` the core announces; further
+ * attachments open another connection, which the load balancer may place on
+ * another replica. A lost connection's attachments re-attach elsewhere with
+ * their latest parameters; `connection.drain` moves them before the core
+ * closes the connection. Connections that hold nothing close after a short
+ * idle period.
+ */
+export declare class BackendConnectionPool {
+    #private;
+    constructor(options: BackendConnectionPoolOptions);
+    /** Open Backend Connections, for diagnostics and tests. */
+    get connections(): number;
+    /**
+     * Attach a Session and keep it attached until `detach()` or until the pool
+     * gives it up through `ended()`. Rejects when the first attach fails; one
+     * attachment per Session is allowed at a time.
+     */
+    attach(attachment: PoolAttachment): Promise<AttachResult>;
+    /** Release an attachment. Best effort: a lost connection releases it anyway. */
+    detach(attachment: PoolAttachment): Promise<void>;
+    /**
+     * Send a request that any connection of the Organization may carry, such as
+     * `tool.result`, retrying on another connection after transient failures
+     * until `retryUntil` (epoch milliseconds). Only idempotent requests belong here.
+     */
+    request<T = unknown>(method: string, params: Record<string, unknown>, options?: {
+        retryUntil?: number;
+    }): Promise<T>;
+    /**
+     * End every attachment with reason `closed`, release them and close the
+     * connections. Later attaches are refused.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=backend-pool.d.ts.map

package/dist/backend-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-pool.d.ts","sourceRoot":"","sources":["../src/backend-pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AAQjC,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,MAAM,aAAa;AACvB,sEAAsE;AACpE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE;AAC1B,+BAA+B;GAC7B;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE;AAC/B,oEAAoE;GAClE;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE;AACtB,qEAAqE;GACnE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAExC,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnF;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACxD,yEAAyE;IACzE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACjF,oFAAoF;IACpF,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC7C,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA4CD;;;;;;;;GAQG;AACH,qBAAa,qBAAqB;;gBAiBpB,OAAO,EAAE,4BAA4B;IAQjD,2DAA2D;IAC3D,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACG,MAAM,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAgB/D,gFAAgF;IAC1E,MAAM,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvD;;;;OAIG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GACpC,OAAO,CAAC,CAAC,CAAC;IAwBb;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyQ7B"}