@microsoft/agents-telemetry 1.5.0-beta.23.g2277c6f0ab

package/dist/cjs/src/observability/trace.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceFactory = traceFactory;
+const attempt_js_1 = require("../utils/attempt.js");
+const category_js_1 = require("./category.js");
+const constants_js_1 = require("./constants.js");
+const noop_js_1 = require("../utils/noop.js");
+/**
+ * Creates the trace helper bound to the package tracer.
+ *
+ * @remarks
+ * - Only span names declared in `SpanNames` are accepted.
+ * - Disabled span categories return a no-op context instead of creating a real span.
+ */
+function traceFactory(otel) {
+    const validSpanNames = new Set(Object.values(constants_js_1.SpanNames));
+    const tracer = otel.trace.getTracer('@microsoft/agents-telemetry');
+    const trace = function trace(target, callback) {
+        if (!target) {
+            throw new Error('Trace definition is required');
+        }
+        if (!validSpanNames.has(target.name)) {
+            throw new Error(`Unrecognized span name "${target.name}". See SpanNames constants.`);
+        }
+        if ((0, category_js_1.isSpanDisabled)(target.name)) {
+            return (0, noop_js_1.noopContext)(callback);
+        }
+        const record = createRecord(target);
+        if (!callback) {
+            // TODO: if parent/child span connections are needed, we could expose a 'child' function that internally connects them.
+            const span = tracer.startSpan(target.name);
+            const flow = start(otel, target, span, record);
+            return {
+                record: flow.record,
+                actions: flow.actions,
+                fail: flow.fail,
+                end: flow.end
+            };
+        }
+        return tracer.startActiveSpan(target.name, span => {
+            const flow = start(otel, target, span, record);
+            return (0, attempt_js_1.attempt)({
+                try: () => callback({ record: flow.record, actions: flow.actions }),
+                catch: (error) => { throw flow.fail(error); },
+                finally: flow.end
+            });
+        });
+    };
+    trace.define = definition => definition;
+    return trace;
+}
+/**
+ * Creates the mutable record stored for a trace execution.
+ *
+ * @remarks
+ * - Updates use `Object.assign`, so nested objects are replaced rather than deeply merged.
+ */
+function createRecord(target) {
+    const state = target.record ? { ...target.record } : {};
+    return {
+        set(values) {
+            // TODO: use deep-merge strategy for Object and Array
+            Object.assign(state, values);
+        },
+        get() {
+            return state;
+        }
+    };
+}
+/**
+ * Initializes a trace execution and returns the action helpers plus end/fail controls.
+ */
+function start(otel, target, span, record) {
+    var _a, _b;
+    const start = performance.now();
+    let ended = false;
+    let _error;
+    return {
+        record: record.set,
+        actions: (_b = (_a = target.actions) === null || _a === void 0 ? void 0 : _a.call(target, { span })) !== null && _b !== void 0 ? _b : {},
+        fail(error) {
+            _error = error;
+            return error;
+        },
+        end() {
+            if (ended || !otel) {
+                return;
+            }
+            ended = true;
+            if (_error === undefined) {
+                span.setStatus({ code: otel.SpanStatusCode.OK });
+            }
+            else {
+                captureError(otel, span, _error);
+            }
+            try {
+                target.end({
+                    span,
+                    record: record.get(),
+                    duration: performance.now() - start,
+                    error: _error,
+                });
+            }
+            catch (endError) {
+                captureError(otel, span, endError);
+            }
+            finally {
+                span.end();
+            }
+        }
+    };
+}
+/**
+ * Records an error on the span and sets the span status to `ERROR`.
+ *
+ * @remarks
+ * - Non-`Error` values are stringified so thrown primitives are still captured.
+ */
+function captureError(otel, span, error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+        span.recordException(error);
+    }
+    else {
+        message = String(error);
+        span.recordException({ name: String(typeof error), message });
+    }
+    span.setStatus({ code: otel.SpanStatusCode.ERROR, message });
+}
+//# sourceMappingURL=trace.js.map

package/dist/cjs/src/observability/trace.js.map

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

package/dist/cjs/src/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Logger } from './loggers/base.js';
+import { MetricNames, SpanNames } from './observability/constants.js';
+import type { Span, Meter } from '@opentelemetry/api';
+/**
+ * These type re-exports are intentional.
+ *
+ * @remarks
+ * This package is primarily a shared telemetry layer for other Agents SDK packages, so its
+ * TypeScript surface may depend on OpenTelemetry types even when runtime loading falls back
+ * to noop behavior if the optional dependencies are absent.
+ */
+export type * from '@opentelemetry/api';
+export type { Span, Meter } from '@opentelemetry/api';
+export type * from '@opentelemetry/api-logs';
+/**
+ * Runtime type for the optional OpenTelemetry API module.
+ */
+export type OTel = typeof import('@opentelemetry/api');
+/**
+ * Runtime type for the optional OpenTelemetry logs module.
+ */
+export type OTelLogs = typeof import('@opentelemetry/api-logs');
+/**
+ * Union of the supported span names exposed by the package constants.
+ */
+export type SpanName = typeof SpanNames[keyof typeof SpanNames];
+/**
+ * Mutable state container used while a trace is active.
+ *
+ * @remarks
+ * - `set()` performs a shallow merge.
+ * - `get()` returns the latest snapshot stored for the span.
+ */
+export interface TraceRecord<TRecord extends object> {
+    set(values: Partial<TRecord>): void;
+    get(): Readonly<TRecord>;
+}
+/**
+ * Context passed to traced callbacks.
+ */
+export interface TraceContext<TRecord extends object, TActions extends object> {
+    record(values: Partial<TRecord>): void;
+    actions: TActions;
+}
+/**
+ * Callback used by callback-based trace execution.
+ */
+export type TraceCallback<TRecord extends object, TActions extends object, TReturn = unknown> = (context: TraceContext<TRecord, TActions>) => TReturn;
+/**
+ * Context used to create action helpers backed by the underlying span.
+ */
+export interface TraceActionsContext {
+    span: Span;
+}
+/**
+ * Data provided to the `end` hook when a trace finishes.
+ */
+export interface TraceEndContext<TRecord extends object> {
+    span: Span;
+    record: Readonly<TRecord>;
+    duration: number;
+    error?: unknown;
+}
+/**
+ * Handle returned when a trace is created without a callback.
+ */
+export interface TraceManagedContext<TRecord extends object, TActions extends object> extends TraceContext<TRecord, TActions> {
+    end(): void;
+    fail<T extends unknown>(error: T): T;
+}
+/**
+ * Declares how a span should be created, enriched, and finalized.
+ *
+ * @remarks
+ * - `name` must come from `SpanNames`.
+ * - `record` provides the default shape for values collected during the span lifetime.
+ */
+export interface TraceDefinition<TRecord extends object = Record<string, never>, TActions extends object = Record<string, Function>> {
+    name: SpanName;
+    record: TRecord;
+    actions?(context: TraceActionsContext): TActions;
+    end(context: TraceEndContext<TRecord>): void;
+}
+/**
+ * Trace helper that supports both managed spans and callback-based spans.
+ */
+export interface TraceFunction {
+    define<TRecord extends object, TActions extends object>(definition: TraceDefinition<TRecord, TActions>): TraceDefinition<TRecord, TActions>;
+    <TRecord extends object, TActions extends object>(definition: TraceDefinition<TRecord, TActions>): TraceManagedContext<TRecord, TActions>;
+    <TRecord extends object, TActions extends object, TReturn>(definition: TraceDefinition<TRecord, TActions>, callback: TraceCallback<TRecord, TActions, TReturn>): TReturn;
+}
+/**
+ * Metric factory surface exposed by the package.
+ */
+export interface Metric {
+    histogram: Meter['createHistogram'];
+    counter: Meter['createCounter'];
+}
+/**
+ * Loader interface for the index function, which conditionally loads OpenTelemetry dependencies at runtime.
+ */
+export interface Loader {
+    otel(): OTel | Promise<OTel>;
+    logs(): OTelLogs | Promise<OTelLogs>;
+}
+/**
+ * Conditional return type for the index loader function, based on whether the loader returns Promises.
+ */
+export type LoaderReturn<TLoader extends Loader> = Extract<ReturnType<TLoader['otel']> | ReturnType<TLoader['logs']>, PromiseLike<unknown>> extends never ? Factory : Promise<Factory>;
+/**
+ * Public telemetry API exported by the package entrypoints.
+ */
+export interface Factory {
+    SpanNames: typeof SpanNames;
+    MetricNames: typeof MetricNames;
+    /**
+     * Creates a namespaced logger.
+     *
+      * @remarks
+     * - Debug output is always used.
+     * - When the OTel logs API is available, messages are mirrored to OpenTelemetry logs.
+     */
+    debug(namespace: string): Logger;
+    /**
+     * Starts spans from a `TraceDefinition`.
+     */
+    trace: TraceFunction;
+    /**
+     * Exposes histogram and counter creators from the package meter.
+     */
+    metric: Metric;
+}
+/**
+ * Options used by the shared `attempt()` helper.
+ *
+ * @remarks
+ * - Omitting catch preserves the original error.
+ * - catch is for side effects only; recovery values are not used.
+ * - Declare catch as returning never when it always rethrows.
+ * - Declare catch as returning void when it may swallow the failure.
+ */
+export interface AttemptOptions<TResult, TCatch = never> {
+    try(): TResult;
+    catch?(error: unknown): TCatch;
+    finally?(): void;
+}

package/dist/cjs/src/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/cjs/src/utils/attempt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { AttemptOptions } from '../types.js';
+/**
+ * Detects promise-like values returned by internal loaders and callbacks.
+ */
+export declare function isPromise<T>(value: T | Promise<T>): value is Promise<T>;
+type SwallowingAttemptOptions<TResult> = AttemptOptions<TResult, void>;
+type RethrowingAttemptOptions<TResult> = AttemptOptions<TResult, never>;
+/**
+ * Runs a callback and normalizes sync and async error/finally handling.
+ *
+ * @remarks
+ * - If try succeeds, its result is returned.
+ * - If try fails and catch is omitted, the original error is propagated.
+ * - If try fails and catch throws, that error is propagated.
+ * - If try fails and catch completes normally, the failure is treated as swallowed
+ *   and attempt returns or resolves to undefined.
+ * - catch is side-effect only; any value it returns is ignored.
+ * - Type narrowing is based on whether catch is omitted or its declared return type:
+ *   omitted or never means the error is rethrown, void means the error may be swallowed.
+ * - finally runs once for both sync and async paths.
+ */
+export declare function attempt<TResult>(options: RethrowingAttemptOptions<TResult>): TResult;
+export declare function attempt<TResult>(options: RethrowingAttemptOptions<Promise<TResult>>): Promise<TResult>;
+export declare function attempt<TResult>(options: SwallowingAttemptOptions<TResult>): TResult | undefined;
+export declare function attempt<TResult>(options: SwallowingAttemptOptions<Promise<TResult>>): Promise<TResult | undefined>;
+export {};

package/dist/cjs/src/utils/attempt.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPromise = isPromise;
+exports.attempt = attempt;
+/**
+ * Detects promise-like values returned by internal loaders and callbacks.
+ */
+function isPromise(value) {
+    return ((typeof value === 'object' || typeof value === 'function') &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+function attempt(options) {
+    var _a;
+    // Note: order of overloads ensures correct typing.
+    let isAsync = false;
+    try {
+        const result = options.try();
+        if (isPromise(result)) {
+            isAsync = true;
+            return result
+                .catch(error => {
+                var _a;
+                if (!options.catch) {
+                    throw error;
+                }
+                const result = (_a = options.catch) === null || _a === void 0 ? void 0 : _a.call(options, error);
+                if (isPromise(result)) {
+                    return result.then(() => undefined);
+                }
+                return undefined;
+            })
+                .finally(options.finally);
+        }
+        return result;
+    }
+    catch (error) {
+        if (!options.catch) {
+            throw error;
+        }
+        options.catch(error);
+        return undefined;
+    }
+    finally {
+        !isAsync && ((_a = options.finally) === null || _a === void 0 ? void 0 : _a.call(options));
+    }
+}
+//# sourceMappingURL=attempt.js.map

package/dist/cjs/src/utils/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../../../../src/utils/attempt.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAOH,8BAOC;AAuBD,0BAgCC;AAjED;;GAEG;AACH,SAAgB,SAAS,CAAK,KAAqB;IACjD,OAAO,CACL,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC;QAC1D,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,CACjC,CAAA;AACH,CAAC;AAuBD,SAAgB,OAAO,CAAW,OAA8C;;IAC9E,mDAAmD;IACnD,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAA;QAE5B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,GAAG,IAAI,CAAA;YACd,OAAO,MAAM;iBACV,KAAK,CAAC,KAAK,CAAC,EAAE;;gBACb,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;oBACnB,MAAM,KAAK,CAAA;gBACb,CAAC;gBACD,MAAM,MAAM,GAAG,MAAA,OAAO,CAAC,KAAK,wDAAG,KAAK,CAAC,CAAA;gBACrC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtB,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;gBACrC,CAAC;gBACD,OAAO,SAAS,CAAA;YAClB,CAAC,CAAC;iBACD,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC7B,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,KAAK,CAAA;QACb,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;YAAS,CAAC;QACT,CAAC,OAAO,KAAI,MAAA,OAAO,CAAC,OAAO,uDAAI,CAAA,CAAA;IACjC,CAAC;AACH,CAAC"}

package/dist/cjs/src/utils/noop.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { Metric, TraceCallback, TraceFunction, TraceManagedContext } from '../types.js';
+/**
+ * No-op trace implementation used when tracing is unavailable or disabled.
+ */
+export declare const noopTrace: TraceFunction;
+/**
+ * No-op metric implementation used when the OTel metrics API is unavailable.
+ */
+export declare function noopMetric(): Metric;
+/**
+ * Creates a callback/manually-managed trace context that safely does nothing.
+ */
+export declare function noopContext<TRecord extends object, TActions extends object>(): TraceManagedContext<TRecord, TActions>;
+export declare function noopContext<TRecord extends object, TActions extends object, TReturn>(callback: TraceCallback<TRecord, TActions, TReturn>): TReturn;

package/dist/cjs/src/utils/noop.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopTrace = void 0;
+exports.noopMetric = noopMetric;
+exports.noopContext = noopContext;
+const noopFn = () => { };
+/**
+ * No-op trace implementation used when tracing is unavailable or disabled.
+ */
+exports.noopTrace = function (target, callback) {
+    return noopContext(callback);
+};
+exports.noopTrace.define = definition => definition;
+/**
+ * No-op metric implementation used when the OTel metrics API is unavailable.
+ */
+function noopMetric() {
+    return {
+        histogram: () => ({ record: noopFn }),
+        counter: () => ({ add: noopFn }),
+    };
+}
+function noopContext(callback) {
+    const actions = new Proxy({}, { get: () => noopFn });
+    const context = {
+        record: noopFn,
+        actions,
+    };
+    if (callback) {
+        return callback(context);
+    }
+    const managedContext = {
+        record: context.record,
+        actions: context.actions,
+        end: noopFn,
+        fail(error) {
+            return error;
+        },
+    };
+    return managedContext;
+}
+//# sourceMappingURL=noop.js.map

package/dist/cjs/src/utils/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../../../src/utils/noop.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAkBH,gCAKC;AAOD,kCAqBC;AA/CD,MAAM,MAAM,GAAG,GAAG,EAAE,GAAE,CAAC,CAAA;AAEvB;;GAEG;AACU,QAAA,SAAS,GAAG,UAAU,MAAM,EAAE,QAAQ;IACjD,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAA;AAC9B,CAAkB,CAAA;AAElB,iBAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,UAAU,CAAA;AAE3C;;GAEG;AACH,SAAgB,UAAU;IACxB,OAAO;QACL,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACrC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;KACjC,CAAA;AACH,CAAC;AAOD,SAAgB,WAAW,CAA4D,QAAoD;IACzI,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAa,CAAA;IAChE,MAAM,OAAO,GAAoC;QAC/C,MAAM,EAAE,MAAM;QACd,OAAO;KACR,CAAA;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IAED,MAAM,cAAc,GAA2C;QAC7D,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,EAAE,MAAM;QACX,IAAI,CAAqB,KAAQ;YAC/B,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;IAED,OAAO,cAAc,CAAA;AACvB,CAAC"}

package/dist/cjs/src/utils/platform.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Indicates whether the current runtime looks like a browser with DOM access.
+ */
+export declare const isBrowser: boolean;

package/dist/cjs/src/utils/platform.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBrowser = void 0;
+/**
+ * Indicates whether the current runtime looks like a browser with DOM access.
+ */
+exports.isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+//# sourceMappingURL=platform.js.map

package/dist/cjs/src/utils/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../../../src/utils/platform.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;GAEG;AACU,QAAA,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAA"}

package/dist/cjs/src/utils/setting.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Reads a configuration setting from `localStorage` in the browser or `process.env` in Node.js.
+ *
+ * @remarks
+ * - Browser storage access failures are ignored and treated as an empty value.
+ */
+export declare function getSetting(name: string): string;

package/dist/cjs/src/utils/setting.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSetting = getSetting;
+const platform_js_1 = require("./platform.js");
+/**
+ * Reads a configuration setting from `localStorage` in the browser or `process.env` in Node.js.
+ *
+ * @remarks
+ * - Browser storage access failures are ignored and treated as an empty value.
+ */
+function getSetting(name) {
+    var _a, _b;
+    if (platform_js_1.isBrowser) {
+        try {
+            return (_a = window.localStorage.getItem(name)) !== null && _a !== void 0 ? _a : '';
+        }
+        catch {
+            // no-op
+        }
+    }
+    else {
+        return (_b = process.env[name]) !== null && _b !== void 0 ? _b : '';
+    }
+    return '';
+}
+//# sourceMappingURL=setting.js.map

package/dist/cjs/src/utils/setting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting.js","sourceRoot":"","sources":["../../../../src/utils/setting.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAUH,gCAYC;AApBD,+CAAyC;AAEzC;;;;;GAKG;AACH,SAAgB,UAAU,CAAE,IAAW;;IACrC,IAAI,uBAAS,EAAE,CAAC;QACd,IAAI,CAAC;YACH,OAAO,MAAA,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,mCAAI,EAAE,CAAA;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ;QACV,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,MAAA,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAI,EAAE,CAAA;IAChC,CAAC;IAED,OAAO,EAAE,CAAA;AACX,CAAC"}