@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/session-connection.js

@@ -0,0 +1,334 @@
+import { validateClientTools, } from "./client-tools.js";
+import { ClientToolExecutor } from "./client-tool-executor.js";
+import { TiDBLinkApiError, TiDBLinkError } from "./errors.js";
+import { asKnownSessionEvent, sessionEventFrom, } from "./events.js";
+import { HttpClient, requestOptions, requireKnownKeys } from "./http.js";
+import { requireOpenRealtimeConnectionReceipt, requireRealtimeConnectGrantReceipt, } from "./realtime.js";
+import { sendOverConnection, } from "./session-send.js";
+const DECIMAL = /^(0|[1-9][0-9]*)$/;
+/** Whether `cursor` is at or before `last`; opaque cursors never compare. */
+const notAfter = (cursor, last) => last !== undefined &&
+    DECIMAL.test(cursor) &&
+    DECIMAL.test(last) &&
+    BigInt(cursor) <= BigInt(last);
+/**
+ * A Session attached over this process's Backend Connections. It receives
+ * the Session's events, in order and without gaps, across reconnects and
+ * replica moves, until `close()` or until `closed` reports why it ended.
+ */
+export class SessionConnection {
+    sessionId;
+    userId;
+    /** Resolves once, with why the connection ended. */
+    closed;
+    #pool;
+    #http;
+    #options;
+    #declarations;
+    #attachment;
+    #cursor;
+    #generation;
+    #link;
+    #ended;
+    #settle;
+    #queue = Promise.resolve();
+    #executor;
+    /** Waiting for the next attach, or for the end. */
+    #linkWaiters = [];
+    /** Event buffers of `send()` calls in flight. */
+    #watchers = new Set();
+    /** @internal Use `session.connect()`. */
+    constructor(pool, http, userId, sessionId, options, declarations) {
+        this.#pool = pool;
+        this.#http = http;
+        this.userId = userId;
+        this.sessionId = sessionId;
+        this.#options = options;
+        this.#declarations = declarations;
+        this.#cursor = options.cursor;
+        this.closed = new Promise((resolve) => {
+            this.#settle = resolve;
+        });
+        // An executing connection runs the Session's calls, declared here or not.
+        this.#executor = options.observe
+            ? undefined
+            : new ClientToolExecutor({
+                pool,
+                sessionId,
+                handlers: options.tools ?? {},
+                report: (error) => this.#report(error),
+            });
+        this.#attachment = {
+            sessionId,
+            attachParams: () => this.#attachParams(),
+            attached: (result, link) => this.#attached(result, link),
+            notify: (method, params, link) => this.#notify(method, params, link),
+            ended: (end) => this.#end(end),
+        };
+    }
+    /**
+     * Cursor of the last event whose callbacks completed, or the Session's
+     * position when the connection attached if none has arrived since.
+     */
+    get cursor() {
+        return this.#cursor;
+    }
+    /** The Session's attachment generation from the latest attach. */
+    get generation() {
+        return this.#generation;
+    }
+    /**
+     * Release the Session. Events stop, and calls published later go to no one
+     * until another connection attaches. Calls already running finish and
+     * their results are still submitted.
+     */
+    async close() {
+        if (this.#ended)
+            return;
+        this.#end({ reason: "closed" });
+        await this.#pool.detach(this.#attachment);
+    }
+    /**
+     * Send a user message over the connection and wait for the Turn it starts,
+     * or the active Turn it steers. `onProgress` receives the assistant's draft
+     * from the pushed events; the result is read once the Turn finished, with
+     * the same shape and errors as `session.turn()`. A message whose answer was
+     * lost to a reconnect is sent again with the same `clientEventId`, which
+     * the core deduplicates.
+     */
+    send(text, options) {
+        return sendOverConnection({
+            sessionId: this.sessionId,
+            http: this.#http,
+            closed: this.closed,
+            link: (signal, after) => this.#nextLink(signal, after),
+            report: (error) => this.#report(error),
+            watch: () => this.#watch(),
+        }, text, options);
+    }
+    /**
+     * Prepare the Session's Realtime connection and return what a device needs
+     * to join it directly: the WebSocket URL and a short-lived connect token.
+     * When a Realtime connection is already live, a new token for it is
+     * returned instead and `audio` is not applied.
+     */
+    async realtimeGrant(input = {}, options) {
+        requireKnownKeys(input, ["audio", "metadata"], "Realtime grant input");
+        const request = requestOptions(options);
+        const path = `/sessions/${encodeURIComponent(this.sessionId)}/realtime`;
+        try {
+            const result = await this.#http.postResponse(path, input, {
+                ...request,
+                outcomeUnknown: true,
+            });
+            const opened = requireOpenRealtimeConnectionReceipt(result.data, result.requestId);
+            return {
+                websocketUrl: opened.websocketUrl,
+                connectToken: opened.connectToken,
+                connectTokenExpiresAt: opened.connectTokenExpiresAt,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof TiDBLinkApiError) || error.code !== "realtime_connection_live")
+                throw error;
+        }
+        const result = await this.#http.postResponse(`${path}/connect-tokens`, undefined, {
+            ...request,
+            outcomeUnknown: true,
+        });
+        return requireRealtimeConnectGrantReceipt(result.data, result.requestId);
+    }
+    /** @internal */
+    async attach() {
+        await this.#pool.attach(this.#attachment);
+    }
+    #report(error) {
+        if (this.#options.onError) {
+            try {
+                this.#options.onError(error);
+                return;
+            }
+            catch (thrown) {
+                error = thrown;
+            }
+        }
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+    #attachParams() {
+        return {
+            userId: this.userId,
+            sessionId: this.sessionId,
+            ...(this.#options.observe ? { kind: "observing" } : {}),
+            ...(this.#declarations ? { tools: this.#declarations } : {}),
+            ...(this.#cursor === undefined ? {} : { cursor: this.#cursor }),
+        };
+    }
+    #attached(result, link) {
+        this.#link = link;
+        this.#generation = result.generation;
+        // Without a resume point, delivery starts after the attach position.
+        this.#cursor ??= result.cursor;
+        this.#wakeLinkWaiters();
+    }
+    #wakeLinkWaiters() {
+        const waiters = this.#linkWaiters;
+        this.#linkWaiters = [];
+        for (const waiter of waiters)
+            waiter.resolve();
+    }
+    /** The open link holding the attachment, other than `after`; waits for a re-attach. */
+    async #nextLink(signal, after) {
+        for (;;) {
+            signal.throwIfAborted();
+            if (this.#ended)
+                throw new TiDBLinkError(`The Session connection ended (${this.#ended.reason}); connect again to send`);
+            const link = this.#link;
+            if (link && link.open && link !== after)
+                return link;
+            await new Promise((resolve, reject) => {
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener("abort", onAbort, { once: true });
+                this.#linkWaiters.push({
+                    resolve: () => {
+                        signal.removeEventListener("abort", onAbort);
+                        resolve();
+                    },
+                });
+                // A link that closed without a re-attach yet: look again shortly.
+                if (link && !link.open)
+                    setTimeout(() => this.#wakeLinkWaiters(), 100);
+            });
+        }
+    }
+    #watch() {
+        const watcher = { events: [], wake: () => undefined };
+        this.#watchers.add(watcher);
+        return {
+            next: async (signal) => {
+                for (;;) {
+                    const event = watcher.events.shift();
+                    if (event)
+                        return event;
+                    if (this.#ended)
+                        return undefined;
+                    signal.throwIfAborted();
+                    await new Promise((resolve, reject) => {
+                        const onAbort = () => reject(signal.reason);
+                        signal.addEventListener("abort", onAbort, { once: true });
+                        watcher.wake = () => {
+                            signal.removeEventListener("abort", onAbort);
+                            watcher.wake = () => undefined;
+                            resolve();
+                        };
+                    });
+                }
+            },
+            stop: () => {
+                this.#watchers.delete(watcher);
+            },
+        };
+    }
+    #notify(method, params, link) {
+        if (this.#ended)
+            return;
+        if (method === "tool.call") {
+            this.#executor?.receive(params, link);
+            return;
+        }
+        if (method !== "session.event")
+            return;
+        let event;
+        try {
+            event = sessionEventFrom(params.event, params.cursor, {
+                sessionId: this.sessionId,
+            });
+        }
+        catch (error) {
+            this.#queue = this.#queue.then(() => this.#report(error));
+            return;
+        }
+        // One event at a time, so that callbacks and saved cursors follow the Session's order.
+        this.#queue = this.#queue.then(() => this.#deliver(event));
+    }
+    async #deliver(event) {
+        // A re-attach replays from the last completed event; skip what already ran.
+        if (this.#ended || notAfter(event.cursor, this.#cursor))
+            return;
+        const options = this.#options;
+        await this.#run(() => options.onEvent?.(event));
+        const known = asKnownSessionEvent(event);
+        if (known?.type === "agent.session.realtime.input_transcript.completed")
+            await this.#run(() => options.onTranscript?.(known.data));
+        if (known?.type === "agent.session.realtime.response.completed")
+            await this.#run(() => options.onResponse?.(known.data));
+        this.#cursor = event.cursor;
+        for (const watcher of this.#watchers) {
+            watcher.events.push(event);
+            watcher.wake();
+        }
+        await this.#run(() => options.onCursor?.(event.cursor));
+    }
+    async #run(callback) {
+        try {
+            await callback();
+        }
+        catch (error) {
+            this.#report(error);
+        }
+    }
+    #end(end) {
+        if (this.#ended)
+            return;
+        this.#ended = end;
+        this.#link = undefined;
+        this.#settle(end);
+        this.#wakeLinkWaiters();
+        for (const watcher of this.#watchers)
+            watcher.wake();
+    }
+}
+/** Check `connect()` options and turn tool handlers into declarations. */
+export function connectDeclarations(options) {
+    requireKnownKeys(options, ["tools", "observe", "cursor", "onCursor", "onEvent", "onTranscript", "onResponse", "onError"], "Session connection options");
+    for (const key of ["onCursor", "onEvent", "onTranscript", "onResponse", "onError"])
+        if (options[key] !== undefined && typeof options[key] !== "function")
+            throw new TypeError(`${key} must be a function`);
+    if (options.observe !== undefined && typeof options.observe !== "boolean")
+        throw new TypeError("observe must be a boolean");
+    if (options.cursor !== undefined &&
+        (typeof options.cursor !== "string" || !/^(0|[1-9][0-9]{0,14})$/.test(options.cursor)))
+        throw new TypeError("cursor must be an event cursor received from this Session");
+    if (options.tools === undefined)
+        return undefined;
+    if (options.observe)
+        throw new TypeError("An observing connection cannot declare Client Tools");
+    if (typeof options.tools !== "object" || options.tools === null || Array.isArray(options.tools))
+        throw new TypeError("tools must map each Client Tool name to its handler");
+    const declarations = Object.entries(options.tools).map(([name, handler]) => {
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name))
+            throw new TypeError(`Client Tool name ${JSON.stringify(name)} must be 1-64 letters, digits, _ or -`);
+        requireKnownKeys(handler, ["description", "parameters", "run"], `Client Tool ${name}`);
+        if (typeof handler.run !== "function")
+            throw new TypeError(`Client Tool ${name} requires a run function`);
+        return {
+            type: "function",
+            name,
+            description: handler.description,
+            parameters: handler.parameters,
+        };
+    });
+    validateClientTools(declarations);
+    return declarations;
+}
+/** Open a Session connection; resolves once the first attach took effect. */
+export async function connectSession(http, pool, userId, sessionId, options = {}) {
+    if (!pool || !userId)
+        throw new TiDBLinkError("connect() needs a Session selected through OrganizationClient.user(userId)");
+    const declarations = connectDeclarations(options);
+    const connection = new SessionConnection(pool, http, userId, sessionId, options, declarations);
+    await connection.attach();
+    return connection;
+}
+//# sourceMappingURL=session-connection.js.map

package/dist/session-connection.js.map

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

package/dist/session-send.d.ts

@@ -0,0 +1,49 @@
+import type { BackendLink } from "./backend-pool.js";
+import type { SessionEvent } from "./events.js";
+import { HttpClient } from "./http.js";
+import type { BillingTag } from "./session.js";
+import { type TurnResult } from "./turn.js";
+export interface SendOptions {
+    /**
+     * Stable identity of this message in the Session's command namespace,
+     * shared with REST. Persist it before sending to recover the result after a
+     * crash with `session.waitForResult(clientEventId)`. Default: a random UUID.
+     */
+    clientEventId?: string;
+    userFileIds?: string[];
+    clarificationSourceTurnId?: string;
+    billingTag?: BillingTag | null;
+    /**
+     * The assistant's draft so far, each time it grows. Each call carries the
+     * complete draft: replace what you showed, do not append.
+     */
+    onProgress?: (draft: string) => void;
+    /** Local deadline for the whole call; default 60 seconds. Never cancels the Turn. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** What `send()` needs from its Session connection. */
+export interface SendChannel {
+    readonly sessionId: string;
+    readonly http: HttpClient;
+    /** The link that holds the attachment now, or the next one; rejects once the connection ended. */
+    link(signal: AbortSignal, after?: BackendLink): Promise<BackendLink>;
+    /** Resolves when the connection ends. */
+    readonly closed: Promise<unknown>;
+    /** Report an error that does not end the call. */
+    report(error: unknown): void;
+    /** Start buffering this connection's events, in delivery order. */
+    watch(): EventWatch;
+}
+export interface EventWatch {
+    /** The next event, or `undefined` once the connection ended. */
+    next(signal: AbortSignal): Promise<SessionEvent | undefined>;
+    stop(): void;
+}
+/**
+ * Submit a user message over the connection and wait for the Turn it starts
+ * or steers: progress from the pushed events, and the result read once the
+ * Turn's terminal event arrives.
+ */
+export declare function sendOverConnection(channel: SendChannel, text: string | [string, ...string[]], options?: SendOptions): Promise<TurnResult>;
+//# sourceMappingURL=session-send.d.ts.map

package/dist/session-send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-send.d.ts","sourceRoot":"","sources":["../src/session-send.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,UAAU,EAA+C,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,kGAAkG;IAClG,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACrE,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,KAAK,IAAI,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAC7D,IAAI,IAAI,IAAI,CAAC;CACd;AAkBD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EACpC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAiKrB"}

package/dist/session-send.js

@@ -0,0 +1,179 @@
+import { BackendConnectionClosedError, BackendRequestError, InputNotAppliedError, OutcomeUnknownError, TiDBLinkError, TurnWaitTimeoutError, } from "./errors.js";
+import { requireInteraction } from "./history.js";
+import { HttpClient, requireCreationKey, requireKnownKeys, sleep } from "./http.js";
+import { validateMessageData, validateWaitOptions, waitForResult, } from "./turn.js";
+/** How long a finished Turn's result waits for the Session's release, and at least for its read. */
+const RELEASE_WAIT_MS = 5_000;
+const aborted = (signal) => new Promise((_, reject) => {
+    if (signal.aborted)
+        reject(signal.reason);
+    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+});
+/** Refusals after which the same message may go out on the next link. */
+const MOVE_ON = new Set(["connection_draining", "session_not_attached"]);
+const isAmbiguous = (error) => error instanceof BackendConnectionClosedError ||
+    (error instanceof BackendRequestError && error.code === -32603);
+/**
+ * Submit a user message over the connection and wait for the Turn it starts
+ * or steers: progress from the pushed events, and the result read once the
+ * Turn's terminal event arrives.
+ */
+export async function sendOverConnection(channel, text, options = {}) {
+    requireKnownKeys(options, [
+        "clientEventId",
+        "userFileIds",
+        "clarificationSourceTurnId",
+        "billingTag",
+        "onProgress",
+        "timeoutMs",
+        "signal",
+    ], "Send options");
+    const { clientEventId = crypto.randomUUID(), onProgress, timeoutMs, signal } = options;
+    requireCreationKey(clientEventId);
+    if (onProgress !== undefined && typeof onProgress !== "function")
+        throw new TypeError("onProgress must be a function");
+    const data = {
+        text,
+        ...(options.userFileIds === undefined ? {} : { userFileIds: options.userFileIds }),
+        ...(options.clarificationSourceTurnId === undefined
+            ? {}
+            : { clarificationSourceTurnId: options.clarificationSourceTurnId }),
+        ...(options.billingTag === undefined ? {} : { billingTag: options.billingTag }),
+    };
+    validateMessageData(data);
+    const { timeoutMs: limit } = validateWaitOptions(timeoutMs === undefined ? {} : { timeoutMs });
+    signal?.throwIfAborted();
+    const startedAt = Date.now();
+    const deadline = AbortSignal.timeout(limit);
+    const stop = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    const { sessionId } = channel;
+    // Events of the Turn may arrive before the receipt.
+    const watch = channel.watch();
+    let receipt;
+    let ambiguous = false;
+    let turnFinished = false;
+    try {
+        receipt = await submit();
+        if (receipt.rejection || receipt.mode === "rejected")
+            throw new InputNotAppliedError(sessionId, clientEventId, receipt.turnId);
+        if (receipt.result.status === "running")
+            await untilFinished(receipt.turnId);
+    }
+    catch (error) {
+        if (error instanceof InputNotAppliedError || error instanceof BackendRequestError)
+            throw error;
+        // Nothing reached the core: the error is definite.
+        if (receipt === undefined && !ambiguous)
+            throw error;
+        const ErrorClass = deadline.aborted && !signal?.aborted ? TurnWaitTimeoutError : OutcomeUnknownError;
+        throw new ErrorClass(receipt === undefined
+            ? "The message's outcome is unknown; recover it with session.waitForResult(clientEventId)"
+            : "Local wait stopped before the Turn finished; query or wait for the original input", {
+            sessionId,
+            inputId: clientEventId,
+            ...(receipt ? { turnId: receipt.turnId } : {}),
+            cause: error,
+        });
+    }
+    finally {
+        watch.stop();
+    }
+    // The terminal event arrived (or the connection ended): read the settled result.
+    const remaining = Math.max(0, limit - (Date.now() - startedAt));
+    return waitForResult(channel.http, sessionId, clientEventId, {
+        // A finished Turn's result is read even when the local deadline just passed.
+        timeoutMs: turnFinished ? Math.max(remaining, RELEASE_WAIT_MS) : remaining,
+        pollIntervalMs: 100,
+        ...(signal ? { signal } : {}),
+    });
+    async function submit() {
+        let link;
+        for (;;) {
+            link = await channel.link(stop, link);
+            let result;
+            try {
+                result = await Promise.race([
+                    link.request("session.send", { sessionId, clientEventId, data }),
+                    aborted(stop),
+                    // Ended while the answer was outstanding: the core may have accepted it.
+                    channel.closed.then(() => {
+                        throw new BackendConnectionClosedError({
+                            code: 1000,
+                            message: "The Session connection ended before the message's answer arrived",
+                        });
+                    }),
+                ]);
+            }
+            catch (error) {
+                if (isAmbiguous(error)) {
+                    // The core may have accepted it; the same clientEventId replays the receipt.
+                    ambiguous = true;
+                    if (error instanceof BackendRequestError) {
+                        // An internal error on a live connection: try the same one again shortly.
+                        await Promise.race([sleep(200), aborted(stop)]);
+                        link = undefined;
+                    }
+                    continue;
+                }
+                if (error instanceof BackendRequestError && MOVE_ON.has(error.reason ?? ""))
+                    continue;
+                throw error;
+            }
+            const interaction = result?.interaction;
+            const parsed = requireInteraction(interaction, clientEventId, undefined);
+            if (parsed.kind !== "message" || !parsed.message || parsed.message.role !== "user")
+                throw new TiDBLinkError("session.send returned a different command receipt");
+            return parsed;
+        }
+    }
+    /**
+     * Follow the Turn until it finished and the Session released it, so that
+     * the next message starts a new Turn instead of steering a finished one.
+     */
+    async function untilFinished(turnId) {
+        let finished = false;
+        let release;
+        for (;;) {
+            let event;
+            try {
+                event = await watch.next(release ?? stop);
+            }
+            catch (error) {
+                // The result exists; only the release is still outstanding.
+                if (finished)
+                    return;
+                throw error;
+            }
+            // The connection ended; the REST read below still establishes the result.
+            if (!event)
+                return;
+            if (event.type === "agent.session.idle") {
+                const released = event.data.turnId;
+                // Released without a terminal event (kept for checkpoint recovery): the REST read decides.
+                if (released === turnId || event.turnId === turnId)
+                    return;
+                continue;
+            }
+            if (event.turnId !== turnId)
+                continue;
+            const payload = event.data;
+            if (event.type === "agent.session.turn.output_text.snapshot" &&
+                typeof payload.payload?.text === "string") {
+                try {
+                    onProgress?.(payload.payload.text);
+                }
+                catch (error) {
+                    // A failing display callback does not change the Turn.
+                    channel.report(error);
+                }
+            }
+            if (payload.event === "turn_finished" && !finished) {
+                finished = true;
+                turnFinished = true;
+                // The release normally follows at once; do not hold a known result for long.
+                release = AbortSignal.any([stop, AbortSignal.timeout(RELEASE_WAIT_MS)]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=session-send.js.map

package/dist/session-send.js.map

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